@republicroad/seal-appshell 1.1.0

package/dist/integration/decision-graph-appshell.stories.d.ts

@@ -0,0 +1,10 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+/**
+ * Cross-package integration: kernel DecisionGraph + appshell custom nodes
+ * (useCustomNodes) + an in-memory GraphPersistenceAdapter — the scheme D
+ * kernel/shell contract exercised end to end.
+ */
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj;
+export declare const KernelPlusAppshell: Story;

package/dist/lib/__tests__/crypto-protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/custom-node-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/http-request-protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/json-path-protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/storage-key.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/auth/__tests__/adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/auth/adapter.d.ts

@@ -0,0 +1,7 @@
+export interface AuthUser {
+    userId: string;
+    displayName?: string;
+}
+export type AuthAdapter = () => Promise<AuthUser | null>;
+export declare const createAnonymousAdapter: () => AuthAdapter;
+export declare const createBetterAuthAdapter: () => AuthAdapter;

package/dist/lib/auth-client.d.ts

@@ -0,0 +1,3 @@
+export declare const authClient: import('better-auth/react').ReactAuthClient<{
+    baseURL: string;
+}>;

package/dist/lib/crypto-protocol.d.ts

@@ -0,0 +1,28 @@
+import { CustomNodeExpression } from './custom-node-types';
+export declare const CRYPTO_UDF = "crypto";
+export declare const CRYPTO_ALGORITHMS: readonly ["md5", "sha1", "sha256", "sha512"];
+export type CryptoAlgorithm = (typeof CRYPTO_ALGORITHMS)[number];
+export declare const CRYPTO_ENCODINGS: readonly ["hex", "base64", "base64url"];
+export type CryptoEncoding = (typeof CRYPTO_ENCODINGS)[number];
+export interface CryptoFields {
+    inputExpr: string;
+    algorithm: CryptoAlgorithm;
+    secretExpr: string;
+    encoding: CryptoEncoding;
+    upperExpr: string;
+}
+export type CryptoMode = 'plain' | 'hmac';
+/** 密钥槽位非空即 HMAC(旧图兼容的隐式约定) */
+export declare const deriveCryptoMode: (secretExpr: string) => CryptoMode;
+/** 显式模式归一：普通摘要强制清空密钥槽位，HMAC 保留原表达式 */
+export declare const applyCryptoMode: (fields: CryptoFields, mode: CryptoMode) => CryptoFields;
+export declare const normalizeAlgorithm: (value: string) => CryptoAlgorithm;
+export declare const normalizeEncoding: (value: string) => CryptoEncoding;
+/** upper 槽位仅接受布尔字面量 true(其余一律视为未勾选) */
+export declare const isUpperChecked: (expr: string) => boolean;
+export declare const parseCrypto: (expr?: CustomNodeExpression) => CryptoFields;
+/**
+ * 变长序列化：固定前缀 [crypto, input, "algorithm"]，可选尾参(secret/encoding/upper)
+ * 末尾连续空值截断省略，中段空串占位保证槽位对齐；后端对缺省/空值回退默认。
+ */
+export declare const toCryptoValue: (fields: CryptoFields) => string[];

package/dist/lib/custom-node-plans.d.ts

@@ -0,0 +1,24 @@
+import { CustomFunctionTool, CustomNodeConfig, CustomNodeNamespace } from './custom-node-types';
+export declare const uid: () => string;
+export declare const LEGACY_UDF_KIND = "UDF";
+export declare const CUSTOM_FUNCTION_GROUP = "\u81EA\u5B9A\u4E49\u51FD\u6570";
+export declare const EMPTY_EXPRESSIONS_CONFIG: CustomNodeConfig;
+/** 纯数据节点计划：kind 约定与播种逻辑在此(可测)，React/jdm-editor 组装在 registry */
+export type CustomNodePlan = {
+    kind: string;
+    displayName: string;
+    group: string;
+    shortDescription?: string;
+    /** 命名空间工具集：存在时节点挂 schema 感知编辑面板（函数下拉 + 位置参数） */
+    tools?: CustomFunctionTool[];
+    seed: (params: {
+        index: number;
+    }) => {
+        name: string;
+        config: CustomNodeConfig;
+    };
+};
+export declare const containerPlan: (namespace: CustomNodeNamespace) => CustomNodePlan;
+export declare const legacyUdfPlan: () => CustomNodePlan;
+/** schema → 节点计划：每个命名空间一个集合容器节点(kind = 命名空间名，函数限定集合内) */
+export declare function schemaToNodePlans(schema: CustomNodeNamespace[]): CustomNodePlan[];

package/dist/lib/custom-node-registry.d.ts

@@ -0,0 +1,13 @@
+import { CustomNodeSpecification, createJdmNode } from '@republicroad/seal-editor';
+import { CustomNodeNamespace } from './custom-node-types';
+export type CustomNodeSpec = CustomNodeSpecification<object, any>;
+type SpecExtras = Pick<CustomNodeSpec, 'renderTab' | 'calculateDiff' | 'inferTypes'>;
+type CreateSpecNodeOptions = Parameters<typeof createJdmNode>[0] & SpecExtras;
+/** createJdmNode 只收 BaseNode 画布字段；spec 级 renderTab/calculateDiff/inferTypes 由本组合器附加 */
+export declare const createSpecNode: (options: CreateSpecNodeOptions) => CustomNodeSpec;
+export { CUSTOM_FUNCTION_GROUP, LEGACY_UDF_KIND, uid } from './custom-node-plans';
+export { parseOperatorArgs } from './http-request-protocol';
+/** 每个命名空间生成一个集合容器节点(kind = 命名空间名) */
+export declare function schemaToCustomNodes(schema: CustomNodeNamespace[]): ReturnType<typeof createJdmNode>[];
+export declare function createLegacyUdfNode(): ReturnType<typeof createJdmNode>;
+export { DEFAULT_SCHEMA_URL, fetchCustomNodeSchema, parseCustomNodeSchemaPayload, type CustomNodeSchemaSource, } from './custom-node-schema-source';

package/dist/lib/custom-node-schema-source.d.ts

@@ -0,0 +1,6 @@
+import { CustomNodeNamespace } from './custom-node-types';
+export type CustomNodeSchemaSource = string | (() => Promise<CustomNodeNamespace[]> | CustomNodeNamespace[]);
+export declare const DEFAULT_SCHEMA_URL = "/api/custom-nodes/schema";
+/** 校验并收窄 schema 载荷；非法结构抛错，由调用方决定回退策略 */
+export declare function parseCustomNodeSchemaPayload(payload: unknown): CustomNodeNamespace[];
+export declare function fetchCustomNodeSchema(source?: CustomNodeSchemaSource): Promise<CustomNodeNamespace[]>;

package/dist/lib/custom-node-types.d.ts

@@ -0,0 +1,73 @@
+export interface JsonSchemaProperty {
+    type?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    anyOf?: JsonSchemaProperty[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchemaProperty;
+    $ref?: string;
+    $defs?: Record<string, JsonSchemaProperty>;
+    enum?: unknown[];
+    format?: string;
+    [key: string]: unknown;
+}
+export interface JsonSchema {
+    type?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    anyOf?: JsonSchema[];
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchemaProperty;
+    $ref?: string;
+    $defs?: Record<string, JsonSchemaProperty>;
+    [key: string]: unknown;
+}
+export interface CustomFunctionTool {
+    name: string;
+    title: string;
+    type: 'function';
+    description?: string;
+    parameters: {
+        properties: Record<string, JsonSchemaProperty>;
+        required?: string[];
+        title?: string;
+        type?: 'object';
+    };
+    returns: JsonSchema;
+    namespace: string;
+    kind: string;
+}
+export interface CustomNodeNamespace {
+    /** 恒为 'namespace'(集合容器档；契约字段保留供未来场景) */
+    type?: 'namespace';
+    title: string;
+    name: string;
+    description?: string;
+    tools: CustomFunctionTool[];
+}
+export type CustomNodeExpression = {
+    id: string;
+    key: string;
+    /**
+     * 调用形态三模（JSON-RPC 式类型判别）：
+     * - 数组（默认）= 位置调用 [fn, arg1, ..., argn]
+     * - 字符串 = legacy `;;` 拼接（旧图兼容）
+     * - 对象 = 命名调用 { $call: fn, ...具名实参 }（实参值为 zen 表达式或字面量）
+     */
+    value: string | string[] | Record<string, unknown>;
+};
+export type CustomNodeConfig = {
+    /** 锁定节点 UI 标记：true 表示此节点有专属页面设计（数据侧显式声明，缺省=通用锁定表格 UI） */
+    locked?: true;
+    inputField?: string | null;
+    outputPath?: string | null;
+    passThrough?: boolean;
+    expressions: CustomNodeExpression[];
+    __meta__?: Record<string, unknown>;
+};

package/dist/lib/http-request-protocol.d.ts

@@ -0,0 +1,47 @@
+import { CustomNodeExpression } from './custom-node-types';
+export declare const UDF_FUNC = "http_request";
+export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+export interface HttpRequestFields {
+    urlExpr: string;
+    method: HttpMethod;
+    headersExpr: string;
+    bodyExpr: string;
+    paramsExpr: string;
+    timeoutExpr: string;
+    retryExpr: string;
+    authExpr: string;
+}
+export interface KeyValueRow {
+    key: string;
+    valueExpr: string;
+}
+export type AuthMode = 'none' | 'basic' | 'bearer';
+export interface AuthState {
+    mode: AuthMode;
+    username: string;
+    passwordExpr: string;
+    tokenExpr: string;
+}
+export declare const EMPTY_AUTH: AuthState;
+export declare const unquote: (value: string) => string;
+export declare const quote: (value: string) => string;
+/** 表达式实参拆分：数组原样(仅 trim)；旧 `;;` 字符串按引号感知切分 */
+export declare const parseOperatorArgs: (expr: string | string[]) => string[];
+export declare const normalizeMethod: (value: string) => HttpMethod;
+export declare const isIdentKey: (key: string) => boolean;
+export declare const serializeHeaderKey: (key: string) => string;
+export declare const splitTopLevel: (text: string, separator: string) => string[];
+export declare const findTopLevelColon: (text: string) => number;
+/** `{ k: expr, ... }` 对象字面量 ⇄ 行数组；无法拆行时返回 null(交由原始表达式模式) */
+export declare const parseObjectLiteralRows: (expr: string) => KeyValueRow[] | null;
+export declare const serializeObjectLiteralRows: (rows: KeyValueRow[]) => string;
+export declare const parseHttpRequest: (expr?: CustomNodeExpression) => HttpRequestFields;
+/**
+ * 变长序列化：可选尾部参数(params/timeout/retry/auth)按位置占位，末尾连续空值截断省略；
+ * 中段空值保留空串占位以保证后续参数位置正确，后端对空串回退默认值。
+ */
+export declare const toHttpRequestValue: (fields: HttpRequestFields) => string[];
+/** 解析 auth 表达式为结构化状态；非对象字面量或无法识别的 type 返回 null(交由界面提示保留原文) */
+export declare const parseAuthState: (expr: string) => AuthState | null;
+export declare const serializeAuthExpr: (state: AuthState) => string;

package/dist/lib/json-path-protocol.d.ts

@@ -0,0 +1,11 @@
+import { CustomNodeExpression } from './custom-node-types';
+export declare const JSON_PATH_UDF = "json_path";
+export interface JsonPathFields {
+    inputExpr: string;
+    pathExpr: string;
+    defaultExpr: string;
+}
+export declare const normalizeJsonPath: (value: string) => string;
+export declare const parseJsonPath: (expr?: CustomNodeExpression) => JsonPathFields;
+/** 变长尾参:default 末尾空值截断;路径槽位恒以字符串字面量序列化 */
+export declare const toJsonPathValue: (fields: JsonPathFields) => string[];

package/dist/lib/roster-source.d.ts

@@ -0,0 +1,12 @@
+/**
+ * roster 名单数据源（可注入）：默认同源 `/api/rosters`（宿主后端实现名单列表契约，
+ * 返回 `[{ name, size }]`）。跨源后端/本地夹具经 setRosterSource 注入。
+ */
+export interface RosterOption {
+    name: string;
+    size: number;
+}
+export type RosterSource = (query: string) => Promise<RosterOption[]>;
+export declare const getRosterSource: () => RosterSource;
+/** 宿主注入名单来源（跨源后端/本地夹具等）；与 setRosterSource 对应的恢复用 resetRosterSource */
+export declare const setRosterSource: (source: RosterSource) => void;

package/dist/lib/storage-key.d.ts

@@ -0,0 +1,5 @@
+export declare const storageKey: (key: string) => string;
+/** 读取命名空间键；新键缺失时回退读历史无前缀键(一次性兼容)，均缺失或存储不可用返回 null */
+export declare const readStorage: (key: string) => string | null;
+/** 写入命名空间键；存储不可用时静默忽略 */
+export declare const writeStorage: (key: string, value: string) => void;

package/dist/lib/user-resolver.d.ts

@@ -0,0 +1,6 @@
+import { AuthAdapter } from './auth/adapter';
+export type UserResolver = () => Promise<{
+    user?: string;
+}> | null;
+export declare const createUserResolver: (adapter: AuthAdapter) => UserResolver;
+export declare const createBetterAuthResolver: () => UserResolver;

package/dist/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { ClassValue } from 'clsx';
+export declare const cn: (...inputs: ClassValue[]) => string;

package/dist/reui/icons/animated/duotone/lock.d.ts

@@ -0,0 +1,3 @@
+export default function LockIcon({ className }: {
+    className?: string;
+}): import('react').JSX.Element;

package/dist/reui/icons/animated/outline/play-circle.d.ts

@@ -0,0 +1,3 @@
+export default function PlayCircleIcon({ className }: {
+    className?: string;
+}): import('react').JSX.Element;

package/dist/reui/icons/default/outline/plus-circle.d.ts

@@ -0,0 +1,3 @@
+export default function PlusCircleIcon({ className }: {
+    className?: string;
+}): import('react').JSX.Element;

package/dist/reui/icons/default/outline/shield-search.d.ts

@@ -0,0 +1,3 @@
+export default function ShieldSearchIcon({ className }: {
+    className?: string;
+}): import('react').JSX.Element;

package/dist/reui/icons/default/outline/trash-square.d.ts

@@ -0,0 +1,3 @@
+export default function TrashSquareIcon({ className }: {
+    className?: string;
+}): import('react').JSX.Element;

package/dist/shell/__tests__/default-simulate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell/__tests__/graphs-http-adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell/default-simulate.d.ts

@@ -0,0 +1,3 @@
+import { SimulateHandler } from './types';
+/** 默认模拟实现：同源 POST /api/simulate，错误映射为 Simulation 信封(不抛出，经 errorMessage 传达) */
+export declare const createDefaultSimulate: (url?: string) => SimulateHandler;

package/dist/shell/editor-shell.context.d.ts

@@ -0,0 +1,22 @@
+import { CustomNodeSpecification } from '@republicroad/seal-editor';
+import { default as React } from 'react';
+import { CustomNodeNamespace } from '../lib/custom-node-types';
+import { UserResolver } from '../lib/user-resolver';
+import { GraphPersistenceAdapter } from './persistence';
+import { EditorShellOptions, SimulateHandler } from './types';
+type CustomNodeSpec = CustomNodeSpecification<object, any>;
+export interface EditorShellContextValue {
+    customNodes: CustomNodeSpec[];
+    schema: CustomNodeNamespace[] | null;
+    ready: boolean;
+    userResolver: UserResolver;
+    runSimulate: SimulateHandler;
+    /** 图持久化适配器：注入后页面打开/另存走宿主存储；未注入则回退浏览器本地文件 */
+    persistence?: GraphPersistenceAdapter;
+}
+export declare const EditorShellProvider: React.FC<{
+    options?: EditorShellOptions;
+    children: React.ReactNode;
+}>;
+export declare const useEditorShell: () => EditorShellContextValue;
+export {};

package/dist/shell/execute-simulate.d.ts

@@ -0,0 +1,8 @@
+import { SimulateHandler } from './types';
+/**
+ * 模拟实现：POST {baseUrl}/v1/execute（demo-server / verdict 执行方言），
+ * `{ model, input, trace: true }` → `{ result, performance, trace }`，
+ * 映射为 kernel Simulation 信封（错误不抛出，经 errorMessage 传达）。
+ * 与 createDefaultSimulate（/api/simulate 方言）并列，按宿主引擎二选一。
+ */
+export declare const createExecuteSimulate: (baseUrl?: string) => SimulateHandler;

package/dist/shell/graphs-http-adapter.d.ts

@@ -0,0 +1,7 @@
+import { GraphPersistenceAdapter } from './persistence';
+/**
+ * 将 /api/graphs 参考实现封装为 GraphPersistenceAdapter。
+ * 宿主可原样复用，或照此实现自己的后端(契约见 persistence.ts)。
+ * 404 → load 返回 null / delete 返回 false；409 CONFLICT → 抛 GraphPersistenceError。
+ */
+export declare const createGraphsHttpAdapter: (baseUrl?: string) => GraphPersistenceAdapter;

package/dist/shell/index.d.ts

@@ -0,0 +1,10 @@
+export { EditorShellProvider, useEditorShell, type EditorShellContextValue } from './editor-shell.context';
+export { ThemeContextProvider, useTheme, type ThemePreference } from '../context/theme.provider';
+export { createDefaultSimulate } from './default-simulate';
+export { createExecuteSimulate } from './execute-simulate';
+export type { EditorShellOptions, SimulateHandler, ShellSimulateResult } from './types';
+export { GraphPersistenceError } from './persistence';
+export { createGraphsHttpAdapter } from './graphs-http-adapter';
+export { createIndexedDbAdapter, AUTO_VERSIONS_KEEP } from './indexed-db-adapter';
+export { restoreVersion } from './restore';
+export type { GraphPersistenceAdapter, GraphRecord, GraphRecordMeta, PersistenceErrorCode } from './persistence';

package/dist/shell/indexed-db-adapter.d.ts

@@ -0,0 +1,16 @@
+import { GraphPersistenceAdapter } from './persistence';
+/**
+ * 本地图多版本持久化适配器（IndexedDB）。
+ *
+ * 为无后端的宿主提供与 HTTP 适配器同构的版本能力：
+ * head + 版本归档 + auto/manual 标记 + 保留策略（全部 manual + 最近 AUTO_VERSIONS_KEEP 条 auto）。
+ *
+ * 语义差异（本地单用户）：无 owner 隔离、无 CONFLICT——save 恒成功，baseRevision 忽略。
+ *
+ * 存储模型：object store "graphs"，双键——
+ *   head::{id}              → { meta, content }
+ *   ver::{id}::{revision}   → { meta, content }（归档）
+ */
+export declare const AUTO_VERSIONS_KEEP = 20;
+/** 本地图多版本持久化适配器（IndexedDB）——无后端宿主的完整版本能力 */
+export declare function createIndexedDbAdapter(): GraphPersistenceAdapter;

package/dist/shell/persistence.d.ts

@@ -0,0 +1,89 @@
+import { TabSnapshot } from '@republicroad/seal-editor';
+export interface GraphRecordMeta {
+    /** 宿主侧唯一标识(UUID/slug，由宿主生成) */
+    id: string;
+    name: string;
+    description?: string;
+    /** 缺省=共享(复用名单 owner 语义)；宿主服务端注入，客户端传值被剥离 */
+    owner?: string;
+    tags?: string[];
+    /** 图+配置打包：宿主可挂载调度、环境绑定等非图数据 */
+    extensions?: Record<string, unknown>;
+    /** 当前 head 版本号(宿主/适配器生成，单调递增)。save 调用方可省略——由适配器分配新版本号；load/list 场景恒有 */
+    revision?: string;
+    /** 自动保存条目（与手动保存区分显示/治理策略），缺省 = 手动 */
+    auto?: boolean;
+    /**
+     * 版本命名（"named version"）。保存时携带 → 该版本归档后按名显示；
+     * 命名版本不受 auto 保留策略治理（见各适配器实现）。
+     */
+    versionName?: string;
+    /** 钉住标记（S007）：钉住的版本（含 auto）同样豁免 auto 保留策略治理。 */
+    pinned?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface GraphRecord extends GraphRecordMeta {
+    /** DecisionGraphType(nodes/edges/meta)，由消费方解包 */
+    content: unknown;
+    /**
+     * UI 会话现场（GraphRef.serialize() 的快照：viewport/打开页签/各页签 slice）。
+     * 与 content 兄弟存储——历史条目=完整现场快照（1a+4b）；缺省=旧记录降级（跳过 restore）。
+     */
+    session?: TabSnapshot;
+}
+export type PersistenceErrorCode = 'NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN';
+export declare class GraphPersistenceError extends Error {
+    code: PersistenceErrorCode;
+    constructor(code: PersistenceErrorCode, message?: string);
+}
+export interface GraphPersistenceAdapter {
+    /** 列出当前用户可见的图元数据(head 版本)；未实现则 shell 隐藏「打开」面板 */
+    list?(query?: {
+        q?: string;
+    }): Promise<GraphRecordMeta[]>;
+    /**
+     * 加载指定图。
+     * @param opts.revision 指定历史版本号；省略则加载 head。
+     * @returns null = 不可见或不存在(返回 404 语义，不暴露是否存在)
+     */
+    load(id: string, opts?: {
+        revision?: string;
+    }): Promise<GraphRecord | null>;
+    /**
+     * 保存(upsert)。
+     * @param opts.baseRevision 乐观锁：提供时校验 head 是否匹配，不匹配抛 CONFLICT。
+     * @returns 包含分配的 id 与新 revision。
+     */
+    save(record: GraphRecord, opts?: {
+        baseRevision?: string;
+    }): Promise<{
+        id: string;
+        revision: string;
+    }>;
+    /** 删除指定图；返回 false = 不可见或不存在(404 语义) */
+    delete?(id: string): Promise<boolean>;
+    /** 列出指定图的所有历史版本(可选；未实现则 shell 不展示版本历史面板) */
+    listVersions?(id: string): Promise<Array<{
+        revision: string;
+        versionName?: string;
+        pinned?: boolean;
+        updatedAt?: string;
+        auto?: boolean;
+    }>>;
+    /**
+     * 更新指定历史版本的元数据（钉住/命名，S007）：可选方法；未实现则 shell 隐藏
+     * 对应入口。部分更新语义：仅显式给出的键被更新（undefined = 保留现值，
+     * null = 清除），未提及的兄弟键必须原样保留。
+     * @throws GraphPersistenceError('NOT_FOUND') 版本不存在时（本地适配器语义）。
+     */
+    updateVersionMeta?(id: string, revision: string, meta: {
+        pinned?: boolean;
+        versionName?: string | null;
+    }): Promise<void>;
+    /**
+     * 重命名（或清除，传 null）指定历史版本的 versionName。兼容别名：
+     * 等价于 updateVersionMeta(id, revision, { versionName })。
+     */
+    renameVersion?(id: string, revision: string, versionName: string | null): Promise<void>;
+}

package/dist/shell/restore.d.ts

@@ -0,0 +1,21 @@
+import { GraphPersistenceAdapter } from './persistence';
+/**
+ * 恢复即前进（restore-is-forward）：将指定历史版本的内容固化为新的 head。
+ *
+ * 语义：load(revision) 取回历史条目 → 以其 content/session/meta 为基础 save()。
+ * 两个适配器的 save 恒定「bump head + 归档旧 head」，因此恢复只追加历史、
+ * 永不覆盖其后版本；被恢复的源版本自身也完好保留（本函数不再为其建档）。
+ *
+ * 宿主的 VersionHistoryPanel.onRestore 可直接调用本函数，无需自行编排。
+ *
+ * @param opts.versionName 可选：为恢复产生的新 head 命名（透传给 save，
+ *   命名版本不受 auto 保留策略治理）。
+ * @returns 新 head 的 id 与 revision。
+ * @throws GraphPersistenceError('NOT_FOUND') 图或版本不存在时。
+ */
+export declare function restoreVersion(adapter: GraphPersistenceAdapter, id: string, revision: string, opts?: {
+    versionName?: string;
+}): Promise<{
+    id: string;
+    revision: string;
+}>;

package/dist/shell/types.d.ts

@@ -0,0 +1,20 @@
+import { DecisionGraphType, Simulation } from '@republicroad/seal-editor';
+import { AuthAdapter } from '../lib/auth/adapter';
+import { CustomNodeSchemaSource } from '../lib/custom-node-schema-source';
+import { GraphPersistenceAdapter } from './persistence';
+export interface ShellSimulateResult {
+    simulation: Simulation;
+    /** 失败时的人类可读错误摘要(供宿主 toast/提示)；成功时为 undefined */
+    errorMessage?: string;
+}
+export type SimulateHandler = (graph: DecisionGraphType, context: unknown) => Promise<ShellSimulateResult>;
+export interface EditorShellOptions {
+    /** 自定义节点 schema 来源：默认同源 /api/custom-nodes/schema，可传 URL 或加载函数 */
+    schemaSource?: CustomNodeSchemaSource;
+    /** 鉴权适配器：默认 anonymous(无用户) */
+    authAdapter?: AuthAdapter;
+    /** 模拟执行实现：默认同源 POST /api/simulate；宿主可注入本地 WASM 引擎或远程服务 */
+    simulate?: SimulateHandler;
+    /** 图持久化适配器：未提供时 shell 回退到浏览器本地文件(File System Access API) */
+    persistence?: GraphPersistenceAdapter;
+}

package/dist/skin/__tests__/apply.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/skin/apply.d.ts

@@ -0,0 +1,7 @@
+import { CustomNodeSpec } from '../lib/custom-node-registry';
+import { NodeUiOverride } from './types';
+/**
+ * 按节点 kind 应用 UI 槽位覆写：仅替换显式给出的槽位，其余字段（kind/displayName/
+ * generateNode/inferTypes…）与未命中 kind 的节点保持原样。纯函数，不改入参。
+ */
+export declare function applyNodeOverrides(nodes: CustomNodeSpec[], overrides?: Record<string, NodeUiOverride>): CustomNodeSpec[];

package/dist/skin/layout.d.ts

@@ -0,0 +1,17 @@
+import { ToolbarItem } from '@republicroad/seal-editor';
+import { SkinSlotHostContext, SkinToolbarLayout } from './types';
+/** 槽位排序：order 数组序优先，未列出者按字典序排后（toolbar/panels 共用语义） */
+export declare const orderSlotEntries: <T>(entries: [string, T][], order: string[] | undefined) => [string, T][];
+/** 裸名槽位 id dev-warn 并补 host: 前缀（规格稿 §6-2 命名空间） */
+export declare const ensureHostPrefix: (id: string) => string;
+/**
+ * skin.toolbar 槽位 → kernel ToolbarItem[]（S005 P1 映射纯函数）。
+ *
+ * - 无槽位返回 undefined（零注入透传，SkinnedDecisionGraph 不改写宿主 props）
+ * - 裸名 id dev-warn 并自动补 `host:` 前缀（规格稿 §6-2 命名空间）
+ * - order 数组序优先，未列出者按字典序排在之后（规格稿 §4）
+ * - 注入项全部落在缺省独立组：聚在最右分隔线后（规格稿 §10-1 宿主裁决）
+ */
+export declare function mapToolbarSlots(layout: SkinToolbarLayout | undefined, host: SkinSlotHostContext): ToolbarItem[] | undefined;
+/** 右缘面板槽位的有序 id 列表（无槽位返回 undefined；裸名同样 dev-warn 补前缀） */
+export declare function mapPanelSlotIds(layout: SkinToolbarLayout | undefined): string[] | undefined;