modelstage 0.0.0-stage → 0.5.24

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,
+};

package/src/web/app/dir-picker.js

@@ -0,0 +1,242 @@
+// app/dir-picker.js —— 资源根「选择目录」的服务端目录浏览器
+//
+// 为什么必须有它：模型在**服务端**磁盘上，浏览器拿不到绝对路径（File System Access API 给的是
+//   客户端沙箱句柄），只能让服务端列目录。只能走服务端列目录（`/api/browse`）：浏览器拿不到任意路径的目录列表。
+//
+// 交互//   点「选择目录」→ 弹出面板
+//   顶部：标题 + 关闭
+//   中部：当前路径（含子目录数 / 含多少 .skel）、「↑ 上级目录」、「选择此目录」、📁 子目录列表
+//   底部：显示名称（可空，同名会合并成一个游戏）+「添加」
+//
+// 面板关掉就销毁，不常驻 DOM（不留隐藏节点）。
+
+/** 打开时的默认起点：上次用过的目录优先，否则从根开始让用户自己走 */
+const LAST_DIR_KEY = 'modelstage.dirpicker.last';
+
+// 目录列举走统一 HTTP 层（api.js）：拿重试 + 去重 + 统一的 TimeoutError 归类，别裸 fetch
+import { getJson } from '../infra/api.js';
+
+/**
+ * 创建目录选择器。
+ * @param {{onPick: (payload: {path: string, name: string}) => Promise<boolean>|boolean, formatError?: Function}} deps
+ *   onPick 返回 true 表示添加成功（面板会自行关闭）
+ */
+export function createDirPicker({ onPick, formatError, getLastError } = {}) {
+  let panel = null;      // 遮罩层（含面板）
+  let currentPath = '';  // 当前浏览到的目录
+  let pickedPath = '';   // 用户点过"选择此目录"的目录（空 = 还没选）
+  let busy = false;
+
+  const q = (sel) => (panel ? panel.querySelector(sel) : null);
+
+  /** 读上次目录（浏览器存储不可用时回落空串） */
+  function lastDir() {
+    try { return localStorage.getItem(LAST_DIR_KEY) || ''; } catch { return ''; }
+  }
+
+  function rememberDir(path) {
+    try { localStorage.setItem(LAST_DIR_KEY, path); } catch { /* 存不了就算了 */ }
+  }
+
+  function ensureShell() {
+    if (panel) return panel;
+    panel = document.createElement('div');
+    panel.id = 'dir-picker';
+    panel.className = 'dir-picker';
+    panel.innerHTML = `
+      <div class="dir-picker-box" role="dialog" aria-modal="true" aria-label="添加资源根">
+        <div class="dir-picker-head">
+          <strong>添加资源根</strong>
+          <span class="dir-picker-spacer"></span>
+          <button type="button" class="mini-btn" data-role="close">关闭</button>
+        </div>
+        <div class="dir-picker-body" data-role="body"></div>
+        <!-- 失败原因显示在对话框**自己身上**：它弹在屏幕中央，左栏那行提示在用户背后等于没有 -->
+        <div class="dir-picker-alert" data-role="alert" role="alert" hidden></div>
+        <div class="dir-picker-foot">
+          <span class="muted-hint">显示名称（同名会合并成一个游戏，用于归类原版／Mod）</span>
+          <input type="text" data-role="name" placeholder="如：棕色尘埃2" aria-label="资源根显示名称" />
+          <button type="button" class="mini-btn is-accent" data-role="add">添加</button>
+        </div>
+      </div>`;
+    document.body.append(panel);
+    // 点遮罩关闭（点面板内部不关）
+    panel.addEventListener('click', (e) => { if (e.target === panel) close(); });
+    q('[data-role="close"]').addEventListener('click', close);
+    q('[data-role="add"]').addEventListener('click', doAdd);
+    return panel;
+  }
+
+  /** 渲染当前目录：路径信息 / 上级 / 选择此目录 / 子目录列表 */
+  async function renderBody() {
+    const body = q('[data-role="body"]');
+    if (!body) return;
+    body.replaceChildren();
+    body.append(text('div', 'dir-picker-hint', '加载中…'));
+    let data = null;
+    try {
+      // 幂等 GET（连点同一目录会被 api.js 去重）⇒ 走统一层；超时 30s 的依据：
+      //   本机 CIFS（vers=3.02）实测 75 条目 5.5ms、241 条目 19ms，**未实测到慢例**，
+      //   按项目既有「catalog 冷启动最坏 31s」（同属目录扫描链路）**类推**取 30s。
+      data = await getJson(`/api/browse?path=${encodeURIComponent(currentPath)}`, { timeoutMs: 30000 });
+      if (!data || data.error) throw new Error((data && data.error) || '服务端返回空目录数据');
+    } catch (err) {
+      body.replaceChildren(text('div', 'dir-picker-error',
+        `读取失败：${typeof formatError === 'function' ? formatError(err) : (err && err.message) || err}`));
+      return;
+    }
+    currentPath = data.path || currentPath;
+    const hint = data.hint || {};
+    const info = text('div', 'dir-picker-hint', '');
+    info.append('当前：');
+    const code = document.createElement('code');
+    code.textContent = currentPath;
+    info.append(code);
+    info.append(`　子目录 ${hint.subDirCount || 0} 个${hint.skelHere ? `，含 ${hint.skelHere} 个 .skel` : ''}`);
+    body.replaceChildren(info);
+
+    // ↑ 上级目录
+    if (data.parent) body.append(navBtn(`↑ 上级目录`, data.parent));
+
+    // 选择此目录（已选过就变成"✓ 已选择"，再点仍是选中当前）
+    const pick = document.createElement('button');
+    pick.type = 'button';
+    // 已选中态用描边强调（与「选择目录」「添加」同一套语言），不再用实心高饱和
+    pick.className = pickedPath === currentPath ? 'mini-btn is-accent' : 'mini-btn';
+    pick.dataset.pick = currentPath;
+    pick.textContent = pickedPath === currentPath ? '✓ 已选择此目录' : '选择此目录';
+    pick.addEventListener('click', () => { pickedPath = currentPath; renderBody(); });
+    const pickRow = text('div', 'dir-picker-pick', '');
+    pickRow.append(pick);
+    body.append(pickRow);
+
+    // 子目录列表
+    const dirs = Array.isArray(data.dirs) ? data.dirs : [];
+    if (!dirs.length) {
+      body.append(text('div', 'dir-picker-hint', '（无子目录）'));
+      return;
+    }
+    const list = text('div', 'dir-picker-list', '');
+    for (const d of dirs) {
+      const btn = navBtn(`📁 ${d.name}`, d.path);
+      btn.dataset.dirName = d.name;
+      list.append(btn);
+    }
+    body.append(list);
+  }
+
+  function text(tag, className, content) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (content) n.textContent = content;
+    return n;
+  }
+
+  function navBtn(label, target) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'mini-btn dir-picker-nav';
+    btn.dataset.nav = target;
+    btn.textContent = label;
+    btn.addEventListener('click', () => {
+      // 换目标 ⇒ 之前的「选择此目录」作废。
+      //   不清的后果（实测过的 bug）：在 A 点过选择、再导航到 B 点添加，提交的却是 A，
+      //   服务端按路径判重正确返回 409「该目录已登记为资源根」——
+      //   用户看到的是"我明明没登记 B，凭什么说已登记"，且「✓ 已选择」还挂在 A 上。
+      pickedPath = '';
+      currentPath = target;
+      renderBody();
+    });
+    return btn;
+  }
+
+  /**
+   * 添加：**只提交当前浏览的目录**。
+   *
+   * 为什么不再用 `pickedPath || currentPath`：pickedPath 是"点过选择此目录"留下的，
+   *   一旦导航没清（历史 bug），它就会是**上一次选过的目录** ⇒ 提交一个与当前视图无关的目标
+   *   ⇒ 服务端按路径判重正确返回 409，而用户完全看不出为什么。
+   *   现在 navBtn 已经"导航即清除"，pickedPath 只可能是空或等于 currentPath；
+   *   这里再兜一层：提交值永远来自 currentPath，两者不一致时不可能发生错位。
+   */
+  async function doAdd() {
+    if (busy) return;
+    const path = currentPath;
+    const nameInput = q('[data-role="name"]');
+    const name = nameInput ? nameInput.value.trim() : '';
+    if (!path) return;
+    clearAlert();
+    busy = true;
+    try {
+      const res = typeof onPick === 'function' ? await onPick({ path, name }) : false;
+      // onPick 可能返回布尔（既有实现）或 { ok, error }（更细的实现）——两种都认
+      const ok = res && typeof res === 'object' ? res.ok === true : res === true;
+      if (ok) { rememberDir(path); close(); return; }
+      // 失败：**对话框不关**，把原因写在底部输入行上方，用户改完就能重试
+      showAlert(pickErrorText(res));
+    } finally {
+      busy = false;
+    }
+  }
+
+  /**
+   * 取失败原因文本。
+   * 优先用 onPick 直接给回来的 error（{ ok:false, error }）；
+   * 否则问 getLastError（root-manager 会把上一次失败文案记下来）。
+   * @param {unknown} res onPick 的返回值
+   * @returns {string}
+   */
+  function pickErrorText(res) {
+    if (res && typeof res === 'object' && typeof res.error === 'string' && res.error) return res.error;
+    try {
+      if (typeof getLastError === 'function') {
+        const t = getLastError();
+        if (typeof t === 'string' && t) return t;
+      }
+    } catch { /* 取不到就退回通用文案 */ }
+    return '添加失败，请检查目录路径与名称后重试';
+  }
+
+  /** 把失败原因显示在对话框内 */
+  function showAlert(text) {
+    const box = q('[data-role="alert"]');
+    if (!box) return;
+    box.textContent = String(text || '');
+    box.hidden = !box.textContent;
+  }
+
+  /** 收起错误行（重试时先清掉，避免旧错误杵在那儿） */
+  function clearAlert() {
+    const box = q('[data-role="alert"]');
+    if (!box) return;
+    box.textContent = '';
+    box.hidden = true;
+  }
+
+  /** 打开面板（默认从上次目录或 / 开始） */
+  function open(startPath) {
+    ensureShell();
+    panel.hidden = false;
+    pickedPath = '';
+    currentPath = startPath || lastDir() || '/';
+    const nameInput = q('[data-role="name"]');
+    if (nameInput) nameInput.value = '';
+    renderBody();
+    return panel;
+  }
+
+  /** 关闭并销毁（不留隐藏容器） */
+  function close() {
+    if (!panel) return;
+    panel.remove();
+    panel = null;
+  }
+
+  return {
+    open, close,
+    /** 只读：当前浏览路径 / 已选路径（断言用） */
+    get state() { return { open: !!panel, currentPath, pickedPath }; },
+    /** 断言用：直接设定路径后重绘（等价于用户一路点进来） */
+    goto(path) { currentPath = path; return panel ? renderBody() : null; },
+  };
+}