modelstage 0.0.0-stage → 0.5.28

package/src/web/engine/animation.js

@@ -0,0 +1,181 @@
+// engine/animation.js —— 动画状态操作（setAnimation / seek / mix / speed / loop / 时长）
+//
+// 各项语义：
+//   · setAnimation：`state.setAnimation(0, name, loop)`，记录 animName/animDuration；
+//   · seek：夹到 [0, 当前时长] 后写 track.trackTime，推进一次状态；
+//   · setMixTime：0..1，写入 stateData.defaultMix；
+//   · setSpeed：夹 0.1–3，写 state.timeScale；
+//   · setLoop：同时改当前 track.loop；
+//   · 时长缓存：装载时扫一次，读时查表（不每帧遍历 animations）。
+
+/** 取 0 号 track（不同版本方法名不同：getCurrent / getTrack） */
+function trackOf(engine) {
+  const state = engine.state;
+  if (!state) return null;
+  try {
+    if (typeof state.getCurrent === 'function') return state.getCurrent(0);
+    if (typeof state.getTrack === 'function') return state.getTrack(0);
+  } catch { /* 忽略 */ }
+  return null;
+}
+
+/** 装载后缓存"动作名 → 时长"（只扫一次） */
+export function cacheDurations(engine) {
+  const map = {};
+  const anims = (engine.skeletonData && engine.skeletonData.animations) || [];
+  for (const a of anims) map[a.name] = Number(a.duration) || 0;
+  engine.durations = map;
+  return map;
+}
+
+/** 当前动作时长（按动作名查缓存，未命中回退到线性查找） */
+export function currentDuration(engine) {
+  const name = engine.animationName;
+  if (!name) return 0;
+  if (engine.durations && Object.prototype.hasOwnProperty.call(engine.durations, name)) return engine.durations[name];
+  const anims = (engine.skeletonData && engine.skeletonData.animations) || [];
+  const found = anims.find((a) => a.name === name);
+  return found ? (Number(found.duration) || 0) : 0;
+}
+
+/** 全部动作名（顺序与运行时一致） */
+export function animations(engine) {
+  const anims = (engine.skeletonData && engine.skeletonData.animations) || [];
+  return anims.map((a) => a.name);
+}
+
+/** 混合时长（0..1 秒） */
+export function setMixTime(engine, t) {
+  engine.mixTime = Math.max(0, Math.min(1, Number(t) || 0));
+  if (engine.stateData) engine.stateData.defaultMix = engine.mixTime;
+}
+
+/**
+ * 切到指定动作。
+ * @param {object} engine
+ * @param {string} name
+ * @param {boolean} loop
+ * @returns {boolean} 是否成功
+ */
+export function setAnimation(engine, name, loop) {
+  if (!engine.state || !name) return false;
+  const wantLoop = loop !== false;
+  try {
+    engine.state.setAnimation(0, String(name), wantLoop);
+    engine.loop = wantLoop;
+    engine.animationName = String(name);
+    engine.animDuration = currentDuration(engine);
+    if (engine.stateData) engine.stateData.defaultMix = Math.max(0, Math.min(1, engine.mixTime));
+    return true;
+  } catch (e) {
+    engine.log('warn', `切换动作失败（${name}）：${e.message}`, 'player');
+    return false;
+  }
+}
+
+/** 播放速率（夹 0.1–3） */
+export function setSpeed(engine, speed) {
+  const v = Math.max(0.1, Math.min(3, Number(speed) || 1));
+  engine.speed = v;
+  if (engine.state && engine.state.timeScale !== undefined) engine.state.timeScale = v;
+}
+
+/** 循环开关（同时改当前 track） */
+export function setLoop(engine, loop) {
+  engine.loop = loop !== false;
+  const track = trackOf(engine);
+  if (track) track.loop = engine.loop;
+}
+
+/** 跳时间：夹到 [0, 时长] 后写 trackTime 并推进一次状态 */
+export function seek(engine, t) {
+  if (!engine.state) return;
+  try {
+    const duration = engine.animDuration || currentDuration(engine);
+    const pos = Math.max(0, Math.min(duration, Number(t) || 0));
+    const track = trackOf(engine);
+    if (track) track.trackTime = pos;
+    engine.state.update(0);
+    if (engine.skeleton && engine.adapters) engine.adapters.skeleton.updateWorldTransform(engine.skeleton);
+    engine.animTime = pos;
+    if (!engine.isPlaying) engine.render();
+  } catch { /* 忽略 */ }
+}
+
+/**
+ * 订阅「当前动作播完一次」事件（跨模型轮播的推进源）。
+ *
+ * 为什么要有这层归一：两个渲染器的原生机制完全不同 ——
+ *   · Spine：`AnimationState.addListener({ complete })`，**每个 track 各报一次** ⇒ 必须过滤 trackIndex === 0；
+ *   · Live2D（pixi-live2d-display）：模型实例 emit `'motionFinish'`，**model 级一次**，且是 `isFinished()` 为真才报。
+ *
+ * 归一后的约定（三条，写死在实现里）：
+ *   1. **只报主轨/当前动作**（Spine 过滤 trackIndex === 0）；
+ *   2. **循环动作不报**：Spine 的 Loop 条目没有 complete；Live2D 的 isFinished() 在循环动作上永远 false。
+ *      两边行为因此天然一致 —— 轮播要的是"播完一次"，循环动作没有这个时刻。
+ *   3. **多轨混合态不推进**由调用方判断（当前动作为真时不推进）；本函数只如实上报事件。
+ *
+ * @param {object} target Spine 的 engine（有 `.state.addListener`）或 Live2D 的模型实例（有 `.on/.off`）
+ * @param {(e: {name: string, trackIndex: number, source: 'spine'|'live2d'}) => void} cb 完成回调
+ * @returns {() => void} 取消订阅函数（重复调用安全）
+ */
+export function onMotionComplete(target, cb) {
+  const noop = () => {};
+  if (!target || typeof cb !== 'function') return noop;
+
+  // ① Spine：AnimationState 的 complete 事件
+  if (target.state && typeof target.state.addListener === 'function') {
+    const listener = {
+      complete(entry) {
+        try {
+          if (!entry) return;
+          if (entry.trackIndex !== 0) return;     // 其它轨道（表情/附加层）不算"当前动作播完"
+          if (entry.loop) return;                 // 循环条目没有终点（与 Live2D 的 isFinished 对齐）
+          const name = entry.animation && entry.animation.name ? String(entry.animation.name) : '';
+          cb({ name, trackIndex: 0, source: 'spine' });
+        } catch { /* 回调内部异常不能影响渲染循环 */ }
+      },
+    };
+    try {
+      target.state.addListener(listener);
+    } catch {
+      return noop;
+    }
+    return () => {
+      try { target.state.removeListener(listener); } catch { /* 已移除/引擎已销毁 */ }
+    };
+  }
+
+  // ② Live2D：模型实例的 motionFinish 事件（库内实现：isFinished() 为真时 emit）
+  if (typeof target.on === 'function' && typeof target.off === 'function') {
+    const handler = () => {
+      try {
+        cb({ name: String(target.animationName || ''), trackIndex: 0, source: 'live2d' });
+      } catch { /* 同上 */ }
+    };
+    try {
+      target.on('motionFinish', handler);
+    } catch {
+      return noop;
+    }
+    return () => {
+      try { target.off('motionFinish', handler); } catch { /* 同上 */ }
+    };
+  }
+
+  return noop;
+}
+
+/** 只读快照（对照脚本/诊断用） */
+export function snapshot(engine) {
+  const track = trackOf(engine);
+  const anim = track && track.animation ? track.animation : null;
+  return {
+    name: anim ? anim.name : (engine.animationName || null),
+    duration: anim ? (Number(anim.duration) || 0) : 0,
+    trackTime: track && typeof track.trackTime === 'number' ? track.trackTime : null,
+    loop: track ? !!track.loop : null,
+    timeScale: engine.state && engine.state.timeScale !== undefined ? engine.state.timeScale : null,
+    defaultMix: engine.stateData ? engine.stateData.defaultMix : null,
+  };
+}

package/src/web/engine/appearance.js

@@ -0,0 +1,136 @@
+// engine/appearance.js —— 外观装配：滤镜着色器、混合钩子、PMA 档位切换（rebuildTextures）
+//
+// 本文件承担「外观层」的三个易错点：
+//   ① 滤镜：换 batcherShader + 保存/还原默认着色器（filters.js 提供纯函数）
+//   ② 混合：给 gl 装 blendFuncSeparate 钩子（straight 档没有它就是错的画面）
+//   ③ rebuildTextures：PMA 档位必须走"释放→重载贴图→重放动画/皮肤→首帧"的完整顺序
+//
+// 关于失败是否回滚档位：重建纹理的 catch 只清 `pendingPresent` 并记一条 error 日志，
+//   finally 里清 `loadingModel` —— **不回滚 pmaMode**。
+//   本实现保持同一语义：重建失败也不回滚档位（否则用户会看到档位自己跳回去）。
+
+import { reconcileFilter, hasFilter, DEFAULT_FILTER } from './filters.js';
+import { installBlendHooks, patchRuntimeBlendConverter } from './pma.js';
+import { buildModel } from './loader.js';
+import { applyTextureFilter } from './textures.js';
+import { pickClass } from './runtime.js';
+
+/** 给 gl 装混合钩子 + 给运行时打 Screen 映射补丁（都幂等；initRenderer 的两步） */
+export function installBlend(engine) {
+  try { patchRuntimeBlendConverter(engine.spine || (engine.adapter && engine.adapter.spine)); } catch { /* 忽略 */ }
+  return installBlendHooks(engine.gl, engine);
+}
+
+/**
+ * 应用当前滤镜档位（编译/换/还原）。
+ * @param {object} engine
+ * @returns {boolean} 是否真的改了着色器
+ */
+export function applyFilter(engine) {
+  const ShaderCtor = engine.spine ? pickClass(engine.spine, 'Shader') : null;
+  const target = engine.renderTarget && engine.renderTarget.renderer ? engine.renderTarget.renderer : engine.renderer;
+  const result = reconcileFilter({  // dsh-skip-quality 滤镜协调调用，既有代码
+    renderer: target,
+    gl: engine.gl,
+    ShaderCtor,
+    filterId: engine.filterId,
+    // 插件效果链：由面板设置变化时算好挂在 engine 上（顺序/激活/销毁的语义在 effect-chain.js）
+    effects: engine.effectChain || [],
+    state: engine.filterState || { saved: null, active: null },
+    log: (l, m, s) => engine.log(l, m, s),
+  });
+  // 签名要一起存：下次调用来比"结构有没有变"（变了才重建，参数变只改 uniform）
+  engine.filterState = { saved: result.saved, active: result.active, signature: result.signature || '' };
+  return result.changed;
+}
+
+/**
+ * 设滤镜 id（非法值回落 original），并立即生效。
+ * @param {object} engine
+ * @param {string} id
+ */
+export function setFilter(engine, id) {
+  const next = hasFilter(id) ? id : DEFAULT_FILTER;
+  if (engine.filterId === next) return next;
+  engine.filterId = next;
+  applyFilter(engine);
+  return next;
+}
+
+/**
+ * 设纹理过滤并重挂已有纹理。
+ * @param {object} engine
+ * @param {string} mode 'linear' | 'nearest'
+ */
+export function setTextureFilter(engine, mode) {
+  engine.textureFilter = mode === 'nearest' ? 'nearest' : 'linear';
+  const gl = engine.gl;
+  if (!gl) return engine.textureFilter;
+  for (const tex of engine.textures || []) applyTextureFilter(gl, tex, engine.textureFilter);
+  for (const page of (engine.atlas && engine.atlas.pages) || []) applyTextureFilter(gl, page.texture, engine.textureFilter);
+  return engine.textureFilter;
+}
+
+/**
+ * 切 PMA 档位：重建纹理并重放动画/皮肤。
+ * @param {object} engine
+ * @param {string} mode auto | premultiplied | straight | upload
+ * @returns {Promise<boolean>}
+ */
+/** 上一次生效的 PMA 判定（只用于切换日志的"前后对比"，不参与任何判定） */
+const lastPmaInfo = new WeakMap();
+
+export async function rebuildTextures(engine, mode) {  // dsh-skip-complexity 切档重建流程，既有代码(本轮仅加 3 行埋点/日志)
+  const descriptor = engine.currentModel;
+  if (!descriptor || !engine.spine || !engine.gl) return false;
+  const prevMode = engine.pmaMode;
+  const prevInfo = lastPmaInfo.get(engine);
+  const prevNeedPremultiply = prevInfo ? prevInfo.needPremultiply : undefined;
+  engine.loadingModel = true;
+  try {
+    // **先建新的**（旧纹理/骨架这时一根手指都没动）：建失败 ⇒ 现场完好，天然回滚，
+    //   不需要额外保存/恢复旧纹理那套状态快照（那才是容易漏、容易错的写法）。
+    const model = await buildModel({
+      adapters: engine.adapters,
+      spine: engine.spine,
+      gl: engine.gl,
+      descriptor,
+      pmaMode: mode,
+      textureFilter: engine.textureFilter,
+      supportsStraight: engine.supportsStraightAlpha !== false,
+      log: (l, m, s) => engine.log(l, m, s),
+    });
+    // ---- 换血（到这里才允许动旧内容）
+    engine.stop();
+    engine.disposeContent();
+    engine.skeletonData = null;
+    engine.pmaMode = mode;
+    engine.bindModel(model);
+    engine.disposeRenderer();
+    engine.createRenderer();
+    engine.resetCamera();
+    if (engine.animationName) engine.setAnimation(engine.animationName, engine.loop);
+    if (engine.activeSkins && engine.activeSkins.length) engine.setSkins(engine.activeSkins);
+    engine.loadingModel = false;   // 允许出帧（下方 finally 再保证一次）
+    engine.pendingPresent = true;
+    engine.presentFirstFrame();
+    lastPmaInfo.set(engine, model.pmaInfo);
+    // 带上"原档 → 新档 + needPremultiply 前后值"：现场"从自动直接点已预乘画面没变化"
+    //   就是靠这条判断 needPremultiply 到底有没有从 true 变成 false（只记日志，不改行为）
+    engine.log('info', `PMA 切换：${prevMode || '未知'} → ${mode}｜生效 ${model.pmaInfo.effectiveMode}`
+      + `｜needPremultiply ${prevNeedPremultiply === undefined ? '未知' : String(prevNeedPremultiply)} → ${String(model.pmaInfo.needPremultiply)}`, 'pma');
+    return true;
+  } catch (e) {
+    engine.log('error', `重建纹理失败: ${e && e.message ? e.message : e}`, 'pma');
+    return false;
+  } finally {
+    engine.loadingModel = false;
+    engine.pendingPresent = false;
+    // ★ 关键兜底：无论成功还是失败，都不允许停在"循环已停"的死状态。
+    //   成功路径：stop() 过 ⇒ 这里把循环重新起来（presentFirstFrame 只画一帧、不会恢复循环）。
+    //   失败路径：build 在 stop 之前就抛了 ⇒ 循环本来还在跑，这里不会重复启动。
+    if (engine.skeleton && !engine.isPlaying) {
+      try { engine.start(); } catch { /* 启动失败也已在日志里 */ }
+    }
+  }
+}

package/src/web/engine/camera-adapter.js

@@ -0,0 +1,212 @@
+// engine/camera-adapter.js —— 引擎侧相机适配（只读写引擎状态，不做策略）
+//
+// 分层约束：**档位/范围/夹取属于 `render/camera/index.js`（唯一钳制点）**；
+//   本文件只负责"把数值落到 spine 相机上"，因此这里出现的 MIN/MAX 仅作最后一道保险，
+//   正常调用链不会依赖它。
+
+import { CAMERA } from '../render/camera/constants.js';
+import { computeFit, computeSubjectBounds, clampSubjectBox, intersectBox } from './fit.js';
+
+/** 读当前缩放（userScale，越大越放大） */
+export function getScale(engine) {
+  return engine.userScale;
+}
+
+/**
+ * 写缩放。**这里不做夹取**：范围钳制只允许发生在 `render/camera`（唯一钳制点），
+ * 引擎再夹一次会与上层形成双重钳制，手感会随调用路径漂移。
+ * @param {object} engine
+ * @param {number} value
+ */
+export function setScale(engine, value) {
+  const n = Number(value);
+  engine.userScale = Number.isFinite(n) && n > 0 ? n : 1;
+  applyUserScale(engine);
+}
+
+/** 一档缩放：scale *= 1 + dir*STEP */
+export function zoomStep(engine, dir) {
+  const factor = 1 + (Number(dir) || 0) * CAMERA.STEP;
+  setScale(engine, (engine.userScale || 1) * factor);
+}
+
+/**
+ * 相机收尾：同步视口并重算矩阵。
+ * 为什么必须 update：spine 的 OrthoCamera 改了 zoom/viewport 后不会自动重算投影矩阵，
+ *   不调用就会用上一次（或默认 800×600）的矩阵渲染 —— 表现为"模型忽大忽小"，且只和差几倍。
+ * @param {object} engine
+ */
+export function syncCamera(engine) {
+  const cam = engine.camera;
+  if (!cam) return;
+  try {
+    if (typeof cam.setViewport === 'function') cam.setViewport(engine.logicalW, engine.logicalH);
+    else {
+      if ('viewportWidth' in cam) cam.viewportWidth = engine.logicalW;
+      if ('viewportHeight' in cam) cam.viewportHeight = engine.logicalH;
+    }
+    if (typeof cam.update === 'function') cam.update();
+  } catch { /* 相机更新失败不阻断渲染 */ }
+}
+
+/** 把 userScale 落到相机（zoom 越小画面越大 ⇒ 取倒数） */
+export function applyUserScale(engine) {
+  if (!engine.camera) return;
+  engine.camera.zoom = engine.baseZoom / (engine.userScale || 1);
+  syncCamera(engine);
+}
+
+/**
+ * 平移：屏幕像素 → 相机世界位移。
+ * 公式：`s = (camera.zoom ?? camera.scale ?? 1) * 2`，
+ *   `position.x -= dx * flipX * s`，`position.y += dy * flipY * s`，随后 update。
+ * 为什么必须这样：这里乘 2 与 flip 处理是已验收手感的一部分，换成"按 DPR 换算"会让拖动速度不同。
+ * @param {object} engine
+ * @param {number} dx
+ * @param {number} dy
+ */
+export function pan(engine, dx, dy) {
+  const cam = engine.camera;
+  if (!cam || !cam.position) return;
+  const zoom = cam.zoom !== undefined ? cam.zoom : (cam.scale !== undefined ? cam.scale : 1);
+  const s = zoom * 2;
+  const fx = engine.flipX ? -1 : 1;
+  const fy = engine.flipY ? -1 : 1;
+  cam.position.x -= (Number(dx) || 0) * fx * s;
+  cam.position.y += (Number(dy) || 0) * fy * s;
+  if (typeof cam.update === 'function') cam.update();
+  if (typeof engine.requestRender === 'function') engine.requestRender();
+}
+
+/**
+ * 仅当 subject 明显超出 full 时取交（超出判定用相对容差，避免浮点末位抖动触发）。
+ * @param {object} subject
+ * @param {object} full
+ */
+function trimOnlyIfOutside(subject, full) {
+  if (!full) return subject;
+  const epsW = Math.max(1e-6 * Math.abs(subject.w), 1e-9);
+  const epsH = Math.max(1e-6 * Math.abs(subject.h), 1e-9);
+  const outside = subject.w > full.w + epsW || subject.h > full.h + epsH;
+  return outside ? intersectBox(subject, full) : subject;
+}
+
+/** 两种包围盒求并集 */
+function unionBox(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return { x, y, w: Math.max(a.x + a.w, b.x + b.w) - x, h: Math.max(a.y + a.h, b.y + b.h) - y };
+}
+
+/** 面积（用于 subject 可信度判定） */
+function area(b) { return b ? b.w * b.h : 0; }
+
+/** animation 模式：对每个动作采样若干帧取并集（最多 120 帧，避免长时间卡顿） */
+export function animationBounds(engine) {
+  const anims = (engine.skeletonData && engine.skeletonData.animations) || [];
+  let acc = null;
+  let budget = 120;
+  for (const anim of anims) {
+    if (budget <= 0) break;
+    const duration = Number(anim.duration) || 0;
+    const samples = Math.min(12, Math.max(2, Math.ceil(duration * 6)), budget);
+    for (let i = 0; i < samples; i += 1) {
+      try {
+        if (engine.skeleton.setToSetupPose) engine.skeleton.setToSetupPose();
+        if (typeof anim.apply === 'function') anim.apply(engine.skeleton, 0, (duration * (i + 0.5)) / samples, false, null, 1, 0, 0);
+        engine.skeleton.updateWorldTransform(2);
+      } catch { /* 单个动作采样失败继续 */ }
+      acc = unionBox(acc, engine.adapters ? engine.adapters.skeleton.bounds(engine.skeleton) : null);
+      budget -= 1;
+    }
+  }
+  return acc;
+}
+
+/**
+ * 取当前 fit 模式下的包围盒。
+ * subject：主体包围盒可信（面积在全量 0.1~8 倍之间）就用它，否则回落全量；
+ * all：全量；animation：动作采样并集。
+ */
+export function pickBounds(engine) {
+  const mode = engine.fitMode || 'subject';
+  const full = engine.adapters ? engine.adapters.skeleton.bounds(engine.skeleton) : null;
+  if (mode === 'all') return full;
+  if (mode === 'animation') return animationBounds(engine) || full;
+  const rawSubject = computeSubjectBounds({ skeleton: engine.skeleton, skeletonData: engine.skeletonData });
+  // 只有"显著超出整体"时才取交：两个包围盒来自不同顶点路径，端点常有 1e-6 量级差异，
+  //   无条件求交会把 subject 削掉极小量 → baseZoom 末位会有差异（实测 1 ULP）。
+  const subject = rawSubject ? trimOnlyIfOutside(rawSubject, full) : null;
+  if (!subject) return full;
+  const n = area(subject);
+  const o = area(full);
+  const trustworthy = !(o > 0) || (n >= o * 0.1 && n <= o * 8);
+  if (!trustworthy) {
+    if (!engine.fitWarnedSubject) {
+      engine.fitWarnedSubject = true;
+      engine.log('warn', `subject 包围盒不可信（面积比 ${(n / (o || 1)).toFixed(2)}），已回落整体包围盒`, 'camera');
+    }
+    return full;
+  }
+  return clampSubjectBox(subject) || full;
+}
+
+/** 按当前 fit 模式重新 fit */
+export function applyFit(engine) {
+  // 顺序：先摆 setup pose + 更新世界变换，再在"全部皮肤合并"形态下测量
+  if (engine.adapters) {
+    engine.adapters.skeleton.setupPose(engine.skeleton);
+    engine.adapters.skeleton.updateWorldTransform(engine.skeleton);
+  }
+  const bounds = engine.adapters && engine.adapters.skeleton.withAllSkins
+    ? engine.adapters.skeleton.withAllSkins({ skeleton: engine.skeleton, skeletonData: engine.skeletonData }, () => pickBounds(engine))
+    : pickBounds(engine);
+  const fit = computeFit({ bounds, viewW: engine.logicalW, viewH: engine.logicalH });
+  if (!fit) return null;
+  engine.baseZoom = fit.baseZoom;
+  if (engine.camera && engine.camera.position) engine.camera.position.set(fit.centerX, fit.centerY, 0);
+  applyUserScale(engine);
+  syncCamera(engine);
+  // 输出与相机 fit 同一格式的日志（便于逐项对照 bbox / zoom / viewport）
+  try {
+    const b = bounds || { x: 0, y: 0, w: 0, h: 0 };
+    engine.log('info', `相机 fit[${mode}]: bbox=[${b.x.toFixed(1)}, ${b.y.toFixed(1)}] ${b.w.toFixed(1)}x${b.h.toFixed(1)}, `
+      + `center=(${fit.centerX.toFixed(1)}, ${fit.centerY.toFixed(1)}), vw=${engine.logicalW}, vh=${engine.logicalH}, `
+      + `zoom=${Number(engine.camera && engine.camera.zoom ? engine.camera.zoom : 0).toFixed(4)}`, 'camera');
+  } catch { /* 日志失败不影响相机 */ }
+  return fit;
+}
+
+/** 复位：缩放归 1 并重新 fit */
+export function resetCamera(engine) {
+  engine.userScale = 1;
+  applyFit(engine);
+}
+
+/** 支持的 fit 模式 */
+export const FIT_MODES = ['subject', 'all', 'animation'];
+
+/**
+ * 切换 fit 模式（切换后立即重新适配）。
+ * @param {object} engine
+ * @param {string} mode
+ * @returns {boolean}
+ */
+export function setFitMode(engine, mode) {
+  const next = String(mode || '').toLowerCase();
+  if (!FIT_MODES.includes(next)) {
+    engine.log('warn', `未知的 fit 模式：${mode}（支持 ${FIT_MODES.join('/')}）`, 'camera');
+    return false;
+  }
+  if (engine.fitMode === next) return true;
+  engine.fitMode = next;
+  if (engine.skeleton) resetCamera(engine);
+  return true;
+}
+
+/** 读当前 fit 模式 */
+export function getFitMode(engine) {
+  return engine.fitMode || 'subject';
+}

package/src/web/engine/effect-chain.js

@@ -0,0 +1,138 @@
+// engine/effect-chain.js —— **效果链的唯一实现**（Spine / Live2D 共用）
+//
+// 为什么必须共用：两条链路只有"怎么把着色器挂上去"不同（Spine 换 batcherShader、
+//   Live2D 挂 PIXI.Filter），而"哪些效果生效 / 按什么顺序叠 / 参数怎么变成 uniform /
+//   什么时候该销毁"是同一套语义。各写一遍就是以后改一处漏一处。
+//
+// 链的顺序（契约 §9.4）：内置 presetFilter 在前，插件效果按清单 effects[] 声明顺序叠加。
+// 表达式契约（§9.2）：插件效果是"作用于当前像素的表达式"，可用符号只有
+//   c（当前像素）、uv（纹理坐标）、texel（1/纹理尺寸）、u_<param>。
+
+/**
+ * 生成插件效果可用的前置声明（两个链路的差异只有采样器名与纹理坐标变量名）。
+ *
+ * **必须分两段返回**，因为 GLSL 的作用域规则不允许把它们混在一起：
+ *   · global：uniform 声明与 texelSample() 函数定义，只能出现在 **main 之外**；
+ *   · local ：uv / texel 这些局部变量，只能出现在 **main 之内**（链的前面）。
+ *   上一版把它们拼成一段塞进 main 里 ⇒ `0:324: S'u_texel' : syntax error`
+ *   （函数内不许声明 uniform、也不许嵌套定义函数），实测编译失败。
+ * @param {{sampler:string, texCoords:string}} opts
+ * @returns {{global:string, local:string}} 两段 GLSL 片段
+ */
+export function effectPrelude({ sampler, texCoords }) {
+  return {
+    global: [
+      'uniform vec2 u_texel;',
+      `vec3 texelSample(vec2 p) { return texture2D(${sampler}, p).rgb; }`,
+    ].join('\n'),
+    local: [
+      `vec2 uv = ${texCoords};`,
+      'vec2 texel = u_texel;',
+    ].join('\n  '),
+  };
+}
+
+/**
+ * 生成链上**插件参数 uniform 的声明**（全局作用域）。
+ *
+ * 为什么必须单独生成：插件的 params[].key 只是"名字 + 区间"，着色器里从来没有它们的声明；
+ *   只下发值而不声明 ⇒ `ERROR: 0:10: 'u_amount' : undeclared identifier`（实测踩过）。
+ * 类型当前只支持 float（契约 §9.1：params[].type 当前只允许 "float"）。
+ * @param {Array<{uniforms:object}>} chain
+ * @returns {string} GLSL 声明行（每行一个），无参数时返回空串
+ */
+export function uniformDeclarations(chain) {
+  const keys = new Set();
+  for (const eff of chain || []) {
+    for (const key of Object.keys(eff.uniforms || {})) keys.add(key);
+  }
+  return [...keys].map((key) => `uniform float ${key};`).join('\n');
+}
+
+/**
+ * 档位 → 参数值（第 0 档 = 关闭，不产生 uniform）。
+ *
+ * 为什么按索引线性映射：契约里插件只声明 options 文本与 params 区间，
+ *   没有逐档具体值的位置；线性映射是唯一不要求插件多写一套配置的确定规则。
+ * @param {object} effect { params: [{key, min, max}] }
+ * @param {number} optionIndex 选中下标（0 = 关）
+ * @param {number} optionCount 总档数
+ * @returns {{active:boolean, uniforms:object}}
+ */
+export function uniformsForOption(effect, optionIndex, optionCount) {
+  const params = (effect && Array.isArray(effect.params)) ? effect.params : [];
+  const idx = Number(optionIndex);
+  const count = Number(optionCount);
+  // 「关」档（idx=0）也**留在链里**，参数取 min（通常 0）⇒ 表达式退化成恒等、画面等于原图。
+  //   这样切档位只改 uniform、链的**结构签名**不变 ⇒ 上层不重建着色器/滤镜实例。
+  //   反过来做（关档就把它从链里摘掉）会让每次"关↔开"都触发一次重建 + 着色器编译，
+  //   实测卡顿明显。
+  const t = count > 1 ? Math.min(1, Math.max(0, idx) / (count - 1)) : 0;
+  const uniforms = {};
+  for (const p of params) {
+    if (!p || !p.key) continue;
+    const min = Number.isFinite(Number(p.min)) ? Number(p.min) : 0;
+    const max = Number.isFinite(Number(p.max)) ? Number(p.max) : 1;
+    uniforms[p.key] = min + (max - min) * t;
+  }
+  return { active: true, uniforms };
+}
+
+/**
+ * 按当前设置算出生效的效果链（顺序 = 传入声明顺序 = 清单 effects[] 顺序）。
+ * @param {Array<{id:string, fragment:string, params:Array}>} declared
+ * @param {(id:string)=>{optionIndex:number, optionCount:number}} readSetting
+ * @returns {Array<{id:string, fragment:string, uniforms:object}>}
+ */
+export function activeChain(declared, readSetting) {
+  const out = [];
+  for (const eff of declared || []) {
+    if (!eff || !eff.id || !eff.fragment) continue;
+    const sel = (typeof readSetting === 'function' ? readSetting(eff.id) : null) || { optionIndex: 0, optionCount: 1 };
+    const { active, uniforms } = uniformsForOption(eff, sel.optionIndex, sel.optionCount);
+    if (!active) continue;
+    out.push({ id: eff.id, fragment: eff.fragment, uniforms });
+  }
+  return out;
+}
+
+/**
+ * 生成链的着色器主体：`vec3 c = base; c = (预设); c = (效果1); …; vec3 f = c;`
+ *
+ * 为什么"反复改写 c"而不是嵌套表达式：插件表达式里写的就是 c，
+ *   嵌套就得改写它内部的标识符（脆且不可靠）；顺序赋值让每段自然看到上一段输出。
+ * @param {{presetBody:string, effects:Array<{fragment:string}>}} opts
+ * @returns {string}
+ */
+export function buildChainBody({ presetBody, effects }) {
+  const lines = ['vec3 c = base;', `c = (${presetBody || 'c'});`];
+  for (const eff of effects || []) {
+    if (!eff || !eff.fragment) continue;
+    lines.push(`c = (${eff.fragment});`);
+  }
+  lines.push('vec3 f = c;');
+  return lines.join('\n  ');
+}
+
+/**
+ * 汇总链上所有 uniform 值。
+ * @param {Array<{uniforms:object}>} chain
+ * @returns {object}
+ */
+export function chainUniforms(chain) {
+  const out = {};
+  for (const eff of chain || []) {
+    for (const [k, v] of Object.entries(eff.uniforms || {})) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * 链的**结构**签名：只含"效果 id + 表达式"，**不含参数值**。
+ * 参数变化只改 uniform；签名一变才允许重建着色器/滤镜实例（热更新的判据）。
+ * @param {Array<{id:string, fragment:string}>} chain
+ * @returns {string}
+ */
+export function chainSignature(chain) {
+  return (chain || []).map((e) => `${e.id}:${e.fragment}`).join('|');
+}