modelstage 0.0.0-stage → 0.5.28

package/src/web/infra/slot-registry.js

@@ -0,0 +1,402 @@
+// infra/slot-registry.js —— 插件插槽注册表（**只登记、不渲染**）
+//
+// 为什么单独成模块、且不碰 DOM：
+//   · 校验逻辑（四类拒绝 + 顺序）是本阶段最容易写错的部分，必须能在 `node --test` 里直接跑；
+//     一旦 import 里带上 document/window，就只能靠浏览器套件测，回归成本高一个量级。
+//   · 装配层（plugin-host.js）只负责"把插件声明喂进来、把 disposer 挂进回收链"，
+//     渲染（S2）另外接 —— 模块边界就是"纯校验 + 纯登记"。
+//
+// 校验顺序**固定**（设计 §4.2，测试会钉住）：
+//   ① 同步窗口（不在脚本装载期的调用直接拒，见下）
+//   ② unknown-slot     目录里没有这个名字
+//   ③ slot-not-open    目录里有，但阶段未到（必须先于 ④，否则会被误报成"没声明"）
+//   ④ undeclared-slot  插件清单没声明它
+//   ⑤ risk-mismatch    声明了，但风险等级与目录不符（错误里带双方等级）
+//   之后再查 spec 形状（id 必填 / 前缀 / 同插槽内重名）
+
+/** 插槽名里的占位符写法：`panel.group.<groupId>` */
+const PLACEHOLDER_RE = /<[^>]+>/;
+
+/** 阶段序号：S1 < S2 < …（非 Sx 的值排最前，视为"未开放"） */
+function stageRank(stage) {
+  const m = /^S(\d+)$/i.exec(String(stage || '').trim());
+  return m ? Number(m[1]) : 0;
+}
+
+/**
+ * 把目录里的带占位符名字编译成匹配器。
+ * 例：`panel.group.<groupId>` → /^panel\.group\.\\S+$/
+ * @param {string} pattern
+ * @returns {{test: (name: string) => boolean, dynamic: boolean}}
+ */
+function compilePattern(pattern) {
+  const text = String(pattern || '');
+  if (!PLACEHOLDER_RE.test(text)) {
+    return { test: (name) => name === text, dynamic: false };
+  }
+  const escaped = text
+    .split(/(<[^>]+>)/)
+    // 占位符吃"一段非空、非空白"，**允许带点**：设计 §8.2 要求 panel.control.<key> 的 key 写成
+    //   plugin.<pluginId>.<key>（本身含两个点），禁点会让那条规范永远匹配不上。
+    .map((part) => (PLACEHOLDER_RE.test(part) ? '\\S+' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    .join('');
+  const re = new RegExp(`^${escaped}$`);
+  return { test: (name) => re.test(name), dynamic: true };
+}
+
+/**
+ * 造一个插槽注册表。
+ * @param {{
+ *   catalog?: Array<{name:string, type:string, risk:string, stage:string, desc?:string}>,
+ *   declaredByPlugin?: Record<string, Array<{name:string, risk:string}>>,
+ *   onReject?: (rej: object) => void,
+ *   openStage?: string,
+ *   isInLoadWindow?: () => boolean,
+ * }} [opts]
+ */
+export function createSlotRegistry(opts = {}) {
+  const catalog = Array.isArray(opts.catalog) ? opts.catalog : [];
+  const declaredByPlugin = opts.declaredByPlugin && typeof opts.declaredByPlugin === 'object'
+    ? opts.declaredByPlugin : {};
+  const onReject = typeof opts.onReject === 'function' ? opts.onReject : () => {};
+  const openStage = String(opts.openStage || 'S1');
+  const isInLoadWindow = typeof opts.isInLoadWindow === 'function' ? opts.isInLoadWindow : () => true;
+  /**
+   * 已知的内置分组 id 集合（由装配层传入 PANEL_GROUPS 的 id）。
+   * 用途：区分"引用内置组"与"新建插件组"——前者直接放行，后者必须带 plugin.<pluginId>. 前缀。
+   */
+  const groupIds = opts.groupIds instanceof Set ? opts.groupIds : new Set(opts.groupIds || []);
+  /**
+   * 某插件在清单里声明过的 settings 键（`plugin.json` 的 settings[].key）。
+   * 用途：校验 spec.setting —— 控件声明的存值键必须真的声明过，否则会写出一个
+   *   渲染层永远不认的孤儿键（"改了没反应"类问题的源头）。
+   */
+  const settingsKeysOf = typeof opts.settingsKeysOf === 'function' ? opts.settingsKeysOf : () => [];
+  /**
+   * 内置面板控件的 id 集合（`panel.control.<key>` 的 key 只能指向它们）。
+   * 为什么要有它：替换类插槽**不允许静默新建控件**（那是分组插槽的职责）——
+   *   指向不存在的 id 时必须当场拒绝并说清，否则插件以为替换成功、用户什么也没看到。
+   */
+  /** 全局注册序号（单值插槽的"后注册胜出"依赖它） */
+  let seqCounter = 0;
+  const builtinControlIds = opts.builtinControlIds instanceof Set
+    ? opts.builtinControlIds
+    : new Set(opts.builtinControlIds || []);
+
+  /** 目录项 + 编译后的匹配器（构造时算一次，注册期不重复编译） */
+  const entries = catalog.map((e) => ({ ...e, matcher: compilePattern(e && e.name) }));
+  /** 已登记的插槽：pluginId → [{ name, id, order, label, spec, catalogRisk }] */
+  const byPlugin = new Map();
+  /** 拒绝记录（最近 50 条，测试与排障都读它） */
+  const rejects = [];
+
+  /** 按名字找目录项（静态名优先，其次按占位符模式匹配） */
+  function findCatalogEntry(name) {
+    const hit = entries.find((e) => !e.matcher.dynamic && e.matcher.test(name));
+    if (hit) return hit;
+    return entries.find((e) => e.matcher.dynamic && e.matcher.test(name)) || null;
+  }
+
+  /** 该插件在清单里声明过哪些插槽（服务端 slotErrors 里被丢的项不算声明成功） */
+  function declaredOf(pluginId) {
+    const list = declaredByPlugin[pluginId];
+    if (!Array.isArray(list)) return [];
+    // 服务端下发的 slots 是**字符串数组**（slot-catalog.mjs:171-188 只收非空字符串）；
+    //   同时兼容 {name, risk} 形状（老版本/测试注入），统一成同一种记录
+    return list
+      .map((item) => (typeof item === 'string' ? { name: item.trim(), risk: null } : {
+        name: String((item && item.name) || '').trim(),
+        risk: item && item.risk ? String(item.risk) : null,
+      }))
+      .filter((d) => d.name);
+  }
+
+  /** 记一条拒绝：给调用方 false、给 onReject、给 stats */
+  function reject(pluginId, name, code, why, detail) {
+    const rec = { pluginId: pluginId || null, name: name || null, code, why, at: Date.now(), ...(detail || {}) };
+    rejects.push(rec);
+    if (rejects.length > 50) rejects.shift();
+    try { onReject(rec); } catch { /* 拒绝回执失败不影响拒绝本身 */ }
+    return rec;
+  }
+
+  /** 已登记列表（按插件） */
+  function listOf(pluginId) {
+    return byPlugin.get(pluginId) || [];
+  }
+
+  /**
+   * 登记一个插槽。
+   * @param {string} pluginId 注册者（必须与清单里的 id 一致）
+   * @param {string} name 插槽名，如 `panel.group.settings`
+   * @param {object} spec 插件声明：{ id, order?, label?, render?, onAction? }
+   * @returns {null | (() => void)} 成功返回 disposer；失败返回 null（原因走 onReject + stats）
+   */
+  /**
+   * 校验"这个插槽能不能被这个插件注册"（前三类 + 风险等级）。
+   * 顺序固定：unknown-slot → slot-not-open → undeclared-slot → risk-mismatch。
+   * @param {string} pid
+   * @param {string} slotName
+   * @returns {{ok: true, entry: object, catalogRisk: string} | {ok: false}}
+   */
+  function checkSlotAllowed(pid, slotName, opts = {}) {
+    // ② 目录里没有
+    const entry = findCatalogEntry(slotName);
+    if (!entry) {
+      reject(pid, slotName, 'unknown-slot',
+        `插槽「${slotName}」不在插槽目录里（可用：${entries.map((e) => e.name).join(' / ')}）`);
+      return { ok: false };
+    }
+    // ③ 阶段未到（必须先于 ④：否则"目录里有但没开放"会被误报成"插件没声明"）
+    if (stageRank(entry.stage) > stageRank(openStage)) {
+      reject(pid, slotName, 'slot-not-open',
+        `插槽「${slotName}」在当前阶段（${openStage}）尚未开放（目录标注 ${entry.stage}）`,
+        { catalogStage: entry.stage, openStage });
+      return { ok: false };
+    }
+    // ④ 插件清单没声明
+    //   implicitDeclare（兼容层用）：老接口 registerControls 的插件不可能在 plugin.json 里写 slots，
+    //   把它当成"隐式声明了它要注册的那个分组插槽"——否则老插件一升级就全部失效。
+    //   注意：隐式只作用于**声明检查**，前缀/阶段/风险等级/重名检查一条都不放过。
+    const declared = opts.implicitDeclare
+      ? { name: slotName, risk: null }
+      : (declaredOf(pid).find((d) => d.name === slotName) || null);
+    if (!declared) {
+      reject(pid, slotName, 'undeclared-slot',
+        `插件 ${pid} 没有在 plugin.json 的 slots 里声明「${slotName}」，拒绝注册`,
+        { declared: declaredOf(pid).map((d) => d.name) });
+      return { ok: false };
+    }
+    // ⑤ 风险等级不符（目录为准；清单里的 risk 只作显式确认）
+    const declaredRisk = String(declared.risk || '').trim();
+    const catalogRisk = String(entry.risk || '').trim();
+    if (declaredRisk && catalogRisk && declaredRisk !== catalogRisk) {
+      reject(pid, slotName, 'risk-mismatch',
+        `插槽「${slotName}」风险等级不符：清单声明 ${declaredRisk}，目录要求 ${catalogRisk}`,
+        { catalogRisk, declaredRisk });
+      return { ok: false };
+    }
+    return { ok: true, entry, catalogRisk };
+  }
+
+  /**
+   * 校验 spec 形状：id 必填、必须带插件前缀（设计 §8.2）、同插槽内不许重名。
+   * @param {string} pid
+   * @param {string} slotName
+   * @param {object} spec
+   * @returns {{ok: true, id: string, order: number, label: string} | {ok: false}}
+   */
+  /**
+   * 键值插槽的目标控件校验：`panel.control.plugin.<pid>.<内置控件 id>`。
+   *
+   * 三条规则：
+   *   ① 后缀（目标 id）不能空
+   *   ② 目标必须是**既有内置控件** —— 键值插槽的语义是"替换"，不是"新建"（新建归分组插槽）
+   *   ③ 抢占按**目标控件**判，不是按 slot 名：两个插件的 key 天生不同，只有目标会撞
+   * @param {string} pid 插件 id
+   * @param {string} slotName 插槽名
+   * @param {string} prefix `plugin.<pid>.`
+   * @returns {{ok: true, target: string}|{ok: false}}
+   */
+  /**
+   * `spec.setting` 校验：给了就必须是**该插件清单里声明过的**键，且带 `plugin.<pid>.` 前缀。
+   * 为什么要在注册期拦：写错一个键名会得到"控件能点、值写进了没人读的孤儿键"，
+   *   表现为"改了没反应"，比直接报错难查得多。
+   * @param {string} pid 插件 id
+   * @param {string} slotName 插槽名（只为日志）
+   * @param {string} setting 设置键
+   * @returns {boolean} 是否通过
+   */
+  function checkSettingKey(pid, slotName, setting) {
+    const declaredKeys = new Set((settingsKeysOf(pid) || []).map(String));
+    if (!declaredKeys.has(setting)) {
+      reject(pid, slotName, 'undeclared-setting',
+        `spec.setting「${setting}」不在该插件清单的 settings 里声明过（已声明：${[...declaredKeys].join(' / ') || '无'}）`);
+      return false;
+    }
+    if (!setting.startsWith(`plugin.${pid}.`)) {
+      reject(pid, slotName, 'bad-setting-prefix',
+        `spec.setting「${setting}」必须以 plugin.${pid}. 开头（设计 §8.3：插件设置键带插件前缀）`);
+      return false;
+    }
+    return true;
+  }
+
+  function checkKeyedTarget(pid, slotName, prefix, setting) {
+    const raw = slotName.slice('panel.control.'.length);
+    const tail = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+    if (!tail) {
+      reject(pid, slotName, 'missing-target',
+        '键值插槽的目标控件 id 为空：应写成 panel.control.plugin.<pluginId>.<内置控件 id>');
+      return { ok: false };
+    }
+    if (!builtinControlIds.has(tail)) {
+      reject(pid, slotName, 'unknown-control',
+        `目标控件「${tail}」不在内置控件表里（替换只能指向既有控件；新建控件请用分组插槽 panel.group.*）`);
+      return { ok: false };
+    }
+    // 替换型控件**必须**带自己的 setting：值域与身份绑定，绝不与内置改动共用一个存储槽
+    //   （共用会出现"存储旧值不在新值域 ⇒ 替换期间无选中项"，那是根因层面的错配，不是显示小瑕疵）
+    if (!setting) {
+      reject(pid, slotName, 'missing-setting',
+        '替换型控件不得复用原生设置键，请声明自己的 setting（形如 plugin.<pluginId>.<key>，并在清单 settings 里声明）；'
+        + '纯动作按钮请改用 toolbar.actions 或分组插槽新增控件');
+      return { ok: false };
+    }
+    const holder = [...byPlugin.values()].flat().find((r) => String((r && r.target) || '') === tail);
+    if (holder) {
+      reject(pid, slotName, 'control-taken',
+        `内置控件「${tail}」已被插件「${holder.pluginId}」占位（后注册者被拒；先卸载或改用分组插槽新增控件）`);
+      return { ok: false };
+    }
+    return { ok: true, target: tail };
+  }
+
+  function checkSpec(pid, slotName, spec) {
+    // spec.setting（可选）：统一"控件存值键"与"清单设置键"（校验细节见 checkSettingKey）
+    const setting = String((spec && spec.setting) || '').trim();
+    if (setting && !checkSettingKey(pid, slotName, setting)) return { ok: false };
+    // 分组 id 规则（设计 §七·一）：内置组直接用 id；插件新建分组必须带 plugin.<pluginId>. 前缀。
+    //   放在注册期而不是渲染期：渲染期被拒时控件"登记成功却不显示"，插件作者会以为系统坏了。
+    const gm = /^panel\.group\.(.+)$/.exec(slotName);
+    if (gm) {
+      const gid = gm[1];
+      const isKnown = groupIds.has(gid);
+      const isPluginOwned = gid.startsWith(`plugin.${pid}.`) && gid.length > `plugin.${pid}.`.length;
+      if (!isKnown && !isPluginOwned) {
+        reject(pid, slotName, 'bad-group-id',
+          `分组「${gid}」不存在；新建分组的 id 必须写成 plugin.<pluginId>.<name>（当前插件 ${pid}，应形如 plugin.${pid}.<name>）`);
+        return { ok: false };
+      }
+    }
+    const id = String((spec && spec.id) || '').trim();
+    if (!id) { reject(pid, slotName, 'missing-id', 'spec.id 必填（同插槽内唯一，用于回收与冲突提示）'); return { ok: false }; }
+    // 前缀强制只适用于**键值插槽**（设计 §8.2：panel.control.<key> 的 key 必须写成 plugin.<pluginId>.<key>）。
+    //   分组插槽（panel.group.*）里的控件 id 只需全局唯一 —— 它的归属已经由 pluginId 记录，
+    //   强行加前缀会把插件自己习惯的命名一脚踢开（验收夹具 zzfixture.amount 就是这么被误拒的）。
+    const isKeyed = /^panel\.control\./.test(slotName);
+    const prefix = `plugin.${pid}.`;
+    if (isKeyed && !id.startsWith(prefix)) {
+      reject(pid, slotName, 'bad-id-prefix', `键值插槽的 spec.id「${id}」必须带插件前缀 ${prefix}（设计 §8.2）`);
+      return { ok: false };
+    }
+    // 键值插槽：解析目标控件 + 抢占检测（细节见 checkKeyedTarget）
+    if (isKeyed) {
+      const keyed = checkKeyedTarget(pid, slotName, prefix, setting);
+      if (!keyed.ok) return { ok: false };
+      return { ok: true, id, setting, target: keyed.target };
+    }
+    if (listOf(pid).some((r) => r.name === slotName && r.id === id)) {
+      reject(pid, slotName, 'duplicate-id', `插槽「${slotName}」里已存在 id「${id}」`, { id });
+      return { ok: false };
+    }
+    return {
+      ok: true,
+      id,
+      order: Number.isFinite(Number(spec && spec.order)) ? Number(spec.order) : 1000,
+      label: String((spec && spec.label) || id),
+      setting,          // '' = 用 control id 存值（兼容既有插件）
+    };
+  }
+
+  /**
+   * 登记一个插槽（只登记，不渲染）。
+   * @param {string} pluginId 注册者（必须与清单里的 id 一致）
+   * @param {string} name 插槽名，如 `panel.group.settings`
+   * @param {object} spec 插件声明：{ id, order?, label?, render?, onAction? }
+   * @returns {null | (() => void)} 成功返回 disposer；失败返回 null（原因走 onReject + stats）
+   */
+  function register(pluginId, name, spec, opts = {}) {
+    const pid = String(pluginId || '').trim();
+    const slotName = String(name || '').trim();
+
+    // ① 同步窗口：不在脚本装载期的调用一律拒（异步注册在 S1 就是明确不支持）
+    if (!isInLoadWindow()) {
+      reject(pid, slotName, 'not-in-load-window',
+        '不在脚本装载期：slots.register 必须在插件脚本顶层同步调用（await/Promise/setTimeout 之后的注册不被支持）');
+      return null;
+    }
+    if (!pid) { reject('', slotName, 'missing-plugin-id', '缺少 pluginId（宿主未提供装载上下文）'); return null; }
+    if (!slotName) { reject(pid, '', 'missing-slot-name', '缺少插槽名'); return null; }
+
+    const allowed = checkSlotAllowed(pid, slotName, opts);
+    if (!allowed.ok) return null;
+    const shape = checkSpec(pid, slotName, spec);
+    if (!shape.ok) return null;
+
+    const record = {
+      pluginId: pid, name: slotName, id: shape.id, order: shape.order, label: shape.label,
+      // 全局注册序号：单值插槽（panel.brand）靠它判"谁是最后注册的那个"，
+      //   不能按 order（那是展示顺序）也不能按插件分组后的数组位置（跨插件会乱）
+      seq: (seqCounter += 1),
+      setting: shape.setting || '',
+      target: shape.target || '',
+      risk: allowed.catalogRisk, spec: spec || {},
+      // 兼容层来的登记留个标记：排查"这个控件哪来的"时能一眼分清
+      via: opts.implicitDeclare ? 'legacy-registerControls' : 'slots.register',
+    };
+    const list = byPlugin.get(pid) || [];
+    list.push(record);
+    byPlugin.set(pid, list);
+
+    let disposed = false;
+    return function disposeSlot() {
+      if (disposed) return;                       // 幂等：重复调用不会误删别人
+      disposed = true;
+      const cur = byPlugin.get(pid) || [];
+      const i = cur.indexOf(record);
+      if (i >= 0) cur.splice(i, 1);
+      if (!cur.length) byPlugin.delete(pid);
+    };
+  }
+
+  /**
+   * 回收某个插件的全部插槽登记（卸载插件时调；与逐个 disposer 等价，但更省事）。
+   * @param {string} pluginId
+   * @returns {number} 回收条数
+   */
+  function disposeAll(pluginId) {
+    const pid = String(pluginId || '').trim();
+    const list = byPlugin.get(pid) || [];
+    byPlugin.delete(pid);
+    return list.length;
+  }
+
+  /** 快照（测试与 __SLOT_STATS__ 读它） */
+  function stats() {
+    const plugins = {};
+    let total = 0;
+    for (const [pid, list] of byPlugin) {
+      plugins[pid] = list.length;
+      total += list.length;
+    }
+    return {
+      openStage,
+      catalogSize: entries.length,
+      total,
+      byPlugin: plugins,
+      // 明细保留必要字段即可：spec 里可能有函数，不能直接序列化给测试
+      entries: [...byPlugin].flatMap(([pid, list]) => list.map((r) => ({
+        pluginId: pid, name: r.name, id: r.id, order: r.order, label: r.label, risk: r.risk,
+        setting: r.setting || '', seq: r.seq || 0, target: r.target || '', via: r.via || 'slots.register',
+      }))),
+      rejects: rejects.slice(),
+    };
+  }
+
+  /**
+   * 供**渲染层**读取的登记明细（含 spec，能拿到 render 函数）。
+   *
+   * 与 stats() 的区别：stats() 是给测试/__SLOT_STATS__ 的可序列化快照（不含函数），
+   *   这里是装配期真正要拿去渲染的对象；两者共用一个真相（byPlugin），只是视图不同。
+   * @returns {Array<{pluginId:string,name:string,id:string,order:number,label:string,risk:string,spec:object}>}
+   */
+  function renderEntries() {
+    return [...byPlugin].flatMap(([pid, list]) => list.map((r) => ({
+      pluginId: pid, name: r.name, id: r.id, order: r.order, label: r.label, risk: r.risk,
+      setting: r.setting || '', target: r.target || '', seq: r.seq || 0, spec: r.spec || {},
+    })));
+  }
+
+  return { register, disposeAll, stats, renderEntries };
+}

package/src/web/infra/vfs.js

@@ -0,0 +1,247 @@
+// vfs.js —— 虚拟文件系统（VirtualFS）：内存资源成为一等公民
+//
+// 做什么：插件把内存里的文件（Blob / 字符串）按「前缀 + 相对路径」注册进来，
+//   加载器拿原始 URL 来问 resolve()，命中就返回一个可用的 Blob URL，未命中返回 null。
+// 为什么需要：Live2D / 资源包等插件的资源常常不是磁盘文件，以前只能 patch 加载器；
+//   有了 VirtualFS，插件只注册文件，加载器保持原样（未命中回落原 URL，天然可退化）。
+//
+// 设计约束：
+//   · 纯模块：不碰 DOM、不 import 任何模块，可在 Node 里直接单测；
+//   · Blob URL **懒创建 + 缓存**：第一次 resolve 才建，重复 resolve 复用同一个；
+//   · revoke(prefix) 释放该前缀下所有 Blob URL 并注销该前缀（之后 resolve 返回 null）；
+//   · prefix 全局唯一：重复注册直接抛错，避免"谁覆盖谁"的隐性 bug；
+//   · 路径归一化统一处理 `./`、`../`、查询串、哈希、URL 编码、反斜杠。
+
+/**
+ * 把任意写法的路径归一化成「无前导斜杠、无 ./、无 ../、无查询串」的相对路径。
+ * @param {string} raw
+ * @returns {string|null} 归一化结果；无法解析时返回 null
+ */
+function normalizePath(raw) {
+  if (typeof raw !== 'string' || !raw) return null;
+  let p = raw.split('#')[0].split('?')[0];
+  // 编码可能套了两层（例如 %2520），最多解两层，解不开就保持原样
+  for (let i = 0; i < 2; i += 1) {
+    try {
+      const decoded = decodeURIComponent(p);
+      if (decoded === p) break;
+      p = decoded;
+    } catch {
+      break;
+    }
+  }
+  p = p.replace(/\\/g, '/');
+  const parts = [];
+  for (const seg of p.split('/')) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') { parts.pop(); continue; }
+    parts.push(seg);
+  }
+  return parts.join('/');
+}
+
+/**
+ * 取 URL 里可参与匹配的部分。
+ *
+ * http(s) 取 pathname（真实网络资源）；
+ * **自定义 scheme（vfs://…）整体按路径归一化** —— 它本身就是"路径标识"，不是网络地址。
+ * 早期一律走 new URL()：`vfs://prov/root/a.json` 会被拆成 host=prov + pathname=/root/a.json，
+ * 于是与注册时归一化出的 `vfs:/prov/root` 前缀永远对不上，vfs:// 路径全部 resolve 失败。
+ * @param {string} url
+ * @returns {string|null}
+ */
+function pathOfUrl(url) {
+  const text = String(url == null ? '' : url);
+  if (!text) return null;
+  const customScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) && !/^https?:\/\//i.test(text);
+  if (customScheme) return normalizePath(text);
+  try {
+    const parsed = new URL(text, 'http://vfs.local/');
+    return normalizePath(parsed.pathname);
+  } catch {
+    return normalizePath(text);
+  }
+}
+
+/** 字节数：Blob 用 size，字符串按 UTF-8 估算 */
+function sizeOf(value) {
+  if (typeof value === 'string') {
+    if (typeof TextEncoder === 'function') return new TextEncoder().encode(value).length;
+    return value.length;
+  }
+  if (value && typeof value.size === 'number') return value.size;
+  return 0;
+}
+
+/**
+ * 创建虚拟文件系统。
+ * @param {{
+ *   createObjectURL?: (blob: Blob) => string,
+ *   revokeObjectURL?: (url: string) => void,
+ * }} [options] 可注入 URL 工厂（Node 环境没有 URL.createObjectURL 时用 fake 单测）
+ */
+export function createVirtualFS(options = {}) {
+  const createObjectURL = typeof options.createObjectURL === 'function'
+    ? options.createObjectURL
+    : (blob) => URL.createObjectURL(blob);
+  const revokeObjectURL = typeof options.revokeObjectURL === 'function'
+    ? options.revokeObjectURL
+    : (url) => URL.revokeObjectURL(url);
+
+  /** prefix → { files: Map<relPath, Blob|string>, urls: Map<relPath, blobUrl> } */
+  const entries = new Map();
+  let hits = 0;
+  let misses = 0;
+  let createdUrls = 0;
+
+  /**
+   * 注册一批文件。
+   * @param {string} prefix 前缀（全局唯一），如 `/live2d-lib/` 或 `atlas/`
+   * @param {Map<string, Blob|string>|Record<string, Blob|string>} files 相对路径 → 内容
+   */
+  function register(prefix, files) {
+    const key = normalizePath(prefix);
+    if (!key) throw new Error('VirtualFS.register: prefix 不能为空');
+    if (entries.has(key)) throw new Error(`VirtualFS.register: prefix 已注册：${prefix}`);
+
+    const src = files instanceof Map ? files : new Map(Object.entries(files || {}));
+    const normalized = new Map();
+    for (const [rel, value] of src) {
+      const p = normalizePath(rel);
+      if (!p) throw new Error(`VirtualFS.register: 非法相对路径：${rel}`);
+      if (typeof value !== 'string' && !(value && typeof value === 'object' && typeof value.size === 'number')) {
+        throw new Error(`VirtualFS.register: 内容必须是 Blob 或字符串：${rel}`);
+      }
+      normalized.set(p, value);
+    }
+    entries.set(key, { files: normalized, urls: new Map() });
+  }
+
+  /**
+   * 某前缀下已注册多少个文件（**只读诊断接口**；0 = 这个前缀压根没注册过）。
+   *
+   * 为什么需要它：`stats()` 给的是**全部前缀的合计**，看不出"我请求的这个前缀下一个文件都没有"
+   *   这个关键区别 —— 而那正是"prefix 对不上（产物里存的是旧 prefix）"与
+   *   "这个包真的缺这个文件"两种故障的分水岭。没有它，排查只能靠猜。
+   * 不改任何行为：只查表，不注册、不撤销、不创建 Blob、不计命中/未命中。
+   * @param {string} prefix 原始写法（内部按与 register 相同的规则归一化）
+   * @returns {number}
+   */
+  function prefixFileCount(prefix) {
+    const key = normalizePath(prefix);
+    if (!key) return 0;
+    const entry = entries.get(key);
+    return entry && entry.files ? entry.files.size : 0;
+  }
+
+  /** 懒创建并缓存某文件的 Blob URL */
+  function urlFor(prefix, rel, value) {
+    const entry = entries.get(prefix);
+    const cached = entry.urls.get(rel);
+    if (cached) return cached;
+    const blob = typeof value === 'string' ? new Blob([value]) : value;
+    const url = createObjectURL(blob);
+    entry.urls.set(rel, url);
+    createdUrls += 1;
+    return url;
+  }
+
+  /**
+   * 把原始 URL 解析成可用地址。
+   * @param {string} url
+   * @returns {string|null} 命中返回 Blob URL；未命中返回 null（调用方回落原 URL）
+   */
+  function resolve(url) {
+    const target = pathOfUrl(url);
+    if (!target) { misses += 1; return null; }
+    for (const [prefix, entry] of entries) {
+      if (target !== prefix && !target.startsWith(`${prefix}/`)) continue;
+      const rel = target === prefix ? '' : target.slice(prefix.length + 1);
+      const value = entry.files.get(rel);
+      if (value === undefined) continue;
+      hits += 1;
+      return urlFor(prefix, rel, value);
+    }
+    misses += 1;
+    return null;
+  }
+
+  /**
+   * 释放某个前缀下的全部 Blob URL 并注销该前缀（之后 resolve 返回 null）。
+   * @param {string} prefix
+   * @returns {number} 释放的 URL 数量
+   */
+  function revoke(prefix) {
+    const key = normalizePath(prefix);
+    const entry = key ? entries.get(key) : null;
+    if (!entry) return 0;
+    let count = 0;
+    for (const url of entry.urls.values()) {
+      try { revokeObjectURL(url); count += 1; } catch { /* 释放失败继续 */ }
+    }
+    entry.urls.clear();
+    entries.delete(key);
+    return count;
+  }
+
+  /**
+   * 统计：前缀数、文件数、字节数、命中/未命中次数（+ 已创建 URL 数，便于验证懒创建）。
+   */
+  function stats() {
+    let files = 0;
+    let bytes = 0;
+    for (const entry of entries.values()) {
+      files += entry.files.size;
+      for (const value of entry.files.values()) bytes += sizeOf(value);
+    }
+    return { prefixes: entries.size, files, bytes, hits, misses, urls: createdUrls };
+  }
+
+  /**
+   * 列出某个前缀下已注册的**相对路径**（升序）。
+   *
+   * 与 resolve 的区别：resolve 按完整 VFS 地址取**内容**，这里只要**名字**——
+   *   面板 owner props 的 document.files 就是它（插件拿名字做判断，不需要字节）。
+   * 返回 null 表示"这个前缀还没注册"（≠ 已注册但为空数组）：
+   *   调用方要能区分"还没解包完"与"确实没有文件"，否则会给出误导性的空清单。
+   * @param {string} prefix 前缀（如 `vfs://xxx/`）
+   * @returns {string[]|null}
+   */
+  function list(prefix) {
+    const key = normalizePath(prefix);
+    const entry = key ? entries.get(key) : null;
+    if (!entry) return null;
+    return [...entry.files.keys()].sort();
+  }
+
+  return { register, resolve, revoke, stats, prefixFileCount, list };
+}
+
+/**
+ * 进程内共享实例（懒创建、幂等）。
+ *
+ * 为什么需要它：VirtualFS 是"注册方（插件/测试）"与"消费方（渲染器）"之间的唯一通道，
+ * 双方必须拿到**同一个实例** —— 各建一个的话 register 完也解析不到，表现为"接了但没生效"。
+ * 同时挂到 window.__VFS__ 作为诊断/验收入口（与 window.__DIAG__ 同一模式）：
+ * 便于在页面里手工 register 一段内存资源，再用 vfs:// 路径装载做端到端验证。
+ * @returns {ReturnType<typeof createVirtualFS>}
+ */
+let sharedInstance = null;
+export function getSharedVirtualFS() {
+  if (!sharedInstance) {
+    sharedInstance = createVirtualFS();
+    try {
+      if (typeof window !== 'undefined' && !window.__VFS__) window.__VFS__ = sharedInstance;
+    } catch { /* 只读环境忽略 */ }
+  }
+  return sharedInstance;
+}
+
+export default createVirtualFS;
+
+// 诊断入口立刻可用：不等第一次资源解析。
+// 为什么：验收入口/排查时需要在**加载之前**就能 register 一段内存资源，
+//   懒创建会让"先 register 再装载"的顺序做不出来（表现为 __VFS__ 是 undefined）。
+if (typeof window !== 'undefined') {
+  try { if (!window.__VFS__) window.__VFS__ = getSharedVirtualFS(); } catch { /* 只读环境忽略 */ }
+}