@dsh-workbench/shared 0.3.3 → 0.3.5

package/dist/i18n/zh.d.ts

@@ -1,3 +1,4 @@
+/** 外壳自带的中文词表（命名空间 `workbench`）：`en` 与它逐键对齐，模块那份在它之上合并。 */
 export declare const zh: {
     readonly 'brand.name': "工作台";
     readonly 'toggle.open': "打开侧边栏";
@@ -408,19 +409,33 @@ export declare const zh: {
     readonly 'configSync.noSource': "这台机器上只有工作台这一个 profile，没有可同步的来源";
     readonly 'configSync.emptyProviders': "工作台还没有任何模型供应商 —— 去「配置同步」从某个 profile 把 llm- 那几行搬过来，或自己去「模型」里配。";
     readonly 'configSync.failed': "同步没成功，再试一次。";
-    readonly 'debug.status': "工作台 DIY 开发调试中";
-    readonly 'debug.status.trouble': "工作台 DIY 开发调试异常";
-    readonly 'debug.stalled': "工作台 DIY 调试暂停";
+    readonly 'debug.workspace': "这个工作区";
+    readonly 'debug.status': "「{title}」调试中";
+    readonly 'debug.status.trouble': "调试要你看一眼（{title}）";
+    readonly 'debug.stalled': "调试已暂停（{title}）";
     readonly 'debug.act.pause': "暂停调试";
     readonly 'debug.act.resume': "继续调试";
     readonly 'debug.act.stop': "结束调试";
     readonly 'debug.act.stop.ask': "确认结束";
-    readonly 'debug.card.here.title': "当前工作台 DIY 开发调试中";
+    readonly 'debug.card.here.title': "正在调试「{title}」";
     readonly 'debug.card.here.note': "请勿切换工作区和操作面板";
-    readonly 'debug.card.away.title': "工作台 DIY 开发调试中";
-    readonly 'debug.card.away.note': "请切换到工作台 DIY 工作区";
+    readonly 'debug.card.away.note': "请切回「{title}」那一屏";
     readonly 'debug.card.paused.note': "已暂停";
-    readonly 'debug.card.hidden.note': "请切换到工作台面板";
-    readonly 'debug.back': "回到工坊那一屏";
+    readonly 'debug.card.hidden.note': "请切回工作台面板";
+    readonly 'record.waiting': "取证交接 · 等你出手";
+    readonly 'record.waiting.note': "请在那一页按「开始录制」，做完按「结束录制」（录完不替你切回来）";
+    readonly 'record.recording': "录制中";
+    readonly 'record.recording.note': "做完按「结束录制」；浮条没了按「停」，让 agent 先取再收";
+    readonly 'record.finished': "录制完成";
+    readonly 'record.finished.note': "这一段录完了 —— agent 会自己来取并收工，不用你点";
+    readonly 'record.act.cancel': "取消";
+    readonly 'record.act.halt': "停";
+    readonly 'approval.record.site': "站点";
+    readonly 'approval.record.what': "录制功能";
+    readonly 'approval.record.lands': "落点";
+    readonly 'approval.record.noUrl': "没给站点地址（这次会被当场拒）";
+    readonly 'approval.record.oneAction': "一次操作";
+    readonly 'approval.record.noSwitch': "录完不会替你切回来（左栏底部会亮一条状态）";
 };
+/** 中文词表的键类型：`en` 与模块词表都得覆盖同一批键。 */
 export type WorkbenchMessages = typeof zh;

package/dist/i18n/zh.js

@@ -1,3 +1,4 @@
+/** 外壳自带的中文词表（命名空间 `workbench`）：`en` 与它逐键对齐，模块那份在它之上合并。 */
 export const zh = {
     'brand.name': '工作台',
     'toggle.open': '打开侧边栏',
@@ -408,18 +409,31 @@ export const zh = {
     'configSync.noSource': '这台机器上只有工作台这一个 profile，没有可同步的来源',
     'configSync.emptyProviders': '工作台还没有任何模型供应商 —— 去「配置同步」从某个 profile 把 llm- 那几行搬过来，或自己去「模型」里配。',
     'configSync.failed': '同步没成功，再试一次。',
-    'debug.status': '工作台 DIY 开发调试中',
-    'debug.status.trouble': '工作台 DIY 开发调试异常',
-    'debug.stalled': '工作台 DIY 调试暂停',
+    'debug.workspace': '这个工作区',
+    'debug.status': '「{title}」调试中',
+    'debug.status.trouble': '调试要你看一眼（{title}）',
+    'debug.stalled': '调试已暂停（{title}）',
     'debug.act.pause': '暂停调试',
     'debug.act.resume': '继续调试',
     'debug.act.stop': '结束调试',
     'debug.act.stop.ask': '确认结束',
-    'debug.card.here.title': '当前工作台 DIY 开发调试中',
+    'debug.card.here.title': '正在调试「{title}」',
     'debug.card.here.note': '请勿切换工作区和操作面板',
-    'debug.card.away.title': '工作台 DIY 开发调试中',
-    'debug.card.away.note': '请切换到工作台 DIY 工作区',
+    'debug.card.away.note': '请切回「{title}」那一屏',
     'debug.card.paused.note': '已暂停',
-    'debug.card.hidden.note': '请切换到工作台面板',
-    'debug.back': '回到工坊那一屏',
+    'debug.card.hidden.note': '请切回工作台面板',
+    'record.waiting': '取证交接 · 等你出手',
+    'record.waiting.note': '请在那一页按「开始录制」，做完按「结束录制」（录完不替你切回来）',
+    'record.recording': '录制中',
+    'record.recording.note': '做完按「结束录制」；浮条没了按「停」，让 agent 先取再收',
+    'record.finished': '录制完成',
+    'record.finished.note': '这一段录完了 —— agent 会自己来取并收工，不用你点',
+    'record.act.cancel': '取消',
+    'record.act.halt': '停',
+    'approval.record.site': '站点',
+    'approval.record.what': '录制功能',
+    'approval.record.lands': '落点',
+    'approval.record.noUrl': '没给站点地址（这次会被当场拒）',
+    'approval.record.oneAction': '一次操作',
+    'approval.record.noSwitch': '录完不会替你切回来（左栏底部会亮一条状态）',
 };

package/dist/index.d.ts

@@ -20,8 +20,11 @@ export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
 export * from './components/Field.js';
+export * from './components/Form.js';
 export * from './components/FormActions.js';
+export * from './components/FormNodes.js';
 export * from './components/FormRows.js';
+export * from './components/FormTypes.js';
 export * from './components/Link.js';
 export * from './components/LongTaskRow.js';
 export * from './components/Note.js';
@@ -29,6 +32,7 @@ export * from './components/ResourceStates.js';
 export * from './components/Rows.js';
 export * from './components/SaveBar.js';
 export * from './components/SelectField.js';
+export * from './components/SelectFieldNodes.js';
 export * from './components/SettingsSection.js';
 export * from './components/Spinner.js';
 export * from './components/Stack.js';
@@ -43,10 +47,11 @@ export * from './i18n/index.js';
 export * from './i18n/merge.js';
 export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
-export * from './lib/busy.js';
-export * from './lib/form-problem.js';
 export * from './lib/board-fact.js';
+export * from './lib/busy.js';
 export * from './lib/diy-debug.js';
+export * from './lib/diy-record.js';
+export * from './lib/form-problem.js';
 export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';

package/dist/index.js

@@ -20,8 +20,11 @@ export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
 export * from './components/Field.js';
+export * from './components/Form.js';
 export * from './components/FormActions.js';
+export * from './components/FormNodes.js';
 export * from './components/FormRows.js';
+export * from './components/FormTypes.js';
 export * from './components/Link.js';
 export * from './components/LongTaskRow.js';
 export * from './components/Note.js';
@@ -29,6 +32,7 @@ export * from './components/ResourceStates.js';
 export * from './components/Rows.js';
 export * from './components/SaveBar.js';
 export * from './components/SelectField.js';
+export * from './components/SelectFieldNodes.js';
 export * from './components/SettingsSection.js';
 export * from './components/Spinner.js';
 export * from './components/Stack.js';
@@ -43,10 +47,11 @@ export * from './i18n/index.js';
 export * from './i18n/merge.js';
 export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
-export * from './lib/busy.js';
-export * from './lib/form-problem.js';
 export * from './lib/board-fact.js';
+export * from './lib/busy.js';
 export * from './lib/diy-debug.js';
+export * from './lib/diy-record.js';
+export * from './lib/form-problem.js';
 export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';

package/dist/lib/blocker-action.d.ts

@@ -1,13 +1,35 @@
+/**
+ * 阻断态取词：i18n 的 `(key) => 文案` 那一半；那几颗钮的「重试中…」等临时说法都从它来。
+ */
 export type BlockerLabelTranslate = (key: string) => string;
+/**
+ * 阻断态上一颗钮的形状：`kind` 定行为（`retry` / `copy` 等），`label` 是它平时的文案。
+ */
 export interface BlockerActionShape {
     readonly kind: string;
     readonly label: string;
     readonly text?: string | undefined;
 }
+/**
+ * 这颗钮此刻的运行态：是否正在重试、哪一支正在跑（按 label 认）、刚复制过哪段文本。
+ */
 export interface BlockerLabelState {
     readonly retrying: boolean;
     readonly running: string | null;
     readonly copied: string | null;
 }
+/**
+ * 这颗钮此刻该不该按成等待态：这一轮忙还没收，或有一支正在跑。
+ * @param busy - 这一轮忙是不是还在。
+ * @param running - 正在跑的那一支的 label；没有就给 `null`。
+ * @returns 该等待给 `true`，否则 `false`。
+ */
 export declare function blockerPending(busy: boolean, running: string | null): boolean;
+/**
+ * 这颗钮此刻该显示什么字：正在重试说「重试中…」，正在跑的那一支说「修复中…」，刚复制过的说「已复制」，其余原样。
+ * @param action - 这颗钮的形状（行为 + 平时文案）。
+ * @param state - 此刻的运行态。
+ * @param t - i18n 取词函数。
+ * @returns 要显示的文案；三种临时态都不成立时就是 `action.label`。
+ */
 export declare function blockerActionLabel(action: BlockerActionShape, state: BlockerLabelState, t: BlockerLabelTranslate): string;

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

@@ -0,0 +1,98 @@
+/**
+ * 录制交接的三个相位：`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;
+    readonly workspace: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly action: string;
+    readonly expect: RecordExpect | null;
+    readonly captureFile: string;
+    readonly startedAt: number;
+    readonly t0: number | null;
+    readonly t1: number | null;
+    readonly at: number;
+}
+/**
+ * 开一次录制要交的那几件：会话、工作区、单元、名字、页面 URL 与标题、动作名、期望、落盘文件，以及此刻时间。
+ */
+export interface RecordPact {
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly action: string;
+    readonly expect: RecordExpect | null;
+    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;
+} | {
+    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;
+        readonly capture: boolean;
+    }>) | undefined;
+    live(now: number): RecordState | null;
+    begin(pact: RecordPact): RecordMove;
+    started(sessionId: string, at: number, now: number): RecordMove;
+    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

@@ -0,0 +1,96 @@
+/**
+ * 录制约定的有效期（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;
+}
+function alive(state, now) {
+    if (state === null)
+        return null;
+    return now - state.at <= RECORD_STALE_MS ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+    const held = alive(state, now);
+    if (held === null)
+        return 'none';
+    return held.sessionId === sessionId ? held : 'not-owner';
+}
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
+export function createRecordStore() {
+    let held = null;
+    const live = (now) => alive(held, now);
+    return {
+        live,
+        begin(pact) {
+            const current = alive(held, pact.now);
+            if (current !== null) {
+                return { ok: false, code: current.sessionId === pact.sessionId ? 'already-held' : 'held-by-other' };
+            }
+            const state = {
+                phase: 'armed',
+                sessionId: pact.sessionId,
+                workspace: pact.workspace,
+                unit: pact.unit,
+                name: pact.name,
+                url: pact.url,
+                title: pact.title,
+                action: pact.action,
+                expect: pact.expect,
+                captureFile: pact.captureFile,
+                startedAt: pact.now,
+                t0: null,
+                t1: null,
+                at: pact.now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        started(sessionId, at, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'recording')
+                return { ok: false, code: 'already-recording' };
+            if (found.phase !== 'armed')
+                return { ok: false, code: 'not-armed' };
+            const state = { ...found, phase: 'recording', t0: at, at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        finished(sessionId, at, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase !== 'recording')
+                return { ok: false, code: 'not-recording' };
+            const state = { ...found, phase: 'finished', t1: at, at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        stop(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            held = null;
+            return { ok: true, state: found };
+        },
+    };
+}
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @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;