@svadmin/surface 0.8.19 → 0.10.0

package/README.md

@@ -1,16 +1,22 @@
 # @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
 
+The declared minimum combination is Core 0.53.0, UI 0.73.0, and Svelte
+5.56.10, matching the published UI peer requirements. `compatibility.json`
+lists verification targets, not proof of a successful run. Acceptance requires
+the `minimum-supported` strict install and consumer checks in `pack:check` to
+pass against registry artifacts; workspace tarballs do not replace that check.
+
 ```bash
 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 CSS compiler plugins to consume the package's static component styles.
 
 ```ts
 import { validateSurfaceSpec, type SurfacePolicy, type SurfaceSpec } from '@svadmin/surface';
@@ -27,10 +33,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 +81,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.
+
+Preview controls use local finite class helpers and maintained static CSS. `@svadmin/surface/editor.css` remains available for explicit CSS collection. Density/button variants and complete-color semantic CSS variable overrides are preserved. Widgets use local semantic recipes to retain compatibility with older UI peers; no UI-generated helpers are copied during build. The separate `@svadmin/surface/styles.css` entry remains available and rendering components also import it automatically; see `STYLING.md`.
 
 ## Built-in catalog
 
@@ -117,18 +154,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 +176,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 historical integration evidence. 中文指南见文档站的“声明式 Surface”。

package/STYLING.md

@@ -0,0 +1,33 @@
+# 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 helper 和静态 styles.css；design-contract 统一从 @svadmin/ui/design-contract 导入，要求 UI >=0.73.0 <0.74.0。不复制 UI 生成物，也不依赖样式编译器。渲染组件自动导入语义样式；原有 styles.css 子路径仍可显式导入。UI 基础样式仍由宿主通过 @svadmin/ui/app.css 加载。构建仅执行 svelte-package；styles:check 检查全部有限变体及静态 CSS 边界。
+
+editor.css 与本地 styles/editor.ts 一起维护，保留 density、button variant、禁用/焦点状态和语义变量覆盖；editor.css 子路径不变。宿主升级时应同时升级 UI 与 Surface，并重新执行消费侧构建。
+
+AI 只能选择公开枚举，不能指定 class/style、任意颜色、recipe 定义或可执行代码。字段权限、只读查询、版本匹配和宿主确认要求不因样式变体而改变。
+
+此次仅替换样式基础设施。OpenUI 入口、catalog/schema 校验、workflow 授权与执行、提案预览及宿主确认逻辑保持不变；去除样式编译器不代表增加新的协议能力。

package/compatibility.json

@@ -1,16 +1,16 @@
 {
-  "surface": "0.8.x",
+  "surface": "0.10.x",
   "minimumSupported": {
-    "@svadmin/core": "0.34.2",
-    "@svadmin/ui": "0.40.6",
-    "svelte": "5.56.8"
+    "@svadmin/core": "0.53.0",
+    "@svadmin/ui": "0.73.0",
+    "svelte": "5.56.10"
   },
   "testedCombinations": [
     {
       "name": "minimum-supported",
-      "core": "0.34.2",
-      "ui": "0.40.6",
-      "svelte": "5.56.8"
+      "core": "0.53.0",
+      "ui": "0.73.0",
+      "svelte": "5.56.10"
     },
     {
       "name": "workspace-packed",
@@ -18,5 +18,37 @@
       "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."
+    },
+    "./business": {
+      "status": "experimental",
+      "requiredUiCapabilities": [
+        "ActivityFeed.title",
+        "ActivityFeed.emptyLabel",
+        "ActivityFeed.countLabel"
+      ],
+      "minimumPublishedUi": null,
+      "verification": "same-checkout business + interactive packed consumer; current Surface workflow reports",
+      "releaseGate": "Coordinate a tested UI release and verify the peer floor before publishing this new entry."
+    }
+  }
 }

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' | 'record';
+        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,206 @@
+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', 'record'].includes(widget.dataKind))
+            throw new Error('Invalid surface widget data kind');
+        if (widget.dataKind === 'record' && !widget.getReferencedFields)
+            throw new Error('Record widgets require an explicit field selector');
+        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')
+                        : widget.dataKind === 'record' ? Type.Literal('') : 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;