modelstage 0.0.0-stage → 0.5.28

package/src/web/panel/slider.js

@@ -0,0 +1,210 @@
+// panel/slider.js —— 滑块控件的渲染与"位置↔数值"映射（从 view.js 抽出来）
+//
+// 为什么单独一个文件：滑块是唯一带**非线性映射**的控件（双段比例 + 吸附 + 刻度），
+//   逻辑量比其它控件大；留在 view.js 里会把那个文件继续推长（超长文件审计不过）。
+//
+// 契约《禁止内联 CSS 与 JS》：
+//   · 颜色/尺寸/圆角/字体全部在 panel/panel.css（类名 + CSS 变量），这里**不写 element.style**；
+//   · 轨道与手柄用原生 `accent-color: var(--color-primary)` 跟随五套主题；
+//   · 中线刻度是伪元素，颜色由 CSS 侧的 var(--color-muted-foreground) 指定（accent-color 不影响伪元素）。
+
+/** 允许的空值语义：0 值有专门文案时优先显示它（混合时长 0 秒 = "关"） */
+
+/**
+ * 滑块的"位置 ↔ 数值"映射表（非线性滑块的唯一权威）。
+ *
+ * 为什么速度要非线性：原生 range 是线性的，若 0.1~3 平铺，1.0 只落在 31% 处，
+ *   慢速段（0.1~1.0）被压成一小段，想细看慢动作很难拖准。
+ *   改成**双段比例**：左半 0~50 格 → 0.1~1.0（细调），右半 50~100 格 → 1.0~3.0（粗调），
+ *   1.0 恰好在正中间 —— 视觉上天然是"基准点"，也更符合人对倍率的感知（不是线性的）。
+ */
+/** 速度滑块的取值域与双段划分（数值含义集中在常量里，映射函数只引用它们） */
+export const SPEED_MIN = 0.1;        // 最慢
+export const SPEED_MID = 1;          // 基准值：落在滑块正中
+export const SPEED_MAX = 3;          // 最快
+export const SPEED_STEP = 0.1;       // 对外声明的步进（读数是两位小数，实际由量化决定）
+export const SPEED_DEFAULT = 1;      // 默认倍率
+export const MIX_MIN = 0;            // 混合时长：0 = 不混合
+export const MIX_MAX = 1;            // 最长 1 秒
+export const MIX_STEP = 0.05;        // 混合时长步进
+export const MIX_DEFAULT = 0.2;      // 默认 0.2 秒（引擎默认过渡）
+
+const POS_MIN = 0;                   // 滑块格位下界
+const POS_MID = 50;                  // 正中 = SPEED_MID
+const POS_MAX = 100;                 // 格位上界
+const SNAP_RANGE = 3;                // 正中 ±3 格内吸附到基准值
+const QUANTIZE_STEPS = 20;           // 按 1/20 = 0.05 归整
+
+export const SLIDER_CURVES = {
+  speed: {
+    /** 位置(0~100 整数) → 数值 */
+    toValue: (p) => (p <= POS_MID
+      ? SPEED_MIN + (p / POS_MID) * (SPEED_MID - SPEED_MIN)
+      : SPEED_MID + ((p - POS_MID) / (POS_MAX - POS_MID)) * (SPEED_MAX - SPEED_MID)),
+    /** 数值 → 位置(0~100 浮点，写入时取整) */
+    toPos: (v) => (v <= SPEED_MID
+      ? ((v - SPEED_MIN) / (SPEED_MID - SPEED_MIN)) * POS_MID
+      : POS_MID + ((v - SPEED_MID) / (SPEED_MAX - SPEED_MID)) * (POS_MAX - POS_MID)),
+    /** 靠近正中（基准倍率）就吸附过去，避免"想回 1x 却总停在 0.97x" */
+    snap: { at: POS_MID, range: SNAP_RANGE },
+    // 按 0.05 归整：慢速段每格 ≈0.018，若按 0.1 归整会把 25% 处的 0.55 变成 0.6（与双段比例对不上）；
+    //   0.05 既贴合映射、又保证下发/持久化里不会出现 1.2999999 这类长小数。
+    quantize: (v) => Math.round(v * QUANTIZE_STEPS) / QUANTIZE_STEPS,
+    precision: 1,
+    posMin: POS_MIN,
+    posMax: POS_MAX,
+  },
+};
+
+/**
+ * 取控件用的映射（无 curve 声明 ⇒ 线性，直接读 input 的 min/max/step）。
+ * @param {object} ctl schema 控件声明
+ */
+export function curveOf(ctl) {
+  return (ctl && ctl.curve && SLIDER_CURVES[ctl.curve]) || null;
+}
+
+/**
+ * 数值 → 滑块位置（线性控件原样返回）。
+ * @param {object} ctl
+ * @param {number} value 真实数值
+ * @returns {number} 位置（非线性时 0~100，线性时 min..max）
+ */
+export function posOf(ctl, value) {
+  const cv = curveOf(ctl);
+  return cv ? cv.toPos(Number(value)) : Number(value);
+}
+
+/**
+ * 位置 → 真实数值（非线性时做量化）。
+ * @param {object} ctl
+ * @param {number} pos 滑块位置
+ * @returns {number} 真实数值
+ */
+export function valueOfPos(ctl, pos) {
+  const cv = curveOf(ctl);
+  const raw = cv ? cv.toValue(Number(pos)) : Number(pos);
+  return cv ? cv.quantize(raw) : raw;
+}
+
+/**
+ * 读数格式化（按 schema 的 `format` 声明，不在这里猜单位）。
+ *   format: 'x' → 1.5x（播速）；'s' → 0.85s（时长）；0 且声明了 zeroText → 显示该文案（"关"）
+ * @param {object} ctl
+ * @param {number} v
+ * @returns {string}
+ */
+export function formatSliderValue(ctl, v) {
+  const n = Number(v);
+  if (ctl.zeroText && Number.isFinite(n) && n === 0) return ctl.zeroText;
+  const cv = curveOf(ctl);
+  const digits = cv && cv.precision !== undefined ? cv.precision : 2;
+  if (ctl.format === 's') return `${(Number.isFinite(n) ? n : 0).toFixed(2)}s`;
+  if (ctl.format === 'x') {
+    // 速度读数两位、裁掉末尾的 0，但**保留一位**（1.0x 不写成 1x、0.55x 不写成 0.6x）：
+    //   读数是"真实生效值"的唯一可见出口，必须与内部值一致（0.05 归整后会出现 0.55 这类两位值）
+    const t = (Number.isFinite(n) ? n : 1).toFixed(2);          // 1.50 / 0.55 / 1.00
+    return `${t.endsWith('0') ? t.slice(0, -1) : t}x`;           // 1.5x / 0.55x / 1.0x
+  }
+  return Number.isFinite(n) ? n.toFixed(digits) : '';
+}
+
+/**
+ * 渲染一个滑块控件。
+ *
+ * 结构**标签在左、当前值在右（等宽），滑块单独一行占满宽度**，正中一条基准刻度：
+ *   ┌ 速度            1.5x ┐
+ *   └ ─────●──┊───────────┘
+ *
+ * @param {object} ctl schema 控件声明（kind: 'slider'）
+ * @param {object} ctx 面板上下文：{ isWired(id), onSetting(id, value) }
+ * @param {(tag: string, cls?: string, text?: string) => HTMLElement} el DOM 构造小工具（由 view.js 注入）
+ * @param {(node: HTMLElement, ctl: object, ctx: object) => void} markDisabled 置灰工具
+ * @returns {HTMLElement}
+ */
+/**
+ * 建滑块的原生 input（非线性曲线统一用 0~100 格；线性控件直接用 min/max/step）。
+ * @returns {HTMLInputElement}
+ */
+function buildRangeInput(ctl, cv, el) {
+  const input = el('input', 'ctl-slider-input');
+  input.id = ctl.id || '';
+  input.type = 'range';
+  if (cv) {
+    input.min = String(cv.posMin);
+    input.max = String(cv.posMax);
+    input.step = '1';
+    input.value = String(Math.round(posOf(ctl, ctl.defaultValue !== undefined ? ctl.defaultValue : SPEED_MID)));
+  } else {
+    input.min = String(ctl.min !== undefined ? ctl.min : 0);
+    input.max = String(ctl.max !== undefined ? ctl.max : 100);
+    input.step = String(ctl.step !== undefined ? ctl.step : 1);
+    input.value = String(ctl.defaultValue !== undefined ? ctl.defaultValue : input.min);
+  }
+  input.setAttribute('aria-label', ctl.label);
+  return input;
+}
+
+/**
+ * 渲染一个滑块控件（结构见文件头注释）。
+ * @param {object} ctl schema 控件声明（kind: 'slider'）
+ * @param {object} ctx 面板上下文：{ isWired(id), onSetting(id, value) }
+ * @param {Function} el DOM 构造小工具（由 view.js 注入）
+ * @param {Function} markDisabled 置灰工具（由 view.js 注入）
+ * @returns {HTMLElement}
+ */
+export function renderSlider(ctl, ctx, el, markDisabled) {
+  const wired = ctx.isWired(ctl.id) && ctl.disabled !== true;
+  const cv = curveOf(ctl);
+  const box = el('div', 'ctl-slider');
+  box.dataset.ctl = ctl.id || '';
+
+  const head = el('div', 'ctl-slider-head');
+  head.append(el('span', 'ctl-slider-label', ctl.label));
+  // 契约 R2：首次渲染就用工厂里的当前值（有则覆盖 schema 默认），避免"先默认后跳"
+  const ivSlider = ctx && typeof ctx.initialValue === 'function' ? ctx.initialValue(ctl.id) : undefined;
+  const seed = ivSlider === undefined ? ctl.defaultValue : ivSlider;
+  const readout = el('span', 'ctl-slider-value', formatSliderValue(ctl, seed));
+  readout.dataset.readout = ctl.id || '';
+  readout.setAttribute('aria-live', 'polite');
+  head.append(readout);
+
+  const track = el('div', 'ctl-slider-track');
+  const input = buildRangeInput(ctl, cv, el);
+  // 滑块 input.value 存的是**格位**（非线性滑块要换算），所以按 posOf 定位而不是直接写数值
+  if (ivSlider !== undefined) {
+    try { input.value = String(Math.round(posOf(ctl, ivSlider))); } catch { /* 换算失败就用默认位置 */ }
+  }
+  track.append(input);
+  box.append(head, track);
+
+  if (!wired) {
+    markDisabled(input, ctl, ctx);
+    return box;
+  }
+  input.title = ctl.title || ctl.label;
+  readout.title = cv && cv.snap ? '双击回到基准值' : '双击复位到默认值';
+
+  /** 读当前格位 → 吸附 → 回写滑块 → 返回真实数值 */
+  const readSnapped = () => {
+    let pos = Number(input.value);
+    if (cv && cv.snap && Math.abs(pos - cv.snap.at) <= cv.snap.range) {
+      pos = cv.snap.at;
+      input.value = String(pos);
+    }
+    return valueOfPos(ctl, pos);
+  };
+  const commit = (v) => {
+    readout.textContent = formatSliderValue(ctl, v);
+    try { ctx.onSetting(ctl.id, v); } catch { /* 接线失败不影响面板自身显示 */ }
+  };
+
+  input.addEventListener('input', () => commit(readSnapped()));
+  // 双击读数复位：不额外占一行按钮
+  readout.addEventListener('dblclick', () => {
+    const back = ctl.defaultValue !== undefined ? ctl.defaultValue : valueOfPos(ctl, input.min);
+    input.value = String(Math.round(posOf(ctl, back)));
+    commit(back);
+  });
+  return box;
+}

package/src/web/panel/toolbar-schema.js

@@ -0,0 +1,111 @@
+// src/web/panel/toolbar-schema.js —— 顶栏按钮的**声明式表**（内置 5 个）
+//
+// 为什么要有这张表：顶栏原先在 index.html 里手写 5 个 <button>（每个带内联 SVG），
+//   插件按钮就没有位置可插、更无法与内置按钮定序。改成"数据 → 渲染"之后，
+//   内置与插件按钮走**同一个渲染器**、同一套排序与图标白名单。
+//
+// 字段口径：
+//   id       DOM id（**必须与旧手写按钮一致**：context.js 在模块加载时按 id 取节点）
+//   icon     图标名（白名单见 icons.js 的三张表：TOPBAR_ICONS / GROUP_ICONS / ACTION_ICONS）
+//   label    aria-label（可访问名）
+//   title    tooltip（与 aria-label 可以不同：tooltip 更简短）
+//   action   事件名（由连接层 dispatch；渲染器不认识业务）
+//   order    升序；插件按钮缺省 1000，因此天然排在内置之后
+//   pressed  可选：'true'/'false' 初值的 aria-pressed（开关类按钮）
+
+import { TOPBAR_ICONS, GROUP_ICONS, ACTION_ICONS } from './icons.js';
+
+/** 内置按钮的有效顺序与旧 HTML 完全一致（左→右） */
+export const TOOLBAR_ACTIONS = [
+  {
+    id: 'btn-library',
+    icon: 'panelLeft',
+    label: '模型库（显示/隐藏左栏）',
+    title: '模型库（显示/隐藏左栏）',
+    action: 'toggle-left-panel',
+    order: 10,
+  },
+  {
+    id: 'btn-menu',
+    icon: 'panelRight',
+    label: '菜单（显示/隐藏右侧控制面板）',
+    title: '菜单（显示/隐藏右侧控制面板）',
+    action: 'toggle-right-panel',
+    order: 20,
+    pressed: 'true',
+  },
+  {
+    id: 'btn-shot',
+    icon: 'camera',
+    label: '截图导出',
+    title: '截图导出（PNG，文件名带模型名与时间戳）',
+    action: 'screenshot',
+    order: 30,
+  },
+  {
+    id: 'btn-cinema',
+    // 影院模式图标是"画框"，与内置分组图标无关，单独登记在 TOOLBAR_EXTRA_ICONS
+    icon: 'cinema',
+    label: '影院模式（显示/隐藏顶栏与左右栏，Esc 或中心双击退出）',
+    title: '影院模式（Esc 或中心双击退出）',
+    action: 'toggle-cinema',
+    order: 40,
+    pressed: 'false',
+  },
+  {
+    id: 'btn-fullscreen',
+    icon: 'fullscreen',
+    label: '全屏',
+    title: '全屏',
+    action: 'fullscreen',
+    order: 50,
+  },
+];
+
+/**
+ * 顶栏专用图标（内联 SVG 的 path/d 串）：这三种在内置分组表里没有对应项。
+ * 从 index.html 原样搬过来，避免"迁移后图标变了"这种无意义回归。
+ */
+export const TOOLBAR_EXTRA_ICONS = {
+  camera: '<path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z"/><circle cx="12" cy="13" r="3"/>',
+  cinema: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="M7 4v16M17 4v16M2 12h20"/>',
+  fullscreen: '<path d="M8 3H5a2 2 0 0 0-2 2v3M16 3h3a2 2 0 0 1 2 2v3M8 21H5a2 2 0 0 1-2-2v-3M16 21h3a2 2 0 0 0 2-2v-3"/>',
+};
+
+/**
+ * 图标白名单：插件只能报**名字**，拿不到就退化成纯文本按钮。
+ *
+ * 为什么必须白名单：顶栏图标的实现是"注入 SVG 内层 HTML"，
+ *   如果允许插件传任意串，等于允许它往宿主 DOM 里塞任意标记（声明式纪律的第一条禁止项）。
+ */
+export const TOOLBAR_ICON_WHITELIST = new Set([
+  ...Object.keys(TOPBAR_ICONS),
+  ...Object.keys(GROUP_ICONS),
+  ...Object.keys(ACTION_ICONS),
+  ...Object.keys(TOOLBAR_EXTRA_ICONS),
+]);
+
+/**
+ * 按图标名取 SVG 内层内容。
+ * @param {string} name 图标名
+ * @returns {string|null} 命中白名单返回内层标记；否则 null（调用方退化成文本按钮）
+ */
+export function iconBodyOf(name) {
+  const key = String(name || '');
+  if (!key) return null;
+  if (TOOLBAR_EXTRA_ICONS[key]) return TOOLBAR_EXTRA_ICONS[key];
+  if (TOPBAR_ICONS[key]) return TOPBAR_ICONS[key];
+  if (GROUP_ICONS[key]) return GROUP_ICONS[key];
+  if (ACTION_ICONS[key]) return ACTION_ICONS[key];
+  return null;
+}
+
+/**
+ * 插件按钮的**安全阀**（不是布局上限）。
+ *
+ * 历史：S3 时这里是 3，超出即丢弃 —— 用户既看不到按钮也不知道被跳过。
+ * 现在布局改成"插件按钮进横向滚动区"，可见性问题由滚动解决；
+ *   保留 20 只是防"某个插件一口气注册上百个按钮"把 DOM 撑爆的安全阀。
+ * @type {number}
+ */
+export const PLUGIN_TOOLBAR_MAX = 20;

package/src/web/panel/toolbar.js

@@ -0,0 +1,195 @@
+// src/web/panel/toolbar.js —— 顶栏渲染器（内置 + 插件按钮走同一套）
+//
+// 两类按钮的差异只有"事件怎么来"：
+//   · 内置：DOM id 与旧手写按钮**完全一致**（btn-library / btn-menu / …），
+//     所以既有连接层（topbar-actions.js 按 id getElementById 绑事件）**一行都不用改**。
+//   · 插件：点击走 onAction（与面板控件同一套回调通道），由装配层注入。
+//
+// 渲染器不认识业务、不发请求、不碰状态：只按数据造节点。
+
+import { svgIcon } from './icons.js';
+import { PLUGIN_TOOLBAR_MAX, TOOLBAR_ACTIONS, iconBodyOf } from './toolbar-schema.js';
+
+// ⚠️ 这里**不能**顶层 import app/status.js（它 → app/context.js，会在模块加载时
+//   用 getElementById 把顶栏按钮快照成 null）。顶栏渲染必须发生在 context 之前，
+//   所以日志能力由装配层注入（opts.log），渲染器本身保持"零依赖 app 层"。
+
+/**
+ * 造一个顶栏按钮（内置与插件共用）。
+ * @param {{id:string, label:string, title?:string, icon?:string, pressed?:string, pluginId?:string}} item
+ * @returns {HTMLButtonElement}
+ */
+/**
+ * 求出按钮的按下态。
+ *
+ * 支持两种写法（**getter 优先**，这也是本轮选定的形式）：
+ *   · `spec.pressed` 是函数 ⇒ 渲染时求值（可读 owner props）
+ *   · `spec.pressed` 是布尔   ⇒ 直接当常量用
+ * 选 getter 的理由：与 owner props 的 getter 语义一致——插件不用自己记"什么时候该重绘"，
+ *   宿主每次渲染/重建时重新求值即可；布尔常量仍可用，写起来最省事。
+ * @param {object} item 按钮描述
+ * @param {object} [props] owner props（只有当 pressed 是函数时才会传进去）
+ * @returns {boolean|undefined} undefined 表示"这个按钮没有按下态"
+ */
+function resolvePressed(item, props) {
+  const raw = item && item.pressed;
+  if (typeof raw === 'function') {
+    try { return raw(props || {}) === true; } catch { return undefined; }
+  }
+  if (raw === true || raw === 'true') return true;
+  if (raw === false || raw === 'false') return false;
+  return undefined;
+}
+
+/** 写 aria-pressed（undefined ⇒ 移除属性，不冒充"关"） */
+function applyPressedAttr(btn, pressed) {
+  if (pressed === true || pressed === false) btn.setAttribute('aria-pressed', String(pressed));
+  else btn.removeAttribute('aria-pressed');
+}
+
+/**
+ * 插件按钮的横向滚动容器（幂等：已存在就复用）。
+ *
+ * 为什么单独一个容器：内置按钮必须**固定可见**、插件按钮可以很多 ——
+ *   把两者放进同一个 flex 容器时，插件一多会把内置按钮挤出屏幕。
+ * @param {HTMLElement} nav 顶栏 nav
+ * @returns {HTMLElement}
+ */
+function pluginStrip(nav) {
+  let strip = nav.querySelector(':scope > .header-plugin-actions');
+  if (!strip) {
+    strip = document.createElement('div');
+    strip.className = 'header-plugin-actions';
+    strip.dataset.pluginToolbar = '1';
+    nav.append(strip);
+  }
+  return strip;
+}
+
+function buildButton(item) {
+  const btn = document.createElement('button');
+  btn.type = 'button';
+  btn.className = 'icon-btn';
+  btn.id = String(item.id || '');
+  // 可访问名与 tooltip 分开：tooltip 可以更短（与旧 HTML 的口径一致）
+  btn.setAttribute('aria-label', String(item.label || item.id || ''));
+  btn.title = String(item.title || item.label || item.id || '');
+  // pressed 语义与内置按钮完全一致：只写 aria-pressed（样式由 .icon-btn[aria-pressed='true'] 负责）。
+  //   undefined ⇒ 不写属性（纯动作按钮，如截图/全屏那种"按一下就走"的）。
+  applyPressedAttr(btn, item.pressed);
+  if (item.pluginId) {
+    btn.dataset.pluginId = String(item.pluginId);
+    btn.dataset.pluginToolbar = '1';   // 重建时按它清理，不影响内置按钮节点
+  }
+  const body = iconBodyOf(item.icon);
+  if (body) {
+    btn.append(svgIcon(body));
+  } else {
+    // 图标名不在白名单（或没给）：只显示文本 label —— 绝不放行任意标记
+    const text = document.createElement('span');
+    text.className = 'icon-btn-text';
+    text.textContent = String(item.label || item.id || '');
+    btn.append(text);
+  }
+  return btn;
+}
+
+/**
+ * 渲染内置按钮（幂等：已渲染过就直接返回）。
+ *
+ * 必须在 main.js 之前跑：`context.js` 在模块加载时用 getElementById 缓存这些节点。
+ * @param {HTMLElement} nav 顶栏 `<nav class="header-actions">`
+ * @returns {number} 本次新建的按钮数
+ */
+export function mountToolbar(nav) {
+  if (!nav) return 0;
+  if (nav.dataset.toolbarMounted === '1') return 0;
+  const items = [...TOOLBAR_ACTIONS].sort((a, b) => (a.order || 0) - (b.order || 0));
+  for (const item of items) nav.append(buildButton(item));
+  nav.dataset.toolbarMounted = '1';
+  return items.length;
+}
+
+/**
+ * 同步插件按钮（每次面板重建后调用）。
+ *
+ * 规则（设计 §7.2 的声明式纪律）：
+ *   · 只追加在内置按钮之后，按 order 升序（缺省 1000）
+ *   · 图标只认白名单名字，拿不到就只显示文本
+ *   · 超过 PLUGIN_TOOLBAR_MAX 的部分不渲染，并记一条 info（溢出菜单留后续）
+ * @param {HTMLElement} nav 顶栏 nav
+ * @param {Array} entries 插槽登记项（name === 'toolbar.actions'）
+ * @param {{onAction?: (entry:object, ev:MouseEvent) => void}} [opts]
+ * @returns {{added:number, skipped:number}}
+ */
+/**
+ * 单值插槽 `panel.brand`：换掉顶栏品牌名（**纯文本**，不做标记解析）。
+ *
+ * 生效模型："后注册者胜出"——按全局注册序号 seq 取最大的那条；
+ *   它的 disposer 执行后自然回退到**上一个**注册者（不是直接回内置），因为记录被移除后
+ *   重新算一遍"最大 seq"就落到前一条。一条都没有时用内置文本。
+ * @param {HTMLElement} el 品牌元素（#brand-title）
+ * @param {Array} entries 插槽登记项
+ * @param {{fallback?: string}} [opts]
+ * @returns {{text: string, pluginId: string|null}}
+ */
+export function syncBrand(el, entries, opts = {}) {
+  const fallback = String(opts.fallback || 'ModelStage');
+  if (!el) return { text: fallback, pluginId: null };
+  const list = (Array.isArray(entries) ? entries : [])
+    .filter((e) => e && String(e.name || '') === 'panel.brand')
+    .sort((a, b) => (Number(a.seq) || 0) - (Number(b.seq) || 0));
+  const top = list.length ? list[list.length - 1] : null;
+  const spec = (top && top.spec) || {};
+  // 文本取 spec.text / spec.label；用 textContent 写入（HTML 字符串会被当字面文本，不会解析）
+  const text = top ? String(spec.text != null ? spec.text : (spec.label != null ? spec.label : '')) : fallback;
+  el.textContent = text || fallback;
+  if (top) el.dataset.brandPlugin = String(top.pluginId || '');
+  else delete el.dataset.brandPlugin;
+  return { text: el.textContent, pluginId: top ? String(top.pluginId || '') : null };
+}
+
+export function syncPluginToolbar(nav, entries, opts = {}) {
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  if (!nav) return { added: 0, skipped: 0 };
+  // 插件按钮统一进滚动容器；容器整体清空重来（内置按钮不在里面，不会被误伤）
+  const strip = pluginStrip(nav);
+  strip.textContent = '';
+  const list = (Array.isArray(entries) ? entries : [])
+    .filter((e) => e && String(e.name || '') === 'toolbar.actions')
+    .sort((a, b) => (Number(a.order) || 1000) - (Number(b.order) || 1000));
+  let added = 0;
+  let skipped = 0;
+  for (const entry of list) {
+    if (added >= PLUGIN_TOOLBAR_MAX) {
+      skipped += 1;
+      continue;
+    }
+    const spec = (entry && entry.spec) || {};
+    const props = typeof opts.buildProps === 'function' ? opts.buildProps(entry) : {};
+    const btn = buildButton({
+      id: String(entry.id || `plugin-toolbar-${added}`),
+      label: String(spec.label || entry.label || entry.id || ''),
+      title: String(spec.title || spec.label || entry.label || entry.id || ''),
+      icon: String(spec.icon || ''),
+      pluginId: entry.pluginId,
+      pressed: resolvePressed(spec, props),
+    });
+    btn.addEventListener('click', (ev) => {
+      try {
+        if (typeof opts.onAction === 'function') opts.onAction(entry, ev);
+      } catch { /* 插件回调抛错不影响顶栏 */ }
+      // 点完重新求值一次按下态：插件不必自己记"该重绘了"（getter 形式的直接受益点）。
+      //   只重算这一个按钮：整条重建会丢焦点（键盘用户会掉 focus）。
+      try { applyPressedAttr(btn, resolvePressed((entry && entry.spec) || {}, props)); } catch { /* 忽略 */ }
+    });
+    strip.append(btn);
+    added += 1;
+  }
+  if (skipped) {
+    // 正常情况下永远不会触发（20 是防失控的安全阀，不是布局上限）；真触发说明有插件在刷按钮
+    log('warn', `顶栏插件按钮超过安全阀（${PLUGIN_TOOLBAR_MAX} 个），已跳过 ${skipped} 个：${list
+      .slice(PLUGIN_TOOLBAR_MAX).map((e) => e.id).join(' / ')}`, { source: 'plugin-toolbar' });
+  }
+  return { added, skipped };
+}