dsh-plugin-update 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [0.4.0] - 2026-10-05
+
+### Added
+- 更新日志无脑接入（#38）：宿主新增 `updateChangelog` 电话（入参版本号，回该版 tarball 内全文，取不到回空；同源 + 精确路径 + `integrity` + 三墙复用，按版本记住结果）；面板 `autoChangelog` 默认自动展示（有新版调一次，显式文本仍赢，`false` 退回手动）；入口件透传跟上；批量详情行按行自动取（无新增批量电话，单行失败只影响该行）；HTTP 版白名单放行，老三电话形状不变。
+- 按钮交互反馈：查新版/安装在途置忙（禁用 + 文案 + `aria-busy` + 纯 CSS 转圈，并发连点只认第一次）；默认主题补 hover / 按下下沉 / 过渡；busy 脉冲与 `prefers-reduced-motion` 关闭。
+- 原生 `title` 说明：单面板全部动作按钮、批量宏按钮带悬停一句话（零成本 tooltip，不引入浮层组件）。
+- Toast 语义：复制/重启类回执 5 秒后自动过期，不靠下次点击才消失。
+- 首帧骨架：快照没到之前版本条画微光占位（`aria-hidden`，不进语义）。
+- 批量「取消这一批」鼠标两步确认（第一次上膛红框，点别的自动卸膛；程序调 `act('cancel')` 仍一次即执行）。
+- Esc 关弹窗：单面板 / 批量面板 dialog 与入口件 dialog 均支持（容器契约内，只用 innerHTML + 事件）。
+
+## [0.3.1] - 2026-10-05
+
+### Added
+- 新增 `dsh-plugin-update/http`：`createHttpCall`（单三电话 + 批量五电话同一内核，`batchPrefix` 独立）+ `mountUpdatePanelHttp`/`mountUpdateEntryHttp`/`mountUpdateBatchPanelHttp`，只传 pluginId + prefix/batchPrefix + baseUrl/routes 即跑通检查/安装/待重启/失败与批量总账/明细/动作；queue/env/session/rows/progress/diag 全透传，传输失败走 `http-transport-failed` 异常通道，取消整批走 `batchCancel` 电话。
+
 ## [0.3.0] - 2026-10-04
 
 ### Added

package/README.md

@@ -2,14 +2,14 @@
 
 给 DSH 插件加「检查更新 / 安装更新」能力的 npm 包。宿主侧一段接线，面板侧挂一个现成组件，装不上时给用户一条可复制的手工命令。
 
-要求 Node 22 或更高，零运行时依赖。当前版本 `0.3.0`。
+要求 Node 22 或更高，零运行时依赖。当前版本 `0.4.0`。
 
 装上它你会拿到六样东西：
 
-- **三个电话**：查状态（只读本地）、查新版（用户点了才联网一次）、装更新（拿凭证提交）。电话指宿主对外提供的方法。
+- **四个电话**：查状态（只读本地）、查新版（用户点了才联网一次）、装更新（拿凭证提交）、取日志（按版取更新日志，全文或空）。电话指宿主对外提供的方法。
 - **一套落盘**：任务状态、安装锁、回滚凭据，按「插件标识 + 使用范围」隔离，多插件互不干扰。
 - **面板要的派生取值**：电话名与轮询间隔，构建期从本包生成，面板里不写死。
-- **一个现成整组件**：默认内嵌、可切弹窗，调用者传参指定；轮询、安装门控、中文一句话、待重启横幅、手工命令展示与复制、排队可见开关、跳过与恢复、诊断一键复制全在组件内部消化。
+- **一个现成整组件**：默认内嵌、可切弹窗，调用者传参指定；轮询、安装门控、中文一句话、待重启横幅、手工命令展示与复制、排队可见开关、跳过与恢复、诊断一键复制、**更新日志自动展示**全在组件内部消化。
 - **一个更新入口件**：配置页一行挂上就是「检查更新」按钮（或只给状态点的徽标、或整块内嵌），按钮文案随状态自己变；见第 2.5 节。
 - **一套多目标批量更新**：一个插件管 N 个插件的更新（总账 + 明细 + 动作，一家收尾才起下一家，会话落盘可断点续跑）；见第 2.6 节。
 
@@ -52,7 +52,7 @@ for (const [name, handler] of Object.entries(update.handlers)) {
 }
 ```
 
-这一步得到三个电话名：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`。
+这一步得到四个电话名：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`、`notes.updateChangelog`（取日志：给版本号，回该版 tarball 里的更新日志全文，取不到回空）。
 
 `pluginId` 必填（非空字符串，不含路径分隔符）。单例复用键强制含插件标识，多插件不串内存状态与锁。
 除 `pluginId` 之外的配置都可选并带默认值，不传即走默认（见第 3 节）。
@@ -78,6 +78,7 @@ createHostUpdate(
 | `….updateStatus` | `{}` | `{ ok: true, snapshot, manual, receipt: null }` | `{ ok: false, error, errorKind, diag? }` |
 | `….updateCheck` | `{}` | `{ ok: true, snapshot, manual, receipt }` | 同上 |
 | `….updateInstall` | `{ checkId, requestId }` | `{ ok: true, snapshot, manual, receipt: null }` | 同上 |
+| `….updateChangelog` | `{ version }` | `{ ok: true, version, markdown: string \| null }` | 同上 |
 
 - `snapshot` 恒为第 5.1 节那六个字段；`manual` 是第 5.3 节那条手工命令（能给则给，不能给为 `null`）。
 - `receipt` 只有查新版给（`{ checkId, checkedAt, expiresAt }`）；装更新时把 `checkId` 原样带回来，`requestId` 由面板自己生成（同一个编号重复提交直接返回旧结果）。
@@ -144,6 +145,21 @@ mountUpdatePanel(slot, { pluginId: 'my-notes-plugin', prefix: 'notes', call: hos
 
 类型定义随包分发（`dsh-plugin-update/panel` 的 `.d.ts`），不用自编译；面板离线可读，与包版本绑定。
 
+整组件 HTTP 版（无 `host.call` 环境即跑：浏览器面板经 HTTP POST 直达宿主网关，只传三样）：
+
+```js
+import { mountUpdatePanelHttp } from 'dsh-plugin-update/http'
+
+mountUpdatePanelHttp(document.querySelector('#upd'), {
+  pluginId: 'my-plugin',
+  prefix: 'myplug',
+  baseUrl: 'https://host.local:3000/upd',
+  showOthers: false,
+  pollMs: 1000,
+})
+// 离开时 panel.unmount()：只停轮询，安装在宿主侧继续跑。
+```
+
 ### 第 2.5 节：更新入口件（配置页上那一颗按钮）
 
 目标只有一句：**让用户不用点开就知道有没有事。** 一行挂上：
@@ -221,10 +237,23 @@ const panel = mountUpdateBatchPanel(el, {
 })
 ```
 
+批量面板 HTTP 版（无 `host.call` 环境即跑：同一传输内核，五电话走同一映射，取消走 `batchCancel`）：
+
+```js
+import { mountUpdateBatchPanelHttp } from 'dsh-plugin-update/http'
+
+mountUpdateBatchPanelHttp(document.querySelector('#batch'), {
+  batchPrefix: 'life',
+  baseUrl: 'https://host.local:3000/upd',
+  pollMs: 1500,
+})
+// 取消整批走 batchCancel 电话；unmount 只停轮询，宿主侧照跑。
+```
+
 三条硬约束（都在实现里）：**一行只回答一个问题**（这家的下一步是什么，状态词全中文可执行）；
 **行内动作只作用于该行**，「全部更新」是宏而不是第二个状态机；**待重启与失败常驻横幅**，不藏进展开里。
 
-点任意一行展开该家详情：**内容是单插件那套五章内核的只读渲染，动作由批量面板自己提供**。
+点任意一行展开该家详情：**内容是单插件那套五章内核的只读渲染，动作由批量面板自己提供**。第 02 章日志由批量面板按行自动取该行自己的 `updateChangelog` 电话（按行+版本记住结果，取不到即中性提示，不挡安装；`autoChangelog: false` 可关）。
 内核渲染时传 `actions: 'none'`——五章内容、进度条、「已跳过」提示一字不减，**动作按钮一个都不画**
 （内核里那些按钮带的是 `data-action`，批量面板只认 `data-act`；照搬 markup 而不接管行为，
 就会得到「可点却没反应」的死按钮——这条缝现在由渲染开关焊死）。详情里的动作行是批量面板自己的：
@@ -246,11 +275,33 @@ const panel = mountUpdateBatchPanel(el, {
 **跨使用范围如实拒绝**：`web` 与 `desktop` 各自排队（装的是不同落点），混在一起的目标会回
 `cross-scope`，本包不会替你跨范围抢锁。
 
+### 第 2.7 节：更新日志自动展示（告诉用户更新了什么）
+
+任何插件的升级能力都是两件事：**① 给一套面板**（上面第 4 步 / 2.5 / 2.6，挂载一行即跑）；**② 告诉用户这次更新了什么**（本节，写 md 即显示，零新增代码）。
+
+```js
+import { mountUpdatePanel } from 'dsh-plugin-update/panel'
+
+// 与第 4 步同一行，不用加任何参数：有新版时第 02 章“更新日志”自动出现
+const panel = mountUpdatePanel(document.getElementById('update-slot'), {
+  pluginId: 'my-notes-plugin',
+  prefix: 'notes',
+  call: (name, args) => host.call(name, args),
+})
+```
+
+作者侧只写文件，不写代码（发布后用户自动看到）：
+
+1. 包根放 `CHANGELOG.md`（文件名全大写，小写视为没有），版本节形如 `## [1.2.0] - 2026-10-05`（最新在前），分类用 `### Added/Fixed/Changed`（面板展开；`Deprecated/Removed/Security` 折叠；`Unreleased` 与空节忽略）。
+2. `package.json` 的 `files` 白名单加上 `CHANGELOG.md`（否则发出去的包里没有它，面板永远读不到），发布前跑一次 `npm publish --dry-run` 核对。
+
+行为：有新版时面板按新版号自动取一次该版 tarball 里的全文（复用官方源 + `integrity` 校验，同一版本只取一次）；删了文件或取不到即中性提示，**安装永远不受影响**。想自己接管就传 `autoChangelog: false` 退回手动（备好文本后 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 传入，显式文本永不被覆盖）。入口件与批量面板同样自动：前者透传，后者展开行按行取。细节与边界见第 5.8 节。
+
 ### 升级本包（已经接入过的项目）
 
 宿主种类与安装出口都由本包自己探测和选择，**升级依赖即可，宿主侧与面板侧都不用改代码**：
 
-1. 依赖版本提到 `^0.3.0`。
+1. 依赖版本提到 `^0.4.0`。
 2. 重新装 / 发一版你自己的插件，让新依赖进当前使用范围（运行时用的是 `node_modules` 里那份）。
 3. 如果你自己接过一版宿主安装出口，把它删掉——它会挡在本包的路由前面。
 
@@ -398,7 +449,8 @@ dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=ht
 
 - 有新版时面板在横幅下方展示“更新说明（当前版 → 新版）：”，按目标包内 `CHANGELOG.md`（Keep-a-Changelog 子集）渲染：`Added/Fixed/Changed` 展开，`Deprecated/Removed/Security` 折叠，`Unreleased` 与空节不展示。
 - 作者未提供说明时显示“作者未提供更新说明，安装不受影响。”——缺日志永不挡安装，不改变 `canInstall` 与 `blockedReason`。
-- 说明文本由集成方备好后传入：已装版离线读本机 `node_modules/<目标包>/CHANGELOG.md`，新版按需取新版 tarball 内同名文件（复用官方源与 `integrity` 校验，取不到即回落中性提示；参考包根导出的 `readInstalledChangelogText` / `fetchReleaseChangelogText`），经 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 交给面板。
+- 默认自动：面板看到有新版即按新版号调一次 `….updateChangelog`，回来自己填进第 02 章；同一版本只取一次，取不到即中性提示。作者侧只要写好包根 `CHANGELOG.md` 并随包发布，零新增代码。
+- 手动模式（老用法照旧）：传 `autoChangelog: false` 即退回手动——已装版离线读本机 `node_modules/<目标包>/CHANGELOG.md`，新版按需取新版 tarball 内同名文件（复用官方源与 `integrity` 校验，取不到即回落中性提示；参考包根导出的 `readInstalledChangelogText` / `fetchReleaseChangelogText`），经 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 交给面板；显式传过的文本自动链路永不覆盖。
 
 ## 6. 排错
 
@@ -438,6 +490,25 @@ import { mountUpdatePanel } from 'dsh-plugin-update/panel'
 mountUpdatePanel(slot, { pluginId: 'notes', prefix: 'notes', call: host.call })
 ```
 
+**更新日志自动**（#38：写 md 即显示，零新增代码）：
+
+```js
+// 宿主侧：createHostUpdate 顺手注册第 4 个电话，无新增配置
+//   入参 { version }（发行版号，先验 validReleaseVersion + 通道门禁）
+//   成功 { ok: true, version, markdown: string | null }（取不到即 null，中性提示）
+//   失败复用 error / errorKind 体系；回包无路径、无快照；按版本记住结果
+import { buildChangelogPhoneName } from 'dsh-plugin-update'
+
+buildChangelogPhoneName('notes')  // 'notes.updateChangelog'，与宿主侧同一套拼法
+
+// 面板侧：默认自动，有新版调一次；显式文本仍赢，false 退回手动
+mountUpdatePanel(slot, { pluginId: 'my-notes-plugin', prefix: 'notes', call: host.call })
+// mountUpdatePanel(slot, { pluginId, prefix, call, autoChangelog: false })
+// mountUpdatePanel(slot, { pluginId, prefix, call, changelogMarkdown })  // 手动模式
+```
+
+- 入口件（`dsh-plugin-update/entry`）把 `autoChangelog / changelogMarkdown` 透传给面板 dialog/inline；批量面板（`dsh-plugin-update/panel-batch`）展开行自动调该行自己的 `updateChangelog`（无新增批量电话，`autoChangelog: false` 可关整批）；HTTP 版（`dsh-plugin-update/http`）白名单已放行，默认路径即达。
+
 **客户端入口**（`dist/client.js`，构建期打包用）：
 
 ```js
@@ -478,6 +549,6 @@ queuePositionOf(queueState, 'my-plugin', requestId)  // 0 = 在装，1..n = 顺
 
 ## 9. 兼容与稳定性
 
-这些形状稳定，可以放心依赖：三个电话名与入参回参、快照六字段、任务公开形状、配置只经函数入参注入、安装配方五键、日志事件字段基线（三个事件各带必填 `pluginId`）、历史落盘路径。
+这些形状稳定，可以放心依赖：四个电话名与入参回参（老三电话一字不动，`updateChangelog` 是新增）、快照六字段、任务公开形状、配置只经函数入参注入、安装配方五键、日志事件字段基线（三个事件各带必填 `pluginId`）、历史落盘路径。
 
 向后兼容的扩展：新增可选配置键、新增可选 `readerOverrides`（如 `targetPackageDir`）、新增宿主种类与路由取值。调用方不认新取值时按普通宿主处理即可，不会因此报错。

package/dist/client.d.ts

@@ -1,6 +1,6 @@
-import { type PhoneAction } from './config.js';
-export { buildPhoneName, buildPhoneNames } from './config.js';
-export type { PhoneAction } from './config.js';
+import { type ChangelogPhoneAction, type PhoneAction } from './config.js';
+export { buildChangelogPhoneName, buildPhoneName, buildPhoneNames } from './config.js';
+export type { ChangelogPhoneAction, PhoneAction } from './config.js';
 export { manualCommand } from './commands.js';
 export { QUEUE_INTENT_TTL_MS, cancelEnqueuedInQueue, emptyQueueState, enqueueInQueue, isHeadOfQueue, isQueueBusy, normalizeQueueState, pruneExpiredIntents, queuePositionOf, releaseOwnerInQueue, setOwnerIfFree, visibleQueueFor, } from './queue.js';
 export type { QueuedEntry, QueueOwner, UpdateQueueState, VisibleQueue, VisibleQueueOwner } from './queue.js';
@@ -12,5 +12,5 @@ export declare const CLIENT_POLL: {
     readonly defaultMs: 1000;
     readonly minMs: 250;
 };
-export declare function buildClientPhoneNames(prefix: string): Record<PhoneAction, string>;
+export declare function buildClientPhoneNames(prefix: string): Record<PhoneAction, string> & Record<ChangelogPhoneAction, string>;
 export declare function assertPollInterval(ms: unknown): number;

package/dist/client.js

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/client.ts
 import { buildPhoneNames, DEFAULT_PANEL_POLL_MS, MIN_PANEL_POLL_MS } from "./config.js";
-import { buildPhoneName, buildPhoneNames as buildPhoneNames2 } from "./config.js";
+import { buildChangelogPhoneName, buildPhoneName, buildPhoneNames as buildPhoneNames2 } from "./config.js";
 import { manualCommand as manualCommand2 } from "./commands.js";
 import {
   QUEUE_INTENT_TTL_MS,
@@ -66,6 +66,7 @@ export {
   batchEntryOf,
   batchProgress,
   batchRequestId,
+  buildChangelogPhoneName,
   buildClientPhoneNames,
   buildPhoneName,
   buildPhoneNames2 as buildPhoneNames,

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 export declare const DEFAULT_PREFIX = "wf";
 export declare const PHONE_ACTIONS: readonly ["updateStatus", "updateCheck", "updateInstall"];
 export type PhoneAction = (typeof PHONE_ACTIONS)[number];
+export declare const CHANGELOG_PHONE_ACTION: "updateChangelog";
+export type ChangelogPhoneAction = typeof CHANGELOG_PHONE_ACTION;
 export declare const DEFAULT_TARGET_PACKAGE = "dsh-mattpocock-skills-deck";
 export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
 export declare const LEGACY_PLUGIN_ID = "dsh-mattpocock-skills-deck";
@@ -44,5 +46,6 @@ export interface ResolvedUpdateConfig {
 export declare function assertPluginId(value: unknown): string;
 export declare function assertPrefix(value: unknown, role: string): string;
 export declare function resolveUpdateConfig(input: UpdateConfigInput): ResolvedUpdateConfig;
-export declare function buildPhoneNames(prefix: string): Record<PhoneAction, string>;
+export declare function buildPhoneNames(prefix: string): Record<PhoneAction, string> & Record<ChangelogPhoneAction, string>;
+export declare function buildChangelogPhoneName(prefix: string): string;
 export declare function buildPhoneName(prefix: string, action: PhoneAction): string;

package/dist/config.js

@@ -1,6 +1,7 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/config.ts
 const DEFAULT_PREFIX = "wf";
 const PHONE_ACTIONS = ["updateStatus", "updateCheck", "updateInstall"];
+const CHANGELOG_PHONE_ACTION = "updateChangelog";
 const DEFAULT_TARGET_PACKAGE = "dsh-mattpocock-skills-deck";
 const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
 const LEGACY_PLUGIN_ID = "dsh-mattpocock-skills-deck";
@@ -73,14 +74,19 @@ function buildPhoneNames(prefix) {
   return {
     updateStatus: checked + ".updateStatus",
     updateCheck: checked + ".updateCheck",
-    updateInstall: checked + ".updateInstall"
+    updateInstall: checked + ".updateInstall",
+    updateChangelog: checked + ".updateChangelog"
   };
 }
+function buildChangelogPhoneName(prefix) {
+  return buildPhoneNames(prefix).updateChangelog;
+}
 function buildPhoneName(prefix, action) {
   return buildPhoneNames(prefix)[action];
 }
 export {
   BACKUP_FILE,
+  CHANGELOG_PHONE_ACTION,
   DEFAULT_CHECK_TIMEOUT_MS,
   DEFAULT_CONFIRMATION_TTL_MS,
   DEFAULT_INSTALL_TIMEOUT_MS,
@@ -99,6 +105,7 @@ export {
   STATE_FILE,
   assertPluginId,
   assertPrefix,
+  buildChangelogPhoneName,
   buildPhoneName,
   buildPhoneNames,
   resolveUpdateConfig

package/dist/entry.d.ts

@@ -31,6 +31,12 @@ export interface UpdateEntryOptions {
     label?: string;
     profileName?: string;
     pollMs?: number;
+    /**
+     * 更新日志自动/手动（#38）：透传给面板（dialog 与 inline 同走 mountPanel），默认自动；
+     * 显式文本仍赢，false 退回手动。入口件自己不取数。
+     */
+    autoChangelog?: boolean;
+    changelogMarkdown?: string | null;
     /** variant='badge' 或 openOn='manual' 时，点击交给接入方（自己跳自己的页面）。 */
     onActivate?: (state: {
         hasUpdate: boolean;

package/dist/entry.js

@@ -48,6 +48,13 @@ const UPDATE_ENTRY_CSS = [
   ".dsh-upd-entry-btn{font:inherit;border:1px solid var(--dsh-upd-line,#d1d5db);border-radius:6px;",
   "background:var(--dsh-upd-btn,#f9fafb);color:inherit;padding:4px 12px;cursor:pointer}",
   ".dsh-upd-entry-btn:hover{border-color:var(--dsh-upd-primary,#2563eb)}",
+  ".dsh-upd-entry-btn,.dsh-upd-entry-dot{transition:background-color .15s ease,border-color .15s ease,color .15s ease,transform .06s ease}",
+  ".dsh-upd-entry-btn:active:not(:disabled){transform:translateY(1px)}",
+  ".dsh-upd-entry-btn:disabled,.dsh-upd-entry-dot:disabled{opacity:.55;cursor:wait}",
+  '.dsh-upd-entry-btn[aria-busy="true"]::after{content:"";display:inline-block;width:10px;height:10px;margin-left:7px;vertical-align:-1px;',
+  "border:2px solid currentColor;border-top-color:transparent;border-radius:50%;animation:dsh-upd-entry-spin .8s linear infinite}",
+  "@keyframes dsh-upd-entry-spin{to{transform:rotate(360deg)}}",
+  '@media (prefers-reduced-motion: reduce){.dsh-upd-entry-btn,.dsh-upd-entry-dot{transition:none}.dsh-upd-entry-btn[aria-busy="true"]::after{animation:none}}',
   ".dsh-upd-entry-btn:focus-visible,.dsh-upd-entry-dot:focus-visible{outline:2px solid var(--dsh-upd-focus,#2563eb);outline-offset:1px}",
   '.dsh-upd-entry[data-state="update"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-ok-line,#059669);color:var(--dsh-upd-ok-line,#059669)}',
   '.dsh-upd-entry[data-state="restart"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-warn-line,#d97706);color:var(--dsh-upd-warn-line,#d97706)}',
@@ -121,6 +128,7 @@ function mountUpdateEntry(container, options) {
   let snapshot = null;
   let error = null;
   let note = null;
+  let activating = false;
   let mounted = true;
   let panel = null;
   let panelMode = null;
@@ -156,9 +164,10 @@ function mountUpdateEntry(container, options) {
   }
   function entryHTML() {
     const kind = entryStateKind(stateOf());
-    const text = currentLabel();
+    const text = activating ? "\u6B63\u5728\u67E5\u65B0\u7248\u2026" : currentLabel();
+    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)}"></button>` : `<button type="button" class="dsh-upd-entry-btn" ${ENTRY_ATTR}="activate">${escapeHtml(text)}</button>`;
+    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>
 <span class="dsh-upd-entry" data-variant="${variant}" data-state="${kind}"${themeAttr}>${control}${noteHTML}</span>`;
@@ -208,6 +217,8 @@ function mountUpdateEntry(container, options) {
       theme,
       pollMs,
       profileName,
+      autoChangelog: options.autoChangelog,
+      changelogMarkdown: options.changelogMarkdown ?? null,
       call: panelCall
     });
     panelMode = mode;
@@ -233,10 +244,15 @@ function mountUpdateEntry(container, options) {
     void refresh();
   }
   async function activate() {
-    if (!mounted || panelMode !== null) return;
+    if (!mounted || panelMode !== null || activating) return;
+    activating = true;
     note = null;
     render();
-    await checkNow();
+    try {
+      await checkNow();
+    } finally {
+      activating = false;
+    }
     if (!mounted) return;
     if (variant === "badge" || openOn === "manual") {
       if (onActivate) onActivate({ hasUpdate: hasUpdate(), latestVersion: snapshot?.latestVersion ?? null });
@@ -273,6 +289,14 @@ function mountUpdateEntry(container, options) {
     } catch {
     }
   }
+  function onKeyDown(ev) {
+    try {
+      const e = ev;
+      if (!mounted || panelMode !== "dialog" || !e || e.key !== "Escape") return;
+      close();
+    } catch {
+    }
+  }
   function unmount() {
     if (!mounted) return;
     mounted = false;
@@ -287,11 +311,19 @@ function mountUpdateEntry(container, options) {
       container.removeEventListener?.("click", onClick);
     } catch {
     }
+    try {
+      container.removeEventListener?.("keydown", onKeyDown);
+    } catch {
+    }
   }
   try {
     container.addEventListener?.("click", onClick);
   } catch {
   }
+  try {
+    container.addEventListener?.("keydown", onKeyDown);
+  } catch {
+  }
   if (variant === "inline") mountPanel("embedded");
   else render();
   if (autoCheck === "mount") void refresh();

package/dist/host.d.ts

@@ -1,8 +1,8 @@
-import { type PhoneAction, type UpdateConfigInput } from './config.js';
+import { type ChangelogPhoneAction, type PhoneAction, type UpdateConfigInput } from './config.js';
 import type { EnvironmentKind, ReleaseChannel } from './ports.js';
 import { type UpdateQueueState } from './queue.js';
-export { buildPhoneName, buildPhoneNames, resolveUpdateConfig } from './config.js';
-export type { PhoneAction, UpdateConfigInput } from './config.js';
+export { buildChangelogPhoneName, buildPhoneName, buildPhoneNames, resolveUpdateConfig } from './config.js';
+export type { ChangelogPhoneAction, PhoneAction, UpdateConfigInput } from './config.js';
 export { parseEventListManifest, checkEventFields, checkEventCounts } from './gate.js';
 export type { GateEventLevel, GateEventKind, GateEventEntry, GateEventCounts, GateEventList, GateFieldCheck, GateCountCheck } from './gate.js';
 export { containingPackage, defaultHomeDir, profileNameValid, registrySpec, resolveTargetPackage } from './reader.js';
@@ -111,7 +111,7 @@ type LogCtx = {
     fire: (level: string, event: string, fields: Record<string, unknown>) => void;
 } | null;
 export interface HostUpdate {
-    phoneNames: Record<PhoneAction, string>;
+    phoneNames: Record<PhoneAction, string> & Record<ChangelogPhoneAction, string>;
     handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
 }
 /**

package/dist/host.js

@@ -10,8 +10,9 @@ import {
   resolveUpdateConfig
 } from "./config.js";
 import { manualCommand } from "./commands.js";
+import { fetchReleaseChangelogText } from "./changelog-io.js";
 import { buildDiag } from "./diag.js";
-import { isVersionAllowedInChannel, validRequestId } from "./service.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";
 import {
@@ -27,7 +28,7 @@ import {
   setOwnerIfFree,
   visibleQueueFor
 } from "./queue.js";
-import { buildPhoneName, buildPhoneNames as buildPhoneNames2, resolveUpdateConfig as resolveUpdateConfig2 } from "./config.js";
+import { buildChangelogPhoneName, buildPhoneName, buildPhoneNames as buildPhoneNames2, resolveUpdateConfig as resolveUpdateConfig2 } from "./config.js";
 import { parseEventListManifest, checkEventFields, checkEventCounts } from "./gate.js";
 import { containingPackage, defaultHomeDir as defaultHomeDir2, profileNameValid, registrySpec, resolveTargetPackage as resolveTargetPackage2 } from "./reader.js";
 import {
@@ -87,7 +88,7 @@ import {
   CHANGELOG_TAR_MAX_BYTES,
   CHANGELOG_TARBALL_MAX_BYTES,
   extractChangelogFromTar,
-  fetchReleaseChangelogText,
+  fetchReleaseChangelogText as fetchReleaseChangelogText2,
   readInstalledChangelogText
 } from "./changelog-io.js";
 import { createUpdateDiskPorts as createUpdateDiskPorts2, createUpdateExecutor as createUpdateExecutor2, pathsForUpdate, resolveCliEntry } from "./store.js";
@@ -105,7 +106,7 @@ import {
   compareReleaseVersions,
   isPrereleaseVersion,
   isVersionAllowedInChannel as isVersionAllowedInChannel2,
-  validReleaseVersion,
+  validReleaseVersion as validReleaseVersion2,
   validVersion,
   compareVersions
 } from "./service.js";
@@ -524,6 +525,49 @@ function loggedPhone(method, kind, pluginId, fn, diagCtx) {
     }
   };
 }
+function loggedChangelogPhone(method, pluginId, fn, diagCtx) {
+  return async function(args) {
+    const t0 = Date.now();
+    const emit = (level, event, fields) => {
+      try {
+        if (phoneLogCtx && typeof phoneLogCtx.fire === "function") phoneLogCtx.fire(level, event, fields);
+      } catch {
+      }
+    };
+    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 });
+      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 });
+      let diag;
+      try {
+        const cfg = diagCtx?.config;
+        const overrides = diagCtx?.readerOverrides ?? {};
+        const envRaw = overrides?.environmentKind;
+        const runningRaw = overrides?.runningVersion;
+        const built = buildDiag({
+          errorCode: payload.error,
+          phoneKind: "update-changelog",
+          error,
+          args: safeArgs,
+          targetPackageName: cfg?.targetPackageName,
+          registryUrl: cfg?.registryUrl,
+          runningVersion: typeof runningRaw === "string" ? runningRaw : void 0,
+          latestVersion: void 0,
+          environmentKind: typeof envRaw === "string" ? envRaw : void 0,
+          latencyMs: Date.now() - t0
+        });
+        if (built && typeof built === "object") diag = built;
+      } catch {
+        diag = void 0;
+      }
+      return { ok: false, ...payload, ...diag ? { diag } : {} };
+    }
+  };
+}
 function createHostUpdate(deps = {}, configInput) {
   const config = resolveUpdateConfig(configInput);
   const pluginId = config.pluginId;
@@ -533,6 +577,28 @@ function createHostUpdate(deps = {}, configInput) {
   else watchDesktopPnpm(ctx);
   const readerOverrides = { ...deps.readerOverrides ?? {}, ctx, ...deps.pluginManager ? { pluginManager: deps.pluginManager } : {} };
   const phoneNames = buildPhoneNames(config.prefix);
+  const changelogCache = /* @__PURE__ */ new Map();
+  async function readChangelog(args) {
+    const raw = args ? args["version"] : void 0;
+    if (!validReleaseVersion(raw)) throw updateError("invalid-release");
+    const version = raw;
+    if (!isVersionAllowedInChannel(version, config.releaseChannel)) throw updateError("invalid-release");
+    if (changelogCache.has(version)) return { version, markdown: changelogCache.get(version) ?? null };
+    const fetchImpl = readerOverrides.fetchImpl ?? globalThis.fetch;
+    const release = await fetchNpmVersionRelease(fetchImpl, config.checkTimeoutMs, {
+      targetPackageName: config.targetPackageName,
+      registryUrl: config.registryUrl,
+      releaseChannel: config.releaseChannel,
+      version
+    });
+    const markdown = await fetchReleaseChangelogText(
+      fetchImpl,
+      { tarball: release.tarball, integrity: release.integrity, version },
+      { targetPackageName: config.targetPackageName, registryUrl: config.registryUrl, timeoutMs: config.checkTimeoutMs }
+    );
+    changelogCache.set(version, markdown);
+    return { version, markdown };
+  }
   async function readStatus(args) {
     const reader = await getSharedReader(pluginId, config, {
       ...readerOverrides,
@@ -630,6 +696,10 @@ function createHostUpdate(deps = {}, configInput) {
     [phoneNames.updateInstall]: loggedPhone(phoneNames.updateInstall, "update-install", pluginId, runInstall, {
       config,
       readerOverrides
+    }),
+    [phoneNames.updateChangelog]: loggedChangelogPhone(phoneNames.updateChangelog, pluginId, readChangelog, {
+      config,
+      readerOverrides
     })
   };
   return { phoneNames, handlers };
@@ -682,6 +752,7 @@ export {
   SKIPPED_FILE,
   __resetSharedUpdateReaderForTests,
   addSkipped,
+  buildChangelogPhoneName,
   buildDiag2 as buildDiag,
   buildPhoneName,
   buildPhoneNames2 as buildPhoneNames,
@@ -709,7 +780,7 @@ export {
   enforceBudget as enforceDiagBudgetForPhone,
   enqueueInQueue2 as enqueueInQueue,
   extractChangelogFromTar,
-  fetchReleaseChangelogText,
+  fetchReleaseChangelogText2 as fetchReleaseChangelogText,
   hasVisibleSections,
   isHeadOfQueue2 as isHeadOfQueue,
   isPrereleaseVersion,
@@ -741,7 +812,7 @@ export {
   setOwnerIfFree2 as setOwnerIfFree,
   skipKey,
   truncateToWordBoundary,
-  validReleaseVersion,
+  validReleaseVersion2 as validReleaseVersion,
   validVersion,
   visibleQueueFor2 as visibleQueueFor
 };