@dsh-workbench/shared 0.3.4 → 0.3.5

package/dist/lib/blocker-action.js

@@ -1,6 +1,19 @@
+/**
+ * 这颗钮此刻该不该按成等待态：这一轮忙还没收，或有一支正在跑。
+ * @param busy - 这一轮忙是不是还在。
+ * @param running - 正在跑的那一支的 label；没有就给 `null`。
+ * @returns 该等待给 `true`，否则 `false`。
+ */
 export function blockerPending(busy, running) {
     return busy || running !== null;
 }
+/**
+ * 这颗钮此刻该显示什么字：正在重试说「重试中…」，正在跑的那一支说「修复中…」，刚复制过的说「已复制」，其余原样。
+ * @param action - 这颗钮的形状（行为 + 平时文案）。
+ * @param state - 此刻的运行态。
+ * @param t - i18n 取词函数。
+ * @returns 要显示的文案；三种临时态都不成立时就是 `action.label`。
+ */
 export function blockerActionLabel(action, state, t) {
     if (action.kind === 'retry' && state.retrying)
         return t('blocker.retry.running');

package/dist/lib/board-fact.d.ts

@@ -1,5 +1,14 @@
+/**
+ * 椅面（右栏那块画板）此刻归属哪一类：`workshop` 本工坊、`other` 别家、`hidden` 没画出来、`unknown` 探不到。
+ */
 export type BoardFactState = 'workshop' | 'other' | 'hidden' | 'unknown';
+/**
+ * 左栏底部「调试」那条状态要说的档位：`ok` 在板上、`off-workspace` 切去了别的项目、`panel-closed` 面板没开、`other-board` 画的是别家的板、`unknown` 探不到。
+ */
 export type BoardSituation = 'ok' | 'off-workspace' | 'panel-closed' | 'other-board' | 'unknown';
+/**
+ * 一次页面探针的读数：外壳在不在、探的是哪个工作区、右栏开没开、板上挂的路径、椅面画出来没有。
+ */
 export interface BoardProbe {
     readonly workbench: boolean;
     readonly where: string;
@@ -8,6 +17,24 @@ export interface BoardProbe {
     readonly open: boolean;
     readonly drawn: boolean;
 }
+/**
+ * 判一个路径落不落在这个工作区里（按路径前缀比，不是字符串包含）。
+ * @param root - 工作区根路径。
+ * @param target - 要判的路径。
+ * @returns 同一个路径或在其下给 `true`；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
+ */
 export declare function insideWorkshop(root: string, target: string): boolean;
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
 export declare function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFactState;
+/**
+ * 把探针读数归成左栏那句人话的档位。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 一律 `unknown`。
+ * @returns 椅面画着 → 本板 `ok` / 别板 `other-board`；没画着 → 页面已走 `off-workspace`，否则 `panel-closed`。
+ */
 export declare function boardSituation(probe: BoardProbe, workshop: string | null): BoardSituation;

package/dist/lib/board-fact.js

@@ -1,9 +1,21 @@
+/**
+ * 判一个路径落不落在这个工作区里（按路径前缀比，不是字符串包含）。
+ * @param root - 工作区根路径。
+ * @param target - 要判的路径。
+ * @returns 同一个路径或在其下给 `true`；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
+ */
 export function insideWorkshop(root, target) {
     if (target === root)
         return true;
     const base = root.endsWith('/') ? root : `${root}/`;
     return target.startsWith(base);
 }
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
 export function boardFactOf(probe, workshop) {
     if (!probe.workbench)
         return 'unknown';
@@ -13,6 +25,12 @@ export function boardFactOf(probe, workshop) {
         return 'unknown';
     return insideWorkshop(workshop, probe.board) ? 'workshop' : 'other';
 }
+/**
+ * 把探针读数归成左栏那句人话的档位。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 一律 `unknown`。
+ * @returns 椅面画着 → 本板 `ok` / 别板 `other-board`；没画着 → 页面已走 `off-workspace`，否则 `panel-closed`。
+ */
 export function boardSituation(probe, workshop) {
     if (!probe.workbench || workshop === null)
         return 'unknown';

package/dist/lib/busy.d.ts

@@ -1,5 +1,15 @@
+/**
+ * 忙态按下限收尾的判据结果：还该不该显示（`visible`），以及还要按住多少毫秒（`releaseInMs`，0 = 立刻可收）。
+ */
 export interface BusyHold {
     readonly visible: boolean;
     readonly releaseInMs: number;
 }
+/**
+ * 按「至少显示 floorMs」算这一轮忙此刻该不该收：没到下限就继续显示，并给出剩余时长供调用方起定时器。
+ * @param since - 这一轮忙开始的时间戳；`null`（没开过这一轮）一律不显示。
+ * @param now - 当前时间戳。
+ * @param floorMs - 至少显示的时长（毫秒）。
+ * @returns 还该不该显示 + 剩余毫秒；到点或已过下限给不显示，时钟倒退按「刚开头」算（剩余 = 下限，不给负数）。
+ */
 export declare function holdBusy(since: number | null, now: number, floorMs: number): BusyHold;

package/dist/lib/busy.js

@@ -1,3 +1,10 @@
+/**
+ * 按「至少显示 floorMs」算这一轮忙此刻该不该收：没到下限就继续显示，并给出剩余时长供调用方起定时器。
+ * @param since - 这一轮忙开始的时间戳；`null`（没开过这一轮）一律不显示。
+ * @param now - 当前时间戳。
+ * @param floorMs - 至少显示的时长（毫秒）。
+ * @returns 还该不该显示 + 剩余毫秒；到点或已过下限给不显示，时钟倒退按「刚开头」算（剩余 = 下限，不给负数）。
+ */
 export function holdBusy(since, now, floorMs) {
     if (since === null)
         return { visible: false, releaseInMs: 0 };

package/dist/lib/diy-debug.d.ts

@@ -1,26 +1,54 @@
+/**
+ * 调试约定的两个相位：`debugging` 正占着用户的屏，`paused` 已暂停但仍持着约定。
+ */
 export type DebugPhase = 'debugging' | 'paused';
+/**
+ * 调试约定收得下的三个人话动作：暂停 / 继续 / 结束。
+ */
 export type DebugIntent = 'pause' | 'resume' | 'stop';
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
 export declare function parseDebugIntent(value: unknown): DebugIntent | null;
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export declare const DEBUG_STALE_MS: number;
+/**
+ * 一份活着的调试约定：相位 + 谁的会话 + 哪个工作区 / 板 / 单元 + 起于何时（`at` 是最后一次动作）。
+ */
 export interface DebugState {
     readonly phase: DebugPhase;
     readonly sessionId: string;
-    readonly workspace: string;
+    readonly workspacePath: string;
+    readonly title: string;
     readonly board: string;
     readonly unit: string;
     readonly name: string;
     readonly startedAt: number;
     readonly at: number;
 }
+/**
+ * 建立约定要交的那几件：会话、工作区、板、单元、名字，以及此刻的时间戳。
+ */
 export interface DebugPact {
     readonly sessionId: string;
-    readonly workspace: string;
+    readonly workspacePath: string;
+    readonly title: string;
     readonly board: string;
     readonly unit: string;
     readonly name: string;
     readonly now: number;
 }
+/**
+ * 约定被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已暂停 / 已在调试。
+ */
 export type DebugRefusal = 'already-held' | 'held-by-other' | 'not-owner' | 'none' | 'already-paused' | 'already-debugging';
+/**
+ * 一次约定动作的结果：成功带新状态，失败带拒绝码。
+ */
 export type DebugMove = {
     readonly ok: true;
     readonly state: DebugState;
@@ -28,6 +56,9 @@ export type DebugMove = {
     readonly ok: false;
     readonly code: DebugRefusal;
 };
+/**
+ * 调试约定的存取口（外壳持有一份）：`live` 取当前有效的约定，`begin` / `pause` / `resume` / `stop` 推相位。
+ */
 export interface DebugStore {
     live(now: number): DebugState | null;
     begin(pact: DebugPact): DebugMove;
@@ -36,5 +67,14 @@ export interface DebugStore {
     stop(sessionId: string, now: number): DebugMove;
     settle?(): Promise<void>;
 }
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
 export declare function createDebugStore(): DebugStore;
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
 export declare function debugOwnerText(state: DebugState): string;

package/dist/lib/diy-debug.js

@@ -1,6 +1,14 @@
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
 export function parseDebugIntent(value) {
     return value === 'pause' || value === 'resume' || value === 'stop' ? value : null;
 }
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export const DEBUG_STALE_MS = 4 * 60 * 60 * 1000;
 function alive(state, now) {
     if (state === null)
@@ -13,6 +21,10 @@ function ownerOf(state, sessionId, now) {
         return 'none';
     return held.sessionId === sessionId ? held : 'not-owner';
 }
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
 export function createDebugStore() {
     let held = null;
     const live = (now) => alive(held, now);
@@ -26,7 +38,8 @@ export function createDebugStore() {
             const state = {
                 phase: 'debugging',
                 sessionId: pact.sessionId,
-                workspace: pact.workspace,
+                workspacePath: pact.workspacePath,
+                title: pact.title,
                 board: pact.board,
                 unit: pact.unit,
                 name: pact.name,
@@ -65,6 +78,11 @@ export function createDebugStore() {
         },
     };
 }
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
 export function debugOwnerText(state) {
     return `会话 ${state.sessionId}（自 ${new Date(state.startedAt).toISOString().slice(11, 19)}Z 起在调试 ${state.unit}）`;
 }

package/dist/lib/diy-record.d.ts

@@ -1,9 +1,21 @@
+/**
+ * 录制交接的三个相位：`armed` 等用户在外站页面上动手，`recording` 正在录，`finished` 录完待取。
+ */
 export type RecordPhase = 'armed' | 'recording' | 'finished';
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export declare const RECORD_STALE_MS: number;
+/**
+ * 这次录制要找的那一次写：HTTP 方法 + URL 里必须含的一段（不填就是只认方法）。
+ */
 export interface RecordExpect {
     readonly method: string;
     readonly urlContains: string;
 }
+/**
+ * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 + 落盘文件 + 三个时间戳。
+ */
 export interface RecordState {
     readonly phase: RecordPhase;
     readonly sessionId: string;
@@ -20,6 +32,9 @@ export interface RecordState {
     readonly t1: number | null;
     readonly at: number;
 }
+/**
+ * 开一次录制要交的那几件：会话、工作区、单元、名字、页面 URL 与标题、动作名、期望、落盘文件，以及此刻时间。
+ */
 export interface RecordPact {
     readonly sessionId: string;
     readonly workspace: string;
@@ -32,7 +47,13 @@ export interface RecordPact {
     readonly captureFile: string;
     readonly now: number;
 }
+/**
+ * 录制被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已在录 / 还没 arm / 不在录 / 还没录完。
+ */
 export type RecordRefusal = 'already-held' | 'held-by-other' | 'not-owner' | 'none' | 'already-recording' | 'not-armed' | 'not-recording' | 'not-finished';
+/**
+ * 一次录制动作的结果：成功带新状态，失败带拒绝码。
+ */
 export type RecordMove = {
     readonly ok: true;
     readonly state: RecordState;
@@ -40,8 +61,19 @@ export type RecordMove = {
     readonly ok: false;
     readonly code: RecordRefusal;
 };
+/**
+ * 录制约定收得下的三个人话动作：看看进度 / 停手 / 结束并取回。
+ */
 export type RecordIntent = 'peek' | 'halt' | 'stop';
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
 export declare function parseRecordIntent(raw: unknown): RecordIntent | null;
+/**
+ * 录制约定的存取口（外壳持有一份）：相位随 `begin → started → finished` 推进，`release` 是收尾时放掉浏览器那一跳。
+ */
 export interface RecordStore {
     readonly release?: ((state: RecordState) => Promise<{
         readonly tab: boolean;
@@ -53,5 +85,14 @@ export interface RecordStore {
     finished(sessionId: string, at: number, now: number): RecordMove;
     stop(sessionId: string, now: number): RecordMove;
 }
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
 export declare function createRecordStore(): RecordStore;
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
 export declare function recordOwnerText(state: RecordState): string;

package/dist/lib/diy-record.js

@@ -1,4 +1,12 @@
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export const RECORD_STALE_MS = 15 * 60 * 1000;
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
 export function parseRecordIntent(raw) {
     return raw === 'peek' || raw === 'halt' || raw === 'stop' ? raw : null;
 }
@@ -13,6 +21,10 @@ function ownerOf(state, sessionId, now) {
         return 'none';
     return held.sessionId === sessionId ? held : 'not-owner';
 }
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
 export function createRecordStore() {
     let held = null;
     const live = (now) => alive(held, now);
@@ -73,6 +85,11 @@ export function createRecordStore() {
         },
     };
 }
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
 export function recordOwnerText(state) {
     const at = new Date(state.startedAt).toISOString().slice(11, 19);
     return `会话 ${state.sessionId}（自 ${at}Z 起在录 ${state.unit} 的「${state.action}」）`;

package/dist/lib/form-problem.d.ts

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

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';