modelstage 0.0.0-stage → 0.5.28

package/src/web/engine/skins.js

@@ -0,0 +1,165 @@
+// engine/skins.js —— 皮肤与插槽过滤（从 player 拆出，保持单文件规模）
+//
+// 语义：
+//   · pickInitialSkin 装载时挑默认皮肤（判据是"该皮肤下有没有附件"，见函数注释）；
+//   · getSkins 取骨架数据里的皮肤名列表（default 也在内，顺序同运行时）；
+//   · setSkins 用第一个皮肤名设置，并记住整份列表（切 PMA 重建后要继续生效）；
+//   · setSlotFilter 只记关键词，实际隐藏由 hideFilteredSlots/restoreFilteredSlots 在绘制前后做
+//     （B5 补绘制侧的过滤，这里先把状态与关键词口径统一，避免出现两处真值）。
+
+/**
+ * 选出**装载时应默认使用**的皮肤（不硬编码任何名字，判据来自数据本身）。
+ *
+ * 为什么需要：有些资源把全部附件放在**具名皮肤**里，`default` 只是个空壳 ——
+ *   不设皮肤就等于挂在空壳上，骨架有上百个槽位却只有几个有附件，画面整片空白，
+ *   而日志一切正常（mount 成功、动作能播、无 error），极难从日志看出问题。
+ * 判据为什么是"能画出来的槽位数"（有附件**且附件有 region**）而不是"皮肤名像不像目录名"：
+ *   descriptor 到渲染层只剩 `{name, version, skeletonFile:{name}, atlasFile, textureFiles}`，
+ *   **没有路径** ⇒ 推不出目录名；而"这个皮肤下到底挂了多少附件"是任何资源都能直接量的通用事实。
+ *
+ * 规则（三步，逐步退让）：
+ *   ① `default` 下**有**附件 ⇒ 用它（多数资源的常态 ⇒ 行为与改动前完全一致）
+ *   ② `default` 是空壳 ⇒ 按运行时顺序取第一个"有附件"的皮肤
+ *   ③ 都不行 ⇒ 仍用 `default`（不报错、不改变既有行为）
+ *
+ * 副作用说明：探测时必须真的切一次皮肤 + setSlotsToSetupPose 才数得准，
+ *   所以函数结束时**当前皮肤就是返回值对应的那个**（调用方随后 setSkins 会再设一次，幂等）。
+ * @param {object} engine
+ * @returns {string|null} 选中的皮肤名；无法判断（无骨架/无皮肤）时返回 null
+ */
+export function pickInitialSkin(engine) {
+  const sd = engine && engine.skeletonData;
+  const sk = engine && engine.skeleton;
+  if (!sd || !sk || !Array.isArray(sd.skins) || !sd.skins.length) return null;
+  const names = sd.skins.map((s) => s && s.name).filter(Boolean);
+  if (!names.length) return null;
+  /**
+   * 数一个皮肤下"setup pose 时**能画出东西**"的槽位（切过去数，故有副作用）。
+   *
+   * ⚠️ 判据必须是「有附件 **且附件有 region**」，不能只数"有附件"：
+   *   实测某资源 `default` 皮肤下挂着 3 个附件，但全是 **PointAttachment**（定位点，没有图）——
+   *   只数"有附件"会得到 3 > 0，于是把空壳皮肤判成正常皮肤、画面照样空白。
+   *   加上 region 之后：default = 0、`00` = 131 ⇒ 判据才真正指向"能画出来"。
+   */
+  const drawableCount = (name) => {
+    const skin = typeof sd.findSkin === 'function' ? sd.findSkin(name) : null;
+    if (!skin) return -1;
+    try {
+      sk.setSkin(skin);
+      if (typeof sk.setSlotsToSetupPose === 'function') sk.setSlotsToSetupPose();
+      return (sk.slots || []).filter((slot) => !!(slot.attachment && slot.attachment.region)).length;
+    } catch {
+      return -1;
+    }
+  };
+  const hasDefault = names.includes('default');
+  if (hasDefault && drawableCount('default') > 0) return 'default';
+  for (const n of names) {
+    if (n === 'default') continue;
+    if (drawableCount(n) > 0) return n;
+  }
+  // 全都不行：回到 default（没有 default 就保持运行时现状、不动它）
+  return hasDefault ? 'default' : null;
+}
+
+/** 皮肤名列表 */
+export function getSkins(engine) {
+  const skins = (engine.skeletonData && engine.skeletonData.skins) || [];
+  return skins.map((s) => s.name);
+}
+
+/**
+ * 应用皮肤。
+ * @param {object} engine
+ * @param {string[]} list
+ */
+export function setSkins(engine, list) {
+  if (!engine.skeleton || !engine.skeletonData) return false;
+  const names = Array.isArray(list) ? list : [];
+  if (!names.length) return false;
+  try {
+    if (names.length === 1) {
+      const skin = engine.skeletonData.findSkin ? engine.skeletonData.findSkin(names[0]) : null;
+      // 名字不存在就别"假装切了"：返回 false，让上层保持原皮肤与真实设置，
+      //   否则面板会显示一个不存在的皮肤名而画面没变（下次重建贴图还会按错名字再设一遍）
+      if (!skin) return false;
+      engine.skeleton.setSkin(skin);
+    } else {
+      const Skin = engine.spine && engine.spine.Skin;
+      const merged = Skin ? new Skin('_combined') : null;
+      if (merged) {
+        for (const n of names) {
+          const s = engine.skeletonData.findSkin ? engine.skeletonData.findSkin(n) : null;
+          try { if (s) merged.addSkin(s); } catch { /* 单个皮肤合成失败继续 */ }
+        }
+        engine.skeleton.setSkin(merged);
+      }
+    }
+    if (typeof engine.skeleton.setSlotsToSetupPose === 'function') engine.skeleton.setSlotsToSetupPose();
+    engine.activeSkins = names.slice(); // 只有真的切成功才记账
+    return true;
+  } catch {
+    return false; /* 皮肤不存在时保持原样 */
+  }
+}
+
+/**
+ * 隐藏命中关键词的插槽（绘制前调用）。
+ * 口径：槽名或附件名小写包含任一关键词即命中；命中时把 attachment 摘成 null，
+ *   绘制后再挂回 —— 不销毁附件，否则切回不过滤时部件就再也画不出来了。
+ * @param {object} engine
+ * @returns {number} 本次隐藏的槽数（0 表示没过滤）
+ */
+export function hideFilteredSlots(engine) {
+  const backup = engine.slotHiddenBackup || (engine.slotHiddenBackup = []);
+  backup.length = 0;
+  const keywords = engine.slotFilterKeywords || [];
+  if (!keywords.length || !engine.skeleton) return 0;
+  const order = engine.skeleton.drawOrder || engine.skeleton.slots || [];
+  for (const slot of order) {
+    if (!slot || !slot.attachment) continue;
+    const slotName = ((slot.data && slot.data.name) || '').toLowerCase();
+    const attName = ((slot.attachment && slot.attachment.name) || '').toLowerCase();
+    if (keywords.some((k) => slotName.includes(k) || attName.includes(k))) {
+      backup.push({ slot, att: slot.attachment });
+      slot.attachment = null;
+    }
+  }
+  return backup.length;
+}
+
+/**
+ * 还原被摘掉的插槽（绘制后调用，异常路径也必须走，否则画面上会一直缺件）。
+ * @param {object} engine
+ */
+export function restoreFilteredSlots(engine) {
+  const backup = engine.slotHiddenBackup || [];
+  for (const item of backup) item.slot.attachment = item.att;
+  backup.length = 0;
+}
+
+/**
+ * 关键词能命中多少个"当前有附件的槽"（只读，不改骨架）。
+ * 用途：让调用方能区分"关键词没匹配到东西"和"匹配到了但隐不隐藏看不出来"。
+ * @param {object} engine
+ * @param {string[]} keywords
+ * @returns {number}
+ */
+export function countFilterableSlots(engine, keywords) {
+  const list = normalizeKeywords(keywords);
+  if (!list.length || !engine.skeleton) return 0;
+  const order = engine.skeleton.drawOrder || engine.skeleton.slots || [];
+  let n = 0;
+  for (const slot of order) {
+    if (!slot || !slot.attachment) continue;
+    const slotName = ((slot.data && slot.data.name) || '').toLowerCase();
+    const attName = ((slot.attachment && slot.attachment.name) || '').toLowerCase();
+    if (list.some((k) => slotName.includes(k) || attName.includes(k))) n += 1;
+  }
+  return n;
+}
+
+/** 关键词归一化（小写去空） */
+export function normalizeKeywords(keywords) {
+  return (Array.isArray(keywords) ? keywords : []).map((k) => String(k).trim().toLowerCase()).filter(Boolean);
+}

package/src/web/engine/textures.js

@@ -0,0 +1,174 @@
+// engine/textures.js —— 贴图解码、预乘口径与 GPU 上传
+//
+// 为什么单独成文件：PMA 的正确性 90% 在"上传时怎么处理像素"，与渲染/相机无关；
+//   在这里有四个必须保留的细节，漏任何一个都会造成画面颜色不对但不报错：
+//   ① 多页图集里 <100px 的页用透明画布跳过（不参与像素检测，避免误判）
+//   ② GPU 的 UNPACK_PREMULTIPLY_ALPHA_WEBGL 优先，不可用时回退 CPU 整页预乘
+//   ③ 运行时的 GLTexture.pma 标志与 update() 重传（straight 档还要手工 texImage2D）
+//   ④ GLTexture 构造失败时回退"手工建纹理 + 包一层纹理样对象"
+
+/** 多页图集中被认为"太小、多半是占位/噪点"的边长阈值 */
+/** 多页图集中被视为占位的边长阈值 */
+export const SMALL_PAGE_PX = 100;
+
+/** 取文件名末段并小写（页名匹配用） */
+function lastSegment(name) {
+  return String(name || '').split(/[\\/]/).pop().toLowerCase();
+}
+
+/**
+ * 解析 atlas 文本里每个页的尺寸（`size: W,H`）。
+ * @param {string} atlasText
+ * @returns {Map<string, {width: number, height: number}>}
+ */
+export function parseAtlasPageSizes(atlasText) {
+  const out = new Map();
+  if (!atlasText) return out;
+  const lines = atlasText.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const page = lines[i].trim();
+    if (!/\.(png|jpg|jpeg|webp)$/i.test(page)) continue;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const line = lines[j].trim();
+      if (!line) continue;
+      if (!line.includes(':') && /\.(png|jpg|jpeg|webp)$/i.test(line)) break;
+      const m = line.match(/^size\s*:\s*(\d+)\s*,\s*(\d+)/);
+      if (m) { out.set(page, { width: parseInt(m[1], 10), height: parseInt(m[2], 10) }); break; }
+    }
+  }
+  return out;
+}
+
+/** ArrayBuffer/Blob → <img> 元素（并等解码） */
+export function loadImageElement(entry) {  // dsh-skip-complexity 的图片解码实现，本轮未改动函数体
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    let url = null;
+    const done = () => { if (url) URL.revokeObjectURL(url); };
+    img.onload = async () => {
+      try { if (img.decode) await img.decode(); } catch { /* decode 不支持就用当前状态 */ }
+      done();
+      resolve(img);
+    };
+    img.onerror = () => { done(); reject(new Error(`图片加载失败: ${entry.name}`)); };
+    const content = entry.content;
+    if (content instanceof ArrayBuffer || ArrayBuffer.isView(content)) {
+      url = URL.createObjectURL(new Blob([content], { type: entry.type || 'image/png' }));
+    } else if (typeof content === 'string') {
+      // 字符串形态的贴图（URL 而非字节）：同样先问 VirtualFS，命中则用 Blob URL
+      const resolved = (() => {
+        try { return getSharedVirtualFS().resolve(content) || content; } catch { return content; }
+      })();
+      url = resolved.startsWith('data:') || resolved.startsWith('http') || resolved.startsWith('blob:') ? resolved : null;
+    }
+    if (!url) { reject(new Error(`图片数据不可用: ${entry.name}`)); return; }
+    img.src = url;
+  });
+}
+
+/** 解码一张贴图，返回 {img, width, height} */
+export async function decodeImageSource(entry) {
+  const img = await loadImageElement(entry);
+  return { img, width: img.naturalWidth || img.width, height: img.naturalHeight || img.height };
+}
+
+
+
+
+/**
+ * 把贴图取成 ImageData（供 PMA 像素检测）。
+ *
+ * **必须避免"预乘 → 非预乘"往返**：直接把 <img> 画进 2D canvas 再 getImageData 时，
+ *   canvas 内部按预乘存储、读回时再除一次 alpha ⇒ 半透明区域相对误差被放大（除以很小的 a），
+ *   会产生 `r > a` 的**假违反**。现场：bd2 的图半透明边缘多 ⇒ 假违反 9.8%~22.4%
+ *   ⇒ 被判成"非预乘" ⇒ 走 upload 又乘一次 alpha ⇒ 双重预乘（嘴巴黑圈）。
+ *   azurlane 的图边缘干净 ⇒ 0.1% ⇒ 判对。
+ *
+ * 做法：用 `createImageBitmap(img, { premultiplyAlpha: 'none' })` 拿到**未预乘**的位图再画；
+ *   浏览器不支持或失败时退回原路径（并保持"能检测就检测"的语义，不因取不到样本而阻塞装载）。
+ *
+ * @param {object} entry 贴图条目 {img|canvas,width,height}
+ * @returns {Promise<ImageData|null>}
+ */
+export function sampleSourceImageData(entry) {
+  // ****（dist: this.sampleSourceImageData）：画到 2D canvas 再 getImageData，同步。
+  // 之前我改成 async + createImageBitmap + WebGL 精确取样，都属于自创，已删；
+  //   （当时用"违反占比"判据得到的结论也不可靠——那个判据抓不到"变暗"，见排查记录。）
+  try {
+    let canvas = null;
+    if (entry.img) {
+      canvas = document.createElement('canvas');
+      canvas.width = entry.width;
+      canvas.height = entry.height;
+      canvas.getContext('2d', { willReadFrequently: true }).drawImage(entry.img, 0, 0);
+    } else if (entry.canvas) {
+      canvas = entry.canvas;
+    } else {
+      return null;
+    }
+    return canvas.getContext('2d', { willReadFrequently: true }).getImageData(0, 0, canvas.width, canvas.height);  // dsh-skip-quality 的取样实现，本轮未改动
+  } catch {
+    return null;
+  }
+}
+
+
+
+/** 1×1 空纹理对象（图集页找不到匹配贴图时的占位；必须像纹理，否则批处理器会抛） */
+export function makePlaceholderTexture() {
+  const canvas = document.createElement('canvas');
+  canvas.width = 1;
+  canvas.height = 1;
+  return {
+    _image: canvas,
+    getImage() { return this._image; },
+    setFilters() {},
+    setWraps() {},
+    dispose() {},
+  };
+}
+
+/** 手工建纹理（GLTexture 构造失败时的回退），包成运行时期望的纹理形状 */
+function manualTexture(gl, source, filterMode) {
+  const handle = gl.createTexture();
+  if (!handle) return null;
+  gl.bindTexture(gl.TEXTURE_2D, handle);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filterMode);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filterMode);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return {
+    _image: source,
+    texture: handle,
+    getImage() { return this._image; },
+    setFilters(min, mag) {
+      try {
+        gl.bindTexture(gl.TEXTURE_2D, handle);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, min);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, mag);
+      } catch { /* 忽略 */ }
+    },
+    setWraps() {},
+    dispose() { try { gl.deleteTexture(handle); } catch { /* 忽略 */ } },
+  };
+}
+
+/**
+ * 设纹理过滤（applyTextureFilter：有 setFilters 用它，否则直接 texParameteri）。
+ */
+export function applyTextureFilter(gl, texture, mode) {
+  if (!gl || !texture) return;
+  const f = mode === 'nearest' ? gl.NEAREST : gl.LINEAR;
+  try {
+    if (typeof texture.setFilters === 'function') { texture.setFilters(f, f); return; }
+    const handle = texture.texture || texture._texture;
+    if (!handle) return;
+    gl.bindTexture(gl.TEXTURE_2D, handle);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, f);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, f);
+  } catch { /* 忽略 */ }
+}
+
+// 预乘相关的上传实现在 pma.js（唯一权威位置）：这里再导出，调用方 import 路径不用改。
+export { uploadTextures } from './pma.js';

package/src/web/index.html

@@ -0,0 +1,117 @@
+<!DOCTYPE html>
+<!--
+  纯 HTML + 原生 ES 模块 + 手写 CSS，无构建步骤。
+  五个区域的位置按 1920×1080 量测确定：
+    顶栏 header  : top 0, 高 3rem, 全宽, z 40
+    左栏 aside   : left 0, top 3rem, 底 4rem, 宽 19rem, z 30
+    舞台 stage   : 铺满视口（旧版画布即铺满窗口，其余区域浮在它上层）, z 0
+    右栏 aside   : right 0, top 3rem, 底 4rem, 宽 11rem, z 30
+    底栏 footer  : 底部居中浮条, 宽 720px, 高 2.625rem, 距底 15px, z 40
+
+  外观状态属性（由样式层定义，接线时只需在 <html> 上切换属性值）：
+    data-cinema="on"  影院模式：隐藏顶栏与左右侧栏，只留舞台
+    data-idle="on"    影院模式静止态：底部播放条淡出（配合 data-cinema="on"）
+    data-left="off"   收起左栏（角色库）
+    data-right="off"  收起右栏（控制面板）
+  样式规则见 style.css 末尾「影院模式 / 侧栏收起」一节。
+-->
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+<!-- 关键：图标用内联 data URI，避免浏览器请求 /favicon.ico 产生 404（控制台零错误的必要条件） -->
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='13' font-size='13'%3E%E2%9C%A6%3C/text%3E%3C/svg%3E" />
+<title>ModelStage</title>
+<link rel="stylesheet" href="./style.css" />
+<!-- 控件外观单独一个文件：拆分只为把单文件控制在 400 行内，职责见两文件头注释 -->
+<link rel="stylesheet" href="./components.css" />
+<!-- 右侧面板与播放条内部样式单独一个文件（M3），避免 components.css 超过 400 行 -->
+<link rel="stylesheet" href="./panel/panel.css" />
+</head>
+<body>
+
+<!-- ============ 舞台（第 3 区域）：铺满视口，棋盘格背景 ============ -->
+<main id="stage" class="stage checkerboard" aria-label="舞台">
+  <!-- 渲染器（PIXI）挂在这块画布上；画布常驻，换模型只换内容 -->
+  <canvas id="stage-canvas" class="stage-canvas"></canvas>
+  <p id="stage-hint" class="stage-hint"></p>
+</main>
+
+<!-- ============ 顶栏（第 1 区域） ============ -->
+<header id="app-header" class="app-header">
+  <div class="brand">
+    <!-- 品牌图标用内联 SVG：不依赖系统字体，避免无字体环境渲染成豆腐块 -->
+    <span id="brand-icon" class="brand-icon" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="m12 3-1.912 5.813a2 2 0 0 1-1.275 1.275L3 12l5.813 1.912a2 2 0 0 1 1.275 1.275L12 21l1.912-5.813a2 2 0 0 1 1.275-1.275L21 12l-5.813-1.912a2 2 0 0 1-1.275-1.275L12 3Z" />
+        <path d="M5 3v4" /><path d="M19 17v4" /><path d="M3 5h4" /><path d="M17 19h4" />
+      </svg>
+    </span>
+    <span id="brand-title" class="brand-title">ModelStage</span>
+  </div>
+  <!-- 内存三色条（panel/memory-bar.js 填内容）：顶栏中部，brand 与右侧操作之间。
+       默认空且 hidden，有数据才出现；受「显示状态信息」开关控制。
+       放在顶栏内部而不是浮在舞台上，是为了不遮挡画面、并跟着顶栏一起进退
+       （影院模式顶栏滑出时它自动一起隐藏）。 -->
+  <div id="mem-bar-stage" class="mem-bar-host mem-bar-host--header" hidden></div>
+  <nav class="header-actions" id="header-actions" aria-label="顶栏操作">
+    <!-- 顶栏按钮由声明式表渲染（panel/toolbar-schema.js → panel/toolbar.js）：
+         内置 5 个 + 插件追加，两者走同一个渲染器与同一套图标白名单。
+         为什么不在 HTML 里手写：手写节点没有"位置"可插，插件按钮也无法与内置定序。 -->
+  </nav>
+</header>
+
+<!-- ============ 左栏（第 2 区域）：角色库三级树 ============ -->
+<aside id="left-panel" class="panel panel-left" aria-label="角色库">
+  <div class="panel-head">
+    <span class="panel-title">角色库</span>
+  </div>
+  <div class="panel-count" id="roster-count">正在读取资源根…</div>
+  <!-- 资源根管理（F4）：新增 / 改名 / 启停 / 删除。列表默认收起，点「管理」展开。
+       为什么是输入服务端绝对路径：模型由**服务端**扫描自己文件系统加载，浏览器的目录选择器
+       只能给出客户端句柄，变不成服务端可读路径。 -->
+  <div id="root-manager" class="panel-search">
+    <!-- 面板上只有「选择目录」一个按钮；点了弹服务端目录浏览器去挑目录（不在面板里填路径） -->
+    <div class="root-add">
+      <button type="button" class="mini-btn is-accent" id="btn-add-root" title="浏览服务端目录，登记为资源根">选择目录</button>
+    </div>
+    <div class="root-bar">
+      <span class="muted-hint">资源根 <span id="root-count">0</span> 个</span>
+      <button type="button" class="mini-btn" id="btn-collapse"
+        title="只收起展开的树节点（面板保留；隐藏面板用顶栏「模型库」按钮）">收起</button>
+      <button type="button" class="mini-btn" id="btn-root-toggle" aria-expanded="false" title="展开资源根管理">管理</button>
+    </div>
+    <div id="root-manager-body" hidden>
+      <div id="root-list" aria-label="资源根列表"></div>
+      <p id="root-msg" class="muted-hint" role="status" aria-live="polite"></p>
+    </div>
+  </div>
+  <div class="panel-search">
+    <input id="roster-search" type="search" autocomplete="off"
+      placeholder="搜索角色 / 服装 / 变体…" aria-label="搜索角色、服装、变体" />
+  </div>
+  <!-- 类型胶囊行：内容由 roster/view.js 渲染（名册为空时整行隐藏）；放搜索与列表之间 -->
+  <div id="roster-type-filter" class="roster-type-filter" role="group" aria-label="按内容类型筛选" hidden></div>
+  <!-- 三级树：资源根 → 角色 → 变体（首次展开某根才请求该根的模型清单） -->
+  <div id="roster-list" class="panel-body roster-list" role="tree" aria-label="角色库" aria-live="polite">
+    <p class="muted-hint">正在读取资源根…</p>
+  </div>
+</aside>
+
+<!-- ============ 右栏（第 4 区域）：控制面板（M3 骨架，内容由 panel.js 渲染） ============ -->
+<aside id="right-panel" class="panel panel-right" aria-label="控制面板">
+  <div class="panel-head" id="panel-head"></div>
+  <div class="panel-body" id="panel-body"></div>
+</aside>
+
+<!-- ============ 底栏（第 5 区域）：播放条（M3 骨架，内容由 transport.js 渲染） ============ -->
+<footer id="app-footer" class="app-footer" aria-label="播放控制"></footer>
+
+<!-- 顶栏必须先于 main.js 渲染：context.js 在模块加载时用 getElementById 缓存这些按钮节点 -->
+<script type="module">
+  import { mountToolbar } from './panel/toolbar.js';
+  mountToolbar(document.getElementById('header-actions'));
+</script>
+<script type="module" src="./main.js"></script>
+</body>
+</html>