dsh-plugin-update 0.5.3 → 0.5.5

package/dist/entry.js

@@ -5,6 +5,7 @@ import {
   mountUpdatePanel,
   normalizePanelTheme
 } from "./panel.js";
+import { BILINGUAL_CSS, bilingualHTML, bilingualText } from "./bilingual.js";
 const LABEL_IDLE = "\u68C0\u67E5\u66F4\u65B0";
 const LABEL_FAILED = "\u66F4\u65B0\u5931\u8D25\uFF0C\u70B9\u6B64\u67E5\u770B";
 const LABEL_BUSY = "\u6B63\u5728\u5B89\u88C5\u2026";
@@ -28,6 +29,36 @@ function entryStateKind(state) {
   if (hasUpdateOf(snapshot)) return "update";
   return "idle";
 }
+function entryBilingualKeyFor(state) {
+  switch (entryStateKind(state)) {
+    case "busy":
+      return "entry.label.busy";
+    case "restart":
+      return "entry.label.restart";
+    case "failed":
+      return "entry.label.failed";
+    case "update": {
+      const latest = state?.snapshot?.latestVersion;
+      return typeof latest === "string" && latest.trim() ? "entry.label.has-update" : "entry.label.idle";
+    }
+    default:
+      return "entry.label.idle";
+  }
+}
+function entryBilingualValuesFor(state) {
+  const key = entryBilingualKeyFor(state);
+  if (key === "entry.label.has-update") {
+    const v = state?.snapshot?.latestVersion;
+    return { version: typeof v === "string" ? v.trim() : "" };
+  }
+  return {};
+}
+function entryBilingualHTMLFor(state) {
+  return bilingualHTML(entryBilingualKeyFor(state), entryBilingualValuesFor(state));
+}
+function entryBilingualTextFor(state) {
+  return bilingualText(entryBilingualKeyFor(state), entryBilingualValuesFor(state));
+}
 function entryLabelFor(state) {
   switch (entryStateKind(state)) {
     case "busy":
@@ -66,13 +97,13 @@ const UPDATE_ENTRY_CSS = [
   '.dsh-upd-entry[data-state="failed"] .dsh-upd-entry-dot{background:var(--dsh-upd-bad-line,#dc2626)}',
   // 小字自带底（深色宿主 + 浅色变量时也读得出；浅底宿主上只是多一圈细线，不抢戏）。
   ".dsh-upd-entry-note{font-size:12.5px;opacity:.9;background:var(--dsh-upd-bg,#ffffff);border:1px solid var(--dsh-upd-line,#e5e7eb);border-radius:4px;padding:1px 8px}",
-  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-note{background:var(--d5-card);border-color:var(--d5-line-strong);color:var(--d5-ink)}',
-  '.dsh-upd-entry[data-theme="d5-paper"]{--d5-ink:#1a1a1a;--d5-muted:#6f675a;--d5-line-strong:#c4b896;--d5-accent:#c8402a;--d5-card:#fffdf6;',
+  '.dsh-upd-entry[data-theme="archive"] .dsh-upd-entry-note{background:var(--d5-card);border-color:var(--d5-line-strong);color:var(--d5-ink)}',
+  '.dsh-upd-entry[data-theme="archive"]{--d5-ink:#1a1a1a;--d5-muted:#6f675a;--d5-line-strong:#c4b896;--d5-accent:#c8402a;--d5-card:#fffdf6;',
   'font-family:Georgia,"Songti SC","STSong","SimSun",serif;color:var(--d5-ink)}',
   // 按钮脸自己不透明（深色宿主 + 浅色系统变量时也读得出；hover 红在深浅底上都可见）。
-  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn{border-color:var(--d5-line-strong);background:var(--d5-card);color:var(--d5-ink);border-radius:3px}',
-  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn:hover{border-color:var(--d5-accent);color:var(--d5-accent)}',
-  '@media (prefers-color-scheme: dark){.dsh-upd-entry[data-theme="d5-paper"]{--d5-ink:#ece5d3;--d5-muted:#a89c83;--d5-line-strong:#5c4e3b;--d5-accent:#e0684e;--d5-card:#1e1a15}}',
+  '.dsh-upd-entry[data-theme="archive"] .dsh-upd-entry-btn{border-color:var(--d5-line-strong);background:var(--d5-card);color:var(--d5-ink);border-radius:3px}',
+  '.dsh-upd-entry[data-theme="archive"] .dsh-upd-entry-btn:hover{border-color:var(--d5-accent);color:var(--d5-accent)}',
+  '@media (prefers-color-scheme: dark){.dsh-upd-entry[data-theme="archive"]{--d5-ink:#ece5d3;--d5-muted:#a89c83;--d5-line-strong:#5c4e3b;--d5-accent:#e0684e;--d5-card:#1e1a15}}',
   "@media (prefers-color-scheme: dark){.dsh-upd-entry{color:#e5e7eb}",
   ".dsh-upd-entry-btn{--dsh-upd-btn:#1f2937;--dsh-upd-line:#374151}}"
 ].join("\n");
@@ -133,7 +164,7 @@ function mountUpdateEntry(container, options) {
   const call = options.call;
   let snapshot = null;
   let error = null;
-  let note = null;
+  let noteVersion = null;
   let activating = false;
   let mounted = true;
   let panel = null;
@@ -170,12 +201,14 @@ function mountUpdateEntry(container, options) {
   }
   function entryHTML() {
     const kind = entryStateKind(stateOf());
-    const text = activating ? "\u6B63\u5728\u67E5\u65B0\u7248\u2026" : currentLabel();
+    const labelHTML = labelOverride ? escapeHtml(labelOverride) : activating ? bilingualHTML("entry.action.checking") : entryBilingualHTMLFor(stateOf());
+    const labelText = labelOverride ?? (activating ? bilingualText("entry.action.checking") : entryBilingualTextFor(stateOf()));
     const busyAttr = activating ? ' disabled aria-busy="true"' : "";
-    const themeAttr = theme === "d5-paper" ? ' data-theme="d5-paper"' : "";
-    const control = variant === "badge" ? `<button type="button" class="dsh-upd-entry-dot" ${ENTRY_ATTR}="activate" title="${escapeHtml(text)}" aria-label="${escapeHtml(text)}"${busyAttr}></button>` : `<button type="button" class="dsh-upd-entry-btn" ${ENTRY_ATTR}="activate"${busyAttr}>${escapeHtml(text)}</button>`;
-    const noteHTML = note ? `<span class="dsh-upd-entry-note" data-dsh-upd-note="1">${escapeHtml(note)}</span>` : "";
-    return `<style>${UPDATE_ENTRY_CSS}</style>
+    const themeAttr = theme === "archive" ? ' data-theme="archive"' : "";
+    const control = variant === "badge" ? `<button type="button" class="dsh-upd-entry-dot" ${ENTRY_ATTR}="activate" title="${escapeHtml(labelText)}" aria-label="${escapeHtml(labelText)}"${busyAttr}></button>` : `<button type="button" class="dsh-upd-entry-btn" ${ENTRY_ATTR}="activate"${busyAttr}>${labelHTML}</button>`;
+    const noteHTML = noteVersion ? `<span class="dsh-upd-entry-note" data-dsh-upd-note="1">${bilingualHTML("entry.note.up-to-date", { version: noteVersion })}</span>` : "";
+    return `<style>${UPDATE_ENTRY_CSS}
+${BILINGUAL_CSS}</style>
 <span class="dsh-upd-entry" data-variant="${variant}" data-state="${kind}"${themeAttr}>${control}${noteHTML}</span>`;
   }
   function render() {
@@ -258,7 +291,7 @@ function mountUpdateEntry(container, options) {
       return;
     }
     activating = true;
-    note = null;
+    noteVersion = null;
     render();
     try {
       await checkNow();
@@ -276,7 +309,7 @@ function mountUpdateEntry(container, options) {
       openDialog();
       return;
     }
-    note = `\u5DF2\u662F\u6700\u65B0 ${snapshot.runningVersion}`;
+    noteVersion = snapshot.runningVersion;
     render();
   }
   function setTheme(next) {
@@ -342,6 +375,10 @@ function mountUpdateEntry(container, options) {
 }
 export {
   UPDATE_ENTRY_CSS,
+  entryBilingualHTMLFor,
+  entryBilingualKeyFor,
+  entryBilingualTextFor,
+  entryBilingualValuesFor,
   entryLabelFor,
   entryStateKind,
   mountUpdateEntry

package/dist/host.js

@@ -13,6 +13,7 @@ import { manualCommand } from "./commands.js";
 import { fetchReleaseChangelogText } from "./changelog-io.js";
 import { shouldFetchChangelog } from "./changelog.js";
 import { buildDiag } from "./diag.js";
+import { LOG_EVENT_CALL, LOG_EVENT_CALL_FAIL } from "./log-events.js";
 import { fetchNpmVersionRelease, isVersionAllowedInChannel, updateError, validReleaseVersion, validRequestId } from "./service.js";
 import { createUpdateDiskPorts, createUpdateExecutor, createUpdateQueuePorts } from "./store.js";
 import { createUpdateReader, defaultHomeDir, resolveProfileName, resolveTargetPackage } from "./reader.js";
@@ -496,7 +497,7 @@ function loggedPhone(method, kind, pluginId, fn, diagCtx) {
     try {
       const out = await fn(safeArgs);
       const snapshot = out && out.snapshot ? out.snapshot : out;
-      emit("info", "host.call", { method, latencyMs: Date.now() - t0, ok: true, kind, pluginId });
+      emit("info", LOG_EVENT_CALL, { method, latencyMs: Date.now() - t0, ok: true, kind, pluginId });
       return {
         ok: true,
         snapshot,
@@ -509,7 +510,7 @@ function loggedPhone(method, kind, pluginId, fn, diagCtx) {
       };
     } catch (error) {
       const payload = toUpdateErrorPayload(error);
-      emit("warn", "host.call.fail", { method, kind, errorHash: hash8(String(error?.message || payload.error)), pluginId });
+      emit("warn", LOG_EVENT_CALL_FAIL, { method, kind, errorHash: hash8(String(error?.message || payload.error)), pluginId });
       let diag;
       try {
         const cfg = diagCtx?.config;
@@ -581,11 +582,11 @@ function loggedChangelogPhone(method, pluginId, fn, diagCtx) {
     const safeArgs = args && typeof args === "object" ? args : {};
     try {
       const out = await fn(safeArgs);
-      emit("info", "host.call", { method, latencyMs: Date.now() - t0, ok: true, kind: "update-changelog", pluginId });
+      emit("info", LOG_EVENT_CALL, { method, latencyMs: Date.now() - t0, ok: true, kind: "update-changelog", pluginId });
       return { ok: true, version: out.version, markdown: out.markdown };
     } catch (error) {
       const payload = toUpdateErrorPayload(error);
-      emit("warn", "host.call.fail", { method, kind: "update-changelog", errorHash: hash8(String(error?.message || payload.error)), pluginId });
+      emit("warn", LOG_EVENT_CALL_FAIL, { method, kind: "update-changelog", errorHash: hash8(String(error?.message || payload.error)), pluginId });
       let diag;
       try {
         const cfg = diagCtx?.config;

package/dist/log-events.d.ts

@@ -0,0 +1,10 @@
+/**
+ * src/log-events.ts —— 日志事件名（单源）。
+ *
+ * 宿主发射（host/store）、面板路牌（panel）、测试断言都从这里取：
+ * 改名即全改，不存在“发射侧改了、路牌还是旧名”的静默分叉。
+ * 本文件零导入，宿主/面板同缝（与 redaction 同口径）。
+ */
+export declare const LOG_EVENT_CALL = "host.call";
+export declare const LOG_EVENT_CALL_FAIL = "host.call.fail";
+export declare const LOG_EVENT_INSTALL_EXEC = "update.install.exec";

package/dist/log-events.js

@@ -0,0 +1,9 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/log-events.ts
+const LOG_EVENT_CALL = "host.call";
+const LOG_EVENT_CALL_FAIL = "host.call.fail";
+const LOG_EVENT_INSTALL_EXEC = "update.install.exec";
+export {
+  LOG_EVENT_CALL,
+  LOG_EVENT_CALL_FAIL,
+  LOG_EVENT_INSTALL_EXEC
+};

package/dist/panel-batch.d.ts

@@ -49,6 +49,11 @@ export interface BatchPanelOptions {
      * 老宿主没给行电话名即回中性提示；false 关闭。
      */
     autoChangelog?: boolean;
+    /**
+     * 弹窗关闭的落地（与单插件面板同一口径）：只在 dialog 下点「关闭」/按 Esc 时调用；调用方在此撤掉弹窗 DOM。
+     * 不传则回退为只停轮询（unmount），DOM 留给调用方处理。入口件打开的 dialog 已内置（收 dialog + 还原按钮）。
+     */
+    onCloseRequested?: () => void | Promise<void>;
 }
 /** 面板可点的动作（HTML 上 data-act 一一对应；测试走同一条路）。 */
 export type BatchPanelActionKind = 'check' | 'install' | 'resume' | 'cancel' | 'row-install' | 'row-skip' | 'row-resume-skip' | 'row-cancel-queue' | 'row-copy-manual' | 'row-copy-diag' | 'toggle-details' | 'restart' | 'close';

package/dist/panel-batch.js

@@ -131,7 +131,7 @@ function renderBatchPanelHTML(input) {
   parts.push('<div class="dsh-upd-batch-macros">');
   parts.push('<button type="button" data-act="check"' + disabled + ' title="\u91CD\u65B0\u8BFB\u53D6\u6279\u91CF\u72B6\u6001\uFF08\u53EA\u8BFB\uFF09">\u68C0\u67E5\u66F4\u65B0</button>');
   parts.push('<button type="button" data-act="install" data-primary="1"' + disabled + ' title="\u628A\u6709\u65B0\u7248\u7684\u51E0\u5BB6\u4E00\u6B21\u63D0\u4EA4\uFF1B\u540C\u4E00\u4F1A\u8BDD\u540C\u4E00\u5E42\u7B49\u7F16\u53F7">\u5168\u90E8\u66F4\u65B0</button>');
-  if (mode === "dialog") parts.push('<button type="button" data-act="close" title="\u5173\u95ED\u9762\u677F\uFF08\u6279\u91CF\u63A8\u8FDB\u5728\u5BBF\u4E3B\u4FA7\u7EE7\u7EED\u8DD1\uFF09">\u5173\u95ED</button>');
+  if (mode === "dialog") parts.push('<button type="button" data-act="close" title="\u5173\u95ED\u7A97\u53E3\uFF0C\u6279\u91CF\u66F4\u65B0\u4E0D\u53D7\u5F71\u54CD">\u5173\u95ED</button>');
   parts.push("</div>");
   parts.push("</div>");
   const summary = loaded ? batchSummaryText(counts, rows, total, installing, lastError !== null) : "\u6B63\u5728\u8BFB\u53D6\u6279\u91CF\u66F4\u65B0\u72B6\u6001\u2026";
@@ -169,8 +169,8 @@ function renderBatchPanelHTML(input) {
     parts.push('<div class="dsh-upd-batch-notice" role="status">' + escapeHtml(notice) + "</div>");
   }
   const kernel = parts.join(String.fromCharCode(10));
-  const d5 = normalizePanelTheme(theme) === "d5-paper";
-  const attr = d5 ? ' data-theme="d5-paper"' : "";
+  const d5 = normalizePanelTheme(theme) === "archive";
+  const attr = d5 ? ' data-theme="archive"' : "";
   const seal = batchSealOf(counts);
   const root = '<div class="dsh-upd dsh-upd-batch" data-mode="' + mode + '" data-seal="' + escapeHtml(seal.text) + '" data-seal-tone="' + seal.tone + '"' + attr + ">\n" + kernel + "\n</div>";
   const body = mode === "dialog" ? '<div class="dsh-upd-overlay" data-mode="dialog">' + root + "</div>" : root;
@@ -388,16 +388,16 @@ const UPDATE_BATCH_PANEL_CSS = [
 ].join(String.fromCharCode(10));
 const UPDATE_BATCH_PANEL_D5_CSS = [
   "/* \u6279\u91CF\u9762\u677F\u7684 D5 \u76AE\u80A4\uFF1A\u53EA\u6362\u989C\u8272/\u5B57\u4F53/\u95F4\u8DDD\uFF1B\u6839\u4E0A\u7684\u5927\u5370\u7AE0\u7531 UPDATE_PANEL_D5_CSS \u8D1F\u8D23\u3002 */",
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-batch-head{padding-right:120px}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-batch-title{font-family:var(--d5-serif);font-size:21px;letter-spacing:.04em}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-batch-title i{color:var(--d5-accent)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-brow-main{background:transparent;border:0;color:var(--d5-ink)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-brow-main:hover{color:var(--d5-accent)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-bname{font-family:var(--d5-serif)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-bver{font-family:var(--d5-mono);color:var(--d5-muted)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-batch-ledger{color:var(--d5-muted)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-batch-sum{color:var(--d5-ink)}',
-  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-brow-set{border-top-color:var(--d5-line)}'
+  '.dsh-upd[data-theme="archive"] .dsh-upd-batch-head{padding-right:120px}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-batch-title{font-family:var(--d5-serif);font-size:21px;letter-spacing:.04em}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-batch-title i{color:var(--d5-accent)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-brow-main{background:transparent;border:0;color:var(--d5-ink)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-brow-main:hover{color:var(--d5-accent)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-bname{font-family:var(--d5-serif)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-bver{font-family:var(--d5-mono);color:var(--d5-muted)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-batch-ledger{color:var(--d5-muted)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-batch-sum{color:var(--d5-ink)}',
+  '.dsh-upd[data-theme="archive"] .dsh-upd-brow-set{border-top-color:var(--d5-line)}'
 ].join(String.fromCharCode(10));
 function escapeHtml(text) {
   return String(text).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -627,6 +627,7 @@ function mountUpdateBatchPanel(container, options) {
   const call = options.call;
   const titles = options.titles && typeof options.titles === "object" ? options.titles : {};
   const onRestartRequested = options.onRestartRequested;
+  const onCloseRequested = typeof options.onCloseRequested === "function" ? options.onCloseRequested : null;
   const copyText = options.copyText ?? defaultCopyText;
   const skipStores = /* @__PURE__ */ new Map();
   const autoChangelogEnabled = options.autoChangelog !== false;
@@ -968,26 +969,36 @@ function mountUpdateBatchPanel(container, options) {
         return;
       }
       case "close": {
-        if (mode === "dialog") unmount();
+        await requestDialogClose();
         return;
       }
       default:
         return;
     }
   }
+  async function requestDialogClose() {
+    if (!mounted || mode !== "dialog") return;
+    if (onCloseRequested) {
+      try {
+        await onCloseRequested();
+      } catch {
+      }
+    }
+    unmount();
+  }
   function onKeyDown(ev) {
     try {
       const e = ev;
       if (!mounted || mode !== "dialog" || !e || e.key !== "Escape") return;
-      unmount();
+      void requestDialogClose();
     } catch {
     }
   }
   function setTheme(next) {
-    if (next !== "default" && next !== "d5-paper") {
-      throw new Error("[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 d5-paper\uFF08\u6536\u5230 " + JSON.stringify(next) + "\uFF09");
+    if (next !== "default" && next !== "archive" && next !== "d5-paper") {
+      throw new Error("[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 archive\uFF08d5-paper \u4E3A\u65E7\u522B\u540D\u4ECD\u53EF\u7528\uFF09\uFF08\u6536\u5230 " + JSON.stringify(next) + "\uFF09");
     }
-    theme = next;
+    theme = normalizePanelTheme(next);
     render();
   }
   function setMode(next) {

package/dist/panel.d.ts

@@ -9,16 +9,16 @@ export type UpdatePanelMode = 'embedded' | 'dialog';
  */
 export type UpdatePanelTheme = 'default' | 'archive' | 'd5-paper';
 /**
- * 主题归一：archive 与旧别名 d5-paper 走同一套渲染（DOM 属性仍为 d5-paper，既有覆盖样式不断）；
+ * 主题归一：archive 为首选名，旧别名 d5-paper 仍收并归到 archive（DOM 属性只出 archive）；
  * 其余一律回 default（纯渲染函数永不抛；挂载/setTheme 的非法值另行抛错）。
  */
-export declare function normalizePanelTheme(value: unknown): 'default' | 'd5-paper';
+export declare function normalizePanelTheme(value: unknown): 'default' | 'archive';
 /** 与宿主通话的传输函数：面板只认这个签名，不认任何宿主对象的具体形状。 */
 export type UpdatePanelCall = (phoneName: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 复制文本的出口：不传即尝试浏览器剪贴板，都没有则只留“已生成、请手动复制”提示。 */
 export type UpdatePanelCopyText = (text: string) => void | Promise<void>;
 /** 面板可点的动作（与 HTML 里 data-action 一一对应，测试走同一条路）。 */
-export type UpdatePanelActionKind = 'check' | 'install' | 'skip' | 'reset-skip' | 'copy-manual' | 'copy-diag' | 'toggle-queue' | 'restart-hint' | 'close-view';
+export type UpdatePanelActionKind = 'check' | 'install' | 'skip' | 'reset-skip' | 'copy-manual' | 'copy-diag' | 'toggle-queue' | 'restart-hint' | 'close-view' | 'dismiss-failure';
 export interface UpdatePanelOptions {
     /** 插件标识：必填，与宿主侧 createHostUpdate 传的 pluginId 一致。 */
     pluginId: string;
@@ -30,6 +30,8 @@ export interface UpdatePanelOptions {
     theme?: UpdatePanelTheme;
     /** 是否看他人排队明细：默认只看自己的（他人仅露正忙占位，位置照给）。 */
     showOthers?: boolean;
+    /** 是否显示深挖日志指引：默认显示；面向纯终端用户的嵌入可关（失败证据行不受影响）。 */
+    showLogHint?: boolean;
     /** 轮询间隔毫秒：默认 1000，不得小于 250。 */
     pollMs?: number;
     /** 与宿主通话的函数（面板侧唯一的宿主接触面）。 */
@@ -235,7 +237,7 @@ export interface PanelRenderInput extends PanelViewInput {
     showOthers: boolean;
     pluginId: string;
     copyNotice: string | null;
-    /** 可选主题：不传即默认（输出与旧版一字不差）；`d5-paper` 切 D5 档案卷。 */
+    /** 可选主题：不传即默认（输出与旧版一字不差）；`archive` 切档案卷（旧别名 `d5-paper` 仍收）。 */
     theme?: UpdatePanelTheme;
     /** 使用范围名（profile）：面板「使用范围」一栏的唯一来源，缺省显示“未知”，不猜。 */
     profileName?: string | null;
@@ -246,6 +248,10 @@ export interface PanelRenderInput extends PanelViewInput {
      * 缺省即静默（输出与旧版一字不差）；只在挂载器置忙的那次 render 里传。
      */
     busyAct?: 'check' | 'install' | null;
+    /** 失败引用（失败档案的查询键；缺省即无失败，不画卷宗）。 */
+    failure?: PanelFailureRef | null;
+    /** 日志指引开关：false 即藏通用日志行（失败证据行不受影响）。 */
+    showLogHint?: boolean;
     /**
      * 动作面归谁：`default`（缺省）由内核画动作按钮；`none` 只画内容、不画按钮。
      * 给「调用方自己提供动作面」的场景（如批量面板的详情：动作由批量面板经自己的通道提供）。
@@ -253,6 +259,16 @@ export interface PanelRenderInput extends PanelViewInput {
      */
     actions?: 'default' | 'none';
 }
+/** 内核渲染用的失败引用（只读快照：证据仍在锁存里，这里只传展示键）。 */
+export interface PanelFailureRef {
+    requestId: string | null;
+    checkId: string | null;
+    atMs: number | null;
+    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;
 /** 整面板 HTML（含样式；重绘即整体替换 innerHTML，故每次都带 style 也只留一份）。 */