modelstage 0.0.0-stage → 0.5.28

package/src/web/components.css

@@ -0,0 +1,524 @@
+/* 语义色 token：控件外观用到的语义色集中在这里定义（基础调色板在 style.css）。
+   抽成变量是为了换主题/深浅色时只改一处，而不是在十几处裸色值里逐个找。 */
+:root {
+  --color-accent-action: #2b6cb0;      /* 主操作按钮底色 */
+  --color-accent-action-hover: #3178c6;
+  --color-on-accent: #fff;             /* 主色/类型标签上的文字 */
+  /* 变体标签颜色**不在这里定义**：由插件在 plugin.json 里自声明 accent，
+     运行期以内联变量 --badge-accent 落到该元素上（见 roster/rows.js）。
+     这里只留一个"判不出归属"的中性兜底色，避免没声明的插件被涂成别人的颜色。 */
+  --color-type-unknown: #4a5568;       /* 变体标签：归属待定/未声明 */
+  --color-text-strong: #cfd6dd;        /* 变体行主文本 */
+  --color-text-dim: #9aa;              /* 展开箭头等弱提示 */
+  --color-orig-border: #4a5;           /* 角色行「原名」标签描边 */
+  --color-orig-text: #8a9;             /* 「原名」/计数字样 */
+  --color-icon-bg: #111;               /* 角色头像占位底 */
+  --color-text-muted: #8a94a0;         /* 变体行原名后缀等次级文本 */
+}
+
+/* ============================================================================
+   ModelStage 本实现 · 控件外观
+   只管"控件长什么样"：品牌、按钮、资源根列表、右栏分组行、底栏分组、错误横幅。
+   布局与几何在 style.css，两个文件由 index.html 一起引入。
+   ========================================================================== */
+
+/* ------------------------------------------------------------ 品牌（顶栏左） */
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+
+.brand-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  color: var(--color-primary);
+  font-size: 15px;
+  line-height: 1;
+}
+
+/* 内置 SVG（默认形态）：颜色跟随 .brand-icon 的 color */
+.brand-icon svg {
+  width: 16px;
+  height: 16px;
+  display: block;
+}
+
+/* 服务端下发图片图标时的 <img> */
+.brand-icon.is-image img {
+  width: 18px;
+  height: 18px;
+  object-fit: contain;
+  display: block;
+}
+
+.brand-title {
+  font-size: 13px;
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ---------------------------------------------------------------- 按钮 */
+
+.header-actions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  /* 内置 5 个按钮固定可见；插件按钮多时只让滚动区压缩，不挤动内置按钮 */
+  min-width: 0;
+}
+
+/* 插件按钮区：横向滚动、不换行（换行会把顶栏撑高）。
+   为什么给它上限宽度：顶栏是固定高度的一条，插件按钮无限增长必须有个"先滚起来"的边界；
+   取 min(42vw,460px) 是"常见分辨率下能放下 3~5 个、再多就滚"的折中。 */
+.header-plugin-actions {
+  display: flex;
+  /* 顶端对齐：滚动条在内容下方，若居中会把按钮整体抬高 2~3px（与内置按钮错位） */
+  align-items: flex-start;
+  gap: 6px;
+  flex-wrap: nowrap;
+  min-width: 0;
+  /* 上限取 min(30vw,320px)：实测 8 个按钮内容宽约 362px ⇒ 溢出并由容器滚动；
+     常见的 2~4 个按钮（约 80~160px）远小于上限，不会出现滚动条。 */
+  max-width: min(30vw, 320px);
+  /* 高度锁死成按钮高度（30px）：插件按钮与内置按钮必须同一条基线。
+     滚动条会占 6px —— 用 margin-bottom:-6px 把这 6px 抵消掉，
+     否则整条顶栏（nav）会被撑高、按钮也随之向上错位（实测 30px → 40px、错位 5px）。 */
+  /* 30px 按钮区 + 6px 滚动条 = 36px 内容高；只把**下边距**做成 -6px：
+     净高度回到 30px（nav 不被撑高），而顶端仍与内置按钮同一条基线。
+     上下对称的 -3px 会把整块上移 3px（实测插件按钮比内置高 3px）。 */
+  height: 36px;
+  margin-top: 0;
+  margin-bottom: -6px;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+  /* 滚动条：细、默认透明，悬停才显形（与整体克制风格一致） */
+  scrollbar-width: thin;
+  scrollbar-color: transparent transparent;
+}
+
+.header-plugin-actions:hover {
+  scrollbar-color: var(--color-border) transparent;
+}
+
+.header-plugin-actions::-webkit-scrollbar {
+  height: 6px;
+}
+
+.header-plugin-actions::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.header-plugin-actions::-webkit-scrollbar-thumb {
+  background: transparent;
+  border-radius: 3px;
+}
+
+.header-plugin-actions:hover::-webkit-scrollbar-thumb {
+  background: var(--color-border);
+}
+
+/* 按钮自身不压缩：滚动由容器负责，按钮保持方形/文字宽 */
+.header-plugin-actions > .icon-btn {
+  flex: 0 0 auto;
+}
+
+.icon-btn {
+  height: 30px;
+  padding: 0 10px;
+  display: inline-flex;
+  align-items: center;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  color: var(--color-foreground);
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+.icon-btn:hover {
+  background: var(--color-secondary);
+  border-color: var(--color-border);
+}
+
+/* 图标版顶栏按钮：方形、只放图标，名称走 aria-label/title */
+.icon-btn:has(> svg) {
+  width: 30px;
+  padding: 0;
+  justify-content: center;
+}
+
+.btn-icon {
+  display: inline-flex;
+  align-items: center;
+  margin-right: 4px;
+}
+
+.btn-icon > svg {
+  width: 14px;
+  height: 14px;
+  display: block;
+}
+
+.mini-btn.has-icon,
+.transport-group .mini-btn.has-icon {
+  display: inline-flex;
+  align-items: center;
+}
+
+.icon-btn > svg {
+  width: 17px;
+  height: 17px;
+  display: block;
+}
+
+/* 选中/开启态（模型库、菜单、影院这类开关型按钮）：主色描边 + 主色图标 */
+.icon-btn[aria-pressed='true'] {
+  color: var(--color-primary);
+  border-color: color-mix(in srgb, var(--color-primary) 45%, transparent);
+}
+
+.icon-btn[aria-pressed='false'] {
+  color: var(--color-muted-foreground);
+}
+
+.mini-btn {
+  height: 26px;
+  padding: 0 8px;
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  background: var(--color-muted);
+  color: var(--color-foreground);
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+.mini-btn:hover:not(:disabled) {
+  background: var(--color-secondary);
+}
+
+/* 主操作按钮（左栏「选择目录」）：配色*/
+.mini-btn.is-primary {
+  border-color: transparent;
+  background: var(--color-accent-action);
+  color: var(--color-on-accent);
+}
+
+.mini-btn.is-primary:hover:not(:disabled) {
+  background: var(--color-accent-action-hover);
+}
+
+/* 强调按钮（**描边式**）：表示"这一屏的主操作"，但不做高饱和实心。
+   为什么不用 .is-primary：它是实心高饱和 + 反白字，在暗色描边面板/对话框里像另一套设计。
+   应用处：左栏「选择目录」、目录对话框「添加」、对话框内「此目录已选中」——
+   三处必须看起来是同一套按钮，所以只允许这一个类，不许各自加样式。 */
+.mini-btn.is-accent {
+  border-color: var(--color-primary);
+  color: var(--color-primary);
+  background: color-mix(in srgb, var(--color-primary) 14%, transparent);
+  font-weight: 600;
+}
+
+.mini-btn.is-accent:hover:not(:disabled) {
+  border-color: var(--color-primary);
+  background: color-mix(in srgb, var(--color-primary) 22%, transparent);
+}
+
+/* ------------------------------------------------------------ 提示文案 */
+
+.muted-hint {
+  margin: 8px 4px;
+  color: var(--color-muted-foreground);
+  font-size: 11px;
+  line-height: 1.6;
+}
+
+/* ------------------------------------------------ 角色库：计数 / 搜索 / 三级树 */
+
+.panel-count {
+  flex: none;
+  padding: 6px 12px 0;
+  color: var(--color-muted-foreground);
+  font-size: 11px;
+  line-height: 1.4;
+}
+
+.panel-search {
+  flex: none;
+  padding: 6px 12px 8px;
+}
+
+.panel-search input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 5px 8px;
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  background: var(--color-muted);
+  color: var(--color-foreground);
+  font-size: 12px;
+  outline: none;
+}
+
+.panel-search input:focus {
+  border-color: var(--color-primary);
+}
+
+/* ------------------------------------------------------------ 类型筛选胶囊行 */
+
+/**
+ * 类型胶囊行（搜索框与名册列表之间）。
+ *
+ * 两个必须的几何约束（设计稿 §4.1 与 §10.2）：
+ *   ① **自动换行、不横向滚动**：类型数量由数据决定（今天 3 种，将来可能更多），
+ *      横向滚动在 304px 的窄栏里几乎不可用；
+ *   ② **单行最小高度**：类型从 2 行回落到 1 行时，若容器随之变矮，下面的列表会"猛地往上一跳"。
+ *      给 min-height 兜住这一档，高度变化只发生在真的加了一整行时。
+ */
+.roster-type-filter {
+  flex: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  min-height: 22px;            /* 单行高度：防列表因胶囊行消失/收缩而跳动 */
+  padding: 0 12px 8px;
+}
+
+.roster-type-filter[hidden] {
+  display: none;
+}
+
+/* 单个类型胶囊：复用 .mini-btn 的视觉语言（描边 + 底色），但高度更小、可换行 */
+.roster-type-chip,
+.roster-type-clear {
+  height: 22px;
+  padding: 0 8px;
+  border: 1px solid var(--color-border);
+  border-radius: 999px;
+  background: var(--color-muted);
+  color: var(--color-foreground);
+  font-size: 12px;
+  line-height: 20px;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.roster-type-chip:hover,
+.roster-type-clear:hover {
+  background: var(--color-secondary);
+}
+
+/* 选中态：主色描边 + 主色底（与工具栏 aria-pressed 同一套语义，颜色浓度略低以免抢眼） */
+.roster-type-chip[aria-pressed='true'] {
+  border-color: var(--color-primary);
+  color: var(--color-primary);
+  background: color-mix(in srgb, var(--color-primary) 18%, transparent);
+  font-weight: 600;
+}
+
+/* 「清除」比胶囊更轻：它是辅助动作，不该和类型胶囊抢视觉权重 */
+.roster-type-clear {
+  border-style: dashed;
+  color: var(--color-muted-foreground, var(--color-foreground));
+  opacity: 0.85;
+}
+
+.roster-list {
+  padding: 2px 0 8px;
+}
+
+/* 树行通用：一行 flex，靠 padding-left 表达层级 */
+.tree-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.tree-row:hover {
+  background: var(--color-secondary);
+}
+
+.tree-game {
+  padding-top: 6px;
+  padding-bottom: 6px;
+  font-weight: 600;
+}
+
+.tree-char {
+  padding-left: 22px;
+}
+
+.tree-variant {
+  padding-left: 40px;
+  color: var(--color-text-strong);
+}
+
+/* 展开箭头（内联 SVG）：不依赖字体，避免无桌面字体环境渲染成豆腐块 */
+.tree-arrow {
+  flex: 0 0 10px;
+  width: 10px;
+  height: 10px;
+  color: var(--color-text-dim);
+}
+
+.tree-game-name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* 资源根 id 徽标：区分同名资源根（如碧蓝的三个根） */
+.tree-badge {
+  flex: 0 0 auto;
+  padding: 0 5px;
+  border: 1px solid var(--color-border);
+  border-radius: 4px;
+  color: var(--color-primary);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 10px;
+  font-weight: 400;
+}
+
+.tree-icon {
+  flex: 0 0 26px;
+  width: 26px;
+  height: 26px;
+  object-fit: contain;
+  border-radius: 4px;
+  background: var(--color-icon-bg);
+}
+
+.tree-char-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* 角色行的「原名」标签（归一化键，与显示名不同才有信息增量） */
+.tree-orig {
+  flex: 0 0 auto;
+  padding: 0 3px;
+  border: 1px solid var(--color-orig-border);
+  border-radius: 3px;
+  color: var(--color-orig-text);
+  font-size: 10px;
+  font-weight: 400;
+}
+
+.tree-count {
+  flex: 0 0 auto;
+  color: var(--color-orig-text);
+  font-size: 11px;
+  font-weight: 400;
+}
+
+/* 未匹配名表的角色：右侧一个小红点（hover 有说明）。
+   为什么是一个点而不是文字/图标：名册是用户界面，红点只表达"这里没匹配上、值得看一眼"；
+   未命中通常是少数几条，做成常驻文字会把内部概念铺满整个列表。 */
+.tree-miss-dot {
+  flex: 0 0 auto;
+  width: 6px;
+  height: 6px;
+  margin-left: 2px;
+  border-radius: 50%;
+  background: var(--color-danger, #e05252);
+  cursor: help;
+}
+
+/* 变体行的类型标签：颜色**由插件声明**（内联 --badge-accent，来自 plugin.json 的 accent）。
+   这里不再有 kind → 颜色的映射：拿不到声明就落中性色，绝不替插件假装一种颜色。
+   （类名 tree-type-spine / -live2d / -bundle 仍由 roster/rows.js 打上，只作分组用，不再上色） */
+.tree-type {
+  flex: 0 0 auto;
+  padding: 0 5px;
+  border-radius: 4px;
+  background: var(--badge-accent, var(--color-type-unknown));
+  color: var(--color-on-accent);
+  font-size: 10px;
+}
+
+.tree-variant-text {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.tree-variant-orig {
+  flex: 0 1 auto;
+  color: var(--color-text-muted);
+  font-size: 11px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* 选中态：变体行高亮 */
+.tree-variant.is-selected {
+  background: rgba(31, 192, 197, 0.14);
+  box-shadow: inset 2px 0 0 var(--color-primary);
+  color: var(--color-primary);
+}
+
+.tree-hint {
+  padding-left: 22px;
+}
+
+/* --------------------------------------------------------- 底栏三组按钮 */
+
+.transport-group {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.transport-group:first-child {
+  justify-content: flex-start;
+}
+
+.transport-group:last-child {
+  justify-content: flex-end;
+}
+
+/* ----------------------------------------------------------- 错误横幅 */
+
+.error-banner {
+  margin: 8px 4px;
+  padding: 8px 10px;
+  border: 1px solid var(--color-danger);
+  border-radius: 6px;
+  background: rgba(224, 108, 117, 0.12);
+  color: var(--color-danger);
+  font-size: 11px;
+  line-height: 1.5;
+  word-break: break-all;
+}
+
+/* 资产残缺角标（catalog 里 missingTextures 非空的条目）
+   为什么显示而不是隐藏：这些条目点了会渲染失败，用户有权知道"为什么这个不行"，
+   并且有资源包版本时系统会自动改用（状态行会明确提示，不静默降级）。 */
+.tree-variant-warn {
+  color: #e8a33d;
+  margin-left: 4px;
+  font-size: 12px;
+  flex: none;
+}
+.tree-variant.is-incomplete .tree-variant-text {
+  opacity: 0.72;
+}

package/src/web/debug/diag-hud.js

@@ -0,0 +1,95 @@
+// diag-hud.js —— 渲染诊断 HUD（仅 URL 带 `?diag=1` 时创建）
+//
+// 为什么做成独立模块：诊断面板只读、零依赖、且不在正常路径上；
+//   单独一个文件便于审查「它绝不参与渲染决策」，也便于将来整文件删除。
+//
+// 用法（在 createLive2DStage 内）：
+//   installDiagHud({ getRendererInfo: rendererInfo, readCanvasPixels, overlayCanvasId });
+// 行为：不带 `diag=1` ⇒ 什么都不创建；带 ⇒ 右下角面板，每 500ms 刷新。
+
+/**
+ * 安装诊断 HUD。
+ * @param {{
+ *   getRendererInfo: () => object|null,
+ *   readCanvasPixels: (points: Array<[number, number]>) => Promise<Array<object>|null>,
+ *   overlayCanvasId: string,
+ *   log?: (message: string) => void,
+ * }} options
+ */
+export function installDiagHud({ getRendererInfo, readCanvasPixels, overlayCanvasId, log } = {}) {
+  try {
+    if (typeof document === 'undefined') return;
+    // 只认 diag=1；其它参数一律不启用（对正常渲染零影响）
+    const enabled = /[?&]diag=1(?:&|$)/.test(window.location.search || '');
+    if (!enabled) return { stop() {} };
+    if (document.getElementById('l2d-diag')) return;
+
+    const box = document.createElement('div');
+    box.id = 'l2d-diag';
+    // 样式改由 style.css 的 #l2d-diag 承担（契约：设计值不进 JS）
+
+    const head = document.createElement('div');
+    head.className = 'l2d-diag-head';
+    head.textContent = '【渲染诊断】点此折叠';
+    const body = document.createElement('div');
+    body.className = 'l2d-diag-body';
+    box.appendChild(head);
+    box.appendChild(body);
+    document.body.appendChild(box);
+
+    let collapsed = false;
+    head.addEventListener('click', () => {
+      collapsed = !collapsed;
+      box.classList.toggle('is-collapsed', collapsed);   // 折叠态交给 CSS
+      head.textContent = collapsed ? '【渲染诊断】已折叠（点此展开）' : '【渲染诊断】点此折叠';
+    });
+
+    /** 尺寸描述：attr / client */
+    const sizes = (el) => (el ? `${el.width}x${el.height} / ${el.clientWidth}x${el.clientHeight}` : 'n/a');
+
+    const update = async () => {
+      if (collapsed) return;
+      try {
+        const stageEl = document.getElementById('stage');
+        const spineCv = document.getElementById('stage-canvas');
+        const overlayCv = document.getElementById(overlayCanvasId);
+        const ri = (() => {
+          try { return getRendererInfo ? getRendererInfo() : null; } catch { return null; }
+        })();
+        if (!ri) {
+          body.textContent = `等待模型…（app 尚未就绪）
+viewport ${window.innerWidth}x${window.innerHeight}`;
+          return;
+        }
+        const rows = [
+          `viewport ${window.innerWidth}x${window.innerHeight}`,
+          `stageMode ${stageEl ? stageEl.dataset.stageMode || 'n/a' : 'n/a'}   #stage.bg ${stageEl ? getComputedStyle(stageEl).backgroundColor : 'n/a'}`,
+          `#stage-canvas    attr/client ${sizes(spineCv)}   visibility ${spineCv ? getComputedStyle(spineCv).visibility : 'n/a'}`,
+          `#live2d-overlay  attr/client ${sizes(overlayCv)}   bg ${overlayCv ? getComputedStyle(overlayCv).backgroundColor : 'n/a'}`,
+          `PIXI  w ${ri ? ri.width : '?'} h ${ri ? ri.height : '?'} res ${ri ? ri.resolution : '?'}`,
+        ];
+        if (overlayCv && overlayCv.clientWidth > 0 && overlayCv.clientHeight > 0 && readCanvasPixels) {
+          const w = overlayCv.clientWidth;
+          const h = overlayCv.clientHeight;
+          const px = await readCanvasPixels([[4, 4], [w - 4, 4], [4, h - 4], [w - 4, h - 4], [Math.floor(w / 2), Math.floor(h / 2)]]);
+          if (px) {
+            const alphaAt = (i) => (px[i] && px[i].rgba ? px[i].rgba[3] : '?');
+            rows.push(`calls ${ri?.clearCalls ?? '?'} / bufFv ${ri?.clearBufferCalls?.fv ?? '?'} / bufFi ${ri?.clearBufferCalls?.fi ?? '?'} / wrMask ${(ri?.colorWriteMask || []).map((v) => (v ? 1 : 0)).join('') || '?'} / ctxAlpha ${ri?.contextAlpha === true ? 1 : ri?.contextAlpha === false ? 0 : '?'}`);
+          }
+        }
+        body.textContent = rows.join('\n');
+      } catch (err) {
+        body.textContent = `diag error: ${err && err.message ? err.message : err}`;
+      }
+    };
+
+    update();
+    const timer = setInterval(() => { try { update(); } catch (e) { if (window.console && console.warn) console.warn('[diag-hud]', e && e.message); } }, 500);
+    return { stop() { try { clearInterval(timer); } catch { /* 忽略 */ } } };
+    if (typeof log === 'function') log('诊断 HUD 已启用（?diag=1）');
+  } catch {
+    /* 诊断失败不影响渲染 */
+  }
+}
+
+export default installDiagHud;