web-sdk-pp-detection 0.3.0 → 0.3.2

package/README.md

@@ -4,15 +4,15 @@
 
 基于 ONNX Runtime Web 的浏览器端 PP-Detection 目标检测 SDK，支持 PC、移动端与各类 H5 页面。
 
-当前 SDK 版本为 **0.3.0**，完整变更见[发布说明](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/zh-CN/release-0.3.0.md)。
+当前 SDK 版本为 **0.3.2**，完整变更见[发布说明](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/zh-CN/release-0.3.2.md)。
 
 ## 安装
 
 ```bash
-pnpm add web-sdk-pp-detection@0.3.0
+pnpm add web-sdk-pp-detection@0.3.2
 ```
 
-也可以使用 `npm install web-sdk-pp-detection@0.3.0`。
+也可以使用 `npm install web-sdk-pp-detection@0.3.2`。
 
 ## 快速开始
 
@@ -37,17 +37,17 @@ await detector.dispose();
 
 `classThresholds` 按 manifest 标签名称覆盖目标检测置信度过滤阈值，未配置的类别回退到全局 `threshold`。未知类别名称或超出 `0` 到 `1` 的值会被拒绝。
 
-工厂必须显式传入 `model` 或 `manifest`，两者均缺省时抛出 `INVALID_MANIFEST`；同时传入时优先使用 `model`。仓库提供 PicoDet 1.0.1 FP32 stable manifest，npm 包不包含 ONNX 模型本体。自定义模型也应传入经过验证的 runtime manifest 或清单对象。
+工厂必须显式传入 `model` 或 `manifest`，两者均缺省时抛出 `INVALID_MANIFEST`；同时传入时优先使用 `model`。仓库提供 PicoDet 1.0.2 与 PP-YOLOE 0.1.1 的六个 stable 变体清单，npm 包不内置清单或 ONNX 模型本体。自定义模型也应传入经过验证的 runtime manifest 或清单对象。
 
-仓库模型 manifest 默认来源为 Hugging Face；在线 Demo 的来源选择默认设为 ModelScope，两者分别属于模型清单和 Demo 配置。
+两份当前 manifest 和在线 Demo 均默认 ModelScope，并可显式选择 ModelScope 或 Hugging Face。
 
 模型初始化耗时可以通过 `detector.loadTimings` 查看。`totalMs` 是初始化总耗时，同时提供 `modelDownloadMs`（网络下载）、`modelCacheReadMs`（缓存读取）、`integrityMs`（SHA-256 完整性校验）和 `sessionMs`（ONNX Runtime Session 创建）。从 0.2.0 起，`loadTimings.modelSource` 区分 `network`、`cache`、`memory`，`runtime.runtimeVersion/environment` 记录实际 ORT 版本和环境快照。初始化总耗时包含 manifest 获取，详细语义见[性能文档](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/zh-CN/performance.md)。
 
 ## 运行后端与精度
 
 - `backend: "auto"` 优先使用 WebGPU；设置 `allowFallback: true` 后，WebGPU 会话或推理失败才会尝试 WASM（CPU）。也可手动指定 `"webgpu"` 或 `"wasm"`。
-- `precision: "auto"` 选择清单中可用的默认稳定精度；当前默认 PicoDet 仅验证 FP32，因此不会臆测切换到 FP16。已验证其他精度时可手动指定 `"fp16"`、`"int8"` 等。
-- 默认 PicoDet 1.0.1 FP32 已发布可下载的 stable ONNX 资产，并通过 Linux WASM 与 Windows NVIDIA WebGPU 七张 fixture 验证；FP16、INT8、INT4 和 FP8 仍需独立证据。
+- `precision: "auto"` 选择清单默认的稳定精度，当前两份清单均为 FP32；`precision: "fp16"` 选择 FP16，`precision: "int8"` 选择 W8A32。
+- 两模型的 FP32、FP16、W8A32 均为 stable。FP16/W8A32 证据仅覆盖 2026-09-12 桌面 WASM/WebGPU 固定 64 图三轮验证；小米 15 实测仅覆盖原 FP32。
 - 使用默认模型时，显式请求清单中未声明的组合会抛出 `CAPABILITY_UNSUPPORTED`，不会改写无效组合；自定义清单可在单独验证后声明其他组合。上游模型是 float32，不支持 FP64；FP32 约为 FP16 两倍大小并可能更慢、更占显存。
 - `detect` 可接收图片 Blob/File、Canvas/ImageData、`HTMLVideoElement` 或单帧 `VideoFrame`。摄像头和视频播放的权限、帧率控制由宿主页面负责；每次提交一帧后应等待 Promise 完成，并在停止媒体时调用 `dispose()`。
 
@@ -82,15 +82,15 @@ const detector = await createPPDetection({
 
 A browser-first PP-Detection object detection SDK powered by ONNX Runtime Web for desktop, mobile, and H5 pages.
 
-The current SDK version is **0.3.0**. See the [release notes](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/en/release-0.3.0.md) for the complete changes.
+The current SDK version is **0.3.2**. See the [release notes](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/en/release-0.3.2.md) for the complete changes.
 
 ### Installation
 
 ```bash
-pnpm add web-sdk-pp-detection@0.3.0
+pnpm add web-sdk-pp-detection@0.3.2
 ```
 
-`npm install web-sdk-pp-detection@0.3.0` is also supported.
+`npm install web-sdk-pp-detection@0.3.2` is also supported.
 
 ### Quick start
 
@@ -115,17 +115,17 @@ await detector.dispose();
 
 `classThresholds` overrides object-detection confidence filtering for matching manifest label names and falls back to the global `threshold` for unspecified classes. Unknown class names and values outside `0` through `1` are rejected.
 
-The factory requires an explicit `model` or `manifest`; omitting both throws `INVALID_MANIFEST`, and `model` takes precedence when both are supplied. The repository provides the PicoDet 1.0.1 FP32 stable manifest; the npm package contains no ONNX model binary. Custom models also require a verified runtime or custom manifest.
+工厂必须显式传入 `model` 或 `manifest`，两者均缺省时抛出 `INVALID_MANIFEST`；同时传入时优先使用 `model`。仓库提供 PicoDet 1.0.2 与 PP-YOLOE 0.1.1 的六个 stable 变体清单，npm 包不内置清单或 ONNX 模型本体。
 
-The repository model manifest defaults to Hugging Face. The live Demo independently configures its source selector to default to ModelScope.
+两份当前 manifest 和在线 Demo 均默认 ModelScope，并可显式选择 ModelScope 或 Hugging Face。
 
 Detailed initialization timings are available through `detector.loadTimings`. `totalMs` is the full initialization duration. The additive fields `modelDownloadMs`, `modelCacheReadMs`, `integrityMs`, and `sessionMs` separate network download, cache reads, SHA-256 verification, and Session creation. From 0.2.0, `loadTimings.modelSource` distinguishes `network`, `cache`, and `memory`, while `runtime.runtimeVersion/environment` capture the actual ORT version and environment. Initialization totals include manifest retrieval; see [performance](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/en/performance.md) for the full semantics.
 
 ### Backend and precision
 
 - `backend: "auto"` prefers WebGPU; with `allowFallback: true`, a failed WebGPU session or inference attempts WASM (CPU). Use `"webgpu"` or `"wasm"` for an explicit choice.
-- `precision: "auto"` selects the available default stable precision from the manifest. The default PicoDet 1.0.1 validates FP32 only, so the SDK does not guess an FP16 switch. When another precision has been validated, select it explicitly with `"fp16"`, `"int8"`, and so on.
-- The default PicoDet 1.0.1 FP32 variant is a downloadable stable ONNX asset and has passed seven-fixture validation on Linux WASM and Windows NVIDIA WebGPU. FP16, INT8, INT4, and FP8 still require independent release-source and backend evidence.
+- `precision: "auto"` 选择清单默认的稳定精度，当前两份清单均为 FP32；`precision: "fp16"` 选择 FP16，`precision: "int8"` 选择 W8A32。
+- 两模型的 FP32、FP16、W8A32 均为 stable。FP16/W8A32 证据仅覆盖 2026-09-12 桌面 WASM/WebGPU 固定 64 图三轮验证；小米 15 实测仅覆盖原 FP32。
 - `detect` accepts image Blob/File, Canvas/ImageData, `HTMLVideoElement`, or a single `VideoFrame`. Hosts own camera/video permissions and frame pacing; await each frame Promise and call `dispose()` when media stops.
 - Explicit pairs absent from the default manifest throw `CAPABILITY_UNSUPPORTED` instead of rewriting an invalid pair. The upstream model is float32, not FP64; FP64 inference is unsupported. FP32 is about twice the size of FP16 and may be slower or use more GPU memory.
 
@@ -151,7 +151,11 @@ WeChat official-account pages and other H5/WebView integrations are supported. N
 
 ### PP-YOLOE 稳定模型（0.3.0 起）
 
-0.3.0 配套提供 PP-YOLOE+ S 640 FP32 `0.1.0 stable` 清单，模型从 ModelScope 或 Hugging Face 的固定 revision 下载，npm 包不包含权重。见[模型接入](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/v0.3.0/examples/ppyoloe-candidate/README.md)。`allowExperimental` 默认关闭，仅运行 labs 候选时显式开启；blocked 仍被拒绝。Demo 默认 PicoDet，两个模型均默认 ModelScope。
+当前 PP-YOLOE+ S 640 为 `0.1.1`，与 PicoDet 1.0.2 一样提供 FP32、FP16、W8A32 stable 变体。见[六变体示例](https://github.com/chenmohan123/web-sdk-PP-Detection/tree/main/examples/model-variants)。`allowExperimental` 默认关闭，仅运行旧 labs 候选时显式开启；blocked 仍被拒绝。Demo 默认 PicoDet、ModelScope、FP32。
+
+### 下载配置（0.3.2 起）
+
+0.3.2 新增 `download.timeoutMs`、`download.idleTimeoutMs` 和 `download.maxRetries`。默认每次请求总时限 180 秒、无新增字节时限 30 秒、最多重试 2 次。仅 ONNX 权重下载使用此策略，清单 JSON 加载沿用既有流程。
 
 ### Documentation
 

package/dist/browser-global.js

@@ -14007,34 +14007,58 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     const rounded = value >> BICUBIC_PRECISION_BITS;
     return Math.max(0, Math.min(255, rounded));
   }
-  function bicubicChannel(raster, resizedWidth, resizedHeight, channel) {
+  function writeBicubicChannels(raster, resizedWidth, resizedHeight, target) {
     const horizontal = createBicubicAxis(raster.width, resizedWidth);
     const vertical = createBicubicAxis(raster.height, resizedHeight);
-    const intermediate = new Uint8Array(raster.height * resizedWidth);
+    const rowStride = resizedWidth * 3;
+    const intermediate = new Uint8Array(raster.height * rowStride);
     for (let y = 0; y < raster.height; y += 1) {
+      const sourceRow = y * raster.width * 4;
+      const targetRow = y * rowStride;
       for (let x = 0; x < resizedWidth; x += 1) {
         const [start, count] = horizontal.bounds[x];
         const coefficients = horizontal.coefficients[x];
-        let sum = BICUBIC_ROUNDING;
+        let red = BICUBIC_ROUNDING;
+        let green = BICUBIC_ROUNDING;
+        let blue = BICUBIC_ROUNDING;
+        let source2 = sourceRow + start * 4;
         for (let index = 0; index < count; index += 1) {
-          sum += raster.rgba[(y * raster.width + start + index) * 4 + channel] * coefficients[index];
+          const coefficient = coefficients[index];
+          red += raster.rgba[source2] * coefficient;
+          green += raster.rgba[source2 + 1] * coefficient;
+          blue += raster.rgba[source2 + 2] * coefficient;
+          source2 += 4;
         }
-        intermediate[y * resizedWidth + x] = clipBicubic(sum);
+        const offset = targetRow + x * 3;
+        intermediate[offset] = clipBicubic(red);
+        intermediate[offset + 1] = clipBicubic(green);
+        intermediate[offset + 2] = clipBicubic(blue);
       }
     }
-    const output = new Uint8Array(resizedWidth * resizedHeight);
+    const plane = target.inputWidth * target.inputHeight;
     for (let y = 0; y < resizedHeight; y += 1) {
       const [start, count] = vertical.bounds[y];
       const coefficients = vertical.coefficients[y];
+      const sourceRow = start * rowStride;
+      const targetRow = (y + target.padTop) * target.inputWidth + target.padLeft;
       for (let x = 0; x < resizedWidth; x += 1) {
-        let sum = BICUBIC_ROUNDING;
+        let red = BICUBIC_ROUNDING;
+        let green = BICUBIC_ROUNDING;
+        let blue = BICUBIC_ROUNDING;
+        let source2 = sourceRow + x * 3;
         for (let index = 0; index < count; index += 1) {
-          sum += intermediate[(start + index) * resizedWidth + x] * coefficients[index];
+          const coefficient = coefficients[index];
+          red += intermediate[source2] * coefficient;
+          green += intermediate[source2 + 1] * coefficient;
+          blue += intermediate[source2 + 2] * coefficient;
+          source2 += rowStride;
         }
-        output[y * resizedWidth + x] = clipBicubic(sum);
+        const offset = targetRow + x;
+        target.data[offset] = target.values[clipBicubic(red)];
+        target.data[plane + offset] = target.values[256 + clipBicubic(green)];
+        target.data[plane * 2 + offset] = target.values[512 + clipBicubic(blue)];
       }
     }
-    return output;
   }
   function preprocessImage(raster, preprocessing) {
     const inputWidth = preprocessing.size.width;
@@ -14061,18 +14085,35 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     const mean = normalize ? preprocessing.mean ?? [0, 0, 0] : [0, 0, 0];
     const std = normalize ? preprocessing.std ?? [1, 1, 1] : [1, 1, 1];
     const interpolation2 = preprocessing.interpolation ?? "bilinear";
+    const bicubicValues = doResize && interpolation2 === "bicubic" ? new Float32Array(256 * 3) : void 0;
     for (let channel = 0; channel < 3; channel += 1) {
       const padding = normalize && mean[channel] !== 0 ? -mean[channel] / std[channel] : 0;
       data.fill(padding, channel * plane, (channel + 1) * plane);
-      const bicubic = doResize && interpolation2 === "bicubic" ? bicubicChannel(raster, resizedWidth, resizedHeight, channel) : void 0;
+      if (bicubicValues) {
+        for (let pixel = 0; pixel < 256; pixel += 1) {
+          const scaled = rescale ? pixel * preprocessing.rescaleFactor : pixel;
+          bicubicValues[channel * 256 + pixel] = normalize ? (scaled - mean[channel]) / std[channel] : scaled;
+        }
+        continue;
+      }
       for (let y = 0; y < resizedHeight; y += 1) {
         for (let x = 0; x < resizedWidth; x += 1) {
-          const pixel = bicubic ? bicubic[y * resizedWidth + x] : doResize ? bilinearChannel(raster, x, y, resizedWidth, resizedHeight, channel) : sampleChannel(raster, x, y, channel);
+          const pixel = doResize ? bilinearChannel(raster, x, y, resizedWidth, resizedHeight, channel) : sampleChannel(raster, x, y, channel);
           const scaled = rescale ? pixel * preprocessing.rescaleFactor : pixel;
           data[channel * plane + (y + padTop) * inputWidth + x + padLeft] = normalize ? (scaled - mean[channel]) / std[channel] : scaled;
         }
       }
     }
+    if (bicubicValues) {
+      writeBicubicChannels(raster, resizedWidth, resizedHeight, {
+        data,
+        inputWidth,
+        inputHeight,
+        padLeft,
+        padTop,
+        values: bicubicValues
+      });
+    }
     return {
       data,
       dims: [1, 3, inputHeight, inputWidth],
@@ -15069,11 +15110,36 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
   }
 
   // src/model/download.ts
+  var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+  var RetryableDownloadError = class extends PPDetectionError {
+    constructor(message, details = {}, cause) {
+      super("MODEL_DOWNLOAD_FAILED", message, details, { cause });
+    }
+  };
+  function resolveDownloadOptions(options = {}) {
+    if (options === null || typeof options !== "object")
+      throw new PPDetectionError("INVALID_INPUT", "\u4E0B\u8F7D\u914D\u7F6E\u5FC5\u987B\u662F\u5BF9\u8C61");
+    const resolved = {
+      timeoutMs: options.timeoutMs === void 0 ? 18e4 : options.timeoutMs,
+      idleTimeoutMs: options.idleTimeoutMs === void 0 ? 3e4 : options.idleTimeoutMs,
+      maxRetries: options.maxRetries === void 0 ? 2 : options.maxRetries
+    };
+    for (const [key, value] of Object.entries(resolved)) {
+      const maximum = key === "maxRetries" ? 5 : 2147483647;
+      if (!Number.isSafeInteger(value) || value < 0 || value > maximum)
+        throw new PPDetectionError("INVALID_INPUT", "\u4E0B\u8F7D\u53C2\u6570\u5FC5\u987B\u4E3A\u5141\u8BB8\u8303\u56F4\u5185\u7684\u5B89\u5168\u6574\u6570", {
+          parameter: key,
+          value,
+          maximum
+        });
+    }
+    return resolved;
+  }
   function now() {
     return globalThis.performance?.now() ?? Date.now();
   }
   function aborted(error, signal) {
-    return signal?.aborted === true || error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+    return signal?.aborted === true || error instanceof Error && error.name === "AbortError";
   }
   function throwIfAborted3(signal) {
     if (signal?.aborted) throw new PPDetectionError("ABORTED", "\u6A21\u578B\u4E0B\u8F7D\u5DF2\u53D6\u6D88");
@@ -15101,106 +15167,206 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       });
     }
   }
-  async function readResponse(response, expectedBytes, signal, onProgress) {
-    const totalBytes = contentLength(response, expectedBytes);
-    if (!response.body) {
-      const bytes2 = await response.arrayBuffer();
-      throwIfAborted3(signal);
-      onProgress?.({ loadedBytes: bytes2.byteLength, totalBytes });
-      return bytes2;
+  function cancelQuietly(cancel) {
+    try {
+      void Promise.resolve(cancel()).catch(() => void 0);
+    } catch {
     }
-    const reader = response.body.getReader();
-    const chunks = [];
-    let loadedBytes = 0;
+  }
+  async function downloadAttempt(asset, fetcher, options, policy, attempt) {
+    const controller = new AbortController();
+    let response;
+    let reader;
+    let active = true;
+    let cancelledBody = false;
+    let stopError;
+    let totalTimer;
+    let idleTimer;
+    let rejectStop;
+    const stopped = new Promise((_resolve, reject) => {
+      rejectStop = reject;
+    });
+    void stopped.catch(() => void 0);
+    const cancelBody = (reason) => {
+      if (cancelledBody || !reader && !response?.body) return;
+      cancelledBody = true;
+      if (reader) cancelQuietly(() => reader.cancel(reason));
+      else cancelQuietly(() => response.body.cancel(reason));
+    };
+    const stop = (error) => {
+      if (!active || stopError) return;
+      stopError = error;
+      rejectStop(error);
+      controller.abort();
+      cancelBody(error);
+    };
+    const abort = () => stop(new PPDetectionError("ABORTED", "\u6A21\u578B\u4E0B\u8F7D\u5DF2\u53D6\u6D88"));
+    const renewIdle = () => {
+      clearTimeout(idleTimer);
+      if (policy.idleTimeoutMs > 0)
+        idleTimer = setTimeout(
+          () => stop(
+            new RetryableDownloadError("\u6A21\u578B\u4E0B\u8F7D\u957F\u65F6\u95F4\u6CA1\u6709\u65B0\u589E\u5B57\u8282", {
+              idleTimeoutMs: policy.idleTimeoutMs
+            })
+          ),
+          policy.idleTimeoutMs
+        );
+    };
+    const checkActive = () => {
+      if (stopError) throw stopError;
+      throwIfAborted3(options.signal);
+    };
+    const network = async (operation) => {
+      try {
+        checkActive();
+        const value = await Promise.race([operation(), stopped]);
+        checkActive();
+        return value;
+      } catch (error) {
+        if (stopError) throw stopError;
+        if (aborted(error, options.signal))
+          throw new PPDetectionError("ABORTED", "\u6A21\u578B\u4E0B\u8F7D\u5DF2\u53D6\u6D88", {}, { cause: error });
+        if (error instanceof PPDetectionError) throw error;
+        throw new RetryableDownloadError(
+          "\u6A21\u578B\u4E0B\u8F7D\u8BF7\u6C42\u6216\u54CD\u5E94\u8BFB\u53D6\u5931\u8D25",
+          { sourceKind: asset.source.kind, downloadUrl: asset.source.downloadUrl },
+          error
+        );
+      }
+    };
+    const report = (loadedBytes) => {
+      checkActive();
+      options.onProgress?.({
+        loadedBytes,
+        totalBytes: asset.source.bytes,
+        attempt,
+        maxAttempts: policy.maxRetries + 1
+      });
+      checkActive();
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
     try {
+      throwIfAborted3(options.signal);
+      if (policy.timeoutMs > 0)
+        totalTimer = setTimeout(
+          () => stop(
+            new RetryableDownloadError("\u6A21\u578B\u4E0B\u8F7D\u8D85\u8FC7\u8BF7\u6C42\u603B\u65F6\u9650", { timeoutMs: policy.timeoutMs })
+          ),
+          policy.timeoutMs
+        );
+      renewIdle();
+      report(0);
+      response = await network(
+        () => Promise.resolve(
+          fetcher(asset.source.downloadUrl, {
+            signal: controller.signal,
+            ...attempt > 1 ? { cache: "reload" } : {}
+          })
+        ).then((value) => {
+          response = value;
+          if (!active || stopError) cancelBody(stopError);
+          return value;
+        })
+      );
+      if (!response.ok) {
+        const details = {
+          sourceKind: asset.source.kind,
+          status: response.status,
+          statusText: response.statusText
+        };
+        if (RETRYABLE_STATUSES.has(response.status))
+          throw new RetryableDownloadError("\u6A21\u578B\u4E0B\u8F7D\u8FD4\u56DE\u53EF\u91CD\u8BD5\u72B6\u6001", details);
+        throw new PPDetectionError("MODEL_DOWNLOAD_FAILED", "\u6A21\u578B\u4E0B\u8F7D\u8FD4\u56DE\u975E\u6210\u529F\u72B6\u6001", details);
+      }
+      validatePartialResponse(response, asset.source.bytes);
+      contentLength(response, asset.source.bytes);
+      if (!response.body) {
+        const bytes2 = await network(() => response.arrayBuffer());
+        report(bytes2.byteLength);
+        return bytes2;
+      }
+      reader = response.body.getReader();
+      const chunks = [];
+      let loadedBytes = 0;
       while (true) {
-        throwIfAborted3(signal);
-        const chunk = await reader.read();
+        const chunk = await network(() => reader.read());
         if (chunk.done) break;
+        if (chunk.value.byteLength === 0) continue;
         loadedBytes += chunk.value.byteLength;
-        if (loadedBytes > expectedBytes) {
+        if (loadedBytes > asset.source.bytes)
           throw new PPDetectionError("MODEL_INTEGRITY_FAILED", "\u6A21\u578B\u54CD\u5E94\u8D85\u8FC7\u6E05\u5355\u58F0\u660E\u5927\u5C0F", {
-            expectedBytes,
+            expectedBytes: asset.source.bytes,
             loadedBytes
           });
-        }
         chunks.push(chunk.value);
-        onProgress?.({ loadedBytes, totalBytes });
+        renewIdle();
+        report(loadedBytes);
+      }
+      const bytes = new Uint8Array(loadedBytes);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
       }
+      report(loadedBytes);
+      return bytes.buffer;
     } catch (error) {
+      controller.abort();
+      cancelBody(error);
+      throw error;
+    } finally {
+      active = false;
+      clearTimeout(totalTimer);
+      clearTimeout(idleTimer);
+      options.signal?.removeEventListener("abort", abort);
       try {
-        await reader.cancel(error);
+        reader?.releaseLock();
       } catch {
       }
-      throw error;
-    } finally {
-      reader.releaseLock();
     }
-    const bytes = new Uint8Array(loadedBytes);
-    let offset = 0;
-    for (const chunk of chunks) {
-      bytes.set(chunk, offset);
-      offset += chunk.byteLength;
-    }
-    onProgress?.({ loadedBytes, totalBytes });
-    return bytes.buffer;
+  }
+  function waitForRetry(delayMs, signal) {
+    throwIfAborted3(signal);
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        reject(new PPDetectionError("ABORTED", "\u6A21\u578B\u4E0B\u8F7D\u5DF2\u53D6\u6D88"));
+      };
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", abort);
+        resolve();
+      }, delayMs);
+      signal?.addEventListener("abort", abort, { once: true });
+      if (signal?.aborted) abort();
+    });
   }
   async function loadModelAsset(asset, options = {}) {
     throwIfAborted3(options.signal);
+    const policy = resolveDownloadOptions(options.download);
     const fetcher = options.fetcher ?? globalThis.fetch?.bind(globalThis);
     if (!fetcher)
       throw new PPDetectionError("MODEL_DOWNLOAD_FAILED", "\u5F53\u524D\u73AF\u5883\u6CA1\u6709 fetch API", {
         sourceKind: asset.source.kind
       });
     const downloadStarted = now();
-    let response;
-    try {
-      response = await fetcher(asset.source.downloadUrl, { signal: options.signal });
-    } catch (error) {
-      if (aborted(error, options.signal))
-        throw new PPDetectionError("ABORTED", "\u6A21\u578B\u4E0B\u8F7D\u5DF2\u53D6\u6D88", {}, { cause: error });
-      throw new PPDetectionError(
-        "MODEL_DOWNLOAD_FAILED",
-        "\u6A21\u578B\u4E0B\u8F7D\u8BF7\u6C42\u5931\u8D25",
-        {
-          sourceKind: asset.source.kind,
-          downloadUrl: asset.source.downloadUrl
-        },
-        { cause: error }
-      );
-    }
-    if (!response.ok) {
-      throw new PPDetectionError("MODEL_DOWNLOAD_FAILED", "\u6A21\u578B\u4E0B\u8F7D\u8FD4\u56DE\u975E\u6210\u529F\u72B6\u6001", {
-        sourceKind: asset.source.kind,
-        status: response.status,
-        statusText: response.statusText
-      });
-    }
-    validatePartialResponse(response, asset.source.bytes);
     let bytes;
-    try {
-      bytes = await readResponse(response, asset.source.bytes, options.signal, options.onProgress);
-    } catch (error) {
-      if (error instanceof PPDetectionError) throw error;
-      if (aborted(error, options.signal))
-        throw new PPDetectionError("ABORTED", "\u6A21\u578B\u4E0B\u8F7D\u5DF2\u53D6\u6D88", {}, { cause: error });
-      throw new PPDetectionError(
-        "MODEL_DOWNLOAD_FAILED",
-        "\u8BFB\u53D6\u6A21\u578B\u54CD\u5E94\u5931\u8D25",
-        { sourceKind: asset.source.kind },
-        { cause: error }
-      );
+    for (let attempt = 1; ; attempt++) {
+      throwIfAborted3(options.signal);
+      try {
+        bytes = await downloadAttempt(asset, fetcher, options, policy, attempt);
+        break;
+      } catch (error) {
+        throwIfAborted3(options.signal);
+        if (!(error instanceof RetryableDownloadError) || attempt > policy.maxRetries) throw error;
+        await waitForRetry(Math.min(500 * 2 ** (attempt - 1), 4e3), options.signal);
+      }
     }
     const modelDownloadMs = now() - downloadStarted;
     const integrityStarted = now();
     await verifyModelIntegrity(bytes, asset.source, options.signal);
-    return {
-      bytes,
-      timings: {
-        modelDownloadMs,
-        integrityMs: now() - integrityStarted
-      }
-    };
+    return { bytes, timings: { modelDownloadMs, integrityMs: now() - integrityStarted } };
   }
 
   // src/model/source-resolver.ts
@@ -15267,6 +15433,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
   }
   var ModelManager = class {
     fetcher;
+    download;
     cache;
     coordinator;
     lifecycle = new AbortController();
@@ -15275,6 +15442,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     disposed = false;
     disposePromise;
     constructor(options = {}) {
+      this.download = resolveDownloadOptions(options.download);
       this.fetcher = options.fetcher;
       this.cache = createCache(options.cache);
       this.coordinator = coordinateCache(this.cache);
@@ -15371,6 +15539,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
         try {
           loaded = await loadModelAsset(asset, {
             fetcher: this.fetcher,
+            download: this.download,
             signal: options.signal,
             onProgress: options.onProgress
           });
@@ -15855,7 +16024,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
   };
 
   // src/index.ts
-  var CURRENT_SDK_VERSION = "0.3.0";
+  var CURRENT_SDK_VERSION = "0.3.2";
   function probePPDetectionCapabilities(options = {}) {
     return probeCapabilities(options);
   }
@@ -15980,6 +16149,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       simpleManifest(runtimeManifest)
     );
     const modelManager = new ModelManager({
+      download: options.download,
       cache: options.cache === false ? false : options.cache === "memory" ? "memory" : void 0
     });
     let executor;