diff --git a/.changeset/five-mice-clap.md b/.changeset/five-mice-clap.md
new file mode 100644
index 0000000..c2f4028
--- /dev/null
+++ b/.changeset/five-mice-clap.md
@@ -0,0 +1,35 @@
+---
+"@yeez-tech/meta-encryptor": patch
+---
+
+修复下载/解密卡死与静默截断问题：
+
+- **浏览器流式下载卡 99%（主因）**：`inspectSealed` 的明文大小是高估值（漏算 nt-package 封装开销），
+  之前作为 `Content-Length` 传给 StreamSaver，导致浏览器下载永远到不了声明大小。现在不再向
+  `createWriteStream` 声明 size；该值更名为 `plaintextSizeEstimate`（保留 `plaintextSize` 别名），
+  仅用于大小限制与进度估算。进度 transformer 中间值钳制在 99% 以下，流真正完成时在 `flush()`
+  补发最终 `onProgress(total, total)`。
+- **解密失败静默跳过**：`UnsealerCore` 解密结果为空/过短时原来 `continue`（不计数、不报错），导致
+  `finished` 永远为假、输出被静默截断。现在抛出 `ERR_DECRYPT_FAILED`。
+- **Node Unsealer 流终止**：不再在 `_transform` 内 `push(null)`（消除 push-after-EOF 风险）；
+  `_flush` 检测截断输入（新会话中 `totalItems>0 && !finished` → `ERR_TRUNCATED_INPUT`；续传会话宽松处理）。
+  浏览器 `Unsealer` 的 `flush()` 同样检测截断。
+- **Recoverable 流挂起**：`RecoverableReadStream` 在输入结束于任意状态时都能正确终止（含 header
+  阶段 EOF 报错、防止 `once('readable')` 叠加）；`RecoverableWriteStream._final` 在内部流已
+  finish/destroy 时不再永久等待，并补充 `_destroy`；已提交 item 数现在持久化到 context
+  （`readItemCount`），续传时正确恢复。
+- **HttpSealedFileStream 背压**：重写为 pull-based（每次 pull 拉取一个 Range 分片），所有 await
+  进入 try/catch，支持 `signal`（AbortSignal），Range 使用重定向后的 URL，分片长度校验。
+- **停滞看门狗**：`downloadUnsealed`/`streamDownloadAndDecrypt`/`blobDownloadAndDecrypt` 新增
+  不活动看门狗（默认 60s 无数据中止，`timeoutMs` 可配置，0 禁用），流式尝试挂起时能真正触发
+  Blob 降级而不是永久挂起；StreamSaver CDN 脚本加载增加 4s 超时（CDN 被墙时不再挂死）。
+- **空输入密封产物非法**：`DataProvider` 构造时未设置 magic number，空输入（0 item）密封出的
+  文件永远无法校验/解封。现在构造时即设置。
+- **死导出清理**：移除始终为 `undefined` 的 `checkSealedData`/`unsealData` 导出。
+- **新增导出**：`HeaderSize`、`BlockInfoSize`、`MaxItemSize`、`validateHeader`、`UnsealerCore`、
+  `createInactivityWatchdog`；浏览器入口另导出 `inspectSealed`、`blobDownloadAndDecrypt`、
+  `getBestWritable`、progress transformers。
+- locale JSON 转为 JS 模块（裸 Node ESM 可直接 import，修复 `gen:fixtures` 崩溃）。
+
+⚠️ 行为变更：以往"静默截断也算成功"的输入（密钥错误、数据不完整）现在会报错
+（`ERR_DECRYPT_FAILED` / `ERR_TRUNCATED_INPUT`）——这是预期行为，损坏数据不应被当作成功。
diff --git a/index.d.ts b/index.d.ts
index 19f7aac..f262d62 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1,5 +1,16 @@
 import { Transform, Readable, Writable } from 'stream';
 
+export class MetaEncryptorError extends Error {
+  code: string;
+  detail?: any;
+  readonly localizedMessage: string;
+  constructor(code: string, options?: { detail?: any; cause?: any });
+  toJSON(): { name: string; code: string; message: string; detail?: any; causeMessage?: string };
+}
+
+export function configureLocale(options?: { messages?: Record<string, string> | null }): void;
+export function detectLocale(): string;
+
 export class ToString extends Transform {
   constructor(options?: any, schema?: any);
 }
@@ -63,8 +74,24 @@ export class DataProviderClass {
 }
 
 export const DataProvider: typeof DataProviderClass;
-export const checkSealedData: any;
-export const unsealData: any;
+
+// Sealed format constants / helpers
+export const HeaderSize: number;
+export const BlockInfoSize: number;
+export const MaxItemSize: number;
+export function validateHeader(headerBytes: Uint8Array): { itemNumber: number; blockNumber: number };
+export class UnsealerCore {
+  constructor(opts: any);
+  processChunk(chunk: Uint8Array): Promise<void>;
+  readonly finished: boolean;
+  readonly headerReady: boolean;
+  readonly totalItems: number;
+  readonly readItemCount: number;
+  remaining: Uint8Array;
+  readonly processedBytes: number;
+  readonly writeBytes: number;
+}
+export function createInactivityWatchdog(ms: number, onStall: () => void): { kick(): void; stop(): void };
 
 export const YPCNtObject: any;
 export const YPCCrypto: any;
@@ -87,8 +114,6 @@ export default {
   forwardSkey,
   calculateSealedHash,
   DataProvider,
-  checkSealedData,
-  unsealData,
   YPCNtObject,
   YPCCrypto
 };
diff --git a/jest.config.node.cjs b/jest.config.node.cjs
index d6a05ea..659e7ad 100644
--- a/jest.config.node.cjs
+++ b/jest.config.node.cjs
@@ -1,6 +1,9 @@
 
 module.exports = {
   testEnvironment: 'node',
+  // Several suites seal/unseal 100–500MB files; jest's default 5s timeout
+  // fails them before they get a chance to run.
+  testTimeout: 300000,
   testMatch: [
     "**/test/*.spec.js"
   ],
diff --git a/package.json b/package.json
index 54422d9..7652ac5 100644
--- a/package.json
+++ b/package.json
@@ -1,12 +1,13 @@
 {
     "name": "@yeez-tech/meta-encryptor",
-    "version": "5.0.4",
+    "version": "5.0.5",
     "description": "Data Seal/Unseal for Fidelius",
     "main": "build/commonjs/index.node.cjs",
     "module": "build/es/index.node.js",
     "types": "index.d.ts",
     "exports": {
         ".": {
+            "types": "./index.d.ts",
             "browser": {
                 "import": "./build/es/index.browser.js"
             },
diff --git a/src/browser/HttpSealedFileStream.js b/src/browser/HttpSealedFileStream.js
index d7a6b91..8147fab 100644
--- a/src/browser/HttpSealedFileStream.js
+++ b/src/browser/HttpSealedFileStream.js
@@ -3,6 +3,10 @@
  * and streams its raw content (header + data, skipping block-info bytes).
  *
  * Analogous to Node's SealedFileStream but works over HTTP with Range requests.
+ * Pull-based: one Range request per pull(), so downstream backpressure limits
+ * how much data is buffered (the old implementation fetched the whole file
+ * inside start(), buffering it unboundedly when the consumer was slow or
+ * never ready).
  *
  * Usage:
  *   const stream = new HttpSealedFileStream('https://example.com/file.sealed');
@@ -23,94 +27,97 @@ export class HttpSealedFileStream extends ReadableStream {
    * @param {object} [options]
    * @param {number} [options.chunkSize] - bytes per Range request (default 1 MB)
    * @param {Function} [options.fetch] - fetch impl (defaults to globalThis.fetch)
+   * @param {AbortSignal} [options.signal] - aborts in-flight requests
    */
-  constructor(url, { chunkSize = DEFAULT_CHUNK, fetch: fetchFn } = {}) {
+  constructor(url, { chunkSize = DEFAULT_CHUNK, fetch: fetchFn, signal } = {}) {
     const _fetch = fetchFn || fetch.bind(globalThis);
     const state = {
       url,
+      fetchUrl: url,
       totalSize: 0,
       blockNumber: 0,
       contentSize: 0,
+      pos: 0,
     };
 
     const CHUNK = chunkSize;
 
     super({
       start: async (controller) => {
-        let headResp;
         try {
-          headResp = await _fetch(url, { method: 'HEAD' });
-        } catch (e) {
-          controller.error(new MetaEncryptorError('ERR_HEAD_REQUEST_FAILED', { detail: { status: e.message }, cause: e }));
-          return;
-        }
-        if (!headResp.ok) {
-          controller.error(new MetaEncryptorError('ERR_HEAD_REQUEST_FAILED', { detail: { status: headResp.status } }));
-          return;
-        }
-        const totalSize = parseInt(headResp.headers.get('Content-Length') || '0', 10);
-        if (totalSize < HeaderSize) {
-          controller.error(new MetaEncryptorError('ERR_FILE_TOO_SMALL'));
-          return;
-        }
-        state.totalSize = totalSize;
-        const fetchUrl = resolvedFetchUrl(headResp, url);
+          let headResp;
+          try {
+            headResp = await _fetch(url, { method: 'HEAD', signal });
+          } catch (e) {
+            throw new MetaEncryptorError('ERR_HEAD_REQUEST_FAILED', { detail: { status: e.message }, cause: e });
+          }
+          if (!headResp.ok) {
+            throw new MetaEncryptorError('ERR_HEAD_REQUEST_FAILED', { detail: { status: headResp.status } });
+          }
+          const totalSize = parseInt(headResp.headers.get('Content-Length') || '0', 10);
+          if (totalSize < HeaderSize) {
+            throw new MetaEncryptorError('ERR_FILE_TOO_SMALL');
+          }
+          state.totalSize = totalSize;
+          state.fetchUrl = resolvedFetchUrl(headResp, url);
 
-        const tailStart = totalSize - HeaderSize;
-        let tailResp;
-        try {
-          const result = await fetchRange(fetchUrl, { start: tailStart, end: totalSize - 1, fetch: _fetch });
-          tailResp = result.response;
-        } catch (e) {
-          controller.error(e);
-          return;
-        }
-        const headerBuf = new Uint8Array(await tailResp.arrayBuffer());
-        if (headerBuf.length !== HeaderSize) {
-          controller.error(new MetaEncryptorError('ERR_HEADER_INCOMPLETE', { detail: { expected: HeaderSize, actual: headerBuf.length } }));
-          return;
-        }
+          const tailStart = totalSize - HeaderSize;
+          const { response: tailResp } = await fetchRange(state.fetchUrl, {
+            start: tailStart, end: totalSize - 1, fetch: _fetch, signal
+          });
+          const headerBuf = new Uint8Array(await tailResp.arrayBuffer());
+          if (headerBuf.length !== HeaderSize) {
+            throw new MetaEncryptorError('ERR_HEADER_INCOMPLETE', {
+              detail: { expected: HeaderSize, actual: headerBuf.length }
+            });
+          }
 
-        const dv = new DataView(headerBuf.buffer, headerBuf.byteOffset, headerBuf.byteLength);
-        const lo = dv.getUint32(16, true);
-        const hi = dv.getUint32(20, true);
-        state.blockNumber = hi * 0x100000000 + lo;
+          const { blockNumber } = validateHeader(headerBuf);
+          state.blockNumber = blockNumber;
 
-        controller.enqueue(headerBuf);
+          state.contentSize = totalSize - HeaderSize - BlockInfoSize * state.blockNumber;
+          if (state.contentSize <= 0) {
+            throw new MetaEncryptorError('ERR_EMPTY_CONTENT');
+          }
 
-        state.contentSize = totalSize - HeaderSize - BlockInfoSize * state.blockNumber;
-        if (state.contentSize <= 0) {
-          controller.error(new MetaEncryptorError('ERR_EMPTY_CONTENT'));
-          return;
+          controller.enqueue(headerBuf);
+        } catch (e) {
+          controller.error(e);
         }
+      },
 
-        let pos = 0;
-        while (pos < state.contentSize) {
-          const chunkEnd = Math.min(pos + CHUNK, state.contentSize);
-          let resp;
-          try {
-            const result = await fetchRange(url, { start: pos, end: chunkEnd - 1, fetch: _fetch });
-            resp = result.response;
-          } catch (e) {
-            controller.error(e);
+      pull: async (controller) => {
+        try {
+          if (state.pos >= state.contentSize) {
+            controller.close();
             return;
           }
+          const chunkEnd = Math.min(state.pos + CHUNK, state.contentSize);
+          const { response: resp } = await fetchRange(state.fetchUrl, {
+            start: state.pos, end: chunkEnd - 1, fetch: _fetch, signal
+          });
           const buf = new Uint8Array(await resp.arrayBuffer());
-          if (buf.length > 0) {
-            controller.enqueue(buf);
+          const expected = chunkEnd - state.pos;
+          if (buf.length !== expected) {
+            throw new MetaEncryptorError('ERR_UNEXPECTED_EOF', {
+              detail: { expected, actual: buf.length, pos: state.pos }
+            });
           }
-          pos = chunkEnd;
+          controller.enqueue(buf);
+          state.pos = chunkEnd;
+        } catch (e) {
+          controller.error(e);
         }
-
-        controller.close();
       }
     });
 
-    // expose state via public getters
-    this.url = state.url || url;
-    this.totalSize = state.totalSize;
-    this.blockNumber = state.blockNumber;
-    this.contentSize = state.contentSize;
+    // expose live state (start() is async, so plain copies would stay 0)
+    this.url = url;
+    Object.defineProperties(this, {
+      totalSize: { get: () => state.totalSize },
+      blockNumber: { get: () => state.blockNumber },
+      contentSize: { get: () => state.contentSize },
+    });
   }
 }
 
diff --git a/src/browser/Unsealer.js b/src/browser/Unsealer.js
index 5628058..85a99f4 100644
--- a/src/browser/Unsealer.js
+++ b/src/browser/Unsealer.js
@@ -10,6 +10,7 @@
 
 import { UnsealerCore } from '../common/unsealer_core.js';
 import { BrowserCrypto } from './ypccrypto.browser.js';
+import { MetaEncryptorError } from '../common/errors.js';
 
 export class Unsealer extends TransformStream {
   /** @type {UnsealerCore} */
@@ -25,6 +26,20 @@ export class Unsealer extends TransformStream {
       transform: async (chunk, controller) => {
         core.onPlain = (plain) => controller.enqueue(plain);
         await core.processChunk(chunk);
+      },
+      flush: async () => {
+        // Upstream closed: if not every declared item was decrypted the sealed
+        // input was truncated — fail instead of finishing with shorter output.
+        // headerReady with totalItems === 0 is a legitimately empty stream.
+        if (!core.headerReady || (core.totalItems > 0 && !core.finished)) {
+          throw new MetaEncryptorError('ERR_TRUNCATED_INPUT', {
+            detail: {
+              headerReady: core.headerReady,
+              readItemCount: core.readItemCount,
+              totalItems: core.totalItems,
+            }
+          });
+        }
       }
     });
 
diff --git a/src/browser/blob_download.js b/src/browser/blob_download.js
index a6b1d6d..440b06c 100644
--- a/src/browser/blob_download.js
+++ b/src/browser/blob_download.js
@@ -1,27 +1,46 @@
 import { Unsealer } from './Unsealer.js'
 import { HttpSealedFileStream } from './HttpSealedFileStream.js'
+import { MetaEncryptorError } from '../common/errors.js';
 import { createProgressTransformer, createDownloadReadyTransformer } from '../common/progress.js';
+import { createInactivityWatchdog } from '../common/watchdog.js';
+import { DEFAULT_STALL_MS } from './stream_download.js';
 
 /**
  * @param {string} url
  * @param {string} privateKeyHex
  * @param {string} filename
- * @param {{ log?: Function, onProgress?: Function, fetch?: Function, size?: number, onDownloadReady?: Function }} [opts]
+ * @param {{ log?: Function, onProgress?: Function, fetch?: Function, size?: number, onDownloadReady?: Function, timeoutMs?: number }} [opts]
  */
-export async function blobDownloadAndDecrypt(url, privateKeyHex, filename, { log, onProgress, fetch: _fetch, size, onDownloadReady } = {}) {
+export async function blobDownloadAndDecrypt(url, privateKeyHex, filename, { log, onProgress, fetch: _fetch, size, onDownloadReady, timeoutMs } = {}) {
   log = log || (() => {})
+
+  const stallMs = timeoutMs === undefined ? DEFAULT_STALL_MS : timeoutMs;
+  const abort = new AbortController();
+  const watchdog = createInactivityWatchdog(stallMs, () => {
+    log(`Blob download stalled: no data for ${stallMs}ms, aborting`);
+    abort.abort(new MetaEncryptorError('ERR_STREAM_STALLED', { detail: { timeoutMs: stallMs } }));
+  });
+
   try {
     const chunks = []
 
-    const stream = new HttpSealedFileStream(url, { fetch: _fetch })
+    const stream = new HttpSealedFileStream(url, { fetch: _fetch, signal: abort.signal })
     const unsealer = new Unsealer({
       privateKeyHex: privateKeyHex.trim(),
       progressHandler: (total, processed, readBytes, writeBytes) => {
         if (onProgress) onProgress(total, processed, readBytes, writeBytes)
       }
     })
+    const watchdogTap = new TransformStream({
+      transform(chunk, controller) {
+        watchdog.kick();
+        controller.enqueue(chunk);
+      }
+    })
 
+    watchdog.kick();
     await stream
+      .pipeThrough(watchdogTap)
       .pipeThrough(createDownloadReadyTransformer(onDownloadReady))
       .pipeThrough(unsealer)
       .pipeThrough(createProgressTransformer(size, onProgress))
@@ -29,7 +48,7 @@ export async function blobDownloadAndDecrypt(url, privateKeyHex, filename, { log
         write(plain) {
           chunks.push(new Uint8Array(plain))
         }
-      }))
+      }), { signal: abort.signal })
 
     const blob = new Blob(chunks, { type: 'application/octet-stream' })
     const urlObj = URL.createObjectURL(blob)
@@ -43,7 +62,10 @@ export async function blobDownloadAndDecrypt(url, privateKeyHex, filename, { log
     log('Download complete (client-side Blob decrypt)');
     return { ok: true }
   } catch (e) {
-    log('Blob download failed: ' + e.message);
-    throw e
+    const err = (abort.signal.aborted && abort.signal.reason instanceof Error) ? abort.signal.reason : e;
+    log('Blob download failed: ' + err.message);
+    throw err
+  } finally {
+    watchdog.stop();
   }
-}
\ No newline at end of file
+}
diff --git a/src/browser/downloadUnsealed.js b/src/browser/downloadUnsealed.js
index 9352a89..68e574f 100644
--- a/src/browser/downloadUnsealed.js
+++ b/src/browser/downloadUnsealed.js
@@ -22,7 +22,7 @@ function makeLogger(onLog) {
   };
 }
 
-async function inspectSealed(url, log) {
+export async function inspectSealed(url, log) {
   log('HEAD ' + url);
   let headResp;
   try {
@@ -69,10 +69,22 @@ async function inspectSealed(url, log) {
   const sealedContentSize = totalSize - HeaderSize - blockNumber * BlockInfoSize;
   if (sealedContentSize <= 0) throw new MetaEncryptorError('ERR_EMPTY_CONTENT');
 
-  // per-item overhead: 8 (len prefix) + 12 (IV) + 64 (public key) + 16 (GCM tag) = 100
-  const plaintextSize = sealedContentSize - itemNumber * 100;
-
-  return { totalSize, blockNumber, itemNumber, sealedContentSize, plaintextSize };
+  // Per-item overhead is at least 100 bytes (8 len prefix + 12 IV + 64 public
+  // key + 16 GCM tag), but each encrypted item also contains nt-package
+  // framing (12B per item + 20B per nt-input) that cannot be derived from the
+  // header alone. This value is therefore an OVER-estimate of the plaintext
+  // size — never use it as an exact Content-Length.
+  const plaintextSizeEstimate = sealedContentSize - itemNumber * 100;
+
+  return {
+    totalSize,
+    blockNumber,
+    itemNumber,
+    sealedContentSize,
+    plaintextSizeEstimate,
+    // legacy alias, kept for compatibility
+    plaintextSize: plaintextSizeEstimate,
+  };
 }
 
 
@@ -88,6 +100,7 @@ async function inspectSealed(url, log) {
  * @param {Function} [options.onDownloadReady] - HTTP 流首个数据块进入管道时触发（可关蒙层）
  * @param {Function} [options.onSuccess]
  * @param {Function} [options.onError]
+ * @param {number} [options.timeoutMs] - inactivity watchdog (ms); 0 disables
  * @returns {Promise<void>}
  */
 export async function downloadUnsealed({
@@ -98,7 +111,8 @@ export async function downloadUnsealed({
   onProgress,
   onDownloadReady,
   onSuccess,
-  onError
+  onError,
+  timeoutMs
 }) {
   const log = makeLogger(onLog);
   const key = privateKey.trim()
@@ -113,7 +127,7 @@ export async function downloadUnsealed({
     log('Checking file url=' + url + ' filename=' + filename);
     const meta = await inspectSealed(url, log);
     log('inspect file succ');
-    log(`Plaintext size=${meta.plaintextSize} bytes, sealed=${meta.sealedContentSize} bytes, totalSize=${meta.totalSize}`);
+    log(`Plaintext size(est)=${meta.plaintextSizeEstimate} bytes, sealed=${meta.sealedContentSize} bytes, totalSize=${meta.totalSize}`);
 
     const mobile = isMobile()
     const limit = mobile ? MOBILE_LIMIT : DESKTOP_LIMIT
@@ -121,9 +135,9 @@ export async function downloadUnsealed({
     const ua = typeof navigator !== 'undefined' ? navigator.userAgent : 'n/a';
     log(`Detected ${mode} (ua=${ua}), limit ${(limit / 1024 / 1024).toFixed(0)} MB`);
 
-    if (meta.plaintextSize > limit) {
+    if (meta.plaintextSizeEstimate > limit) {
       throw new MetaEncryptorError('ERR_FILE_TOO_LARGE', {
-        detail: { size: (meta.plaintextSize / 1024 / 1024).toFixed(0), mode, limit: (limit / 1024 / 1024).toFixed(0) }
+        detail: { size: (meta.plaintextSizeEstimate / 1024 / 1024).toFixed(0), mode, limit: (limit / 1024 / 1024).toFixed(0) }
       })
     }
 
@@ -133,8 +147,9 @@ export async function downloadUnsealed({
         await streamDownloadAndDecrypt(url, key, filename, {
           log,
           onProgress,
-          size: meta.plaintextSize,
+          size: meta.plaintextSizeEstimate,
           onDownloadReady,
+          timeoutMs,
         })
         if (onSuccess) onSuccess({ filename })
         return
@@ -144,7 +159,13 @@ export async function downloadUnsealed({
     }
 
     log('Using Blob download...')
-    await blobDownloadAndDecrypt(url, key, filename, { log, onProgress, onDownloadReady })
+    await blobDownloadAndDecrypt(url, key, filename, {
+      log,
+      onProgress,
+      size: meta.plaintextSizeEstimate,
+      onDownloadReady,
+      timeoutMs,
+    })
     if (onSuccess) onSuccess({ filename })
   } catch (error) {
     log('Download failed: ' + error.message)
diff --git a/src/browser/stream_download.js b/src/browser/stream_download.js
index 94eb67c..995865f 100644
--- a/src/browser/stream_download.js
+++ b/src/browser/stream_download.js
@@ -2,6 +2,11 @@ import { Unsealer } from './Unsealer.js'
 import { HttpSealedFileStream } from './HttpSealedFileStream.js'
 import { MetaEncryptorError } from '../common/errors.js';
 import { createProgressTransformer, createDownloadReadyTransformer } from '../common/progress.js';
+import { createInactivityWatchdog } from '../common/watchdog.js';
+
+export const DEFAULT_STALL_MS = 60 * 1000;
+
+const STREAMSAVER_LOAD_TIMEOUT_MS = 4000;
 
 async function ensureStreamSaver(log) {
   if (typeof window === 'undefined') return null;
@@ -9,11 +14,18 @@ async function ensureStreamSaver(log) {
 
   try {
     log?.('Loading StreamSaver...');
+    // The CDN may be unreachable (blocked networks) and the <script> then
+    // neither loads nor errors — without a timeout the whole download hangs
+    // here instead of falling back to FSA/Blob.
     await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('StreamSaver load timeout')),
+        STREAMSAVER_LOAD_TIMEOUT_MS
+      );
       const s = document.createElement('script');
       s.src = 'https://cdn.jsdelivr.net/npm/streamsaver@2.0.3/StreamSaver.min.js';
-      s.onload = resolve;
-      s.onerror = reject;
+      s.onload = () => { clearTimeout(timer); resolve(); };
+      s.onerror = (e) => { clearTimeout(timer); reject(e); };
       document.head.appendChild(s);
     });
     if (window.streamSaver?.createWriteStream) {
@@ -26,15 +38,16 @@ async function ensureStreamSaver(log) {
   return null;
 }
 
-export async function getBestWritable(filename, { log, size } = {}) {
- 
-
+export async function getBestWritable(filename, { log } = {}) {
   const ss = await ensureStreamSaver(log);
   if (ss) {
     log?.('Using StreamSaver...');
-    return ss.createWriteStream(filename, size !== undefined ? { size } : undefined);
+    // Never declare a size: the exact plaintext size cannot be computed from
+    // the sealed header (only over-estimated). Declaring a too-large
+    // Content-Length pins the browser download just below 100% forever.
+    return ss.createWriteStream(filename);
   }
-   
+
   if (typeof window !== 'undefined' && window.showSaveFilePicker) {
     try {
       log?.('Using File System Access API...');
@@ -45,36 +58,55 @@ export async function getBestWritable(filename, { log, size } = {}) {
       log?.(`File System Access API unavailable: ${e.message}`);
     }
   }
-  
 
   return null;
 }
 
-export async function streamDownloadAndDecrypt(url, privateKeyHex, filename, { log, onProgress, writable, size, fetch: _fetch, onDownloadReady } = {}) {
+export async function streamDownloadAndDecrypt(url, privateKeyHex, filename, { log, onProgress, writable, size, fetch: _fetch, onDownloadReady, timeoutMs } = {}) {
   log = log || (() => {})
+
+  const stallMs = timeoutMs === undefined ? DEFAULT_STALL_MS : timeoutMs;
+  const abort = new AbortController();
+  const watchdog = createInactivityWatchdog(stallMs, () => {
+    log(`Stream stalled: no data for ${stallMs}ms, aborting`);
+    abort.abort(new MetaEncryptorError('ERR_STREAM_STALLED', { detail: { timeoutMs: stallMs } }));
+  });
+
   try {
-    const out = writable || await getBestWritable(filename, { log, size })
+    const out = writable || await getBestWritable(filename, { log })
     if (!out) throw new MetaEncryptorError('ERR_NO_STREAM_WRITABLE');
     log('Stream download starting...');
 
-    const stream = new HttpSealedFileStream(url, { fetch: _fetch })
+    const stream = new HttpSealedFileStream(url, { fetch: _fetch, signal: abort.signal })
     const unsealer = new Unsealer({
       privateKeyHex: privateKeyHex.trim(),
       progressHandler: (total, processed, readBytes, writeBytes) => {
         if (onProgress) onProgress(total, processed, readBytes, writeBytes)
       }
     })
+    const watchdogTap = new TransformStream({
+      transform(chunk, controller) {
+        watchdog.kick();
+        controller.enqueue(chunk);
+      }
+    })
 
+    watchdog.kick();
     await stream
+      .pipeThrough(watchdogTap)
       .pipeThrough(createDownloadReadyTransformer(onDownloadReady))
       .pipeThrough(unsealer)
       .pipeThrough(createProgressTransformer(size, onProgress))
-      .pipeTo(out)
+      .pipeTo(out, { signal: abort.signal })
 
     log('Download complete');
     return { ok: true }
   } catch (e) {
-    log('Stream download failed: ' + e.message);
-    throw e
+    // surface the stall reason instead of a generic AbortError
+    const err = (abort.signal.aborted && abort.signal.reason instanceof Error) ? abort.signal.reason : e;
+    log('Stream download failed: ' + err.message);
+    throw err
+  } finally {
+    watchdog.stop();
   }
 }
diff --git a/src/common/locale.js b/src/common/locale.js
index 0e6f960..afd80d3 100644
--- a/src/common/locale.js
+++ b/src/common/locale.js
@@ -1,5 +1,5 @@
-import en from '../locales/en.json';
-import zhCN from '../locales/zh-CN.json';
+import en from '../locales/en.js';
+import zhCN from '../locales/zh-CN.js';
 
 const _bundled = { en, 'zh-CN': zhCN };
 let _messages = null;
diff --git a/src/common/progress.js b/src/common/progress.js
index f501738..d2ca848 100644
--- a/src/common/progress.js
+++ b/src/common/progress.js
@@ -2,19 +2,35 @@
  * Create a TransformStream that reports plaintext download progress.
  * Accumulates bytes from each chunk and calls onProgress.
  *
- * @param {number} plaintextSize - total plaintext size in bytes
+ * `plaintextSize` is an over-estimate (the exact plaintext size cannot be
+ * derived from the sealed header), so intermediate reports are clamped below
+ * 100% and a final onProgress(total, total) is emitted from flush() when the
+ * stream really completes.
+ *
+ * @param {number} plaintextSize - estimated total plaintext size in bytes
  * @param {Function} onProgress - progress callback (totalSize, receivedBytes)
  * @returns {TransformStream}
  */
 export function createProgressTransformer(plaintextSize, onProgress) {
   let received = 0
+  const hasSize = typeof plaintextSize === 'number' && plaintextSize > 0
   return new TransformStream({
     transform(chunk, controller) {
       received += chunk.length
       if (onProgress) {
-        onProgress(plaintextSize, received)
+        if (hasSize) {
+          onProgress(plaintextSize, Math.min(received, Math.floor(plaintextSize * 0.99)))
+        } else {
+          onProgress(plaintextSize, received)
+        }
       }
       controller.enqueue(chunk)
+    },
+    flush() {
+      if (onProgress) {
+        const total = hasSize ? plaintextSize : received
+        onProgress(total, total)
+      }
     }
   })
 }
diff --git a/src/common/unsealer_core.js b/src/common/unsealer_core.js
index aeed42f..b9a355c 100644
--- a/src/common/unsealer_core.js
+++ b/src/common/unsealer_core.js
@@ -162,6 +162,11 @@ export async function processSealedChunk(state, newChunk, { decrypt, onPlain, on
   }
 
   while (true) {
+    // Once all declared items are read, ignore any trailing bytes (block-info /
+    // tail header when the source streams the raw file) instead of parsing
+    // them as items.
+    if (state.totalItems > 0 && state.readItemCount >= state.totalItems) break;
+
     const item = tryReadItem(state.accumulated);
     if (!item) break;
 
@@ -169,7 +174,18 @@ export async function processSealedChunk(state, newChunk, { decrypt, onPlain, on
     state.processedBytes += item.consumedBytes;
 
     const decrypted = await decrypt(item.cipher);
-    if (!decrypted || decrypted.length < 12) continue;
+    if (!decrypted || decrypted.length < 12) {
+      // A failed/short decrypt means a wrong key or corrupt data. Silently
+      // skipping would leave readItemCount short of totalItems forever (the
+      // stream would hang instead of finishing) and truncate the output.
+      throw new MetaEncryptorError('ERR_DECRYPT_FAILED', {
+        detail: {
+          itemIndex: state.readItemCount,
+          cipherLength: item.cipher.length,
+          decryptedLength: decrypted ? decrypted.length : 0,
+        }
+      });
+    }
 
     let plainSize = 0;
     const batch = ntpackage2batch(decrypted);
@@ -189,7 +205,6 @@ export async function processSealedChunk(state, newChunk, { decrypt, onPlain, on
     if (onProgress) {
       onProgress(state.totalItems, state.readItemCount, state.processedBytes, state.writeBytes);
     }
-    if (state.readItemCount >= state.totalItems) break;
   }
 }
 
@@ -286,6 +301,7 @@ export class UnsealerCore {
   }
 
   get finished() { return this.#state.totalItems > 0 && this.#state.readItemCount >= this.#state.totalItems; }
+  get headerReady() { return this.#state.isHeaderReady; }
   get totalItems() { return this.#state.totalItems; }
   get readItemCount() { return this.#state.readItemCount; }
   /** @type {Uint8Array} unconsumed trailing bytes (for context persistence) */
diff --git a/src/common/watchdog.js b/src/common/watchdog.js
new file mode 100644
index 0000000..989dfca
--- /dev/null
+++ b/src/common/watchdog.js
@@ -0,0 +1,27 @@
+/**
+ * Inactivity watchdog: fires onStall once if kick() is not called again within
+ * `ms` milliseconds. Used to abort transfer pipelines that would otherwise
+ * hang forever waiting for an event that never comes.
+ *
+ * A ms of 0/null disables the watchdog (kick becomes a no-op).
+ */
+export function createInactivityWatchdog(ms, onStall) {
+  let timer = null;
+  let stopped = false;
+
+  const kick = () => {
+    if (stopped || !ms || ms <= 0) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      if (!stopped) onStall();
+    }, ms);
+  };
+
+  const stop = () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+
+  return { kick, stop };
+}
diff --git a/src/index.browser.js b/src/index.browser.js
index 9b930e4..2135e5a 100644
--- a/src/index.browser.js
+++ b/src/index.browser.js
@@ -12,7 +12,15 @@ export { Unsealer } from "./browser/Unsealer.js";
 
 export { HttpSealedFileStream } from "./browser/HttpSealedFileStream.js";
 
-export { downloadUnsealed } from "./browser/downloadUnsealed.js";
+export { downloadUnsealed, inspectSealed } from "./browser/downloadUnsealed.js";
 
-export { streamDownloadAndDecrypt } from "./browser/stream_download.js";
+export { streamDownloadAndDecrypt, getBestWritable } from "./browser/stream_download.js";
+
+export { blobDownloadAndDecrypt } from "./browser/blob_download.js";
+
+export { createProgressTransformer, createDownloadReadyTransformer } from "./common/progress.js";
+
+export { HeaderSize, BlockInfoSize, MaxItemSize } from "./common/limits.js";
+export { validateHeader, UnsealerCore } from "./common/unsealer_core.js";
+export { createInactivityWatchdog } from "./common/watchdog.js";
 
diff --git a/src/index.node.js b/src/index.node.js
index 62b468e..a5fb4cc 100644
--- a/src/index.node.js
+++ b/src/index.node.js
@@ -23,7 +23,13 @@ export {
   calculateSealedHash
 } from "./node/SealedFileUtil.js";
 
-export const { DataProvider, checkSealedData, unsealData } = Provider;
+// NOTE: checkSealedData/unsealData were removed — they never existed on the
+// DataProvider default export and were always `undefined`.
+export const { DataProvider } = Provider;
+
+export { HeaderSize, BlockInfoSize, MaxItemSize } from "./common/limits.js";
+export { validateHeader, UnsealerCore } from "./common/unsealer_core.js";
+export { createInactivityWatchdog } from "./common/watchdog.js";
 
 export const YPCNtObject = YPCNt_Object();
 export const YPCCrypto = nodeYPCCrypto();
diff --git a/src/locales/en.js b/src/locales/en.js
new file mode 100644
index 0000000..8a09715
--- /dev/null
+++ b/src/locales/en.js
@@ -0,0 +1,56 @@
+// Auto-converted from en.json so plain Node ESM can import it
+// (raw .json imports require import attributes in Node >= 17.5).
+export default {
+  "ERR_INVALID_MAGIC": "Invalid magic number",
+  "ERR_INVALID_MAGIC_LENGTH": "Invalid magic number: length mismatch",
+  "ERR_UNSUPPORTED_VERSION": "Unsupported version: {version}",
+  "ERR_INVALID_HEADER": "Invalid header",
+  "ERR_INVALID_HEADER_HASH": "header.data_hash is invalid",
+  "ERR_FILE_TOO_SMALL": "File too small to be a valid sealed file",
+  "ERR_FILE_TOO_SMALL_HEADER": "Cannot read header. File too small",
+  "ERR_INVALID_FILE_SIZE": "Invalid file size",
+  "ERR_UNEXPECTED_EOF": "Reached end of file unexpectedly",
+  "ERR_HEAD_REQUEST_FAILED": "HEAD request failed: HTTP {status}",
+  "ERR_FILE_NOT_SEALED": "File too small, not a valid sealed file: content-length={totalSize}",
+  "ERR_CANNOT_READ_TAIL": "Cannot read file tail: HTTP {status}, range={rangeHeader}",
+  "ERR_HEADER_INCOMPLETE": "Header incomplete: expected {expected} bytes, got {actual}, totalSize={totalSize}, range={rangeHeader}, status={status}",
+  "ERR_EMPTY_CONTENT": "Invalid sealed file: content size is 0",
+  "ERR_MISSING_PARAMS": "URL, private key, and filename are required (url={url}, key={key}, filename={filename})",
+  "ERR_FILE_TOO_LARGE": "File too large ({size} MB), exceeds {mode} limit ({limit} MB)",
+  "ERR_NO_STREAM_WRITABLE": "No streaming writable available",
+  "ERR_STREAM_DOWNLOAD_FAILED": "Stream download failed: {message}",
+  "ERR_INVALID_PRIVATE_KEY": "Invalid private key",
+  "ERR_VERSION_MISMATCH": "Only version {expected} is supported, got {actual}",
+  "ERR_MUST_USE_NEW": "{name} must be called with new keyword",
+  "ERR_PIPELINE_CONTEXT_SAVE": "saveContext should be implemented",
+  "ERR_PIPELINE_CONTEXT_LOAD": "loadContext should be implemented",
+  "ERR_PIPELINE_CONTEXT_INVALID": "PipelineContextInFile::loadContext invalid length",
+  "ERR_DOWNLOAD_FAILED": "Download failed: {message}",
+  "ERR_DECRYPT_FAILED": "Failed to decrypt item {itemIndex}: wrong key or corrupt data (cipher {cipherLength} bytes, decrypted {decryptedLength} bytes)",
+  "ERR_TRUNCATED_INPUT": "Sealed input ended prematurely: read {readItemCount} of {totalItems} items (headerReady={headerReady})",
+  "ERR_STREAM_STALLED": "Transfer stalled: no data received for {timeoutMs} ms",
+  "ERR_RANGE_NOT_HONORED": "Range request was not honored by the server (got {actualStatus} instead of {expectedStatus}). This usually indicates a network proxy or security software is intercepting HTTP requests. Please try using the desktop client instead, or contact your network administrator.",
+  "ERR_TOO_MANY_REDIRECTS": "Too many redirects (max {redirectCount})",
+  "LOG_HEAD": "HEAD {url}",
+  "LOG_HEAD_STATUS": "HEAD status={status} content-length={cl} accept-ranges={ar}",
+  "LOG_RANGE": "Range {range} (tail {tailSize} bytes of {total})",
+  "LOG_HEADER_OK": "header ok: blockNumber={block}",
+  "LOG_INSPECT_OK": "inspect file succ",
+  "LOG_CHECKING_FILE": "Checking file url={url} filename={filename}",
+  "LOG_CONTENT_SIZE": "Plain size(est)={size} bytes, totalSize={total}",
+  "LOG_DEVICE_DETECTED": "Detected {mode} (ua={ua}), limit {limit} MB",
+  "LOG_TRYING_STREAM": "Trying stream download...",
+  "LOG_STREAM_FALLBACK": "Stream failed: {message}, falling back to Blob",
+  "LOG_USING_BLOB": "Using Blob download...",
+  "LOG_DOWNLOAD_FAILED": "Download failed: {message}",
+  "LOG_STREAM_START": "Stream download starting...",
+  "LOG_DOWNLOAD_COMPLETE": "Download complete",
+  "LOG_STREAM_FAILED": "Stream download failed: {message}",
+  "LOG_BLOB_COMPLETE": "Download complete (client-side Blob decrypt)",
+  "LOG_BLOB_FAILED": "Blob download failed: {message}",
+  "LOG_STREAMSAVER_LOADING": "Loading StreamSaver...",
+  "LOG_STREAMSAVER_FAIL": "StreamSaver load failed",
+  "LOG_USING_FSA": "Using File System Access API...",
+  "LOG_FSA_UNAVAILABLE": "File System Access API unavailable: {message}",
+  "LOG_USING_STREAMSAVER": "Using StreamSaver..."
+};
diff --git a/src/locales/en.json b/src/locales/en.json
index 30550db..ca4d4a0 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -24,6 +24,9 @@
   "ERR_PIPELINE_CONTEXT_LOAD": "loadContext should be implemented",
   "ERR_PIPELINE_CONTEXT_INVALID": "PipelineContextInFile::loadContext invalid length",
   "ERR_DOWNLOAD_FAILED": "Download failed: {message}",
+  "ERR_DECRYPT_FAILED": "Failed to decrypt item {itemIndex}: wrong key or corrupt data (cipher {cipherLength} bytes, decrypted {decryptedLength} bytes)",
+  "ERR_TRUNCATED_INPUT": "Sealed input ended prematurely: read {readItemCount} of {totalItems} items (headerReady={headerReady})",
+  "ERR_STREAM_STALLED": "Transfer stalled: no data received for {timeoutMs} ms",
   "ERR_RANGE_NOT_HONORED": "Range request was not honored by the server (got {actualStatus} instead of {expectedStatus}). This usually indicates a network proxy or security software is intercepting HTTP requests. Please try using the desktop client instead, or contact your network administrator.",
   "ERR_TOO_MANY_REDIRECTS": "Too many redirects (max {redirectCount})",
   "LOG_HEAD": "HEAD {url}",
diff --git a/src/locales/zh-CN.js b/src/locales/zh-CN.js
new file mode 100644
index 0000000..0220a22
--- /dev/null
+++ b/src/locales/zh-CN.js
@@ -0,0 +1,56 @@
+// Auto-converted from zh-CN.json so plain Node ESM can import it
+// (raw .json imports require import attributes in Node >= 17.5).
+export default {
+  "ERR_INVALID_MAGIC": "无效的魔数",
+  "ERR_INVALID_MAGIC_LENGTH": "无效的魔数：长度不匹配",
+  "ERR_UNSUPPORTED_VERSION": "不支持的版本：{version}",
+  "ERR_INVALID_HEADER": "无效的文件头",
+  "ERR_INVALID_HEADER_HASH": "header.data_hash 无效",
+  "ERR_FILE_TOO_SMALL": "文件太小，不是有效的封装文件",
+  "ERR_FILE_TOO_SMALL_HEADER": "无法读取文件头，文件太小",
+  "ERR_INVALID_FILE_SIZE": "无效的文件大小",
+  "ERR_UNEXPECTED_EOF": "意外到达文件末尾",
+  "ERR_HEAD_REQUEST_FAILED": "HEAD 请求失败：HTTP {status}",
+  "ERR_FILE_NOT_SEALED": "文件太小，不是有效的封装文件：content-length={totalSize}",
+  "ERR_CANNOT_READ_TAIL": "无法读取文件尾部：HTTP {status}",
+  "ERR_HEADER_INCOMPLETE": "文件头不完整：期望 {expected} 字节，实际 {actual}",
+  "ERR_EMPTY_CONTENT": "无效的封装文件：内容大小为0",
+  "ERR_MISSING_PARAMS": "缺少必要参数：URL、私钥和文件名",
+  "ERR_FILE_TOO_LARGE": "文件过大（{size} MB），超出{mode}限制（{limit} MB）",
+  "ERR_NO_STREAM_WRITABLE": "无可用的流式下载方式",
+  "ERR_STREAM_DOWNLOAD_FAILED": "流式下载失败：{message}",
+  "ERR_INVALID_PRIVATE_KEY": "无效的私钥",
+  "ERR_VERSION_MISMATCH": "仅支持版本 {expected}，当前版本 {actual}",
+  "ERR_MUST_USE_NEW": "{name} 必须使用 new 关键字调用",
+  "ERR_PIPELINE_CONTEXT_SAVE": "saveContext 需要被实现",
+  "ERR_PIPELINE_CONTEXT_LOAD": "loadContext 需要被实现",
+  "ERR_PIPELINE_CONTEXT_INVALID": "PipelineContextInFile::loadContext 无效的长度",
+  "ERR_DOWNLOAD_FAILED": "下载失败：{message}",
+  "ERR_DECRYPT_FAILED": "第 {itemIndex} 个数据块解密失败：密钥错误或数据损坏（密文 {cipherLength} 字节，解密结果 {decryptedLength} 字节）",
+  "ERR_TRUNCATED_INPUT": "封装数据不完整：仅读取 {readItemCount}/{totalItems} 个数据块（headerReady={headerReady}）",
+  "ERR_STREAM_STALLED": "传输停滞：{timeoutMs} 毫秒内未收到数据",
+  "ERR_RANGE_NOT_HONORED": "服务器未响应 Range 请求（返回 {actualStatus} 而非 {expectedStatus}）。这通常是因为网络环境中设置了安全代理，拦截了 HTTP 请求。请尝试使用桌面客户端下载，或联系网络管理员。",
+  "ERR_TOO_MANY_REDIRECTS": "重定向次数过多（最多 {redirectCount} 次）",
+  "LOG_HEAD": "HEAD {url}",
+  "LOG_HEAD_STATUS": "HEAD status={status} content-length={cl} accept-ranges={ar}",
+  "LOG_RANGE": "Range {range} (tail {tailSize} bytes of {total})",
+  "LOG_HEADER_OK": "header ok: blockNumber={block}",
+  "LOG_INSPECT_OK": "文件检查完成",
+  "LOG_CHECKING_FILE": "检查文件 url={url} filename={filename}",
+  "LOG_CONTENT_SIZE": "明文大小(估算)={size} 字节, totalSize={total}",
+  "LOG_DEVICE_DETECTED": "检测到 {mode} 端 (ua={ua})，大小限制 {limit} MB",
+  "LOG_TRYING_STREAM": "尝试流式下载...",
+  "LOG_STREAM_FALLBACK": "流式下载失败: {message}，回退到 Blob 下载",
+  "LOG_USING_BLOB": "使用 Blob 下载...",
+  "LOG_DOWNLOAD_FAILED": "下载失败: {message}",
+  "LOG_STREAM_START": "流式下载开始...",
+  "LOG_DOWNLOAD_COMPLETE": "下载完成",
+  "LOG_STREAM_FAILED": "流式下载失败: {message}",
+  "LOG_BLOB_COMPLETE": "下载完成 (页面端解密 Blob)",
+  "LOG_BLOB_FAILED": "Blob 下载失败: {message}",
+  "LOG_STREAMSAVER_LOADING": "正在加载 StreamSaver...",
+  "LOG_STREAMSAVER_FAIL": "StreamSaver 加载失败",
+  "LOG_USING_FSA": "使用 File System Access API 流式下载...",
+  "LOG_FSA_UNAVAILABLE": "File System Access API 不可用: {message}",
+  "LOG_USING_STREAMSAVER": "使用 StreamSaver 流式下载..."
+};
diff --git a/src/locales/zh-CN.json b/src/locales/zh-CN.json
index 136da89..a9efc03 100644
--- a/src/locales/zh-CN.json
+++ b/src/locales/zh-CN.json
@@ -24,6 +24,9 @@
   "ERR_PIPELINE_CONTEXT_LOAD": "loadContext 需要被实现",
   "ERR_PIPELINE_CONTEXT_INVALID": "PipelineContextInFile::loadContext 无效的长度",
   "ERR_DOWNLOAD_FAILED": "下载失败：{message}",
+  "ERR_DECRYPT_FAILED": "第 {itemIndex} 个数据块解密失败：密钥错误或数据损坏（密文 {cipherLength} 字节，解密结果 {decryptedLength} 字节）",
+  "ERR_TRUNCATED_INPUT": "封装数据不完整：仅读取 {readItemCount}/{totalItems} 个数据块（headerReady={headerReady}）",
+  "ERR_STREAM_STALLED": "传输停滞：{timeoutMs} 毫秒内未收到数据",
   "ERR_RANGE_NOT_HONORED": "服务器未响应 Range 请求（返回 {actualStatus} 而非 {expectedStatus}）。这通常是因为网络环境中设置了安全代理，拦截了 HTTP 请求。请尝试使用桌面客户端下载，或联系网络管理员。",
   "ERR_TOO_MANY_REDIRECTS": "重定向次数过多（最多 {redirectCount} 次）",
   "LOG_HEAD": "HEAD {url}",
diff --git a/src/node/DataProvider.js b/src/node/DataProvider.js
index 4f2e8b3..fa1a84c 100644
--- a/src/node/DataProvider.js
+++ b/src/node/DataProvider.js
@@ -30,6 +30,10 @@ const DataProvider = function(_key) {
     throw new MetaEncryptorError('ERR_MUST_USE_NEW', { detail: { name: 'DataProvider' } });
   }
   this.header = new header_t(0, 0, 0, 0);
+  // magic must be set here, not only in BlockFile.append_item — otherwise a
+  // zero-item seal (empty input) writes a header with a zero magic number,
+  // producing a sealed file that can never be validated/unsealed.
+  this.header.magic_number = MagicNum;
   this.header.version_number = 2;
   this.block_meta_info = [];
   this.sealed_data = [];
diff --git a/src/node/Recoverable.js b/src/node/Recoverable.js
index b43c38e..00493b9 100644
--- a/src/node/Recoverable.js
+++ b/src/node/Recoverable.js
@@ -2,6 +2,7 @@ import {WriteStream} from 'fs';
 import {Readable, Writable} from 'stream';
 import { SealedFileStream } from './SealedFileStream.js';
 import { HeaderSize } from '../common/limits.js';
+import { MetaEncryptorError } from '../common/errors.js';
 import fs from 'fs';
 import log from 'loglevel';
 
@@ -17,20 +18,44 @@ export class RecoverableReadStream extends Readable {
         });
         this.state = 'header';
         this.headerRead = 0;
+        this.inputEnded = false;
+        this.pushedEof = false;
+        this.waitingReadable = false;
 
         this.inputStream.on('error', (err) => {
             this.emit('error', err);
         });
         this.inputStream.on('end', () => {
-            if (this.state === 'remaining') {
-                this.push(null);
+            this.inputEnded = true;
+            if (this.state === 'header') {
+                // input ended before a full header could be read — corrupt file
+                this.emit('error', new MetaEncryptorError('ERR_UNEXPECTED_EOF'));
+            } else if (this.state === 'remaining') {
+                this._pushEof();
             }
+            // 'contextData' needs no action: once the context data is drained,
+            // _read switches to 'remaining' and sees inputEnded.
             if (this.inputStream && typeof this.inputStream.destroy === 'function') {
                 this.inputStream.destroy();
             }
         });
     }
 
+    _pushEof() {
+        if (this.pushedEof) return;
+        this.pushedEof = true;
+        this.push(null);
+    }
+
+    _waitReadable(size) {
+        if (this.waitingReadable) return;
+        this.waitingReadable = true;
+        this.inputStream.once('readable', () => {
+            this.waitingReadable = false;
+            this._read(size);
+        });
+    }
+
     _getReadStartInContext() {
         if (
             this.context.context === null ||
@@ -68,10 +93,10 @@ export class RecoverableReadStream extends Readable {
                     if (this.headerRead === HeaderSize) {
                         this.state = 'contextData';
                     }
+                } else if (this.inputEnded || this.inputStream.readableEnded) {
+                    this.emit('error', new MetaEncryptorError('ERR_UNEXPECTED_EOF'));
                 } else {
-                    this.inputStream.once('readable', () => {
-                        this._read(size);
-                    });
+                    this._waitReadable(size);
                 }
                 logger.debug("Reading header, read so far:", this.headerRead);
                 break;
@@ -110,13 +135,10 @@ export class RecoverableReadStream extends Readable {
                     
                     this.push(remainingChunk);
                 } else {
-                    if (this.inputStream.readableEnded) {
-                        //console.log("push null")
-                        this.push(null);
+                    if (this.inputEnded || this.inputStream.readableEnded) {
+                        this._pushEof();
                     } else {
-                        this.inputStream.once('readable', () => {
-                            this._read(size);
-                        });
+                        this._waitReadable(size);
                     }
                 }
                 logger.debug("Reading remaining data from file");
@@ -217,6 +239,9 @@ export class RecoverableWriteStream extends Writable {
         let remain = writtenBytes;
         const runtime = this.context.runtime;
         const blocks = runtime.pendingBlocks || [];
+        if (runtime.itemsCommitted === undefined) {
+            runtime.itemsCommitted = (this.context.context && this.context.context['readItemCount']) || 0;
+        }
 
         let hasCommittedBlock = false;
         let committedRawBytes = 0;
@@ -234,6 +259,7 @@ export class RecoverableWriteStream extends Writable {
                 runtime.rawCommitted += block.rawSize;
                 runtime.plainCommitted += block.plainSize;
                 committedRawBytes += block.rawSize;
+                runtime.itemsCommitted += 1;
                 blocks.shift();
                 hasCommittedBlock = true;
             }
@@ -257,6 +283,7 @@ export class RecoverableWriteStream extends Writable {
             }
             this.context.context['readStart'] = runtime.rawCommitted;
             this.context.context['writeStart'] = runtime.plainCommitted;
+            this.context.context['readItemCount'] = runtime.itemsCommitted;
             logger.debug("After writing, updated readStart to:", this.context.context['readStart'],
                          " writeStart to:", this.context.context['writeStart'],
                          " data length to:", this.context.context['data'] ? this.context.context['data'].length : 0);
@@ -267,7 +294,13 @@ export class RecoverableWriteStream extends Writable {
     }
 
     _final(callback) {
-        this.writeStream.on('finish', () => {
+        let settled = false;
+        const settle = (err) => {
+            if (settled) return;
+            settled = true;
+            callback(err);
+        };
+        const finalize = () => {
             const readStart = this.context.context['readStart'] || 0;
             const writeStart = this.context.context['writeStart'] || 0;
             const length = this.context.context.data ? this.context.context.data.length : 0;
@@ -276,19 +309,39 @@ export class RecoverableWriteStream extends Writable {
                 fs.truncate(this.filePath, writeStart, (truncateErr) => {
                     if (truncateErr) {
                         logger.warn("Error truncating file:", truncateErr);
-                        callback(truncateErr);
+                        settle(truncateErr);
                     } else {
                         logger.debug("File truncated successfully to length:", writeStart);
-                        callback();
+                        settle();
                     }
                 });
             } else {
 
                 logger.debug("Not truncating file as not at the end. readStart + length:", readStart + length, ", fileSize:", this.fileSize);
-                callback();
+                settle();
             }
-        });
-        this.writeStream.end();
+        };
+
+        // The inner fs stream may already be finished or destroyed (pause /
+        // cleanup paths call end()/destroy() directly). Waiting for a 'finish'
+        // that will never fire would leave _final's callback pending forever,
+        // so the outer stream would never emit 'finish'.
+        if (this.writeStream.writableFinished) {
+            finalize();
+        } else if (this.writeStream.destroyed) {
+            settle(new Error('RecoverableWriteStream: inner stream destroyed before finalize'));
+        } else {
+            this.writeStream.once('finish', finalize);
+            this.writeStream.once('error', (err) => settle(err));
+            this.writeStream.end();
+        }
         logger.debug("Finalizing write stream");
     }
+
+    _destroy(err, callback) {
+        if (this.writeStream && !this.writeStream.destroyed) {
+            this.writeStream.destroy();
+        }
+        callback(err);
+    }
 }
diff --git a/src/node/Sealer.js b/src/node/Sealer.js
index 6cb9418..60c25b9 100644
--- a/src/node/Sealer.js
+++ b/src/node/Sealer.js
@@ -5,9 +5,6 @@ import YPCNt_Object from "../common/ypcntobject.js"
 
 const {
   DataProvider,
-  unsealData,
-  checkSealedData,
-  headerAndBlockBufferFromFile
 } = Provider;
 
 const YPCNtObject = YPCNt_Object()
diff --git a/src/node/Unsealer.js b/src/node/Unsealer.js
index b26b216..486f16b 100644
--- a/src/node/Unsealer.js
+++ b/src/node/Unsealer.js
@@ -3,6 +3,7 @@ import { Transform } from "stream";
 import log from "loglevel";
 
 import { UnsealerCore } from '../common/unsealer_core.js';
+import { MetaEncryptorError } from '../common/errors.js';
 const logger = log.getLogger("meta-encryptor/Unsealer");
 
 import YPCCryptoFun from "./ypccrypto.js";
@@ -12,6 +13,9 @@ export class Unsealer extends Transform {
   /** @type {UnsealerCore} */
   #core;
 
+  /** @type {boolean} skip strict truncation check for legacy resumed contexts */
+  #lenientEof = false;
+
   constructor(options) {
     super(options);
 
@@ -61,6 +65,13 @@ export class Unsealer extends Transform {
       }
     });
 
+    // On resumed sessions the item count may be absent or incomplete (contexts
+    // persisted by older versions), making `finished` unreachable — the strict
+    // truncation check in _flush only applies to fresh (non-resumed) streams.
+    this.#lenientEof =
+      !!options &&
+      ((options.processedBytes || 0) > 0 || (options.processedItemCount || 0) > 0);
+
     // keep references for external consumers (tests may read them)
     this._keyPair = keyPair;
     this._progressHandler = progressHandler;
@@ -75,10 +86,6 @@ export class Unsealer extends Transform {
     try {
       await this.#core.processChunk(chunk);
 
-      if (this.#core.finished) {
-        this.push(null);
-      }
-
       // persist trailing unconsumed bytes for recoverable stream context
       if (this._context && this._context.context && this._context.context["status"] === "file") {
         this._context.context["data"] = this.#core.remaining;
@@ -91,5 +98,24 @@ export class Unsealer extends Transform {
     }
   }
 
-  _flush(callback) { callback(); }
+  // End the readable side only when the input ends (never push(null) inside
+  // _transform — trailing bytes arriving after an early EOF would trigger
+  // ERR_STREAM_PUSH_AFTER_EOF). If the input ended before every declared item
+  // was decrypted, the sealed input was truncated: fail instead of silently
+  // emitting a shorter plaintext.
+  _flush(callback) {
+    // headerReady with totalItems === 0 is a legitimately empty sealed stream.
+    if (!this.#core.headerReady ||
+        (!this.#lenientEof && this.#core.totalItems > 0 && !this.#core.finished)) {
+      callback(new MetaEncryptorError('ERR_TRUNCATED_INPUT', {
+        detail: {
+          headerReady: this.#core.headerReady,
+          readItemCount: this.#core.readItemCount,
+          totalItems: this.#core.totalItems,
+        }
+      }));
+      return;
+    }
+    callback();
+  }
 }
diff --git a/src/node/index.js b/src/node/index.js
index 92a06b0..29df3cb 100644
--- a/src/node/index.js
+++ b/src/node/index.js
@@ -20,7 +20,13 @@ export {
   calculateSealedHash
 } from "./SealedFileUtil.js";
 
-export const { DataProvider, checkSealedData, unsealData } = Provider;
+// NOTE: checkSealedData/unsealData were removed — they never existed on the
+// DataProvider default export and were always `undefined`.
+export const { DataProvider } = Provider;
+
+export { HeaderSize, BlockInfoSize, MaxItemSize } from "../common/limits.js";
+export { validateHeader, UnsealerCore } from "../common/unsealer_core.js";
+export { createInactivityWatchdog } from "../common/watchdog.js";
 
 export const YPCNtObject = YPCNt_Object();
 export const YPCCrypto = nodeYPCCrypto();
diff --git a/test/downloadFunctions.spec.mjs b/test/downloadFunctions.spec.mjs
index b935d21..0290b32 100644
--- a/test/downloadFunctions.spec.mjs
+++ b/test/downloadFunctions.spec.mjs
@@ -62,7 +62,7 @@ describe('blobDownloadAndDecrypt', () => {
       );
 
       expect(result).toEqual({ ok: true });
-      expect(logs.some(m => m.includes('下载完成'))).toBe(true);
+      expect(logs.some(m => m.includes('Download complete'))).toBe(true);
       expect(blobContent).not.toBeNull();
     } finally {
       URL.createObjectURL = origCOU;
@@ -80,8 +80,8 @@ describe('blobDownloadAndDecrypt', () => {
     await expect(
       blobDownloadAndDecrypt('http://mock/file', 'a'.repeat(64), 'out.bin', { log: (m) => logs.push(m) })
     ).rejects.toThrow('fetch fail');
-    expect(logs.some(m => m.includes('失败'))).toBe(true);
-  });
+    expect(logs.some(m => m.includes('failed'))).toBe(true);
+  }, 15000);
 });
 
 describe('streamDownloadAndDecrypt', () => {
@@ -98,7 +98,7 @@ describe('streamDownloadAndDecrypt', () => {
     );
 
     expect(result).toEqual({ ok: true });
-    expect(logs.some(m => m.includes('下载完成'))).toBe(true);
+    expect(logs.some(m => m.includes('Download complete'))).toBe(true);
     expect(chunks.length).toBe(1);
     expect(new TextDecoder().decode(chunks[0])).toBe('hello from mock');
   });
@@ -107,7 +107,7 @@ describe('streamDownloadAndDecrypt', () => {
     const logs = [];
     await expect(
       streamDownloadAndDecrypt('http://mock/file', 'a'.repeat(64), 'out.bin', { log: (m) => logs.push(m) })
-    ).rejects.toThrow('StreamSaver');
-    expect(logs.some(m => m.includes('失败'))).toBe(true);
-  });
+    ).rejects.toThrow('No streaming writable');
+    expect(logs.some(m => m.includes('failed'))).toBe(true);
+  }, 15000);
 });
diff --git a/test/progress.spec.mjs b/test/progress.spec.mjs
index 0eaf187..d6e5951 100644
--- a/test/progress.spec.mjs
+++ b/test/progress.spec.mjs
@@ -17,7 +17,9 @@ describe('progress transformers', () => {
 
     while (!(await reader.read()).done) {}
 
-    expect(calls).toEqual([[10, 3], [10, 5]]);
+    // plaintextSize is an over-estimate: intermediate reports are clamped
+    // below 100% and flush() emits a final (total, total) on real completion.
+    expect(calls).toEqual([[10, 3], [10, 5], [10, 10]]);
   });
 
   test('createDownloadReadyTransformer fires once on first chunk', async () => {
diff --git a/test/regression_fixes.spec.js b/test/regression_fixes.spec.js
new file mode 100644
index 0000000..88cad2b
--- /dev/null
+++ b/test/regression_fixes.spec.js
@@ -0,0 +1,280 @@
+/**
+ * Regression tests for the download-hang fixes:
+ *  - truncated sealed input must ERROR, not hang or silently truncate output
+ *  - a failed decrypt (wrong key) must ERROR, not silently skip the item
+ *  - empty plaintext must still complete
+ *  - RecoverableWriteStream._final must not hang when the inner stream is
+ *    already finished/destroyed
+ *  - readItemCount is persisted into the recoverable context on commit
+ *  - createInactivityWatchdog fires once on stall and never after stop()
+ */
+import fs from 'fs';
+import path from 'path';
+import { PassThrough } from 'stream';
+import { Sealer } from '../src/node/Sealer.js';
+import { Unsealer } from '../src/node/Unsealer.js';
+import { SealedFileStream } from '../src/node/SealedFileStream.js';
+import { RecoverableReadStream, RecoverableWriteStream } from '../src/node/Recoverable.js';
+import { PipelineContextInFile } from '../src/node/PipelineConext.js';
+import { HeaderSize, BlockInfoSize } from '../src/common/limits.js';
+import { validateHeader } from '../src/common/unsealer_core.js';
+import { createInactivityWatchdog } from '../src/common/watchdog.js';
+import { key_pair, testPath } from './helper';
+
+const other_key_pair = {
+  private_key:
+    '2b3e4b3f6cba1a54a219c521c825f1a30045d9c62571a83b56c8e6b56b3e0a12',
+};
+
+function sealBuffer(input) {
+  return new Promise((resolve, reject) => {
+    const sealer = new Sealer({ keyPair: key_pair });
+    const chunks = [];
+    sealer.on('data', (c) => chunks.push(c));
+    sealer.on('end', () => resolve(Buffer.concat(chunks)));
+    sealer.on('error', reject);
+    sealer.end(input);
+  });
+}
+
+/**
+ * Reorder a raw sealed buffer ([items][blockInfos][header]) into the layout
+ * the Unsealer consumes ([header][items]) — what SealedFileStream does.
+ */
+function unsealerInput(sealed) {
+  const header = sealed.subarray(sealed.length - HeaderSize);
+  const { blockNumber } = validateHeader(header);
+  const contentSize = sealed.length - HeaderSize - BlockInfoSize * blockNumber;
+  return { header, content: sealed.subarray(0, contentSize), contentSize };
+}
+
+function collectUnsealed(feed, unsealerOpts = {}) {
+  return new Promise((resolve, reject) => {
+    const unsealer = new Unsealer({ keyPair: key_pair, ...unsealerOpts });
+    const out = [];
+    const src = new PassThrough();
+    src.pipe(unsealer);
+    unsealer.on('data', (c) => out.push(c));
+    unsealer.on('end', () => resolve(Buffer.concat(out)));
+    unsealer.on('error', reject);
+    feed(src);
+  });
+}
+
+describe('unsealer stream termination fixes', () => {
+  test('roundtrip completes with exact bytes and emits end', async () => {
+    const plain = Buffer.from('hello dianshu download fix'.repeat(1000));
+    const sealed = await sealBuffer(plain);
+    const { header, content } = unsealerInput(sealed);
+
+    const result = await collectUnsealed((src) => {
+      src.write(header);
+      src.write(content);
+      src.end();
+    });
+    expect(Buffer.compare(result, plain)).toBe(0);
+  });
+
+  test('empty plaintext roundtrip still completes', async () => {
+    const sealed = await sealBuffer(Buffer.alloc(0));
+    const { header, content } = unsealerInput(sealed);
+
+    const result = await collectUnsealed((src) => {
+      src.write(header);
+      if (content.length > 0) src.write(content);
+      src.end();
+    });
+    expect(result.length).toBe(0);
+  });
+
+  test('truncated input errors with ERR_TRUNCATED_INPUT instead of hanging', async () => {
+    const plain = Buffer.from('x'.repeat(200 * 1024)); // several 64KB items
+    const sealed = await sealBuffer(plain);
+    const { header, content } = unsealerInput(sealed);
+
+    await expect(
+      collectUnsealed((src) => {
+        src.write(header);
+        // cut the last item short
+        src.write(content.subarray(0, content.length - 16));
+        src.end();
+      })
+    ).rejects.toMatchObject({ code: 'ERR_TRUNCATED_INPUT' });
+  }, 10000);
+
+  test('header-only input (no items) errors instead of hanging', async () => {
+    const plain = Buffer.from('y'.repeat(1024));
+    const sealed = await sealBuffer(plain);
+    const { header } = unsealerInput(sealed);
+
+    await expect(
+      collectUnsealed((src) => {
+        src.write(header);
+        src.end();
+      })
+    ).rejects.toMatchObject({ code: 'ERR_TRUNCATED_INPUT' });
+  }, 10000);
+
+  test('wrong key errors instead of silently skipping items', async () => {
+    const plain = Buffer.from('z'.repeat(4096));
+    const sealed = await sealBuffer(plain);
+    const { header, content } = unsealerInput(sealed);
+
+    await expect(
+      collectUnsealed(
+        (src) => {
+          src.write(header);
+          src.write(content);
+          src.end();
+        },
+        { keyPair: { ...key_pair, private_key: other_key_pair.private_key } }
+      )
+    ).rejects.toBeTruthy();
+  }, 10000);
+
+  test('trailing bytes after the last item are tolerated (raw file piped in full)', async () => {
+    const plain = Buffer.from('t'.repeat(4096));
+    const sealed = await sealBuffer(plain);
+    const { header } = unsealerInput(sealed);
+
+    // header first, then the WHOLE raw file body incl. blockinfo bytes
+    const result = await collectUnsealed((src) => {
+      src.write(header);
+      src.write(sealed);
+      src.end();
+    });
+    expect(Buffer.compare(result, plain)).toBe(0);
+  });
+});
+
+describe('RecoverableWriteStream finalize fixes', () => {
+  test('_final completes even when the inner stream already finished', async () => {
+    const target = testPath('rws_inner_finished.out');
+    try { fs.unlinkSync(target); } catch (e) {}
+
+    const context = { context: { status: 'file' }, runtime: null, saveContext: () => {} };
+    const ws = new RecoverableWriteStream(target, context);
+
+    await new Promise((resolve, reject) => {
+      ws.write(Buffer.from('abc'), (err) => (err ? reject(err) : resolve()));
+    });
+
+    // simulate a cleanup path ending the inner stream first
+    await new Promise((resolve) => {
+      ws.writeStream.end(() => resolve());
+    });
+
+    await expect(
+      new Promise((resolve, reject) => {
+        const guard = setTimeout(
+          () => reject(new Error('RecoverableWriteStream finish never fired')),
+          5000
+        );
+        ws.on('finish', () => { clearTimeout(guard); resolve(); });
+        ws.on('error', (e) => { clearTimeout(guard); reject(e); });
+        ws.end();
+      })
+    ).resolves.toBeUndefined();
+
+    try { fs.unlinkSync(target); } catch (e) {}
+  }, 10000);
+
+  test('_final surfaces an error when the inner stream was destroyed', async () => {
+    const target = testPath('rws_inner_destroyed.out');
+    try { fs.unlinkSync(target); } catch (e) {}
+
+    const context = { context: {}, runtime: null, saveContext: () => {} };
+    const ws = new RecoverableWriteStream(target, context);
+    ws.writeStream.destroy();
+    // give the inner stream a tick to settle
+    await new Promise((r) => setTimeout(r, 20));
+
+    await expect(
+      new Promise((resolve, reject) => {
+        const guard = setTimeout(
+          () => reject(new Error('RecoverableWriteStream never settled')),
+          5000
+        );
+        ws.on('finish', () => { clearTimeout(guard); resolve('finish'); });
+        ws.on('error', (e) => { clearTimeout(guard); reject(e); });
+        ws.end();
+      })
+    ).rejects.toBeTruthy();
+
+    try { fs.unlinkSync(target); } catch (e) {}
+  }, 10000);
+});
+
+describe('recoverable pipeline persists readItemCount', () => {
+  test('full run commits readItemCount to the context', async () => {
+    const srcData = Buffer.from('m'.repeat(150 * 1024)); // multiple items
+    const srcFile = testPath('ric_src.bin');
+    const sealedFile = testPath('ric_src.bin.sealed');
+    const outFile = testPath('ric_src.bin.out');
+    const ctxFile = testPath('ric_context');
+    for (const f of [srcFile, sealedFile, outFile, ctxFile]) {
+      try { fs.unlinkSync(f); } catch (e) {}
+    }
+    fs.writeFileSync(srcFile, srcData);
+
+    const sealed = await sealBuffer(srcData);
+    fs.writeFileSync(sealedFile, sealed);
+    const { header } = unsealerInput(sealed);
+    const totalItems = validateHeader(header).itemNumber;
+
+    const context = new PipelineContextInFile(ctxFile);
+    await context.loadContext();
+
+    const rs = new RecoverableReadStream(sealedFile, context);
+    const ws = new RecoverableWriteStream(outFile, context);
+    const unsealer = new Unsealer({ keyPair: key_pair, context });
+    rs.pipe(unsealer).pipe(ws);
+
+    await new Promise((resolve, reject) => {
+      ws.on('finish', resolve);
+      ws.on('error', reject);
+      rs.on('error', reject);
+      unsealer.on('error', reject);
+    });
+
+    expect(Buffer.compare(fs.readFileSync(outFile), srcData)).toBe(0);
+    expect(context.context.readItemCount).toBe(totalItems);
+
+    for (const f of [srcFile, sealedFile, outFile, ctxFile]) {
+      try { fs.unlinkSync(f); } catch (e) {}
+    }
+  }, 20000);
+});
+
+describe('createInactivityWatchdog', () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => jest.useRealTimers());
+
+  test('fires once after inactivity and is silenced by kick/stop', () => {
+    const onStall = jest.fn();
+    const wd = createInactivityWatchdog(1000, onStall);
+
+    wd.kick();
+    jest.advanceTimersByTime(900);
+    wd.kick(); // activity resets the timer
+    jest.advanceTimersByTime(900);
+    expect(onStall).not.toHaveBeenCalled();
+
+    jest.advanceTimersByTime(200); // 1100ms since last kick
+    expect(onStall).toHaveBeenCalledTimes(1);
+
+    wd.stop();
+    wd.kick();
+    jest.advanceTimersByTime(5000);
+    expect(onStall).toHaveBeenCalledTimes(1);
+  });
+
+  test('ms of 0 disables the watchdog', () => {
+    const onStall = jest.fn();
+    const wd = createInactivityWatchdog(0, onStall);
+    wd.kick();
+    jest.advanceTimersByTime(60_000);
+    expect(onStall).not.toHaveBeenCalled();
+    wd.stop();
+  });
+});