@dsh-workbench/shared 0.3.4 → 0.3.5

package/dist/api/facts.js

@@ -1,13 +1,36 @@
+/**
+ * 范围查法的后缀：cmdb/* 这类名字表示「这个前缀下的一族」，不是一条事实。
+ */
 export const FACT_SCOPE_SUFFIX = '*';
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
 export function unitFactScope(unit) {
     return `${unit}${FACT_SCOPE_SUFFIX}`;
 }
+/**
+ * 判一个名字是不是范围查法，不是问这条事实存不存在。
+ * @param name 事实名或范围名。
+ * @returns 单字符 * 不算范围；只有「至少一个字符加 *」才算。
+ */
 export function isFactScope(name) {
     return name.length > 1 && name.endsWith(FACT_SCOPE_SUFFIX);
 }
+/**
+ * 取范围名对应的前缀，普通事实名原样返回。
+ * @param name 事实名或范围名。
+ * @returns 去掉末尾 * 的前缀；本来不是范围就给原值。
+ */
 export function scopePrefixOf(name) {
     return isFactScope(name) ? name.slice(0, -FACT_SCOPE_SUFFIX.length) : name;
 }
+/**
+ * 造一条事实通道：第一次订阅时才连传输层，最后一个订阅者走掉就断开。
+ * @param options 传输层，用来连宿主。
+ * @returns 通道句柄；没记录过的事实版本给 0，refresh() 不带事实名时刷新全部并逐个通知。
+ */
 export function createFactChannel(options) {
     const entries = new Map();
     let epoch = null;
@@ -124,6 +147,11 @@ export function createFactChannel(options) {
     };
     return channel;
 }
+/**
+ * 把传输层收到的原始数据读成一帧；坏数据当没收到。
+ * @param data 帧的原始数据，期望是 JSON 字符串。
+ * @returns 合法帧；不是字符串、JSON 坏了、或 rev 不是数字都给 null。
+ */
 export function parseFactFrame(data) {
     if (typeof data !== 'string')
         return null;
@@ -141,6 +169,11 @@ export function parseFactFrame(data) {
         return null;
     }
 }
+/**
+ * 读口路由到事实名的映射，当前一对一。
+ * @param route 读口路由。
+ * @returns 该路由对应的事实名（就是路由本身）。
+ */
 export function factOfRoute(route) {
     return route;
 }

package/dist/api/host-write.d.ts

@@ -1,6 +1,18 @@
 import type { ApiResponse } from './workbench-client.js';
+/**
+ * 宿主写口的五条通道（偏好、动作、供给、工坊调试、工坊录制），是写路由的第一段。
+ */
 export type WriteChannel = 'prefs' | 'actions' | 'provision' | 'diy-debug' | 'diy-record';
+/**
+ * 由通道与资源拼出写路由。
+ * @param channel 写通道。
+ * @param resource 该通道下的资源名。
+ * @returns 路由字符串；provision 只有一段，其余是 channel/resource。
+ */
 export declare function writeRoute(channel: WriteChannel, resource: string): string;
+/**
+ * 写通道统一的结果：成了带值，没成带一句能给人看的话（可选明细与帮助链接）。
+ */
 export type WriteOutcome<T> = {
     readonly ok: true;
     readonly value: T;
@@ -10,4 +22,10 @@ export type WriteOutcome<T> = {
     readonly detail?: string;
     readonly helpUrl?: string;
 };
+/**
+ * 把写通道的响应翻成 WriteOutcome。
+ * @param response 写口回的响应；null 表示请求本身没成（网络断了，宿主没答）。
+ * @param networkText 拿不到任何服务端文案时兜底的那句。
+ * @returns 失败时 message 优先用服务端自己的话，没有才用响应正文或 networkText。
+ */
 export declare function writeOutcomeOf<T>(response: ApiResponse<T> | null, networkText: string): WriteOutcome<T>;

package/dist/api/host-write.js

@@ -1,8 +1,20 @@
+/**
+ * 由通道与资源拼出写路由。
+ * @param channel 写通道。
+ * @param resource 该通道下的资源名。
+ * @returns 路由字符串；provision 只有一段，其余是 channel/resource。
+ */
 export function writeRoute(channel, resource) {
     if (channel === 'provision')
         return 'provision';
     return `${channel}/${resource}`;
 }
+/**
+ * 把写通道的响应翻成 WriteOutcome。
+ * @param response 写口回的响应；null 表示请求本身没成（网络断了，宿主没答）。
+ * @param networkText 拿不到任何服务端文案时兜底的那句。
+ * @returns 失败时 message 优先用服务端自己的话，没有才用响应正文或 networkText。
+ */
 export function writeOutcomeOf(response, networkText) {
     if (response === null)
         return { ok: false, message: networkText };

package/dist/api/long-task.d.ts

@@ -1,18 +1,54 @@
+/**
+ * 一条长任务的四种态；needs-login 与 running 一样算还没结束。
+ */
 export type LongTaskStatus = 'running' | 'needs-login' | 'ok' | 'failed';
+/**
+ * 长任务步骤流里的一行：kind 定样式，登录那一步带 loginUrl 给用户去点。
+ */
 export interface LongTaskStep {
     readonly kind: 'start' | 'succeed' | 'fail' | 'info' | 'warn';
     readonly text: string;
     readonly loginUrl?: string | undefined;
 }
+/**
+ * 单元的长任务读口路由。
+ * @param unit 单元 id。
+ * @returns <unit>/runs。
+ */
 export declare function runsRouteOf(unit: string): string;
+/**
+ * 长任务读口回的载荷：一串 run，形状由模块自己定，外壳只透传。
+ */
 export interface LongTasksPayload {
     readonly runs: readonly Readonly<Record<string, unknown>>[];
 }
+/**
+ * 有长任务在跑时的轮询间隔（毫秒）。
+ */
 export declare const LONG_TASK_POLL_MS = 1500;
+/**
+ * 没有长任务时的轮询间隔（毫秒），比在跑那一档大一个量级。
+ */
 export declare const LONG_TASK_IDLE_MS = 10000;
+/**
+ * 算这次该隔多久再问一次长任务。
+ * @param live 是否有在跑的长任务。
+ * @param override 调用点指定的间隔；给了就用它，不再看 live。
+ * @returns 毫秒：有活 1500，没活 10000。
+ */
 export declare function longTaskPollMs(live: boolean, override?: number | undefined): number;
+/**
+ * 从读口状态里取 run 列表。
+ * @param state 读口状态；value 还没到就按空算。
+ * @returns 一串 run（形状由调用点自己判），没有就给空数组。
+ */
 export declare function longTaskRunsOf<T>(state: {
     readonly phase?: string | undefined;
     readonly value?: LongTasksPayload | undefined;
 }): readonly T[];
+/**
+ * 把长任务态折成状态点的那一档。
+ * @param status 长任务的四种态。
+ * @returns ongoing / done / error / idle；needs-login 也算进行中。
+ */
 export declare function longTaskDot(status: LongTaskStatus): 'ongoing' | 'done' | 'error' | 'idle';

package/dist/api/long-task.js

@@ -1,16 +1,43 @@
+/**
+ * 单元的长任务读口路由。
+ * @param unit 单元 id。
+ * @returns <unit>/runs。
+ */
 export function runsRouteOf(unit) {
     return `${unit}/runs`;
 }
+/**
+ * 有长任务在跑时的轮询间隔（毫秒）。
+ */
 export const LONG_TASK_POLL_MS = 1500;
+/**
+ * 没有长任务时的轮询间隔（毫秒），比在跑那一档大一个量级。
+ */
 export const LONG_TASK_IDLE_MS = 10_000;
+/**
+ * 算这次该隔多久再问一次长任务。
+ * @param live 是否有在跑的长任务。
+ * @param override 调用点指定的间隔；给了就用它，不再看 live。
+ * @returns 毫秒：有活 1500，没活 10000。
+ */
 export function longTaskPollMs(live, override) {
     if (override !== undefined)
         return override;
     return live ? LONG_TASK_POLL_MS : LONG_TASK_IDLE_MS;
 }
+/**
+ * 从读口状态里取 run 列表。
+ * @param state 读口状态；value 还没到就按空算。
+ * @returns 一串 run（形状由调用点自己判），没有就给空数组。
+ */
 export function longTaskRunsOf(state) {
     return (state.value?.runs ?? []);
 }
+/**
+ * 把长任务态折成状态点的那一档。
+ * @param status 长任务的四种态。
+ * @returns ongoing / done / error / idle；needs-login 也算进行中。
+ */
 export function longTaskDot(status) {
     if (status === 'ok')
         return 'done';

package/dist/api/unit-board.d.ts

@@ -1,14 +1,39 @@
 import type { ModuleBlocker } from './blocker.js';
 import type { CapabilityPayload } from './workbench-contract.js';
 import type { ApiError } from './workbench-client.js';
+/**
+ * 卡片闸的两种档：capability 按环境读数判，none 无条件放行。
+ */
 export type GateMode = 'capability' | 'none';
+/**
+ * 一次放行判定的结果；gated 为假时卡片不画。
+ */
 export interface UnitGate {
     readonly gated: boolean;
 }
+/**
+ * 判这张卡现在能不能画。
+ * @param capability 环境读数；还没读到给 null。
+ * @param mode 闸档。
+ * @returns mode 为 none 或读数还没到都放行（先放行让它读）；读到明确不通过（ok 与 unchecked 之外）才拦。
+ */
 export declare function gateOf(capability: CapabilityPayload | null, mode: GateMode): UnitGate;
+/**
+ * 一个单元攒下的卡住态：blocker 顶掉卡片，notice 只提示；组装方产出，卡片消费。
+ */
 export interface UnitBlockers {
     readonly blocker?: ModuleBlocker;
     readonly notice?: ModuleBlocker;
 }
+/**
+ * 把候选卡住态分档，每档只留第一个。
+ * @param candidates 候选（可能含 undefined），按优先级从高到低给。
+ * @returns 分出的 blocker 与 notice；已经有 blocker 时不带 notice（挡住就不必再提示）。
+ */
 export declare function splitBlocker(candidates: readonly (ModuleBlocker | undefined)[]): UnitBlockers;
+/**
+ * 由读口错误算出「出错搭车强探」的防抖键：同一个键只自动重探一次。
+ * @param error 读口错误；undefined 表示这次没有错误。
+ * @returns 键字符串；空 code 归一到 unknown。
+ */
 export declare function probeKeyOf(error: ApiError | undefined): string | null;

package/dist/api/unit-board.js

@@ -1,3 +1,9 @@
+/**
+ * 判这张卡现在能不能画。
+ * @param capability 环境读数；还没读到给 null。
+ * @param mode 闸档。
+ * @returns mode 为 none 或读数还没到都放行（先放行让它读）；读到明确不通过（ok 与 unchecked 之外）才拦。
+ */
 export function gateOf(capability, mode) {
     if (mode === 'none')
         return { gated: true };
@@ -5,6 +11,11 @@ export function gateOf(capability, mode) {
         return { gated: true };
     return { gated: capability.status === 'ok' || capability.status === 'unchecked' };
 }
+/**
+ * 把候选卡住态分档，每档只留第一个。
+ * @param candidates 候选（可能含 undefined），按优先级从高到低给。
+ * @returns 分出的 blocker 与 notice；已经有 blocker 时不带 notice（挡住就不必再提示）。
+ */
 export function splitBlocker(candidates) {
     let blocker;
     let notice;
@@ -22,6 +33,11 @@ export function splitBlocker(candidates) {
         ...(blocker !== undefined || notice === undefined ? {} : { notice }),
     };
 }
+/**
+ * 由读口错误算出「出错搭车强探」的防抖键：同一个键只自动重探一次。
+ * @param error 读口错误；undefined 表示这次没有错误。
+ * @returns 键字符串；空 code 归一到 unknown。
+ */
 export function probeKeyOf(error) {
     if (error === undefined)
         return null;

package/dist/api/unit-declaration.d.ts

@@ -1,15 +1,30 @@
 import type { UnitEnvNeeds, UnitHostNeeds, UnitManifest } from './unit.js';
+/**
+ * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
+ */
 export declare const WORKBENCH_API_VERSION = 1;
+/**
+ * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
+ */
 export declare const SUPPORTED_API_VERSIONS: readonly number[];
+/**
+ * 清单里那半张卡片声明：文案键加排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
+ */
 export interface UnitCardDeclaration {
     readonly titleKey: string;
     readonly order: number;
 }
+/**
+ * 清单里的一条工具声明：进 dsh 工具表的全名、会不会写，以及生成物里的键名。
+ */
 export interface UnitToolDeclaration {
     readonly name: string;
     readonly writes: boolean;
     readonly key?: string;
 }
+/**
+ * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、卡片、工具、宿主与环境需要）。
+ */
 export interface UnitDeclaration {
     readonly apiVersion: number;
     readonly unit: string;
@@ -18,12 +33,33 @@ export interface UnitDeclaration {
     readonly host: UnitHostNeeds;
     readonly env?: UnitEnvNeeds;
 }
+/**
+ * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ */
 export declare const DECLARATION_KEYS: readonly string[];
+/**
+ * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ */
 export declare const DECLARATION_REQUIRED_KEYS: readonly string[];
+/**
+ * 查清单里 dsh.workbench 那一段的形状，回一串给人看的问题（中文，带字段路径）。
+ * @param subject 报错时用的主语，一般是包名。
+ * @param raw 清单里那段原始值，可能什么都不是。
+ * @returns 空数组表示形状过得去；版本不对就当场返回（后面的字段无从判起）。
+ */
 export declare function declarationProblemsOf(subject: string, raw: unknown): readonly string[];
+/**
+ * 读一份清单的结果：要么带着规整过的声明与 manifest，要么只带一串问题。
+ */
 export interface DeclarationRead {
     readonly declaration?: UnitDeclaration;
     readonly manifest?: UnitManifest;
     readonly problems: readonly string[];
 }
+/**
+ * 读一份清单：先查形状，过了再把声明规整成 manifest。
+ * @param subject 报错时用的主语。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 有问题时只有 problems；没问题时 declaration 与 manifest 都给，manifest 里的字符串已 trim。
+ */
 export declare function readDeclaration(subject: string, raw: unknown): DeclarationRead;

package/dist/api/unit-declaration.js

@@ -1,5 +1,14 @@
+/**
+ * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
+ */
 export const WORKBENCH_API_VERSION = 1;
+/**
+ * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
+ */
 export const SUPPORTED_API_VERSIONS = [WORKBENCH_API_VERSION];
+/**
+ * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ */
 export const DECLARATION_KEYS = [
     'apiVersion',
     'unit',
@@ -8,6 +17,9 @@ export const DECLARATION_KEYS = [
     'host',
     'env',
 ];
+/**
+ * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ */
 export const DECLARATION_REQUIRED_KEYS = [
     'apiVersion',
     'unit',
@@ -36,6 +48,12 @@ function stringArrayProblems(at, value) {
         return [`${at} 要是一串字符串，现在是 ${JSON.stringify(value)}`];
     return value.flatMap((item, index) => text(item) === '' ? [`${at}[${index}] 不是非空字符串：${JSON.stringify(item)}`] : []);
 }
+/**
+ * 查清单里 dsh.workbench 那一段的形状，回一串给人看的问题（中文，带字段路径）。
+ * @param subject 报错时用的主语，一般是包名。
+ * @param raw 清单里那段原始值，可能什么都不是。
+ * @returns 空数组表示形状过得去；版本不对就当场返回（后面的字段无从判起）。
+ */
 export function declarationProblemsOf(subject, raw) {
     if (!isRecord(raw))
         return [`${subject}: dsh.workbench 不是一个对象 —— ${JSON.stringify(raw)}`];
@@ -158,6 +176,12 @@ export function declarationProblemsOf(subject, raw) {
     }
     return problems;
 }
+/**
+ * 读一份清单：先查形状，过了再把声明规整成 manifest。
+ * @param subject 报错时用的主语。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 有问题时只有 problems；没问题时 declaration 与 manifest 都给，manifest 里的字符串已 trim。
+ */
 export function readDeclaration(subject, raw) {
     const problems = declarationProblemsOf(subject, raw);
     if (problems.length > 0)

package/dist/api/unit.d.ts

@@ -1,15 +1,27 @@
+/**
+ * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
+ */
 export interface UnitCard {
     readonly titleKey: string;
     readonly order: number;
 }
+/**
+ * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ */
 export interface UnitTool {
     readonly name: string;
     readonly writes: boolean;
 }
+/**
+ * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
+ */
 export interface UnitHostNeeds {
     readonly inject: readonly string[];
     readonly optional?: readonly string[];
 }
+/**
+ * 一个 opencli 插件的来源三选一（git / 本地 / npm）；npm 那支的安装源先看 registryEnv 那个环境变量，没设才用 registryDefault。
+ */
 export type PluginSource = {
     readonly kind: 'git';
     readonly url: string;
@@ -22,11 +34,17 @@ export type PluginSource = {
     readonly registryEnv: string;
     readonly registryDefault?: string;
 };
+/**
+ * 模块要的一个 opencli 插件：名字、它得提供的命令，以及装它的来源（没写就是不代装）。
+ */
 export interface UnitPluginNeed {
     readonly name: string;
     readonly commands?: readonly string[];
     readonly installSource?: PluginSource;
 }
+/**
+ * 模块要的一个共用库：名字、期望范围与它为什么要这个版本（purpose 会进申报文案）。
+ */
 export interface UnitLibNeed {
     readonly name: string;
     readonly version?: string | undefined;
@@ -34,15 +52,24 @@ export interface UnitLibNeed {
     readonly registryDefault: string;
     readonly purpose: string;
 }
+/**
+ * 模块的整份环境需要：一条自检命令，加上插件与共用库两张表。
+ */
 export interface UnitEnvNeeds {
     readonly command?: string;
     readonly plugins?: readonly UnitPluginNeed[];
     readonly libs?: readonly UnitLibNeed[];
 }
+/**
+ * 已装插件与源上最新版那一对，用来判该不该提示升级；latest 缺省表示还没查到。
+ */
 export interface PluginRelease {
     readonly installed: string;
     readonly latest?: string;
 }
+/**
+ * 装配期用的模块清单：单元 id、卡片、工具与宿主 / 环境需要，比声明少一层协议包装。
+ */
 export interface UnitManifest {
     readonly id: string;
     readonly card: UnitCard | null;
@@ -50,4 +77,9 @@ export interface UnitManifest {
     readonly host: UnitHostNeeds;
     readonly env?: UnitEnvNeeds;
 }
+/**
+ * 判这个模块要不要往外装东西。
+ * @param manifest 模块清单。
+ * @returns 插件与共用库两张表都空时给 false。
+ */
 export declare function hasEnvSupply(manifest: UnitManifest): boolean;

package/dist/api/unit.js

@@ -1,3 +1,8 @@
+/**
+ * 判这个模块要不要往外装东西。
+ * @param manifest 模块清单。
+ * @returns 插件与共用库两张表都空时给 false。
+ */
 export function hasEnvSupply(manifest) {
     return (manifest.env?.plugins ?? []).length > 0 || (manifest.env?.libs ?? []).length > 0;
 }

package/dist/api/workbench-client.d.ts

@@ -1,3 +1,6 @@
+/**
+ * 宿主读口 / 写口回的错误：code 给判据分档，message 给人看，helpUrl 有就去点。
+ */
 export interface ApiError {
     readonly code: string;
     readonly message: string;
@@ -5,15 +8,37 @@ export interface ApiError {
     readonly hint?: string;
     readonly helpUrl?: string;
 }
+/**
+ * 读口的统一响应：成了把载荷摊平在顶层，没成只有一条 ApiError。
+ */
 export type ApiResponse<T> = ({
     readonly ok: true;
 } & T) | {
     readonly ok: false;
     readonly error: ApiError;
 };
+/**
+ * GET 的查询参数：值为 undefined 的键直接丢掉，不进 URL。
+ */
 export type Query = Record<string, string | number | boolean | undefined>;
+/**
+ * GET 的可选项；目前只有中止信号。
+ */
 export interface ApiGetOptions {
     readonly signal?: AbortSignal | undefined;
 }
+/**
+ * 打一条宿主读口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param query 查询参数，undefined 的值不序列化。
+ * @param options 中止信号等。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛，调用点要接住。
+ */
 export declare function apiGet<T>(route: string, query?: Query, options?: ApiGetOptions): Promise<ApiResponse<T>>;
+/**
+ * 打一条宿主写口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param body 请求体，按 JSON 序列化。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛。
+ */
 export declare function apiPost<T>(route: string, body: Record<string, unknown>): Promise<ApiResponse<T>>;

package/dist/api/workbench-client.js

@@ -1,4 +1,11 @@
 import { API_PREFIX } from '../config/constants.js';
+/**
+ * 打一条宿主读口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param query 查询参数，undefined 的值不序列化。
+ * @param options 中止信号等。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛，调用点要接住。
+ */
 export async function apiGet(route, query = {}, options = {}) {
     const { signal } = options;
     const search = new URLSearchParams();
@@ -20,6 +27,12 @@ export async function apiGet(route, query = {}, options = {}) {
     }
     return (await response.json());
 }
+/**
+ * 打一条宿主写口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param body 请求体，按 JSON 序列化。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛。
+ */
 export async function apiPost(route, body) {
     const response = await fetch(`${API_PREFIX}/${route}`, {
         method: 'POST',

package/dist/api/workbench-contract.d.ts

@@ -1,5 +1,11 @@
 import type { PluginRelease } from '../api/unit.js';
+/**
+ * 供给动作的那几档（装 / 升 / 卸，模块、共用依赖与插件各一套）；写口按它分派。
+ */
 export type ProvisionAction = 'install' | 'update' | 'uninstall' | 'update-dependency' | 'install-bundle' | 'update-bundle' | 'remove-bundle' | 'cancel-install' | 'update-plugin' | 'uninstall-plugin' | 'update-workbench';
+/**
+ * 宿主报的一个 opencli 插件此刻的状态：装没装、缺哪些命令、该不该升，以及怎么升。
+ */
 export interface PluginStatePayload {
     readonly name: string;
     readonly status: 'ok' | 'outdated' | 'missing';
@@ -8,6 +14,9 @@ export interface PluginStatePayload {
     readonly command?: string;
     readonly release?: PluginRelease;
 }
+/**
+ * 宿主对「这个单元现在能不能用」的那份读数：状态、缺的命令与插件、修复动作和供给细节。
+ */
 export interface CapabilityPayload {
     readonly unit: string;
     readonly status: 'ok' | 'failed' | 'missing-commands' | 'missing-plugin' | 'unchecked';
@@ -22,6 +31,9 @@ export interface CapabilityPayload {
     readonly install?: 'ready' | 'not-declared' | 'env-missing' | 'malformed';
     readonly libs?: readonly LibStatePayload[];
 }
+/**
+ * 宿主报的一个共用库此刻的状态（装没装、版本对不对）与它为什么要这个版本。
+ */
 export interface LibStatePayload {
     readonly name: string;
     readonly purpose: string;

package/dist/components/Activity.d.ts

@@ -1,17 +1,40 @@
 import type { ReactNode } from '../lib/react.js';
 import './Activity.css';
+/**
+ * `ActivityBlock` 的契约：块头与块内容。
+ */
 export interface ActivityBlockProps {
     readonly head?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }
+/**
+ * "它做过什么"那一块：上面一行块头、下面一列活动行，卡里放时间线就用它。
+ * @param props.head - 块头（如"最近 10 次"）；不给不画那一行。
+ * @param props.children - 块内容，通常是一串 `ActivityLine`。
+ * @returns 一个 div。
+ */
 export declare function ActivityBlock({ head, children }: ActivityBlockProps): JSX.Element;
+/**
+ * `ActivityLine` 的契约：状态点、正文、时间与行尾动作。
+ */
 export interface ActivityLineProps {
     readonly dot?: ReactNode | undefined;
     readonly text: ReactNode;
     readonly at?: ReactNode | undefined;
     readonly actions?: ReactNode | undefined;
 }
+/**
+ * 一条活动：状态点 + 正文 + 时间，行尾可挂动作；时间一律用它，别自己拼。
+ * @param props.dot - 行首那枚状态点；不给就只留正文。
+ * @param props.text - 这一条干了什么。
+ * @param props.at - 时间那一格（相对时间文本）；不给不画。
+ * @param props.actions - 行尾动作，通常是一两颗 `ActivityAction`；不给不画。
+ * @returns 一行。
+ */
 export declare function ActivityLine({ dot, text, at, actions }: ActivityLineProps): JSX.Element;
+/**
+ * `ActivityAction` 的契约：一颗图标钮、一个外链，或一个失败态。
+ */
 export interface ActivityActionProps {
     readonly label: string;
     readonly hint?: string | undefined;
@@ -20,4 +43,14 @@ export interface ActivityActionProps {
     readonly onClick?: (() => void) | undefined;
     readonly failed?: boolean | undefined;
 }
+/**
+ * 活动行尾那颗动作：给 `href` 就是外链，否则是图标钮并带上 tooltip。
+ * @param props.label - 读屏名，也是 `hint` 不给时的 tooltip 文案。
+ * @param props.hint - tooltip 上那句更细的说明；不给退化成 `label`。
+ * @param props.icon - 那颗图标。
+ * @param props.href - 给了就渲染成新窗口外链；与 `onClick` 同时给时以它为准。
+ * @param props.onClick - 图标钮的点击回调。
+ * @param props.failed - 上一次动作失败了：钮换成危险色（默认 false）。
+ * @returns 一个 `<a>` 或一颗 `Button`。
+ */
 export declare function ActivityAction({ label, hint, icon, href, onClick, failed }: ActivityActionProps): JSX.Element;