@svadmin/surface 0.8.19 → 0.9.0

package/dist/agent.js

@@ -1,78 +1,117 @@
 import { Type } from '@sinclair/typebox';
 import { TypeCompiler } from '@sinclair/typebox/compiler';
-import { jsonPointer } from './json.js';
+import { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_AGENT_SCHEMA_VERSION, createSurfaceAgentResponseSchema, createSurfaceCatalogManifest, createSurfaceGenerationSpecSchema, surfaceCannotFulfillSchema, surfaceSchemaToJson, } from './agent-contract.js';
 import { validateSurfaceSpec } from './validation.js';
-/** Wire version for model-produced, human-reviewable Surface proposals. */
-export const SURFACE_AGENT_SCHEMA_VERSION = 'surface-agent/v1';
-const proposalSchema = Type.Object({
+import { parseSurfaceJson, surfaceWireError } from './wire.js';
+export { SURFACE_AGENT_SCHEMA_VERSION } from './agent-contract.js';
+const proposalFields = {
     schemaVersion: Type.Literal(SURFACE_AGENT_SCHEMA_VERSION),
     action: Type.Literal('propose'),
     summary: Type.Optional(Type.String({ minLength: 1, maxLength: 240 })),
     spec: Type.Unknown(),
+};
+const proposalSchema = Type.Object(proposalFields, { additionalProperties: false });
+const responseProposalSchema = Type.Object({
+    ...proposalFields,
+    schemaVersion: Type.Literal(SURFACE_AGENT_RESPONSE_SCHEMA_VERSION),
 }, { additionalProperties: false });
 const compiledProposalSchema = TypeCompiler.Compile(proposalSchema);
-function parseCandidate(value) {
-    if (typeof value !== 'string')
-        return value;
-    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(value);
-    const source = fenced?.[1] ?? value.trim();
-    return JSON.parse(source);
+const compiledResponseSchema = TypeCompiler.Compile(Type.Union([
+    proposalSchema, responseProposalSchema, surfaceCannotFulfillSchema,
+]));
+function schemaIssues(errors) {
+    return [...errors].map((issue) => ({ code: 'invalid_json', path: issue.path || '', message: issue.message }));
 }
-function proposalIssue(message) {
-    return {
-        code: 'invalid_json',
-        path: '/',
-        message,
-    };
-}
-function proposalSchemaIssues(errors) {
-    return [...errors].map((issue) => ({
-        code: 'invalid_json',
-        path: issue.path || jsonPointer([]),
-        message: issue.message,
-    }));
-}
-/**
- * Parse and fully validate an AI-generated proposal before a host previews it.
- * This function has no side effects and never queries a provider.
- */
+/** 保留 v1 的函数签名、返回类型以及带说明文字的 fenced JSON 兼容行为。 */
 export function parseSurfaceAgentProposal(input, catalog, policy) {
-    let candidate;
-    try {
-        candidate = parseCandidate(input);
-    }
-    catch {
-        return { ok: false, issues: [proposalIssue('Agent proposal must be valid JSON')] };
+    const parsed = parseSurfaceJson(input, true);
+    if (!parsed.ok)
+        return parsed;
+    if (!compiledProposalSchema.Check(parsed.value)) {
+        return { ok: false, issues: schemaIssues(compiledProposalSchema.Errors(parsed.value)) };
     }
-    if (!compiledProposalSchema.Check(candidate)) {
-        return { ok: false, issues: proposalSchemaIssues(compiledProposalSchema.Errors(candidate)) };
+    const surface = validateSurfaceSpec(parsed.value.spec, catalog, policy);
+    if (!surface.ok)
+        return surface;
+    return { ok: true, value: { ...parsed.value, spec: surface.value } };
+}
+/** 结构化“无法完成”也是有效响应，但永远不是可渲染/可执行的提案。 */
+export function parseSurfaceAgentResponse(input, catalog, policy) {
+    const parsed = parseSurfaceJson(input);
+    if (!parsed.ok)
+        return parsed;
+    if (!compiledResponseSchema.Check(parsed.value)) {
+        return { ok: false, issues: schemaIssues(compiledResponseSchema.Errors(parsed.value)) };
     }
-    const parsed = candidate;
-    const surface = validateSurfaceSpec(parsed.spec, catalog, policy);
+    const candidate = parsed.value;
+    if (candidate.action === 'cannot-fulfill')
+        return { ok: true, value: candidate };
+    const surface = validateSurfaceSpec(candidate.spec, catalog, policy);
     if (!surface.ok)
         return surface;
+    return { ok: true, value: { ...candidate, spec: surface.value } };
+}
+const safetyInstructions = 'Never generate or execute Svelte, HTML, CSS, JavaScript, SQL, URLs, event handlers, or mutations. Use only catalog widgets and policy-authorized resources and fields. Widget IDs and source IDs must be unique across the document. Bind item widgets to /items, and scalar widgets to /total or an explicitly readable getOne field. JSON Schema does not replace runtime policy validation or server authorization.';
+function validateRequest(request) {
+    if (typeof request !== 'string' || request.trim().length === 0 || request.length > SURFACE_AGENT_LIMITS.maxRequestCharacters) {
+        throw new Error('Surface request must be non-empty and within the request character limit');
+    }
+}
+function contractContext(catalog, policy) {
+    const manifest = createSurfaceCatalogManifest(catalog);
+    const resources = Object.entries(policy.resources).map(([resource, rule]) => (`${resource}(read=${rule.readFields.join(',') || '(none)'};filter=${rule.filterFields?.join(',') || '(none)'};sort=${rule.sortFields?.join(',') || '(none)'};getOne=${rule.allowGetOne === true};maxPageSize=${rule.maxPageSize ?? 'default'})`)).join(' | ') || '(none)';
+    return `Catalog: ${JSON.stringify(manifest.catalogVersion)}\nComponent contracts: ${JSON.stringify(manifest)}\nResource policy: ${resources}\nPolicy JSON: ${JSON.stringify(policy)}`;
+}
+function boundedPrompt(prompt) {
+    if (prompt.length > SURFACE_AGENT_LIMITS.maxContractCharacters)
+        throw new Error('Surface prompt exceeds the contract character limit; select a smaller catalog');
+    return prompt;
+}
+/** 兼容旧 v1 输出，同时补齐从组件契约派生的完整参数/结构 schema。 */
+export function buildSurfaceAgentPrompt(request, catalog, policy) {
+    validateRequest(request);
+    const schema = surfaceSchemaToJson(Type.Object({
+        ...proposalFields,
+        spec: createSurfaceGenerationSpecSchema(catalog, policy),
+    }, { additionalProperties: false }));
+    return boundedPrompt(`${request}\n\n[svadmin surface agent protocol]\nReturn only a human-reviewable fenced JSON proposal. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${JSON.stringify(schema)}\nIf the request cannot be represented safely, explain the limitation without inventing fields or capabilities. For machine-readable cannot-fulfill responses use the surface-agent/v2 message API.`);
+}
+/** 系统契约与用户需求分开传递；不绑定某个模型厂商或 CSS 编译器。 */
+export function buildSurfaceAgentMessages(request, catalog, policy) {
+    validateRequest(request);
+    const content = boundedPrompt(`[svadmin surface agent protocol]\nReturn exactly one JSON object matching the output schema, without markdown or prose. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${JSON.stringify(createSurfaceAgentResponseSchema(catalog, policy))}\nIf the request cannot be represented, return action "cannot-fulfill" with a reason and a short message. Never invent capabilities or return an incomplete spec.`);
+    return [{ role: 'system', content }, { role: 'user', content: request }];
+}
+/** 有界传输缓冲，不冒充 OpenUI 增量渲染；半成品不进入运行时。 */
+export function createSurfaceAgentStream(catalog, policy) {
+    let chunks = [];
+    let characters = 0;
+    let result;
     return {
-        ok: true,
-        value: {
-            schemaVersion: SURFACE_AGENT_SCHEMA_VERSION,
-            action: 'propose',
-            ...(parsed.summary === undefined ? {} : { summary: parsed.summary }),
-            spec: surface.value,
+        push(chunk) {
+            if (result !== undefined)
+                return surfaceWireError('Surface stream is already closed');
+            if (typeof chunk !== 'string') {
+                result = surfaceWireError('Surface stream chunks must be text');
+            }
+            else if (characters + chunk.length > SURFACE_AGENT_LIMITS.maxInputCharacters) {
+                result = surfaceWireError('Surface stream is too large', 'limit_exceeded');
+            }
+            else {
+                characters += chunk.length;
+                if (chunk.length > 0)
+                    chunks.push(chunk);
+                return { ok: true, characters };
+            }
+            chunks = [];
+            return result;
+        },
+        finish() {
+            if (result === undefined) {
+                result = parseSurfaceAgentResponse(chunks.join(''), catalog, policy);
+                chunks = [];
+            }
+            return result;
         },
     };
 }
-/** Build a model instruction that keeps generation inside the Surface contract. */
-export function buildSurfaceAgentPrompt(request, catalog, policy) {
-    const widgetTypes = catalog.widgets.map((widget) => widget.type).join(', ') || '(none)';
-    const resources = Object.entries(policy.resources).map(([resource, resourcePolicy]) => {
-        const permissions = [
-            `read=${resourcePolicy.readFields.join(',') || '(none)'}`,
-            `filter=${resourcePolicy.filterFields?.join(',') || '(none)'}`,
-            `sort=${resourcePolicy.sortFields?.join(',') || '(none)'}`,
-            `getOne=${resourcePolicy.allowGetOne === true}`,
-            `maxPageSize=${resourcePolicy.maxPageSize ?? 'default'}`,
-        ];
-        return `${resource}(${permissions.join(';')})`;
-    }).join(' | ') || '(none)';
-    return `${request}\n\n[svadmin surface agent protocol]\nReturn only a human-reviewable fenced JSON proposal. Never generate or execute Svelte, HTML, CSS, JavaScript, SQL, URLs, event handlers, or mutations. The envelope must be {"schemaVersion":"${SURFACE_AGENT_SCHEMA_VERSION}","action":"propose","summary":"...","spec":{...}}. The spec must use schemaVersion "surface/v1" and catalogVersion "${catalog.version}". Allowed widget types: ${widgetTypes}. Resource policy: ${resources}. Use only catalog widgets and policy-authorized resources and fields. If the request cannot be represented safely, explain the limitation without inventing fields or capabilities.`;
-}

package/dist/binding.d.ts

@@ -1,2 +1,4 @@
 import type { SurfaceSourceDataState, SurfaceWidget, SurfaceWidgetDataState } from './types.js';
 export declare function resolveSurfaceWidgetData(widget: SurfaceWidget, sourceStates: Readonly<Record<string, SurfaceSourceDataState>>): SurfaceWidgetDataState;
+/** Resolve one binding without subscribing the widget to unrelated source states. */
+export declare function resolveSurfaceSourceData(widget: SurfaceWidget, sourceState: SurfaceSourceDataState | undefined): SurfaceWidgetDataState;

package/dist/binding.js

@@ -37,10 +37,16 @@ function missingPointerState(sourceId) {
     };
 }
 export function resolveSurfaceWidgetData(widget, sourceStates) {
+    const sourceId = widget.binding?.sourceId;
+    return resolveSurfaceSourceData(widget, sourceId !== undefined && Object.hasOwn(sourceStates, sourceId)
+        ? sourceStates[sourceId]
+        : undefined);
+}
+/** Resolve one binding without subscribing the widget to unrelated source states. */
+export function resolveSurfaceSourceData(widget, sourceState) {
     if (!widget.binding)
         return { status: 'unbound' };
     const sourceId = widget.binding.sourceId;
-    const sourceState = Object.hasOwn(sourceStates, sourceId) ? sourceStates[sourceId] : undefined;
     if (!sourceState)
         return { status: 'loading', sourceId };
     if (sourceState.status !== 'ready')

package/dist/builtin-definitions.d.ts

@@ -0,0 +1,6 @@
+import type { SurfaceCatalog } from './types.js';
+export declare const DEFAULT_SURFACE_CATALOG_VERSION: "svadmin/v1";
+export declare const STYLED_SURFACE_CATALOG_VERSION: "svadmin/styled-v1";
+/** The same definitions are consumed by Node validation and Svelte rendering. */
+export declare const defaultSurfaceDefinitions: SurfaceCatalog;
+export declare const styledSurfaceDefinitions: SurfaceCatalog;

package/dist/builtin-definitions.js

@@ -0,0 +1,40 @@
+import { Value } from '@sinclair/typebox/value';
+import { styledMetricPropsSchema, styledResourceTablePropsSchema, barChartPropsSchema, lineChartPropsSchema, metricPropsSchema, resourceTablePropsSchema, } from './builtin-schemas.js';
+export const DEFAULT_SURFACE_CATALOG_VERSION = 'svadmin/v1';
+export const STYLED_SURFACE_CATALOG_VERSION = 'svadmin/styled-v1';
+/** The same definitions are consumed by Node validation and Svelte rendering. */
+export const defaultSurfaceDefinitions = {
+    version: DEFAULT_SURFACE_CATALOG_VERSION,
+    widgets: [
+        { type: 'metric', dataKind: 'scalar',
+            description: 'Display a count or readable scalar. Bind list counts to /total; currency metrics require an ISO currency code.',
+            examples: [{ label: 'Total', format: 'number' }], propsSchema: metricPropsSchema },
+        { type: 'resource-table', dataKind: 'items',
+            description: 'Display up to eight explicitly readable resource fields. Bind to /items and select fields from the active resource policy.',
+            propsSchema: resourceTablePropsSchema,
+            getReferencedFields: (props) => Value.Decode(resourceTablePropsSchema, props).columns.map((column) => column.field) },
+        { type: 'bar-chart', dataKind: 'items',
+            description: 'Compare a readable numeric field by a readable label field. Bind to /items; aggregated data must come from an authorized backend resource.',
+            propsSchema: barChartPropsSchema,
+            getReferencedFields: (props) => { const p = Value.Decode(barChartPropsSchema, props); return [p.labelField, p.valueField]; } },
+        { type: 'line-chart', dataKind: 'items',
+            description: 'Show a trend using readable label and numeric fields. Bind to /items; request only policy-authorized sorting.',
+            propsSchema: lineChartPropsSchema,
+            getReferencedFields: (props) => { const p = Value.Decode(lineChartPropsSchema, props); return [p.labelField, p.valueField]; } },
+    ],
+};
+export const styledSurfaceDefinitions = {
+    version: STYLED_SURFACE_CATALOG_VERSION,
+    widgets: defaultSurfaceDefinitions.widgets.map((widget) => {
+        if (widget.type === 'metric')
+            return { ...widget, propsSchema: styledMetricPropsSchema,
+                description: 'Numeric KPI; tone and density select prebuilt semantic styles, never CSS.',
+                examples: [{ label: 'Pending orders', format: 'number', tone: 'warning', density: 'compact' }] };
+        if (widget.type === 'resource-table')
+            return { ...widget, propsSchema: styledResourceTablePropsSchema,
+                getReferencedFields: (props) => Value.Decode(styledResourceTablePropsSchema, props).columns.map((column) => column.field),
+                description: 'Read-only table; density is a prebuilt semantic variant.',
+                examples: [{ title: 'Inventory', columns: [{ field: 'name', label: 'Name' }], density: 'compact' }] };
+        return widget;
+    }),
+};

package/dist/builtin-schemas.d.ts

@@ -36,3 +36,28 @@ export type MetricProps = Static<typeof metricPropsSchema>;
 export type ResourceTableProps = Static<typeof resourceTablePropsSchema>;
 export type BarChartProps = Static<typeof barChartPropsSchema>;
 export type LineChartProps = Static<typeof lineChartPropsSchema>;
+export declare const styledMetricPropsSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+    tone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"compact" | "comfortable">[]>>;
+    label: import("@sinclair/typebox").TString;
+    format: import("@sinclair/typebox").TLiteral<"currency">;
+    currency: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>, import("@sinclair/typebox").TObject<{
+    tone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"compact" | "comfortable">[]>>;
+    label: import("@sinclair/typebox").TString;
+    format: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"number">, import("@sinclair/typebox").TLiteral<"percent">]>;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNever>;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>]>;
+export declare const styledResourceTablePropsSchema: import("@sinclair/typebox").TObject<{
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"compact" | "comfortable">[]>>;
+    title: import("@sinclair/typebox").TString;
+    emptyLabel: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    columns: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        field: import("@sinclair/typebox").TString;
+        label: import("@sinclair/typebox").TString;
+        format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"number">, import("@sinclair/typebox").TLiteral<"date">, import("@sinclair/typebox").TLiteral<"boolean">]>>;
+    }>>;
+}>;

package/dist/builtin-schemas.js

@@ -1,3 +1,4 @@
+import { surfaceDesignContract } from './styled-system/design-contract.js';
 import { Type } from "@sinclair/typebox";
 const catalogFieldSchema = Type.String({
     minLength: 1,
@@ -44,3 +45,15 @@ export const lineChartPropsSchema = Type.Object({
     showDots: Type.Optional(Type.Boolean()),
     fill: Type.Optional(Type.Boolean()),
 }, { additionalProperties: false });
+const styledMetricProperties = {
+    tone: Type.Optional(Type.Union(surfaceDesignContract.metric.tone.map((value) => Type.Literal(value)))),
+    density: Type.Optional(Type.Union(surfaceDesignContract.metric.density.map((value) => Type.Literal(value)))),
+};
+export const styledMetricPropsSchema = Type.Union([
+    Type.Object({ ...currencyMetric.properties, ...styledMetricProperties }, { additionalProperties: false }),
+    Type.Object({ ...otherMetric.properties, ...styledMetricProperties }, { additionalProperties: false }),
+]);
+export const styledResourceTablePropsSchema = Type.Object({
+    ...resourceTablePropsSchema.properties,
+    density: Type.Optional(Type.Union(surfaceDesignContract.table.density.map((value) => Type.Literal(value)))),
+}, { additionalProperties: false });

package/dist/catalog.d.ts

@@ -1,7 +1,7 @@
 import type { Component } from 'svelte';
 import type { JsonObject, SurfaceCatalog, SurfaceWidgetDataState, SurfaceWidgetDefinition } from './types.js';
 import type { SurfaceMessages } from './localization.js';
-export declare const DEFAULT_SURFACE_CATALOG_VERSION: "svadmin/v1";
+export { DEFAULT_SURFACE_CATALOG_VERSION, STYLED_SURFACE_CATALOG_VERSION } from './builtin-definitions.js';
 export interface SurfaceWidgetRendererProps {
     readonly widgetId: string;
     readonly props: JsonObject;
@@ -10,69 +10,12 @@ export interface SurfaceWidgetRendererProps {
     readonly messages?: SurfaceMessages;
 }
 export interface SurfaceWidgetRegistration extends SurfaceWidgetDefinition {
+    readonly presentation?: 'surface-appearance/v1';
     readonly component: Component<SurfaceWidgetRendererProps>;
 }
 export interface SurfaceRenderCatalog extends SurfaceCatalog {
     readonly widgets: readonly SurfaceWidgetRegistration[];
 }
 export declare function defineSurfaceCatalog<const TCatalog extends SurfaceRenderCatalog>(catalog: TCatalog): TCatalog;
-declare function tableFields(props: JsonObject): readonly string[];
-declare function barChartFields(props: JsonObject): readonly string[];
-declare function lineChartFields(props: JsonObject): readonly string[];
-export declare const defaultSurfaceCatalog: {
-    readonly version: "svadmin/v1";
-    readonly widgets: readonly [{
-        readonly type: "metric";
-        readonly dataKind: "scalar";
-        readonly propsSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
-            label: import("@sinclair/typebox").TString;
-            format: import("@sinclair/typebox").TLiteral<"currency">;
-            currency: import("@sinclair/typebox").TString;
-            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-        }>, import("@sinclair/typebox").TObject<{
-            label: import("@sinclair/typebox").TString;
-            format: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"number">, import("@sinclair/typebox").TLiteral<"percent">]>;
-            currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNever>;
-            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-        }>]>;
-        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
-    }, {
-        readonly type: "resource-table";
-        readonly dataKind: "items";
-        readonly propsSchema: import("@sinclair/typebox").TObject<{
-            title: import("@sinclair/typebox").TString;
-            emptyLabel: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-            columns: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
-                field: import("@sinclair/typebox").TString;
-                label: import("@sinclair/typebox").TString;
-                format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"number">, import("@sinclair/typebox").TLiteral<"date">, import("@sinclair/typebox").TLiteral<"boolean">]>>;
-            }>>;
-        }>;
-        readonly getReferencedFields: typeof tableFields;
-        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
-    }, {
-        readonly type: "bar-chart";
-        readonly dataKind: "items";
-        readonly propsSchema: import("@sinclair/typebox").TObject<{
-            title: import("@sinclair/typebox").TString;
-            labelField: import("@sinclair/typebox").TString;
-            valueField: import("@sinclair/typebox").TString;
-            showValues: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
-        }>;
-        readonly getReferencedFields: typeof barChartFields;
-        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
-    }, {
-        readonly type: "line-chart";
-        readonly dataKind: "items";
-        readonly propsSchema: import("@sinclair/typebox").TObject<{
-            title: import("@sinclair/typebox").TString;
-            labelField: import("@sinclair/typebox").TString;
-            valueField: import("@sinclair/typebox").TString;
-            showDots: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
-            fill: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
-        }>;
-        readonly getReferencedFields: typeof lineChartFields;
-        readonly component: Component<SurfaceWidgetRendererProps, {}, "">;
-    }];
-};
-export {};
+export declare const defaultSurfaceCatalog: SurfaceRenderCatalog;
+export declare const styledSurfaceCatalog: SurfaceRenderCatalog;

package/dist/catalog.js

@@ -3,8 +3,8 @@ import BarChartWidget from './components/BarChartWidget.svelte';
 import LineChartWidget from './components/LineChartWidget.svelte';
 import MetricWidget from './components/MetricWidget.svelte';
 import ResourceTableWidget from './components/ResourceTableWidget.svelte';
-import { barChartPropsSchema, lineChartPropsSchema, metricPropsSchema, resourceTablePropsSchema, } from './builtin-schemas.js';
-export const DEFAULT_SURFACE_CATALOG_VERSION = 'svadmin/v1';
+import { defaultSurfaceDefinitions, styledSurfaceDefinitions } from './builtin-definitions.js';
+export { DEFAULT_SURFACE_CATALOG_VERSION, STYLED_SURFACE_CATALOG_VERSION } from './builtin-definitions.js';
 export function defineSurfaceCatalog(catalog) {
     if (catalog.version.length === 0)
         throw new Error('Surface catalog version must not be empty');
@@ -13,49 +13,25 @@ export function defineSurfaceCatalog(catalog) {
         if (widgetTypes.has(widget.type))
             throw new Error(`Duplicate surface widget type "${widget.type}"`);
         widgetTypes.add(widget.type);
+        if ((widget.examples?.length ?? 0) > 3)
+            throw new Error('Catalog examples are limited to three per widget');
+        for (const example of widget.examples ?? []) {
+            if (!Value.Check(widget.propsSchema, example))
+                throw new Error('Invalid catalog example for ' + widget.type);
+        }
     }
     return catalog;
 }
-function tableFields(props) {
-    return Value.Decode(resourceTablePropsSchema, props).columns.map((column) => column.field);
+const components = {
+    metric: MetricWidget, 'resource-table': ResourceTableWidget, 'bar-chart': BarChartWidget, 'line-chart': LineChartWidget,
+};
+function rendered(definitions) {
+    return defineSurfaceCatalog({ ...definitions, widgets: definitions.widgets.map((widget) => {
+            const component = components[widget.type];
+            if (!component)
+                throw new Error(`Missing built-in component: ${widget.type}`);
+            return { ...widget, component };
+        }) });
 }
-function barChartFields(props) {
-    const chartProps = Value.Decode(barChartPropsSchema, props);
-    return [chartProps.labelField, chartProps.valueField];
-}
-function lineChartFields(props) {
-    const chartProps = Value.Decode(lineChartPropsSchema, props);
-    return [chartProps.labelField, chartProps.valueField];
-}
-export const defaultSurfaceCatalog = defineSurfaceCatalog({
-    version: DEFAULT_SURFACE_CATALOG_VERSION,
-    widgets: [
-        {
-            type: 'metric',
-            dataKind: 'scalar',
-            propsSchema: metricPropsSchema,
-            component: MetricWidget,
-        },
-        {
-            type: 'resource-table',
-            dataKind: 'items',
-            propsSchema: resourceTablePropsSchema,
-            getReferencedFields: tableFields,
-            component: ResourceTableWidget,
-        },
-        {
-            type: 'bar-chart',
-            dataKind: 'items',
-            propsSchema: barChartPropsSchema,
-            getReferencedFields: barChartFields,
-            component: BarChartWidget,
-        },
-        {
-            type: 'line-chart',
-            dataKind: 'items',
-            propsSchema: lineChartPropsSchema,
-            getReferencedFields: lineChartFields,
-            component: LineChartWidget,
-        },
-    ],
-});
+export const defaultSurfaceCatalog = rendered(defaultSurfaceDefinitions);
+export const styledSurfaceCatalog = rendered(styledSurfaceDefinitions);

package/dist/components/MetricWidget.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
   import { Value } from '@sinclair/typebox/value';
+  import { surfaceMetric } from '../styled-system/recipes/index.js';
   import StatsCard from '@svadmin/ui/components/StatsCard.svelte';
-  import { metricPropsSchema } from '../builtin-schemas.js';
+  import { styledMetricPropsSchema as metricPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
   import { resolveSurfaceMessages } from '../localization.js';
 
@@ -9,6 +10,8 @@
   const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const metricProps = $derived(Value.Decode(metricPropsSchema, props));
+  const metricClasses = $derived(metricProps.tone !== undefined || metricProps.density !== undefined
+    ? surfaceMetric({ tone: metricProps.tone, density: metricProps.density }) : undefined);
   const formattedValue = $derived.by(() => {
     if (data.status !== 'ready') return '—';
     const value = data.value;
@@ -26,17 +29,17 @@
   });
 </script>
 
-<article aria-labelledby="{widgetId}-label" aria-busy={data.status === 'loading'}>
+<article class={metricClasses?.root} data-surface-tone={metricProps.tone} data-surface-density={metricProps.density} aria-labelledby="{widgetId}-label" aria-busy={data.status === 'loading'}>
   <span id="{widgetId}-label" class="visually-hidden">{metricProps.label}</span>
   {#if data.status === 'loading'}
-    <StatsCard label={metricProps.label} value="" loading />
+    <StatsCard class={metricClasses?.card ?? ''} label={metricProps.label} value="" loading />
   {:else if data.status === 'ready' && typeof data.value === 'number'}
-    <StatsCard label={metricProps.label} value={formattedValue} />
+    <StatsCard class={metricClasses?.card ?? ''} label={metricProps.label} value={formattedValue} />
     {#if metricProps.description}
-      <p class="metric-description">{metricProps.description}</p>
+      <p class={"metric-description " + (metricClasses?.description ?? "")}>{metricProps.description}</p>
     {/if}
   {:else}
-    <div class="metric-state" role={data.status === 'error' ? 'alert' : 'status'}>
+    <div class={"metric-state " + (metricClasses?.state ?? "")} role={data.status === 'error' ? 'alert' : 'status'}>
       <strong>{metricProps.label}</strong>
       <span>{data.status === 'error' ? data.error.message : data.status === 'empty' ? activeMessages.metricNoData : activeMessages.metricInvalidData}</span>
     </div>
@@ -65,9 +68,10 @@
   .metric-state {
     display: grid;
     gap: 0.35rem;
-    min-height: 6rem;
-    padding: 1.25rem;
+    min-height: var(--svadmin-metric-state-height, 6rem);
+    padding: var(--svadmin-metric-state-padding, 1.25rem);
     border: 1px solid var(--border);
+    border-inline-start: var(--svadmin-metric-state-border-width, 1px) solid var(--svadmin-metric-state-accent, var(--border));
     border-radius: 0.75rem;
     background: var(--card);
     color: var(--muted-foreground);

package/dist/components/ResourceFormBody.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+  import { onDestroy, untrack } from 'svelte';
+  import { Value } from '@sinclair/typebox/value';
+  import JsonSchemaForm from '@svadmin/ui/components/JsonSchemaForm.svelte';
+  import { createSurfaceFormController, type SurfaceWorkflowClientState } from '../workflows/client.js';
+  import type { SurfaceWorkflowHost } from '../workflows/context.js';
+  import type { SurfaceActionDescriptor } from '../workflows/types.js';
+  import type { JsonObject } from '../types.js';
+  import { editorClasses, editorButtonClasses } from '../styles/editor.generated.js';
+  import '../styles/editor.css';
+  let { widgetId, host, action, title, locale }: {
+    widgetId: string; host: SurfaceWorkflowHost; action: SurfaceActionDescriptor; title: string; locale: string;
+  } = $props();
+  const instanceId = $props.id();
+  let value = $state<Record<string, unknown>>({});
+  let formState = $state<SurfaceWorkflowClientState>({ busy: false });
+  let errors = $state<string[]>([]);
+  const schema = $derived(JSON.parse(JSON.stringify(action.inputSchema)));
+  const zh = $derived(locale.startsWith('zh'));
+  const labels = $derived(zh ? {
+    submit: '提交操作提案', confirm: '确认这些参数', execute: '执行已批准操作', refresh: '查询状态', reject: '取消提案', reset: '开始新操作',
+    disabled: '预览模式：业务操作尚未启用', pending: '等待确认或独立审批', approved: '已批准，尚未执行',
+    executing: '正在执行，请勿重复提交', succeeded: '操作已完成', indeterminate: '结果不明确，需要服务端核对，禁止直接重试', rejected: '提案已取消',
+    error: '操作未完成。请先查询状态，避免重复执行。', args: '待确认参数',
+  } : {
+    submit: 'Propose action', confirm: 'Confirm these arguments', execute: 'Execute approved action', refresh: 'Check status', reject: 'Cancel proposal', reset: 'Start another action',
+    disabled: 'Preview mode: business actions are disabled', pending: 'Waiting for confirmation or independent approval', approved: 'Approved; not yet executed',
+    executing: 'Executing; do not submit again', succeeded: 'Action completed', indeterminate: 'Outcome unknown; server reconciliation is required before retry', rejected: 'Proposal cancelled',
+    error: 'Operation did not complete. Check status before retrying.', args: 'Arguments to confirm',
+  });
+  const scope = $derived(host.getScope());
+  const controller = untrack(() => createSurfaceFormController({ action, getScope: host.getScope,
+    onState: (next) => { formState = next; }, onCommitted: host.committed }));
+  let identity: readonly unknown[] = [];
+  $effect.pre(() => {
+    const next = [scope.scopeKey, scope.surfaceId, scope.revision, scope.transport, scope.enabled];
+    untrack(() => {
+      if (identity.length && next.some((part, index) => part !== identity[index])) {
+        controller.reset();
+        value = {};
+        errors = [];
+      }
+      identity = next;
+    });
+  });
+  onDestroy(() => controller.dispose());
+  async function submit(input: Record<string, unknown>) {
+    // Optional cleared fields may be undefined in a bound form; omission is the
+    // wire representation. The server repeats JSON and schema validation.
+    const args: unknown = JSON.parse(JSON.stringify(input));
+    if (!Value.Check(action.inputSchema, args)) {
+      errors = [...Value.Errors(action.inputSchema, args)].slice(0, 12).map((error) => `${error.path}: ${error.message}`);
+      return;
+    }
+    errors = [];
+    await controller.submit(args as JsonObject);
+  }
+</script>
+
+<section class="svadmin-surface-editor {editorClasses.comfortable}" aria-labelledby="{instanceId}-form-title" aria-busy={formState.busy}>
+  <h3 id="{instanceId}-form-title">{title}</h3>
+  {#if !scope.enabled}<p role="status">{labels.disabled}</p>{/if}
+  {#if errors.length}
+    <div role="alert"><ul>{#each errors as error, index (`${index}:${error}`)}<li>{error}</li>{/each}</ul></div>
+  {/if}
+  <fieldset disabled={!scope.enabled || formState.busy || !!formState.proposal} class="form-fields">
+    <JsonSchemaForm {schema} {locale} bind:value onsubmit={submit} submitText={labels.submit} idPrefix={`surface-${widgetId}-${instanceId}`} />
+  </fieldset>
+  {#if formState.error}<p role="alert">{labels.error}</p>{/if}
+  {#if formState.proposal}
+    {@const p = formState.proposal}
+    <section aria-label={p.actionLabel}>
+      <p role="status" data-workflow-status={p.status}>{labels[p.status]}</p>
+      <strong>{p.actionLabel}</strong>
+      <details><summary>{labels.args}</summary><pre>{JSON.stringify(p.args, null, 2)}</pre></details>
+      <div data-part="actions">
+        {#if p.status === 'pending' && p.approval === 'confirm'}
+          <button class={editorButtonClasses.secondary} disabled={formState.busy || !scope.enabled} onclick={() => controller.confirm()}>{labels.confirm}</button>
+        {/if}
+        {#if p.status === 'approved'}
+          <button class={editorButtonClasses.primary} disabled={formState.busy || !scope.enabled} onclick={() => controller.execute()}>{labels.execute}</button>
+        {/if}
+        <button class={editorButtonClasses.secondary} disabled={formState.busy || !scope.enabled} onclick={() => controller.refresh()}>{labels.refresh}</button>
+        {#if p.status === 'pending' || p.status === 'approved'}
+          <button class={editorButtonClasses.secondary} disabled={formState.busy || !scope.enabled} onclick={() => controller.reject()}>{labels.reject}</button>
+        {:else if p.status === 'succeeded' || p.status === 'rejected'}
+          <button class={editorButtonClasses.secondary} disabled={formState.busy} onclick={() => controller.reset()}>{labels.reset}</button>
+        {/if}
+      </div>
+    </section>
+  {/if}
+</section>
+
+<style>
+  .form-fields { border: 0; padding: 0; margin: 0; min-width: 0; }
+  pre { white-space: pre-wrap; overflow-wrap: anywhere; max-height: 16rem; overflow: auto; }
+</style>

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

@@ -0,0 +1,13 @@
+import type { SurfaceWorkflowHost } from '../workflows/context.js';
+import type { SurfaceActionDescriptor } from '../workflows/types.js';
+import '../styles/editor.css';
+type $$ComponentProps = {
+    widgetId: string;
+    host: SurfaceWorkflowHost;
+    action: SurfaceActionDescriptor;
+    title: string;
+    locale: string;
+};
+declare const ResourceFormBody: import("svelte").Component<$$ComponentProps, {}, "">;
+type ResourceFormBody = ReturnType<typeof ResourceFormBody>;
+export default ResourceFormBody;