u-space 0.0.31 → 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-effects.md

@@ -1,6 +1,6 @@
 # Effects API
 
-`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮、呼吸等材质特效，`TSLEffects` 用于生成动态颜色节点模式。
+`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮、呼吸等材质特效，`TSLEffects` 用于生成动态颜色节点模式和可组合的 Outline 输出效果。
 
 ## `MaterialEffects`
 
@@ -123,7 +123,71 @@ await MaterialEffects.fadeIn(myModel, { duration: 500 });
 
 ## `TSLEffects`
 
-静态工厂类，返回 TSL 颜色节点。将返回值赋给 `NodeMaterial` 的 `material.colorNode` 即可应用动态着色器特效。持续动画需要 `viewer.frameloop = 'always'`。
+静态工厂类。`flow()`、`breathe()` 和 `fluid()` 返回可赋给 `NodeMaterial.colorNode` 的 TSL 颜色节点；`outline()` 返回接入 `RenderPipeline` 的输出效果。持续动画需要 `viewer.frameloop = 'always'`。
+
+### `TSLEffects.outline(options?)`
+
+创建基于 Three.js `OutlineNode` 的屏幕空间描边效果。它不会修改对象材质，而是通过 `RenderPipeline.addOutputEffect()` 叠加在默认渲染结果上，因此可以与内置 Bloom、SSGI、SSR 以及其他 output effects 组合。
+
+```typescript
+import { TSLEffects } from 'u-space';
+
+const outline = TSLEffects.outline({
+  selectedObjects: [model],
+  edgeStrength: 3,
+  edgeThickness: 1.5,
+  edgeGlow: 0,
+  visibleEdgeColor: 0x00e5ff,
+  hiddenEdgeColor: 0xff4d6d,
+  downSampleRatio: 2,
+  instanceBoundsProxy: true,
+  instanceBoundsPadding: 0.05,
+});
+
+viewer.renderPipeline.addOutputEffect(outline);
+
+// 替换当前描边对象，不需要重建后处理链。
+outline.setSelectedObjects([anotherObject]);
+
+// 运行时更新样式与 InstanceObject bounds proxy 参数。
+outline.update({ edgeStrength: 4, edgeGlow: 0.25 });
+viewer.render();
+
+// 销毁前先从 RenderPipeline 移除。
+viewer.renderPipeline.removeOutputEffect(outline);
+outline.dispose();
+```
+
+#### `TSLOutlineOptions`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `selectedObjects` | `readonly Object3D[]` | `[]` | 初始描边对象。普通 Mesh、Group 与核心 `InstanceObject` 均可传入。 |
+| `edgeStrength` | `number` | `3` | 边缘颜色强度。 |
+| `edgeThickness` | `number` | `1` | 边缘厚度。 |
+| `edgeGlow` | `number` | `0` | 描边向外扩散的发光强度。 |
+| `visibleEdgeColor` | `ColorRepresentation` | `0xffffff` | 可见边缘颜色。 |
+| `hiddenEdgeColor` | `ColorRepresentation` | `0x4e3636` | 被遮挡边缘颜色。 |
+| `downSampleRatio` | `number` | `2` | Outline pass 降采样比例；非有限值或 `<= 0` 时恢复为 `2`。值越大成本越低，但边缘精度也越低。 |
+| `instanceBoundsProxy` | `boolean` | `true` | `InstanceObject` 没有可直接描边的渲染子树时，是否用世界包围盒代理生成轮廓。 |
+| `instanceBoundsPadding` | `number` | `0` | bounds proxy 每个方向额外扩张的世界单位。 |
+| `instanceBoundsMinSize` | `number` | `0.001` | bounds proxy 每个轴向的最小尺寸，避免退化包围盒无法描边。 |
+
+#### 返回的 `TSLOutlineEffect`
+
+| 成员 | 说明 |
+| :--- | :--- |
+| `selectedObjects` | 当前逻辑选择对象的只读快照。 |
+| `outlineNode` | 当前内部 `OutlineNode`；在 RenderPipeline 首次构建前为 `null`，Scene 或 Camera 变化后可能被替换。 |
+| `setSelectedObjects(objects)` | 替换当前选择并返回自身，便于链式调用。空数组会清除描边。 |
+| `update(options)` | 更新除 `selectedObjects` 外的全部样式和 bounds proxy 选项，并返回自身。 |
+| `dispose()` | 释放内部 OutlineNode、代理 Geometry/Material 和 dirty 订阅。调用前应先 `removeOutputEffect()`。 |
+
+对于 `InstanceObject`，效果会优先描边 `getInstanceRenderObject()` 返回的可渲染对象；如果逻辑对象自身包含 Mesh/Sprite，则直接使用该对象；只有两者都不可用时才根据 `getInstanceBoundingBox()` 创建不可见 bounds proxy。代理会监听 `onInstanceRenderDirty()`，在实例显隐、变换或包围盒变化后同步，而且不会参与拾取、颜色输出或阴影。
+
+> 如果业务设置了自定义 `viewer.renderPipeline.setOutputComposer()`，RenderPipeline 会按自定义 composer 语义跳过所有 output effects，Outline 也不会显示。更新选择或参数后，`frameloop = 'demand'` 的 Viewer 需要调用 `viewer.render()` 或 `viewer.invalidate()` 请求新帧。
+
+[在线示例](https://u-space-phi.vercel.app/examples/test_outline.html)
 
 ### `TSLEffects.flow(parameters?)`