modelstage 0.0.0-stage → 0.5.24

package/src/web/plugin/unpack-worker.js

@@ -0,0 +1,185 @@
+// src/web/plugin/unpack-worker.js —— 资源包解包 Worker（classic worker，不是 module worker）
+//
+// 为什么是 classic：插件 lib 全是 **classic script**，它们靠 `globalThis.__ULB__` 逐级挂载、
+//   靠 `plugin.json` 的 `files[]` **加载顺序**建立依赖。module worker 的 import 语义与此不符，
+//   而 classic worker 的 `importScripts()` 天然按调用顺序同步执行 —— 与浏览器里注入 <script> 等价。
+//
+// 为什么搬进 worker：LZMA 解压实测 300~620ms/MB（解压后），8.28MB 的包要 3.9 秒。
+//   这段是**纯同步 CPU**，留在主线程就是 4 秒白屏冻死；放进 worker 后主线程照常渲染。
+//
+// 消息协议（只有 4 种，刻意保持最小）：
+//   ← {t:'init',    base, files[]}          主线程告诉它插件目录与加载顺序
+//   → {t:'ready'}                             lib 载好，provider 已捕获
+//   → {t:'progress', phase, detail}          进度（块表 / 开始解压 / 完成）
+//   ← {t:'unpack',  id, file:{rootId,rel}, bytes}
+//   → {t:'done',    id, res:{prefix,entry,files:[[path, Blob|Uint8Array, type]]}, ms}
+//   → {t:'fail',    id, code, message}
+//
+// 硬约束：
+//   · 产物出口**两种形态**：插件交付的 Blob 原样透传（= 零拷贝，Blob 过通道是引用语义）；
+//     非 Blob（LZMA 中间结果是普通 Array / TypedArray）才归一成 Uint8Array，并带上 MIME type
+//     供主线程按需重建 Blob。Array 过通道还是 Array，所以那一路必须先归一，否则主线程按字节处理会错位。
+//   · 只有 Uint8Array 那一路进 transfer 列表（transferable 只认 ArrayBuffer 系；Blob 不能也不需 transfer）
+
+// 插件 index.js 顶层读 `window.SpineViewerPlugins`（懒获取宿主面）。
+// worker 里没有 window ⇒ 用 self 兜上，再挂一个**宽容的 stub**：只捕获 register，
+// 其余成员一律 no-op（插件可能调用 log/emit 等非必需能力）。
+self.window = self;
+
+let captured = null;      // 插件 register 进来的 provider 记录
+let loaded = false;       // lib 是否已载入
+
+function installHostStub() {
+  const noop = () => {};
+  const stub = {
+    // 唯一的真实现：捕获插件注册（我们要的就是它的 resolve）
+    register(rec) { captured = rec; return true; },
+    // worker 里没有文件系统/网络：插件若真要额外取文件，明确抛错而不是静默返回空
+    fetchFile() { throw new Error('unpack-worker：worker 内不提供文件读取（字节随消息传入）'); },
+    // 进度回调给主线程（插件若有 post 通道就顺手用上）
+    post(msg) { self.postMessage(msg); },
+  };
+  self.SpineViewerPlugins = new Proxy(stub, {
+    get(target, key) { return key in target ? target[key] : noop; },
+  });
+}
+
+/** 把 Array / ArrayBuffer / TypedArray / **Blob** 统一成 Uint8Array（跨线程前必须做） */
+async function toU8(v) {
+  if (v instanceof Uint8Array) return v;
+  if (v instanceof ArrayBuffer) return new Uint8Array(v);
+  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  if (Array.isArray(v)) return Uint8Array.from(v);   // ← LZMA 的普通 Array 走这条
+  // 插件产物实际是 **Blob**（vfs.register 只收 Blob/字符串），必须读出字节再传
+  if (v && typeof v.arrayBuffer === 'function') return new Uint8Array(await v.arrayBuffer());
+  return new Uint8Array(0);
+}
+
+// 先挂一次（函数声明提升，此处赋值即可）；载完 lib 后 init 分支里会**再挂一次**（见那里的说明）
+self.onmessage = handleMessage;
+
+async function handleMessage(ev) {
+  const msg = ev.data || {};
+  try {
+    if (msg.t === 'init') {
+      installHostStub();
+      // 按 plugin.json 的 files[] 顺序逐条载入（顺序即依赖，不许自己排）
+      for (const rel of msg.files || []) importScripts(new URL(rel, msg.base).href);
+      loaded = true;
+      // ⚠️ 必须**重新挂 onmessage**：lib/lzma-d-min.js 是上游的 worker 版 IIFE，它检测到
+      //   "有 onmessage、没有 window.document" 就把自己的 worker 协议处理器赋给 onmessage
+      //   （源文件末尾那段自举）。不重挂，后续 unpack 消息会被它吃掉 ⇒ 表现成
+      //   "ready 之后再无消息、解包永远不返回"（这个坑实测踩过一次）。
+      self.onmessage = handleMessage;
+      self.postMessage({ t: 'ready', hasProvider: !!captured, providerId: captured && captured.id });
+      return;
+    }
+
+    if (msg.t === 'unpack') {
+      if (!loaded || !captured || typeof captured.resolve !== 'function') {
+        self.postMessage({ t: 'fail', id: msg.id, code: 'ULB_WORKER_NO_PROVIDER', message: 'worker 里没有可用的 provider.resolve（插件注册失败）' });
+        return;
+      }
+      // 取字节的两种方式（方向④）：
+      //   · msg.bytes 已给 ⇒ 直接用（调用方本来就读过了）
+      //   · 只有 msg.url ⇒ **worker 自己拉**。这一步是本轮的核心：主线程不再把 19MB 读进来
+      //     再 postMessage 拷一遍（实测那一段 3918ms/19.3MB，是首帧最大的单笔开销）。
+      //     fetch 与页面同源，自动带 cookie；失败要如实回 fail，让主线程按老规矩回落。
+      let bytes;
+      if (msg.bytes) {
+        bytes = toU8(msg.bytes);
+      } else if (msg.url) {
+        const tf = Date.now();
+        let res;
+        try {
+          res = await fetch(msg.url, { credentials: 'same-origin' });
+        } catch (e) {
+          self.postMessage({ t: 'fail', id: msg.id, code: 'ULB_WORKER_FETCH', message: `worker 拉包失败：${(e && e.message) || e}` });
+          return;
+        }
+        if (!res || !res.ok) {
+          self.postMessage({ t: 'fail', id: msg.id, code: 'ULB_WORKER_FETCH', message: `worker 拉包失败：HTTP ${res ? res.status : '?'}` });
+          return;
+        }
+        bytes = toU8(await res.arrayBuffer());
+        self.postMessage({
+          t: 'progress', id: msg.id, phase: 'fetched',
+          detail: { bytes: bytes.byteLength, fetchMs: Date.now() - tf },
+        });
+      } else {
+        self.postMessage({ t: 'fail', id: msg.id, code: 'ULB_WORKER_NO_BYTES', message: '既没有 bytes 也没有 url' });
+        return;
+      }
+      const t0 = Date.now();
+
+      // 注意：这里**不调 captured.canHandle**。
+      //   canHandle 走 bundleProbe.run → unityfs.parse（完整解压）+ serialized 解析；
+      //   实测把它放进 worker 会长时间无响应（36 秒未返回，原因未定位），所以回退。
+      //   类型判定改由「主线程调用 canHandle 时不传 bytes」解耦：插件对无 bytes 的调用直接返回 true
+      //   （插件 index.js 的 canHandle 开头 `if (!bytes) return true`），主线程因此零解析成本；
+      //   真正的类型判定交给下面 resolve 的成败 —— 认不了就抛错，由主线程换下一个候选。
+
+      // 进度①：读块表（`blocksSummary` 只解 blocksInfo、不碰数据块，实测 ~5ms）
+      try {
+        const ufs = self.__ULB__ && self.__ULB__.unityfs;
+        if (ufs && typeof ufs.blocksSummary === 'function') {
+          const s = ufs.blocksSummary(bytes);
+          const head = ufs.readHeader(bytes);
+          const algoNames = { 0: 'none', 1: 'LZMA', 2: 'LZ4', 3: 'LZ4HC', 4: 'LZHAM' };
+          const algo = [...new Set(head.blocks.map((b) => algoNames[b.flags & 0x3f] || '?'))].join('+');
+          self.postMessage({
+            t: 'progress', id: msg.id, phase: 'blocks',
+            detail: {
+              algo,
+              blocks: s.blockCount,
+              decompressedMB: +(s.decompressedBytes / 1048576).toFixed(2),
+              // 经验系数：LZMA 约 470ms/MB（实测 2.76~33.4MB 区间 300~620），用于给用户一个量级预期
+              estimateMs: algo.includes('LZMA') ? Math.round((s.decompressedBytes / 1048576) * 470) : 0,
+            },
+          });
+        }
+      } catch { /* 读块表失败不影响解压，静默跳过 */ }
+
+      // 进度②：开始解压（块级进度钩不到 —— 那在插件内部循环里，本轮不改插件实现）
+      self.postMessage({ t: 'progress', id: msg.id, phase: 'unpacking' });
+
+      const res = await captured.resolve({ ...msg.file, bytes, host: self.SpineViewerPlugins });
+      if (!res || typeof res !== 'object' || !res.files) {
+        self.postMessage({ t: 'fail', id: msg.id, code: 'ULB_WORKER_BAD_RESULT', message: 'resolve 没有返回 files' });
+        return;
+      }
+
+      // 出口归一：**Blob 原样透传，其余才转 Uint8Array**
+      //   为什么不再一律转 Uint8Array：插件产物本来就是 Blob（vfs.register 只收 Blob 或字符串），
+      //   而 Blob → Uint8Array 要整份读出来（44MB 级的包就是一次全量复制），
+      //   主线程收到后再 new Blob([u8]) 又复制一次 —— 一进一出两次都是白做的。
+      //   Blob 过 postMessage 是**引用/快照语义**（不复制字节），原样传就等于零拷贝到主线程。
+      const files = [];
+      const transfer = [];
+      const src = res.files instanceof Map ? res.files : Object.entries(res.files);
+      for (const [path, val] of src) {
+        const type = (val && typeof val.type === 'string') ? val.type : '';
+        if (typeof Blob !== 'undefined' && val instanceof Blob) {
+          // 零拷贝：不读、不转，也不能进 transfer 列表（transferable 只认 ArrayBuffer 系）
+          files.push([path, val, type]);
+          continue;
+        }
+        const u8 = await toU8(val);
+        files.push([path, u8, type]);
+        if (u8.buffer instanceof ArrayBuffer) transfer.push(u8.buffer);
+      }
+      self.postMessage({
+        t: 'done', id: msg.id,
+        res: { prefix: res.prefix, entry: res.entry, files },
+        ms: Date.now() - t0,
+      }, transfer);
+      return;
+    }
+  } catch (e) {
+    self.postMessage({
+      t: 'fail', id: msg.id || 0,
+      code: (e && e.code) || 'ULB_WORKER_FAIL',
+      message: String((e && e.message) || e).slice(0, 300),
+    });
+  }
+};

package/src/web/render/camera/constants.js

@@ -0,0 +1,60 @@
+// render/camera/constants.js —— 相机唯一常量来源
+//
+// 为什么单独放一个模块：缩放范围、档位步长、fit 边距这三个数**只允许在这里出现**。
+//   任何逻辑文件里再写裸数字（0.125 / 16 / 0.1 / 0.05）都视为违规 ——
+//   调范围时只改这一处，两套渲染（Spine / Live2D）才不会各自漂移。
+// 数值来源：引擎 `SpineEngine.SCALE_MIN/SCALE_MAX/FIT_MARGIN`（= 0.125 / 16 / 0.05），
+//   档位步长 0.1 对应引擎 `userScale *= (1 + t*0.1)` 的一档 ±10%。
+
+// 面 → 相机覆盖值的键由元数据表给（不在这里写 kind 二分）
+import { byKind } from '../surfaces.js';
+
+/** 相机通用参数（Spine 与 Live2D 共用同一份） */
+export const CAMERA = Object.freeze({
+  /** 最小缩放（12.5%） */
+  MIN: 0.125,
+  /** 最大缩放（1600%） */
+  MAX: 16,
+  /** 一档步长：scale *= 1 + dir * STEP（±10%） */
+  STEP: 0.1,
+  /** fit 边距：最终系数 = (1 - FIT_MARGIN) */
+  FIT_MARGIN: 0.05,
+});
+
+/**
+ * Live2D 专用覆盖值（默认空 ⇒ 与 CAMERA 完全一致）。
+ * 将来若需要为保护画质而限制 Live2D 的放大范围，**只在这里覆盖**，不改任何逻辑。
+ * 例：{ MAX: 8 } 表示 Live2D 最多 8×，其余仍用 CAMERA。
+ */
+export const LIVE2D_OVERRIDE = Object.freeze({});
+
+/**
+ * 主体包围盒排除名单（部件名不区分大小写、按子串匹配）。
+ * 用途：Live2D 没有骨骼/插槽语义，靠部件名剔除场景板与特效，逼近 Spine 的 `subject` 语义。
+ */
+export const SUBJECT_EXCLUDE = Object.freeze(['bg', 'back', 'background', 'effect', 'mask', 'scene', 'kazari']);
+
+/**
+ * 各面的相机覆盖值表（键 = 面元数据表的 cameraKind）。
+ * 加新面时若要限制它的缩放范围，在这里加一个键 —— 不必改 limitsFor 的判断。
+ */
+const CAMERA_OVERRIDES = Object.freeze({
+  live2d: LIVE2D_OVERRIDE,
+});
+
+/**
+ * 取某个后端实际生效的 limits（CAMERA 叠加该面的覆盖值）。
+ *
+ * 覆盖关系查 render/surfaces.js 的 cameraKind，不再写 `kind === 'live2d'`：
+ *   未知 kind ⇒ 不叠加覆盖、直接用通用值。这里刻意**不抛错**：
+ *   相机范围有通用兜底，不像画布/面模式那样写错就错乱，所以"查不到覆盖表键"等同于"这个面没有特殊限制"。
+ * @param {'spine'|'live2d'} kind
+ * @returns {{min: number, max: number}}
+ */
+export function limitsFor(kind) {
+  const meta = byKind(kind);
+  const override = meta ? (CAMERA_OVERRIDES[meta.cameraKind] || null) : null;
+  const min = override && typeof override.MIN === 'number' ? override.MIN : CAMERA.MIN;
+  const max = override && typeof override.MAX === 'number' ? override.MAX : CAMERA.MAX;
+  return { min, max };
+}

package/src/web/render/camera/index.js

@@ -0,0 +1,123 @@
+// render/camera/index.js —— 相机统一入口
+//
+// 设计：外部只看到一套语义（档位 / 范围 / 锚点 / 复位 / 平移单位），差异全部收进 backend。
+//   · 共用（本文件唯一实现）：`scale *= (1 + dir*STEP)`、clamp 到 limits、复位归 1、节流入口
+//   · backend 只负责「读/写状态 + 怎么落地」：
+//       getScale() / setScale(v) / pan(dx, dy) / resetView(keepScale)
+//   · fit 是能力差异（Spine 有三种模式，Live2D 只有主体包围盒），因此不进本文件；
+//     由 backend 自己暴露 `fit?()`，渲染器在需要时调用。
+//
+// 数值一律取自 `./constants.js`（本文件不出现裸数字）。
+
+import { CAMERA, limitsFor } from './constants.js';
+
+/**
+ * 创建统一相机。
+ *
+ * @param {{
+ *   kind?: 'spine'|'live2d',
+ *   backend: {
+ *     getScale: () => number|null,
+ *     setScale: (v: number) => void,
+ *     pan: (dx: number, dy: number) => void,
+ *     resetView: (keepScale: boolean) => void,
+ *   },
+ *   log?: (message: string, level?: 'info'|'warn') => void,
+ * }} options
+ */
+export function createCamera({ kind = 'spine', backend, log } = {}) {
+  if (!backend || typeof backend.getScale !== 'function' || typeof backend.setScale !== 'function') {
+    throw new Error('createCamera: backend 需要提供 getScale/setScale');
+  }
+  const limits = limitsFor(kind);
+
+  /** 统一日志出口（缺省静默） */
+  let logger = typeof log === 'function' ? log : null;
+  function note(message, level = 'info') {
+    if (logger) {
+      try { logger(message, level); } catch { /* 日志失败不影响相机 */ }
+    }
+  }
+
+  /** 夹取到 limits（唯一钳制点） */
+  function clamp(v) {
+    const n = Number(v);
+    if (!Number.isFinite(n)) return null;
+    return Math.min(limits.max, Math.max(limits.min, n));
+  }
+
+  /** 读当前缩放（backend 是唯一真相） */
+  function scale() {
+    try {
+      const v = backend.getScale();
+      return Number.isFinite(v) ? v : null;
+    } catch { return null; }
+  }
+
+  /** 写缩放（夹取后交给 backend） */
+  function zoomTo(value) {
+    const v = clamp(value);
+    if (v === null) return scale();
+    try { backend.setScale(v); } catch (err) { note(`setScale 失败：${err && err.message}`, 'warn'); }
+    return scale();
+  }
+
+  /**
+   * 缩放步进（与引擎 `userScale *= 1 + t*STEP` 完全一致）。
+   *
+   * `dir` 的**符号给方向、绝对值给档数**：交互层按帧合并滚轮事件时会把一次帧内的
+   *   多个 tick 累加成一个数传进来（如 +7），若只取符号就会把幅度丢掉——用户快速滚轮
+   *   反而只缩一档，手感明显回退。传 ±1 时行为与原来逐字一致。
+   * @param {number} dir 方向 + 档数：>0 放大、<0 缩小（|dir| 档）
+   */
+  function zoomStep(dir) {
+    const cur = scale();
+    if (!Number.isFinite(cur)) return null;
+    const sign = dir > 0 ? 1 : dir < 0 ? -1 : 0;
+    if (sign === 0) return cur;
+    const steps = Math.max(1, Math.trunc(Math.abs(Number(dir) || 1)));
+    const next = clamp(cur * (1 + sign * CAMERA.STEP) ** steps);
+    if (next === null) return cur;
+    try { backend.setScale(next); } catch (err) { note(`setScale 失败：${err && err.message}`, 'warn'); }
+    note(`zoomStep(${sign > 0 ? '+' : '-'}${steps}) ${cur.toFixed(4)} → ${next.toFixed(4)}（范围 ${limits.min}~${limits.max}）`);
+    return scale();
+  }
+
+  /**
+   * 平移：参数单位固定为「屏幕像素增量」，内部乘子由 backend 决定。
+   * @param {number} dx
+   * @param {number} dy
+   */
+  function panBy(dx, dy) {
+    try { backend.pan(Number(dx) || 0, Number(dy) || 0); } catch (err) { note(`pan 失败：${err && err.message}`, 'warn'); }
+    return null;
+  }
+
+  /**
+   * 复位：先归 1（keepScale=false），再让 backend 重新适配。
+   * @param {{keepScale?: boolean}} [opts]
+   */
+  function reset(opts = {}) {
+    const keep = !!opts.keepScale;
+    if (!keep) {
+      try { backend.setScale(1); } catch { /* 忽略 */ }
+    }
+    try { backend.resetView(keep); } catch (err) { note(`resetView 失败：${err && err.message}`, 'warn'); }
+    note(`reset（keepScale=${keep}）→ scale=${scale()}`);
+    return scale();
+  }
+
+  /** 设置日志出口（交互层在 boot 时挂上） */
+  function setLogger(fn) {
+    logger = typeof fn === 'function' ? fn : null;
+  }
+
+  /** 只读信息（排查/断言用） */
+  function info() {
+    return { kind, limits: { ...limits }, step: CAMERA.STEP, scale: scale() };
+  }
+
+  return { kind, zoomStep, zoomTo, panBy, reset, scale, setLogger, note, info };
+}
+
+export default createCamera;

package/src/web/render/camera/spine.js

@@ -0,0 +1,124 @@
+// render/camera/spine.js —— 相机统一入口（Spine / Live2D 共用，全部委托引擎原生方法）
+//
+// 设计约束（重要）：
+//   1. 本文件**不做任何坐标换算**：没有 ppw、没有 ×2、没有锚点公式、没有 exp 曲线。
+//      缩放档位、像素倍率、flip、Live2D 委托全部由引擎内部处理：
+//        engine.applyZoom(t)        userScale *= (1 + t*0.1)，clamp [SCALE_MIN, SCALE_MAX]
+//        engine.setCameraZoom(s)    直接设 userScale
+//        engine.applyPan(dx, dy)    dx/dy 是屏幕像素差值，方向为「内容跟随手指」
+//        engine.resetCamera()       重新 fit（受 fitMode 影响）
+//        engine.getCameraZoom()     只读当前 userScale
+//   2. 本文件**不判断 l2dActive()**：引擎三个方法开头已有 L2D 分支并委托 bridge，
+//      在这里再写一份就会出现两套真相。
+//   3. 所有动作都输出一条 CAMERA 日志（含输入侧），供真机操作时逐条核对。
+
+/**
+ * @param {{getEngine: () => any}} options getEngine 每次调用时取当前引擎（MSAA 重建后引擎实例会换）
+ */
+import { CAMERA, limitsFor } from './constants.js';
+
+export function createStageCamera({ getEngine } = {}) {
+  /** 日志输出函数（由宿主注入，缺省静默） */
+  let logger = null;
+
+  /** 取可用引擎；没有相机能力时返回 null，调用方据此跳过 */
+  function engineOf() {
+    const engine = typeof getEngine === 'function' ? getEngine() : null;
+    return engine && typeof engine.getCameraZoom === 'function' ? engine : null;
+  }
+
+  /** 写一条 CAMERA 日志（日志失败不影响相机） */
+  /** panBy 逐帧日志的节流时间戳（毫秒） */
+  let lastPanLogAt = 0;
+
+  function emit(message, data) {
+    if (typeof logger !== 'function') return;
+    try { logger(message, data); } catch { /* 忽略 */ }
+  }
+
+  /** 读数包装：拿不到引擎时返回 null（而不是抛错） */
+  function readScale(engine) {
+    try { return Number(engine.getCameraZoom()); } catch { return null; }
+  }
+
+  const camera = {
+    /** 缩放一档。dir ：滚轮向下 = -1，其余 = +1 */
+    zoomStep(dir) {
+      const engine = engineOf();
+      if (!engine) return null;
+      const before = readScale(engine);
+      const lim = limitsFor('spine');
+      // 唯一钳制点：先把目标值夹进范围，再交给引擎（引擎本身不再夹）
+      const target = Math.max(lim.min, Math.min(lim.max, (before == null ? 1 : before) * (1 + (dir > 0 ? 1 : -1) * CAMERA.STEP)));
+      try { engine.setCameraZoom(target); } catch { return before; }
+      const after = readScale(engine);
+      emit(`zoomStep(${dir > 0 ? '+1' : '-1'}) → userScale ${before} → ${after}`, { before, after });
+      return after;
+    },
+
+    /** 缩放到指定 userScale（捏合：起始 userScale × 距离比） */
+    zoomTo(scale) {
+      const engine = engineOf();
+      if (!engine || !Number.isFinite(scale)) return null;
+      const before = readScale(engine);
+      const lim = limitsFor('spine');
+      try { engine.setCameraZoom(Math.max(lim.min, Math.min(lim.max, scale))); } catch { return before; }
+      const after = readScale(engine);
+      emit(`zoomTo(${scale}) → userScale ${before} → ${after}`, { before, after });
+      return after;
+    },
+
+    /** 平移。dx/dy 是屏幕像素差值，原样交给引擎（倍率与 flip 由引擎处理） */
+    panBy(dx, dy) {
+      const engine = engineOf();
+      if (!engine || !Number.isFinite(dx) || !Number.isFinite(dy)) return null;
+      let posBefore = null;
+      try {
+        const cam = engine.camera;
+        if (cam && cam.position) posBefore = { x: cam.position.x, y: cam.position.y };
+      } catch { /* 读不到位置不影响平移 */ }
+      try { engine.applyPan(dx, dy); } catch { return posBefore; }
+      let posAfter = null;
+      try {
+        const cam = engine.camera;
+        if (cam && cam.position) posAfter = { x: cam.position.x, y: cam.position.y };
+      } catch { /* 同上 */ }
+      // 逐帧节流：一次拖动会调用几十次，全记会把日志刷满；这里 400ms 最多留一条过程样本，
+      //   整体位移由交互层抬手时汇总（drag total）。
+      const now = Date.now();
+      if (now - lastPanLogAt >= 400) {
+        lastPanLogAt = now;
+        emit(`panBy(${dx > 0 ? '+' : ''}${dx}, ${dy > 0 ? '+' : ''}${dy}) → position ${posBefore ? `(${posBefore.x.toFixed(2)},${posBefore.y.toFixed(2)})` : '?'} → ${posAfter ? `(${posAfter.x.toFixed(2)},${posAfter.y.toFixed(2)})` : '?'}`, { dx, dy, posBefore, posAfter });
+      }
+      return posAfter;
+    },
+
+    /** 视图复位：交给引擎重新 fit */
+    reset() {
+      const engine = engineOf();
+      if (!engine || typeof engine.resetCamera !== 'function') return null;
+      try { engine.resetCamera(); } catch { return readScale(engine); }
+      const scale = readScale(engine);
+      emit(`reset() → userScale ${scale}, fit 完成`, { scale });
+      return scale;
+    },
+
+    /** 只读当前 userScale */
+    scale() {
+      const engine = engineOf();
+      return engine ? readScale(engine) : null;
+    },
+
+    /** 写一条 CAMERA 日志（供交互层汇报输入侧动作，与上面同一路通道） */
+    note(message, data) {
+      emit(message, data);
+    },
+
+    /** 注入日志输出（宿主把 debug-log 接进来）。传 null 关闭 */
+    setLogger(fn) {
+      logger = typeof fn === 'function' ? fn : null;
+    },
+  };
+
+  return camera;
+}

package/src/web/render/capture.js

@@ -0,0 +1,30 @@
+// render/capture.js —— 「导出截图」的唯一入口（与 reset-view.js / playback.js 同一口径）
+//
+// 为什么收口：截图以前在调用点写死 `#stage-canvas`（Spine 画布），
+//   Live2D 的画面在覆盖层自己的 canvas 上，结果在 Live2D 面导出的是"上次 Spine 的残留帧"。
+// 现在调用方只说"给我当前面的画面"，由渲染器自己知道该从哪取像素。
+
+/**
+ * 取当前渲染面的画面。
+ * @param {object|null} surface 舞台表面（提供 activeRenderer()）
+ * @returns {{canvas: HTMLCanvasElement, width: number, height: number, source: string}|null}
+ *   source 标识实际通路：'renderer.capture' / 'none' / 'no-renderer'
+ */
+export function captureActive(surface) {
+  const renderer = surface && typeof surface.activeRenderer === 'function' ? surface.activeRenderer() : null;
+  if (!renderer) return null;
+  if (typeof renderer.capture !== 'function') return null;
+  try {
+    const shot = renderer.capture();
+    if (!shot || !shot.canvas || !shot.width || !shot.height) return null;
+    return {
+      canvas: shot.canvas, width: shot.width, height: shot.height,
+      source: 'renderer.capture',
+      digest: shot.digest || 0,
+      // nonEmpty 向后兼容（老断言用它判"不是空白图"）：渲染器给了就用，否则用指纹兜底
+      nonEmpty: typeof shot.nonEmpty === 'number' ? shot.nonEmpty : (shot.digest ? 1 : 0),
+    };
+  } catch {
+    return null;
+  }
+}