@svadmin/surface 0.8.6 → 0.9.0

package/dist/components/SvarGridWidget.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import SvarDataGrid from '@svadmin/ui/components/SvarDataGrid.svelte';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { SVAR_SURFACE_CONTEXT, type SvarSurfaceContext } from '../svar-context.js';
+  import { decodeSvarGridProps } from '../svar-schema.js';
+  import { asRecordArray } from '../widget-data.js';
+  import { resolveSurfaceMessages } from '../localization.js';
+
+  let { widgetId, props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const host = getContext<SvarSurfaceContext | undefined>(SVAR_SURFACE_CONTEXT);
+  const labels = $derived(resolveSurfaceMessages(locale, messages));
+  const config = $derived(decodeSvarGridProps(props));
+  const records = $derived(data.status === 'ready' ? asRecordArray(data.value) : undefined);
+  const columns = $derived(config.columns.map(column => ({
+    key: column.field, label: column.label,
+    ...(column.width === undefined ? {} : { width: column.width }),
+    ...(column.format === undefined ? {} : { format: column.format }),
+  })));
+  const Grid = $derived(host?.Grid);
+  const Theme = $derived(host?.Theme);
+</script>
+
+<section aria-labelledby="svar-surface-{widgetId}" class="surface-data-grid">
+  <h3 id="svar-surface-{widgetId}">{config.title}</h3>
+  {#if !Grid || !Theme}
+    <p role="alert">{locale.startsWith('zh') ? '宿主尚未配置 SVAR 引擎' : 'The host has not configured the SVAR engine'}</p>
+  {:else if data.status === 'error'}
+    <p role="alert">{data.error.message}</p>
+  {:else if data.status === 'unbound' || (records && !records.ok)}
+    <p role="alert">{labels.tableInvalidData}</p>
+  {:else}
+    <SvarDataGrid {Grid} {Theme} {columns} items={records?.ok ? records.value : []}
+      primaryKey={config.rowKey ?? 'id'} height={config.height ?? 360} density={config.density ?? 'comfortable'}
+      freezeLeft={config.freezeLeft ?? 0} freezeRight={config.freezeRight ?? 0}
+      loading={data.status === 'loading'} label={config.title} {locale}
+      scopeKey={`${host?.scopeKey ?? 0}:${widgetId}:${'sourceId' in data ? data.sourceId : ''}`}
+      loadingLabel={labels.tableLoading} emptyLabel={config.emptyLabel ?? labels.tableNoRecords}
+      selectable={false} />
+  {/if}
+</section>
+
+<style>
+  .surface-data-grid { min-width: 0; padding: 1rem; background: var(--card, Canvas); color: var(--foreground, CanvasText); border: 1px solid var(--border, GrayText); border-radius: var(--radius, 8px); }
+  h3 { margin: 0 0 0.75rem; font-size: 1rem; }
+  [role='alert'] { color: var(--destructive, CanvasText); }
+</style>

package/dist/components/SvarGridWidget.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { SurfaceWidgetRendererProps } from '../catalog.js';
+declare const SvarGridWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
+type SvarGridWidget = ReturnType<typeof SvarGridWidget>;
+export default SvarGridWidget;

package/dist/components/SvarSurfaceProvider.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import { setContext, type Snippet } from 'svelte';
+  import { SVAR_SURFACE_CONTEXT, type SvarSurfaceContext } from '../svar-context.js';
+  let { Grid, Theme, scopeKey = 0, children }: {
+    Grid: SvarSurfaceContext['Grid']; Theme: SvarSurfaceContext['Theme']; scopeKey?: string | number; children: Snippet;
+  } = $props();
+  setContext<SvarSurfaceContext>(SVAR_SURFACE_CONTEXT, {
+    get Grid() { return Grid; }, get Theme() { return Theme; }, get scopeKey() { return scopeKey; },
+  });
+</script>
+
+{@render children()}

package/dist/components/SvarSurfaceProvider.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type Snippet } from 'svelte';
+import { type SvarSurfaceContext } from '../svar-context.js';
+type $$ComponentProps = {
+    Grid: SvarSurfaceContext['Grid'];
+    Theme: SvarSurfaceContext['Theme'];
+    scopeKey?: string | number;
+    children: Snippet;
+};
+declare const SvarSurfaceProvider: import("svelte").Component<$$ComponentProps, {}, "">;
+type SvarSurfaceProvider = ReturnType<typeof SvarSurfaceProvider>;
+export default SvarSurfaceProvider;

package/dist/edits.d.ts

@@ -0,0 +1,57 @@
+import type { SurfaceAgentMessage } from './agent.js';
+import type { JsonObject, SurfaceCatalog, SurfaceDataSource, SurfaceGridLayout, SurfacePolicy, SurfaceSpec, SurfaceValidationIssue, SurfaceWidget } from './types.js';
+export declare const SURFACE_EDIT_SCHEMA_VERSION: "surface-edit/v1";
+export declare const SURFACE_EDIT_LIMITS: {
+    readonly maxOperations: 64;
+};
+export type SurfaceEditOperation = {
+    readonly op: 'set-title';
+    readonly value: string;
+} | {
+    readonly op: 'set-layout';
+    readonly value: SurfaceGridLayout;
+} | {
+    readonly op: 'upsert-widget';
+    readonly widget: SurfaceWidget;
+} | {
+    readonly op: 'remove-widget';
+    readonly id: string;
+} | {
+    readonly op: 'upsert-source';
+    readonly source: SurfaceDataSource;
+} | {
+    readonly op: 'remove-source';
+    readonly id: string;
+} | {
+    readonly op: 'reorder-widgets';
+    readonly ids: readonly string[];
+};
+export interface SurfaceEditProposal {
+    readonly schemaVersion: typeof SURFACE_EDIT_SCHEMA_VERSION;
+    readonly catalogVersion: string;
+    readonly surfaceId: string;
+    readonly baseRevision: number;
+    readonly operations: readonly SurfaceEditOperation[];
+}
+export interface SurfaceRevision {
+    readonly revision: number;
+    readonly spec: SurfaceSpec;
+}
+export interface SurfaceEditIssue extends Omit<SurfaceValidationIssue, 'code'> {
+    readonly code: SurfaceValidationIssue['code'] | 'revision_conflict' | 'invalid_edit';
+}
+export type SurfaceRevisionResult = {
+    readonly ok: true;
+    readonly value: SurfaceRevision;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SurfaceEditIssue[];
+};
+export declare function createSurfaceRevision(spec: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy, revision?: number): SurfaceRevisionResult;
+/**
+ * 只生成下一版候选快照，不保存、不渲染、不访问 DataProvider。
+ * 服务端保存时仍必须对 revision 做原子 compare-and-swap，并重新授权。
+ */
+export declare function applySurfaceEditProposal(current: SurfaceRevision, input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceRevisionResult;
+export declare function createSurfaceEditSchema(): JsonObject;
+export declare function buildSurfaceEditMessages(request: string, current: SurfaceRevision, catalog: SurfaceCatalog, policy: SurfacePolicy): readonly SurfaceAgentMessage[];

package/dist/edits.js

@@ -0,0 +1,166 @@
+import { Type } from '@sinclair/typebox';
+import { TypeCompiler } from '@sinclair/typebox/compiler';
+import { createSurfaceCatalogManifest, SURFACE_AGENT_LIMITS, surfaceSchemaToJson } from './agent-contract.js';
+import { surfaceIdSchema, surfaceLayoutSchema, surfaceListSourceSchema, surfaceOneSourceSchema, surfaceSpecSchema, surfaceWidgetSchema, } from './schema.js';
+import { SURFACE_LIMITS } from './types.js';
+import { validateSurfaceSpec } from './validation.js';
+import { parseSurfaceJson } from './wire.js';
+export const SURFACE_EDIT_SCHEMA_VERSION = 'surface-edit/v1';
+export const SURFACE_EDIT_LIMITS = { maxOperations: 64 };
+const revisionSchema = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const editSchema = Type.Object({
+    schemaVersion: Type.Literal(SURFACE_EDIT_SCHEMA_VERSION),
+    catalogVersion: Type.String({ minLength: 1 }),
+    surfaceId: surfaceIdSchema,
+    baseRevision: revisionSchema,
+    operations: Type.Array(Type.Union([
+        Type.Object({ op: Type.Literal('set-title'), value: Type.String({ minLength: 1, maxLength: SURFACE_LIMITS.maxTitleLength }) }, { additionalProperties: false }),
+        Type.Object({ op: Type.Literal('set-layout'), value: surfaceLayoutSchema }, { additionalProperties: false }),
+        Type.Object({ op: Type.Literal('upsert-widget'), widget: surfaceWidgetSchema }, { additionalProperties: false }),
+        Type.Object({ op: Type.Literal('remove-widget'), id: surfaceIdSchema }, { additionalProperties: false }),
+        Type.Object({ op: Type.Literal('upsert-source'), source: Type.Union([surfaceListSourceSchema, surfaceOneSourceSchema]) }, { additionalProperties: false }),
+        Type.Object({ op: Type.Literal('remove-source'), id: surfaceIdSchema }, { additionalProperties: false }),
+        Type.Object({ op: Type.Literal('reorder-widgets'), ids: Type.Array(surfaceIdSchema, { maxItems: SURFACE_LIMITS.maxWidgets, uniqueItems: true }) }, { additionalProperties: false }),
+    ]), { minItems: 1, maxItems: SURFACE_EDIT_LIMITS.maxOperations }),
+}, { additionalProperties: false });
+const compiledEdit = TypeCompiler.Compile(editSchema);
+const compiledRevision = TypeCompiler.Compile(Type.Object({ revision: revisionSchema, spec: surfaceSpecSchema }, { additionalProperties: false }));
+function editError(code, path, message) {
+    return { ok: false, issues: [{ code, path, message }] };
+}
+// 输入已通过 JSON 检查。新快照独立于调用方对象，也不会冻结调用方原有状态。
+function immutableCopy(input) {
+    const copy = JSON.parse(JSON.stringify(input));
+    const pending = [copy];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current !== null && typeof current === 'object') {
+            pending.push(...Object.values(current));
+            Object.freeze(current);
+        }
+    }
+    return copy;
+}
+export function createSurfaceRevision(spec, catalog, policy, revision = 0) {
+    if (!Number.isSafeInteger(revision) || revision < 0)
+        return editError('invalid_edit', '/revision', 'Revision must be a non-negative safe integer');
+    const parsed = parseSurfaceJson(spec);
+    if (!parsed.ok)
+        return parsed;
+    const result = validateSurfaceSpec(parsed.value, catalog, policy);
+    if (!result.ok)
+        return result;
+    return { ok: true, value: immutableCopy({ revision, spec: result.value }) };
+}
+/**
+ * 只生成下一版候选快照，不保存、不渲染、不访问 DataProvider。
+ * 服务端保存时仍必须对 revision 做原子 compare-and-swap，并重新授权。
+ */
+export function applySurfaceEditProposal(current, input, catalog, policy) {
+    const parsedCurrent = parseSurfaceJson(current);
+    if (!parsedCurrent.ok)
+        return parsedCurrent;
+    if (!compiledRevision.Check(parsedCurrent.value))
+        return editError('invalid_edit', '', 'Invalid current surface revision');
+    const original = validateSurfaceSpec(parsedCurrent.value.spec, catalog, policy);
+    if (!original.ok)
+        return original;
+    const parsed = parseSurfaceJson(input);
+    if (!parsed.ok)
+        return parsed;
+    if (!compiledEdit.Check(parsed.value))
+        return editError('invalid_edit', '', 'Edit does not match the surface-edit/v1 schema');
+    const edit = parsed.value;
+    if (edit.catalogVersion !== catalog.version || edit.catalogVersion !== original.value.catalogVersion) {
+        return editError('catalog_version_mismatch', '/catalogVersion', 'Edit catalog version does not match the active catalog');
+    }
+    if (edit.surfaceId !== original.value.surfaceId)
+        return editError('invalid_edit', '/surfaceId', 'Edit targets a different surface');
+    if (edit.baseRevision !== parsedCurrent.value.revision)
+        return editError('revision_conflict', '/baseRevision', 'Edit is based on a stale surface revision');
+    if (edit.baseRevision === Number.MAX_SAFE_INTEGER)
+        return editError('invalid_edit', '/baseRevision', 'Revision counter is exhausted');
+    let title = original.value.title;
+    let layout = original.value.layout;
+    const sources = [...original.value.dataSources];
+    let widgets = [...original.value.widgets];
+    for (const [index, operation] of edit.operations.entries()) {
+        const path = `/operations/${index}`;
+        switch (operation.op) {
+            case 'set-title':
+                title = operation.value;
+                break;
+            case 'set-layout':
+                layout = operation.value;
+                break;
+            case 'upsert-widget': {
+                const target = widgets.findIndex((widget) => widget.id === operation.widget.id);
+                if (target === -1)
+                    widgets.push(operation.widget);
+                else
+                    widgets[target] = operation.widget;
+                break;
+            }
+            case 'remove-widget': {
+                const target = widgets.findIndex((widget) => widget.id === operation.id);
+                if (target === -1)
+                    return editError('invalid_edit', path, 'Cannot remove an unknown widget');
+                widgets.splice(target, 1);
+                break;
+            }
+            case 'upsert-source': {
+                const target = sources.findIndex((source) => source.id === operation.source.id);
+                if (target === -1)
+                    sources.push(operation.source);
+                else
+                    sources[target] = operation.source;
+                break;
+            }
+            case 'remove-source': {
+                const target = sources.findIndex((source) => source.id === operation.id);
+                if (target === -1)
+                    return editError('invalid_edit', path, 'Cannot remove an unknown source');
+                sources.splice(target, 1);
+                break;
+            }
+            case 'reorder-widgets': {
+                if (operation.ids.length !== widgets.length || new Set(operation.ids).size !== widgets.length) {
+                    return editError('invalid_edit', path, 'Reordering must list every widget exactly once');
+                }
+                const ordered = [];
+                for (const id of operation.ids) {
+                    const widget = widgets.find((candidate) => candidate.id === id);
+                    if (!widget)
+                        return editError('invalid_edit', path, 'Cannot reorder an unknown widget');
+                    ordered.push(widget);
+                }
+                widgets = ordered;
+                break;
+            }
+        }
+    }
+    // 整个事务合并后再验证关联；任何失败都不改变上一版快照。
+    const result = validateSurfaceSpec({ ...original.value, title, layout, dataSources: sources, widgets }, catalog, policy);
+    if (!result.ok)
+        return result;
+    const bounded = parseSurfaceJson(result.value);
+    if (!bounded.ok)
+        return bounded;
+    return { ok: true, value: immutableCopy({ revision: edit.baseRevision + 1, spec: result.value }) };
+}
+export function createSurfaceEditSchema() {
+    return surfaceSchemaToJson(editSchema);
+}
+export function buildSurfaceEditMessages(request, current, catalog, policy) {
+    if (typeof request !== 'string' || !request.trim() || request.length > SURFACE_AGENT_LIMITS.maxRequestCharacters) {
+        throw new Error('Surface edit request must be non-empty and within the request character limit');
+    }
+    const parsed = parseSurfaceJson(current);
+    if (!parsed.ok || !compiledRevision.Check(parsed.value) || !validateSurfaceSpec(parsed.value.spec, catalog, policy).ok) {
+        throw new Error('Cannot generate edits for an invalid current revision');
+    }
+    const content = `Return one JSON surface-edit/v1 proposal, not code, markdown, or a full replacement surface. Preserve IDs and all unrequested widgets, sources, filters, and layout. Use the current surfaceId, catalogVersion and baseRevision exactly. Only the listed operations and catalog widgets are allowed. Do not generate CSS, JavaScript, SQL, URLs, event handlers, or mutations. Edits are proposals requiring whole-document validation and host approval, never permission grants.\nCatalog: ${JSON.stringify(createSurfaceCatalogManifest(catalog))}\nPolicy: ${JSON.stringify(policy)}\nEdit JSON Schema: ${JSON.stringify(createSurfaceEditSchema())}\nCurrent revision: ${JSON.stringify(parsed.value)}`;
+    if (content.length > SURFACE_AGENT_LIMITS.maxContractCharacters)
+        throw new Error('Surface edit context exceeds the contract character limit');
+    return [{ role: 'system', content }, { role: 'user', content: request }];
+}

package/dist/index.d.ts

@@ -2,5 +2,11 @@ export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export type { JsonObject, JsonPrimitive, JsonValue, ResourceListDataSource, ResourceListSource, ResourceOneDataSource, ResourceOneSource, SurfaceBinding, SurfaceCatalog, SurfaceCatalogDataKind, SurfaceDataError, SurfaceDataProvider, SurfaceDataSource, SurfaceFilter, SurfaceGridLayout, SurfaceGridSpan, SurfacePolicy, SurfaceResourcePolicy, SurfaceSort, SurfaceSpec, SurfaceValidationCode, SurfaceValidationIssue, SurfaceValidationResult, SurfaceWidget, SurfaceWidgetDataState, SurfaceWidgetDefinition, } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
 export type { SurfaceMessages } from './localization.js';
-export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, parseSurfaceAgentProposal, } from './agent.js';
-export type { SurfaceAgentProposal, SurfaceAgentValidationResult, } from './agent.js';
+export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
+export type { SurfaceAgentProposal, SurfaceAgentProposalV2, SurfaceAgentCannotFulfill, SurfaceAgentResponse, SurfaceAgentResponseResult, SurfaceAgentMessage, SurfaceAgentStream, SurfaceAgentValidationResult, } from './agent.js';
+export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';
+export type { SurfaceCatalogManifest } from './agent-contract.js';
+export { SURFACE_EDIT_SCHEMA_VERSION, SURFACE_EDIT_LIMITS, createSurfaceRevision, applySurfaceEditProposal, createSurfaceEditSchema, buildSurfaceEditMessages, } from './edits.js';
+export type { SurfaceEditOperation, SurfaceEditProposal, SurfaceEditIssue, SurfaceRevision, SurfaceRevisionResult, } from './edits.js';
+export { svarGridPropsSchema, svarGridDefinition } from './svar-schema.js';
+export type { SvarGridProps } from './svar-schema.js';

package/dist/index.js

@@ -1,3 +1,7 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
-export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, parseSurfaceAgentProposal, } from './agent.js';
+export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
+export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';
+export { SURFACE_EDIT_SCHEMA_VERSION, SURFACE_EDIT_LIMITS, createSurfaceRevision, applySurfaceEditProposal, createSurfaceEditSchema, buildSurfaceEditMessages, } from './edits.js';
+// 只导出 JSON schema，不将可选 SVAR 渲染器加载到协议入口。
+export { svarGridPropsSchema, svarGridDefinition } from './svar-schema.js';

package/dist/interactive.d.ts

@@ -0,0 +1,6 @@
+import { type SurfaceRenderCatalog } from './catalog.js';
+import type { SurfaceActionDescriptor } from './workflows/types.js';
+export { default as SurfaceWorkflowProvider } from './components/SurfaceWorkflowProvider.svelte';
+export { withSurfaceAppearance } from './workflows/catalog.js';
+export type { SurfaceWorkflowTransport } from './workflows/client.js';
+export declare function createInteractiveSurfaceCatalog(actions: readonly SurfaceActionDescriptor[], base?: SurfaceRenderCatalog): SurfaceRenderCatalog;

package/dist/interactive.js

@@ -0,0 +1,15 @@
+import { defineSurfaceCatalog, styledSurfaceCatalog } from './catalog.js';
+import { createInteractiveSurfaceDefinitions } from './workflows/catalog.js';
+import ResourceFormWidget from './components/ResourceFormWidget.svelte';
+export { default as SurfaceWorkflowProvider } from './components/SurfaceWorkflowProvider.svelte';
+export { withSurfaceAppearance } from './workflows/catalog.js';
+export function createInteractiveSurfaceCatalog(actions, base = styledSurfaceCatalog) {
+    const definitions = createInteractiveSurfaceDefinitions(actions, base);
+    const components = new Map(base.widgets.map((widget) => [widget.type, widget.component]));
+    return defineSurfaceCatalog({ ...definitions, widgets: definitions.widgets.map((widget) => {
+            const component = widget.type === 'resource-form' ? ResourceFormWidget : components.get(widget.type);
+            if (!component)
+                throw new Error(`Missing renderer for ${widget.type}`);
+            return { ...widget, component };
+        }) });
+}

package/dist/json.js

@@ -99,8 +99,7 @@ export function jsonValueIssue(input) {
                 }
                 entries.push([key, descriptor.value]);
             }
-            for (let index = entries.length - 1; index >= 0; index -= 1) {
-                const [key, entry] = entries[index];
+            for (const [key, entry] of entries.reverse()) {
                 pending.push({ kind: 'visit', candidate: entry, path: [...path, key], depth: depth + 1 });
             }
         }

package/dist/openui.d.ts

@@ -0,0 +1,64 @@
+import type { SurfaceCatalog, SurfacePolicy, SurfaceSpec } from './types.js';
+import { SurfaceOpenUIError, OPENUI_LIMITS } from './workflows/openui-guard.js';
+export { SurfaceOpenUIError, OPENUI_LIMITS };
+/** Structural subset of @openuidev/lang-core's public types. The actual parser
+ * factory is injected by the trusted host, avoiding a React/Zod/runtime dependency
+ * in the existing Surface root entry. Tested integration must use the real factory.
+ */
+export interface SurfaceOpenUILibrarySchema {
+    $defs: Record<string, {
+        properties: Record<string, unknown>;
+        required: string[];
+    }>;
+}
+export interface SurfaceOpenUIElement {
+    type: 'element';
+    typeName: string;
+    props: Record<string, unknown>;
+    partial: boolean;
+}
+export interface SurfaceOpenUIParseResult {
+    root: SurfaceOpenUIElement | null;
+    meta: {
+        incomplete: boolean;
+        unresolved: string[];
+        orphaned: string[];
+        errors: readonly unknown[];
+    };
+    stateDeclarations?: Record<string, unknown>;
+    queryStatements?: readonly unknown[];
+    mutationStatements?: readonly unknown[];
+}
+export type SurfaceOpenUIParserFactory = (schema: SurfaceOpenUILibrarySchema, rootName?: string) => {
+    push(chunk: string): SurfaceOpenUIParseResult;
+    getResult(): SurfaceOpenUIParseResult;
+};
+export type SurfaceOpenUIResult = {
+    readonly ok: true;
+    readonly complete: boolean;
+    readonly preview: SurfaceSpec | null;
+    readonly unresolved: readonly string[];
+} | {
+    readonly ok: false;
+    readonly preview: null;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export declare function createSurfaceOpenUISchema(catalog: SurfaceCatalog): SurfaceOpenUILibrarySchema;
+export declare function createSurfaceOpenUIStream(options: {
+    readonly catalog: SurfaceCatalog;
+    readonly policy: SurfacePolicy;
+    readonly createStreamingParser: SurfaceOpenUIParserFactory;
+}): {
+    push(chunk: string): SurfaceOpenUIResult;
+    finish(): SurfaceOpenUIResult;
+};
+export declare function buildSurfaceOpenUIMessages(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): ({
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string;
+})[];

package/dist/openui.js

@@ -0,0 +1,168 @@
+import { SURFACE_AGENT_LIMITS, createSurfaceCatalogManifest } from './agent-contract.js';
+import { validateSurfaceSpec } from './validation.js';
+import { isJsonValue } from './json.js';
+import { createOpenUIStatementGuard, SurfaceOpenUIError, OPENUI_LIMITS } from './workflows/openui-guard.js';
+export { SurfaceOpenUIError, OPENUI_LIMITS };
+function componentNames(catalog) {
+    const names = new Map();
+    for (const widget of catalog.widgets) {
+        const name = widget.type.split(/[^A-Za-z0-9]+/u).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+        if (!/^[A-Z][A-Za-z0-9]*$/u.test(name) || ['Surface', 'Source'].includes(name) || names.has(name)) {
+            throw new Error(`Surface widget cannot be mapped to a unique OpenUI name: ${widget.type}`);
+        }
+        names.set(name, widget.type);
+    }
+    return names;
+}
+export function createSurfaceOpenUISchema(catalog) {
+    // Validates the same host-owned catalog used by prompts and the renderer.
+    createSurfaceCatalogManifest(catalog);
+    const names = componentNames(catalog);
+    const defs = {
+        Surface: { properties: {
+                surfaceId: { type: 'string' }, title: { type: 'string' },
+                sources: { type: 'array' }, widgets: { type: 'array' }, gap: { type: 'string' },
+            }, required: ['surfaceId', 'title', 'sources', 'widgets'] },
+        Source: { properties: { value: { type: 'object' } }, required: ['value'] },
+    };
+    for (const [name, type] of names) {
+        const definition = catalog.widgets.find((widget) => widget.type === type);
+        if (!definition)
+            throw new Error(`Missing component definition: ${type}`);
+        defs[name] = { properties: {
+                id: { type: 'string' }, props: JSON.parse(JSON.stringify(definition.propsSchema)),
+                binding: { anyOf: [{ type: 'object' }, { type: 'null' }] },
+                span: { type: 'number' },
+            }, required: ['id', 'props'] };
+    }
+    return { $defs: defs };
+}
+function element(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value)
+        && value.type === 'element'
+        && typeof value.typeName === 'string'
+        && !!value.props && typeof value.props === 'object';
+}
+export function createSurfaceOpenUIStream(options) {
+    const { catalog, policy } = options;
+    const schema = createSurfaceOpenUISchema(catalog);
+    const names = componentNames(catalog);
+    const parser = options.createStreamingParser(schema, 'Surface');
+    const guard = createOpenUIStatementGuard(Object.keys(schema.$defs));
+    let terminal;
+    let latestPreview = { ok: true, complete: false, preview: null, unresolved: [] };
+    function normalize(final) {
+        const parsed = parser.getResult();
+        if ((parsed.queryStatements?.length ?? 0) || (parsed.mutationStatements?.length ?? 0)
+            || Object.keys(parsed.stateDeclarations ?? {}).length) {
+            throw new SurfaceOpenUIError('unsupported', 'OpenUI state, Query and Mutation execution is not allowed');
+        }
+        if (parsed.meta.errors.length)
+            throw new SurfaceOpenUIError('syntax', 'OpenUI component arguments failed validation');
+        if (final && (parsed.meta.incomplete || parsed.meta.unresolved.length || parsed.meta.orphaned.length)) {
+            throw new SurfaceOpenUIError('syntax', 'Incomplete, unresolved or unreachable declarations remain');
+        }
+        if (!parsed.root) {
+            if (final)
+                throw new SurfaceOpenUIError('syntax', 'A Surface root is required');
+            return { ok: true, complete: false, preview: null, unresolved: parsed.meta.unresolved };
+        }
+        const root = parsed.root;
+        if (root.typeName !== 'Surface' || root.partial)
+            throw new SurfaceOpenUIError('syntax', 'Expected a complete Surface declaration');
+        const { surfaceId, title, sources, widgets, gap } = root.props;
+        if (!Array.isArray(sources) || !Array.isArray(widgets))
+            throw new SurfaceOpenUIError('syntax', 'Surface sources and widgets must be arrays');
+        const dataSources = [];
+        for (const source of sources) {
+            if (source === null && !final)
+                continue;
+            if (!element(source) || source.typeName !== 'Source' || source.partial || !isJsonValue(source.props['value'])) {
+                throw new SurfaceOpenUIError('syntax', 'Invalid Source node');
+            }
+            dataSources.push(source.props['value']);
+        }
+        const normalized = [];
+        for (const widget of widgets) {
+            if (widget === null && !final)
+                continue;
+            if (!element(widget) || widget.partial || !names.has(widget.typeName))
+                throw new SurfaceOpenUIError('syntax', 'Unregistered widget node');
+            const { id, props, binding, span } = widget.props;
+            if (!isJsonValue(props))
+                throw new SurfaceOpenUIError('syntax', 'Widget props must be literal JSON');
+            // A forward reference is never replaced with invented data or defaults.
+            // Exclude widgets depending on unresolved sources from structural previews.
+            if (!final && binding && typeof binding === 'object'
+                && !dataSources.some((source) => source.id === binding.sourceId))
+                continue;
+            normalized.push({ id, type: names.get(widget.typeName), props,
+                ...(binding == null ? {} : { binding }),
+                ...(span == null ? {} : { placement: { columnSpan: span } }),
+            });
+        }
+        const candidate = { schemaVersion: 'surface/v1', catalogVersion: catalog.version,
+            surfaceId, title, layout: { type: 'grid', columns: 12, ...(gap == null ? {} : { gap }) }, dataSources, widgets: normalized };
+        const result = validateSurfaceSpec(candidate, catalog, policy);
+        if (!result.ok)
+            throw new SurfaceOpenUIError('invalid_surface', result.issues.map((issue) => `${issue.code}:${issue.path}`).join(', '));
+        return { ok: true, complete: final, preview: result.value, unresolved: [...parsed.meta.unresolved] };
+    }
+    function fail(error) {
+        terminal = { ok: false, preview: null, error: {
+                code: error instanceof SurfaceOpenUIError ? error.code : 'syntax',
+                message: error instanceof SurfaceOpenUIError ? error.message : 'OpenUI parser failed',
+            } };
+        return terminal;
+    }
+    return {
+        push(chunk) {
+            if (terminal)
+                return { ok: false, preview: null, error: { code: 'closed', message: 'Stream is closed' } };
+            try {
+                const statements = guard.push(chunk);
+                // Token-by-token transport must not repeatedly materialize an unchanged tree.
+                if (!statements.length)
+                    return latestPreview;
+                for (const statement of statements)
+                    parser.push(statement);
+                latestPreview = normalize(false);
+                return latestPreview;
+            }
+            catch (error) {
+                return fail(error);
+            }
+        },
+        finish() {
+            if (terminal)
+                return terminal;
+            try {
+                for (const statement of guard.finish())
+                    parser.push(statement);
+                terminal = normalize(true);
+                return terminal;
+            }
+            catch (error) {
+                return fail(error);
+            }
+        },
+    };
+}
+export function buildSurfaceOpenUIMessages(request, catalog, policy) {
+    if (typeof request !== 'string' || !request.trim() || request.length > 8000)
+        throw new Error('Invalid Surface request');
+    const schema = createSurfaceOpenUISchema(catalog);
+    const content = [
+        'Return only static OpenUI Lang declarations. Use root = Surface(surfaceId, title, sources, widgets, gap).',
+        'Use Source(resourceSourceJSON). Each catalog component uses (id, props, bindingOrNull, columnSpan).',
+        'Use named component declarations, never inline calls or reusable literal declarations. Forward references are allowed only once in the Surface root. Use quoted JSON object keys and double-quoted strings.',
+        'Never emit Markdown, expressions, state, Query, Mutation, Action, arbitrary code, CSS, URLs or tool calls.',
+        'Form field schemas and submission labels belong to registered host actions, not model output. Never claim a write has executed.',
+        `Library: ${JSON.stringify(schema)}`,
+        `Catalog: ${JSON.stringify(createSurfaceCatalogManifest(catalog))}`,
+        `Resource policy: ${JSON.stringify(policy)}`,
+    ].join('\n');
+    if (content.length > SURFACE_AGENT_LIMITS.maxContractCharacters)
+        throw new Error('Select a smaller Surface catalog');
+    return [{ role: 'system', content }, { role: 'user', content: request }];
+}