@xiaoso/dsh-workflow-lite 0.0.0-stage → 0.1.0

package/lib/types/client/model/pathSample.d.ts

@@ -0,0 +1,26 @@
+/**
+ * dsh-workflow-lite — 沿一条 SVG 路径等距取点（纯计算，不碰 DOM）。
+ *
+ * 光带（FlowStreaks）每次线变了都要沿线重新取点；拖卡片时线每帧都在变。以前是把路径塞进一个
+ * 隐形的 `<path>` 再调 `getTotalLength` / `getPointAtLength`，每次都要浏览器重新解析、量一遍，
+ * 是拖动时主线程上最大的开销之一。这里直接按画布自己生成的路径算：把曲线压成细折线，按弧长取点。
+ *
+ * 只认画布会生成的绝对坐标命令：`M` `L` `H` `V` `Q` `C` `Z`（React Flow 的贝塞尔用逗号分隔，也认）。
+ * 碰到别的命令返回 `null`，调用方自己退回 DOM 测量。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/pathSample
+ */
+export interface MeasuredPath {
+    /** 整条路径的长度。 */
+    length: number;
+    /** 从起点到终点等距取 `count` 个点（含两头），每个点带它离起点的弧长。 */
+    sample(count: number): {
+        x: number;
+        y: number;
+        at: number;
+    }[];
+}
+/** 把路径压成折线（相邻的重复点去掉）。不认识的命令 → `null`。 */
+export declare function flattenPath(d: string): [number, number][] | null;
+/** 量一条路径。路径为空、长度为零或认不出来时返回 `null`。 */
+export declare function measurePath(d: string): MeasuredPath | null;

package/lib/types/client/model/route.d.ts

@@ -0,0 +1,121 @@
+/**
+ * dsh-workflow-lite — 读写线挂在哪两个连接点上、怎么走。
+ *
+ * 画布的版式语法是「左右走流程，上下走文件」：步骤左右两侧只接步骤之间的线，读写线一律挂在
+ * 步骤的上下边。文件卡和步骤卡一样「左进右出」：左边的空心圈接写入，右边的实心点拖出去是读取。
+ * 每条线**都落在一个真实的连接点上**（点画在哪，线就接在哪），只是按两张卡当下的位置挑用哪一个：
+ * - 写：文件在下方 = 步骤底边 `file` → 文件左边 `in`；文件在上方 = 步骤上边 `fileUp` → 文件左边 `in`；
+ * - 读：文件右边 `out` 出发，步骤在上方落到它底边的 `read`，在下方落到上边的 `readTop`。
+ *
+ * 写线是直角折线：从步骤的写点竖着落下（升起）、拐个弯横着进文件卡的左边。一个步骤写的几份文件
+ * 竖着挂在它下面，几条写线共用一根"树干"、各自分叉进自己的文件——像文件树，不会穿过别的卡片。
+ *
+ * 连接点在卡片边上的位置也定在这里（`STEP_SPOTS` / `FILE_SPOTS`），卡片组件照着摆，
+ * 拖线预览照着算，三处永远一致。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/route
+ */
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface Anchor {
+    x: number;
+    y: number;
+    side: Side;
+}
+/** 一个连接点在卡片上的位置：在哪条边上、沿这条边走到几成处。 */
+export interface Spot {
+    side: Side;
+    at: number;
+}
+/** 步骤上挂读写线的连接点（左 `in` / 右 `out` 是流程线的，不在这里）。 */
+export type StepFileHandle = 'file' | 'fileUp' | 'read' | 'readTop';
+/** 文件卡上的连接点：左进（被写）右出（被读）。 */
+export type FileHandle = 'in' | 'out';
+/**
+ * 读点贴着左下角（读的文件多半来自左边的上游，从左边进来不用跨过自己的文件树），
+ * 写点在它右边一点：那是文件树的树干，挂在下面的文件卡往右缩进、左边对着树干。
+ * 上边的写点比底边的再靠右一点：同一列里下面的步骤往上写上面那个步骤的文件时，
+ * 它的树干和上面那个步骤的树干错开，不会连成一根、看着像两个步骤连在了一起。
+ */
+export declare const STEP_SPOTS: Record<StepFileHandle, Spot>;
+export declare const FILE_SPOTS: Record<FileHandle, Spot>;
+/** 写线从写点伸出去多远才拐弯 / 横着进文件卡前留多长。 */
+export declare const WRITE_REACH = 22;
+/** 连接点在画布上的坐标。 */
+export declare function spotOf(rect: Rect, spot: Spot): Anchor;
+/**
+ * 一条读写线挂在哪两个连接点上。
+ * @param kind `'write'` 步骤 → 文件；`'read'` 文件 → 步骤。
+ */
+export declare function routeFileLink(kind: 'write' | 'read', step: Rect, file: Rect): {
+    step: StepFileHandle;
+    file: FileHandle;
+};
+/** 读写线两头的坐标（`from` 是线的起点：写 = 步骤，读 = 文件卡）——拖线预览用。 */
+export declare function fileLinkEnds(kind: 'write' | 'read', step: Rect, file: Rect): {
+    from: Anchor;
+    to: Anchor;
+};
+/**
+ * 写线的折点：从步骤的写点竖着出去，横着从左边进文件卡。
+ *
+ * - 常见的情形（文件挂在步骤下方 / 上方、左边在树干右侧）：一个直角——竖着到文件那一行，横着进去；
+ * - 否则绕一下：先竖着出去一小段，横着走到文件左边外侧，再竖着对齐入口、从左边进去；
+ *   横走的那段若会穿过文件卡，就改从文件卡的另一侧绕过去。
+ *
+ * @param from 步骤上的写点（`side` 是 `bottom` 或 `top`）。
+ * @param to 文件卡左边的入口。
+ * @param fileH 文件卡的高度（绕行时要避开它）。
+ */
+export declare function writePoints(from: Anchor, to: {
+    x: number;
+    y: number;
+}, fileH: number): [number, number][];
+/**
+ * 往右走的流程线：一条三次贝塞尔。出口那头的控制柄拉得比入口那头长——线先横着走出一截、
+ * 走到两列之间的空当里再拐下去（上来），不会斜着擦过出口下面挂着的那串文件卡（它们比步骤卡
+ * 往右多伸出一截）。
+ * @returns `[路径, 标签 x, 标签 y]`（曲线正中）。
+ */
+export declare function flowPath(sx: number, sy: number, tx: number, ty: number): [string, number, number];
+/** 往回走的线：右边那条竖段离出口多远（要让过出口下面那串文件卡多伸出来的一截）。 */
+export declare const LOOP_REACH = 64;
+/**
+ * 往回走的线横着走回来的"走廊"放在哪：从 `from` 往下找第一条横穿 `[x1, x2]` 时不压到任何卡片的 y。
+ * @param boxes 画布上的卡片（含文件卡）。
+ */
+export declare function freeLane(boxes: readonly Rect[], x1: number, x2: number, from: number): number;
+/** 贝塞尔流程线（`flowPath` 的那条）会不会压到哪张卡片（不算两头自己的卡）。 */
+export declare function flowBlocked(boxes: readonly Rect[], sx: number, sy: number, tx: number, ty: number): boolean;
+/**
+ * 横穿 `[x1, x2]` 时不压到任何卡片、又离 `around` 最近的 y（往上往下都找）。
+ * 候选就是 `around` 本身和每张挡路的卡片的上沿之上、下沿之下。
+ */
+export declare function nearestLane(boxes: readonly Rect[], x1: number, x2: number, around: number): number;
+type Point2 = [number, number];
+/** 一条绕开卡片的直角走线：折点（含两头）与代价（长度 + 拐弯）。 */
+export interface OrthoRoute {
+    points: Point2[];
+    cost: number;
+}
+/**
+ * 从 `start` 到 `end` 找一条不压到任何卡片的直角折线：两头都先垂直于所在的边伸出一小段，
+ * 中间最多再拐三次，走在卡片之间的缝里。候选的竖道 / 横道取自附近卡片的四边外侧，
+ * 按"长度 + 拐弯"从便宜到贵逐条检查，第一条走得通的就是答案；一条都走不通返回 `null`。
+ * @param boxes 画布上所有卡片（含两头自己的卡片）。
+ * @param startBox / endBox 两头自己的卡片：伸出去的那一小段本来就贴着它们。
+ */
+export declare function orthoRoute(start: Anchor, end: Anchor, boxes: readonly Rect[], startBox: Rect, endBox: Rect): OrthoRoute | null;
+/** 一串直角折点压没压到哪张卡片（不算 `skip` 里的）。 */
+export declare function pointsBlocked(points: readonly Point2[], boxes: readonly Rect[], skip: readonly Rect[]): boolean;
+/**
+ * React Flow 的贝塞尔（`getBezierPath`，曲率 0.25）压没压到哪张卡片（不算 `skip` 里的）：
+ * 读线平时就用它画，只有压到卡片时才改走直角。
+ */
+export declare function bezierBlocked(from: Anchor, to: Anchor, boxes: readonly Rect[], skip: readonly Rect[]): boolean;
+export {};

package/lib/types/client/model/runDraft.d.ts

@@ -0,0 +1,68 @@
+/**
+ * dsh-workflow-lite — 实例视图里用户攒的状态改动（草稿）。
+ *
+ * 改动不实时落盘：先记成"字段 → 改前 / 改后"的清单，用户确认后一次交给 host（`run/save`）。
+ * 草稿期间状态文件照常刷新：模型改了别的字段，画布跟着变；模型改了用户也改过的**同一个**字段，
+ * 那条就是冲突，让用户选（见 {@link rebase}）。
+ *
+ * 全是纯函数：实例视图只负责把它们接到界面上。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/runDraft
+ */
+import { type EditValue, type NodeStatus, type RunState, type StateEdit } from '../../shared/runState.ts';
+/** 草稿里的一条冲突：用户以为的旧值、用户要的新值、文件里现在的值。 */
+export interface DraftConflict {
+    path: string[];
+    from: EditValue;
+    to: EditValue;
+    disk: EditValue;
+}
+export declare function samePath(a: readonly string[], b: readonly string[]): boolean;
+export declare function sameValue(a: EditValue, b: EditValue): boolean;
+/** 状态里某个字段的值（没有 = `null`）。 */
+export declare function valueAt(state: RunState, path: readonly string[]): EditValue;
+/**
+ * 记一处改动。`base` 是文件里现在的状态：同一个字段第一次改时记下它的值当"改前"；
+ * 改回和"改前"一样就从草稿里撤掉。
+ */
+export declare function setField(draft: readonly StateEdit[], base: RunState, path: readonly string[], to: EditValue): StateEdit[];
+/** 把草稿叠到状态上（画布显示的就是叠完的样子）。 */
+export declare function applyDraft(state: RunState, draft: readonly StateEdit[]): RunState;
+/**
+ * 把一个步骤改成某个状态（连带的字段一起改，见 `statusFields`）。
+ * `base` 是文件里的状态，`now` 是这一刻的时间（ISO 8601）。
+ */
+export declare function setNodeStatus(draft: readonly StateEdit[], base: RunState, id: string, status: NodeStatus, now: string): StateEdit[];
+/**
+ * "重跑这一步"：它和它下游已经做过的步骤一起改回 `pending`。
+ * `downstream` 由调用方按图算好（含它自己）。
+ */
+export declare function rerun(draft: readonly StateEdit[], base: RunState, ids: readonly string[], now: string): StateEdit[];
+/**
+ * 文件刷新之后重新对一遍草稿：
+ * - 文件里已经是用户要的值（模型也这么改了）→ 这条不用再存，撤掉；
+ * - 文件里的值和"改前"对不上 → 冲突；
+ * - 其余照旧。
+ */
+export declare function rebase(draft: readonly StateEdit[], disk: RunState): {
+    draft: StateEdit[];
+    conflicts: DraftConflict[];
+};
+/** 冲突的两种了结：以我的为准（改前换成文件里的值），或用文件里的（撤掉这条）。 */
+export declare function resolve(draft: readonly StateEdit[], conflict: DraftConflict, keep: 'mine' | 'theirs'): StateEdit[];
+/** 改了几处：按对象算（整体一处、每个步骤一处），连带改的字段不另算。 */
+export declare function changeCount(draft: readonly StateEdit[]): number;
+/** 一个步骤在草稿里有没有改动（卡片上挂小圆点）。 */
+export declare function editedNodes(draft: readonly StateEdit[]): Set<string>;
+/**
+ * 草稿存下去时流水会多出来的那几条（每个改过的步骤一条，指定下一步再一条，顺序同 `run/save`），叠在 `state` 后面。
+ * 只给推「最后执行 / 下一步」用：位置看流水先后，不补这几条，草稿里的改动在位置上看不出来。
+ */
+export declare function withDraftLog(state: RunState, draft: readonly StateEdit[]): RunState;
+/** 用户指定的下一步里加上 / 去掉一步（去光了就删掉这个字段）。 */
+export declare function togglePin(pinned: readonly string[], id: string): string[] | null;
+/** 从某个步骤往下（沿步骤之间的线，含回边）能走到的步骤，含它自己。 */
+export declare function downstreamOf(edges: readonly {
+    source: string;
+    target: string;
+}[], steps: ReadonlySet<string>, start: string): string[];

package/lib/types/client/model/runGraph.d.ts

@@ -0,0 +1,15 @@
+/**
+ * dsh-workflow-lite — 实例视图里改图：单独撤回一处改动、哪些步骤不能删。
+ *
+ * 「已改 x 处」的清单按 `shared/graphDiff.ts` 数；这里把清单里的一行还原成改之前的样子
+ * （其余改动不动），交给编辑器整张换上（进撤销历史）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/runGraph
+ */
+import type { GraphChange } from '../../shared/graphDiff.ts';
+import type { RunState } from '../../shared/runState.ts';
+import type { WorkflowDocument } from '../../shared/types.ts';
+/** 把 `doc` 里的这一处改动还原成 `base` 里的样子。 */
+export declare function revertChange(base: WorkflowDocument, doc: WorkflowDocument, change: GraphChange): WorkflowDocument;
+/** 删不得的步骤：执行过的（状态不是待执行，或流水里有它）。不记状态的实例没有限制。 */
+export declare function lockedSteps(state: RunState | null): (id: string) => boolean;

package/lib/types/client/model/runHistory.d.ts

@@ -0,0 +1,40 @@
+/**
+ * dsh-workflow-lite — 实例视图的撤销 / 重做：图的改动和状态的改动排成一条。
+ *
+ * 两边各有自己的撤销栈（图：编辑器状态机；状态：草稿）。这里只记"每一步是哪一边的"，
+ * 撤销时弹出最后一步、交给那一边撤；两边的栈有了变化（新的一步、到上限挤掉最早的、存完 / 放弃后清空），
+ * 用 {@link reconcileOrder} 把这条顺序对齐回去。
+ *
+ * 新的一步之后不能再重做：哪一边有了新的一步，另一边的重做栈也要丢掉（`dropFuture` 告诉调用方丢哪边）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/runHistory
+ */
+export type HistorySide = 'graph' | 'state';
+export declare const HISTORY_SIDES: readonly HistorySide[];
+/** 一边的撤销栈：能撤几步、能重做几步、一共压过几步（只增不减）。 */
+export interface SideHistory {
+    past: number;
+    future: number;
+    seq: number;
+}
+/** 排成一条的顺序：`past` 的最后一项是下一次撤销的那一边，`future` 的最后一项是下一次重做的那一边。 */
+export interface HistoryOrder {
+    past: HistorySide[];
+    future: HistorySide[];
+}
+export declare const EMPTY_ORDER: HistoryOrder;
+/** 两边的栈从 `before` 变成 `after` 之后，对齐这条顺序。 */
+export declare function reconcileOrder(order: HistoryOrder, before: Record<HistorySide, SideHistory>, after: Record<HistorySide, SideHistory>): {
+    order: HistoryOrder;
+    dropFuture: HistorySide[];
+};
+/** 撤一步：弹出最后一步交给那一边（顺序空了但某一边还能撤，就撤那一边）。 */
+export declare function undoStep(order: HistoryOrder, sides: Record<HistorySide, SideHistory>): {
+    order: HistoryOrder;
+    side: HistorySide;
+} | null;
+/** 重做一步：弹出最近撤掉的那一步。 */
+export declare function redoStep(order: HistoryOrder, sides: Record<HistorySide, SideHistory>): {
+    order: HistoryOrder;
+    side: HistorySide;
+} | null;

package/lib/types/client/model/themes.d.ts

@@ -0,0 +1,87 @@
+/**
+ * dsh-workflow-lite — 画布的配色主题：亮色、暗色各四套。
+ *
+ * 亮 / 暗跟着宿主设在 `<html>` 上的 `color-scheme` 走；人只挑「亮的时候用哪套、暗的时候用哪套」
+ * （工作流中心「设置」页）。每套主题给出一份完整的基础色，视图根节点按选中的两套写成
+ * `--wl-l-*`、`--wl-d-*` 两组变量，shell.module.css 再用 `light-dark()` 拼成界面用的 `--wl-*`。
+ * 浅色的「淡」档（选中底、标签底）由基础色按固定比例调出来，这里不重复写。
+ *
+ * 主题不只是换底色：线色（也是光带、图例、线上牌子的颜色）、强调色、步骤图标色、状态色都是一整套。
+ * 除了两套默认和晴白，每套照着一份成熟的配色方案来配：雾蓝 = Nord、林间 = Everforest、墨黑 = Geist 式高对比、
+ * 深海 = Tokyo Night、暖夜 = Gruvbox；保留它们的色相和饱和，只按面板把亮度调到读得清。
+ * 主干线（「总是」）就用强调色，选中框、按钮、主干线、上面跑的光带是同一个颜色，整套主题一个基调。
+ *
+ * 每套都要过同一套检查（tests/client/themes.spec.ts）：三级文字、强调色文字、语义色、
+ * 七种线色、步骤图标色在面板上过 4.5:1，线色在画布上过 3:1，七种线两两的 OKLab 色差不小于 8。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/themes
+ */
+export type ThemeMode = 'light' | 'dark';
+export declare const LIGHT_THEME_IDS: readonly ["paper", "white", "mist", "sage"];
+export declare const DARK_THEME_IDS: readonly ["slate", "ink", "ocean", "umber"];
+export type LightThemeId = (typeof LIGHT_THEME_IDS)[number];
+export type DarkThemeId = (typeof DARK_THEME_IDS)[number];
+export type ThemeId = LightThemeId | DarkThemeId;
+export declare const DEFAULT_LIGHT: LightThemeId;
+export declare const DEFAULT_DARK: DarkThemeId;
+export interface ThemeTokens {
+    /** 面：画布、浮在上面的面板与卡片、输入框底、更深一档的底。 */
+    canvas: string;
+    panel: string;
+    fill: string;
+    fillStrong: string;
+    /** 网格点、悬停底、描边用的墨色（`R G B`），各自配一档透明度（百分数）。 */
+    ink: string;
+    dotAlpha: number;
+    hoverAlpha: number;
+    lineAlpha: number;
+    lineStrongAlpha: number;
+    /** 阴影的颜色（`R G B`）；透明度按亮 / 暗写在 CSS 里。 */
+    shade: string;
+    scrim: string;
+    text: string;
+    text2: string;
+    text3: string;
+    accent: string;
+    accentStrong: string;
+    accentOn: string;
+    accentText: string;
+    danger: string;
+    warn: string;
+    ok: string;
+    /** 七种线：流程线按条件，读写线按读写（见 ui/lines.ts）。 */
+    always: string;
+    pass: string;
+    fail: string;
+    custom: string;
+    produce: string;
+    update: string;
+    read: string;
+    /** 资源卡。 */
+    file: string;
+    fileSurface: string;
+    fileBorder: string;
+    fileTab: string;
+    fileBack: string;
+    /** 步骤图标的色板（shared/appearance.ts 的 STEP_COLORS）。 */
+    cBlue: string;
+    cGreen: string;
+    cAmber: string;
+    cCoral: string;
+    cTeal: string;
+    cPink: string;
+    cOlive: string;
+    cViolet: string;
+    cSlate: string;
+    /** 输入节点（交回答的线）的中性墨色。 */
+    ask: string;
+    tip: string;
+    tipOn: string;
+}
+export declare const THEMES: Record<ThemeId, ThemeTokens>;
+export declare function isLightTheme(id: unknown): id is LightThemeId;
+export declare function isDarkTheme(id: unknown): id is DarkThemeId;
+/** 一套主题写成一组 CSS 变量：亮色档写 `--wl-l-*`，暗色档写 `--wl-d-*`。 */
+export declare function themeVars(mode: ThemeMode, id: ThemeId): Record<string, string>;
+/** 视图根节点的内联样式：亮、暗各一套。 */
+export declare function themeStyle(light: LightThemeId, dark: DarkThemeId): Record<string, string>;

package/lib/types/client/model/time.d.ts

@@ -0,0 +1,7 @@
+/**
+ * dsh-workflow-lite — 时间的显示。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/model/time
+ */
+/** `10-02 14:30`：列表、顶栏、文件信息里的时间。 */
+export declare function shortTime(value: number | string | undefined): string;

package/lib/types/client/rpc.d.ts

@@ -0,0 +1,42 @@
+/**
+ * dsh-workflow-lite — 画布的 typed RPC 调用器。
+ *
+ * 走共享 Connection 的 `/api` 通道（与 host 侧 one-route-per-endpoint 对齐）。
+ *
+ * 这里定义自己的载体接口而不直接用 `ConnectionHandle`：`dsh-client-connection` 的宿主半与
+ * 客户端半各自给 cordis 的 `Context` 声明了 `connection`，两半同进一个 TS 工程时类型冲突。
+ * 所以只按**形状**收窄出要用的那一小块（一个 `rpc.call`），运行时校验、不对就响亮报错。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/rpc
+ */
+import type { ConnectionRpcResult } from '@deepseek-ai/dsh-client-connection';
+import { type WorkflowLiteEndpoint, type WorkflowLiteRpcMap } from '../shared/wire.ts';
+/** 我们真正需要的那一小块 Connection 面。 */
+export interface RpcCarrier {
+    rpc: {
+        call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<ConnectionRpcResult<unknown>>;
+    };
+}
+/** 画布需要的调用面。 */
+export interface WorkflowLiteRpc {
+    call<K extends WorkflowLiteEndpoint>(endpoint: K, args: WorkflowLiteRpcMap[K]['args']): Promise<WorkflowLiteRpcMap[K]['result']>;
+}
+/**
+ * 按形状收窄出一个 RPC 载体。
+ * @param service - `ctx.get('connection')` 拿到的值。
+ * @throws 服务缺失或形状不对——宁可注册时就炸，也不要第一次保存时才炸。
+ */
+export declare function requireRpcCarrier(service: unknown): RpcCarrier;
+/** 端点失败——带 host 给的 `code` 与结构化 `details`（`conflict` 的冲突清单就在里面）。 */
+export declare class WorkflowLiteRpcError extends Error {
+    /** host 的失败码（`not_found` / `invalid_args` / `blocked` / `conflict` / `io_error`）。 */
+    readonly code: string;
+    readonly details: ReadonlyMap<string, unknown>;
+    constructor(code: string, message: string, details: unknown);
+}
+/** 错误的失败码；不是端点失败就给 `undefined`。 */
+export declare function errorCode(error: unknown): string | undefined;
+/** 错误的人话说明。 */
+export declare function errorMessage(error: unknown): string;
+/** 建一个调用器。 */
+export declare function createWorkflowLiteRpc(carrier: RpcCarrier): WorkflowLiteRpc;

package/lib/types/client/ui/AppearancePicker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * dsh-workflow-lite — 选步骤的图标与颜色：点面板标题左边的图标块，弹出色板与图标库。
+ *
+ * 画布上的步骤（属性面板）与「我的步骤」（步骤库详情）共用。选了就改，不用确认；
+ * 「恢复默认」清掉两项，回到按 id 猜的样子。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/AppearancePicker
+ */
+import { type Appearance, type StepColor, type StepIcon } from '../../shared/appearance.ts';
+import type { T } from '../i18n.ts';
+/** `undefined` = 清掉这一项（回到按 id 猜）。 */
+export interface AppearancePatch {
+    icon?: StepIcon | undefined;
+    color?: StepColor | undefined;
+}
+export declare function AppearancePicker(props: {
+    t: T;
+    look: Appearance;
+    /** 存了样子（不是猜的）：才有「恢复默认」。 */
+    custom: boolean;
+    size?: number;
+    onChange(patch: AppearancePatch): void;
+}): React.JSX.Element;

package/lib/types/client/ui/Canvas.d.ts

@@ -0,0 +1,76 @@
+/**
+ * dsh-workflow-lite — 画布：把文档画成步骤卡与连线，把指针操作翻译成编辑动作。
+ *
+ * 文档是事实源，React Flow 只负责渲染与手势：
+ * - 节点对象按"文档里的那个节点 + 选中/语气"缓存，没变的节点保持同一个引用，React Flow
+ *   就不会重建它的内部状态（尺寸、连接点位置）；
+ * - 拖动过程中的坐标只放在本组件的局部状态里，**松手才写进文档**——一次拖拽 = 一次改动、
+ *   一条撤销步、一次保存；
+ * - 选中态由文档这边说了算，单向告诉 React Flow。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/Canvas
+ */
+import '@xyflow/react/dist/base.css';
+import type { GraphAnalysis } from '../../shared/graph.ts';
+import type { NodeStatus } from '../../shared/runState.ts';
+import type { Point, ValidationProblem, WorkflowDocument } from '../../shared/types.ts';
+import type { LocaleKey, T } from '../i18n.ts';
+import { type Edit, type Selection } from '../model/editor.ts';
+import { type StepSource } from '../model/library.ts';
+import type { FocusFile } from './Handoff.tsx';
+/** 「在这里加一个步骤」的请求：屏幕坐标用来摆菜单，画布坐标用来落节点。 */
+export interface AddRequest {
+    client: Point;
+    flow: Point;
+    /** 顺手从这个节点连过来（步骤 = 接一步；资源 = 新步骤读它）。 */
+    from?: string;
+}
+export interface CanvasProps {
+    t: T;
+    doc: WorkflowDocument;
+    analysis: GraphAnalysis;
+    /** 换了一份基线（打开 / 重新加载）就变：据此重新定视口。 */
+    loadKey: string;
+    /** 图名：给了就把人动过的视口记在浏览器里（见 `app/viewport.ts`），下次打开接着看；不写进图文件。 */
+    viewKey?: string;
+    selection: Selection;
+    problems: readonly ValidationProblem[];
+    /** 自动看全图时四周要让开的浮层宽度。 */
+    insets: {
+        left: number;
+        right: number;
+    };
+    onEdit(edit: Edit): void;
+    onSelect(selection: Selection): void;
+    onRequestAdd(request: AddRequest): void;
+    onDropSource(source: StepSource, flow: Point): void;
+    onStarter(): void;
+    /** 正在悬停的资源卡 id：用到它的步骤标出角色，其余的淡下去。 */
+    focusFile: string | null;
+    onFocusFile: FocusFile;
+    /** 工作流实例视图：每张步骤卡挂上运行状态，走过的线亮、没走过的淡。缺省 = 模板编辑。 */
+    run?: RunDecor;
+}
+/** 实例视图给画布的装饰。 */
+export interface RunDecor {
+    /**
+     * 每个步骤此刻的状态（已经叠上草稿）；`mark` = 执行位置：最后执行的、接下来要做的
+     * （见 `shared/runCursor.ts`）。
+     */
+    nodes: Readonly<Record<string, RunNodeDecor>>;
+    /** 走过的线。 */
+    taken: ReadonlySet<string>;
+    /** 资源里每个文件、文件夹在不在（资源 id → 按项；不是路径的项为 `null`）。 */
+    files: Readonly<Record<string, readonly (boolean | null)[]>>;
+    /** 点卡片上的状态小标：在它旁边弹出改状态的菜单。 */
+    onStatus(id: string, anchor: Element): void;
+}
+export interface RunNodeDecor {
+    status: NodeStatus;
+    round: number;
+    edited: boolean;
+    mark?: RunMark | undefined;
+}
+export type RunMark = 'last' | 'next';
+export declare const RUN_TEXT: Record<NodeStatus, LocaleKey>;
+export declare function Canvas(props: CanvasProps): React.JSX.Element;

package/lib/types/client/ui/Confirm.d.ts

@@ -0,0 +1,42 @@
+/**
+ * dsh-workflow-lite — 二次确认：点了删除 / 放弃这类收不回的按钮，在按钮旁边浮出一张小卡问一句。
+ *
+ * 不在原地换出「取消 / 确认」：那样同一行的东西会被挤开，用户正要点的地方跟着挪。
+ * 小卡浮在视图根上（摆位、收起规则同 {@link useFloat}），按钮原地不动、旁边的东西也不动：
+ *
+ * - 触发器在视图右半边就右边对齐，免得卡片离按钮太远；下面放不下翻到上方；
+ * - 再点一下触发器、点别处、滚动、Esc 都等于取消；焦点先落在「取消」上，关掉后回到触发器
+ *   （确认后若触发器在对话框里，交给对话框——触发器多半跟着被删的东西一起没了）；
+ * - 卡片里的按键不往外冒（不会删到画布上选中的步骤）。
+ *
+ * 用法：`const confirm = useConfirm<HTMLButtonElement>()`，触发器挂 `ref={confirm.anchorRef}`、
+ * `onClick={confirm.toggle}`，再在旁边放 `{confirm.render({...})}`。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/Confirm
+ */
+import type { T } from '../i18n.ts';
+export interface ConfirmOptions {
+    t: T;
+    /** 问的那句话：「删除这个实例？」 */
+    title: string;
+    /** 补一句后果（可选）。 */
+    desc?: string;
+    /** 标题下面额外的东西（比如「连同状态文件」勾选框）。 */
+    children?: React.ReactNode;
+    /** 确认按钮上的字：「删除」「放弃」。 */
+    confirmText: string;
+    /** 确认按钮的 `data-testid`；整张卡是 `${testId}-pop`。 */
+    testId?: string;
+    disabled?: boolean;
+    /** 确认按钮是红的（删除、放弃）；`false` = 主色（切换这类收得回来的）。缺省红。 */
+    danger?: boolean;
+    onConfirm(): void;
+}
+export declare function useConfirm<A extends HTMLElement>(): {
+    anchorRef: React.RefObject<A>;
+    open: boolean;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    render(options: ConfirmOptions): React.ReactNode;
+};

package/lib/types/client/ui/DocViewer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * dsh-workflow-lite — 看一份文档的模态框（产出文件、SKILL.md 共用）。
+ *
+ * 标题行：图标、名字、一行元信息，右边「排版 / 源码」（Markdown、HTML 才有）、复制路径、
+ * 用其他程序打开（含在文件管理器中显示）、关闭。正文：Markdown 默认排版，HTML 默认在沙箱框里渲染
+ * （能跑脚本，但是独立的源：碰不到画布、拿不到登录态），其余原样；读不了的只说明原因。
+ * 有说明（`note`）时标题行多一个「说明」开关，点开从右边滑出一栏，不占正文的地方。
+ * 调用方可以在正文前插一段（`lead`），在底部放操作条（`footer`）。
+ * 给了 `edit` 就多一个「编辑」：整块文字在这里改（提示词、摘要这类大段文字都在弹窗里改）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/DocViewer
+ */
+import type { Desktop } from '../app/desktop.ts';
+import type { T } from '../i18n.ts';
+import { type IconName } from './Icon.tsx';
+/** 弹窗里能改的那段文字怎么交出去。 */
+export interface DocEdit {
+    onChange(text: string): void;
+    placeholder?: string;
+    maxLength?: number;
+    testId?: string;
+    /** 一打开就在「编辑」。 */
+    start?: boolean;
+}
+/** 正文是什么：还在读、读不了（说明原因）、读到了一段文字。 */
+export type DocBody = {
+    kind: 'loading';
+} | {
+    kind: 'state';
+    icon: IconName;
+    text: string;
+} | {
+    kind: 'text';
+    text: string;
+    format: 'plain' | 'markdown' | 'html';
+}
+/** 调用方自己画的正文（文件夹里有什么、网址的说明）。 */
+ | {
+    kind: 'node';
+    node: React.ReactNode;
+};
+export declare function DocViewer(props: {
+    t: T;
+    /** 标题（也是对话框的无障碍名）。 */
+    name: string;
+    /** 标题左边的图标块。 */
+    badge: React.ReactNode;
+    /** 标题下面的一行（路径、大小……）。 */
+    meta: React.ReactNode;
+    body: DocBody;
+    /** 「复制路径」复制什么；`null` 时按钮禁用。 */
+    copyPath: string | null;
+    /** 复制按钮的说明（缺省「复制路径」：网址、自定义文字复制的不是路径）。 */
+    copyLabel?: string;
+    /** 「用其他程序打开」打开什么；`null`（文件还不在、没有文件）时不出现。 */
+    openPath: string | null;
+    desktop: Desktop | undefined;
+    testId: string;
+    lead?: React.ReactNode;
+    /** 这一项的说明（产出文件的生成要求、步骤的描述）：收在标题行的「说明」开关里。 */
+    note?: string;
+    footer?: React.ReactNode;
+    className?: string;
+    /** 能改：正文就是这段文字，「编辑」里改了直接交出去。 */
+    edit?: DocEdit;
+    onClose(): void;
+}): React.JSX.Element;

package/lib/types/client/ui/Dock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * dsh-workflow-lite — 左下角的缩放条：缩放、看全图、快捷键说明，加上线条图例
+ * （放不下时收成一个「图例」按钮）。模板编辑与实例视图共用。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/Dock
+ */
+import type { T } from '../i18n.ts';
+export declare function ZoomDock(props: {
+    t: T;
+    keysOpen: boolean;
+    setKeysOpen: (open: boolean) => void;
+    onFit: () => void;
+}): React.JSX.Element;

package/lib/types/client/ui/FileTag.d.ts

@@ -0,0 +1,9 @@
+/**
+ * dsh-workflow-lite — 文件的类型签：印扩展名，按类型配色（Markdown 蓝、代码绿、数据琥珀…）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/ui/FileTag
+ */
+export declare function FileTag(props: {
+    path: string;
+    large?: boolean;
+}): React.JSX.Element;