u-space 0.0.32 → 0.0.33

package/dist/worker/model-decoder.js

@@ -1,95 +1,87 @@
 import { g as F } from "../getTransferables-DrzSmiCR.js";
-import { c as M } from "../workerImageUtils-mQD3TQ1N.js";
-import { M as O, v as S, U as L } from "../modelDecodeProtocol-wDB7ksYw.js";
-const B = "u-space-model-loader-cache", U = "SBMG----", C = 1179937895, R = 1313821514, D = 5130562, E = new TextDecoder();
+import { c as U } from "../workerImageUtils-mQD3TQ1N.js";
+import { l as E, U as v, d as S, M as C, v as B } from "../modelDecodeProtocol-CC2tkS8h.js";
+const R = "SBMG----", V = 1179937895, D = 1313821514, G = 5130562, k = new TextDecoder();
 function g(e) {
-  throw new L(e);
+  throw new v(e);
 }
-async function k(e, t, s, o = e, i = !1) {
-  const n = e.startsWith("data:") || e.startsWith("blob:");
-  let l = !i;
-  if (i && !n)
+function O(e, t, n, s = e, a = !1) {
+  const i = e.startsWith("data:") || e.startsWith("blob:");
+  let l = !a;
+  if (a && !i)
     try {
-      const f = new URL(e), c = new URL(o);
-      l = (f.protocol === "http:" || f.protocol === "https:") && f.origin === c.origin;
+      const d = new URL(e), f = new URL(s);
+      l = (d.protocol === "http:" || d.protocol === "https:") && d.origin === f.origin;
     } catch {
       l = !1;
     }
-  const h = await fetch(e, n ? { signal: s } : {
-    signal: s,
+  return i ? { signal: n, persistent: !1 } : {
+    signal: n,
+    persistent: t.persistent,
+    cacheMode: t.cacheMode,
+    cacheKey: t.cacheKey,
     headers: l ? t.headers : void 0,
     credentials: l ? t.credentials : "omit"
-  });
-  if (!h.ok)
-    throw new Error(`Failed to load model resource ${e}: ${h.status} ${h.statusText}`);
-  return h;
+  };
 }
-async function T(e, t, s, o, i, n, l) {
-  const h = N(e, t), f = n ? await n.resolve(h, i) : { url: h, complete() {
+async function T(e, t, n, s, a, i, l, d) {
+  const f = N(e, t), u = i ? await i.resolve(f, a) : { url: f, complete() {
   } };
   try {
-    const c = await k(f.url, o, i, s, !0), r = await l(c);
-    return f.complete(), r;
-  } catch (c) {
-    throw f.complete(c), c;
-  }
-}
-async function $(e, t, s) {
-  if (t.persistent !== !1 && typeof caches < "u") {
-    let o;
-    try {
-      o = await caches.open(B);
-      const n = await o.match(e);
-      if (n) return n.arrayBuffer();
-    } catch (n) {
-      if (s.aborted) throw n;
-      console.warn(`[ModelDecodeWorker] Failed to read Cache Storage for ${e}:`, n);
-    }
-    const i = await k(e, t, s);
-    if (o)
-      try {
-        await o.put(e, i.clone());
-      } catch (n) {
-        if (s.aborted) throw n;
-        console.warn(`[ModelDecodeWorker] Failed to write Cache Storage for ${e}:`, n);
+    const r = O(
+      u.url,
+      s,
+      a,
+      n,
+      !0
+    ), o = await E(u.url, r);
+    o.fromCache && l.push({
+      url: u.url,
+      options: {
+        headers: r.headers,
+        credentials: r.credentials,
+        cacheKey: r.cacheKey
       }
-    return i.arrayBuffer();
+    });
+    const c = await d(o);
+    return u.complete(), c;
+  } catch (r) {
+    throw u.complete(r), r;
   }
-  return (await k(e, t, s)).arrayBuffer();
 }
-function V(e) {
-  if (e.byteLength < 8 || E.decode(new Uint8Array(e, 0, 8)) !== U) return e;
-  const s = new Uint8Array(e.byteLength - 8), o = new Uint8Array(e, 8);
-  for (let i = 0; i < o.length; i++) {
-    const n = o[i];
-    s[i] = n >> 4 & 15 | n << 4 & 240;
+function $(e) {
+  if (e.byteLength < 8 || k.decode(new Uint8Array(e, 0, 8)) !== R) return e;
+  const n = new Uint8Array(e.byteLength - 8), s = new Uint8Array(e, 8);
+  for (let a = 0; a < s.length; a++) {
+    const i = s[a];
+    n[a] = i >> 4 & 15 | i << 4 & 240;
   }
-  return s.buffer;
+  return n.buffer;
 }
-function G(e) {
+function I(e) {
   const t = new DataView(e);
-  if (e.byteLength >= 12 && t.getUint32(0, !0) === C) {
-    const s = t.getUint32(8, !0);
-    if (s > e.byteLength)
-      throw new Error(`Invalid GLB length: expected ${s}, received ${e.byteLength}.`);
-    let o = 12, i;
-    const n = [];
-    for (; o + 8 <= s; ) {
-      const l = t.getUint32(o, !0), h = t.getUint32(o + 4, !0);
-      if (o += 8, o + l > s) throw new Error("Invalid GLB chunk length.");
-      const f = e.slice(o, o + l);
-      h === R ? i = JSON.parse(E.decode(f).replace(/\u0000+$/u, "")) : h === D && n.push(f), o += l;
+  if (e.byteLength >= 12 && t.getUint32(0, !0) === V) {
+    const n = t.getUint32(8, !0);
+    if (n > e.byteLength)
+      throw new Error(`Invalid GLB length: expected ${n}, received ${e.byteLength}.`);
+    let s = 12, a;
+    const i = [];
+    for (; s + 8 <= n; ) {
+      const l = t.getUint32(s, !0), d = t.getUint32(s + 4, !0);
+      if (s += 8, s + l > n) throw new Error("Invalid GLB chunk length.");
+      const f = e.slice(s, s + l);
+      d === D ? a = JSON.parse(k.decode(f).replace(/\u0000+$/u, "")) : d === G && i.push(f), s += l;
     }
-    if (!i) throw new Error("GLB does not contain a JSON chunk.");
-    return { document: i, binaryChunks: n };
+    if (!a) throw new Error("GLB does not contain a JSON chunk.");
+    return { document: a, binaryChunks: i };
   }
   return {
-    document: JSON.parse(E.decode(e).replace(/^\uFEFF/u, "")),
+    document: JSON.parse(k.decode(e).replace(/^\uFEFF/u, "")),
     binaryChunks: []
   };
 }
-function I(e) {
-  e.asset?.version?.startsWith("2") || g("Only glTF 2.x static models are supported by the decode worker."), (e.extensionsRequired?.length || e.extensionsUsed?.length) && g("glTF extensions are not supported by the decode worker."), e.animations?.length && g("Animated glTF models must use the regular loader."), e.skins?.length && g("Skinned glTF models must use the regular loader."), e.cameras?.length && g("glTF cameras must use the regular loader."), S(e);
+function K(e) {
+  e.asset?.version?.startsWith("2") || g("Only glTF 2.x static models are supported by the decode worker."), (e.extensionsRequired?.length || e.extensionsUsed?.length) && g("glTF extensions are not supported by the decode worker."), e.animations?.length && g("Animated glTF models must use the regular loader."), e.skins?.length && g("Skinned glTF models must use the regular loader."), e.cameras?.length && g("glTF cameras must use the regular loader."), B(e);
   for (const t of e.accessors ?? [])
     t.sparse && g("Sparse glTF accessors must use the regular loader."), t.bufferView === void 0 && g("Accessors without a bufferView must use the regular loader."), ["SCALAR", "VEC2", "VEC3", "VEC4"].includes(t.type) || g(`Accessor type ${t.type} must use the regular loader.`), [5120, 5121, 5122, 5123, 5125, 5126].includes(t.componentType) || g(`Accessor component type ${t.componentType} must use the regular loader.`);
   for (const t of e.bufferViews ?? [])
@@ -97,8 +89,8 @@ function I(e) {
   for (const t of e.nodes ?? [])
     (t.skin !== void 0 || t.weights?.length || t.camera !== void 0) && g("Skinned, morphed, or camera glTF nodes must use the regular loader."), t.extensions && Object.keys(t.extensions).length > 0 && g("Extended glTF nodes must use the regular loader.");
   for (const t of e.meshes ?? [])
-    for (const s of t.primitives)
-      (s.mode ?? 4) !== 4 && g("Only triangle glTF primitives are supported."), s.targets?.length && g("Morph targets must use the regular loader."), s.extensions && Object.keys(s.extensions).length > 0 && g("Extended glTF primitives must use the regular loader.");
+    for (const n of t.primitives)
+      (n.mode ?? 4) !== 4 && g("Only triangle glTF primitives are supported."), n.targets?.length && g("Morph targets must use the regular loader."), n.extensions && Object.keys(n.extensions).length > 0 && g("Extended glTF primitives must use the regular loader.");
   for (const t of e.materials ?? [])
     t.extensions && Object.keys(t.extensions).length > 0 && g("Extended glTF materials must use the regular loader.");
   for (const t of e.textures ?? [])
@@ -107,233 +99,267 @@ function I(e) {
 function N(e, t) {
   return e.startsWith("data:") || e.startsWith("blob:") ? e : new URL(e, t).href;
 }
-async function _(e, t, s, o, i, n, l) {
-  const h = [...t], f = [];
-  for (const c of e.buffers ?? []) {
-    let r;
-    if (c.uri)
-      r = await T(
-        c.uri,
+async function _(e, t, n, s, a, i, l, d = []) {
+  const f = [...t], u = [];
+  for (const r of e.buffers ?? []) {
+    let o;
+    if (r.uri)
+      o = await T(
+        r.uri,
+        n,
         s,
-        o,
+        a,
         i,
-        n,
         l,
-        (a) => a.arrayBuffer()
+        d,
+        (c) => c.buffer
       );
     else {
-      const a = h.shift();
-      if (!a) throw new Error("glTF buffer is missing its GLB binary chunk.");
-      r = a;
+      const c = f.shift();
+      if (!c) throw new Error("glTF buffer is missing its GLB binary chunk.");
+      o = c;
     }
-    if (r.byteLength < c.byteLength)
-      throw new Error(`glTF buffer is truncated: expected ${c.byteLength}, received ${r.byteLength}.`);
-    f.push(r), Reflect.deleteProperty(c, "uri");
+    if (o.byteLength < r.byteLength)
+      throw new Error(`glTF buffer is truncated: expected ${r.byteLength}, received ${o.byteLength}.`);
+    u.push(o), Reflect.deleteProperty(r, "uri");
   }
-  return f;
+  return u;
 }
-function W(e, t, s, o) {
-  const i = e.bufferViews?.[s];
-  if (!i) throw new Error(`glTF image references missing bufferView ${s}.`);
-  const n = t[i.buffer];
-  if (!n) throw new Error(`glTF image references missing buffer ${i.buffer}.`);
-  const l = i.byteOffset ?? 0;
-  return new Blob([new Uint8Array(n, l, i.byteLength)], {
-    type: o ?? "application/octet-stream"
+function j(e, t, n, s) {
+  const a = e.bufferViews?.[n];
+  if (!a) throw new Error(`glTF image references missing bufferView ${n}.`);
+  const i = t[a.buffer];
+  if (!i) throw new Error(`glTF image references missing buffer ${a.buffer}.`);
+  const l = a.byteOffset ?? 0;
+  return new Blob([new Uint8Array(i, l, a.byteLength)], {
+    type: s ?? "application/octet-stream"
   });
 }
-async function j(e, t, s, o, i, n, l) {
-  const h = [], f = [];
+async function P(e, t, n, s, a, i, l, d = []) {
+  const f = [], u = [];
   try {
-    for (const c of e.images ?? []) {
-      let r;
-      if (c.uri)
-        r = await T(
-          c.uri,
+    for (const r of e.images ?? []) {
+      let o;
+      if (r.uri)
+        o = await T(
+          r.uri,
+          n,
           s,
-          o,
+          a,
           i,
-          n,
           l,
-          (u) => u.blob()
+          d,
+          (p) => new Blob([p.buffer], {
+            type: p.headers.get("content-type") ?? "application/octet-stream"
+          })
         );
-      else if (c.bufferView !== void 0)
-        r = W(e, t, c.bufferView, c.mimeType);
+      else if (r.bufferView !== void 0)
+        o = j(e, t, r.bufferView, r.mimeType);
       else
         throw new Error("glTF image is missing both uri and bufferView.");
-      if (n.aborted) throw n.reason ?? new DOMException("Aborted", "AbortError");
-      const a = await globalThis.crypto.subtle.digest("SHA-256", await r.arrayBuffer());
-      if (n.aborted) throw n.reason ?? new DOMException("Aborted", "AbortError");
-      const d = Array.from(new Uint8Array(a), (u) => u.toString(16).padStart(2, "0")).join("");
-      f.push(`${r.type}:${r.size}:${d}`), h.push(await M(r, { imageOrientation: "flipY" })), Reflect.deleteProperty(c, "uri");
+      if (i.aborted) throw i.reason ?? new DOMException("Aborted", "AbortError");
+      const c = await globalThis.crypto.subtle.digest("SHA-256", await o.arrayBuffer());
+      if (i.aborted) throw i.reason ?? new DOMException("Aborted", "AbortError");
+      const h = Array.from(new Uint8Array(c), (p) => p.toString(16).padStart(2, "0")).join("");
+      u.push(`${o.type}:${o.size}:${h}`), f.push(await U(o, { imageOrientation: "flipY" })), Reflect.deleteProperty(r, "uri");
     }
-    return { images: h, imageKeys: f };
-  } catch (c) {
-    throw h.forEach((r) => r.close()), c;
+    return { images: f, imageKeys: u };
+  } catch (r) {
+    throw f.forEach((o) => o.close()), r;
   }
 }
-async function P(e, t, s = {}, o = new AbortController().signal, i) {
-  const n = V(t), { document: l, binaryChunks: h } = G(n);
-  I(l);
-  const f = s.resourceBaseUrl ?? e, c = await _(
-    l,
-    h,
+async function A(e, t, n = {}, s = new AbortController().signal, a, i = []) {
+  const l = $(t), { document: d, binaryChunks: f } = I(l);
+  K(d);
+  const u = n.resourceBaseUrl ?? e, r = await _(
+    d,
     f,
+    u,
     e,
+    n,
     s,
-    o,
+    a,
     i
-  ), { images: r, imageKeys: a } = await j(
-    l,
-    c,
-    f,
+  ), { images: o, imageKeys: c } = await P(
+    d,
+    r,
+    u,
     e,
+    n,
     s,
-    o,
+    a,
     i
   );
   return {
-    protocolVersion: O,
+    protocolVersion: C,
     kind: "gltf-static",
     url: e,
-    document: l,
-    buffers: c,
-    images: r,
-    imageKeys: a
+    document: d,
+    buffers: r,
+    images: o,
+    imageKeys: c
   };
 }
-async function q(e, t = {}, s = new AbortController().signal, o) {
-  const i = await $(e, t, s);
-  return P(e, i, t, s, o);
+async function q(e, t = {}, n = new AbortController().signal, s) {
+  const a = O(e, t, n), i = [], l = await E(e, a);
+  l.fromCache && i.push({
+    url: e,
+    options: {
+      headers: a.headers,
+      credentials: a.credentials,
+      cacheKey: a.cacheKey
+    }
+  });
+  try {
+    return await A(
+      e,
+      l.buffer,
+      t,
+      n,
+      s,
+      i
+    );
+  } catch (d) {
+    if (n.aborted || d instanceof v || i.length === 0) throw d;
+    await Promise.all(i.map((u) => S(u.url, u.options)));
+    const f = await E(e, a);
+    return A(
+      e,
+      f.buffer,
+      t,
+      n,
+      s
+    );
+  }
 }
-function A(e) {
+function M(e) {
   return e instanceof Error ? { message: e.message, name: e.name, stack: e.stack } : { message: String(e) };
 }
 function z(e = globalThis) {
-  const t = [], s = /* @__PURE__ */ new Set();
-  let o = null, i = !1, n = !1;
-  const l = (r) => new Promise((a) => {
-    r.acknowledge = a;
-  }), h = (r, a) => {
-    for (const d of r.resources.values())
-      d.cleanup(), d.reject(a);
+  const t = [], n = /* @__PURE__ */ new Set();
+  let s = null, a = !1, i = !1;
+  const l = (r) => new Promise((o) => {
+    r.acknowledge = o;
+  }), d = (r, o) => {
+    for (const c of r.resources.values())
+      c.cleanup(), c.reject(o);
     r.resources.clear();
   }, f = (r) => ({
-    async resolve(a, d) {
-      if (d.aborted) throw d.reason ?? new DOMException("Aborted", "AbortError");
-      const u = r.nextResourceId++, m = await new Promise((p, b) => {
-        const x = () => {
-          r.resources.delete(u), b(d.reason ?? new DOMException("Aborted", "AbortError"));
-        }, y = () => d.removeEventListener("abort", x);
-        r.resources.set(u, {
+    async resolve(o, c) {
+      if (c.aborted) throw c.reason ?? new DOMException("Aborted", "AbortError");
+      const h = r.nextResourceId++, p = await new Promise((m, b) => {
+        const L = () => {
+          r.resources.delete(h), b(c.reason ?? new DOMException("Aborted", "AbortError"));
+        }, y = () => c.removeEventListener("abort", L);
+        r.resources.set(h, {
           resolve(w) {
-            y(), r.resources.delete(u), p(w);
+            y(), r.resources.delete(h), m(w);
           },
           reject(w) {
-            y(), r.resources.delete(u), b(w);
+            y(), r.resources.delete(h), b(w);
           },
           cleanup: y
-        }), d.addEventListener("abort", x, { once: !0 });
+        }), c.addEventListener("abort", L, { once: !0 });
         try {
-          e.postMessage({ type: "resolve-resource", id: r.id, resourceId: u, url: a });
+          e.postMessage({ type: "resolve-resource", id: r.id, resourceId: h, url: o });
         } catch (w) {
-          y(), r.resources.delete(u), b(w instanceof Error ? w : new Error(String(w)));
+          y(), r.resources.delete(h), b(w instanceof Error ? w : new Error(String(w)));
         }
       });
-      let v = !1;
+      let x = !1;
       return {
-        url: m,
-        complete(p) {
-          v || (v = !0, e.postMessage({
+        url: p,
+        complete(m) {
+          x || (x = !0, e.postMessage({
             type: "resource-complete",
             id: r.id,
-            resourceId: u,
-            ok: p === void 0,
-            error: p === void 0 ? void 0 : A(p)
+            resourceId: h,
+            ok: m === void 0,
+            error: m === void 0 ? void 0 : M(m)
           }));
         }
       };
     }
-  }), c = async () => {
-    if (!(i || n)) {
-      i = !0;
+  }), u = async () => {
+    if (!(a || i)) {
+      a = !0;
       try {
-        for (; !n && t.length > 0; ) {
+        for (; !i && t.length > 0; ) {
           const r = t.shift();
-          if (s.delete(r.id)) continue;
-          const a = {
+          if (n.delete(r.id)) continue;
+          const o = {
             id: r.id,
             controller: new AbortController(),
             nextResourceId: 1,
             resources: /* @__PURE__ */ new Map()
           };
-          o = a;
+          s = o;
           try {
-            const d = await q(
+            const c = await q(
               r.url,
               r.options,
-              a.controller.signal,
-              f(a)
+              o.controller.signal,
+              f(o)
             );
-            if (s.delete(r.id) || n) {
-              d.images.forEach((u) => u.close());
+            if (n.delete(r.id) || i) {
+              c.images.forEach((h) => h.close());
               continue;
             }
             try {
               e.postMessage(
-                { type: "decoded", id: r.id, packet: d },
-                F(d)
+                { type: "decoded", id: r.id, packet: c },
+                F(c)
               );
-            } catch (u) {
-              throw d.images.forEach((m) => m.close()), u;
+            } catch (h) {
+              throw c.images.forEach((p) => p.close()), h;
             }
-            await l(a);
-          } catch (d) {
-            const u = s.delete(r.id);
-            if (a.controller.signal.aborted || u || n) continue;
-            d instanceof L ? e.postMessage({ type: "unsupported", id: r.id, reason: d.message }) : e.postMessage({ type: "error", id: r.id, error: A(d) });
+            await l(o);
+          } catch (c) {
+            const h = n.delete(r.id);
+            if (o.controller.signal.aborted || h || i) continue;
+            c instanceof v ? e.postMessage({ type: "unsupported", id: r.id, reason: c.message }) : e.postMessage({ type: "error", id: r.id, error: M(c) });
           } finally {
-            h(a, new DOMException("Model decode request ended.", "AbortError")), s.delete(r.id), o === a && (o = null);
+            d(o, new DOMException("Model decode request ended.", "AbortError")), n.delete(r.id), s === o && (s = null);
           }
         }
       } finally {
-        i = !1, !n && t.length > 0 && c();
+        a = !1, !i && t.length > 0 && u();
       }
     }
   };
   e.addEventListener("message", (r) => {
-    const a = r.data;
-    if (a.type === "decode") {
-      if (n) return;
-      t.push(a), c();
+    const o = r.data;
+    if (o.type === "decode") {
+      if (i) return;
+      t.push(o), u();
       return;
     }
-    if (a.type === "cancel") {
-      s.add(a.id), o?.id === a.id && (o.controller.abort(), o.acknowledge?.());
+    if (o.type === "cancel") {
+      n.add(o.id), s?.id === o.id && (s.controller.abort(), s.acknowledge?.());
       return;
     }
-    if (a.type === "ack") {
-      o?.id === a.id && o.acknowledge?.();
+    if (o.type === "ack") {
+      s?.id === o.id && s.acknowledge?.();
       return;
     }
-    if (a.type === "resource-resolved") {
-      if (o?.id !== a.id) return;
-      const d = o.resources.get(a.resourceId);
-      if (!d) return;
-      if (a.url !== void 0)
-        d.resolve(a.url);
+    if (o.type === "resource-resolved") {
+      if (s?.id !== o.id) return;
+      const c = s.resources.get(o.resourceId);
+      if (!c) return;
+      if (o.url !== void 0)
+        c.resolve(o.url);
       else {
-        const u = new Error(a.error?.message ?? "Failed to resolve model resource URL.");
-        u.name = a.error?.name ?? "Error", u.stack = a.error?.stack, d.reject(u);
+        const h = new Error(o.error?.message ?? "Failed to resolve model resource URL.");
+        h.name = o.error?.name ?? "Error", h.stack = o.error?.stack, c.reject(h);
       }
       return;
     }
-    a.type === "dispose" && (n = !0, t.length = 0, o?.controller.abort(), o?.acknowledge?.(), e.postMessage({ type: "disposed" }), e.close());
+    o.type === "dispose" && (i = !0, t.length = 0, s?.controller.abort(), s?.acknowledge?.(), e.postMessage({ type: "disposed" }), e.close());
   });
 }
 export {
-  O as MODEL_DECODE_PROTOCOL_VERSION,
-  L as UnsupportedModelDecodeError,
+  C as MODEL_DECODE_PROTOCOL_VERSION,
+  v as UnsupportedModelDecodeError,
   z as installModelDecodeWorker,
-  S as validateDecodedGltfNodeGraph
+  B as validateDecodedGltfNodeGraph
 };

package/docs/api-objects.md

@@ -256,8 +256,10 @@ await myModel.loadAsync(parameters: ModelParameters)
 | 属性         | 类型      | 默认值 | 说明                                                                                    |
 | :----------- | :-------- | :----- | :-------------------------------------------------------------------------------------- |
 | `url`        | `string`  | —      | `.gltf` 或 `.glb` 文件的 URL。                                                          |
-| `cache`      | `boolean` | `true` | 启用内存缓存。若模型已加载过，则直接从内存中获取并克隆。                                |
-| `persistent` | `boolean` | `true` | 使用浏览器 Cache API 启用持久化磁盘缓存，适合较大的模型。                               |
+| `cache`      | `boolean` | `true` | 启用内存 LRU 缓存。若同一请求已加载，则直接从内存中获取并克隆；最多保留 32 项。          |
+| `persistent` | `boolean` | `true` | 使用浏览器 Cache API 持久化模型及外部 glTF 依赖；最多保留 64 项或 512 MiB。              |
+| `cacheMode`  | `string`  | —      | 覆盖持久化缓存策略：`no-store`、`reload`、`revalidate` 或 `force-cache`。                 |
+| `cacheKey`   | `string`  | —      | 为同一 URL 指定版本化缓存身份；适用于发布后 URL 不变的模型。                              |
 
 #### 缓存示例
 
@@ -273,8 +275,14 @@ model2.loadAsync({ url: 'model.glb', cache: false });
 // 完全禁用缓存
 const model3 = new Model();
 model3.loadAsync({ url: 'model.glb', cache: false, persistent: false });
+
+// 发布新模型但 URL 保持不变时，获取网络版本并更新该版本条目
+const model4 = new Model();
+model4.loadAsync({ url: 'model.glb', cacheMode: 'reload', cacheKey: '2026-09-02' });
 ```
 
+持久化缓存保留响应类型、验证器和真实字节长度。默认无服务端缓存指令的资源可复用 7 天；到期后优先使用 `ETag` / `Last-Modified` 条件验证，断网时可回退到已存在的非空缓存。`no-store` 不读取或写入持久化缓存；`reload` 强制网络请求并更新缓存；`revalidate` 即使缓存仍新鲜也会条件验证；`force-cache` 优先返回已有的非空缓存。`Cache-Control: no-store/private` 与 `Vary: Cookie/*` 响应不会写入缓存。空缓存、截断的外部 buffer、解析失败或缓存命中时未解码的贴图会删除相关缓存资源并重新请求一次。请求头、credentials 模式和 `cacheKey` 共同参与缓存身份，避免不同授权请求或版本共用同一条目。
+
 ### 动画
 
 `Model` 在加载含内置动画的模型（如 glTF/FBX）后，会自动初始化 `AnimationMixer` 并收集 `AnimationClip`。
@@ -372,6 +380,7 @@ myModel.setMaterial(new MeshStandardMaterial({ color: 0xff0000 }));
 
 - `Model.clearMemoryCache()`：清除运行时内存缓存。
 - `await Model.clearPersistentCache()`：完全清除浏览器中 `u-space` 模型的持久化缓存。
+- `await ModelLoaderManager.deletePersistentCache(url, { cacheKey })`：仅删除指定 URL 与版本身份的持久化缓存。
 
 ## 网格
 

package/docs/changelog.md

@@ -2,6 +2,13 @@
 
 ## 未发布
 
+## 0.0.33
+
+### 修复与优化
+
+- **模型持久化缓存**：主线程与 decode Worker 统一使用带版本、容量和响应元数据的 Cache Storage 策略，缓存项记录真实 `Content-Length`；模型及外部 glTF buffer/贴图支持过期与 `ETag` / `Last-Modified` 条件验证、离线旧缓存、授权请求隔离和损坏缓存单次自愈。调用方可通过 `cacheMode` 跳过、刷新、重验或强制读取缓存，通过 `cacheKey` 隔离同一 URL 的模型版本并精确删除目标缓存。对象内存缓存改为 32 项 LRU，磁盘缓存限制为 64 项或 512 MiB，并遵循 `no-store/private` 与敏感 `Vary` 响应。
+- **UManager 示例**：目标对象不存在、不是 Mesh 或使用多材质时，示例不再直接写入材质属性而导致页面报错。
+
 ## 0.0.32
 
 ### 修复与优化

package/docs/examples-guide.md

@@ -4,7 +4,7 @@
 
 ## 运行方式与版本
 
-示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.32`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.32` 作为直接托管 `examples/` 时的 fallback。
+示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.33`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.33` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -28,7 +28,7 @@
 
 - 使用全局 `Model` 类通过 `Model.prototype.loadAsync()` 异步加载 `.glb` 文件。
 - 理解 `cache: true`（将模型节点保留在内存中，可实现即时克隆/实例化）。
-- 理解 `persistent: true`（使用 Service Worker / Cache Storage API 对实际网络请求数据进行持久化缓存）。
+- 理解 `persistent: true`（使用 Cache Storage API 持久化模型及外部 glTF 依赖，无需注册 Service Worker）。
 - 演示如何将这些异步加载的资源安全地注册到 `viewer.objectManager`。
 - 提供通过 `Model.clearMemoryCache()` 和 `Model.clearPersistentCache()` 手动清除缓存的示例。