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

package/lib/types/client/app/addStep.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-workflow-lite — 往图里加东西、复制一个节点：模板编辑与实例视图共用。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/addStep
+ */
+import type { NodeData, Point, WorkflowDocument } from '../../shared/types.ts';
+import type { T } from '../i18n.ts';
+import { type Edit } from '../model/editor.ts';
+import { type StepSource } from '../model/library.ts';
+export interface AddContext {
+    t: T;
+    doc: WorkflowDocument | null;
+    edit(edit: Edit): void;
+    /** 读「我的步骤」里的一个节点模板；读不到回 `null`。 */
+    loadTemplate(name: string): Promise<NodeData | null>;
+}
+/**
+ * 按来源加一个节点：步骤（空白 / 内置 / 我的步骤）接在 `from` 后面；资源从步骤的「＋」加就是这一步写的产出文件；
+ * 输入从步骤的「＋」加就是这一步要的输入。加完的节点接管选中。
+ */
+export declare function addFromSource(ctx: AddContext, source: StepSource, position: Point, from?: string): Promise<void>;
+/** 就地添加菜单从哪儿来：步骤的「＋」、资源卡拖出来的线、输入，或空白处。 */
+export declare function addOrigin(doc: WorkflowDocument | null, from: string | undefined): 'step' | 'resource' | 'input' | 'none';
+/** 复制一个节点的改动（落在原处右下方一点）；节点不在就是 `null`。 */
+export declare function duplicateEdit(doc: WorkflowDocument | null, id: string): Edit | null;

package/lib/types/client/app/desktop.d.ts

@@ -0,0 +1,52 @@
+/**
+ * dsh-workflow-lite — 用系统里的程序打开文件（和 DSH 文档预览右上角那个按钮同一套能力）。
+ *
+ * 借宿主的 Session Remote：`canOpenWorkspacePath`（这台宿主有没有桌面）、
+ * `workspacePathApplications`（这类文件注册了哪些程序、哪个是默认）、`openWorkspacePath`
+ * （用某个程序打开，或在文件管理器里显示）。服务可选：没接上就不显示「用其他程序打开」。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/desktop
+ */
+/** 能打开这份文件的一个程序。 */
+export interface DesktopApp {
+    id: string;
+    name: string;
+    default: boolean;
+    /** PNG / SVG 的 data URL；系统没给图标时为 `null`。 */
+    icon: string | null;
+}
+type RemoteResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+};
+/** `ctx.remote.session` 用到的部分。 */
+export interface SessionRemote {
+    canOpenWorkspacePath(): Promise<RemoteResult<boolean>>;
+    workspacePathApplications(request: {
+        path: string;
+    }, signal?: AbortSignal): Promise<RemoteResult<readonly DesktopApp[]>>;
+    openWorkspacePath(request: {
+        path: string;
+        action?: 'reveal';
+        application?: string;
+    }): Promise<RemoteResult<unknown>>;
+}
+export interface Desktop {
+    /** 宿主能不能把文件交给系统程序（一页只问一次）。 */
+    available(): Promise<boolean>;
+    /** 这份文件能用哪些程序打开；查不到回 `null`。 */
+    applications(path: string, signal: AbortSignal): Promise<readonly DesktopApp[] | null>;
+    /** 用默认程序 / 指定程序打开，或在文件管理器里显示。成功回 `true`。 */
+    open(path: string, how: {
+        reveal: true;
+    } | {
+        application?: string;
+    }): Promise<boolean>;
+}
+export declare function createDesktop(): Desktop & {
+    attach(remote: SessionRemote): void;
+    detach(): void;
+};
+export {};

package/lib/types/client/app/host.d.ts

@@ -0,0 +1,29 @@
+/**
+ * dsh-workflow-lite — 画布看主机：给资源选文件、文件夹、Skill 时列出主机上有什么。
+ *
+ * 都走 RPC（`host/list`、`host/skills`、`host/skill`）。Skill 清单按「会话 + 工作区」记一份，
+ * 一页里只问一次——选 Skill 是顺手的事，不该每点一下都等一趟。看某个 skill 的全文时才去读它。
+ * 顺带捎上桌面能力（用系统程序打开 SKILL.md、在文件管理器里显示）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/host
+ */
+import type { HostListResponse, HostSkillResponse, HostSkillsResponse } from '../../shared/wire.ts';
+import type { WorkflowLiteRpc } from '../rpc.ts';
+import type { Desktop } from './desktop.ts';
+export interface HostAccess {
+    /** 会话的工作区（列目录的起点，相对路径按它解析）；不知道就是 `undefined`。 */
+    cwd: string | undefined;
+    /** 用系统程序打开文件；宿主没有桌面能力时为 `undefined`。 */
+    desktop: Desktop | undefined;
+    /** 列一个目录；不给就是工作区。 */
+    list(path?: string): Promise<HostListResponse>;
+    /** 会话里的 agent 能用的 skill。 */
+    skills(): Promise<HostSkillsResponse>;
+    /** 读一个 skill 的全文。 */
+    skill(name: string): Promise<HostSkillResponse>;
+}
+export declare function createHostAccess(rpc: WorkflowLiteRpc, where: {
+    cwd?: string | undefined;
+    session?: string | undefined;
+    desktop?: Desktop | undefined;
+}): HostAccess;

package/lib/types/client/app/sessions.d.ts

@@ -0,0 +1,117 @@
+/**
+ * dsh-workflow-lite — 会话桥：画布上的「执行」要列出同一工作区的会话、在同一工作区新建会话、
+ * 往选中的会话里发一句话，发完跳过去。
+ *
+ * 都借宿主现成的东西，不自己造：
+ * - 会话列表与新建：Session Controller 的 `sessions.list` / `sessions.create`（和侧栏同一份数据）；
+ *   新建时按 Workspace Controller 找到本会话所在的工作区，新会话归在同一组里；
+ * - 发消息：会话输入框的标准发送流程（`conversation.input.for(会话 ctx)` 的 `setDraft` + `submit`），
+ *   和用户自己敲回车一模一样——会话正忙时按用户的设置排队或插话；
+ * - 跳过去：`uiWorkspace.openSession`（和点侧栏一样）。
+ *
+ * 这些服务都是**可选**的：入口用 `ctx.inject` 的子上下文接上，缺了只是对应的能力用不了，视图照常。
+ * 宿主的类型包不在依赖里，这里只声明用到的那几个成员。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/sessions
+ */
+/** 列表里的一个会话（侧栏那份数据的子集）。 */
+export interface SessionRow {
+    id: string;
+    title: string;
+    cwd?: string;
+    running: boolean;
+    updatedAt: number;
+    /** 还没说过话的新会话。 */
+    blank: boolean;
+    /** 子代理会话（不在侧栏里列，也不给选）。 */
+    subagent: boolean;
+}
+interface Observable<T> {
+    getSnapshot(): T;
+    subscribe(fn: () => void): () => void;
+}
+interface InputSnapshot {
+    draft: string;
+    phase: 'plain' | 'adjudicating' | 'claimed' | 'submitting';
+}
+interface SessionInput {
+    setDraft(text: string): void;
+    submit(): void;
+    readonly state: Observable<InputSnapshot>;
+}
+/** `ctx.conversation` 用到的部分。 */
+export interface ConversationService {
+    input: {
+        for(ctx: unknown): SessionInput;
+    };
+}
+interface SessionSummary {
+    id: string;
+    title?: string;
+    displayTitle?: string;
+    cwd?: string;
+    origin?: string;
+    running?: boolean;
+    blank?: boolean;
+    updatedAt?: number;
+}
+/** `ctx.sessions` 用到的部分。 */
+export interface SessionsService {
+    list: Observable<{
+        ids: readonly string[];
+        byId: Readonly<Record<string, SessionSummary>>;
+    }>;
+    create(opts?: {
+        workspaceId?: string;
+        cwd?: string;
+    }): Promise<string>;
+    using<T>(target: string, options: {
+        source: string;
+    }, operation: (reference: {
+        binding: {
+            ctx: unknown;
+        };
+    }) => T | Promise<T>): Promise<T>;
+}
+/** `ctx.workspaces` 用到的部分。 */
+export interface WorkspacesService {
+    list: Observable<{
+        items: readonly {
+            workspaceId: string;
+            path: string;
+            sessionIds: readonly string[];
+        }[];
+    }>;
+}
+/** `ctx.uiWorkspace` 用到的部分。 */
+export interface UiWorkspaceService {
+    openSession(target: string): void;
+}
+/** 视图拿到的会话桥。 */
+export interface SessionBridge {
+    /** 服务接上了没有（没接上 = 「执行」不可用）。 */
+    available(): boolean;
+    rows(): readonly SessionRow[];
+    subscribe(fn: () => void): () => void;
+    /** 往会话里发一句话；没发出去就抛错（错误信息给人看）。 */
+    deliver(session: string, text: string): Promise<void>;
+    /** 能不能新建会话。 */
+    canCreate(): boolean;
+    /** 在 `from` 所在的工作区新建一个会话（拿不到工作区就按 `cwd` 建），回新会话的 id。 */
+    create(from: string, cwd: string | undefined): Promise<string>;
+    /** 跳到一个会话（宿主没有导航能力时什么也不做，回 `false`）。 */
+    open(session: string): boolean;
+}
+/** 入口里建一个，服务接上 / 断开时调 `attach` / `detach`。 */
+export declare function createSessionBridge(): SessionBridge & {
+    attach(sessions: SessionsService, conversation: ConversationService): void;
+    detach(): void;
+    attachWorkspaces(workspaces: WorkspacesService | undefined, ui: UiWorkspaceService | undefined): void;
+};
+/** 同一个工作区：路径大小写、分隔符不同也算同一个（Windows）。 */
+export declare function sameDir(a: string | undefined, b: string | undefined): boolean;
+/** 能选的会话：本会话在最前，其余是同一工作区里说过话的主会话，新的在前。 */
+export declare function pickable(rows: readonly SessionRow[], session: string | undefined): SessionRow[];
+/** 订阅会话列表。 */
+export declare function useSessionRows(bridge: SessionBridge | undefined): readonly SessionRow[];
+export {};

package/lib/types/client/app/theme.d.ts

@@ -0,0 +1,27 @@
+/**
+ * dsh-workflow-lite — 选了哪套配色主题：亮色一套、暗色一套，记在浏览器里。
+ *
+ * 只是看起来的样子，不改工作流、也不用存进 profile：和视口、步骤库开关一样记在 localStorage。
+ * 同一个页面里几处一起订阅（视图根节点、设置页），换了马上都跟着变；别的标签页改了也跟着变。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/theme
+ */
+import { type DarkThemeId, type LightThemeId, type ThemeMode } from '../model/themes.ts';
+export interface ThemeChoice {
+    light: LightThemeId;
+    dark: DarkThemeId;
+}
+/** 读记下的选择；没记过、记坏了、存储不可用都按默认（坏掉的那一半单独按默认）。 */
+export declare function readThemeChoice(): ThemeChoice;
+export declare function getThemeChoice(): ThemeChoice;
+/** 换一套（只换给出的那一半）。两套都是默认时把记录删掉。 */
+export declare function setThemeChoice(next: Partial<ThemeChoice>): void;
+export declare function useThemeChoice(): ThemeChoice;
+/** 测试用：丢掉缓存，下次从存储重新读。 */
+export declare function resetThemeCache(): void;
+/**
+ * 此刻是亮还是暗：宿主把 `color-scheme` 写在 `<html>` 上；写的是 `light dark`（跟系统）时看系统设置。
+ * 只用来在设置页标「正在用」，配色本身由 CSS 的 `light-dark()` 自己挑。
+ */
+export declare function currentScheme(): ThemeMode;
+export declare function useColorScheme(): ThemeMode;

package/lib/types/client/app/usePluginConfig.d.ts

@@ -0,0 +1,59 @@
+/**
+ * dsh-workflow-lite — 工作流中心「设置」页的状态：读插件设置、在草稿上改、一次保存。
+ *
+ * - 输入框里的数字先按文字存（打字途中可以是空的），保存时才换成数；「读取上限」给人看 KB，存的是字节。
+ * - 保存时只送改了的几项：改回默认值的发「恢复」（删掉 profile 里那一项），其余发「设成」。
+ * - 别处先改过（修订号对不上）：重新读一遍，草稿留着，告诉人再保存一次。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/usePluginConfig
+ */
+import { type PluginConfigKey, type PluginConfigValues, type PluginConfigView } from '../../shared/wire.ts';
+import type { T } from '../i18n.ts';
+import { type WorkflowLiteRpc } from '../rpc.ts';
+/** 草稿：文字框里的原样。 */
+export interface ConfigDraft {
+    dataDir: string;
+    maxNodes: string;
+    saveDebounceMs: string;
+    /** 以 KB 计。 */
+    maxResultBytes: string;
+    installSkill: boolean;
+}
+export type ConfigErrors = Partial<Record<PluginConfigKey, string>>;
+export interface PluginConfigState {
+    view: PluginConfigView | null;
+    draft: ConfigDraft | null;
+    /** 读不出来时的原因。 */
+    loadError: string | null;
+    errors: ConfigErrors;
+    /** 和已保存的值不一样的几项。 */
+    dirty: PluginConfigKey[];
+    busy: boolean;
+    notice: {
+        tone: 'ok' | 'error';
+        text: string;
+    } | null;
+    edit<K extends keyof ConfigDraft>(key: K, value: ConfigDraft[K]): void;
+    /** 草稿里这一项换回默认值（保存后生效）。 */
+    toDefault(key: PluginConfigKey): void;
+    discard(): void;
+    save(): Promise<void>;
+}
+export declare function toDraft(values: PluginConfigValues): ConfigDraft;
+/**
+ * 草稿 → 值。`saved` 用来认「读取上限没动过」：KB 四舍五入回去和原来的字节数对不上时，原值照留。
+ * @returns 有错的项给出原因；没错的项给出值。
+ */
+export declare function fromDraft(draft: ConfigDraft, saved: PluginConfigValues, t: T): {
+    values: PluginConfigValues;
+    errors: ConfigErrors;
+};
+export declare function usePluginConfig(rpc: WorkflowLiteRpc, t: T, onSaved: () => void): PluginConfigState;
+/** 各项的名字（提示里拼「数据目录、给模型的使用指南要重启」用）。 */
+export declare const LABEL: {
+    readonly dataDir: "cfg.dataDir";
+    readonly maxNodes: "cfg.maxNodes";
+    readonly saveDebounceMs: "cfg.saveDebounce";
+    readonly maxResultBytes: "cfg.maxResult";
+    readonly installSkill: "cfg.skill";
+};

package/lib/types/client/app/useRunFile.d.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh-workflow-lite — 读实例里的一份产出文件（文件面板的预览、查看框）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/useRunFile
+ */
+import type { RunFileResponse } from '../../shared/wire.ts';
+import { type WorkflowLiteRpc } from '../rpc.ts';
+/** 要看哪份：快照里某个资源的第几项，或实例工作区里的相对路径。 */
+export type FileTarget = {
+    node: string;
+    item: number;
+} | {
+    path: string;
+};
+export interface RunFile {
+    file: RunFileResponse | null;
+    error: string | null;
+    loading: boolean;
+    reload(): void;
+}
+/**
+ * @param version - 变了就重读（文件面板拿"文件在不在 + 状态文件修改时间"当版本：模型写完文件通常也会更新状态）。
+ */
+export declare function useRunFile(rpc: WorkflowLiteRpc, instance: string, target: FileTarget | null, version?: string | number): RunFile;

package/lib/types/client/app/useRunGraph.d.ts

@@ -0,0 +1,51 @@
+/**
+ * dsh-workflow-lite — 实例视图里改图：一份只在本地的编辑器（和模板编辑同一个状态机），不自动存。
+ *
+ * 图的改动和状态的改动攒在同一条草稿栏里（「已改 x 处」），用户点「保存并通知模型」才一起交给 host。
+ * 改到一半切走再回来接着改：改过的图按实例存在浏览器里，基线（planId）对不上就作废。
+ *
+ * 检查和模板用同一套规则（`shared/validate.ts` 的四级）：顶栏的检查结果列全部，画布按它标卡片；
+ * 挡保存的只有保存级、编译级，而且只在改过图时才挡（没改过就是建实例时那张，不该拦着改状态）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/useRunGraph
+ */
+import { type GraphChange } from '../../shared/graphDiff.ts';
+import type { ValidationProblem, WorkflowDocument } from '../../shared/types.ts';
+import { type Edit, type Selection } from '../model/editor.ts';
+import type { SideHistory } from '../model/runHistory.ts';
+export interface RunGraph {
+    /** 改到现在的图；基线还没到时是 `null`。 */
+    doc: WorkflowDocument | null;
+    /** 改之前那版。 */
+    base: WorkflowDocument | null;
+    /** 改之前那版的 planId（保存时交给 host 核对）。 */
+    basePlan: string | null;
+    selection: Selection;
+    /** 比基线改了什么（一处一项，按 `shared/graphDiff.ts` 数）。 */
+    changes: GraphChange[];
+    /** 改完的图保存不了的问题（保存级、编译级；没改过图时为空）：保存按钮按住。 */
+    problems: ValidationProblem[];
+    /** 这张图的全部检查结果（四级，和模板同一套规则）：顶栏的检查结果、画布上的标记。 */
+    report: ValidationProblem[];
+    /** 图的撤销栈。 */
+    history: SideHistory;
+    edit(edit: Edit): void;
+    select(selection: Selection): void;
+    seal(): void;
+    undo(): void;
+    redo(): void;
+    /** 丢掉重做栈（状态那边有了新的一步）。 */
+    dropRedo(): void;
+    /** 单独撤回清单里的一处。 */
+    revert(change: GraphChange): void;
+    /** 放弃图的全部改动。 */
+    discard(): void;
+    /** 存好了：改到现在的图就是新的基线（`planId` 是 host 回的新图的）。 */
+    commit(planId: string): void;
+}
+export declare function useRunGraph(id: string, 
+/** host 给的快照（已补好位置）与它的 planId；还没读回来是 `null`。 */
+source: {
+    planId: string;
+    doc: WorkflowDocument;
+} | null, workflow: string | undefined): RunGraph;

package/lib/types/client/app/useRunHistory.d.ts

@@ -0,0 +1,21 @@
+/**
+ * dsh-workflow-lite — 实例视图的撤销 / 重做：把图的撤销栈和状态草稿的撤销栈排成一条
+ * （顺序怎么对齐见 `model/runHistory.ts`）。顶栏的两个按钮和 Ctrl+Z / Ctrl+Shift+Z 都走这里。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/useRunHistory
+ */
+import { type HistorySide, type SideHistory } from '../model/runHistory.ts';
+/** 一边要交给这里的东西。 */
+export interface HistorySource {
+    history: SideHistory;
+    undo(): void;
+    redo(): void;
+    dropRedo(): void;
+}
+export interface RunHistory {
+    canUndo: boolean;
+    canRedo: boolean;
+    undo(): void;
+    redo(): void;
+}
+export declare function useRunHistory(sources: Record<HistorySide, HistorySource>): RunHistory;

package/lib/types/client/app/useRuns.d.ts

@@ -0,0 +1,84 @@
+/**
+ * dsh-workflow-lite — 工作流实例的两只钩子：
+ * - {@link useRuns}：本会话（或全部）的实例列表与当前实例；
+ * - {@link useRun}：正在看的那一个实例——轮询状态文件、攒草稿、冲突、保存并通知模型。
+ *
+ * 只有实例视图轮询（每 2 秒带上次的 mtime 问一次，没变就只回"没变"）；模板编辑照旧不轮询。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/useRuns
+ */
+import { type InstanceSummary, type InstanceView, type NodeStatus, type RunState, type StateEdit } from '../../shared/runState.ts';
+import type { WorkflowDocument } from '../../shared/types.ts';
+import type { RunSaveResponse } from '../../shared/wire.ts';
+import type { T } from '../i18n.ts';
+import { type DraftConflict } from '../model/runDraft.ts';
+import type { SideHistory } from '../model/runHistory.ts';
+import { type WorkflowLiteRpc } from '../rpc.ts';
+/** 实例视图轮询的间隔。 */
+export declare const RUN_POLL_MS = 2000;
+export interface Runs {
+    /** 本会话的实例（新的在前）。 */
+    list: InstanceSummary[];
+    /** 本会话的当前实例。 */
+    current: string | undefined;
+    /** 第一次拉完没有。 */
+    loaded: boolean;
+    refresh(): Promise<void>;
+    /** 设本会话的当前实例（别的会话的实例会被转过来）。 */
+    bind(id: string): Promise<boolean>;
+    remove(id: string, withState: boolean): Promise<boolean>;
+    /** 列全部会话的实例（工作流中心用）。 */
+    all(): Promise<InstanceSummary[]>;
+}
+export declare function useRuns(rpc: WorkflowLiteRpc, session: string | undefined): Runs;
+export interface RunToast {
+    id: number;
+    tone: 'ok' | 'error';
+    text: string;
+}
+export interface Run {
+    /** 最近一次读到的实例（含快照与校验结论）；第一次读回来之前是 `null`。 */
+    view: InstanceView | null;
+    /** 上一次合法的状态（文件写坏时画布保留它）。 */
+    lastGood: RunState | null;
+    /** 叠上草稿之后的状态：画布与面板显示的就是它。 */
+    shown: RunState | null;
+    draft: StateEdit[];
+    conflicts: DraftConflict[];
+    /** 保存后又被模型改回去的字段（提示"你的修改可能被模型覆盖了"）。 */
+    overwritten: string[][];
+    note: string;
+    setNote(note: string): void;
+    /** 保存时通知模型没有（默认通知；关掉就只保存）。 */
+    notify: boolean;
+    setNotify(notify: boolean): void;
+    saving: boolean;
+    error: string | null;
+    toast: RunToast | null;
+    /** 在实例视图底部弹一句话。 */
+    flash(tone: RunToast['tone'], text: string): void;
+    setField(path: string[], to: StateEdit['to']): void;
+    setStatus(id: string, status: NodeStatus): void;
+    /** 一次改几个步骤的状态。 */
+    setStatuses(ids: readonly string[], status: NodeStatus): void;
+    rerun(ids: readonly string[]): void;
+    undoEdit(path: readonly string[]): void;
+    resolve(conflict: DraftConflict, keep: 'mine' | 'theirs'): void;
+    /** 状态草稿的撤销栈（图的在 useRunGraph；两边由 useRunHistory 排成一条）。 */
+    draftHistory: SideHistory;
+    undoDraft(): void;
+    redoDraft(): void;
+    /** 丢掉重做栈（图那边有了新的一步）。 */
+    dropDraftRedo(): void;
+    discard(): void;
+    /**
+     * 保存草稿并通知模型。改了图就把改完的整张图一起交上去（草稿里删掉了的步骤的状态改动不交）；
+     * 存好了回 host 的回执，没存成回 `null`。
+     */
+    save(graph?: {
+        base: string;
+        document: WorkflowDocument;
+    }): Promise<RunSaveResponse | null>;
+    reload(): Promise<void>;
+}
+export declare function useRun(rpc: WorkflowLiteRpc, id: string, session: string | undefined, t: T, onSaved?: () => void): Run;

package/lib/types/client/app/useVersions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * dsh-workflow-lite — 一个工作流的版本：列、存、切、改说明、删，外加「切到这一版会变什么」。
+ *
+ * 编辑页的「版本」对话框和工作流中心的「工作流」页共用它。版本存的是**磁盘上**那份：
+ * 动手之前先调 `before()`（编辑页正开着这张图时把还没写下去的改动存掉）；
+ * 切换写回了工作流之后调 `onRestored()`（正开着就按磁盘重新加载）。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/useVersions
+ */
+import { type GraphChange } from '../../shared/graphDiff.ts';
+import type { VersionEntry, WorkflowDocument } from '../../shared/types.ts';
+import type { T } from '../i18n.ts';
+import { type WorkflowLiteRpc } from '../rpc.ts';
+export interface VersionNotice {
+    tone: 'ok' | 'error';
+    text: string;
+    /** 每条提示一个新值：同样的字再出现一次也要重新淡入。 */
+    seq: number;
+}
+/** 切到某一版会变什么：`base` = 现在，`next` = 那一版。 */
+export interface VersionDiff {
+    changes: GraphChange[];
+    settings: boolean;
+    base: WorkflowDocument;
+    next: WorkflowDocument;
+}
+export interface Versions {
+    /** `null` = 还在读。 */
+    list: VersionEntry[] | null;
+    /** 正在做的那件事（按钮按住）。 */
+    busy: boolean;
+    notice: VersionNotice | null;
+    refresh(): Promise<void>;
+    save(note: string): Promise<boolean>;
+    restore(n: number): Promise<boolean>;
+    setNote(n: number, note: string): Promise<boolean>;
+    remove(n: number): Promise<boolean>;
+    diff(n: number): Promise<VersionDiff | null>;
+}
+export declare function useVersions(options: {
+    t: T;
+    rpc: WorkflowLiteRpc;
+    name: string;
+    /** 动手前（存掉编辑页还没写下去的改动）；回 `false` 就不做了。 */
+    before?: () => Promise<boolean>;
+    /** 切换写回了工作流之后。 */
+    onRestored?: () => void;
+    /** 版本数变了（列表里的「N 个版本」跟上）。 */
+    onChanged?: () => void;
+}): Versions;

package/lib/types/client/app/useWorkflow.d.ts

@@ -0,0 +1,67 @@
+/**
+ * dsh-workflow-lite — 编辑器的"发动机"：加载、自动保存、冲突、目录。
+ *
+ * 状态放在一个 ref 里同步推进，再镜像进 React state 触发渲染。**不能只靠 React state**：
+ * 改完文档要立刻判断"该不该排一次保存"，而 React 的 state 要等下一次渲染才更新——
+ * 读到旧值就会把这次排期整个丢掉（改动永远不落盘）。
+ *
+ * 保存规则：
+ * - 改动 → 防抖后写一次；保存中不重入，保存期间来的改动在这笔写完后补排；
+ * - 换图 / 页面隐藏 / 卸载 → 立即写，不等防抖；
+ * - `broken` 态绝不写盘。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/useWorkflow
+ */
+import { type GraphAnalysis } from '../../shared/graph.ts';
+import type { NodeData } from '../../shared/types.ts';
+import type { GraphListResponse, PlanBuildResponse } from '../../shared/wire.ts';
+import type { T } from '../i18n.ts';
+import { type Edit, type EditorState, type Selection } from '../model/editor.ts';
+import { type WorkflowLiteRpc } from '../rpc.ts';
+export interface Toast {
+    id: number;
+    text: string;
+    tone: 'info' | 'error';
+}
+export interface Workflow {
+    state: EditorState;
+    analysis: GraphAnalysis | null;
+    catalog: GraphListResponse | null;
+    /** 磁盘上的版本与本地改动冲突时的冲突 id 清单；`null` = 没有冲突。 */
+    conflict: string[] | null;
+    /** 本地有改动、磁盘又被别处改过。 */
+    external: boolean;
+    toast: Toast | null;
+    /** 刚建好的工作流名字：顶栏据此直接进入改名。读完即清。 */
+    fresh: string | null;
+    clearFresh(): void;
+    edit(edit: Edit): void;
+    select(selection: Selection): void;
+    undo(): void;
+    redo(): void;
+    /** 一次连续输入结束：断开撤销合并。 */
+    seal(): void;
+    open(name: string): Promise<void>;
+    create(): Promise<void>;
+    /** 改名：`from` 可以是任意一张（不必先打开）；改的是正开着的这张时顶栏跟着换名字。 */
+    rename(from: string, to: string): Promise<boolean>;
+    /** 回 `false` = 没删成（已经提示过了）。 */
+    remove(name: string): Promise<boolean>;
+    reload(): void;
+    retrySave(): void;
+    keepMine(): void;
+    refreshCatalog(): Promise<void>;
+    /** 预览计划；`cwd` = 执行时的工作区（计划里的工作区路径、任务描述路径按它写）。 */
+    buildPlan(full: boolean, cwd?: string): Promise<PlanBuildResponse>;
+    /** 把待写的改动立刻存下去（「执行」之前：实例要拿磁盘上的那份做快照）。存不下去回 `false`。 */
+    flush(): Promise<boolean>;
+    loadTemplate(name: string): Promise<NodeData | null>;
+    saveTemplate(name: string, data: NodeData): Promise<boolean>;
+    /** 读「我的步骤」给人编辑（提示词空着的半成品也能读）。 */
+    loadTemplateDraft(name: string): Promise<NodeData | null>;
+    /** 覆盖保存「我的步骤」；`name` 与 `from` 不同就是改名。成功返回保存后的名字。 */
+    updateTemplate(name: string, data: NodeData, from: string): Promise<string | null>;
+    deleteTemplate(name: string): Promise<boolean>;
+    notify(text: string, tone?: Toast['tone']): void;
+}
+export declare function useWorkflow(rpc: WorkflowLiteRpc, t: T): Workflow;

package/lib/types/client/app/viewport.d.ts

@@ -0,0 +1,14 @@
+/**
+ * dsh-workflow-lite — 每张图上次看到哪（视口）记在浏览器里，不写进图文件。
+ *
+ * 视口是看图的人自己的状态：拖动、缩放只是浏览，不该让图变成「待保存」，
+ * 更不该因为一次平移就整图写盘、和模型正在做的改动撞车。图文件里的 `viewport` 只读不写，
+ * 浏览器里没记过（第一次打开、换了浏览器）时拿它兜底。
+ *
+ * @module @xiaoso/dsh-workflow-lite/client/app/viewport
+ */
+import type { Viewport } from '../../shared/types.ts';
+/** 这张图上次的视口；没记过、记坏了或存储不可用就是 `null`。 */
+export declare function recallViewport(workflow: string): Viewport | null;
+/** 记下这张图的视口（尽力而为）。 */
+export declare function rememberViewport(workflow: string, viewport: Viewport): void;