@svadmin/surface 0.8.19 → 0.10.0

package/dist/svar.d.ts

@@ -0,0 +1,4 @@
+export { default as SvarSurfaceProvider } from './components/SvarSurfaceProvider.svelte';
+export { createSvarSurfaceCatalog } from './svar-catalog.js';
+export { svarGridDefinition, svarGridPropsSchema } from './svar-schema.js';
+export type { SvarGridProps } from './svar-schema.js';

package/dist/svar.js

@@ -0,0 +1,3 @@
+export { default as SvarSurfaceProvider } from './components/SvarSurfaceProvider.svelte';
+export { createSvarSurfaceCatalog } from './svar-catalog.js';
+export { svarGridDefinition, svarGridPropsSchema } from './svar-schema.js';

package/dist/svelte.d.ts

@@ -1,5 +1,7 @@
 export { default as SurfaceRenderer } from './components/SurfaceRenderer.svelte';
-export type { SurfaceRendererError, SurfaceRendererProps, } from './components/SurfaceRenderer.svelte';
+export type { SurfaceRendererError, SurfaceRendererProps } from './components/SurfaceRenderer.svelte';
+export { default as SurfaceEditPreview } from './components/SurfaceEditPreview.svelte';
+export type { SurfaceEditPreviewProps } from './components/SurfaceEditPreview.svelte';
 export type { SurfaceMessages } from './localization.js';
-export { DEFAULT_SURFACE_CATALOG_VERSION, defaultSurfaceCatalog, defineSurfaceCatalog, } from './catalog.js';
+export { DEFAULT_SURFACE_CATALOG_VERSION, STYLED_SURFACE_CATALOG_VERSION, styledSurfaceCatalog, defaultSurfaceCatalog, defineSurfaceCatalog, } from './catalog.js';
 export type { SurfaceRenderCatalog, SurfaceWidgetRegistration, SurfaceWidgetRendererProps, } from './catalog.js';

package/dist/svelte.js

@@ -1,2 +1,3 @@
 export { default as SurfaceRenderer } from './components/SurfaceRenderer.svelte';
-export { DEFAULT_SURFACE_CATALOG_VERSION, defaultSurfaceCatalog, defineSurfaceCatalog, } from './catalog.js';
+export { default as SurfaceEditPreview } from './components/SurfaceEditPreview.svelte';
+export { DEFAULT_SURFACE_CATALOG_VERSION, STYLED_SURFACE_CATALOG_VERSION, styledSurfaceCatalog, defaultSurfaceCatalog, defineSurfaceCatalog, } from './catalog.js';

package/dist/types.d.ts

@@ -88,11 +88,15 @@ export interface SurfaceResourcePolicy {
 export interface SurfacePolicy {
     readonly resources: Readonly<Record<string, SurfaceResourcePolicy>>;
 }
-export type SurfaceCatalogDataKind = 'none' | 'scalar' | 'items';
+export type SurfaceCatalogDataKind = 'none' | 'scalar' | 'items' | 'record';
 export interface SurfaceWidgetDefinition {
     readonly type: string;
     readonly dataKind: SurfaceCatalogDataKind;
     readonly propsSchema: TSchema;
+    /** 由可信目录提供，用于生成 AI 使用说明；不来自模型输出。 */
+    readonly description?: string;
+    /** 参数示例必须通过同一 propsSchema 校验。不要放入真实用户数据。 */
+    readonly examples?: readonly JsonObject[];
     /** Fields read from the bound record, supplied by a trusted Catalog. */
     readonly getReferencedFields?: (props: JsonObject) => readonly string[];
 }

package/dist/validation.js

@@ -1,111 +1,11 @@
-import { Type } from "@sinclair/typebox";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { Value } from "@sinclair/typebox/value";
 import { decodedJsonPointerToken, jsonPointer, jsonValueIssue } from "./json.js";
+import { surfaceSpecSchema } from './schema.js';
 import { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION, } from "./types.js";
-const idSchema = Type.String({
-    minLength: 1,
-    maxLength: SURFACE_LIMITS.maxIdLength,
-    pattern: "^[A-Za-z][A-Za-z0-9_-]*$",
-});
-const fieldSchema = Type.String({
-    minLength: 1,
-    maxLength: SURFACE_LIMITS.maxIdLength,
-});
-const jsonPrimitiveSchema = Type.Union([
-    Type.String(),
-    Type.Number(),
-    Type.Boolean(),
-    Type.Null(),
-]);
-const surfaceFilterSchema = Type.Union([
-    Type.Object({
-        field: fieldSchema,
-        operator: Type.Union([
-            Type.Literal("eq"),
-            Type.Literal("ne"),
-            Type.Literal("lt"),
-            Type.Literal("lte"),
-            Type.Literal("gt"),
-            Type.Literal("gte"),
-            Type.Literal("contains"),
-            Type.Literal("startswith"),
-            Type.Literal("endswith"),
-        ]),
-        value: jsonPrimitiveSchema,
-    }, { additionalProperties: false }),
-    Type.Object({
-        field: fieldSchema,
-        operator: Type.Union([
-            Type.Literal("in"),
-            Type.Literal("nin"),
-        ]),
-        value: Type.Array(jsonPrimitiveSchema),
-    }, { additionalProperties: false }),
-    Type.Object({
-        field: fieldSchema,
-        operator: Type.Union([
-            Type.Literal("null"),
-            Type.Literal("nnull"),
-        ]),
-    }, { additionalProperties: false }),
-]);
-const resourceListSchema = Type.Object({
-    id: idSchema,
-    type: Type.Literal("resource-list"),
-    resource: idSchema,
-    pageSize: Type.Optional(Type.Integer({ minimum: 1 })),
-    sorters: Type.Optional(Type.Array(Type.Object({
-        field: fieldSchema,
-        order: Type.Union([Type.Literal("asc"), Type.Literal("desc")]),
-    }, { additionalProperties: false }))),
-    filters: Type.Optional(Type.Array(surfaceFilterSchema)),
-}, { additionalProperties: false });
-const resourceOneSchema = Type.Object({
-    id: idSchema,
-    type: Type.Literal("resource-one"),
-    resource: idSchema,
-    recordId: Type.Union([Type.String(), Type.Number()]),
-}, { additionalProperties: false });
-const surfaceSpecSchema = Type.Object({
-    schemaVersion: Type.String(),
-    catalogVersion: Type.String({ minLength: 1 }),
-    surfaceId: idSchema,
-    title: Type.String({ minLength: 1, maxLength: SURFACE_LIMITS.maxTitleLength }),
-    layout: Type.Object({
-        type: Type.Literal("grid"),
-        columns: Type.Literal(12),
-        gap: Type.Optional(Type.Union([
-            Type.Literal("sm"),
-            Type.Literal("md"),
-            Type.Literal("lg"),
-        ])),
-    }, { additionalProperties: false }),
-    dataSources: Type.Array(Type.Union([resourceListSchema, resourceOneSchema])),
-    widgets: Type.Array(Type.Object({
-        id: idSchema,
-        type: idSchema,
-        props: Type.Record(Type.String(), Type.Unknown()),
-        binding: Type.Optional(Type.Object({
-            sourceId: idSchema,
-            pointer: Type.Optional(Type.String()),
-        }, { additionalProperties: false })),
-        placement: Type.Optional(Type.Object({
-            columnSpan: Type.Optional(Type.Integer({ minimum: 1, maximum: 12 })),
-        }, { additionalProperties: false })),
-    }, { additionalProperties: false })),
-}, { additionalProperties: false });
 const compiledSurfaceSpec = TypeCompiler.Compile(surfaceSpecSchema);
 const forbiddenPropertyNames = new Set([
-    "class",
-    "className",
-    "color",
-    "href",
-    "html",
-    "innerHTML",
-    "src",
-    "style",
-    "url",
+    "class", "className", "color", "href", "html", "innerHTML", "src", "style", "url",
 ]);
 const strictSchemaProbeKey = "__surface_unknown_property_probe__";
 function invalidJsonIssue(pathSegments, message) {
@@ -197,10 +97,15 @@ function propsContainForbiddenKey(props) {
 }
 function referencedFieldIssue(widget, widgetIndex, definition, source, policy) {
     if (!definition.getReferencedFields)
-        return null;
+        return definition.dataKind === 'record'
+            ? { code: 'invalid_widget_props', path: `/widgets/${widgetIndex}/props`, message: 'Record widgets require an explicit field selector', widgetId: widget.id }
+            : null;
     let referencedFields;
     try {
         referencedFields = definition.getReferencedFields(widget.props);
+        if (!Array.isArray(referencedFields) || (definition.dataKind === 'record' && referencedFields.length === 0)) {
+            throw new Error('Record fields must be explicit');
+        }
     }
     catch {
         return {
@@ -211,13 +116,13 @@ function referencedFieldIssue(widget, widgetIndex, definition, source, policy) {
         };
     }
     const readableFields = resourcePolicyFor(policy, source.resource)?.readFields ?? [];
-    const deniedField = referencedFields.find((field) => (typeof field !== "string" || !readableFields.includes(field)));
-    return deniedField === undefined
+    const deniedIndex = referencedFields.findIndex((field) => (typeof field !== "string" || !readableFields.includes(field)));
+    return deniedIndex === -1
         ? null
         : {
             code: "field_denied",
             path: `/widgets/${widgetIndex}/props`,
-            message: `Field "${String(deniedField)}" is not readable`,
+            message: `Field "${String(referencedFields[deniedIndex])}" is not readable`,
             widgetId: widget.id,
             sourceId: source.id,
         };
@@ -286,8 +191,9 @@ function widgetIssue(widget, widgetIndex, definition, sources, policy) {
     const resourceOneField = source.type === "resource-one" ? resourceOnePointerField(pointer) : null;
     const pointerIsValid = definition.dataKind === "items"
         ? source.type === "resource-list" && pointer === "/items"
-        : (source.type === "resource-list" && pointer === "/total")
-            || resourceOneField !== null;
+        : definition.dataKind === 'record'
+            ? source.type === 'resource-one' && pointer === ''
+            : definition.dataKind === 'scalar' && ((source.type === "resource-list" && pointer === "/total") || resourceOneField !== null);
     if (!pointerIsValid) {
         return {
             code: "invalid_binding_pointer",

package/dist/wire.d.ts

@@ -0,0 +1,13 @@
+import type { SurfaceValidationIssue } from './types.js';
+export type SurfaceWireResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SurfaceValidationIssue[];
+};
+export declare function surfaceWireError(message: string, code?: 'invalid_json' | 'limit_exceeded'): Extract<SurfaceWireResult, {
+    ok: false;
+}>;
+/** 先检查大小和 JSON 安全性，再进入 TypeBox；返回独立副本，避免校验后被调用方改写。 */
+export declare function parseSurfaceJson(input: unknown, legacyFences?: boolean): SurfaceWireResult;

package/dist/wire.js

@@ -0,0 +1,30 @@
+import { jsonPointer, jsonValueIssue } from './json.js';
+import { SURFACE_AGENT_LIMITS } from './agent-contract.js';
+export function surfaceWireError(message, code = 'invalid_json') {
+    return { ok: false, issues: [{ code, path: '', message }] };
+}
+/** 先检查大小和 JSON 安全性，再进入 TypeBox；返回独立副本，避免校验后被调用方改写。 */
+export function parseSurfaceJson(input, legacyFences = false) {
+    try {
+        let candidate = input;
+        if (typeof input === 'string') {
+            if (input.length > SURFACE_AGENT_LIMITS.maxInputCharacters)
+                return surfaceWireError('Surface input is too large', 'limit_exceeded');
+            const source = input.trim();
+            const fenced = legacyFences
+                ? /```(?:json)?\s*([\s\S]*?)```/iu.exec(source)
+                : /^```(?:json)?\s*([\s\S]*?)```$/iu.exec(source);
+            candidate = JSON.parse(fenced?.[1] ?? source);
+        }
+        const issue = jsonValueIssue(candidate);
+        if (issue)
+            return { ok: false, issues: [{ code: 'invalid_json', path: jsonPointer(issue.path), message: issue.message }] };
+        const serialized = JSON.stringify(candidate);
+        if (serialized.length > SURFACE_AGENT_LIMITS.maxInputCharacters)
+            return surfaceWireError('Surface input is too large', 'limit_exceeded');
+        return { ok: true, value: JSON.parse(serialized) };
+    }
+    catch {
+        return surfaceWireError('Surface input must be valid, safely inspectable JSON');
+    }
+}

package/dist/workflows/action-contracts.d.ts

@@ -0,0 +1,7 @@
+import type { SurfaceActionDescriptor, SurfaceRegisteredAction } from './types.js';
+/** Only the form subset actually rendered by JsonSchemaForm is advertised.
+ * No refs, transforms, secret inputs, arbitrary unions or computed fields.
+ */
+export declare function validateSurfaceActionDescriptor(action: SurfaceActionDescriptor): void;
+/** One immutable schema drives the form and the server validation. */
+export declare function defineSurfaceAction(action: Omit<SurfaceRegisteredAction, 'validateInput'>): SurfaceRegisteredAction;

package/dist/workflows/action-contracts.js

@@ -0,0 +1,54 @@
+import { Value } from '@sinclair/typebox/value';
+import { surfaceSchemaToJson } from '../agent-contract.js';
+/** Only the form subset actually rendered by JsonSchemaForm is advertised.
+ * No refs, transforms, secret inputs, arbitrary unions or computed fields.
+ */
+export function validateSurfaceActionDescriptor(action) {
+    if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u.test(action.id) || !action.version || action.version.length > 64
+        || !action.label.trim() || action.label.length > 120 || !['confirm', 'four-eyes'].includes(action.approval)) {
+        throw new Error('Invalid Surface action contract');
+    }
+    surfaceSchemaToJson(action.inputSchema);
+    let fields = 0;
+    function visit(schema, depth) {
+        if (++fields > 128 || depth > 8)
+            throw new Error('Surface form schema exceeds supported limits');
+        if (schema['anyOf'] || schema['oneOf'] || schema['allOf'] || schema['not'] || schema['if'] || schema.writeOnly
+            || !['object', 'array', 'string', 'number', 'integer', 'boolean'].includes(schema['type'])) {
+            throw new Error('Unsupported Surface form schema; use a registered custom widget instead');
+        }
+        if (schema['type'] === 'object') {
+            if (schema['additionalProperties'] !== false || !schema['properties'])
+                throw new Error('Surface actions require closed object schemas');
+            for (const [name, child] of Object.entries(schema['properties'])) {
+                if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(name))
+                    throw new Error('Invalid Surface form field');
+                visit(child, depth + 1);
+            }
+        }
+        else if (schema['type'] === 'array') {
+            if (!schema['items'] || Array.isArray(schema['items']))
+                throw new Error('Surface forms require homogeneous array items');
+            visit(schema['items'], depth + 1);
+        }
+    }
+    if (action.inputSchema['type'] !== 'object')
+        throw new Error('Surface actions require an object input schema');
+    visit(action.inputSchema, 0);
+}
+function snapshot(value) {
+    if (Array.isArray(value))
+        return Object.freeze(value.map(snapshot));
+    if (value && typeof value === 'object') {
+        return Object.freeze(Object.fromEntries(Reflect.ownKeys(value).map((key) => [key, snapshot(Reflect.get(value, key))])));
+    }
+    return value;
+}
+/** One immutable schema drives the form and the server validation. */
+export function defineSurfaceAction(action) {
+    validateSurfaceActionDescriptor(action);
+    if (typeof action.authorize !== 'function' || typeof action.execute !== 'function')
+        throw new Error('Surface actions require authorization and execution handlers');
+    const inputSchema = snapshot(action.inputSchema);
+    return Object.freeze({ ...action, inputSchema, validateInput: (input) => Value.Check(inputSchema, input) });
+}

package/dist/workflows/catalog.d.ts

@@ -0,0 +1,20 @@
+import type { SurfaceCatalog, SurfaceWidgetDefinition, JsonObject } from '../types.js';
+import type { SurfaceActionDescriptor } from './types.js';
+export declare const surfaceAppearanceSchema: import("@sinclair/typebox").TObject<{
+    tone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"compact" | "comfortable">[]>>;
+}>;
+export declare function withoutSurfaceAppearance(props: JsonObject): JsonObject;
+/** Adds frame-level semantic appearance to every registered widget without
+ * leaking presentation props into its existing component implementation.
+ * Internal table cell density remains the table's own semantic prop.
+ */
+export declare function withSurfaceAppearance<T extends SurfaceWidgetDefinition>(catalog: {
+    version: string;
+    widgets: readonly T[];
+}): {
+    version: string;
+    widgets: T[];
+};
+/** DOM-free definitions reused by server validation, prompts and Svelte catalog. */
+export declare function createInteractiveSurfaceDefinitions(actions: readonly SurfaceActionDescriptor[], base: SurfaceCatalog): SurfaceCatalog;

package/dist/workflows/catalog.js

@@ -0,0 +1,50 @@
+import { Type } from '@sinclair/typebox';
+import { surfaceDesignContract } from '../design-contract.js';
+import { validateSurfaceActionDescriptor } from './action-contracts.js';
+export const surfaceAppearanceSchema = Type.Object({
+    tone: Type.Optional(Type.Union(surfaceDesignContract.metric.tone.map((tone) => Type.Literal(tone)))),
+    density: Type.Optional(Type.Union(surfaceDesignContract.metric.density.map((density) => Type.Literal(density)))),
+}, { additionalProperties: false });
+export function withoutSurfaceAppearance(props) {
+    return Object.fromEntries(Object.entries(props).filter(([key]) => key !== 'appearance'));
+}
+function withAppearance(schema) {
+    if (Array.isArray(schema['anyOf']))
+        return { ...schema, anyOf: schema['anyOf'].map((part) => withAppearance(part)) };
+    if (schema['type'] !== 'object' || schema['additionalProperties'] !== false || !schema['properties'] || 'appearance' in schema['properties']) {
+        throw new Error('Surface appearance requires closed object schemas without a reserved appearance property');
+    }
+    return { ...schema, properties: { ...schema['properties'], appearance: Type.Optional(surfaceAppearanceSchema) } };
+}
+/** Adds frame-level semantic appearance to every registered widget without
+ * leaking presentation props into its existing component implementation.
+ * Internal table cell density remains the table's own semantic prop.
+ */
+export function withSurfaceAppearance(catalog) {
+    return { version: `${catalog.version}+appearance/v1`, widgets: catalog.widgets.map((widget) => ({
+            ...widget, presentation: 'surface-appearance/v1', propsSchema: withAppearance(widget.propsSchema),
+            ...(widget.getReferencedFields ? { getReferencedFields: (props) => widget.getReferencedFields?.(withoutSurfaceAppearance(props)) ?? [] } : {}),
+        })) };
+}
+/** DOM-free definitions reused by server validation, prompts and Svelte catalog. */
+export function createInteractiveSurfaceDefinitions(actions, base) {
+    const firstAction = actions[0];
+    if (!firstAction || actions.length > 32)
+        throw new Error('Register between one and 32 Surface actions');
+    if (new Set(actions.map((action) => action.id)).size !== actions.length)
+        throw new Error('Duplicate Surface action');
+    if (base.widgets.some((widget) => widget.type === 'resource-form'))
+        throw new Error('resource-form is reserved by the interactive catalog');
+    for (const action of actions)
+        validateSurfaceActionDescriptor(action);
+    const actionIds = actions.map((action) => Type.Literal(action.id, { description: `${action.label}; version ${action.version}; approval ${action.approval}` }));
+    return withSurfaceAppearance({ version: `${base.version}+forms/v1`, widgets: [...base.widgets, {
+                type: 'resource-form', dataKind: 'none',
+                description: 'Nested resource form backed by a trusted action input schema. Only a user submission can create a proposal. Approval and execution are separate server-authorized steps.',
+                propsSchema: Type.Object({
+                    actionId: Type.Union(actionIds),
+                    title: Type.Optional(Type.String({ minLength: 1, maxLength: 120 })),
+                }, { additionalProperties: false }),
+                examples: [{ actionId: firstAction.id }],
+            }] });
+}

package/dist/workflows/client.d.ts

@@ -0,0 +1,45 @@
+import type { JsonObject } from '../types.js';
+import type { SurfaceActionProposal, SurfaceActionDescriptor } from './types.js';
+/** HTTP bindings are trusted host code. Authenticate and apply CSRF/origin checks
+ * on every server route. Never expose service identity as a model-editable field.
+ */
+export interface SurfaceWorkflowTransport {
+    propose(input: {
+        actionId: string;
+        args: JsonObject;
+        surfaceId: string;
+        surfaceRevision: number;
+        requestKey: string;
+    }, signal: AbortSignal): Promise<SurfaceActionProposal>;
+    inspect(id: string, signal: AbortSignal): Promise<SurfaceActionProposal>;
+    approve(id: string, digest: string, signal: AbortSignal): Promise<SurfaceActionProposal>;
+    reject(id: string, digest: string, signal: AbortSignal): Promise<SurfaceActionProposal>;
+    execute(id: string, digest: string, signal: AbortSignal): Promise<SurfaceActionProposal>;
+}
+export interface SurfaceWorkflowClientScope {
+    readonly scopeKey: string;
+    readonly surfaceId: string;
+    readonly revision: number;
+    readonly enabled: boolean;
+    readonly transport: SurfaceWorkflowTransport;
+}
+export type SurfaceWorkflowClientState = {
+    readonly busy: boolean;
+    readonly proposal?: SurfaceActionProposal;
+    readonly error?: string;
+};
+/** Independent of Svelte so races and late responses can be tested directly. */
+export declare function createSurfaceFormController(options: {
+    action: SurfaceActionDescriptor;
+    getScope: () => SurfaceWorkflowClientScope;
+    onState: (state: SurfaceWorkflowClientState) => void;
+    onCommitted?: (proposal: SurfaceActionProposal) => void;
+}): {
+    submit(args: JsonObject): Promise<void>;
+    confirm(): Promise<void>;
+    execute(): Promise<void>;
+    refresh(): Promise<void>;
+    reject(): Promise<void>;
+    reset: () => void;
+    dispose(): void;
+};

package/dist/workflows/client.js

@@ -0,0 +1,125 @@
+/** Independent of Svelte so races and late responses can be tested directly. */
+export function createSurfaceFormController(options) {
+    let state = { busy: false };
+    let generation = 0;
+    let abort = new AbortController();
+    let disposed = false;
+    let notified;
+    let draft;
+    const action = options.action;
+    let activeScope = { ...options.getScope() };
+    function publish(next) { state = next; options.onState(next); }
+    function same(a, b) {
+        return a.scopeKey === b.scopeKey && a.surfaceId === b.surfaceId && a.revision === b.revision && a.transport === b.transport && a.enabled === b.enabled;
+    }
+    function reset() {
+        if (disposed)
+            return;
+        generation += 1;
+        draft = undefined;
+        abort.abort();
+        abort = new AbortController();
+        activeScope = { ...options.getScope() };
+        publish({ busy: false });
+    }
+    function syncScope() {
+        const next = { ...options.getScope() };
+        if (!same(activeScope, next))
+            reset();
+        return next;
+    }
+    async function run(work) {
+        const scope = syncScope();
+        if (disposed || state.busy || !scope.enabled)
+            return;
+        const ticket = ++generation;
+        publish({ busy: true, ...(state.proposal ? { proposal: state.proposal } : {}) });
+        try {
+            // 宿主状态回调可能同步 reset/dispose；不得继续派发已失效请求。
+            if (disposed || ticket !== generation)
+                return;
+            if (!same(scope, options.getScope())) {
+                reset();
+                return;
+            }
+            const proposal = await work(scope, abort.signal);
+            if (disposed || ticket !== generation)
+                return;
+            if (!same(scope, options.getScope())) {
+                reset();
+                return;
+            }
+            if (proposal.actionId !== action.id || proposal.actionVersion !== action.version || proposal.surfaceId !== scope.surfaceId || proposal.surfaceRevision !== scope.revision) {
+                throw new Error('Proposal does not belong to the active form');
+            }
+            publish({ busy: false, proposal });
+            // 成功状态发布也可能切换会话或启动新请求，旧完成回调必须失效。
+            if (disposed || ticket !== generation)
+                return;
+            if (!same(scope, options.getScope())) {
+                reset();
+                return;
+            }
+            if (proposal.status === 'succeeded' && proposal.id !== notified) {
+                notified = proposal.id;
+                try {
+                    options.onCommitted?.(proposal);
+                }
+                catch { /* A host refresh failure must not misreport a successful write. */ }
+            }
+        }
+        catch {
+            if (disposed || ticket !== generation)
+                return;
+            if (!same(scope, options.getScope())) {
+                reset();
+                return;
+            }
+            publish({ ...state, busy: false, error: 'Operation failed. Check status before retrying.' });
+        }
+    }
+    return {
+        submit(args) {
+            syncScope();
+            if (disposed || state.busy || state.proposal || !options.getScope().enabled)
+                return Promise.resolve();
+            const captured = structuredClone(args);
+            const serialized = JSON.stringify(captured);
+            if (draft?.serialized !== serialized)
+                draft = { serialized, requestKey: crypto.randomUUID() };
+            const requestKey = draft.requestKey;
+            return run((scope, signal) => scope.transport.propose({ actionId: action.id, args: captured,
+                surfaceId: scope.surfaceId, surfaceRevision: scope.revision, requestKey }, signal));
+        },
+        confirm() {
+            syncScope();
+            const p = state.proposal;
+            if (!p || p.status !== 'pending' || p.approval !== 'confirm')
+                return Promise.resolve();
+            return run((scope, signal) => scope.transport.approve(p.id, p.digest, signal));
+        },
+        execute() {
+            syncScope();
+            const p = state.proposal;
+            if (!p || p.status !== 'approved')
+                return Promise.resolve();
+            return run((scope, signal) => scope.transport.execute(p.id, p.digest, signal));
+        },
+        refresh() {
+            syncScope();
+            const p = state.proposal;
+            if (!p)
+                return Promise.resolve();
+            return run((scope, signal) => scope.transport.inspect(p.id, signal));
+        },
+        reject() {
+            syncScope();
+            const p = state.proposal;
+            if (!p || !['pending', 'approved'].includes(p.status))
+                return Promise.resolve();
+            return run((scope, signal) => scope.transport.reject(p.id, p.digest, signal));
+        },
+        reset,
+        dispose() { disposed = true; generation += 1; abort.abort(); },
+    };
+}

package/dist/workflows/context.d.ts

@@ -0,0 +1,9 @@
+import type { SurfaceActionDescriptor, SurfaceActionProposal } from './types.js';
+import type { SurfaceWorkflowClientScope } from './client.js';
+export declare const SURFACE_WORKFLOW_CONTEXT: unique symbol;
+export interface SurfaceWorkflowHost {
+    getScope(): SurfaceWorkflowClientScope;
+    getAction(id: string): SurfaceActionDescriptor | undefined;
+    committed(proposal: SurfaceActionProposal): void;
+}
+export declare function getSurfaceWorkflowHost(): SurfaceWorkflowHost | undefined;

package/dist/workflows/context.js

@@ -0,0 +1,5 @@
+import { getContext } from 'svelte';
+export const SURFACE_WORKFLOW_CONTEXT = Symbol('svadmin.surface.workflow');
+export function getSurfaceWorkflowHost() {
+    return getContext(SURFACE_WORKFLOW_CONTEXT);
+}

package/dist/workflows/openui-guard.d.ts

@@ -0,0 +1,19 @@
+/** Strict, bounded framing for the static OpenUI subset consumed by Surface.
+ * This is NOT a replacement for the upstream parser. It prevents unsupported
+ * expressions from reaching that parser and only releases complete statements.
+ */
+export declare const OPENUI_LIMITS: Readonly<{
+    characters: 131072;
+    statementCharacters: 32768;
+    statements: 128;
+    depth: 32;
+    tokens: 12000;
+}>;
+export declare class SurfaceOpenUIError extends Error {
+    readonly code: 'syntax' | 'limit' | 'unsupported' | 'invalid_surface';
+    constructor(code: 'syntax' | 'limit' | 'unsupported' | 'invalid_surface', message: string);
+}
+export declare function createOpenUIStatementGuard(callNames: readonly string[]): {
+    push(chunk: string): readonly string[];
+    finish(): readonly string[];
+};