web-sdk-pp-detection 0.1.1 → 0.3.0

package/README.md

@@ -4,13 +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)。
+
 ## 安装
 
 ```bash
-pnpm add web-sdk-pp-detection
+pnpm add web-sdk-pp-detection@0.3.0
 ```
 
-也可以使用 `npm install web-sdk-pp-detection`。
+也可以使用 `npm install web-sdk-pp-detection@0.3.0`。
 
 ## 快速开始
 
@@ -35,9 +37,11 @@ await detector.dispose();
 
 `classThresholds` 按 manifest 标签名称覆盖目标检测置信度过滤阈值，未配置的类别回退到全局 `threshold`。未知类别名称或超出 `0` 到 `1` 的值会被拒绝。
 
-当前发布版本内置 PicoDet 1.0.1 FP32 stable manifest；使用默认模型时可以省略 `model`。自定义模型仍应传入经过验证的 runtime manifest 或清单对象。
+工厂必须显式传入 `model` 或 `manifest`，两者均缺省时抛出 `INVALID_MANIFEST`；同时传入时优先使用 `model`。仓库提供 PicoDet 1.0.1 FP32 stable manifest，npm 包不包含 ONNX 模型本体。自定义模型也应传入经过验证的 runtime manifest 或清单对象。
+
+仓库模型 manifest 默认来源为 Hugging Face；在线 Demo 的来源选择默认设为 ModelScope，两者分别属于模型清单和 Demo 配置。
 
-模型初始化耗时可以通过 `detector.loadTimings` 查看。`totalMs` 是初始化总耗时，同时提供 `modelDownloadMs`（网络下载）、`modelCacheReadMs`（缓存读取）、`integrityMs`（SHA-256 完整性校验）和 `sessionMs`（ONNX Runtime Session 创建）。发布版本内置 PicoDet 1.0.1 FP32 stable manifest；使用自定义模型时请传入已验证的 runtime manifest 或清单对象。
+模型初始化耗时可以通过 `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)。
 
 ## 运行后端与精度
 
@@ -61,6 +65,8 @@ const detector = await createPPDetection({
 
 模型加载进度通过 `onProgress` 回调提供。`phase: "model"`、`status: "progress"` 事件中的 `loadedBytes` 和可选的 `totalBytes` 仅表示网络下载字节，不代表完整初始化百分比，也不包含完整性校验或 Session 创建。响应没有 `Content-Length` 时 `totalBytes` 可能缺失，缓存、内存或自定义二进制模型也可能不产生字节进度。可捕获结构化的 `PPDetectionError` 并读取 `code` 与 `details`。SDK 支持模型缓存；可以通过 detector 的缓存方法查询或清理。使用结束后必须调用 `dispose()` 释放 Worker、ONNX Runtime session 与 GPU/CPU 资源。
 
+从 0.2.0 起，无活动检测器时可使用 `ModelManager.getCacheEstimate({ id, version })`、`clearCurrentModelCache({ id, version })` 统计或清理同一模型的全部变体/来源。可选的 `ModelCache.scope/list()` 支持自定义缓存协调和模型枚举；缺少 `list()` 的自定义缓存拒绝按模型操作，不扩大清理范围。同一 JavaScript 执行环境内，清理前启动的迟到下载不会重新填充缓存；跨标签页/Worker 的并发协调不在保证范围内。完整契约见 [API](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/zh-CN/api.md)。
+
 ## 微信环境
 
 支持微信公众号页面以及微信内嵌浏览器中的 H5/WebView 集成。当前不宣称支持 native Mini Program 原生小程序直接推理；原生小程序需要通过 WebView 承载 H5 页面或使用服务端推理。
@@ -76,13 +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.
+
 ### Installation
 
 ```bash
-pnpm add web-sdk-pp-detection
+pnpm add web-sdk-pp-detection@0.3.0
 ```
 
-`npm install web-sdk-pp-detection` is also supported.
+`npm install web-sdk-pp-detection@0.3.0` is also supported.
 
 ### Quick start
 
@@ -107,9 +115,11 @@ 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 release includes a built-in PicoDet 1.0.1 FP32 stable manifest, so `model` may be omitted for the default model. Pass a verified runtime or custom manifest when using another model.
+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.
 
-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. The release includes the PicoDet 1.0.1 FP32 stable manifest; pass a verified runtime or custom model manifest when using another model.
+The repository model manifest defaults to Hugging Face. The live Demo independently configures its source selector to default to ModelScope.
+
+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
 
@@ -133,10 +143,16 @@ const detector = await createPPDetection({
 
 Use `onProgress` for model loading progress. On `phase: "model"`, `status: "progress"` events, `loadedBytes` and the optional `totalBytes` describe network-transfer bytes only; they are not an overall initialization percentage and exclude integrity verification and Session creation. `totalBytes` can be absent without a `Content-Length` response header, while cache, memory, or custom binary model sources may emit no byte progress. Structured failures are exposed as `PPDetectionError` with `code` and `details`. Model cache entries can be listed or cleared through the detector. Always call `dispose()` when finished to release the Worker, ONNX Runtime session, and GPU/CPU resources.
 
+From 0.2.0, without an active detector, `ModelManager.getCacheEstimate({ id, version })` and `clearCurrentModelCache({ id, version })` inspect or clear all variants/sources of the model. Optional `ModelCache.scope/list()` support custom cache coordination and model enumeration; a custom cache without `list()` rejects identity-based operations without broader deletion. Within the same JavaScript execution environment, downloads started before clearing cannot repopulate caches; coordination across tabs/Workers is outside this guarantee. See the [API](https://github.com/chenmohan123/web-sdk-PP-Detection/blob/main/docs/en/api.md).
+
 ### WeChat environments
 
 WeChat official-account pages and other H5/WebView integrations are supported. Native Mini Program inference is not claimed; a native Mini Program should host the H5 experience in a WebView or use server-side inference.
 
+### 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。
+
 ### Documentation
 
 - [Chinese documentation](https://github.com/chenmohan123/web-sdk-PP-Detection#readme)

package/dist/browser-global.js

@@ -14258,7 +14258,11 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
           original: { width: decoded.width, height: decoded.height }
         },
         model: this.model,
-        runtime: this.runtime,
+        runtime: {
+          ...this.runtime,
+          fallbacks: this.runtime.fallbacks.map((fallback) => ({ ...fallback })),
+          ...this.runtime.environment ? { environment: { ...this.runtime.environment } } : {}
+        },
         timings: {
           decodeMs: decoded.decodeMs,
           preprocessMs,
@@ -14751,8 +14755,84 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     });
   }
 
+  // src/cache/coordination.ts
+  var CacheCoordinator = class {
+    caches = /* @__PURE__ */ new Map();
+    generation = 0;
+    keys = /* @__PURE__ */ new Map();
+    pending = Promise.resolve();
+    guard(key) {
+      const generation = this.generation;
+      const keyGeneration = this.keys.get(key) ?? 0;
+      this.keys.set(key, keyGeneration);
+      return () => generation === this.generation && keyGeneration === (this.keys.get(key) ?? 0);
+    }
+    run(operation) {
+      const pending = this.pending.then(operation);
+      this.pending = pending.catch(() => void 0);
+      return pending;
+    }
+    clear(key, matches) {
+      if (matches) {
+        for (const [candidate, generation] of this.keys) {
+          if (matches(candidate)) this.keys.set(candidate, generation + 1);
+        }
+      } else if (key === void 0) this.generation += 1;
+      else this.keys.set(key, (this.keys.get(key) ?? 0) + 1);
+      return this.run(async () => {
+        const outcomes = await Promise.allSettled(
+          [...this.caches.keys()].map(async (cache) => {
+            if (matches && cache.list) {
+              for (const entry of await cache.list()) {
+                if (matches(entry.key)) await cache.clearCurrent(entry.key);
+              }
+            } else if (key === void 0) await cache.clearAll();
+            else await cache.clearCurrent(key);
+          })
+        );
+        const failure = outcomes.find((outcome) => outcome.status === "rejected");
+        if (failure?.status === "rejected") throw failure.reason;
+      });
+    }
+    unregister(cache) {
+      const count = this.caches.get(cache) ?? 0;
+      if (count > 1) {
+        this.caches.set(cache, count - 1);
+        return false;
+      }
+      this.caches.delete(cache);
+      return true;
+    }
+  };
+  var coordinators = /* @__PURE__ */ new WeakMap();
+  function coordinateCache(cache) {
+    const scope = cache.scope ?? cache;
+    let coordinator = coordinators.get(scope);
+    if (!coordinator) {
+      coordinator = new CacheCoordinator();
+      coordinators.set(scope, coordinator);
+    }
+    coordinator.caches.set(cache, (coordinator.caches.get(cache) ?? 0) + 1);
+    return coordinator;
+  }
+  var databaseScopes = /* @__PURE__ */ new WeakMap();
+  function databaseScope(factory, name) {
+    let scopes = databaseScopes.get(factory);
+    if (!scopes) {
+      scopes = /* @__PURE__ */ new Map();
+      databaseScopes.set(factory, scopes);
+    }
+    let scope = scopes.get(name);
+    if (!scope) {
+      scope = {};
+      scopes.set(name, scope);
+    }
+    return scope;
+  }
+
   // src/cache/indexeddb-cache.ts
   var IndexedDBModelCache = class {
+    scope;
     factory;
     databaseName;
     database;
@@ -14761,6 +14841,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       if (!factory) throw new Error("\u5F53\u524D\u73AF\u5883\u4E0D\u652F\u6301 IndexedDB");
       this.factory = factory;
       this.databaseName = options.databaseName ?? "web-sdk-pp-detection-models-v1";
+      this.scope = databaseScope(factory, this.databaseName);
     }
     async get(key) {
       const record3 = await this.request(
@@ -14814,6 +14895,24 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       (await this.database).close();
       this.database = void 0;
     }
+    async list() {
+      const database = await this.open();
+      return await new Promise((resolve, reject) => {
+        const transaction = database.transaction("models", "readonly");
+        const request = transaction.objectStore("models").openCursor();
+        const entries = [];
+        request.onerror = () => reject(request.error ?? new Error("\u8BFB\u53D6\u7F13\u5B58\u5BB9\u91CF\u5931\u8D25"));
+        request.onsuccess = () => {
+          const cursor = request.result;
+          if (!cursor) return;
+          const record3 = cursor.value;
+          entries.push({ key: record3.key, bytes: record3.size });
+          cursor.continue();
+        };
+        transaction.oncomplete = () => resolve(entries);
+        transaction.onabort = () => reject(transaction.error ?? new Error("\u7F13\u5B58\u5BB9\u91CF\u4E8B\u52A1\u4E2D\u6B62"));
+      });
+    }
     open() {
       if (this.database) return this.database;
       this.database = new Promise((resolve, reject) => {
@@ -14883,6 +14982,11 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       this.entries.clear();
       return Promise.resolve();
     }
+    list() {
+      return Promise.resolve(
+        [...this.entries].map(([key, bytes]) => ({ key, bytes: bytes.byteLength }))
+      );
+    }
   };
 
   // src/cache/model-cache.ts
@@ -14890,9 +14994,11 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     constructor(memory, persistent) {
       this.memory = memory;
       this.persistent = persistent;
+      this.scope = persistent?.scope ?? persistent ?? memory;
     }
     memory;
     persistent;
+    scope;
     async get(key) {
       const memoryValue = await this.memory.get(key);
       if (memoryValue) return memoryValue;
@@ -14915,6 +15021,13 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     estimate() {
       return this.persistent?.estimate() ?? this.memory.estimate();
     }
+    async list() {
+      const entries = /* @__PURE__ */ new Map();
+      for (const cache of [this.memory, this.persistent]) {
+        for (const entry of await cache?.list?.() ?? []) entries.set(entry.key, entry);
+      }
+      return [...entries.values()];
+    }
     async close() {
       await this.memory.close?.();
       await this.persistent?.close?.();
@@ -15124,6 +15237,14 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
 
   // src/model/model-manager.ts
   var SDK_CACHE_NAMESPACE = "web-sdk-pp-detection:cache-v1";
+  function matchesModel(key, model) {
+    try {
+      const parts = JSON.parse(key);
+      return Array.isArray(parts) && parts[0] === SDK_CACHE_NAMESPACE && (model === void 0 || parts[1] === model.id && parts[2] === model.version);
+    } catch {
+      return false;
+    }
+  }
   function now2() {
     return globalThis.performance?.now() ?? Date.now();
   }
@@ -15147,6 +15268,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
   var ModelManager = class {
     fetcher;
     cache;
+    coordinator;
     lifecycle = new AbortController();
     activeLoads = /* @__PURE__ */ new Set();
     currentKey;
@@ -15155,6 +15277,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     constructor(options = {}) {
       this.fetcher = options.fetcher;
       this.cache = createCache(options.cache);
+      this.coordinator = coordinateCache(this.cache);
     }
     cacheKey(variant3, source2, model = { id: "unknown", version: "unknown" }) {
       return JSON.stringify([
@@ -15193,16 +15316,24 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       const variant3 = resolveModelVariant(manifest, options.variantId);
       const sourceKind2 = options.sourceKind ?? "auto";
       const sources = resolveModelSources(variant3, sourceKind2);
+      const guards = new Map(
+        sources.map((source2) => {
+          const key = this.cacheKey(variant3, source2, manifest.model);
+          return [key, this.coordinator.guard(key)];
+        })
+      );
       const failures = [];
       let lastError;
       for (const source2 of sources) {
         throwIfAborted4(options.signal);
         const asset = { model: manifest.model, variant: variant3, source: source2 };
         const cacheKey = this.cacheKey(variant3, source2, manifest.model);
+        this.currentKey = cacheKey;
+        const canMutate = guards.get(cacheKey);
         const cacheStarted = now2();
         let cached;
         try {
-          cached = await this.cache.get(cacheKey);
+          cached = await this.coordinator.run(() => this.cache.get(cacheKey));
         } catch (error) {
           if (error instanceof PPDetectionError && error.code === "ABORTED") throw error;
           throwIfAborted4(options.signal);
@@ -15213,7 +15344,6 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
           const integrityStarted = now2();
           try {
             await verifyModelIntegrity(cached, source2, options.signal);
-            this.currentKey = cacheKey;
             return {
               bytes: cached,
               manifest,
@@ -15227,7 +15357,9 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
           } catch (error) {
             if (error instanceof PPDetectionError && error.code === "ABORTED") throw error;
             try {
-              await this.cache.clearCurrent(cacheKey);
+              await this.coordinator.run(async () => {
+                if (canMutate()) await this.cache.clearCurrent(cacheKey);
+              });
             } catch (clearError) {
               if (clearError instanceof PPDetectionError && clearError.code === "ABORTED")
                 throw clearError;
@@ -15263,11 +15395,12 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
         }
         throwIfAborted4(options.signal);
         try {
-          await this.cache.put(cacheKey, loaded.bytes);
+          await this.coordinator.run(async () => {
+            if (canMutate()) await this.cache.put(cacheKey, loaded.bytes);
+          });
         } catch {
         }
         throwIfAborted4(options.signal);
-        this.currentKey = cacheKey;
         return {
           bytes: loaded.bytes,
           manifest,
@@ -15292,16 +15425,44 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     estimate() {
       return this.getCacheEstimate();
     }
-    getCacheEstimate() {
-      return this.cache.estimate();
+    getCacheEstimate(model) {
+      return this.coordinator.run(async () => {
+        if (!this.cache.list) {
+          if (model)
+            throw new PPDetectionError(
+              "CAPABILITY_UNSUPPORTED",
+              "\u81EA\u5B9A\u4E49\u7F13\u5B58\u9700\u5B9E\u73B0 list \u624D\u80FD\u6309\u6A21\u578B\u4F30\u7B97"
+            );
+          return this.cache.estimate();
+        }
+        const unique = /* @__PURE__ */ new Map();
+        for (const cache of this.coordinator.caches.keys()) {
+          for (const entry of await cache.list?.() ?? []) unique.set(entry.key, entry);
+        }
+        const entries = [...unique.values()].filter((entry) => matchesModel(entry.key, model));
+        return {
+          bytes: entries.reduce((sum, entry) => sum + entry.bytes, 0),
+          entries: entries.length
+        };
+      });
     }
-    async clearCurrentModelCache() {
+    async clearCurrentModelCache(model) {
+      if (model) {
+        if (!model.id || !model.version)
+          throw new PPDetectionError("INVALID_MANIFEST", "\u7F13\u5B58\u6A21\u578B\u8EAB\u4EFD\u5FC5\u987B\u5305\u542B id \u548C version");
+        if (!this.cache.list)
+          throw new PPDetectionError(
+            "CAPABILITY_UNSUPPORTED",
+            "\u81EA\u5B9A\u4E49\u7F13\u5B58\u9700\u5B9E\u73B0 list \u624D\u80FD\u6309\u6A21\u578B\u6E05\u7406"
+          );
+        await this.coordinator.clear(void 0, (key) => matchesModel(key, model));
+        return;
+      }
       if (!this.currentKey) return;
-      await this.cache.clearCurrent(this.currentKey);
+      await this.coordinator.clear(this.currentKey);
     }
     async clearAllCache() {
-      await this.cache.clearAll();
-      this.currentKey = void 0;
+      await this.coordinator.clear(void 0, (key) => matchesModel(key));
     }
     async dispose() {
       if (this.disposePromise) return await this.disposePromise;
@@ -15310,7 +15471,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       this.disposePromise = (async () => {
         await Promise.all([...this.activeLoads]);
         this.currentKey = void 0;
-        await this.cache.close?.();
+        if (this.coordinator.unregister(this.cache)) await this.cache.close?.();
       })();
       await this.disposePromise;
     }
@@ -15324,7 +15485,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     if (error instanceof PPDetectionError) return error;
     const message = error instanceof Error ? error.message : String(error);
     const details = { phase, causeMessage: message };
-    if (/abort|cancel/i.test(message))
+    if (error instanceof Error && error.name === "AbortError")
       return new PPDetectionError("ABORTED", "\u63A8\u7406\u5DF2\u53D6\u6D88", details, { cause: error });
     if (/memory|out.of.memory|allocation/i.test(message))
       return new PPDetectionError("OUT_OF_MEMORY", "\u8FD0\u884C\u65F6\u5185\u5B58\u4E0D\u8DB3", details, { cause: error });
@@ -15369,6 +15530,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       return {
         plan,
         sessionMs,
+        runtimeVersion: ort.env.versions?.web ?? null,
         async run(feeds, runOptions = {}) {
           if (disposed) throw new PPDetectionError("DISPOSED", "\u4F1A\u8BDD\u5DF2\u91CA\u653E", { phase: "run" });
           if (runOptions.signal?.aborted)
@@ -15505,13 +15667,19 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     if (executionMode === "worker" && !capabilities.worker) {
       fail("CAPABILITY_UNSUPPORTED", "\u8BF7\u6C42\u7684 worker \u4E0D\u53EF\u7528", { executionMode });
     }
-    const variant3 = manifest.variants?.find(
-      (candidate) => candidate.precision === requestedPrecision && candidate.status !== "labs" && candidate.status !== "blocked"
-    );
+    const matchingVariants = manifest.variants?.filter(
+      (candidate) => candidate.precision === requestedPrecision && candidate.status !== "blocked"
+    ) ?? [];
+    const variant3 = matchingVariants.find((candidate) => candidate.status !== "labs") ?? (options.allowExperimental === true ? matchingVariants.find((candidate) => candidate.status === "labs") : void 0);
     if (!variant3) {
-      fail("MODEL_INCOMPATIBLE", `manifest \u6CA1\u6709\u53EF\u7528\u7684 ${requestedPrecision} \u7A33\u5B9A\u53D8\u4F53`, {
-        requestedPrecision
-      });
+      fail(
+        "MODEL_INCOMPATIBLE",
+        options.allowExperimental === true ? `manifest \u6CA1\u6709\u53EF\u7528\u7684 ${requestedPrecision} \u53D8\u4F53` : `manifest \u6CA1\u6709\u53EF\u7528\u7684 ${requestedPrecision} \u7A33\u5B9A\u53D8\u4F53`,
+        {
+          requestedPrecision,
+          allowExperimental: options.allowExperimental === true
+        }
+      );
     }
     const candidates = candidatesForBackend(requestedBackend, capabilities).filter(
       (backend) => variant3.backends.includes(backend)
@@ -15687,7 +15855,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
   };
 
   // src/index.ts
-  var CURRENT_SDK_VERSION = "0.1.1";
+  var CURRENT_SDK_VERSION = "0.3.0";
   function probePPDetectionCapabilities(options = {}) {
     return probeCapabilities(options);
   }
@@ -15782,6 +15950,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     return new URL("./inference.worker.js", (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('browser-global.js', document.baseURI).href));
   }
   async function createPPDetection(options = {}) {
+    const loadStartedAt = now4();
     if (options.model === void 0 && options.manifest === void 0)
       throw new PPDetectionError("INVALID_MANIFEST", "\u521B\u5EFA PPDetection \u5B9E\u4F8B\u9700\u8981 manifest \u6216 model");
     const capabilities = probeCapabilities();
@@ -15801,6 +15970,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     options.onProgress?.({ phase: "manifest", status: "complete" });
     const plan = selectExecutionPlan(
       {
+        allowExperimental: options.allowExperimental,
         backend: options.backend,
         precision: options.precision === "auto" ? void 0 : options.precision,
         executionMode: options.executionMode,
@@ -15814,7 +15984,6 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
     });
     let executor;
     try {
-      const loadStartedAt = now4();
       options.onProgress?.({ phase: "model", status: "start" });
       let modelBytes;
       let actualSource;
@@ -15826,10 +15995,17 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
           throw new PPDetectionError("MODEL_SOURCE_UNAVAILABLE", "\u6A21\u578B\u53D8\u4F53\u6CA1\u6709\u53EF\u7528\u6765\u6E90", {
             variantId: variant3.id
           });
+        const integrityStartedAt = now4();
         await verifyModelIntegrity(memoryData, source2, options.signal);
+        const integrityMs = now4() - integrityStartedAt;
         modelBytes = memoryData;
         actualSource = source2;
-        loadTimings = { sessionMs: 0, totalMs: now4() - loadStartedAt, integrityMs: 0 };
+        loadTimings = {
+          sessionMs: 0,
+          totalMs: now4() - loadStartedAt,
+          integrityMs,
+          modelSource: "memory"
+        };
       } else {
         const loaded = await modelManager.load({
           manifest: runtimeManifest,
@@ -15841,20 +16017,26 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
         modelBytes = loaded.bytes;
         variant3 = loaded.variant;
         actualSource = loaded.source;
-        loadTimings = { ...loaded.timings, sessionMs: 0, totalMs: now4() - loadStartedAt };
+        loadTimings = {
+          ...loaded.timings,
+          sessionMs: 0,
+          totalMs: now4() - loadStartedAt,
+          modelSource: loaded.fromCache ? "cache" : "network"
+        };
       }
       options.onProgress?.({ phase: "model", status: "complete" });
       const fallbacks = [];
       const createExecutorForPlan = async (candidatePlan) => {
         options.onProgress?.({ phase: "session", status: "start" });
         let bridge;
+        const sessionStartedAt = now4();
         try {
           if (candidatePlan.executionMode === "worker") {
             if (typeof Worker !== "function")
               throw new PPDetectionError("CAPABILITY_UNSUPPORTED", "\u5F53\u524D\u73AF\u5883\u4E0D\u652F\u6301 Worker");
             const worker = new Worker(workerUrl(), { type: "module" });
             bridge = new WorkerBridge(worker);
-            await bridge.load(modelBytes.slice(0), candidatePlan, {
+            const metadata = await bridge.load(modelBytes.slice(0), candidatePlan, {
               onProgress: (event) => options.onProgress?.({
                 phase: "session",
                 status: event.status
@@ -15864,6 +16046,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
                 numThreads: options.ort?.wasm?.numThreads
               }
             });
+            runtimeVersion = typeof metadata === "object" && metadata !== null && "runtimeVersion" in metadata && typeof metadata.runtimeVersion === "string" ? metadata.runtimeVersion : null;
             const activeBridge = bridge;
             options.onProgress?.({ phase: "session", status: "complete" });
             return {
@@ -15881,7 +16064,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
             wasmPaths: options.ort?.wasm?.paths,
             numThreads: options.ort?.wasm?.numThreads
           });
-          sessionMs = session.sessionMs;
+          runtimeVersion = session.runtimeVersion ?? null;
           options.onProgress?.({ phase: "session", status: "complete" });
           return {
             run(input, signal) {
@@ -15905,10 +16088,13 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
             { phase: "create", causeMessage: message },
             { cause: error }
           );
+        } finally {
+          sessionMs += now4() - sessionStartedAt;
         }
       };
       let selectedPlan = plan;
       let sessionMs = 0;
+      let runtimeVersion = null;
       let selectedCandidateIndex = -1;
       for (const [candidateIndex, candidate] of plan.candidates.entries()) {
         const candidatePlan = {
@@ -15950,6 +16136,12 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       }
       if (!executor) throw new PPDetectionError("SESSION_CREATE_FAILED", "\u65E0\u6CD5\u521B\u5EFA\u68C0\u6D4B Session");
       const runtime = {
+        runtimeVersion,
+        environment: {
+          userAgent: globalThis.navigator?.userAgent ?? null,
+          platform: globalThis.navigator?.platform ?? null,
+          capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
         requestedBackend: options.backend ?? "auto",
         backend: selectedPlan.actualBackend,
         precision: selectedPlan.actualPrecision,
@@ -15960,8 +16152,9 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
       let activeExecutor = executor;
       const fallbackExecutor = {
         async run(input, signal) {
+          const attemptInput = runtime.mode === "worker" && options.allowFallback === true && selectedCandidateIndex < plan.candidates.length - 1 ? { ...input, data: input.data.slice() } : input;
           try {
-            return await activeExecutor.run(input, signal);
+            return await activeExecutor.run(attemptInput, signal);
           } catch (error) {
             if (options.allowFallback !== true || selectedCandidateIndex < 0 || selectedCandidateIndex >= plan.candidates.length - 1) {
               throw error;
@@ -15986,6 +16179,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
             runtime.backend = nextPlan.actualBackend;
             runtime.precision = nextPlan.actualPrecision;
             runtime.mode = nextPlan.executionMode;
+            runtime.runtimeVersion = runtimeVersion;
             const fallback = {
               cause: mapped.cause ?? mapped,
               code: mapped.code,
@@ -16017,6 +16211,7 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
         disposeResources: () => modelManager.dispose()
       });
       await detector.load({ signal: options.signal });
+      loadTimings.totalMs = now4() - loadStartedAt;
       options.onProgress?.({ phase: "ready", status: "complete" });
       return detector;
     } catch (error) {
@@ -16033,8 +16228,11 @@ ${u}`, c = n.createShaderModule({ code: d, label: e.name });
   }
   async function clearModelCache() {
     const manager = new ModelManager();
-    await manager.clearAllCache();
-    await manager.dispose();
+    try {
+      await manager.clearAllCache();
+    } finally {
+      await manager.dispose();
+    }
   }
 
   // src/browser-global.ts