modelstage 0.0.0-stage → 0.5.28

package/src/web/app/topbar-actions.js

@@ -0,0 +1,357 @@
+// app/topbar-actions.js —— 顶栏两个"真动作"：截图导出、影院模式
+//
+// 为什么单独成模块：main.js 只做装配（≤400 行），动作实现放这里，顶栏与面板无关。
+//
+// 两条实现要点：
+//   ① 截图不能直接 canvas.toDataURL()：WebGL 默认不保留绘制缓冲，合成后内容可能已经没了。
+//      这里走 gl.readPixels（刚画完的同一任务里取），再翻转到 2D 画布，最后 toBlob 下载。
+//      Live2D 覆盖层叠加同一张图上（drawImage），所以两种渲染器都能截到。
+//   ② 影院模式只是切 <html data-cinema>，显隐与位移全在 style.css 里；JS 只负责状态切换
+//      与"静止数秒淡出播放条"（data-idle），不碰任何几何。
+
+import { stage, state } from './context.js';
+import { stageLog, stageStatus } from './status.js';
+import { repaintActive } from '../render/playback.js';
+import * as uiState from './ui-state.js';
+import { captureActive } from '../render/capture.js';
+import { flushNow, resetStages, trackElementStage } from '../infra/ready.js';
+
+/** 影院模式下静止多久把播放条淡出（毫秒）；鼠标一动就回来 */
+const CINEMA_IDLE_MS = 3000;
+
+let idleTimer = null;
+/** 静止唤醒的监听器引用：单独存，不能挂在定时器句柄上（浏览器里 timeout id 是数字） */
+let idleWake = null;
+
+/** 文件名里的模型名：去掉路径分隔与空白，避免下载文件名非法 */
+function safeName(raw) {
+  return String(raw || 'model')
+    .replace(/[\\/:*?"<>|\s]+/g, '_')
+    .slice(0, 48) || 'model';
+}
+
+/** 时间戳：YYYYMMDD-HHMMSS（本地时间，用户看文件名就能认时间） */
+function stamp(d) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-`
+    + `${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/**
+ * 截图导出：canvas → blob → 触发下载；文件名带模型名与时间戳。
+ * 内容同时留在 __WEB__.screenshotExport 供自动化断言（无头环境无法确认真实落盘）。
+ */
+export function exportScreenshot() {
+  // 先让**当前渲染面**补一帧：暂停时引擎/渲染循环都停着，不补就会截到旧帧或空帧
+  try { repaintActive(state.surface); } catch { /* 画不出新帧就用现成缓冲 */ }
+  try {
+    const engine = stage && stage.debug ? stage.debug().engine : null;
+    if (engine && typeof engine.presentFirstFrame === 'function') engine.presentFirstFrame();
+  } catch { /* 引擎不支持就用现成缓冲 */ }
+  // 画面来源交给**当前渲染器**（以前这里写死 #stage-canvas，Live2D 面会导到上次 Spine 的残留帧）
+  const composed = captureActive(state.surface);
+  if (!composed) {
+    stageLog('error', '截图失败：当前渲染面尚未就绪', { renderer: String(state.currentRenderer && state.currentRenderer.id || '') });
+    return false;
+  }
+  // 模型名优先取名册选中的那个；直连 stage.load（脚本/恢复）时没有 selectedModel，
+  //   回落到引擎侧记的模型名，避免导出成 modelstage-model-*.png 这种没信息量的名字
+  let modelName = (window.__WEB__ && window.__WEB__.state && window.__WEB__.state.selectedModel)
+    ? window.__WEB__.state.selectedModel.name : null;
+  if (!modelName) {
+    try {
+      const snap = stage && typeof stage.stats === 'function' ? stage.stats() : null;
+      modelName = (snap && snap.model && snap.model.name) || null;
+    } catch { modelName = null; }
+  }
+  const model = modelName || 'model';
+  const filename = `modelstage-${safeName(model)}-${stamp(new Date())}.png`;
+  const finish = (bytes) => {
+    window.__WEB__ && (window.__WEB__.screenshotExport = {
+      filename, bytes, width: composed.width, height: composed.height,
+      source: composed.source, digest: composed.digest, nonEmpty: composed.nonEmpty, model,
+    });
+    document.documentElement.dataset.screenshot = `${filename}|${bytes}`;
+    stageStatus(`已导出截图：${filename}（${composed.width}×${composed.height}，${bytes} 字节）`, 'info', { show: true });
+  };
+  try {
+    if (typeof composed.canvas.toBlob === 'function') {
+      composed.canvas.toBlob((blob) => {
+        const bytes = blob ? blob.size : 0;
+        if (blob) {
+          const url = URL.createObjectURL(blob);
+          const link = document.createElement('a');
+          link.href = url;
+          link.download = filename;
+          document.body.append(link);
+          link.click();
+          link.remove();
+          setTimeout(() => URL.revokeObjectURL(url), 1000);
+        }
+        finish(bytes);
+      }, 'image/png');
+      return true;
+    }
+    // 极老环境兜底：dataURL 直接当下载地址
+    const href = composed.canvas.toDataURL('image/png');
+    const link = document.createElement('a');
+    link.href = href;
+    link.download = filename;
+    document.body.append(link);
+    link.click();
+    link.remove();
+    finish(href.length);
+    return true;
+  } catch (err) {
+    stageLog('error', `截图失败：${(err && err.message) || err}`, { err: String((err && err.message) || err) });
+    return false;
+  }
+}
+
+/** 影院模式下的静止淡出：鼠标一动把 data-idle 切回 off，静止 CINEMA_IDLE_MS 后再切 on */
+function startIdleWatch() {
+  stopIdleWatch();
+  const root = document.documentElement;
+  const wake = () => {
+    root.dataset.idle = 'off';
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (root.dataset.cinema === 'on') root.dataset.idle = 'on';
+    }, CINEMA_IDLE_MS);
+  };
+  wake();
+  idleWake = wake;
+  window.addEventListener('pointermove', wake, { passive: true });
+  window.addEventListener('pointerdown', wake, { passive: true });
+}
+
+function stopIdleWatch() {
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+    idleTimer = null;
+  }
+  if (idleWake) {
+    window.removeEventListener('pointermove', idleWake);
+    window.removeEventListener('pointerdown', idleWake);
+    idleWake = null;
+  }
+  document.documentElement.dataset.idle = 'off';
+}
+
+/** 过渡相关的阶段 → 元素选择器（只这三处会"事后过渡"） */
+const STAGE_SELECTORS = {
+  topbar: '#app-header',
+  sidebarLeft: '#left-panel',
+  sidebarRight: '#right-panel',
+};
+
+/** 各阶段当前的跟踪句柄（stop()）：重置前必须先停掉，否则两个跟踪器叠着跑 */
+const stageHandles = new Map();
+/** 待重新起算的阶段（同帧合并用）与其 rAF 句柄 */
+const pendingRetrack = new Set();
+let rafId = 0;
+
+/**
+ * 过渡开始时重新起算某阶段的就绪状态。
+ *
+ * 为什么需要：topbar / sidebarLeft / sidebarRight 在启动时走到 interactive 就 stop() 了，
+ *   之后影院模式、侧栏收展**不再上报任何状态**；于是 `waitStage(name,'settled')` 会拿启动时
+ *   的旧 interactive 立刻返回（rank 已够），等于没等——这是测试里那些"事后过渡等待"换不掉 sleep 的根因。
+ * 做法：先停旧句柄（连续快点以最后一次为准，不叠跟踪器）→ resetStage 回到初始态 →
+ *   用与启动时同一套判据重新跟踪（无动画 + 两次包围盒一致 ⇒ settled），不另写一套。
+ * @param {string} name 阶段名
+ * @returns {boolean} 是否重新起了跟踪
+ */
+export function retrackStage(name) {
+  return retrackStages([name]) > 0;
+}
+
+/**
+ * 批量版：一次交互牵动多个阶段时用它——**整批只上报一次**就绪快照。
+ *
+ * **延到下一帧执行**（不是立即）：调用点都是"改完 class/dataset 就调"，
+ *   若同一帧里既做样式重算又做就绪上报（resetStage → flushNow → fetch 的序列化+发起），
+ *   两者会抢同一帧；而且就绪信号的语义本来就是"等布局稳定"，早一帧上报反而更容易抓到中间态。
+ *   先把 class 变化交还浏览器去重算，下一帧再起算就绪状态。
+ *   同帧内多次调用会合并成一次（连点仍以最后一次为准，不叠加跟踪器）。
+ * @param {string[]} names 阶段名数组
+ * @returns {number} 已受理的阶段数（实际执行在下一帧）
+ */
+export function retrackStages(names) {
+  const list = (Array.isArray(names) ? names : []).filter((n) => STAGE_SELECTORS[n]);
+  if (!list.length) return 0;
+  for (const n of list) pendingRetrack.add(n);
+  if (!rafId) {
+    // 无 rAF 的环境（测试垫片/极老浏览器）就同步执行，保证功能不丢
+    rafId = typeof requestAnimationFrame === 'function'
+      ? requestAnimationFrame(runPendingRetrack)
+      : (runPendingRetrack(), 0);
+  }
+  return list.length;
+}
+
+/** 同帧合并后的真正执行体（原先 retrackStages 的实现） */
+function runPendingRetrack() {
+  rafId = 0;
+  const list = [...pendingRetrack];
+  pendingRetrack.clear();
+  if (!list.length) return;
+  // ① 先停旧句柄（连点以最后一次为准，不叠跟踪器）
+  for (const n of list) {
+    const prev = stageHandles.get(n);
+    if (prev) { try { prev(); } catch { /* 已停 */ } stageHandles.delete(n); }
+  }
+  // ② 批量重置：这里**不单独上报**——紧接着的重新跟踪会在第一拍 markStage('mounted')，
+  //    两者落在同一个去抖窗口里 ⇒ 整次交互只发 1 个 POST（实测：影院切换 1 次 = 1 次上报）
+  resetStages(list, { flush: false });
+  // ③ 用启动时同一套判据重新跟踪
+  let started = 0;
+  for (const n of list) {
+    const el = document.querySelector(STAGE_SELECTORS[n]);
+    if (!el) continue;
+    const stop = trackElementStage({ name: n, el });
+    if (typeof stop === 'function') stageHandles.set(n, stop);
+    started += 1;
+  }
+  // 兜底：元素不在（或跟踪没起来）就没人触发上报，此时必须自己把 reset 发出去
+  if (!started) flushNow();
+}
+
+/**
+ * 影院模式开/关：只切 <html data-cinema>，显隐与位移全交给 style.css。
+ * @param {boolean} [force] 传 true/false 强制设值；不传则翻转
+ * @returns {boolean} 切换后的状态
+ */
+export function toggleCinema(force) {
+  const root = document.documentElement;
+  const next = typeof force === 'boolean' ? force : root.dataset.cinema !== 'on';
+  root.dataset.cinema = next ? 'on' : 'off';
+  // 顶栏与两侧栏一起做位移过渡 ⇒ 三个阶段的就绪状态重新起算（进入/退出都算）。
+  //   用批量接口：整批只上报一次（逐个重置会各发一次 POST，慢机器上会变成一串 ERR_ABORTED）。
+  retrackStages(['topbar', 'sidebarLeft', 'sidebarRight']);
+  const btn = document.getElementById('btn-cinema');
+  if (btn) btn.setAttribute('aria-pressed', String(next));
+  syncSidebarButtons(); // 影院模式隐藏了两侧栏，两个开关的高亮也要跟着灭/亮
+  if (next) startIdleWatch(); else stopIdleWatch();
+  stageStatus(`影院模式：${next ? '开（隐藏顶栏与左右栏，Esc 退出）' : '关'}`, 'info', { show: true });
+  return next;
+}
+
+/**
+ * 边栏"实际可见"判定：收起是靠 translateX 移出视口，所以看几何而不是看状态变量。
+ * 这样影院模式、面板头「收起菜单」、按钮切换、CSS 过渡中都能得到同一口径的答案。
+ * @param {HTMLElement|null} el
+ * @param {'left'|'right'} side
+ * @returns {boolean}
+ */
+function isPanelOnScreen(el, side) {
+  if (!el) return false;
+  const root = document.documentElement;
+  // ① 状态量优先：影院模式 / 收起状态 / is-hidden 都是"确定要隐藏"，过渡动画没走完也该立刻判定为隐藏，
+  //    否则点击后要等 transitionend 才更新高亮，读起来像"慢了半拍"。
+  const declaredHidden = side === 'left'
+    ? (root.dataset.cinema === 'on' || root.dataset.left === 'off' || el.classList.contains('is-hidden'))
+    : (root.dataset.cinema === 'on' || root.dataset.right === 'off');
+  if (declaredHidden) return false;
+  // ② 几何兜底：没有被状态量宣布隐藏时，以真实位置为准（窗口过窄/面板被外部样式挤掉等情况）
+  const r = el.getBoundingClientRect();
+  if (!r.width || !r.height) return false;
+  return side === 'left' ? r.right > 8 : r.left < window.innerWidth - 8;
+}
+
+/**
+ * 把顶栏两个边栏开关的高亮同步到边栏的真实显隐状态。
+ * 高亮只认这一处结论：按钮自己 toggle class 不算，影院模式关掉边栏时也必须跟着灭。
+ * @returns {{leftOn: boolean, rightOn: boolean}}
+ */
+export function syncSidebarButtons() {
+  const leftOn = isPanelOnScreen(document.getElementById('left-panel'), 'left');
+  const rightOn = isPanelOnScreen(document.getElementById('right-panel'), 'right');
+  const btnLeft = document.getElementById('btn-library');
+  const btnRight = document.getElementById('btn-menu');
+  if (btnLeft) {
+    btnLeft.setAttribute('aria-pressed', String(leftOn)); // 高亮态由 aria-pressed 驱动（样式在 components.css）
+    btnLeft.setAttribute('aria-expanded', String(leftOn));
+    btnLeft.dataset.sidebarState = leftOn ? 'shown' : 'hidden';
+  }
+  if (btnRight) {
+    btnRight.setAttribute('aria-pressed', String(rightOn));
+    btnRight.dataset.sidebarState = rightOn ? 'shown' : 'hidden';
+  }
+  document.documentElement.dataset.leftState = leftOn ? 'on' : 'off';
+  document.documentElement.dataset.rightState = rightOn ? 'on' : 'off';
+  return { leftOn, rightOn };
+}
+
+/**
+ * 订阅所有会改变边栏显隐的动作（按钮/影院/收起/过渡/缩放），统一回调同步高亮。
+ * 只绑一次；CSS 过渡结束再同步一次，避免"点完立刻读位置"读到动画中间值。
+ */
+export function bindSidebarStateSync() {
+  if (bindSidebarStateSync.done) return false;
+  bindSidebarStateSync.done = true;
+  for (const id of ['left-panel', 'right-panel']) {
+    const el = document.getElementById(id);
+    if (el) el.addEventListener('transitionend', () => syncSidebarButtons());
+  }
+  window.addEventListener('resize', () => syncSidebarButtons());
+  syncSidebarButtons();
+  return true;
+}
+
+/**
+ * 右侧控制面板显隐（顶栏「菜单」与面板头「收起菜单」共用一个开关）。
+ * 状态写在 <html data-right>，位移与淡出全在 style.css；顶栏按钮 aria-pressed 同步，
+ * 这样"面板被收起后怎么找回来"有明确答案：顶栏「菜单」。
+ * @param {boolean} [force] 传 true/false 强制设值；不传则翻转
+ * @returns {boolean} 切换后的状态（true=显示）
+ */
+export function toggleRightPanel(force) {
+  const root = document.documentElement;
+  const open = typeof force === 'boolean' ? force : root.dataset.right === 'off';
+  root.dataset.right = open ? 'on' : 'off';
+  // S4：记下这次手动选择（左栏沿用当前值，互不覆盖）
+  uiState.setLayout({ rightVisible: open });
+  // 右栏位移是一次过渡 ⇒ 它的就绪状态重新起算（只重置右栏，别的阶段不受影响）
+  retrackStage('sidebarRight');
+  syncSidebarButtons(); // 高亮跟随真实显隐（不在这里自己写 class）
+  stageStatus(`右侧控制面板：${open ? '显示' : '收起（顶栏「菜单」可再打开）'}`, 'info', { show: true });
+  return open;
+}
+
+/**
+ * 退出影院模式（**仅在影院态下才有动作**）。
+ *
+ * 为什么要有这个守卫：toggleCinema(false) 在"本来就没进影院"时也会写状态、重排阶段、记一条日志，
+ *   按 Esc 反复触发会刷出一串无意义的「影院模式：关」。Esc 的语义是"只退不进"。
+ * @returns {boolean} 是否真的退出了
+ */
+export function exitCinemaIfActive() {
+  if (document.documentElement.dataset.cinema !== 'on') return false;
+  toggleCinema(false);
+  return true;
+}
+
+/**
+ * 影院模式的**鼠标**入口：舞台中心区域双击进出。
+ * 为什么限定中心区域：四角/边缘留给拖拽与面板操作，避免"想微调视角却把界面收掉"。
+ * 双击判定用原生 dblclick（两次 click 间隔由浏览器判定），无需自己计时。
+ *
+ * 键盘入口不在这里：Esc 退出 / H 切换统一登记在 infra/shortcuts.js（唯一键盘真相源）。
+ */
+export function bindCinemaKeys() {
+  const stageEl = document.getElementById('stage');
+  if (stageEl) {
+    stageEl.addEventListener('dblclick', (e) => {
+      const box = stageEl.getBoundingClientRect();
+      if (!box.width || !box.height) return;
+      // 中心 60% 区域内才算"中心双击"
+      const nx = (e.clientX - box.left) / box.width;
+      const ny = (e.clientY - box.top) / box.height;
+      const inCenter = nx > 0.2 && nx < 0.8 && ny > 0.2 && ny < 0.8;
+      if (!inCenter) return;
+      e.preventDefault();
+      toggleCinema();
+    });
+  }
+}

package/src/web/app/transport-actions.js

@@ -0,0 +1,297 @@
+// app/transport-actions.js —— 底栏播放条上的动作实现
+//
+// 播放条控件（播放/暂停、上/下一条变体、背景切换、动作下拉、皮肤下拉）都只操作"当前内容"，
+// 与渲染器实现无关，所以统一放这里。状态一律经 state.transport 的句柄落到 DOM，
+// 同时打 dataset 供自动化断言读。
+
+import { dom, stage, state } from './context.js';
+import { setPlaybackPaused } from '../render/playback.js';
+import { getRendererSetting, setRendererSetting } from './renderer-setting.js';
+import { stageLog, stageStatus } from './status.js';
+import { buildChars, createNameIndex, mergeNameTable, loadRootNames } from '../roster/list.js';
+import { formatError } from '../infra/api.js';
+import {
+  buildAnimationList, isCycleLoop, labelWithDuration, notePlaying, playAnimation, setCycleLoop,
+} from './anim-list.js';
+
+/** 播放/暂停：切换引擎播放并同步按钮按下态与 dataset（进 CAMERA 之外的状态日志） */
+/**
+ * 播放/暂停统一入口（render/playback.js）：按当前渲染面派发，
+ * 调用方不判断"现在是哪一面"，也不直连 stage（stage 恒为 Spine 舞台）。
+ * @param {boolean} paused
+ */
+function applyPlaybackPaused(paused) {
+  try { return setPlaybackPaused(state.surface, paused); } catch { return 'none'; }
+}
+
+/**
+ * 播放状态的唯一真相 = state.playing。
+ * UI（图标 / title / aria-pressed / dataset）与引擎状态都由它派生，不各存一份。
+ * @param {boolean} on true=播放中，false=已暂停
+ * @param {{silent?: boolean}} [opts]
+ */
+function setPlaying(on, opts = {}) {
+  const next = !!on;
+  const prev = state.playing === true;
+  state.playing = next;
+  state.playbackPath = applyPlaybackPaused(!next);   // 记账：便于验收贴"走了哪条通路"
+  syncPlayUi();
+  if (!opts.silent && prev !== next) stageStatus(next ? '继续播放' : '已暂停（画面与动作都停住）', 'info');
+  return next;
+}
+
+/** UI 派生：图标（播放中显示"暂停"语义）、title、aria-pressed、dataset 全部跟随 state.playing */
+function syncPlayUi() {
+  const playing = state.playing !== false;
+  if (state.transport) state.transport.setPressed('transport-play', playing);
+  if (state.transport && state.transport.setIcon) state.transport.setIcon('transport-play', playing ? 'pause' : 'play');
+  document.documentElement.dataset.transportPlaying = playing ? 'on' : 'off';
+}
+
+/**
+ * 动作混合（过渡渐变）默认开启，且**面板里没有这个开关**（schema 标了 hidden）。
+ * 没有开关就没人会去打开它，所以由应用层在首次装载时显式落地一次；
+ * 已生效则不重复下发（幂等，避免每次换模型都改一次引擎设置）。
+ */
+function ensureMixModeOn() {
+  if (state.mixModeEnsured === true) return;
+  state.mixModeEnsured = true;
+  try { setRendererSetting('mixMode', true); } catch { /* 该面不支持就跳过 */ }
+  state.mixMode = true;
+  document.documentElement.dataset.mixMode = 'on';
+}
+
+/** 底栏「播放/暂停」：切换 */
+function toggleTransportPlay() {
+  setPlaying(state.playing === false);
+}
+/** 单动循环：切换 settings.loop（引擎 setLoop 走通用 setter） */
+/**
+ * 判断两个条目是否属于「同一个角色（同一组变体）」。
+ *
+ * 字段来源不统一：catalog 条目用 `srcDir`（根内相对目录），旧 models 条目用 `directory`（带根名前缀）。
+ * 优先比 srcDir，缺失时回落到 directory —— 两边都取不到就判为不同组，宁可不合并也不乱合并。
+ * @param {object} m 候选条目
+ * @param {object} cur 当前模型
+ * @param {string} dir 当前模型的目录（兜底）
+ * @returns {boolean}
+ */
+/**
+ * 把条目补成"可装载形态"（**兜底**：树里的条已自带 entry.url）。
+ *
+ * 为什么需要：/api/catalog 的条目自带 `entry.url`，但历史路径（如从别处传入的裸模型对象）
+ *   可能只有 `skeletonFile`；这里统一补齐，避免装载入口报"条目缺少资产地址"。
+ * @param {object} m 模型条目
+ * @returns {object} 补好 entry 的条目（已有 entry 时原样返回）
+ */
+function withEntry(m) {
+  if (!m || typeof m !== 'object') return m;
+  if (m.entry && m.entry.url) return m;
+  const url = (m.skeletonFile && m.skeletonFile.url) || m.modelUrl || null;
+  return url ? { ...m, entry: { url } } : m;
+}
+
+/** 取名册树实例（翻页的池子与"同角色变体"都从它取，见下方说明） */
+function rosterApi() {
+  const r = state.roster;
+  return r && typeof r.listVariants === 'function' && typeof r.variantsOf === 'function' ? r : null;
+}
+
+/**
+ * 装载并同步左栏（统一入口；装载实现仍然是 model-actions 的 onSelectModel）。
+ * @param {object} model
+ */
+async function applyPicked(model) {
+  const { selectModel } = await import('./model-actions.js');
+  selectModel(withEntry(model));
+}
+
+/**
+ * 翻变体（同一角色的不同皮肤/服装）。
+ * @param {number} dir -1 上一个 / +1 下一个
+ * @param {object[]} [peersArg] 已取到的兄弟列表（调用方复用查询结果时传）
+ */
+async function stepVariant(dir, peersArg) {
+  const cur = state.selectedModel;
+  if (!cur) { stageLog('warn', '切换变体失败：当前没有选中的模型', { reason: 'no-current-model' }); return; }
+  const api = rosterApi();
+  if (!api) { stageLog('warn', '切换变体失败：名册树尚未就绪', { reason: 'no-roster' }); return; }
+  const peers = peersArg || (await api.variantsOf(cur.id));
+  if (peers.length < 2) { stageLog('warn', '切换变体失败：当前角色只有 1 个变体', { peers: peers.length }); return; }
+  const at = peers.findIndex((p) => p.model && p.model.id === cur.id);
+  const next = peers[(Math.max(at, 0) + dir + peers.length) % peers.length];
+  if (!next || !next.model) return;
+  stageStatus(`切换变体 → ${next.model.name}`, 'info');
+  await applyPicked(next.model);
+}
+
+/**
+ * 翻模型（**按左栏树从上到下的顺序**，末尾回绕）。
+ *
+ * 池子必须是树，不能是某个接口的清单：
+ *   树的「游戏」节点是**同名根合并**出来的（例如「碧蓝航线」= azurlane + azurlane_spine + azurlane_bundle），
+ *   按单个 rootId 取清单会漏掉同名的其它根 ⇒ 表现为"只能在 live2d 之间翻、翻不到 spine"（实测过的现场）。
+ * @param {number} dir -1 上一个 / +1 下一个
+ * @param {object[]} [flatArg] 已取到的树序序列
+ */
+async function stepModel(dir, flatArg) {
+  const cur = state.selectedModel;
+  if (!cur) { stageLog('warn', '切换模型失败：当前没有选中的模型', { reason: 'no-current-model' }); return; }
+  const api = rosterApi();
+  if (!api) {
+    stageLog('warn', '切换模型失败：名册树尚未就绪', { reason: 'no-roster' });
+    stageStatus('切换失败：模型列表尚未就绪', 'warn');
+    return;
+  }
+  let flat = flatArg;
+  if (!flat) {
+    try { flat = await api.listVariants(); } catch (err) {
+      stageLog('error', `切换模型失败：读取模型列表出错（${formatError(err)}）`, { err: formatError(err) });
+      stageStatus('切换失败：读取模型列表出错', 'warn');
+      return;
+    }
+  }
+  if (!flat || flat.length === 0) {
+    stageLog('warn', '切换模型失败：当前没有可切换的模型', { total: 0 });
+    stageStatus('当前没有可切换的模型', 'warn');
+    return;
+  }
+  if (flat.length === 1) {
+    stageLog('warn', '切换模型失败：库中只有 1 个模型', { total: 1 });
+    stageStatus('库中只有 1 个模型，没有可切换的下一个', 'warn');
+    return;
+  }
+  const at = flat.findIndex((p) => p.model && p.model.id === cur.id);
+  const from = at < 0 ? (dir > 0 ? -1 : 0) : at;
+  const nextAt = (from + dir + flat.length) % flat.length;
+  const next = flat[nextAt];
+  if (!next || !next.model) return;
+  // 回绕提示只在真的"跳过头"时出现：往后翻到第 0 个、往前翻到最后一个
+  if (dir > 0 && nextAt === 0 && at !== 0) stageStatus('已返回第一个模型', 'info');
+  else if (dir < 0 && nextAt === flat.length - 1 && at !== flat.length - 1) stageStatus('已到最后一个模型（回绕）', 'info');
+  else stageStatus(`切换模型 → ${next.model.name}`, 'info');
+  await applyPicked(next.model);
+}
+
+/**
+ * 「上一个 / 下一个」的唯一入口（快捷键 A/S 与底栏两个按钮共用）。
+ *
+ * 粒度：当前角色有多个变体 ⇒ 翻变体（想看的是同角色另一套衣服）；否则 ⇒ 按树序翻模型。
+ * @param {number} dir -1 上一个 / +1 下一个
+ */
+async function stepUnit(dir) {
+  const cur = state.selectedModel;
+  if (!cur) { stageLog('warn', '上一个/下一个失败：当前没有选中的模型', { reason: 'no-current-model' }); return; }
+  const api = rosterApi();
+  if (!api) {
+    stageLog('warn', '上一个/下一个失败：名册树尚未就绪', { reason: 'no-roster' });
+    stageStatus('切换失败：模型列表尚未就绪', 'warn');
+    return;
+  }
+  const peers = await api.variantsOf(cur.id);
+  if (peers.length > 1) { await stepVariant(dir, peers); return; }
+  await stepModel(dir);
+}
+
+
+/** 动作下拉选择：切动画并回填 dataset；右栏高亮与下拉互相跟随（同一份清单） */
+function applyTransportMotion(id) {
+  if (!id) return;
+  // ① 先立真相：任何"读当前动作"的地方（面板重绘、底栏回显）都必须先看到新值，
+  //    否则播放过程中触发的重绘会用旧值把高亮刷回去（实测过的坑）。
+  state.transportMotion = String(id);
+  document.documentElement.dataset.transportMotion = String(id);
+  // ② 再播放：playAnimation 只负责让引擎播，不碰面板（职责分离）
+  const ok = playAnimation(id);
+  // 当前动作的唯一真相是底栏下拉（契约 §七）：不管从哪一处触发，都把下拉同步到这条
+  if (state.transport) state.transport.setSelectValue('transport-motion', id);
+  // 用自定义事件请求重绘，而不是 import 面板模块：
+  //   ① 面板句柄在重建瞬间可能是"半成品"（state.panel 尚未挂 refreshAnimations）；
+  //   ② app 与 panel 互相 import 会形成**循环依赖**，实测会让页面脚本异常。
+  //   事件解耦：谁关心谁监听，app 层不需要知道面板内部结构。
+  if (typeof document !== 'undefined') {
+    document.dispatchEvent(new CustomEvent('panel:refresh-animations'));
+  }
+  if (ok) stageStatus(`动作 → ${id}`, 'info');
+  else stageLog('warn', `动作 → ${id}（引擎拒绝，保持原动作）`, { id, reason: 'renderer-rejected' });
+}
+/**
+ * 循环播放（右栏「动作」组开关，契约 §四）：
+ *   开 = 按列表顺序逐条播完剩余动作、末尾回到第一条并持续；关 = 停留当前动作重复播。
+ * 与「混合模式」正交：混合模式只管切换瞬间的过渡（引擎 mixTime），这里只管"播完接谁"，
+ *   两者互不调用、互不改写对方状态。
+ * @param {boolean} on
+ * @returns {boolean} 落地后的状态
+ */
+function applyAnimLoop(on) {
+  setCycleLoop(!!on);
+  state.animLoop = !!on;
+  document.documentElement.dataset.animLoop = on ? 'on' : 'off';
+  if (state.panel && typeof state.panel.setChecked === 'function') state.panel.setChecked('ctl-anim-loop', !!on);
+  return !!on;
+}
+
+/** 模型加载完成后填充播放条：动作下拉 + 播放状态 */
+function fillTransportOptions(info) {
+  ensureMixModeOn();   // 混合模式默认开启（面板已隐藏该开关，必须由应用层落地）
+  const transport = state.transport;
+  if (!transport) return;
+  // 首次填充顺带刷一次播放 UI：dataset / 图标 / 文案都由 state.playing 派生（幂等）
+  syncPlayUi();
+  // 与右栏同一份清单（同顺序、同文案、同时长）：契约 §一/§三
+  const list = buildAnimationList();
+  if (list.length) {
+    const preferred = (info && info.motion) || '';
+    const startId = list.some((x) => x.id === preferred) ? preferred : list[0].id;
+    transport.setOptions('transport-motion', list.map((x) => ({ text: labelWithDuration(x), value: x.id })), startId);
+    notePlaying(startId);
+  }
+  // 不在这里直读 stage.stats().playing：stage 恒为 Spine 舞台，Live2D 面会被它带偏，
+  //   而且暂停状态只能有一个来源（state.playing）→ 统一走 syncPlayUi 派生。
+  syncPlayUi();
+}
+/** 混合模式：两处开关指向同一状态，点任一处都要同步另一处的显示 */
+/**
+ * 混合模式（动作组）：只控制**动画切换**是否交叉淡化（引擎 mixTime 0.2s / 0）。
+ * 与「皮肤」组那个开关是两件独立的事：一个管动作过渡、一个管换肤过渡，
+ *   两个开关分开、互不同步。
+ */
+function applyMixMode(on) {
+  // 经渲染器下发（INV-01）：混合模式 = 动作切换是否交叉淡化，Spine 面有实现、Live2D 面没有
+  const { ok } = setRendererSetting('mixMode', !!on);
+  const applied = getRendererSetting('mixMode');
+  const value = ok && applied === true ? 0.2 : 0;
+  state.mixMode = !!on;
+  document.documentElement.dataset.mixMode = on ? 'on' : 'off';
+  return value;
+}
+
+/**
+ * 混合模式（皮肤组）：只控制**换肤**是否交叉淡化。
+ * 引擎没有独立的"皮肤混合"参数，所以实现方式是在换肤的那一刻临时套用 0.2s 混合，
+ *   换完立刻还原——这样动作与皮肤两个开关互不影响。
+ */
+function applySkinMix(on) {
+  state.skinMix = !!on;
+  document.documentElement.dataset.skinMix = on ? 'on' : 'off';
+  return state.skinMix;
+}
+
+/** 换肤时按「皮肤混合模式」决定是否临时淡入 */
+function skinSwitchMixTime(fn) {
+  // 换肤那一刻临时套用交叉淡化，换完立刻还原——动作/皮肤两个开关互不影响。
+  // 走渲染器（INV-01）；还原放在 finally 里，异常路径也不让皮肤混合状态漏在临时值上。
+  const want = state.skinMix === true;
+  setRendererSetting('mixMode', want);
+  try {
+    return fn();
+  } finally {
+    // 还原到"用户当前选择"（state.mixMode 才是权威），不是还原到临时值
+    setRendererSetting('mixMode', state.mixMode === true);
+  }
+}
+
+export {
+  toggleTransportPlay, setPlaying, syncPlayUi, stepVariant, stepModel, stepUnit, applyAnimLoop,
+  applyTransportMotion, fillTransportOptions, applyMixMode, applySkinMix, skinSwitchMixTime,
+};