dsh-plugin-update 0.5.8 → 0.7.0

package/dist/panel.d.ts

@@ -1,18 +1,62 @@
 import { type VisibleQueue } from './queue.js';
 import type { BlockedReason, UpdateSnapshot } from './ports.js';
+import { type AppLang, type LocaleOption } from './lang.js';
 /** 摆放形态：默认内嵌，切弹窗走同一参数。 */
 export type UpdatePanelMode = 'embedded' | 'dialog';
-/** 面板主题：默认最小可用样式；`archive` 为档案卷纸面浅色（只换肤，不换 DOM 顺序；`d5-paper` 为旧别名）。 */
+/** 面板主题：默认最小可用样式；`archive` 为档案卷纸面浅色（只换肤，不换 DOM 顺序）。 */
 /**
  * 面板主题：`default` 最小可用深色；`archive` 档案卷纸面浅色（原型敲定的案卷风格，只换肤）。
- * `d5-paper` 是 archive 的旧别名（历史取值），仍可用，渲染逐字相同。
  */
-export type UpdatePanelTheme = 'default' | 'archive' | 'd5-paper';
+export type UpdatePanelTheme = 'default' | 'archive';
 /**
- * 主题归一：archive 为首选名，旧别名 d5-paper 仍收并归到 archive（DOM 属性只出 archive）；
+ * 主题归一：`archive` 挂 `data-theme="archive"`，其余一律回 `default`（DOM 属性只出 `archive`）；
  * 其余一律回 default（纯渲染函数永不抛；挂载/setTheme 的非法值另行抛错）。
  */
 export declare function normalizePanelTheme(value: unknown): 'default' | 'archive';
+/** 第三方主题变量覆盖：键为语义名；颜色收 hex（#rgb/#rrggbb/#rrggbbaa）或英文名单词；其余收安全 CSS 值；缺省即主题默认值，零回归。 */
+export interface UpdateThemeTokens {
+    text?: string;
+    textMuted?: string;
+    bg?: string;
+    bgSoft?: string;
+    border?: string;
+    borderStrong?: string;
+    buttonBg?: string;
+    primary?: string;
+    primaryDeep?: string;
+    focus?: string;
+    okBg?: string;
+    okBorder?: string;
+    okText?: string;
+    warnBg?: string;
+    warnBorder?: string;
+    warnText?: string;
+    badBg?: string;
+    badBorder?: string;
+    badText?: string;
+    busyBg?: string;
+    busyBorder?: string;
+    busyText?: string;
+    fontSans?: string;
+    fontSerif?: string;
+    fontMono?: string;
+    shadow?: string;
+    radiusPanel?: string;
+    radiusButton?: string;
+    radiusBadge?: string;
+    entryFontSize?: string;
+    entryPadding?: string;
+    entryBorderRadius?: string;
+    /** 入口件整体缩放（对应 CSS `zoom`），须为大于 0 的有限数。 */
+    entryScale?: number;
+}
+/** CSS 值最小安全检查（与入口件 sizing 同口径）：放 style 属性前先拦掉注入。 */
+export declare function isSafeThemeCssValue(value: string): boolean;
+/**
+ * `themeTokens` → 根 style 属性体（纯函数：同一输入永远算出同一串；空/缺省回空串，即不写 style）。
+ * 非法即抛（未知键、空串、注入字符、颜色形状不对、非正有限 entryScale 都不收）。
+ */
+export declare function themeTokensStyleFor(tokens: UpdateThemeTokens | null | undefined): string;
 /** 与宿主通话的传输函数：面板只认这个签名，不认任何宿主对象的具体形状。 */
 export type UpdatePanelCall = (phoneName: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 复制文本的出口：不传即尝试浏览器剪贴板，都没有则只留“已生成、请手动复制”提示。 */
@@ -26,8 +70,10 @@ export interface UpdatePanelOptions {
     prefix?: string;
     /** 摆放形态：默认内嵌。 */
     mode?: UpdatePanelMode;
-    /** 面板主题：默认 `default`（最小可用样式，一字不动）；传 `archive` 切档案卷（`d5-paper` 为旧别名）。 */
+    /** 面板主题：默认 `default`（最小可用样式，一字不动）；传 `archive` 切档案卷。 */
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 UpdateThemeTokens；两个主题通用，不传即零回归。 */
+    themeTokens?: UpdateThemeTokens;
     /** 是否看他人排队明细：默认只看自己的（他人仅露正忙占位，位置照给）。 */
     showOthers?: boolean;
     /** 是否显示深挖日志指引：默认显示；面向纯终端用户的嵌入可关（失败证据行不受影响）。 */
@@ -69,10 +115,10 @@ export interface UpdatePanelOptions {
      */
     onCloseRequested?: () => void | Promise<void>;
     /**
-     * 语言覆盖（#60 窗口期占位：本票只加选项不消费，传了暂不生效，消费留给 #61-#66）。
-     * 形态与入口件一致：'zh' | 'en' | { getActive(): string; subscribe?(cb): () => void }。
+     * 语言覆盖（#61 起消费：'zh' | 'en' | { getActive(): string; subscribe?(cb): () => void }，不传即跟随全局信号）。
+     * 与入口件同一口径：显式覆盖 > html[lang] > navigator > zh。
      */
-    locale?: unknown;
+    locale?: LocaleOption;
 }
 /** 挂载点：只要有 innerHTML 的容器即可（浏览器元素或测试替身都行）。 */
 export interface UpdatePanelContainer {
@@ -89,6 +135,8 @@ export interface UpdatePanelController {
     setMode(mode: UpdatePanelMode): Promise<void>;
     /** 切换主题（同一内核重绘，只换肤；默认主题输出与旧版一字不差）。 */
     setTheme(theme: UpdatePanelTheme): Promise<void>;
+    /** 换一套主题变量（同一内核重绘，只换变量；传 undefined 即清掉覆盖，回主题默认）。 */
+    setThemeTokens(tokens: UpdateThemeTokens | undefined): Promise<void>;
     /** 切换排队可见性（重查一次，位置口径不变）。 */
     setShowOthers(show: boolean): Promise<void>;
     /** 收起/展开更新日志（纯视图态，不调电话；轮询与换肤不丢）。 */
@@ -112,8 +160,8 @@ export interface BlockedCopy {
     title: string;
     action: string;
 }
-/** 装不了的原因 → 中文一句话（能装传 null 即回 null，不猜）。 */
-export declare function blockedCopy(reason: BlockedReason | null): BlockedCopy | null;
+/** 装不了的原因 → 单语一句话（能装传 null 即回 null，不猜；lang 缺省 zh，零回归）。 */
+export declare function blockedCopy(reason: BlockedReason | null, lang?: AppLang | string | null): BlockedCopy | null;
 export interface FailureCopy {
     zh: string;
     act: string;
@@ -121,10 +169,10 @@ export interface FailureCopy {
 /** 14 码全表是否包含该码（8 阻塞 + 5 电话 + internal；未来码不在此列，走兜底）。 */
 export declare function isKnownFailureCode(code: unknown): boolean;
 /**
- * 稳定码 → 中文一句话（14 码全覆盖；未知码回未来兜底，空码回 null）。
- * 8 阻塞行复用 BLOCKED_COPY 原文，不另起措辞；面板分支只认返回值，不碰 diag。
+ * 稳定码 → 单语一句话（14 码全覆盖；未知码回未来兜底，空码回 null；lang 缺省 zh，零回归）。
+ * 8 阻塞行复用 blocked 行原文，不另起措辞；面板分支只认返回值，不碰 diag。
  */
-export declare function failureCopy(code: unknown): FailureCopy | null;
+export declare function failureCopy(code: unknown, lang?: AppLang | string | null): FailureCopy | null;
 /**
  * 失败回包取稳定码：只认 errorKind，error 仅作回退（#22 验收：errorKind=internal 时
  * 不许误判为查新版失败；包内已把未知码收敛为 error=check-failed/errorKind=internal，
@@ -158,9 +206,11 @@ export interface PanelDiagnosticInput {
     /** 显式来源（diag 没有时用；有 diag 时显式优先，缺省仍说人话，不留白）。 */
     route?: string | null;
     checkId?: string | null;
+    /** 渲染语言（#63 单语：缺省 zh 零回归；挂载态传 currentLang，纯函数直调可显式传 en/zh）。 */
+    lang?: AppLang | string | null;
 }
-/** 组出一段自包含诊断（调用方直接拿去粘工单/issue；粘之前已脱敏，不必手检）。 */
-export declare function buildDiagnosticText(input: PanelDiagnosticInput): string;
+/** 组出一段自包含诊断（调用方直接拿去粘工单/issue；粘之前已脱敏，不必手检；#63 入字典单语，lang 缺省 zh 零回归）。 */
+export declare function buildDiagnosticText(input: PanelDiagnosticInput, langOverride?: AppLang | string | null): string;
 export type DiagCopyFormat = 'block' | 'line';
 export interface TolerantDiag {
     stage: string | null;
@@ -192,8 +242,11 @@ export interface UpdateDiagCopyInput extends PanelDiagnosticInput {
  * 第一性：顺序码→摘要→来源（#18 定），怎么办是面板页脚放最后，不插断三元组；
  * 缺省即省略（#18）：路由/请求/检查/阶段等缺失即不出现，不占位“未知”；
  * 插件/版本/宿主/使用范围/队列恒显（面板侧显式值兜底），摘要缺省给人话，源缺省给人话（省略本身即信息，人读不懂所以必须说）。
+ * #63 入字典单语（§3.4 22 项，队列 3 复用旧块）：标签跟随语言，变量与自由文本、两种复制形态与字段顺序冻结不动；
+ * 机读 tag [update-diag]/code=/·/— 冻结在代码里不进字典（非人类语言），人类标签（摘要/来源/怎么办/插件=…）走字典；
+ * lang 缺省 zh 零回归，detail/变量/占位符不译（v2 非目标，英文界面出现中文正文属正常）。
  */
-export declare function buildUpdateDiagCopy(input: UpdateDiagCopyInput): string;
+export declare function buildUpdateDiagCopy(input: UpdateDiagCopyInput, langOverride?: AppLang | string | null): string;
 export declare function createMemorySkipStore(now?: () => number): PanelSkipStore;
 /** 浏览器跳过存储（localStorage 形状即可；没有或写坏退内存，绝不因跳过挡住更新）。 */
 export declare function createBrowserSkipStore(pluginId: string, storage?: unknown, now?: () => number): PanelSkipStore;
@@ -210,7 +263,7 @@ export interface PanelView {
     showManual: boolean;
     showReset: boolean;
     queueNote: string | null;
-    /** 大印章（状态词）与小印章（一字）：取值与原型 `d5-paper.html:431-432` 的状态映射一一对应。 */
+    /** 大印章（状态词）与小印章（一字）：取值与原型 `archive.html:431-432` 的状态映射一一对应。 */
     seal: PanelSeal;
 }
 /** 印章色调：与原型 `seal-ink / seal-green / seal-yellow / seal-red` 四个类同名同义。 */
@@ -222,6 +275,8 @@ export interface PanelSeal {
     mini: string;
     tone: PanelSealTone;
 }
+/** 状态 → 单语印章（lang 缺省 zh，零回归；tone 与原型同名同义，不入字典）。 */
+export declare function panelSealFor(kind: PanelBanner['kind'], lang?: AppLang | string | null): PanelSeal;
 export interface PanelViewInput {
     snapshot: UpdateSnapshot | null;
     manual: string | null;
@@ -236,16 +291,20 @@ export interface PanelViewInput {
      */
     changelogMarkdown?: string | null;
 }
-export declare function panelViewModel(input: PanelViewInput): PanelView;
+export declare function panelViewModel(input: PanelViewInput, lang?: AppLang | string | null): PanelView;
 export declare const UPDATE_PANEL_CSS: string;
-export declare const UPDATE_PANEL_D5_CSS: string;
+export declare const UPDATE_PANEL_ARCHIVE_CSS: string;
 export interface PanelRenderInput extends PanelViewInput {
     mode: UpdatePanelMode;
     showOthers: boolean;
     pluginId: string;
     copyNotice: string | null;
-    /** 可选主题：不传即默认（输出与旧版一字不差）；`archive` 切档案卷（旧别名 `d5-paper` 仍收）。 */
+    /** 渲染语言（#61 单语：缺省 zh；挂载态传 currentLang，纯函数直调可显式传 en/zh）。 */
+    lang?: AppLang | string | null;
+    /** 可选主题：不传即默认（输出与旧版一字不差）；`archive` 切档案卷。 */
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 UpdateThemeTokens；写到面板根上，不传即无 style 属性。 */
+    themeTokens?: UpdateThemeTokens;
     /** 使用范围名（profile）：面板「使用范围」一栏的唯一来源，缺省显示“未知”，不猜。 */
     profileName?: string | null;
     /** 宿主种类：进诊断文本；缺省显示“未知”。 */
@@ -279,12 +338,12 @@ export interface PanelFailureRef {
     source: 'check' | 'install' | null;
     volatile: boolean;
 }
-/** 锁存时刻 → 本地 HH:MM:SS（失败档案“失败于”用；非法值回 null，不画时间）。 */
-export declare function formatLatchTime(atMs: unknown): string | null;
-/** 内核 HTML（双形态行为等价的根：同一视图产出同一内核，只换外层）。 */
-export declare function renderUpdatePanelKernel(input: PanelRenderInput, view: PanelView): string;
+/** 锁存时刻 → 本地 HH:MM:SS（失败档案“失败于”用；非法值回 null，不画时间；#62 跟随宿主 locale）。 */
+export declare function formatLatchTime(atMs: unknown, lang?: AppLang | string | null): string | null;
+/** 内核 HTML（双形态行为等价的根：同一视图产出同一内核，只换外层；#62 按 lang 单语，缺省 zh 零回归）。 */
+export declare function renderUpdatePanelKernel(input: PanelRenderInput, view: PanelView, lang?: AppLang | string | null): string;
 /** 整面板 HTML（含样式；重绘即整体替换 innerHTML，故每次都带 style 也只留一份）。 */
-export declare function renderUpdatePanelHTML(input: PanelRenderInput): string;
+export declare function renderUpdatePanelHTML(input: PanelRenderInput, lang?: AppLang | string | null): string;
 /**
  * mount 自动查抑制谓词（#48：#46 结论固化，纯函数）：
  * 仅当快照任务态为 installing/verifying，或已有查/装在途动作时不发起；