@svadmin/surface 0.8.19 → 0.9.0

package/README.md

@@ -1,8 +1,8 @@
 # @svadmin/surface
 
-`@svadmin/surface` renders a small, versioned JSON contract as a trusted Svelte dashboard. It is an optional browser package and does not change the public contract of `@svadmin/core`.
+`@svadmin/surface` renders a versioned JSON contract as a trusted Svelte dashboard. It is an optional package and does not change the public contract of `@svadmin/core`.
 
-The MVP supports Svelte 5 + Vite, a fixed 12-column grid, four built-in widgets, read-only `DataProvider` queries, explicit access checks, field projection, and manual host refresh.
+`surface/v1` supports Svelte 5 + Vite, a fixed 12-column grid, four built-in widgets, read-only `DataProvider` queries, explicit access checks, field projection, and manual host refresh. Optional AI helpers derive generation contracts from the component catalog and support revision-checked edit proposals.
 
 ## Install
 
@@ -10,7 +10,7 @@ The MVP supports Svelte 5 + Vite, a fixed 12-column grid, four built-in widgets,
 bun add @svadmin/surface @svadmin/core @svadmin/ui @tanstack/svelte-query svelte @sinclair/typebox
 ```
 
-Import protocol types and validation from the DOM-free root entry. Import rendering code from the Svelte subpath.
+Import protocol types and validation from the DOM-free root entry. Import rendering code from the Svelte subpath. Hosts do not need Panda or Tailwind compiler plugins to consume precompiled component styles.
 
 ```ts
 import { validateSurfaceSpec, type SurfacePolicy, type SurfaceSpec } from '@svadmin/surface';
@@ -27,10 +27,7 @@ import {
 ```svelte
 <script lang="ts">
   import type { SurfacePolicy, SurfaceSpec } from '@svadmin/surface';
-  import {
-    DEFAULT_SURFACE_CATALOG_VERSION,
-    SurfaceRenderer,
-  } from '@svadmin/surface/svelte';
+  import { DEFAULT_SURFACE_CATALOG_VERSION, SurfaceRenderer } from '@svadmin/surface/svelte';
 
   const policy = {
     resources: {
@@ -78,35 +75,69 @@ import {
 
 When rendered inside `AdminApp`, the renderer resolves the configured provider for each resource. A trusted host may instead pass `dataProvider`, which is still narrowed to `getList` and `getOne`.
 
-The renderer also follows the active `AdminApp` i18n locale. Built-in loading, empty, error, boolean, number, currency, percent, and date presentation updates automatically. A standalone host can pass `locale`, and can override individual built-in strings with `messages`. Business copy such as the surface title, widget titles, labels, and column headers remains part of the JSON spec; build or select a localized spec when the host locale changes.
+The renderer follows the active `AdminApp` i18n locale. Built-in loading, empty, error, boolean, number, currency, percent, and date presentation updates automatically. A standalone host can pass `locale` and override built-in strings with `messages`. Business copy such as titles, labels, and column headers remains part of the JSON spec.
 
 ```svelte
-<SurfaceRenderer
-  {spec}
-  {policy}
-  locale="zh-CN"
-  messages={{ tableNoRecords: '没有符合条件的记录' }}
-/>
+<SurfaceRenderer {spec} {policy} locale="zh-CN"
+  messages={{ tableNoRecords: '没有符合条件的记录' }} />
 ```
 
-## AI proposals
+## Incremental loading and session boundaries
+
+Title, layout, widget ordering, equivalent JSON and locale-only changes reuse unchanged source results and in-flight reads. Query, projection-policy or provider changes reload only affected sources. `refresh(sourceId)` forces one source and `refresh()` forces all sources. Stale replies and errors are ignored after replacement, removal or destruction; this is logical cancellation, not a transport `AbortSignal` guarantee.
+
+Stable widget IDs and component types preserve local input state during visual edits. Removed/retyped widgets can remount. A changed trusted `scopeKey` or `dataScopeKey` clears source identity and remounts local widget state; observable logout, tenant, authentication and access-control identities are also tracked. Hosts must update a non-secret scope token when opaque credentials/session state changes, and discard pending AI proposals on account or tenant changes. These properties are not model-controlled fields. Presentation changes are no longer implicit data refresh or reauthorization signals.
+
+## AI generation contracts
 
-The DOM-free root entry also exposes an opt-in Agent protocol. `buildSurfaceAgentPrompt()` constrains a model to return a proposal envelope and includes the host's widget/resource/field allowlists. `parseSurfaceAgentProposal()` parses and validates the complete `SurfaceSpec` against the same catalog and policy without querying a provider:
+Catalog definitions can include `description` and schema-validated `examples`. The root exports `createSurfaceCatalogManifest()` and `createSurfaceAgentResponseSchema()` for model adapters. Inline, closed TypeBox object schemas are supported; transforms and schema references fail explicitly rather than silently weakening the generated contract.
 
 ```ts
 import {
-  buildSurfaceAgentPrompt,
-  parseSurfaceAgentProposal,
+  buildSurfaceAgentMessages,
+  parseSurfaceAgentResponse,
+  selectSurfaceCatalog,
 } from '@svadmin/surface';
-
-const prompt = buildSurfaceAgentPrompt('Generate an inventory dashboard', catalog, policy);
-const proposal = parseSurfaceAgentProposal(modelText, catalog, policy);
-if (proposal.ok) {
-  // Preview proposal.value.spec, then require explicit user approval before rendering.
+import { defaultSurfaceCatalog } from '@svadmin/surface/svelte';
+
+const catalog = selectSurfaceCatalog(defaultSurfaceCatalog, ['metric', 'resource-table']);
+const messages = buildSurfaceAgentMessages('Generate an inventory dashboard', catalog, policy);
+// Send messages through a trusted model adapter. Never expose model credentials.
+const response = parseSurfaceAgentResponse(modelText, catalog, policy);
+if (response.ok && response.value.action === 'propose') {
+  // Preview response.value.spec and require explicit approval before applying it.
+} else if (response.ok) {
+  // Render response.value.message as text: this is a cannot-fulfill response.
 }
 ```
 
-The adapter is deliberately proposal-only. Persistence, revision history, audit records, and the final apply decision belong to the host application. It never executes generated code or mutation actions.
+Use the same task-scoped catalog for generation, validation and rendering. JSON Schema narrows generation but does not replace cross-source binding checks, field policy or server authorization. The schema is not claimed to match every vendor's restricted structured-output subset.
+
+`buildSurfaceAgentPrompt()` and `parseSurfaceAgentProposal()` remain compatible with the legacy proposal-only `surface-agent/v1` envelope. The new message API uses `surface-agent/v2` with a structured `cannot-fulfill` alternative. `createSurfaceAgentStream()` buffers bounded text and validates at `finish()`; it does **not** render partial JSON or implement OpenUI Lang streaming.
+
+## Revisioned edits and explicit preview
+
+`createSurfaceRevision()` creates a validated immutable snapshot. `buildSurfaceEditMessages()` describes the current revision, catalog and allowed operations. `applySurfaceEditProposal()` validates a complete `surface-edit/v1` transaction and returns a new candidate revision without mutating the old one. Operations cover title/layout, widget/source upsert/removal and complete widget reordering by stable ID. Stale `baseRevision`, unknown IDs, invalid props, denied fields and broken final references reject the whole transaction.
+
+The Svelte `SurfaceEditPreview` component accepts a controlled revision and untrusted proposal:
+
+```svelte
+<SurfaceEditPreview
+  {revision}
+  {proposal}
+  {streaming}
+  {policy}
+  {catalog}
+  {dataProvider}
+  scopeKey={trustedSessionRevision}
+  density="comfortable"
+  onApply={applyApprovedRevision}
+/>
+```
+
+It leaves the current surface intact during streaming, offers a separate preview/back action, and revalidates at the explicit apply click. It calls `onApply(candidate)` only for a valid proposal. The host performs any persistence with server authorization and atomic revision compare-and-swap, then updates `revision` and clears `proposal`. Missing handlers, invalid proposals and pending callbacks disable application. A rejected callback reports an error without changing the controlled revision. Changing scope does not authorize an old proposal: the host must discard old proposals as described above.
+
+The new preview controls use Panda build-time tokens/recipes and import their compiled CSS. `@svadmin/surface/editor.css` is also available for explicit CSS collection. Only finite density/button variants are emitted; host styles can override the existing complete-color semantic CSS variables. The integrated main already uses the compiler-free native/Panda build from PR #430; this preview adds its own scoped recipes without restoring Tailwind dependencies. The separate `@svadmin/surface/styles.css` entry for `styledSurfaceCatalog` remains available; see `STYLING.md`.
 
 ## Built-in catalog
 
@@ -117,18 +148,21 @@ The adapter is deliberately proposal-only. Persistence, revision history, audit
 | `bar-chart` | `/items` | Zero-dependency SVG bar chart |
 | `line-chart` | `/items` | Zero-dependency SVG line chart |
 
-The catalog version is `svadmin/v1`. `catalogVersion` must match exactly.
-
-Custom catalogs are trusted runtime configuration. Every registration must use a strict TypeBox object schema and a trusted Svelte component. Item widgets that read record fields must expose those fields through `getReferencedFields`; validation then checks them against `SurfacePolicy.readFields`.
+The catalog version is `svadmin/v1`. `catalogVersion` must match exactly. Custom registrations use strict TypeBox props schemas and trusted Svelte components. Item widgets reading record fields must expose them through `getReferencedFields` so runtime validation checks `SurfacePolicy.readFields`.
 
 ```ts
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+
+const statusProps = Type.Object({ statusField: Type.String() }, { additionalProperties: false });
 const catalog = defineSurfaceCatalog({
   version: 'acme/v1',
   widgets: [{
     type: 'status-list',
+    description: 'Display a policy-authorized status field from resource items.',
     dataKind: 'items',
-    propsSchema: z.object({ statusField: z.string() }).strict(),
-    getReferencedFields: (props) => [props.statusField as string],
+    propsSchema: statusProps,
+    getReferencedFields: (props) => [Value.Decode(statusProps, props).statusField],
     component: StatusList,
   }],
 });
@@ -136,18 +170,16 @@ const catalog = defineSurfaceCatalog({
 
 ## Security boundary
 
-Surface specs are untrusted data. The renderer validates the whole document before sending any query. It rejects unknown components and sources, duplicate or overlong IDs, invalid props, dangerous pointers, mismatched versions, policy violations, and configured limits.
-
-Specs cannot contain HTML, Svelte, JavaScript, event handlers, Tailwind classes, style declarations, colors, URLs, SQL, provider selection, `meta`, arbitrary requests, or mutation actions. Provider records are projected to `readFields`, and selected values containing `Date`, `File`, `BigInt`, functions, cycles, `NaN`, or infinities fail instead of being converted.
+Surface specs are untrusted data. The renderer validates the whole document before sending any query. It rejects unknown components/sources, duplicate or overlong IDs, invalid props, dangerous pointers, mismatched versions, policy violations, and configured limits.
 
-The browser access-control check is display gating only. The backend must independently authorize every request and must not trust the spec, policy, or projected fields received from a browser.
+Specs cannot contain executable HTML, Svelte, JavaScript, event handlers, class names, style declarations, colors, URLs, SQL, provider selection, `meta`, arbitrary requests, or mutation actions. Provider records are projected to `readFields`. Selected values containing `Date`, `File`, `BigInt`, functions, cycles, `NaN`, or infinities fail instead of being converted.
 
-MVP limits are eight data sources, 24 widgets, 100 rows per page, eight filters, three sorters, 64-character IDs, 64 levels of JSON nesting, and 10,000 JSON nodes. A source is loaded once and shared. Generation checks discard stale responses.
+The browser access-control check is display gating only. The backend must independently authorize every request and must not trust a spec, client policy or projected fields as proof of authority. AI and edit helpers neither contact a model nor execute business writes. Persistence, audit records, model transport and approval policy belong to the host.
 
-Supported Core/UI ranges and the minimum packed-consumer matrix are published in `compatibility.json`.
+Limits are eight data sources, 24 widgets, 100 rows per page, eight filters, three sorters, 64-character IDs, 64 levels of JSON nesting, and 10,000 JSON nodes. AI text/request/contract sizes and edit operation counts are separately bounded by their exported limit constants. Supported Core/UI ranges and packed-consumer requirements are published in `compatibility.json`.
 
-## Out of scope for v1
+## Current boundaries
 
-SSR/Lite, Agent generation, storage, revisions, JSON Patch, actions, mutations, automatic refresh, arbitrary URLs, client aggregation, Canvas, and iframe rendering are intentionally absent. Aggregated metrics should come from a backend summary resource and bind through `resource-one`.
+Actual OpenUI Lang parsing, nested interactive forms, registered business actions, server persistence, SSR/Lite rendering, arbitrary URLs, client aggregation, Canvas and iframe execution are not implemented. Aggregated metrics should come from a policy-authorized backend summary resource and bind through `resource-one`. The current UI contract remains read-only even though its definition can be edited.
 
-中文指南见文档站的“声明式 Surface”。
+See `docs/architecture/openui-surface-phase2.md` for the original feature scope and `docs/architecture/surface-integration-provenance.md` for its integration with the current native/Panda main. 中文指南见文档站的“声明式 Surface”。

package/STYLING.md

@@ -0,0 +1,31 @@
+# Surface semantic styles
+
+默认 `svadmin/v1` 的校验规则和未指定变体时的组件样式保持兼容。新语义变体必须显式选择 `styledSurfaceCatalog`，不能只把 tone/density 添加到旧版 spec。
+
+```ts
+import '@svadmin/ui/app.css';
+import '@svadmin/surface/styles.css';
+import { styledSurfaceCatalog, STYLED_SURFACE_CATALOG_VERSION } from '@svadmin/surface/svelte';
+```
+
+将 spec.catalogVersion 设置为 STYLED_SURFACE_CATALOG_VERSION，并把同一 styledSurfaceCatalog 传给提示生成器、校验器和 SurfaceRenderer 的 catalog 属性。这样三个环节使用同一组件契约。`metric` 支持 tone（neutral/success/warning/danger/info）及 density（comfortable/compact），`resource-table` 支持 density。
+
+```json
+{
+  "type": "metric",
+  "props": {
+    "label": "待处理订单",
+    "format": "number",
+    "tone": "warning",
+    "density": "compact"
+  }
+}
+```
+
+以上只是 widget 片段；完整 spec 仍需要 schemaVersion、catalogVersion、数据源、绑定及布局等必要字段。
+
+Surface 自行打包预生成的 recipe 助手与 styles.css，避免让旧 UI peer 安装必须提供新增的 JS 导出入口。构建本仓库时先构建 UI 样式，再构建 Surface；消费发布包时不需要安装 Panda 或 Tailwind。配合尚未包含新 recipe CSS 的 UI 版本时必须加载 Surface 的 styles.css。
+
+AI 只能选择公开枚举，不能指定 class/style、任意颜色、recipe 定义或可执行代码。字段权限、只读查询、版本匹配和宿主确认要求不因样式变体而改变。
+
+本次是两类 Surface 组件的 recipes 试点；其他 UI 继续使用保留的原生兼容样式。OpenUI Lang 的解析、流式渲染适配、全量 UI recipe 重写以及 DTCG 文件转换器不在本次已实现范围。不能把 CSS 编译器移除等同于以上功能已经完成。

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "surface": "0.8.x",
+  "surface": "0.9.x",
   "minimumSupported": {
     "@svadmin/core": "0.34.2",
     "@svadmin/ui": "0.40.6",
@@ -18,5 +18,26 @@
       "ui": "workspace tarball",
       "svelte": "workspace override"
     }
-  ]
+  ],
+  "minimumSupportedAppliesTo": [
+    ".",
+    "./svelte"
+  ],
+  "entrypointCompatibility": {
+    "./interactive": {
+      "status": "experimental",
+      "requiredUiCapabilities": [
+        "JsonSchemaForm.idPrefix",
+        "proxy-safe nested field updates",
+        "required boolean and decimal input support"
+      ],
+      "minimumPublishedUi": null,
+      "verification": "same-checkout tarballs via scripts/surface-workflows/packed-consumer.mjs; inspect the current run result",
+      "releaseGate": "Coordinate a tested UI release and narrow the package peer floor before publishing this entry."
+    },
+    "./server/sqlite": {
+      "runtime": "Node.js",
+      "verification": "Current CI Node version with real node:sqlite; no browser or distributed-store support implied."
+    }
+  }
 }

package/dist/agent-contract.d.ts

@@ -0,0 +1,37 @@
+import { type TSchema } from '@sinclair/typebox';
+import { type JsonObject, type SurfaceCatalog, type SurfacePolicy } from './types.js';
+export declare const SURFACE_CATALOG_SCHEMA_VERSION: "surface-catalog/v1";
+export declare const SURFACE_AGENT_SCHEMA_VERSION: "surface-agent/v1";
+export declare const SURFACE_AGENT_RESPONSE_SCHEMA_VERSION: "surface-agent/v2";
+export declare const SURFACE_AGENT_LIMITS: {
+    readonly maxInputCharacters: 262144;
+    readonly maxRequestCharacters: 16384;
+    readonly maxContractCharacters: 131072;
+};
+export interface SurfaceCatalogManifest {
+    readonly schemaVersion: typeof SURFACE_CATALOG_SCHEMA_VERSION;
+    readonly catalogVersion: string;
+    readonly widgets: readonly {
+        readonly type: string;
+        readonly dataKind: 'none' | 'scalar' | 'items';
+        readonly description?: string;
+        readonly propsSchema: JsonObject;
+        readonly examples?: readonly JsonObject[];
+    }[];
+}
+/** 不把 Transform、函数或引用 schema 静默降级为宽松的 JSON schema。 */
+export declare function surfaceSchemaToJson(schema: TSchema): JsonObject;
+/** 同一目录可用于提示、运行时校验及渲染；任务筛选不会仅在提示词中生效。 */
+export declare function selectSurfaceCatalog<T extends SurfaceCatalog>(catalog: T, widgetTypes: readonly string[]): Omit<T, 'widgets'> & {
+    readonly widgets: readonly T['widgets'][number][];
+};
+export declare function createSurfaceCatalogManifest(catalog: SurfaceCatalog): SurfaceCatalogManifest;
+/** 生成约束缩小候选空间，不能代替绑定/字段关联校验，更不能代替后端授权。 */
+export declare function createSurfaceGenerationSpecSchema(catalog: SurfaceCatalog, policy: SurfacePolicy): TSchema;
+export declare function createSurfaceAgentResponseSchema(catalog: SurfaceCatalog, policy: SurfacePolicy): JsonObject;
+export declare const surfaceCannotFulfillSchema: import("@sinclair/typebox").TObject<{
+    schemaVersion: import("@sinclair/typebox").TLiteral<"surface-agent/v2">;
+    action: import("@sinclair/typebox").TLiteral<"cannot-fulfill">;
+    reason: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"unsupported_request">, import("@sinclair/typebox").TLiteral<"insufficient_permissions">, import("@sinclair/typebox").TLiteral<"insufficient_context">]>;
+    message: import("@sinclair/typebox").TString;
+}>;

package/dist/agent-contract.js

@@ -0,0 +1,203 @@
+import { Kind, OptionalKind, ReadonlyKind, Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { escapedJsonPointerToken, jsonValueIssue } from './json.js';
+import { surfaceFilterSchema, surfaceIdSchema, surfaceListSourceSchema, surfaceOneSourceSchema, surfaceSpecSchema, surfaceWidgetSchema, } from './schema.js';
+import { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION, } from './types.js';
+export const SURFACE_CATALOG_SCHEMA_VERSION = 'surface-catalog/v1';
+export const SURFACE_AGENT_SCHEMA_VERSION = 'surface-agent/v1';
+export const SURFACE_AGENT_RESPONSE_SCHEMA_VERSION = 'surface-agent/v2';
+export const SURFACE_AGENT_LIMITS = {
+    maxInputCharacters: 262_144,
+    maxRequestCharacters: 16_384,
+    maxContractCharacters: 131_072,
+};
+/** 不把 Transform、函数或引用 schema 静默降级为宽松的 JSON schema。 */
+export function surfaceSchemaToJson(schema) {
+    const ancestors = new Set();
+    let nodes = 0;
+    function visit(value, depth) {
+        nodes += 1;
+        if (nodes > SURFACE_LIMITS.maxJsonNodes || depth > SURFACE_LIMITS.maxJsonDepth) {
+            throw new Error('Surface schema exceeds the supported size');
+        }
+        if (value === null || typeof value === 'string' || typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value !== 'object' || ancestors.has(value)) {
+            throw new Error('Surface schema must be serializable without transforms or cycles');
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+            throw new Error('Surface schema must contain only plain objects');
+        }
+        ancestors.add(value);
+        const result = Object.create(null);
+        for (const key of Reflect.ownKeys(value)) {
+            if (Array.isArray(value) && key === 'length')
+                continue;
+            if (typeof key === 'symbol') {
+                if (key === Kind || key === OptionalKind || key === ReadonlyKind)
+                    continue;
+                throw new Error('Surface schema contains unsupported symbol metadata or a transform');
+            }
+            if (['__proto__', 'constructor', 'prototype', '$ref', '$dynamicRef', '$recursiveRef'].includes(key)) {
+                throw new Error(`Surface schema key "${key}" is not supported; use an inline schema`);
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor)) {
+                throw new Error('Surface schema accessors and hidden properties are not supported');
+            }
+            result[key] = visit(descriptor.value, depth + 1);
+        }
+        ancestors.delete(value);
+        if (Array.isArray(value)) {
+            if (Object.keys(result).length !== value.length || Object.keys(result).some((key) => !/^(0|[1-9][0-9]*)$/u.test(key) || Number(key) >= value.length)) {
+                throw new Error('Surface schema arrays must be dense JSON arrays');
+            }
+            return Array.from({ length: value.length }, (_, index) => {
+                const item = result[String(index)];
+                if (item === undefined)
+                    throw new Error('Surface schema arrays must be dense JSON arrays');
+                return item;
+            });
+        }
+        return result;
+    }
+    const result = visit(schema, 0);
+    if (result === null || typeof result !== 'object' || Array.isArray(result)) {
+        throw new Error('Expected an object JSON schema');
+    }
+    if (JSON.stringify(result).length > SURFACE_AGENT_LIMITS.maxContractCharacters) {
+        throw new Error('Surface schema exceeds the supported character count');
+    }
+    return result;
+}
+function isClosedObject(schema) {
+    if (schema['type'] === 'object' && schema['additionalProperties'] === false)
+        return true;
+    const branches = schema['anyOf'] ?? schema['oneOf'] ?? schema['allOf'];
+    return Array.isArray(branches) && branches.length > 0 && branches.every((branch) => (branch !== null && typeof branch === 'object' && !Array.isArray(branch) && isClosedObject(branch)));
+}
+/** 同一目录可用于提示、运行时校验及渲染；任务筛选不会仅在提示词中生效。 */
+export function selectSurfaceCatalog(catalog, widgetTypes) {
+    const requested = new Set(widgetTypes);
+    if (requested.size !== widgetTypes.length)
+        throw new Error('Duplicate requested surface widget type');
+    const known = new Set(catalog.widgets.map((widget) => widget.type));
+    for (const type of requested) {
+        if (!known.has(type))
+            throw new Error(`Unknown surface widget type "${type}"`);
+    }
+    return { ...catalog, widgets: catalog.widgets.filter((widget) => requested.has(widget.type)) };
+}
+export function createSurfaceCatalogManifest(catalog) {
+    if (!catalog.version)
+        throw new Error('Surface catalog version must not be empty');
+    const known = new Set();
+    const widgets = catalog.widgets.map((widget) => {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/u.test(widget.type) || widget.type.length > SURFACE_LIMITS.maxIdLength || known.has(widget.type)) {
+            throw new Error(`Invalid or duplicate surface widget type "${widget.type}"`);
+        }
+        known.add(widget.type);
+        if (!['none', 'scalar', 'items'].includes(widget.dataKind))
+            throw new Error('Invalid surface widget data kind');
+        const propsSchema = surfaceSchemaToJson(widget.propsSchema);
+        if (!isClosedObject(propsSchema))
+            throw new Error(`Widget "${widget.type}" must use a closed object props schema`);
+        const examples = widget.examples?.map((props) => {
+            if (jsonValueIssue(props) || !Value.Check(widget.propsSchema, props)) {
+                throw new Error(`Invalid props example for widget "${widget.type}"`);
+            }
+            return JSON.parse(JSON.stringify(props));
+        });
+        return {
+            type: widget.type,
+            dataKind: widget.dataKind,
+            ...(widget.description === undefined ? {} : { description: widget.description }),
+            propsSchema,
+            ...(examples === undefined ? {} : { examples }),
+        };
+    });
+    const manifest = {
+        schemaVersion: SURFACE_CATALOG_SCHEMA_VERSION,
+        catalogVersion: catalog.version,
+        widgets,
+    };
+    if (jsonValueIssue(manifest) || JSON.stringify(manifest).length > SURFACE_AGENT_LIMITS.maxContractCharacters) {
+        throw new Error('Surface catalog manifest exceeds the JSON contract limits');
+    }
+    return manifest;
+}
+function literals(values) {
+    return values.length === 0 ? Type.Never() : Type.Union([...new Set(values)].map((value) => Type.Literal(value)));
+}
+/** 生成约束缩小候选空间，不能代替绑定/字段关联校验，更不能代替后端授权。 */
+export function createSurfaceGenerationSpecSchema(catalog, policy) {
+    createSurfaceCatalogManifest(catalog);
+    const sources = [];
+    const scalarPointers = new Set(['/total']);
+    for (const [resource, rule] of Object.entries(policy.resources)) {
+        const limit = Math.min(rule.maxPageSize ?? SURFACE_LIMITS.maxPageSize, SURFACE_LIMITS.maxPageSize);
+        if (!Number.isSafeInteger(limit) || limit < 1)
+            throw new Error(`Invalid page limit for resource "${resource}"`);
+        const filters = Type.Union(surfaceFilterSchema.anyOf.map((branch) => Type.Object({
+            ...branch.properties,
+            field: literals(rule.filterFields ?? []),
+        }, { additionalProperties: false })));
+        sources.push(Type.Object({
+            ...surfaceListSourceSchema.properties,
+            resource: Type.Literal(resource),
+            // 显式页大小避免宿主默认值 10 超过小于 10 的策略上限。
+            pageSize: Type.Integer({ minimum: 1, maximum: limit }),
+            sorters: Type.Optional(Type.Array(Type.Object({
+                field: literals(rule.sortFields ?? []),
+                order: Type.Union([Type.Literal('asc'), Type.Literal('desc')]),
+            }, { additionalProperties: false }), { maxItems: (rule.sortFields?.length ?? 0) > 0 ? SURFACE_LIMITS.maxSorters : 0 })),
+            filters: Type.Optional(Type.Array(filters, { maxItems: (rule.filterFields?.length ?? 0) > 0 ? SURFACE_LIMITS.maxFilters : 0 })),
+        }, { additionalProperties: false }));
+        if (rule.allowGetOne === true) {
+            sources.push(Type.Object({ ...surfaceOneSourceSchema.properties, resource: Type.Literal(resource) }, { additionalProperties: false }));
+            for (const field of rule.readFields)
+                scalarPointers.add(`/${escapedJsonPointerToken(field)}`);
+        }
+    }
+    const widgets = catalog.widgets.map((widget) => {
+        const { binding: _binding, ...properties } = surfaceWidgetSchema.properties;
+        return Type.Object({
+            ...properties,
+            type: Type.Literal(widget.type),
+            props: widget.propsSchema,
+            ...(widget.dataKind === 'none' ? {} : {
+                binding: Type.Object({
+                    sourceId: surfaceIdSchema,
+                    pointer: widget.dataKind === 'items' ? Type.Literal('/items') : literals([...scalarPointers]),
+                }, { additionalProperties: false }),
+            }),
+        }, { additionalProperties: false, ...(widget.description ? { description: widget.description } : {}) });
+    });
+    return Type.Object({
+        ...surfaceSpecSchema.properties,
+        schemaVersion: Type.Literal(SURFACE_SCHEMA_VERSION),
+        catalogVersion: Type.Literal(catalog.version),
+        dataSources: Type.Array(sources.length ? Type.Union(sources) : Type.Never(), { maxItems: sources.length ? SURFACE_LIMITS.maxDataSources : 0 }),
+        widgets: Type.Array(widgets.length ? Type.Union(widgets) : Type.Never(), { maxItems: widgets.length ? SURFACE_LIMITS.maxWidgets : 0 }),
+    }, { additionalProperties: false });
+}
+export function createSurfaceAgentResponseSchema(catalog, policy) {
+    const proposal = Type.Object({
+        schemaVersion: Type.Literal(SURFACE_AGENT_RESPONSE_SCHEMA_VERSION),
+        action: Type.Literal('propose'),
+        summary: Type.Optional(Type.String({ minLength: 1, maxLength: 240 })),
+        spec: createSurfaceGenerationSpecSchema(catalog, policy),
+    }, { additionalProperties: false });
+    return surfaceSchemaToJson(Type.Union([proposal, surfaceCannotFulfillSchema]));
+}
+export const surfaceCannotFulfillSchema = Type.Object({
+    schemaVersion: Type.Literal(SURFACE_AGENT_RESPONSE_SCHEMA_VERSION),
+    action: Type.Literal('cannot-fulfill'),
+    reason: Type.Union([
+        Type.Literal('unsupported_request'), Type.Literal('insufficient_permissions'), Type.Literal('insufficient_context'),
+    ]),
+    message: Type.String({ minLength: 1, maxLength: 480 }),
+}, { additionalProperties: false });

package/dist/agent.d.ts

@@ -1,12 +1,18 @@
+import { type Static } from '@sinclair/typebox';
+import { SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_AGENT_SCHEMA_VERSION, surfaceCannotFulfillSchema } from './agent-contract.js';
 import type { SurfaceCatalog, SurfacePolicy, SurfaceSpec, SurfaceValidationIssue } from './types.js';
-/** Wire version for model-produced, human-reviewable Surface proposals. */
-export declare const SURFACE_AGENT_SCHEMA_VERSION: "surface-agent/v1";
+export { SURFACE_AGENT_SCHEMA_VERSION } from './agent-contract.js';
 export interface SurfaceAgentProposal {
     readonly schemaVersion: typeof SURFACE_AGENT_SCHEMA_VERSION;
     readonly action: 'propose';
     readonly summary?: string;
     readonly spec: SurfaceSpec;
 }
+export interface SurfaceAgentProposalV2 extends Omit<SurfaceAgentProposal, 'schemaVersion'> {
+    readonly schemaVersion: typeof SURFACE_AGENT_RESPONSE_SCHEMA_VERSION;
+}
+export type SurfaceAgentCannotFulfill = Static<typeof surfaceCannotFulfillSchema>;
+export type SurfaceAgentResponse = SurfaceAgentProposal | SurfaceAgentProposalV2 | SurfaceAgentCannotFulfill;
 export type SurfaceAgentValidationResult = {
     readonly ok: true;
     readonly value: SurfaceAgentProposal;
@@ -14,10 +20,35 @@ export type SurfaceAgentValidationResult = {
     readonly ok: false;
     readonly issues: readonly SurfaceValidationIssue[];
 };
-/**
- * Parse and fully validate an AI-generated proposal before a host previews it.
- * This function has no side effects and never queries a provider.
- */
+export type SurfaceAgentResponseResult = {
+    readonly ok: true;
+    readonly value: SurfaceAgentResponse;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SurfaceValidationIssue[];
+};
+export interface SurfaceAgentMessage {
+    readonly role: 'system' | 'user';
+    readonly content: string;
+}
+/** 保留 v1 的函数签名、返回类型以及带说明文字的 fenced JSON 兼容行为。 */
 export declare function parseSurfaceAgentProposal(input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceAgentValidationResult;
-/** Build a model instruction that keeps generation inside the Surface contract. */
+/** 结构化“无法完成”也是有效响应，但永远不是可渲染/可执行的提案。 */
+export declare function parseSurfaceAgentResponse(input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceAgentResponseResult;
+/** 兼容旧 v1 输出，同时补齐从组件契约派生的完整参数/结构 schema。 */
 export declare function buildSurfaceAgentPrompt(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): string;
+/** 系统契约与用户需求分开传递；不绑定某个模型厂商或 CSS 编译器。 */
+export declare function buildSurfaceAgentMessages(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): readonly SurfaceAgentMessage[];
+export interface SurfaceAgentStream {
+    /** 接收文本，不解析、不渲染、不查询数据。 */
+    push(chunk: string): {
+        readonly ok: true;
+        readonly characters: number;
+    } | Extract<SurfaceAgentResponseResult, {
+        ok: false;
+    }>;
+    /** 仅结束后返回整体校验结果。重复调用返回同一终态。 */
+    finish(): SurfaceAgentResponseResult;
+}
+/** 有界传输缓冲，不冒充 OpenUI 增量渲染；半成品不进入运行时。 */
+export declare function createSurfaceAgentStream(catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceAgentStream;