modelstage 0.0.0-stage → 0.5.24

package/src/web/render/surface.js

@@ -0,0 +1,571 @@
+// render/surface.js —— 渲染面（StageSurface）：画布与帧时钟的唯一所有者
+//
+// 职责边界：
+//   · Surface **唯一拥有**：#stage-canvas（Spine 面）、覆盖层容器与它的 canvas（Live2D 面）、
+//     尺寸计算、DPR、z 序、可见性、`data-stage-mode`、帧调度入口；
+//   · Renderer 只拿到 **handle**（canvas / overlay / size / dpr / requestRender / onResize），
+//     不许自己建 canvas、不许读 DOM 尺寸、不许自己起 rAF 主循环；
+//   · 切换只有一个入口 `activate(document)`：loading → 统一卸载 → 装载 → 切面，串行保护；
+//   · 卸载只有 `disposeActive()`：幂等、不关心当前是哪一面。
+//
+// 为什么这么分：新增渲染面（3D）时只加一个 register()，不必再改画布/尺寸/可见性逻辑。
+
+import { createSwitcher } from './surface-switch.js';
+// 面元数据表：kind/id → 面属性（画布、覆盖层、stageMode）的唯一真相
+import { byIdOrKind, byKind } from './surfaces.js';
+import { buildDocument } from '../infra/document.js';
+
+/** 覆盖层容器 id（Live2D 面用） */
+
+const OVERLAY_ID = 'live2d-overlay';
+/** 覆盖层内 canvas id */
+const OVERLAY_CANVAS_ID = 'live2d-overlay-canvas';
+
+/**
+ * 创建渲染面。
+ * @param {{
+ *   root?: HTMLElement | (() => HTMLElement|null),
+ *   log?: (message: string, level?: 'info'|'warn'|'error') => void,
+ * }} [options] root 缺省用 #stage
+ */
+/**
+ * 按 mode 选出要调用的卸载方法（纯函数，契约 §二 / §五-3 的落地判据）。
+ *   · mode='unmount' → 优先 unmount（释放内容、保留引擎）
+ *   · 其它（含缺省）→ dispose（彻底拆）
+ *   · 渲染器**没实现** unmount 时回落 dispose —— 宁可彻底拆，也不能什么都不做（否则就是资源泄漏）
+ * @param {object|null} renderer
+ * @param {'unmount'|'dispose'} mode
+ * @returns {Function|null} 无参调用函数；渲染器为空或两种方法都没有时返回 null
+ */
+export function pickDisposeCall(renderer, mode) {
+  if (!renderer) return null;
+  const want = mode === 'unmount' ? 'unmount' : 'dispose';
+  if (typeof renderer[want] === 'function') return () => renderer[want]();
+  if (typeof renderer.dispose === 'function') return () => renderer.dispose();
+  return null;
+}
+
+export function createStageSurface({ root, log } = {}) {
+  /** 根容器（#stage） */
+  function rootEl() {
+    if (typeof root === 'function') return root();
+    return root || document.getElementById('stage');
+  }
+
+  const renderers = new Map();
+  const resizeCbs = new Set();
+  /** 切换完成后要通知的订阅者（面板据此重算三态） */
+  const switchCbs = new Set();
+
+  const st = {
+    /** 当前渲染器 id（null = 未激活） */
+    activeId: null,
+    /** 当前已装载的 document（便于排查） */
+    document: null,
+    /** 切换串行锁 */
+    swapping: false,
+    pending: null,        // 切换进行中收到的最新请求（last-wins，完成后立即消费）
+    /** 尺寸与 DPR */
+    size: { width: 0, height: 0 },
+    backgroundMode: 'checkerboard', // 背景唯一权威（写 data-bg 的唯一入口）
+    bgCbs: new Set(),
+    dpr: (typeof window !== 'undefined' && window.devicePixelRatio) || 1,
+    /** 帧统计 */
+    frames: 0,
+    fps: 0,
+    fpsAt: 0,
+    /** rAF 句柄（Surface 的帧调度入口） */
+    rafId: 0,
+    /** 待渲染标记 */
+    dirty: false,
+  };
+
+  /** 统一日志出口 */
+  function note(message, level = 'info') {
+    if (typeof log === 'function') {
+      try { log(message, level); } catch { /* 忽略 */ }
+    }
+  }
+
+  // ---------------------------------------------------------------- 画布所有权
+  /** 覆盖层容器（Surface 建、Surface 管） */
+  let overlayEl = null;
+
+  /** 确保覆盖层存在（父级 = #stage，绝对定位铺满，不接收指针事件） */
+  function ensureOverlay() {
+    if (overlayEl && overlayEl.isConnected) return overlayEl;
+    let el = document.getElementById(OVERLAY_ID);
+    if (!el) {
+      el = document.createElement('div');
+      el.id = OVERLAY_ID;
+      // 定位/尺寸/pointer-events 全在 style.css 的 #live2d-overlay（契约：不在 JS 里写设计值）
+      const cv = document.createElement('canvas');
+      cv.id = OVERLAY_CANVAS_ID;
+      el.appendChild(cv);
+      (rootEl() || document.body).appendChild(el);
+    }
+    overlayEl = el;
+    return el;
+  }
+
+  /** 取覆盖层内的 canvas（Live2D 渲染目标） */
+  function overlayCanvas() {
+    ensureOverlay();
+    return document.getElementById(OVERLAY_CANVAS_ID);
+  }
+
+  /** 取 Spine 面 canvas（舞台里已有的那块，Surface 负责尺寸/DPR） */
+  function spineCanvas() {
+    return document.getElementById('stage-canvas');
+  }
+
+  // ---------------------------------------------------------------- 尺寸 / DPR
+  /**
+   * 量测根容器的 CSS 尺寸，并把「CSS 尺寸 + 期望 DPR」交给当前渲染器。
+   * 为什么这里不写 canvas.width：像素尺寸（backing store）只由渲染器/引擎拥有，
+   *   Surface 一旦也写，就会与引擎的 getEffectiveDpr 口径打架 ——
+   *   像素网格变了而 gl.viewport / camera.viewportWidth 没变 ⇒ 画面整体缩放偏移（BUG-2）。
+   */
+  function measure() {
+    const el = rootEl();
+    if (!el) return st.size;
+    const rect = el.getBoundingClientRect();
+    let width = Math.max(1, Math.round(rect.width || el.clientWidth || 0));
+    let height = Math.max(1, Math.round(rect.height || el.clientHeight || 0));
+    // 移动端旋转后 layout viewport 可能滞后：根容器是 position:fixed + inset:0，
+    //   实测横屏时它的 rect 仍是竖屏尺寸（777x1035），与真实视口方向相反 ——
+    //   这会让画布与模型按旧方向布局，表现为"模型只在某个矩形内可见、拖动超出不显示"。
+    //   此时以 innerWidth/innerHeight 为准（它跟随真实视口更新）。
+    //   只在「方向相反」时替换：同方向下的细微差异仍以容器为准（容器可能带内边距等）。
+    if (typeof window !== 'undefined') {
+      const iw = Math.round(window.innerWidth || 0);
+      const ih = Math.round(window.innerHeight || 0);
+      if (iw > 0 && ih > 0 && (width > height) !== (iw > ih)) {
+        width = iw;
+        height = ih;
+      }
+    }
+    const changed = width !== st.size.width || height !== st.size.height;
+    st.size = { width, height };
+    const box = { cssW: width, cssH: height, dpr: st.dpr };
+    if (changed) {
+      notifyResize(box);
+      for (const cb of resizeCbs) {
+        try { cb({ ...box }); } catch { /* 回调异常不影响其它订阅者 */ }
+      }
+    }
+    return st.size;
+  }
+
+  /**
+   * 读取 URL 上的 ?res=N 强制分辨率（对照实验用；缺省/非法返回 null）。
+   * 放在 Surface 里：分辨率也是「几何」的一部分，不允许各渲染面自己解析一遍。
+   * @returns {number|null}
+   */
+  function forcedResOverride() {
+    try {
+      const raw = new URLSearchParams(window.location.search || '').get('res');
+      if (!raw) return null;
+      const n = Number(raw);
+      return Number.isFinite(n) && n >= 1 && n <= 4 ? n : null;
+    } catch { return null; }
+  }
+
+  /**
+   * 尺寸唯一来源：渲染器只从这里取几何，不得自己读 DOM 或 devicePixelRatio。
+   * 语义：cssW/cssH = 舞台 CSS 像素；dpr = 设备比；res = 期望分辨率。
+   *   最终生效的分辨率由各渲染器按自身规则决定（Spine 引擎会再按软件渲染 / dprMode 收口）。
+   * 为什么集中在 Surface：同一件事只能有一个负责人，否则两套渲染面会各自算出不同尺寸。
+   * @returns {{cssW:number, cssH:number, dpr:number, res:number}}
+   */
+  function geometry() {
+    let width = st.size.width;
+    let height = st.size.height;
+    // 首次调用可能还没 measure 过：只补一次只读测量，不触发 notifyResize
+    if (!width || !height) {
+      const el = rootEl();
+      if (el) {
+        const rect = el.getBoundingClientRect();
+        width = Math.max(1, Math.round(rect.width || el.clientWidth || 0));
+        height = Math.max(1, Math.round(rect.height || el.clientHeight || 0));
+      }
+    }
+    const dpr = st.dpr > 0 ? st.dpr : 1;
+    const forced = forcedResOverride();
+    return { cssW: width || 1, cssH: height || 1, dpr, res: forced || dpr };
+  }
+  /**
+   * 把尺寸变化交给当前渲染器（渲染器负责决定 backing store：引擎侧按 getEffectiveDpr 算）。
+   * @param {{cssW:number, cssH:number, dpr:number}} box
+   */
+  function notifyResize(box) {
+    const entry = renderers.get(st.activeId);
+    if (entry && typeof entry.resize === 'function') {
+      try { entry.resize(box); } catch (err) { note(`渲染器 resize 失败：${err && err.message}`, 'warn'); }
+    }
+  }
+
+  /** 尺寸变化订阅（渲染器在这里拿到最新尺寸，自己不读 DOM） */
+  function onResize(cb) {
+    if (typeof cb !== 'function') return () => {};
+    resizeCbs.add(cb);
+    return () => resizeCbs.delete(cb);
+  }
+
+  /** ResizeObserver：root 尺寸变化即重算（避免轮询） */
+  let observer = null;
+  function watchResize() {
+    if (observer || typeof ResizeObserver !== 'function') return;
+    const el = rootEl();
+    if (!el) return;
+    observer = new ResizeObserver(() => { measure(); });
+    observer.observe(el);
+  }
+
+  // ---------------------------------------------------------------- 常驻断言
+
+// ---------------------------------------------------------------- 帧时钟
+  /** 调度一次渲染（Surface 的帧入口：渲染器只"请求渲染"，不自己起循环） */
+  function requestRender() {
+    st.dirty = true;
+    if (st.rafId) return;
+    st.rafId = requestAnimationFrame(() => {
+      st.rafId = 0;
+      if (!st.dirty) return;
+      st.dirty = false;
+      st.frames += 1;
+      const now = performance.now();
+      if (!st.fpsAt) st.fpsAt = now;
+      if (now - st.fpsAt >= 1000) {
+        st.fps = Math.round((st.frames * 1000) / (now - st.fpsAt));
+        st.frames = 0;
+        st.fpsAt = now;
+      }
+      const entry = renderers.get(st.activeId);
+      if (entry && typeof entry.render === 'function') {
+        try { entry.render({ width: st.size.width, height: st.size.height, dpr: st.dpr }); } catch { /* 忽略 */ }
+      }
+    });
+  }
+
+  // ---------------------------------------------------------------- 切面（唯一写入点）
+  /**
+   * 写 data-stage-mode（**本文件是唯一写入点**）。
+   * @param {'spine'|'live2d'|'loading'} mode 渲染面的 id/kind，或过渡值 'loading'
+   */
+  function setMode(mode) {
+    const el = rootEl();
+    // 查表得面属性：'loading' 是过渡遮罩（不属于任何面），其余一律要求命中表项。
+    //   原先 `mode === 'live2d' ? 'live2d' : 'spine'` 会把未知面**静默写成 spine** ——
+    //   于是 CSS 走 2D 布局、覆盖层显隐也按 spine 判，加新面时整个舞台错乱且不报错。
+    const meta = mode === 'loading' ? null : byIdOrKind(mode);
+    const next = mode === 'loading' ? 'loading' : (meta ? meta.stageMode : null);
+    if (!next) throw new Error(`setMode 收到未知渲染面「${mode || '?'}」：未在 render/surfaces.js 注册`);
+    if (el) el.dataset.stageMode = next;
+    // 覆盖层显隐由表字段 overlayVisible 决定（只有声明用覆盖层的面才可见）
+    const ov = document.getElementById(OVERLAY_ID);
+    // 显隐用类切换（样式在 style.css），避免 JS 写 display
+    if (ov) ov.classList.toggle('is-visible', !!(meta && meta.overlayVisible));
+    return next;
+  }
+
+  /** 读当前面 */
+  function stageMode() {
+    const el = rootEl();
+    return el ? el.dataset.stageMode || null : null;
+  }
+
+  /** 切换断言日志（只读三项状态 + 画布尺寸） */
+  function noteSwitch(tag) {
+    const cv = spineCanvas();
+    const ov = document.getElementById(OVERLAY_ID);
+    const entry = renderers.get(st.activeId);
+    let active = null;
+    try { active = entry && typeof entry.isActive === 'function' ? !!entry.isActive() : null; } catch { active = 'err'; }
+    const line = `${tag} → stageMode=${stageMode()} active=${st.activeId} activeState=${active}`
+      + ` overlay=${ov ? getComputedStyle(ov).display : 'none'} spineCanvas=${cv ? getComputedStyle(cv).visibility : null}`
+      + ` width=${cv ? cv.width : null} size=${st.size.width}x${st.size.height}@${st.dpr}`;
+    note(line);
+    return line;
+  }
+
+  // ---------------------------------------------------------------- 注册与句柄
+  /**
+   * 注册一个渲染器。
+   *
+   * 这里做**启动期断言**：渲染器必须声明 kind，且该 kind 必须在面元数据表里、id 与表项一致。
+   * 目的：让"注册了渲染器却忘了加表项"在启动时就炸，而不是等用户点开那个面才现形
+   *   （那种错表现为静默误判，最难排）。也顺带挡住 register('spine-v2') 这类 id 漂移 ——
+   *   表的 id 是 setMode/handle/卸载模式的推导依据，漂了就会查不到。
+   * @param {{id: string, kind: string, capabilities: object, mount: Function, dispose?: Function, isActive?: Function, camera?: object, render?: Function}} renderer
+   */
+  function register(renderer) {
+    if (!renderer || !renderer.id) throw new Error('stageSurface.register: 渲染器必须有 id');
+    if (!renderer.kind) {
+      throw new Error(`stageSurface.register: 渲染器「${renderer.id}」必须声明 kind（用于面元数据表校验）`);
+    }
+    const meta = byKind(renderer.kind);
+    if (!meta) {
+      throw new Error(`stageSurface.register: 渲染面「${renderer.kind}」未在 render/surfaces.js 注册`);
+    }
+    if (meta.id !== renderer.id) {
+      throw new Error(`stageSurface.register: 渲染器 id「${renderer.id}」与表项 id「${meta.id}」不一致（kind=${renderer.kind}）`);
+    }
+    renderers.set(renderer.id, renderer);
+    note(`注册渲染器：${renderer.id}（kind=${renderer.kind}）`);
+    return renderer;
+  }
+
+  /**
+   * 取渲染资源句柄（渲染器只能通过它碰画布/尺寸）。
+   * @param {string} rendererId
+   */
+  function handle(rendererId) {
+    // 用哪个画布由表字段 overlay 决定：'canvas' ⇒ 该面独占覆盖层 canvas；null ⇒ 用舞台画布。
+    //   原先 `const isLive2D = rendererId === 'live2d'` 让未知面拿到舞台画布 + overlay=null，
+    //   等于静默降级成 spine 的形态（新面会在错误的画布上画）。
+    const meta = byIdOrKind(rendererId);
+    if (!meta) throw new Error(`surface.handle 收到未知渲染面「${rendererId || '?'}」：未在 render/surfaces.js 注册`);
+    const useOverlay = meta.overlay === 'canvas';
+    return {
+      /** 该渲染面独占的 canvas（表里 overlay=null 的面用舞台画布，overlay='canvas' 的用覆盖层） */
+      canvas: useOverlay ? overlayCanvas() : spineCanvas(),
+      /** 覆盖层容器（声明用覆盖层的面才有；其余为 null） */
+      overlay: useOverlay ? ensureOverlay() : null,
+      /** 逻辑尺寸（CSS 像素） */
+      get size() { return { ...st.size }; },
+      /** 设备像素比 */
+      get dpr() { return st.dpr; },
+      /** 尺寸唯一来源（cssW/cssH/dpr/res） */
+      geometry,
+      /** 请求渲染（Surface 调度，渲染器不自己起 rAF） */
+      requestRender,
+      /** 订阅尺寸变化 */
+      onResize,
+      /** 背景模式（唯一权威在 Surface；渲染器只读） */
+      getBackgroundMode,
+      /** 订阅背景变化（mount 时订阅、卸载时退订） */
+      onBackgroundChange,
+      /** 背景配色（从 CSS 变量集中读取） */
+      palette,
+    };
+  }
+
+  // ---------------------------------------------------------------- 激活状态机
+  /**
+   * 唯一卸载入口：幂等，不关心当前是哪一面。
+   * @param {'unmount'|'dispose'} [mode] 切换渲染面用 unmount（保留引擎）；Surface 销毁用 dispose（彻底拆）
+   */
+  async function disposeActive(mode = 'dispose') {
+    const entry = renderers.get(st.activeId);
+    const call = pickDisposeCall(entry, mode);
+    if (call) {
+      try { await call(); } catch { /* 卸载失败也要继续切面 */ }
+    }
+    st.activeId = null;
+    st.document = null;
+    setMode('loading');
+  }
+
+  /**
+   * 唯一切换入口。
+   * @param {{kind?: 'spine'|'live2d', id?: string, rendererId?: string}} document
+   * @returns {Promise<any>} 装载结果（并发被丢弃时返回 null）
+   */
+  // 切换状态机（last-wins 排队 + 失败回滚）拆到 surface-switch.js，本文件只提供回调
+  const switcher = createSwitcher({
+    renderers,
+    state: st,
+    setMode,
+    disposeActive,
+    handle,
+    measure,
+    requestRender,
+    note,
+    noteSwitch,
+    onSwitched: (activeId) => { for (const cb of switchCbs) { try { cb(activeId, stageMode()); } catch { /* 订阅者异常不影响切换 */ } } },
+  });
+
+  /** 切换到一份文档（唯一入口，语义见 surface-switch.js） */
+  function activate(document) {
+    return switcher.activate(document);
+  }
+
+  /** 当前渲染器的相机（交互层通过它拿到 camera.*，不关心是哪一面） */
+  function activeCamera() {
+    const entry = renderers.get(st.activeId);
+    return entry && entry.camera ? entry.camera : null;
+  }
+
+  /** 只读统计 */
+  function stats() {
+    return {
+      active: st.activeId,
+      mode: stageMode(),
+      size: { ...st.size },
+      dpr: st.dpr,
+      fps: st.fps,
+      swapping: st.swapping,
+    };
+  }
+
+  /**
+   * 设置期望 DPR：只记录并下发给渲染器，**不直接写画布**。
+   * 真实生效值由引擎 getEffectiveDpr 决定（它知道软件渲染、dprMode、封顶 2 这些规则）。
+   * @param {number|string} value 像素比，或 'auto'
+   */
+  function setDpr(value) {
+    const v = value === 'auto' || value === undefined ? null : Number(value);
+    st.dprRequest = v && v > 0 ? v : null;
+    st.dpr = st.dprRequest || (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
+    const entry = renderers.get(st.activeId);
+    if (entry && typeof entry.setDpr === 'function') {
+      try { entry.setDpr(value); } catch (err) { note(`渲染器 setDpr 失败：${err && err.message}`, 'warn'); }
+    }
+    measure();
+    requestRender();
+    return st.dpr;
+  }
+
+  /**
+   * 读当前背景模式（唯一权威在 Surface，渲染器不得自己读 DOM 属性）。
+   * @returns {'checkerboard'|'solid'|'transparent'}
+   */
+  function getBackgroundMode() {
+    return st.backgroundMode;
+  }
+
+  /**
+   * 读背景配色（从 CSS 变量集中读取，渲染器不自己 getComputedStyle）。
+   * 为什么集中：棋盘/纯色的具体色值属于"表面"的视觉约定，分散到各渲染器会两套真相。
+   * @returns {{solid:string, checkerDark:string, checkerLight:string}}
+   */
+  function palette() {
+    const el = rootEl();
+    const read = (name, fallback) => {
+      try {
+        const v = el ? getComputedStyle(el).getPropertyValue(name).trim() : '';
+        return v || fallback;
+      } catch { return fallback; }
+    };
+    return {
+      solid: read('--stage-solid', '#2a2a2a'),
+      checkerDark: read('--stage-checker-dark', '#2a2a2a'),
+      checkerLight: read('--stage-checker-light', '#3a3f45'),
+    };
+  }
+
+  /**
+   * 设置背景模式（**写 data-bg 的唯一入口**）。
+   * 副作用顺序：更新权威状态 → 写 data-bg（CSS 兜底）→ 通知所有渲染器与订阅者。
+   * @param {'checkerboard'|'solid'|'transparent'} mode
+   * @returns {string} 规范化后的模式
+   */
+  function setBackground(mode) {
+    const el = rootEl();
+    const next = mode === 'solid' || mode === 'transparent' ? mode : 'checkerboard';
+    const changed = next !== st.backgroundMode;
+    st.backgroundMode = next;
+    if (el) el.dataset.bg = next;
+    const pal = palette();
+    // 通知所有已注册渲染器（不论当前是否激活：切面后状态必须一致）
+    for (const [, entry] of renderers) {
+      if (entry && typeof entry.setBackground === 'function') {
+        try { entry.setBackground(next, pal); } catch (err) { note(`渲染器 setBackground 失败：${err && err.message}`, 'warn'); }
+      }
+    }
+    if (changed) {
+      for (const cb of st.bgCbs) {
+        try { cb(next, pal); } catch { /* 订阅者异常不影响其他订阅者 */ }
+      }
+    }
+    return next;
+  }
+
+  /**
+   * 订阅背景变化（渲染器在 mount 时订阅、卸载时退订）。
+   * 回调签名：(mode, palette) => void
+   * @param {(mode: string, pal: object) => void} cb
+   * @returns {() => void} 退订函数
+   */
+  function onBackgroundChange(cb) {
+    if (typeof cb !== 'function') return () => {};
+    st.bgCbs.add(cb);
+    return () => st.bgCbs.delete(cb);
+  }
+  /** 释放整块表面 */
+  function dispose() {
+    try { disposeActive(); } catch { /* 忽略 */ }
+    if (observer) { try { observer.disconnect(); } catch { /* 忽略 */ } observer = null; }
+    if (st.rafId) { try { cancelAnimationFrame(st.rafId); } catch { /* 忽略 */ } st.rafId = 0; }
+    resizeCbs.clear();
+    renderers.clear();
+    note('渲染面已释放');
+  }
+
+  // 初始化：建覆盖层、量尺寸、开始观察
+  try {
+    ensureOverlay();
+    // 以 DOM 现值作为初始权威（样式表可能已预设 data-bg）
+    try {
+      const el0 = rootEl();
+      st.backgroundMode = (el0 && el0.dataset && el0.dataset.bg) || 'checkerboard';
+    } catch { /* 忽略 */ }
+    measure();
+    watchResize();
+  } catch (err) {
+    note(`渲染面初始化失败：${err && err.message}`, 'warn');
+  }
+
+  return {
+    register,
+    /** Assets 层入口（测试/工具用）：catalog entry → ready Document */
+    buildDocument,
+    handle,
+    activate,
+    dispose,
+    disposeActive,
+    setDpr,
+    stats,
+    stageMode,
+    setMode,
+    activeCamera,
+    requestRender,
+    onResize,
+    measure,
+    geometry,
+    getBackgroundMode,
+    setBackground,
+    onBackgroundChange,
+    palette,
+    /**
+     * 交互目标：整个舞台区域（不是某一块画布）。
+     * 为什么要暴露它：画布可见性会随渲染面切换而变化（Live2D 面下 Spine 画布
+     *   `visibility:hidden` 不参与命中测试），而交互属于"舞台区域"、不属于某块画布；
+     * 由 Surface 给出恒定目标，交互层绑定一次即可 —— 切面后无需重绑，也不会双监听。
+     */
+    get interactionTarget() { return rootEl(); },
+    renderers: () => [...renderers.keys()],
+    /** 订阅渲染面切换（回调收到新的激活 id 与 stageMode） */
+    onRendererChange: (cb) => (typeof cb === 'function' ? (switchCbs.add(cb), () => switchCbs.delete(cb)) : () => {}),
+    /**
+     * 当前生效的能力集合。
+     * 取"激活中的渲染器"；还没装载任何内容时用**首个注册者**（默认面），
+     *   因为能力是静态声明，与是否已装载模型无关；一个渲染器都没有才返回 null（面板走回落）。
+     */
+    capabilities() {
+      const entry = renderers.get(st.activeId) || renderers.values().next().value;
+      return entry && entry.capabilities ? entry.capabilities : null;
+    },
+    /**
+     * 当前激活渲染器（供外壳把设置下发给它，不自己持有舞台引用）。
+     * 还没装载任何东西时退回**首个注册者**（默认面）：设置快照要在启动阶段就落到引擎，
+     *   等装载时再补会出现"面板显示 A、引擎在 B"的漂移（与上面 capabilities() 同一口径）。
+     */
+    activeRenderer() {
+      return renderers.get(st.activeId) || renderers.values().next().value || null;
+    },
+    /** 按 id 取渲染器 */
+    renderer: (id) => renderers.get(id) || null,
+  };
+}

package/src/web/render/surfaces.js

@@ -0,0 +1,70 @@
+// render/surfaces.js —— 渲染面元数据表：**「有哪些面、每个面长什么样」的唯一真相**。
+//
+// 为什么要有这张表：这个事实原先被十处 `x === 'live2d' ? : 'spine'` 分别表达。
+//   只有两个面时那种写法成立（"不是 live2d 就是 spine"），加第三个面时每一处都会
+//   **静默误判成 spine** —— 表现为功能错乱而非报错，是最难排的一类缺陷。
+//
+// 加新面时：① 在这里加一行 ② 写 render/<kind>.js ③ main.js 里 register() 一次。
+//   消费方一律查表取值，不再自己写二分判断。
+//
+// 核心约束：**未知 kind 一律返回 null，绝不"回落到 spine"**。
+//   返回 null 会逼调用方显式处理（报错或跳过），比"猜一个默认值"安全得多。
+
+/**
+ * 每个字段都对应一处原先的硬编码（加 3D 时按需填，不必再找第 11 个 if）：
+ *   id             渲染器 id（= document.rendererId 的缺省值，surface.register 的键）
+ *   kind           document.kind 的取值（catalog/document 层的内容类型）
+ *   label          名册里显示的类型名（原 roster/list.js 的三元表达式）
+ *   badge          名册徽标的 CSS 修饰名（原 roster/rows.js 的 kindClass）
+ *   stageMode      写到 data-stage-mode 的值，CSS 据此选布局（原 surface.js setMode）
+ *   overlay        'canvas' = 该面用**覆盖层** canvas；null = 用舞台画布（原 isLive2D 判断）
+ *   overlayVisible 覆盖层容器是否可见（原 setMode 里的 is-visible 类切换）
+ *   cameraKind     相机常量覆盖表的键（原 camera/constants.js limitsFor）
+ *   deepLink       深链（?model= 不带 runtime 时）是否接受这个 kind（原 app/url-params.js）
+ */
+export const SURFACES = [
+  { id: 'spine', kind: 'spine', label: 'Spine', badge: 'spine', stageMode: 'spine', overlay: null, overlayVisible: false, cameraKind: 'spine', deepLink: true },
+  { id: 'live2d', kind: 'live2d', label: 'Live2D', badge: 'live2d', stageMode: 'live2d', overlay: 'canvas', overlayVisible: true, cameraKind: 'live2d', deepLink: true },
+];
+
+/** 按 kind 查（未知 → null） */
+export function byKind(kind) {
+  if (!kind) return null;
+  return SURFACES.find((s) => s.kind === kind) || null;
+}
+
+/** 按渲染器 id 查（未知 → null） */
+export function byId(id) {
+  if (!id) return null;
+  return SURFACES.find((s) => s.id === id) || null;
+}
+
+/** 已知 kind 列表（document.detectKind 用它判"是不是受支持的内容类型"） */
+export function knownKinds() {
+  return SURFACES.map((s) => s.kind);
+}
+
+/** 是否受支持的 kind */
+export function isKnownKind(kind) {
+  return byKind(kind) !== null;
+}
+
+/**
+ * kind → data-stage-mode 的值。**未知 kind 返回 null**，调用方必须显式处理。
+ * @param {string} kind
+ * @returns {string|null}
+ */
+export function stageModeOf(kind) {
+  const s = byKind(kind);
+  return s ? s.stageMode : null;
+}
+
+/**
+ * 给"手里可能是 rendererId、也可能是 kind"的旧调用点一个统一入口
+ * （两个面的 id 与 kind 恰好同名，历史上被混用过；这里一次收敛，不改既有调用语义）。
+ * @param {string} value
+ * @returns {object|null} 元数据
+ */
+export function byIdOrKind(value) {
+  return byId(value) || byKind(value);
+}

package/src/web/roster/filter.js

@@ -0,0 +1,31 @@
+// roster/filter.js —— 名册搜索过滤（纯函数，不碰 DOM）
+//
+// 搜索口径：
+//   · 空关键词 ⇒ 全显示
+//   · 角色整组判定：角色名命中，或该角色任意变体命中（变体命中显示整组，避免"只剩一个变体"的割裂感）
+//   · 游戏名 / 资源根 id 命中也算，直接显示该游戏全部角色
+
+/** 变体参与搜索的文本（模型名 + 目录 + 中文名/原名/服装；统一小写） */
+export function variantSearchText(v) {
+  const m = v.model;
+  const nm = v.nm;
+  return `${m.name} ${m.srcDir || ''} ${nm ? `${nm.name} ${nm.costume}` : ''}`.toLowerCase();
+}
+
+/** 角色是否命中（按角色整组判定：搜角色名时显示该角色全部变体） */
+export function charMatches(c, kw) {
+  if (!kw) return true;
+  if (String(c.title).toLowerCase().includes(kw)) return true;
+  return c.variants.some((v) => variantSearchText(v).includes(kw));
+}
+
+/** 某游戏在搜索下可见的角色（未加载的游戏不参与过滤） */
+export function visibleChars(game, state) {
+  const entry = state.gameChars.get(game.key);
+  if (!entry) return [];
+  const kw = state.keyword;
+  if (!kw) return entry.chars;
+  const gameHit = String(game.name).toLowerCase().includes(kw)
+    || game.roots.some((r) => String(r.id).toLowerCase().includes(kw));
+  return gameHit ? entry.chars : entry.chars.filter((c) => charMatches(c, kw));
+}