@dsh-workbench/shared 0.3.3 → 0.3.5

package/dist/lib/form-problem.js

@@ -7,9 +7,19 @@ const FOCUSABLE_SELECTOR = [
     'a[href]',
     '[tabindex]:not([tabindex="-1"])',
 ].join(', ');
+/**
+ * 找 `root` 里第一个带 `[data-wb-problem]` 标记的元素 —— 表单校验失败时，调用方拿它定位「哪一格错了」。
+ * @param root - 要搜的范围（表单容器，或 document）。
+ * @returns 第一个出问题的元素；一个标记都没有就给 `null`。
+ */
 export function firstProblemOf(root) {
     return root.querySelector(PROBLEM_SELECTOR);
 }
+/**
+ * 把第一个出问题的元素滚进视野、并把焦点交给它里面第一个可聚焦控件（输入框 / 按钮 / 链接等）。
+ * @param root - 要搜的范围。
+ * @returns 找到并滚过给 `true`；没有问题给 `false`（不滚、不抢焦点）；元素不可滚或没有可聚焦控件也不报错，只是少做一步。
+ */
 export function revealFirstProblem(root) {
     const problem = firstProblemOf(root);
     if (problem === null)

package/dist/lib/panel-state.d.ts

@@ -1,8 +1,17 @@
+/**
+ * 一张面板卡片取数走到哪一步：`idle` 还没取、`loading` 取着、`ready` 拿到了、`error` 失败了。
+ */
 export type PanelCardPhase = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * 一次取数失败：机器码 + 给人看的一句话。
+ */
 export interface PanelCardError {
     readonly code: string;
     readonly message: string;
 }
+/**
+ * 一张卡片最近一次取数的读数：哪个单元、哪条路由、什么相位、什么时候、失败原因。
+ */
 export interface PanelCardRead {
     readonly unit: string;
     readonly route: string;
@@ -10,12 +19,18 @@ export interface PanelCardRead {
     readonly at: number;
     readonly error?: PanelCardError;
 }
+/**
+ * 一张卡片崩了的读数：单元、原因、时间，以及同一原因连着崩了几次（窗口见 `PANEL_STATE_CRASH_WINDOW_MS`）。
+ */
 export interface PanelCardCrash {
     readonly unit: string;
     readonly reason: string;
     readonly at: number;
     readonly count: number;
 }
+/**
+ * 一个单元此刻的读数：它的卡片、最近一次读成的时间（`okAt`，没成过给 `null`），以及崩了的那一条。
+ */
 export interface PanelUnitReport {
     readonly unit: string;
     readonly at: number;
@@ -23,31 +38,61 @@ export interface PanelUnitReport {
     readonly cards: readonly PanelCardRead[];
     readonly crash?: PanelCardCrash;
 }
+/**
+ * 一个工作区此刻的全量读数（面板按工作区存）：所有单元的读数 + 整块最近动过的时间。
+ */
 export interface PanelWorkspaceReport {
     readonly workspace: string | null;
     readonly at: number;
     readonly units: readonly PanelUnitReport[];
 }
+/**
+ * 客户端往上报的一批卡片读数（`POST` 请求体的形状）。
+ */
 export interface PanelCardsReport {
     readonly workspace: string;
     readonly cards: readonly PanelCardRead[];
 }
+/**
+ * 客户端往上报的一次卡片崩溃（`POST` 请求体的形状）。
+ */
 export interface PanelCrashReport {
     readonly workspace: string;
     readonly unit: string;
     readonly reason: string;
     readonly at: number;
 }
+/**
+ * 面板运行态的留存口（宿主持有一份）：收卡片读数与崩溃，按工作区取快照。
+ */
 export interface PanelStateStore {
     cards(report: PanelCardsReport): void;
     crash(report: PanelCrashReport): void;
     snapshot(workspace: string | null): PanelWorkspaceReport;
 }
+/**
+ * 留存的工作区上限（LRU，满 64 个丢最旧的）。
+ */
 export declare const PANEL_STATE_MAX_UNITS = 64;
+/**
+ * 每个单元留存的卡片上限（按路由 LRU，满 12 张丢最旧的）。
+ */
 export declare const PANEL_STATE_MAX_CARDS = 12;
+/**
+ * 一次上报最多读入的卡片条数（32 条之后的丢掉）。
+ */
 export declare const PANEL_STATE_MAX_REPORTS = 32;
+/**
+ * 同一原因的连续崩溃算进同一次计数的窗口（10 分钟，毫秒）。
+ */
 export declare const PANEL_STATE_CRASH_WINDOW_MS = 600000;
+/**
+ * 上报文本字段的截断长度（2000 字符；workspace / reason / message 共用）。
+ */
 export declare const PANEL_STATE_MAX_TEXT = 2000;
+/**
+ * 上报解析的结果：`ok: true` 带收好的值，`ok: false` 带一句中文原因（直接回给上报方）。
+ */
 export type PanelParse<T> = {
     readonly ok: true;
     readonly value: T;
@@ -55,6 +100,21 @@ export type PanelParse<T> = {
     readonly ok: false;
     readonly message: string;
 };
+/**
+ * 收一批卡片读数上报。
+ * @param payload - `POST` 的请求体。
+ * @returns 至少收到一条能认的卡片才 `ok: true`；请求体不是对象、`workspace` 为空、`cards` 不是数组，
+ *   或一条都认不出（`unit` / `route` / `phase` / `at` 缺一）时 `ok: false` + 中文原因；认不出的单条静默跳过。
+ */
 export declare function parseCardsReport(payload: unknown): PanelParse<PanelCardsReport>;
+/**
+ * 收一次卡片崩溃上报。
+ * @param payload - `POST` 的请求体。
+ * @returns `workspace` / `unit` / `reason` 都不能空，缺一给 `ok: false` + 中文原因；`at` 缺省或不合法时取当前时间。
+ */
 export declare function parseCrashReport(payload: unknown): PanelParse<PanelCrashReport>;
+/**
+ * 造一份面板运行态的留存（进程内存、按工作区分桶，带上面那几条上限的 LRU）。
+ * @returns 留存口：`cards` / `crash` 收上报，`snapshot(workspace)` 取全量；没存过的工作区（含 `null`）给一份空的。
+ */
 export declare function createPanelStateStore(): PanelStateStore;

package/dist/lib/panel-state.js

@@ -1,7 +1,22 @@
+/**
+ * 留存的工作区上限（LRU，满 64 个丢最旧的）。
+ */
 export const PANEL_STATE_MAX_UNITS = 64;
+/**
+ * 每个单元留存的卡片上限（按路由 LRU，满 12 张丢最旧的）。
+ */
 export const PANEL_STATE_MAX_CARDS = 12;
+/**
+ * 一次上报最多读入的卡片条数（32 条之后的丢掉）。
+ */
 export const PANEL_STATE_MAX_REPORTS = 32;
+/**
+ * 同一原因的连续崩溃算进同一次计数的窗口（10 分钟，毫秒）。
+ */
 export const PANEL_STATE_CRASH_WINDOW_MS = 600000;
+/**
+ * 上报文本字段的截断长度（2000 字符；workspace / reason / message 共用）。
+ */
 export const PANEL_STATE_MAX_TEXT = 2000;
 const PHASES = ['idle', 'loading', 'ready', 'error'];
 function asRecord(value) {
@@ -30,6 +45,12 @@ function errorOf(raw) {
         return undefined;
     return { code: code === '' ? 'unknown' : code, message };
 }
+/**
+ * 收一批卡片读数上报。
+ * @param payload - `POST` 的请求体。
+ * @returns 至少收到一条能认的卡片才 `ok: true`；请求体不是对象、`workspace` 为空、`cards` 不是数组，
+ *   或一条都认不出（`unit` / `route` / `phase` / `at` 缺一）时 `ok: false` + 中文原因；认不出的单条静默跳过。
+ */
 export function parseCardsReport(payload) {
     const record = asRecord(payload);
     if (record === undefined)
@@ -58,6 +79,11 @@ export function parseCardsReport(payload) {
         return { ok: false, message: 'cards 里没有一条能认的（unit / route / phase / at 都要有）' };
     return { ok: true, value: { workspace, cards } };
 }
+/**
+ * 收一次卡片崩溃上报。
+ * @param payload - `POST` 的请求体。
+ * @returns `workspace` / `unit` / `reason` 都不能空，缺一给 `ok: false` + 中文原因；`at` 缺省或不合法时取当前时间。
+ */
 export function parseCrashReport(payload) {
     const record = asRecord(payload);
     if (record === undefined)
@@ -73,6 +99,10 @@ export function parseCrashReport(payload) {
         return { ok: false, message: 'reason 不能是空的（没有原因的崩溃没法查）' };
     return { ok: true, value: { workspace, unit, reason, at: atOf(record['at']) ?? Date.now() } };
 }
+/**
+ * 造一份面板运行态的留存（进程内存、按工作区分桶，带上面那几条上限的 LRU）。
+ * @returns 留存口：`cards` / `crash` 收上报，`snapshot(workspace)` 取全量；没存过的工作区（含 `null`）给一份空的。
+ */
 export function createPanelStateStore() {
     const workspaces = new Map();
     function trim(entry, max) {

package/dist/lib/react.d.ts

@@ -1,14 +1,53 @@
 import type * as ReactTypes from 'react';
+/**
+ * React 的 `createElement` 换个短名字再导出 —— 这套代码用 `h(...)` 写元素。
+ */
 export declare const h: typeof ReactTypes.createElement;
+/**
+ * React 的 `Fragment` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const Fragment: ReactTypes.ExoticComponent<ReactTypes.FragmentProps>;
+/**
+ * React 的 `Component` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const Component: typeof ReactTypes.Component;
+/**
+ * React 的 `createContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const createContext: typeof ReactTypes.createContext;
+/**
+ * React 的 `useContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useContext: typeof ReactTypes.useContext;
+/**
+ * React 的 `useState` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useState: typeof ReactTypes.useState;
+/**
+ * React 的 `useEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useEffect: typeof ReactTypes.useEffect;
+/**
+ * React 的 `useLayoutEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useLayoutEffect: typeof ReactTypes.useLayoutEffect;
+/**
+ * React 的 `useMemo` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useMemo: typeof ReactTypes.useMemo;
+/**
+ * React 的 `useCallback` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useCallback: typeof ReactTypes.useCallback;
+/**
+ * React 的 `useRef` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useRef: typeof ReactTypes.useRef;
+/**
+ * React 的 `useSyncExternalStore` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export declare const useSyncExternalStore: typeof ReactTypes.useSyncExternalStore;
+/**
+ * 从 react 借来的三个类型（`ReactNode` / `CSSProperties` / `ChangeEvent`）—— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export type { ReactNode, CSSProperties, ChangeEvent } from 'react';

package/dist/lib/react.js

@@ -1,13 +1,49 @@
 const react = require('react');
+/**
+ * React 的 `createElement` 换个短名字再导出 —— 这套代码用 `h(...)` 写元素。
+ */
 export const h = react.createElement;
+/**
+ * React 的 `Fragment` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Fragment = react.Fragment;
+/**
+ * React 的 `Component` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Component = react.Component;
+/**
+ * React 的 `createContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const createContext = react.createContext;
+/**
+ * React 的 `useContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useContext = react.useContext;
+/**
+ * React 的 `useState` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useState = react.useState;
+/**
+ * React 的 `useEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useEffect = react.useEffect;
+/**
+ * React 的 `useLayoutEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useLayoutEffect = react.useLayoutEffect;
+/**
+ * React 的 `useMemo` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useMemo = react.useMemo;
+/**
+ * React 的 `useCallback` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useCallback = react.useCallback;
+/**
+ * React 的 `useRef` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useRef = react.useRef;
+/**
+ * React 的 `useSyncExternalStore` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useSyncExternalStore = react.useSyncExternalStore;

package/dist/lib/text.d.ts

@@ -1,4 +1,26 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
 export declare function quoteShellArg(value: unknown): string;
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
 export declare function tailLines(text: string | null | undefined, lines?: number): string;
+/**
+ * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @returns 解析出的值（对象 / 数组 / 标量都原样）；空输入或怎么都解析不出给 `undefined`，调用方据此报「输出认不出」。
+ */
 export declare function parseJsonLoose(text: string | null | undefined): unknown;
+/**
+ * 把一段 Markdown 压成一行纯文本摘要：图片剥掉、链接只留可见文字、标记符号压成空格，超长按字符截断。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param limit - 摘要最多多少字符，默认 80。
+ * @returns 单行摘要；没超限原样给，超了截到 `limit` 并补省略号（总长 `limit + 1`；第 `limit` 个字符是空白时会被 `trimEnd` 去掉、略短），空输入给空串。
+ */
 export declare function excerpt(text: string | null | undefined, limit?: number): string;

package/dist/lib/text.js

@@ -1,6 +1,17 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
 export function quoteShellArg(value) {
     return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
 export function tailLines(text, lines = 6) {
     const all = String(text ?? '')
         .trim()
@@ -24,6 +35,11 @@ function candidateStarts(raw) {
     }
     return starts;
 }
+/**
+ * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @returns 解析出的值（对象 / 数组 / 标量都原样）；空输入或怎么都解析不出给 `undefined`，调用方据此报「输出认不出」。
+ */
 export function parseJsonLoose(text) {
     const raw = String(text ?? '').trim();
     if (!raw)
@@ -50,6 +66,12 @@ export function parseJsonLoose(text) {
 const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/g;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const MARKDOWN_MARKS = /[*`_>#]/g;
+/**
+ * 把一段 Markdown 压成一行纯文本摘要：图片剥掉、链接只留可见文字、标记符号压成空格，超长按字符截断。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param limit - 摘要最多多少字符，默认 80。
+ * @returns 单行摘要；没超限原样给，超了截到 `limit` 并补省略号（总长 `limit + 1`；第 `limit` 个字符是空白时会被 `trimEnd` 去掉、略短），空输入给空串。
+ */
 export function excerpt(text, limit = 80) {
     const flat = String(text ?? '')
         .replace(MARKDOWN_IMAGE, ' ')

package/dist/lib/ui.d.ts

@@ -1,13 +1,63 @@
+/**
+ * 拼类名：只留真值、用空格连接（`false` / `null` / `undefined` / 空串都丢掉）。
+ * @param parts - 若干类名或条件值。
+ * @returns 拼好的类字符串；一个真值都没有给空串。
+ */
 export declare function cx(...parts: Array<string | false | null | undefined>): string;
+/**
+ * 时间文案取词：i18n 的 `(key, params) => 文案`；相对时间那几件都从它拿词。
+ */
 export type TimeTranslate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * 相对时间的档位名，对应词表里的 `time.short.*`。
+ */
 export type RelativeTimeUnit = 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+/**
+ * 相对时间的一档：`unit` 是档位，`n` 是这一档的数量（单位随档位，见 `relativeTimeBucket`）。
+ */
 export interface RelativeTimeBucket {
     readonly unit: RelativeTimeUnit;
     readonly n: number;
 }
+/**
+ * 把时间戳按 dsh 的分档切成「刚刚 / N 分钟 / N 小时 / N 天 / N 月 / N 年」—— 30 天进月、365 天进年。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 档位与数量；时间戳或基准不是有限数给 `null`，未来时间钳到「刚刚」（`now` / 0）。
+ */
 export declare function relativeTimeBucket(epochMs: number, now?: number): RelativeTimeBucket | null;
+/**
+ * 行内用的紧凑相对时间（「3 分钟」这种，不带「前」）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 紧凑文案；时间戳非法给空串。
+ */
 export declare function relativeTimeCompact(epochMs: number, t: TimeTranslate, now?: number): string;
+/**
+ * 悬停卡里用的相对时间（「3 分钟前」）；「刚刚」那一档不加「前」。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 带「前」的文案；时间戳非法给空串。
+ */
 export declare function relativeTimeAgo(epochMs: number, t: TimeTranslate, now?: number): string;
+/**
+ * 会话行那一版相对时间：一小时内按分钟、一天内按小时、七天内按天，再久直接给绝对时间（到秒）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @returns 文案；时间戳不是有限数给空串，未来时间落「刚刚」，七天及以上给本地化的年月日时分秒。
+ */
 export declare function relativeTime(epochMs: number, t: TimeTranslate): string;
+/**
+ * 把 `/Users/<用户名>/…` 缩成 `~/…`，免得会话行里全是一样的长前缀。
+ * @param path - 任意值。
+ * @returns 缩好的路径；不在用户主目录下原样返回，不是字符串给空串。
+ */
 export declare function shortenPath(path: unknown): string;
+/**
+ * 解析不带时区的本地时间戳（`YYYY-MM-DD HH:mm:ss`，也接受 `T` 分隔），按本机时区换算。
+ * @param text - 原文；`null` / `undefined` 当空串；首尾空白容忍。
+ * @returns 毫秒时间戳；形态不认识给 `NaN`（调用方据此回退到原始字符串，宁可不换算也不显示错时间）。
+ */
 export declare function parseLocalTimestamp(text: string | null | undefined): number;

package/dist/lib/ui.js

@@ -1,3 +1,8 @@
+/**
+ * 拼类名：只留真值、用空格连接（`false` / `null` / `undefined` / 空串都丢掉）。
+ * @param parts - 若干类名或条件值。
+ * @returns 拼好的类字符串；一个真值都没有给空串。
+ */
 export function cx(...parts) {
     return parts.filter(Boolean).join(' ');
 }
@@ -6,6 +11,12 @@ const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 const MONTH = 30 * DAY;
 const YEAR = 365 * DAY;
+/**
+ * 把时间戳按 dsh 的分档切成「刚刚 / N 分钟 / N 小时 / N 天 / N 月 / N 年」—— 30 天进月、365 天进年。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 档位与数量；时间戳或基准不是有限数给 `null`，未来时间钳到「刚刚」（`now` / 0）。
+ */
 export function relativeTimeBucket(epochMs, now = Date.now()) {
     if (!Number.isFinite(epochMs) || !Number.isFinite(now))
         return null;
@@ -25,10 +36,24 @@ export function relativeTimeBucket(epochMs, now = Date.now()) {
 function bucketLabel(bucket, t) {
     return bucket.unit === 'now' ? t('time.now') : t(`time.short.${bucket.unit}`, { n: bucket.n });
 }
+/**
+ * 行内用的紧凑相对时间（「3 分钟」这种，不带「前」）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 紧凑文案；时间戳非法给空串。
+ */
 export function relativeTimeCompact(epochMs, t, now) {
     const bucket = relativeTimeBucket(epochMs, now);
     return bucket === null ? '' : bucketLabel(bucket, t);
 }
+/**
+ * 悬停卡里用的相对时间（「3 分钟前」）；「刚刚」那一档不加「前」。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 带「前」的文案；时间戳非法给空串。
+ */
 export function relativeTimeAgo(epochMs, t, now) {
     const bucket = relativeTimeBucket(epochMs, now);
     if (bucket === null)
@@ -36,6 +61,12 @@ export function relativeTimeAgo(epochMs, t, now) {
     const label = bucketLabel(bucket, t);
     return bucket.unit === 'now' ? label : t('time.ago', { t: label });
 }
+/**
+ * 会话行那一版相对时间：一小时内按分钟、一天内按小时、七天内按天，再久直接给绝对时间（到秒）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @returns 文案；时间戳不是有限数给空串，未来时间落「刚刚」，七天及以上给本地化的年月日时分秒。
+ */
 export function relativeTime(epochMs, t) {
     if (!Number.isFinite(epochMs))
         return '';
@@ -57,6 +88,11 @@ export function relativeTime(epochMs, t) {
         second: '2-digit',
     });
 }
+/**
+ * 把 `/Users/<用户名>/…` 缩成 `~/…`，免得会话行里全是一样的长前缀。
+ * @param path - 任意值。
+ * @returns 缩好的路径；不在用户主目录下原样返回，不是字符串给空串。
+ */
 export function shortenPath(path) {
     if (typeof path !== 'string')
         return '';
@@ -64,6 +100,11 @@ export function shortenPath(path) {
     return hit === null ? path : path.replace(hit[0], '~');
 }
 const LOCAL_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/;
+/**
+ * 解析不带时区的本地时间戳（`YYYY-MM-DD HH:mm:ss`，也接受 `T` 分隔），按本机时区换算。
+ * @param text - 原文；`null` / `undefined` 当空串；首尾空白容忍。
+ * @returns 毫秒时间戳；形态不认识给 `NaN`（调用方据此回退到原始字符串，宁可不换算也不显示错时间）。
+ */
 export function parseLocalTimestamp(text) {
     const raw = String(text ?? '').trim();
     if (!LOCAL_TIMESTAMP.test(raw))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

package/src/api/blocker-table.ts

@@ -12,6 +12,13 @@ function copyAction(t: Translate, text: string): BlockerAction {
   return { kind: 'copy', label: t('blocker.copy'), text };
 }
 
+/**
+ * 把一次读失败翻成一张卡住态，交给卡片直接渲染。
+ * @param error 读口回的错误；undefined 表示连错误都没拿到（多半是网络断，回「原因未知」）。
+ * @param t 文案函数，只取 blocker.* 命名空间的键。
+ * @param context 判定现场；platform 缺省时标题不带平台名。
+ * @returns 一定有一张卡，actions 至少一颗「重试」。
+ */
 export function blockerOfError(
   error: ApiError | undefined,
   t: Translate,
@@ -103,6 +110,12 @@ export function blockerOfError(
   }
 }
 
+/**
+ * 把宿主回的环境读数翻成卡住态：探针没查过（unchecked）只算提示，不挡卡片。
+ * @param capability 宿主回的单元环境读数。
+ * @param t 文案函数，键都在 env.unit.* / blocker.* 下。
+ * @returns status 为 'ok' 时给 undefined（没有卡住态），其余状态一律给一张。
+ */
 export function blockerOfCapability(capability: CapabilityPayload, t: Translate): ModuleBlocker | undefined {
   if (capability.status === 'ok') return undefined;
 

package/src/api/blocker.ts

@@ -1,3 +1,6 @@
+/**
+ * 卡住时用户能点的那一下（开链接 / 复制命令 / 重试 / 装或升模块）：由判据产出，卡片照原样渲染。
+ */
 export type BlockerAction =
   | {
       readonly kind: 'open-url';
@@ -15,6 +18,9 @@ export type BlockerAction =
     }
   | { readonly kind: 'open-market'; readonly label: string; readonly unit: string };
 
+/**
+ * 一个单元此刻的卡住态：block 顶掉整张卡片，notice 只在角上提示一句；读口与探针产出，卡片消费。
+ */
 export interface ModuleBlocker {
   readonly id: string;
   readonly severity: 'block' | 'notice';

package/src/api/context-ref.ts

@@ -1,5 +1,11 @@
+/**
+ * 引用标记的固定名字；完整标记是 @<这个名字>:<编码文本>，改它等于作废历史会话里已写下的引用。
+ */
 export const CONTEXT_MARKER_NAME = '工作台';
 
+/**
+ * 一条解析后的引用（种类加路径分段）：输入框写标记时产出，跳转与展示时消费。
+ */
 export interface ContextRef {
   readonly kind: string;
   readonly parts: readonly string[];
@@ -9,10 +15,20 @@ const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._
 
 const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
 
+/**
+ * 把引用拼回标记体里的那一段文本（不含 @ 与标记名）。
+ * @param ref 要拼的引用。
+ * @returns 形如 kind:part/part；分段里的 / 不转义，所以分段名本身不能含 /。
+ */
 export function encodeRef(ref: ContextRef): string {
   return `${ref.kind}:${ref.parts.join('/')}`;
 }
 
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
 export function decodeRef(text: string): ContextRef | undefined {
   const at = text.indexOf(':');
   if (at <= 0 || at === text.length - 1) return undefined;
@@ -23,14 +39,29 @@ export function decodeRef(text: string): ContextRef | undefined {
   return { kind, parts };
 }
 
+/**
+ * 拼出 @ 后面那半截（标记名加已编码文本），比较与拼接都用它。
+ * @param encoded encodeRef 的结果。
+ * @returns 形如 工作台:file:src/a.ts。
+ */
 export function markerBody(encoded: string): string {
   return `${CONTEXT_MARKER_NAME}:${encoded}`;
 }
 
+/**
+ * 把一条引用拼成能写进对话文本的完整标记。
+ * @param ref 要标记的引用。
+ * @returns 形如 @工作台:file:src/a.ts 的一段文本。
+ */
 export function buildMarker(ref: ContextRef): string {
   return `@${markerBody(encodeRef(ref))}`;
 }
 
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
 export function parseMarkers(text: string): ContextRef[] {
   const seen = new Set<string>();
   const refs: ContextRef[] = [];