modelstage 0.0.0-stage → 0.5.28

package/src/web/app/anim-list.js

@@ -0,0 +1,222 @@
+// app/anim-list.js —— 动作清单的唯一数据源 + 播放 + 循环推进
+//
+// 契约要求（docs/契约/渲染面.md）：
+//   §一 动作清单只能有一处来源：右栏与底栏必须读同一份，不得各取一处；
+//   §二 每条 = 动作名 + 时长；取不到时长就不显示（禁止 0s 冒充）；
+//   §三 两处入口行为一致（同列表/同顺序/同时长，点任一处都能播，高亮同步）；
+//   §四 「单动循环」开启 = 按列表顺序依次播完全部并回到第一条；关闭 = 停留当前动作重复播；
+//   §五 Spine 与 Live2D 都要覆盖，Live2D 用 `group / motion` 区分。
+//
+// 为什么集中在这里：此前右栏读 bridge.readState().motions（该字段不存在）、底栏读装载返回，
+//   两处数据源不一致，Live2D 下右栏永远是空的。现在两处都只调 buildAnimationList()。
+//
+// 当前播放项的唯一真相是底栏下拉（#transport-motion）的值（契约 §七），
+//   这里只负责"给出清单 / 播某条 / 按顺序推进"，不自己另存一份"当前动作"。
+
+import { state, stage } from './context.js';
+import { setRendererSetting } from './renderer-setting.js';
+
+/** 面板与底栏共用的清单缓存（每次模型变化后重建） */
+let cached = [];
+/** 循环推进态：只记"从哪条开始、什么时候开始"，当前项仍以下拉为准 */
+const cycle = { on: false, timer: null, startedAt: 0, currentId: '' };
+
+/** Live2D 桥（未装载时返回 null） */
+function live2dBridge() {
+  const l2d = typeof window !== 'undefined' && window.__WEB__ ? window.__WEB__.live2d : null;
+  if (!l2d || typeof l2d.isActive !== 'function' || !l2d.isActive()) return null;
+  return l2d.bridge || null;
+}
+
+/** 时长格式：6.2s；没有时长返回空串（契约禁止显示 0s / —） */
+export function durationText(duration) {
+  const d = Number(duration);
+  if (!Number.isFinite(d) || d <= 0) return '';
+  return `${d.toFixed(1)}s`;
+}
+
+/** 列表项的显示文案：`名字 · 6.2s`（无时长就只留名字） */
+export function labelWithDuration(item) {
+  const t = durationText(item && item.duration);
+  return t ? `${item.label} · ${t}` : String((item && item.label) || '');
+}
+
+/**
+ * 建清单（单一来源）。
+ * Spine：舞台 stats().animations 的名称 + api.animationDetails() 的时长；
+ * Live2D：bridge.motionItems()（label 已是 `group / motion`）。
+ * @returns {Array<{id: string, label: string, duration: number|null}>}
+ */
+export function buildAnimationList() {
+  const bridge = live2dBridge();
+  let list = [];
+  if (bridge && typeof bridge.motionItems === 'function') {
+    list = bridge.motionItems().map((m) => ({ id: m.label, label: m.label, duration: m.duration }));
+  } else {
+    let details = [];
+    try { details = stage && typeof stage.animationDetails === 'function' ? stage.animationDetails() : []; } catch { details = []; }
+    if (details.length) {
+      list = details.map((a) => ({ id: a.name, label: a.name, duration: a.duration }));
+    } else {
+      // 兜底：拿不到时长也要能列出来（名称必须显示）
+      let names = [];
+      try {
+        const snap = stage && typeof stage.stats === 'function' ? stage.stats() : null;
+        names = (snap && Array.isArray(snap.animations)) ? snap.animations : [];
+      } catch { names = []; }
+      list = names.map((n) => ({ id: n, label: String(n), duration: null }));
+    }
+  }
+  cached = list;
+  return list.slice();
+}
+
+/**
+ * 预热动作时长（目前只有 Live2D 需要：时长在动作文件里，不在运行时状态里）。
+ * 取到后回调刷新一次，面板与底栏一起更新；同一模型只尝试一次。
+ * @returns {Promise<number>} 本次新取到条数
+ */
+export async function primeAnimationDurations() {
+  const bridge = live2dBridge();
+  if (!bridge || typeof bridge.ensureMotionDurations !== 'function') return 0;
+  if (primeAnimationDurations.busy) return 0;
+  primeAnimationDurations.busy = true;
+  try {
+    const filled = await bridge.ensureMotionDurations();
+    if (filled > 0) {
+      cached = [];
+      buildAnimationList();
+      if (typeof cycle.onAdvance === 'function') cycle.onAdvance('');
+    }
+    return filled;
+  } catch {
+    return 0;
+  } finally {
+    primeAnimationDurations.busy = false;
+  }
+}
+
+/** 最近一次构建的清单（不重新取数） */
+export function currentList() {
+  return cached.slice();
+}
+
+/**
+ * 用同一份清单重填底栏下拉（同顺序、同文案、同时长）。
+ * 放在这里的原因：装载回调、模型切换、循环推进都可能改变清单，
+ *   让"填下拉"只有一个出口，就不会出现"右栏有、底栏没有"的错位。
+ * @returns {number} 填入条数
+ */
+export function syncTransportOptions() {
+  const transport = state.transport;
+  if (!transport || typeof transport.setOptions !== 'function') return 0;
+  const list = cached.length ? cached : buildAnimationList();
+  if (!list.length) return 0;
+  const picker = transport.picker ? transport.picker('transport-motion') : null;
+  const curVal = picker && typeof picker.value === 'function' ? picker.value() : (document.getElementById('transport-motion') || {}).value;
+  const keep = curVal && list.some((x) => x.id === curVal) ? curVal : list[0].id;
+  transport.setOptions('transport-motion', list.map((x) => ({ text: labelWithDuration(x), value: x.id })), keep);
+  return list.length;
+}
+
+/**
+ * 清掉「当前动作」的所有内存副本（换模型时调用）。
+ *
+ * 为什么需要：动作是**模型属性**（设计 §1.9），但它的三个副本都是应用层状态，不会自己跟着模型走：
+ *   · `cycle.currentId`  —— 循环推进用，名字命中新清单就会继续按旧项推进
+ *   · `state.transportMotion` —— 底栏下拉的副本，被 `currentAnimationId()` 优先读取
+ *   · 底栏下拉自身的值 —— 新模型若有同名动作（碧蓝航线 live2d 全都叫 idle/home/…），
+ *     "保留同名项"的规则会让它原样停在上一个模型选的那条 ⇒ 新模型**真的播它**
+ * 三者不清，就会出现"选了 home、切哪个模型都播 home"。
+ */
+export function resetMotionState() {
+  cycle.currentId = '';
+  cycle.startedAt = 0;
+  if (state) state.transportMotion = '';
+  try { delete document.documentElement.dataset.transportMotion; } catch { /* 忽略 */ }
+}
+
+/** 当前播放项 id：唯一真相是底栏下拉的值（契约 §七） */
+export function currentAnimationId() {
+  // 唯一真相 = state.transportMotion（底栏自绘下拉没有 <select>.value，句柄也可能刚被重建）
+  if (state && state.transportMotion) return String(state.transportMotion);
+  const transport = state && state.transport;
+  if (transport && typeof transport.picker === 'function') {
+    const pk = transport.picker('transport-motion');
+    if (pk && typeof pk.value === 'function') {
+      const v = pk.value();
+      if (v) return v;
+    }
+  }
+  const sel = typeof document !== 'undefined' ? document.querySelector('#transport-motion') : null;
+  return sel && sel.value ? sel.value : '';
+}
+
+/**
+ * 播一条动作。
+ * @param {string} id 清单里的 id（Live2D 为 `group / motion` 标签，Spine 为动作名）
+ * @returns {boolean} 是否被接受
+ */
+export function playAnimation(id) {
+  if (!id) return false;
+  // 一律经渲染器下发（INV-01）：Live2D 面走 bridge.playLabel、Spine 面走舞台的 setAnimation，
+  //   分流在各自渲染器的 setSetting('animation') 里，这里不再判断"哪一面"。
+  const { ok } = setRendererSetting('animation', id);
+  if (ok) notePlaying(id);
+  return ok;
+}
+
+/** 记录"从这条开始播"，供循环推进计算时间 */
+export function notePlaying(id) {
+  cycle.currentId = String(id || '');
+  cycle.startedAt = Date.now();
+}
+
+/** 循环开关（契约 §四）：开 = 顺序播完全部并回到第一条；关 = 停留当前动作重复播 */
+export function setCycleLoop(on) {
+  cycle.on = !!on;
+  if (cycle.timer) { clearInterval(cycle.timer); cycle.timer = null; }
+  if (!cycle.on) return false;
+  cycle.currentId = cycle.currentId || currentAnimationId();
+  cycle.startedAt = Date.now();
+  cycle.timer = setInterval(stepCycle, 200);
+  return true;
+}
+
+export function isCycleLoop() {
+  return cycle.on;
+}
+
+/** 时长未知时的推进间隔：契约要求"依次播完全部"，不能因为没时长就卡住 */
+const FALLBACK_ADVANCE_MS = 1200;
+
+/**
+ * 推进一拍：当前动作放完就切下一条，末尾回到第一条。
+ * 有真实时长就按时长走；没有时长（如空轨道动画）用兜底间隔推进，
+ *   否则循环会在第一个"无时长"动作上停死。
+ */
+function stepCycle() {
+  if (!cycle.on) return;
+  const list = cached.length ? cached : buildAnimationList();
+  if (list.length < 2) return;
+  const id = cycle.currentId || currentAnimationId();
+  const idx = list.findIndex((x) => x.id === id);
+  const cur = idx >= 0 ? list[idx] : null;
+  const dur = cur && Number(cur.duration);
+  const waitMs = Number.isFinite(dur) && dur > 0 ? dur * 1000 - 80 : FALLBACK_ADVANCE_MS;
+  if (Date.now() - cycle.startedAt < waitMs) return;
+  const next = list[(idx + 1) % list.length]; // 末尾回到第一条
+  if (!next) return;
+  const { ok } = setRendererSetting('animation', next.id);
+  if (!ok) return;
+  notePlaying(next.id);
+  if (state.transport) state.transport.setSelectValue('transport-motion', next.id);
+  document.documentElement.dataset.transportMotion = next.id;
+  // 面板高亮跟随（回调注入，避免面板↔应用双向依赖）
+  if (typeof cycle.onAdvance === 'function') cycle.onAdvance(next.id);
+}
+
+/** 面板注册"推进后重绘高亮"的回调 */
+export function onCycleAdvance(fn) {
+  cycle.onAdvance = typeof fn === 'function' ? fn : null;
+}

package/src/web/app/background-solids.js

@@ -0,0 +1,150 @@
+// app/background-solids.js —— 「纯色预设」的前端数据层（只管跟服务端 5 个接口打交道）
+//
+// 为什么不存本地：预设要能列表管理、要跨设备带走（清前端偏好也不该丢），
+//   所以权威数据在服务端；localStorage 只保存"当前选中的颜色值"（那属于界面偏好）。
+//
+// 与 panel/color-picker.js 的分工：
+//   调色盘只回一个 '#rrggbb'；命名、增删改、列表刷新**全在这里**，调色盘不认识"预设"这件事。
+
+import { getJson, postJson, formatError } from '../infra/api.js';
+
+/** 接口根（同源） */
+const API = '/api/backgrounds/solids';
+
+/**
+ * 最近一次成功取到的列表（缓存）。
+ * 用途：给"背景色默认值"提供一个**同步可读**的兜底（view-settings 里取默认色时不能 await）。
+ * 只读语义：这里不做任何本地持久化，进程内缓存而已。
+ */
+let cache = [];
+
+/** 内置兜底色：接口没就绪/取不到时，纯色模式仍然有一个合法颜色可用 */
+export const FALLBACK_COLOR = '#2a2a2a';
+
+/**
+ * 读取缓存中的预设列表（可能为空）。
+ * @returns {Array<{id:string,name:string,color:string,createdAt?:string}>}
+ */
+export function cachedSolids() {
+  return cache.slice();
+}
+
+/**
+ * 默认纯色：预设列表第一条的颜色；没有预设时用内置兜底。
+ * @returns {string} '#rrggbb'
+ */
+export function defaultSolidColor() {
+  const first = cache[0];
+  return first && first.color ? first.color : FALLBACK_COLOR;
+}
+
+/**
+ * 归一化一条记录（服务端字段名固定：id / name / color / createdAt）。
+ * @param {object} it
+ * @returns {{id:string,name:string,color:string,createdAt?:string}}
+ */
+function normalize(it) {
+  const o = it && typeof it === 'object' ? it : {};
+  return {
+    id: String(o.id || ''),
+    name: String(o.name || ''),
+    color: String(o.color || '').toLowerCase(),
+    createdAt: o.createdAt,
+  };
+}
+
+/**
+ * 把失败响应翻成人话（优先用服务端 error，它带具体原因）。
+ * @param {object|null} body
+ * @param {number} status
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+function failureText(body, status, fallback) {
+  if (body && typeof body.error === 'string' && body.error) return body.error;
+  return fallback || `请求失败（HTTP ${status}）`;
+}
+
+/**
+ * 取纯色预设列表。
+ * @returns {Promise<{ok:boolean, items:object[], message?:string}>}
+ */
+export async function listSolids() {
+  try {
+    const body = await getJson(API);
+    const items = (body && Array.isArray(body.items) ? body.items : []).map(normalize);
+    cache = items;
+    return { ok: true, items };
+  } catch (err) {
+    const status = (err && err.status) || 0;
+    return { ok: false, items: [], message: failureText(err && err.body, status, formatError(err)) };
+  }
+}
+
+/**
+ * 新增一条预设。
+ * @param {string} name ≤30 字符（服务端去重/校验，前端不重复实现规则）
+ * @param {string} color '#rrggbb'
+ * @returns {Promise<{ok:boolean, item?:object, message?:string}>}
+ */
+export async function addSolid(name, color) {
+  try {
+    const body = await postJson(API, { name, color });
+    const item = body && body.item ? normalize(body.item) : null;
+    if (item) cache = [...cache, item];
+    return { ok: true, item: item || undefined };
+  } catch (err) {
+    const status = (err && err.status) || 0;
+    return { ok: false, message: failureText(err && err.body, status, formatError(err)) };
+  }
+}
+
+/**
+ * 改名（id 与 color 不变）。
+ * @param {string} id
+ * @param {string} name
+ * @returns {Promise<{ok:boolean, item?:object, message?:string}>}
+ */
+export async function renameSolid(id, name) {
+  try {
+    const body = await postJson(`${API}/rename`, { id, name });
+    const item = body && body.item ? normalize(body.item) : null;
+    if (item) cache = cache.map((x) => (x.id === item.id ? item : x));
+    return { ok: true, item: item || undefined };
+  } catch (err) {
+    const status = (err && err.status) || 0;
+    return { ok: false, message: failureText(err && err.body, status, formatError(err)) };
+  }
+}
+
+/**
+ * 删除一条。
+ * @param {string} id
+ * @returns {Promise<{ok:boolean, removed?:number, id?:string, message?:string}>}
+ */
+export async function removeSolid(id) {
+  try {
+    const body = await postJson(`${API}/remove`, { id });
+    cache = cache.filter((x) => x.id !== id);
+    return { ok: true, removed: body && body.removed, id: (body && body.id) || id };
+  } catch (err) {
+    const status = (err && err.status) || 0;
+    return { ok: false, message: failureText(err && err.body, status, formatError(err)) };
+  }
+}
+
+/**
+ * 恢复默认 5 色（服务端权威：它知道默认是哪 5 条）。
+ * @returns {Promise<{ok:boolean, items:object[], message?:string}>}
+ */
+export async function resetSolids() {
+  try {
+    const body = await postJson(`${API}/reset`, {});
+    const items = (body && Array.isArray(body.items) ? body.items : []).map(normalize);
+    cache = items;
+    return { ok: true, items };
+  } catch (err) {
+    const status = (err && err.status) || 0;
+    return { ok: false, items: [], message: failureText(err && err.body, status, formatError(err)) };
+  }
+}

package/src/web/app/backgrounds.js

@@ -0,0 +1,152 @@
+// app/backgrounds.js —— 自定义背景图的前端数据层（只跟服务端 5 个接口打交道）
+//
+// 为什么不存 localStorage：背景图要能列表管理、要刷新后仍在、要能换机带走，
+//   dataURL 写 localStorage 是"假上传"（换浏览器就丢、单张 4MB 就写爆存储）。
+// 服务端落盘在 data/backgrounds/，这里只管取列表 / 传 / 改名 / 删。
+//
+// 失败原因码（后端 reason）到用户可见文案的映射也放在这里，面板与底栏共用同一套说法。
+
+/** 后端接口根（同源，随页面部署） */
+const API = '/api/backgrounds';
+
+/** 允许的图片类型（与服务端白名单一致；前端只用于 file 选择框过滤） */
+export const ACCEPT = 'image/png,image/jpeg,image/webp';
+
+/** 单张上限（5MB）：服务端权威判定，这里只用于提前给出人话提示 */
+export const MAX_BYTES = 5 * 1024 * 1024;
+
+/** reason → 用户可见文案（后端 error 更具体时优先用后端文案） */
+const REASON_TEXT = {
+  'too-large': `图片超过 ${MAX_BYTES / 1048576}MB 上限，请先压缩再上传`,
+  'bad-type': '只接受 png / jpeg / webp 图片',
+  'bad-name': '名称不能为空',
+  'not-found': '这张图已经不在了，请刷新列表',
+  'empty': '没有收到文件内容',
+  'aborted': '上传被中断了，请重试',
+  'disk-error': '服务端写盘失败，请稍后重试',
+  'server-error': '服务端内部错误',
+};
+
+/**
+ * 把一次失败响应翻成人话（优先用服务端给的 error，它带具体数值）。
+ * @param {object|null} body 响应体（可能是 null）
+ * @param {number} status HTTP 状态码
+ * @returns {{reason: string, message: string}} 原因码与提示文案
+ */
+export function describeFailure(body, status) {
+  const reason = (body && body.reason) || (status === 413 ? 'too-large' : 'server-error');
+  const message = (body && body.error) || REASON_TEXT[reason] || `请求失败（HTTP ${status}）`;
+  return { reason, message };
+}
+
+/**
+ * 统一请求封装：解析 JSON、把失败翻成 {ok:false, reason, message}。
+ * @param {string} url 目标地址
+ * @param {object} [init] fetch 参数（传 signal 可覆盖兜底超时）
+ * @returns {Promise<object>} 成功时为响应体（含 ok:true），失败时 {ok:false, reason, message}
+ */
+async function request(url, init) {
+  let res;
+  try {
+    // 兜底超时 8s：本文件四个调用点（列表/改名/删除/重置）都是读改写一份小 JSON，
+    //   同源同类接口实测 10~58ms（/api/plugins 10ms、/api/config/export 58ms），留 100 倍余量。
+    //   上传那处 body 最大 4MB（dataURL）⇒ 由调用方传更长的 signal 覆盖（见 uploadBackground）。
+    res = await fetch(url, { ...(init || {}), signal: (init && init.signal) || AbortSignal.timeout(8000) });
+  } catch (e) {
+    return { ok: false, reason: 'network', message: `网络请求失败：${(e && e.message) || e}` };
+  }
+  let body = null;
+  try { body = await res.json(); } catch { body = null; }
+  if (!res.ok || !body || body.ok !== true) return { ok: false, ...describeFailure(body, res.status) };
+  return body;
+}
+
+/**
+ * 取列表。
+ * @returns {Promise<{ok:boolean, items?:Array, message?:string}>} items 里每项有 {id,name,url,bytes}
+ */
+export function listBackgrounds() {
+  return request(API, { cache: 'no-store' });
+}
+
+/**
+ * 上传一张图（原始二进制 body + x-filename 头）。
+ *
+ * 为什么不用 FormData：服务端按原始字节流边读边计上限（multipart 要先落临时文件再解析），
+ *   而且这里不需要多字段——文件名走 x-filename（百分号编码，避免中文乱码）。
+ * @param {File} file 用户选的文件
+ * @returns {Promise<object>} 成功 {ok:true, item}，失败 {ok:false, reason, message}
+ */
+export function uploadBackground(file) {
+  if (!file) return Promise.resolve({ ok: false, reason: 'empty', message: '没有选择文件' });
+  if (file.size > MAX_BYTES) {
+    // 前端先挡一层：省掉一次 5MB 的无效上传（服务端仍会再判一次）
+    return Promise.resolve({
+      ok: false, reason: 'too-large',
+      message: `图片 ${(file.size / 1048576).toFixed(2)}MB 超过 ${MAX_BYTES / 1048576}MB 上限，请先压缩`,
+    });
+  }
+  return request(API, {
+    method: 'POST',
+    headers: {
+      'Content-Type': file.type || 'application/octet-stream',
+      'x-filename': encodeURIComponent(file.name || ''),
+    },
+    body: file,
+    // 上传单独覆盖成 15s：body 最大 4MB（MAX_BYTES），服务端要收满 + 落盘（CIFS 上写几 MB 可能数秒），
+    //   兜底的 8s 对这一步太紧；其余三个调用点都是小 JSON，用兜底值即可。
+    signal: AbortSignal.timeout(15000),
+  });
+}
+
+/**
+ * 重命名（只改显示名，id 与 url 不变）。
+ * @param {string} id 目标 id
+ * @param {string} name 新名字
+ * @returns {Promise<object>} 成功 {ok:true, item, adjusted}
+ */
+export function renameBackground(id, name) {
+  return request(`${API}/rename`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id, name }),
+  });
+}
+
+/**
+ * 删除（服务端把文件移进 .trash/，可恢复）。
+ * @param {string} id 目标 id
+ * @returns {Promise<object>} 成功 {ok:true, removed}
+ */
+export function removeBackground(id) {
+  return request(`${API}/delete`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id }),
+  });
+}
+
+/** 把索引 id 变成可直接用的图片地址 */
+export function urlOf(item) {
+  return item && item.url ? item.url : '';
+}
+
+/**
+ * 选择本地图片：弹系统文件选择框，返回用户选的 File（取消返回 null）。
+ * @returns {Promise<File|null>} 选中的文件
+ */
+export function pickFile() {
+  return new Promise((resolve) => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = ACCEPT;
+    input.classList.add('file-picker-hidden');
+    document.body.append(input);
+    input.addEventListener('change', () => {
+      const file = (input.files && input.files[0]) || null;
+      input.remove();
+      resolve(file);
+    }, { once: true });
+    input.click();
+  });
+}

package/src/web/app/camera-log.js

@@ -0,0 +1,28 @@
+// app/camera-log.js —— 相机操作日志的单一出口（控制台 / 断言缓冲 / 调试面板）
+//
+// 为什么独立成模块：main.js 有行数上限，且这段逻辑与"相机怎么动"无关，
+//   只负责把相机侧发出的日志分发给三个消费者。
+
+/**
+ * 把相机日志接到三路输出。
+ * @param {object|null} cameraEntry 当前渲染器的相机入口（含 setLogger）
+ * @returns {boolean} 是否成功接上（相机入口缺失时返回 false）
+ */
+export function installCameraLogger(cameraEntry) {
+  if (!cameraEntry || typeof cameraEntry.setLogger !== 'function') return false;
+  cameraEntry.setLogger((line, data) => {
+    const bag = (window.__WEB__ = window.__WEB__ || {});
+    bag.cameraLog = bag.cameraLog || [];
+    bag.cameraLog.push({ at: Date.now(), line, data });
+    if (bag.cameraLog.length > 200) bag.cameraLog.shift(); // 只留最近 200 条供断言
+    console.info('%c[CAMERA]', 'color:#1fc0c5', line);
+    if (bag.debugLog) {
+      try {
+        const opts = { level: 'info', src: 'camera' };
+        if (data !== undefined && data !== null) opts.data = data; // 结构化字段独立，不拼进正文
+        bag.debugLog.log('CAMERA', line, opts);
+      } catch { /* 日志失败不影响业务 */ }
+    }
+  });
+  return true;
+}

package/src/web/app/context.js

@@ -0,0 +1,72 @@
+// app/context.js —— 页面级共享上下文（DOM 引用、状态容器、舞台实例）
+//
+// 为什么要单独成模块：main.js 只做装配，各功能模块（状态行、视图设置、部件筛除、外壳控件…）
+//   都要读同一份 state / dom / stage。用一个共享上下文模块把它们接起来，避免层层传参。
+//
+// 关键点：stage 是**可变绑定**（boot 时创建、WebGL 不可用时保持 null）。ESM 的 import 是活绑定，
+//   所以其它模块 `import { stage }` 能实时看到这里的新值；main.js 通过 setStage() 赋值
+//   （模块外不能直接给导入的绑定赋值）。
+
+/**
+ * 自动化断言与手工排查的唯一读取口。必须**尽早**建好：boot 早期就有状态日志要落盘、
+ *   有 hangGuard/panelSelfCheck 等计数要暴露，晚建会让这些记录静默丢失（实测踩过）。
+ */
+window.__WEB__ = window.__WEB__ || {};
+
+/** 各区域 DOM 引用：集中取一次，避免函数里反复 querySelector */
+export const dom = {
+  leftPanel: document.getElementById('left-panel'),
+  rosterList: document.getElementById('roster-list'),
+  rosterCount: document.getElementById('roster-count'),
+  rosterSearch: document.getElementById('roster-search'),
+  btnCollapse: document.getElementById('btn-collapse'),
+  brandTitle: document.getElementById('brand-title'),
+  brandIcon: document.getElementById('brand-icon'),
+  btnLibrary: document.getElementById('btn-library'),
+  btnMenu: document.getElementById('btn-menu'),
+  btnShot: document.getElementById('btn-shot'),
+  btnCinema: document.getElementById('btn-cinema'),
+  btnFullscreen: document.getElementById('btn-fullscreen'),
+  stageHint: document.getElementById('stage-hint'),
+  stageCanvas: document.getElementById('stage-canvas'),
+  panelHead: document.getElementById('panel-head'),
+  panelBody: document.getElementById('panel-body'),
+  footer: document.getElementById('app-footer'),
+  // 资源根管理（F4）
+  btnAddRoot: document.getElementById('btn-add-root'),
+  rootList: document.getElementById('root-list'),
+  rootMsg: document.getElementById('root-msg'),
+  rootCount: document.getElementById('root-count'),
+  btnRootToggle: document.getElementById('btn-root-toggle'),
+  rootManagerBody: document.getElementById('root-manager-body'),
+};
+
+/** Spine 渲染舞台：boot 时创建（WebGL 不可用时保持 null，UI 只提示不报错） */
+export let stage = null;
+
+/** 设置舞台实例（唯一写入口；外部模块通过 import 的活绑定读到新值） */
+export function setStage(next) {
+  stage = next;
+  return stage;
+}
+
+/** 最小状态容器（M7 会扩展成带持久化的 store） */
+export const state = {
+  // 表现侧开关（与渲染器无关，由外壳自己维护）：状态行显隐 / 调试日志浮层 / 防卡死保护
+  showStatus: true,
+  debugLog: true,
+  hangGuard: true,
+  debugLogHandle: null,
+  debugPanel: null,
+  debugPanelHost: null,
+  hangGuardTimer: null,
+  hangGuardStats: null,
+  roots: [],
+  rootsError: null,
+  leftPanelVisible: true,
+  selectedModel: null,
+  // 当前渲染器：核心不再直接持有相机，统一从它取（现阶段只有 2D 一个实现）
+  currentRenderer: null,
+  /** 播放状态唯一真相（true=播放中）：UI 与引擎都从它派生，不许各存一份 */
+  playing: true,
+};