@aiti-ai/ext-shared 0.1.12 → 0.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,91 +1,121 @@
1
1
  /**
2
- * 扩展展示名(id → 双语友好名)——唯一权威来源。
2
+ * Extension display-name / self-description entry resolution (self-registered, no central table —
3
+ * 2026-11-15 refactor).
3
4
  *
4
- * 用途:扩展技术 id(如 aiti-cmd / aiti-git-review)对用户不友好,各扩展 client
5
- * (aiti-extman / aiti-helper …)展示扩展分组/列表时用它显示中文/英文友好名,
6
- * 表内缺失的扩展回退到 server name / id。
5
+ * Convention: each extension declares its self-description entries in its own index.ts ui.i18n
6
+ * (bundled at install; third-party extensions use the same mechanism):
7
+ * - "ext.displayName": display name (zh-CN + en; English in en mode, Chinese in zh mode)
8
+ * - "ext.description": one-line description (en table optional; zh mode falls back to the raw manifest)
9
+ * - "feat.<featureId>": feature toggle label (same as above)
10
+ * Lookup rule = the current locale's exact table, no cascading: the raw manifest text IS Chinese
11
+ * (zh-CN source), so only the current locale's own table is honored — en-table entries cover en
12
+ * mode; zh mode without an entry naturally falls back to the raw text.
7
13
  *
8
- * 约定:新增扩展时在此补一行(en + zh)。此表只放「展示名」,不做逻辑。
14
+ * registry: /api/extensions/manifest fetched once, caching every extension's ui.i18n (each
15
+ * extension calls primeExtRegistry(apiUrlFn) at register time to inject a basePath-aware fetch
16
+ * primitive; not-ready / absent falls back to fallback).
17
+ * Scenarios that have only an id without a manifest object (AI Helper grouping, dialog 🤖 button,
18
+ * etc.) go through here.
9
19
  */
10
20
 
11
- export const EXT_DISPLAY_NAMES: Record<string, { en: string; zh: string }> = {
12
- "aiti-acp-agent": { en: "ACP Session Backend", zh: "ACP 会话后端" },
13
- "aiti-ai-input": { en: "AI Input Enhancer", zh: "AI 输入增强" },
14
- "aiti-ai-schedule": { en: "AI Schedule", zh: "AI 定时任务" },
15
- "aiti-ai-speek": { en: "AI Voice Reading", zh: "AI 语音朗读" },
16
- "aiti-ai-usage": { en: "AI Usage", zh: "AI 用量统计" },
17
- "aiti-append-system": { en: "Append System Prompt", zh: "追加系统提示词" },
18
- "aiti-attach-agent": { en: "Attach Session Backend", zh: "附着会话后端" },
19
- "aiti-channels": { en: "IM Channels", zh: "IM 渠道" },
20
- "aiti-claude-code-agent": { en: "Claude Code Session Backend", zh: "Claude Code 会话后端" },
21
- "aiti-cmd": { en: "Command Palette", zh: "命令面板" },
22
- "aiti-codex-agent": { en: "Codex Session Backend", zh: "Codex 会话后端" },
23
- "aiti-configs": { en: "Config Versioning & Self-check", zh: "配置版本化 + 崩溃自检" },
24
- "aiti-cpu-meter": { en: "CPU Meter", zh: "CPU 流畅度仪表" },
25
- "aiti-crash-fatal": { en: "Crash Drill (dev)", zh: "崩溃演习(开发)" },
26
- "aiti-cursor-agent": { en: "Cursor Session Backend", zh: "Cursor 会话后端" },
27
- "aiti-debug-inject": { en: "Remote Debug Inject", zh: "远程调试注入" },
28
- "aiti-devtools": { en: "Page DevTools", zh: "页面 AI 调试工具" },
29
- "aiti-devtools-vite": { en: "DevTools Vite Plugin", zh: "DevTools Vite 插件" },
30
- "aiti-devtools-vue": { en: "DevTools Vue Plugin", zh: "DevTools Vue 插件" },
31
- "aiti-doc-center": { en: "Doc Center", zh: "文档中心" },
32
- "aiti-draft-keeper": { en: "Draft Keeper", zh: "草稿保管员" },
33
- "aiti-echo-agent": { en: "Echo Session Backend", zh: "Echo 会话后端" },
34
- "aiti-editor": { en: "File Editor", zh: "文件编辑器" },
35
- "aiti-event-bus": { en: "Page Event Bus", zh: "页面事件总线" },
36
- "aiti-extman": { en: "Extension Manager", zh: "扩展管理器" },
37
- "aiti-float": { en: "Dialog Float Enhancer", zh: "弹窗浮动增强器" },
38
- "aiti-folder": { en: "Folder Browser", zh: "文件夹浏览器" },
39
- "aiti-git-review": { en: "Git Review", zh: "Git 代码审核" },
40
- "aiti-git-trace": { en: "AI Change Trace", zh: "AI 变更追踪" },
41
- "aiti-helper": { en: "AI Helper", zh: "AI 助手入口" },
42
- "aiti-inject": { en: "Debug Inject FAB", zh: "调试注入按钮" },
43
- "aiti-mcp-bridge": { en: "MCP Bridge", zh: "MCP 桥" },
44
- "aiti-model-check": { en: "Model Availability", zh: "模型可用性管理" },
45
- "aiti-model-wizard": { en: "Model Wizard", zh: "模型添加向导" },
46
- "aiti-msg-anchor": { en: "Message Anchor Banner", zh: "消息锚点横幅" },
47
- "aiti-msg-nav": { en: "Message Scroll Nav", zh: "消息滚动导航" },
48
- "aiti-msg-smart": { en: "Message Intelligence", zh: "消息智能" },
49
- "aiti-onlyoffice": { en: "OnlyOffice Editor", zh: "OnlyOffice 编辑" },
50
- "aiti-pi-agent": { en: "pi Session Backend", zh: "pi 会话后端" },
51
- "aiti-plan-first": { en: "Plan-First Reminder", zh: "方案先行" },
52
- "aiti-plan-review": { en: "Plan Review", zh: "方案评审" },
53
- "aiti-prompts": { en: "Prompt Snippets", zh: "Prompt 片段收藏库" },
54
- "aiti-qoder-agent": { en: "Qoder Session Backend", zh: "Qoder 会话后端" },
55
- "aiti-queue-keeper": { en: "Queue Keeper", zh: "队列管家" },
56
- "aiti-sheet-univer": { en: "Excel Editor", zh: "Excel 编辑器" },
57
- "aiti-subagents": { en: "Subagents", zh: "子代理" },
58
- "aiti-testagent": { en: "TestAgent · Java Debugging", zh: "TestAgent · Java 后端调试" },
59
- "aiti-ui-env": { en: "UI Environment", zh: "UI 环境(桌面/无头虚拟屏)" },
60
- "aiti-word-docx-preview": { en: "Word Preview", zh: "Word 预览" },
61
- "aiti-word-superdoc": { en: "Word Editor", zh: "Word 编辑" },
62
- "aiti-zcode-agent": { en: "ZCode Session Backend", zh: "ZCode 会话后端" },
63
- "demo": { en: "Demo Extension", zh: "示例扩展" },
64
- "demo-lazy": { en: "Demo Extension (Lazy)", zh: "示例扩展(懒加载)" },
65
- "devtools-vscode": { en: "VS Code Plugin", zh: "VS Code 插件" },
66
- "devtools-idea": { en: "IDEA Plugin", zh: "IDEA 插件" },
67
- "ext-jsx-client": { en: "JSX Client Template", zh: "扩展 JSX 客户端模板" },
68
- "service-tunnels": { en: "Service Tunnels", zh: "服务隧道" },
69
- "session-manager": { en: "Session Manager", zh: "会话管理器" },
70
- "sm-demo-source": { en: "Demo Session Source", zh: "第三方会话源示例" },
71
- };
72
-
73
- const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff]/;
74
-
75
- /** 当前界面语言(localStorage pi-locale,与宿主 useI18n 同源;缺省 en)。 */
76
- export function currentUiLocale(): "zh-CN" | "en" {
21
+ /** Current UI locale (localStorage pi-locale, same source as host useI18n; defaults to en). */
22
+ export function currentUiLocale(): "zh-CN" | "zh-TW" | "en" {
77
23
  try {
78
24
  const v = window.localStorage.getItem("pi-locale");
79
- if (v === "zh-CN" || v === "en") return v;
25
+ if (v === "zh-CN" || v === "zh-TW" || v === "en") return v;
80
26
  } catch { /* 存储不可用时用缺省 */ }
81
27
  return "en";
82
28
  }
83
29
 
84
- /** 按界面语言解析扩展展示名:zh → 双语表 zh / server name / id;
85
- * en → 双语表 en / 无 CJK 的 server name / id。 */
30
+ type UiI18n = Record<string, Record<string, string>> | null | undefined;
31
+ type ExtManifestEntry = { id: string; name?: string; ui?: { i18n?: UiI18n } | null };
32
+
33
+ // ---- registry (manifest ui.i18n cache; all data comes from each extension's own declarations, no central table) ----
34
+ let registry: Record<string, ExtManifestEntry> | null = null;
35
+ let registryPrimed = false;
36
+ let registryApiUrl: ((p: string) => string) | null = null;
37
+ const listeners = new Set<() => void>();
38
+
39
+ /** Inject the fetch primitive and prime the manifest cache (called once per extension at register; idempotent). */
40
+ export function primeExtRegistry(apiUrlFn?: (p: string) => string): void {
41
+ if (apiUrlFn) registryApiUrl = apiUrlFn;
42
+ if (registryPrimed || typeof window === "undefined") return;
43
+ const urlFn = registryApiUrl;
44
+ if (!urlFn) return; // fetch primitive not injected → consumers fall back to fallback
45
+ registryPrimed = true;
46
+ fetch(urlFn("/api/extensions/manifest"))
47
+ .then((r) => r.json())
48
+ .then((d) => {
49
+ const map: Record<string, ExtManifestEntry> = {};
50
+ for (const e of d?.extensions ?? []) if (e?.id) map[e.id] = e;
51
+ registry = map;
52
+ for (const l of [...listeners]) { try { l(); } catch { /* ignore */ } }
53
+ })
54
+ .catch(() => { registryPrimed = false; /* failure allows retry */ });
55
+ }
56
+
57
+ /** registry ready/change subscription (for consumer re-renders); returns a disposer. */
58
+ export function onExtRegistryReady(fn: () => void): () => void {
59
+ listeners.add(fn);
60
+ return () => { listeners.delete(fn); };
61
+ }
62
+
63
+ /** The current locale's exact entry table (deliberately non-cascading — see the file header). */
64
+ export function ui18nExact(ui18n: UiI18n, locale: string): Record<string, string> {
65
+ if (!ui18n) return {};
66
+ return ui18n[locale] ?? {};
67
+ }
68
+
69
+ const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff]/;
70
+
71
+ /** Resolve the self-description name via the registry (id-only scenarios: AI Helper grouping,
72
+ * dialog 🤖 etc.). ext.displayName entry (current locale's exact table) → raw text in zh mode /
73
+ * non-CJK fallback in en mode → id. */
86
74
  export function extDisplayName(id: string, fallbackName?: string | null): string {
87
- const entry = EXT_DISPLAY_NAMES[id];
88
- if (currentUiLocale() === "zh-CN") return (entry && entry.zh) || fallbackName || id;
89
- if (entry) return entry.en;
90
- return fallbackName && !CJK_RE.test(fallbackName) ? fallbackName : id;
75
+ const locale = currentUiLocale();
76
+ primeExtRegistry();
77
+ const entry = registry?.[id];
78
+ const over = entry ? ui18nExact(entry.ui?.i18n, locale)["ext.displayName"] : undefined;
79
+ if (over) return over;
80
+ const name = fallbackName ?? entry?.name ?? "";
81
+ if (!name) return id;
82
+ return locale === "zh-CN" ? name : CJK_RE.test(name) ? id : name;
83
+ }
84
+
85
+ /** Synchronous resolution when a full manifest object is available (pure-function scenarios like
86
+ * App Center buildApps). ext.displayName entry → raw text in zh mode / non-CJK raw in en mode → id. */
87
+ export function extNameFor(ext: { id: string; name?: string | null; ui?: { i18n?: UiI18n } | null } | undefined | null, locale: string): string {
88
+ if (!ext) return "";
89
+ const over = ui18nExact(ext.ui?.i18n, locale)["ext.displayName"];
90
+ if (over) return over;
91
+ const name = ext.name ?? "";
92
+ if (!name) return ext.id;
93
+ return locale === "zh-CN" ? name : CJK_RE.test(name) ? ext.id : name;
94
+ }
95
+
96
+ /** Extension description: overridden by the "ext.description" entry; falls back to the raw manifest. */
97
+ export function extDescriptionFor(ext: { description?: string | null; ui?: { i18n?: UiI18n } | null } | undefined | null, locale: string): string {
98
+ const over = ui18nExact(ext?.ui?.i18n, locale)["ext.description"];
99
+ return over || ext?.description || "";
100
+ }
101
+
102
+ /** Feature label: "feat.<id>" entry → "i18n:<key>" prefix (host translateExtItemText cascade) → raw manifest text. */
103
+ export function featureLabelFor(ext: { ui?: { i18n?: UiI18n } | null } | undefined | null, f: { id: string; label?: unknown }, locale: string): string {
104
+ const ui18n = ext?.ui?.i18n;
105
+ const over = ui18nExact(ui18n, locale)["feat." + f.id];
106
+ if (over) return over;
107
+ const raw = f.label != null ? String(f.label) : String(f.id);
108
+ if (raw.startsWith("i18n:")) {
109
+ const key = raw.slice("i18n:".length);
110
+ const tbl = ui18n?.[locale] ?? ui18n?.[locale.split("-")[0]] ?? ui18n?.en ?? Object.values(ui18n ?? {})[0];
111
+ return tbl?.[key] ?? key;
112
+ }
113
+ return raw;
114
+ }
115
+
116
+ /** Feature description: "feat.<id>.desc" override; falls back to the manifest original. */
117
+ export function featureDescriptionFor(ext: { ui?: { i18n?: UiI18n } | null } | undefined | null, f: { id: string; description?: unknown }, locale: string): string {
118
+ const over = ui18nExact(ext?.ui?.i18n, locale)["feat." + f.id + ".desc"];
119
+ if (over) return over;
120
+ return f.description != null ? String(f.description) : "";
91
121
  }
@@ -8,10 +8,8 @@
8
8
  * 3. registerItems 引用的 feature 必须在扩展 features 声明里存在(引用不存在的
9
9
  * feature id = 条目被永远隐藏的死卡——aiti-app-center feature-gate 过滤按此口径);
10
10
  * 4. index.ts 静态 ui 声明的插槽键同样是合法插槽名;
11
- * 5. 镜像脚本排除契约:__pycache__/*.pyc 必须在 sync 脚本排除集内
12
- * (文件系统拷贝绕过 gitignore 的泄露回归,见 sync 脚本 fix c6e38ac0)。
13
11
  *
14
- * Run: node --test pi-web-ext/_shared/ext-entry-contracts.test.mjs
12
+ * Run: node --test extensions/_shared/ext-entry-contracts.test.mjs(aiti-ai 仓根跑)
15
13
  */
16
14
  import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
17
15
  import { join, dirname } from "node:path";
@@ -28,14 +26,20 @@ const VALID_SLOTS = new Set([
28
26
  "toolbar", "sidebar", "sidebarFooter", "sessionTopbar", "sessionRowActions",
29
27
  "sessionRowLeading", "sessionRowMeta", "sidebarProjects", "sidebarContent",
30
28
  "dialogs", "banners", "pages", "chatInputTop", "chatOverlay",
29
+ // commands 目录槽:host registry.ts UI_SLOT_KEYS 已收录(ec06564a),消费方 = aiti-app-center /
30
+ // input 命令提示;aiti-folder 首用(2026-11-15)
31
+ "commands",
31
32
  "userMessageActions", "assistantMessageActions", "assistantMessageFooter",
32
33
  "fileViewer", "pathPicker", "newSessionBackendOptions", "sessionStats",
33
34
  "composerTools", "queuePanel", "recoveryDialog", "workspacePickerActions",
34
35
  "newSessionContextTrailing", "modelSelector", "modelSelectorFooter",
35
36
  "settingsModels", "settingsAgentsFeature", "settingsAgents", "terminalDock",
37
+ // sessionStatsInline (2026-11-21): inline tail inside the session-info stats button;
38
+ // recorded by the host (types.ts + registry.ts UI_SLOT_KEYS); first user = aiti-sysmon top-bar chips
39
+ "sessionStatsInline",
36
40
  "sidebarExplorerDock", "rightFileDock", "sidebarTasks", "composerAffix",
37
41
  "modelInfoLead", "compactLead", "sessionRequestCard", "newSessionSelectors",
38
- "newSessionPreparers", "newSessionWidgets",
42
+ "newSessionPreparers", "newSessionWidgets", "newSessionWorkspacePicker",
39
43
  "noWorkspaceGuide", // v3 新增:fresh 首屏整页引导替换槽(AppShell 消费;aiti-quickstart 首用)
40
44
  // 跨 bundle 生态槽:宿主 ExtSlotName 类型联合未收录(types 缺口,运行时字符串键注册表不受影响),
41
45
  // 消费方 = aiti-model-wizard 的会话信息聚合(getExtUiItems 跨 bundle 读)。见 aiti-provider-usage。
@@ -129,9 +133,3 @@ test("index.ts 静态 ui 声明的插槽键全部合法", () => {
129
133
  }
130
134
  assert.deepEqual(bad, [], "静态 ui 声明使用了未知插槽键");
131
135
  });
132
-
133
- test("镜像脚本排除契约:__pycache__/.pyc 在 sync 排除集内", () => {
134
- const src = readFileSync(join(workRoot, "scripts", "sync-extensions-to-aiti-ai.mjs"), "utf8");
135
- assert.match(src, /EXCLUDE_NAMES = new Set\([^\)]*__pycache__/, "EXCLUDE_NAMES 缺 __pycache__");
136
- assert.match(src, /EXCLUDE_SUFFIX = \[[^\]]*"\.pyc"/, "EXCLUDE_SUFFIX 缺 .pyc");
137
- });
@@ -97,6 +97,27 @@ export function seedBlockCollapsedDefault(blockKey: string, collapsed: boolean):
97
97
  } catch { /* ignore */ }
98
98
  }
99
99
 
100
+ /* ── Dismissed record (user close, 2026-11-21 ruling: "a closed block stays closed
101
+ * across refresh")──
102
+ * User close actions (⋮ Close / TabBar ✕) land in the present state machine's close
103
+ * branch, which writes 1; an explicit open (non-auto present landing in the sidebar
104
+ * family) clears it. Restorative auto-dock call sites ("refresh restores default
105
+ * presence") check this record before presenting, so a closed block is no longer
106
+ * resurrected by a refresh.
107
+ * Readers = per-extension auto-dock call points (aiti-sysmon entry, session-manager
108
+ * Tasks, ...); the sole writer/clearer = the present state machine (aiti-float
109
+ * dock.ts + localPresent below). */
110
+ export const SIDEBAR_DISMISS_PREFIX = "pi:sidebar-dock:dismissed:";
111
+ export function readBlockDismissed(blockKey: string): boolean {
112
+ try { return localStorage.getItem(SIDEBAR_DISMISS_PREFIX + blockKey) === "1"; } catch { return false; }
113
+ }
114
+ export function writeBlockDismissed(blockKey: string, dismissed: boolean): void {
115
+ try {
116
+ if (dismissed) localStorage.setItem(SIDEBAR_DISMISS_PREFIX + blockKey, "1");
117
+ else localStorage.removeItem(SIDEBAR_DISMISS_PREFIX + blockKey);
118
+ } catch { /* ignore */ }
119
+ }
120
+
100
121
  export function readDockOrder(): string[] {
101
122
  try {
102
123
  const raw = JSON.parse(localStorage.getItem(SIDEBAR_ORDER_KEY) ?? "[]");
@@ -210,11 +231,25 @@ export type DockHeaderState = Record<string, unknown>;
210
231
  /** 命令实现表(id → 函数);payload 可用于传递锚点矩形等参数。 */
211
232
  export type DockHeaderCommands = Record<string, ((payload?: unknown) => void) | undefined>;
212
233
 
213
- /** ⋮ 菜单附加项(内容注册,渲染在「工具」组之后的扩展分组)。 */
234
+ /** 图标排注册项(iconsRow 行内按钮;icon 接受 React 元素——与 DockIconRowItem 的 DockIconName 区分)。 */
235
+ export interface MenuIconRowItem {
236
+ key: string;
237
+ icon: unknown;
238
+ label: string;
239
+ run: () => void;
240
+ }
241
+
242
+ /** ⋮ 菜单附加项(内容注册,渲染在「工具」组之后的扩展分组)。
243
+ * iconsRow(2026-11-24):单行「label 居左 + 图标钮排居右」(v5 图标排同款),供同段多动作合并;
244
+ * items 内 icon 接受任意 React 元素(React 端 DockBody 渲染)。 */
214
245
  export type DockMenuItem =
215
246
  | { kind: "item"; id?: string; label: string; icon?: unknown; hint?: string; active?: boolean; alwaysRun?: boolean; disabled?: boolean; run: () => void }
216
247
  | { kind: "sep"; id?: string }
217
- | { kind: "head"; label: string; id?: string };
248
+ | { kind: "head"; label: string; id?: string }
249
+ | { kind: "iconsRow"; id?: string; label?: string; items: MenuIconRowItem[] }
250
+ /** 移动行占位:DockBody 在该位置插入固定「移动」图标行(含 moveRowPin 钉住钮),
251
+ * 并跳过区块段末尾的默认移动行(前移语义);无占位时维持区块段末尾现状。 */
252
+ | { kind: "moveRow"; id?: string };
218
253
 
219
254
  export type DockHeaderRegistration = {
220
255
  actions?: DockHeaderAction[] | null;
@@ -249,7 +284,10 @@ function menuSig(list: DockMenuItem[] | null): string {
249
284
  if (!list) return "";
250
285
  return list.map((m) => m.kind === "item"
251
286
  ? `i:${m.id ?? m.label}:${m.label}:${m.hint ?? ""}:${m.active ? 1 : 0}:${m.alwaysRun ? 1 : 0}:${m.disabled ? 1 : 0}`
252
- : m.kind === "head" ? `h:${m.label}` : "s").join("§");
287
+ : m.kind === "head" ? `h:${m.label}`
288
+ : m.kind === "iconsRow" ? `r:${m.label ?? ""}:${m.items.map((i) => i.key).join(",")}`
289
+ : m.kind === "moveRow" ? "mv-row"
290
+ : "s").join("§");
253
291
  }
254
292
  function stateSig(s: DockHeaderState): string {
255
293
  try { return JSON.stringify(s); } catch { return `keys:${Object.keys(s).length}`; }
@@ -446,13 +484,18 @@ function localPresent(k: string, mode: "open" | "float" | `dock:${string}` | "cl
446
484
  next = (zone ? `docked:${zone}` : "floating") as PresentState;
447
485
  }
448
486
  } else if (mode === "float") next = "floating";
449
- else if (mode === "close") next = "closed";
450
- else if (mode.startsWith("dock:")) {
487
+ else if (mode === "close") {
488
+ next = "closed";
489
+ writeBlockDismissed(k, true); // programmatic closes recorded too — harmless, explicit reopen clears
490
+ } else if (mode.startsWith("dock:")) {
451
491
  const zone = mode.slice(5);
452
492
  // 与 float 状态机 dock.ts 同语义:用户显式停靠即记忆偏好(下次 open 回该位)
453
493
  try { localStorage.setItem(DOCKPREF_KEY(k), zone); } catch { /* ignore */ }
454
494
  next = `docked:${zone}` as PresentState; // 规范态 docked:<zone>(旧实现误存 dock:<zone> → gate 永假,停靠 face 不渲染)
455
495
  }
496
+ // Explicit (non-auto) landing in the sidebar family = user actively bringing the
497
+ // block back → clear the dismissed record (mirrors dock.ts).
498
+ if (!opts?.auto && next !== "closed" && isSidebarDockState(next)) writeBlockDismissed(k, false);
456
499
  if (next === prev) {
457
500
  // 同态 docked 再打开:与 float 状态机同语义——广播 activate 供宿主置前。
458
501
  // auto 透传(与 dock.ts 一致):恢复性入栈的 activate 不得把宿主小屏抽屉拉起。
@@ -616,9 +659,23 @@ if (typeof window !== "undefined") {
616
659
  /* ── 位置菜单(v3 §2-D:DockBody 头行 📍,停靠态一键换位) ──
617
660
  * 数据源 = 调用方传入的 zones/defaultZone(扩展自己知道自己声明了什么;
618
661
  * createDockFaces 自动传)。float 状态机不存 DOM 属性,故不经全局查询。 */
662
+ /** Dock-menu word table (core layer lives in _shared without ctx.t; resolve via the
663
+ * same localStorage pi-locale source as the host useI18n; en default). */
664
+ const DOCK_WORDS: Record<string, { "zh-CN": string; en: string }> = {
665
+ newWindow: { "zh-CN": "新窗口打开", en: "Open in new window" },
666
+ float: { "zh-CN": "浮窗", en: "Float" },
667
+ zoneSidebar: { "zh-CN": "左栏 · 区块", en: "Left · blocks" },
668
+ zoneRight: { "zh-CN": "右栏 · 面板", en: "Right · panels" },
669
+ };
670
+ export function dockWord(key: keyof typeof DOCK_WORDS): string {
671
+ let loc = "en";
672
+ try { loc = window.localStorage.getItem("pi-locale") || "en"; } catch { /* storage unavailable */ }
673
+ const w = DOCK_WORDS[key];
674
+ return (w as any)[loc === "zh-CN" ? "zh-CN" : "en"] ?? w.en;
675
+ }
619
676
  export const DOCK_ZONE_LABELS: Record<string, string> = {
620
- "sidebar-explorer": "左栏 · 区块",
621
- "right-panel": "右栏 · 面板",
677
+ "sidebar-explorer": dockWord("zoneSidebar"),
678
+ "right-panel": dockWord("zoneRight"),
622
679
  };
623
680
 
624
681
  /** ── 图标排模型(v5,方案 docs/pi-web-dock-icon-row-plan.md §3.4)──────────────────
@@ -685,8 +742,8 @@ export function positionMenuItems(k: string, zones: DockZone[], defaultZone: Doc
685
742
  export function positionMenuModel(k: string, zones: DockZone[], defaultZone: DockZone | undefined, cur: PresentState, opts?: { onNewWindow?: (() => void) | null }): PositionMenuItem[] {
686
743
  const newWindow = opts?.onNewWindow ?? dockWindowOpenerOf(k);
687
744
  return [
688
- ...(newWindow ? [{ key: "new-window", icon: "new-window" as const, label: "新窗口打开", run: newWindow }] : []),
689
- { key: "float", icon: "float", label: "浮窗", active: cur === "floating", run: () => undockToFloat(k) },
745
+ ...(newWindow ? [{ key: "new-window", icon: "new-window" as const, label: dockWord("newWindow"), run: newWindow }] : []),
746
+ { key: "float", icon: "float", label: dockWord("float"), active: cur === "floating", run: () => undockToFloat(k) },
690
747
  ...positionMenuItems(k, zones, defaultZone, cur),
691
748
  ];
692
749
  }
@@ -176,6 +176,7 @@ test("降级层:⇱ 菜单 DOM 构建与交互(float 缺席)", async (t) =
176
176
  constructor(type, opts) { this.type = type; if (opts && opts.detail !== undefined) this.detail = opts.detail; }
177
177
  };
178
178
  globalThis.localStorage = dom.window.localStorage;
179
+ globalThis.localStorage.setItem("pi-locale", "zh-CN"); // header/menu word table picks by locale; this block asserts zh labels
179
180
  // 注意:不删全局桩——菜单打开会注册 dismiss setTimeout(0),若测试同步结束后桩被删,
180
181
  // 定时器回调将 ReferenceError 并把整个测试文件标记失败(node --test 文件级失败)。
181
182
  t.after(() => rmSync(dir, { recursive: true, force: true }));