@svadmin/surface 0.8.19 → 0.10.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 './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/business-data.d.ts

@@ -0,0 +1,16 @@
+import type { ActivityFeedProps } from './business-definitions.js';
+import type { JsonValue } from './types.js';
+import { type WidgetValueResult } from './widget-data.js';
+export interface SurfaceActivityItem {
+    id: string;
+    action: string;
+    timestamp: string;
+    user: {
+        name: string;
+    };
+    target?: string;
+    comment?: string;
+    status?: 'info' | 'success' | 'warning' | 'destructive';
+}
+/** 只映射选中的字段；不推断操作者、补造时间或把未知状态伪装成成功。 */
+export declare function asSurfaceActivities(value: JsonValue, props: ActivityFeedProps, unknownActor: string): WidgetValueResult<SurfaceActivityItem[]>;

package/dist/business-data.js

@@ -0,0 +1,42 @@
+import { asRecordArray } from './widget-data.js';
+/** 只映射选中的字段；不推断操作者、补造时间或把未知状态伪装成成功。 */
+export function asSurfaceActivities(value, props, unknownActor) {
+    const records = asRecordArray(value);
+    if (!records.ok)
+        return records;
+    if (records.value.length > 100)
+        return { ok: false, message: 'Too many activity records' };
+    const items = [];
+    const ids = new Set();
+    for (const record of records.value) {
+        const idValue = record[props.idField];
+        const action = record[props.actionField];
+        const timestamp = record[props.timestampField];
+        if (!((typeof idValue === 'string' && idValue.length > 0 && idValue.length <= 128)
+            || (typeof idValue === 'number' && Number.isFinite(idValue)))
+            || typeof action !== 'string' || !action.trim() || action.length > 500
+            || typeof timestamp !== 'string' || !timestamp.trim() || timestamp.length > 128) {
+            return { ok: false, message: 'Activity identity, action or timestamp is invalid' };
+        }
+        // 数字 1 与字符串 "1" 不得造成 keyed each 身份冲突。
+        const id = `${typeof idValue}:${idValue}`;
+        if (ids.has(id))
+            return { ok: false, message: 'Duplicate activity identity' };
+        ids.add(id);
+        const optional = [props.actorField, props.targetField, props.commentField, props.statusField]
+            .map((field) => field === undefined ? undefined : record[field]);
+        if (optional.some((item) => item != null && (typeof item !== 'string' || item.length > 4000))) {
+            return { ok: false, message: 'Optional activity text is invalid' };
+        }
+        const [actor, target, comment, status] = optional;
+        if (status != null && !['info', 'success', 'warning', 'destructive'].includes(String(status))) {
+            return { ok: false, message: 'Unknown activity status' };
+        }
+        items.push({ id, action, timestamp, user: { name: typeof actor === 'string' && actor.trim() ? actor : unknownActor },
+            ...(typeof target === 'string' ? { target } : {}),
+            ...(typeof comment === 'string' ? { comment } : {}),
+            ...(typeof status === 'string' ? { status: status } : {}),
+        });
+    }
+    return { ok: true, value: items };
+}

package/dist/business-definitions.d.ts

@@ -0,0 +1,28 @@
+import { type Static } from '@sinclair/typebox';
+import type { SurfaceCatalog } from './types.js';
+export declare const resourceDetailPropsSchema: import("@sinclair/typebox").TObject<{
+    fields: 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<string>[]>>;
+    }>>;
+    title: import("@sinclair/typebox").TString;
+    tone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"compact" | "comfortable">[]>>;
+}>;
+export declare const activityFeedPropsSchema: import("@sinclair/typebox").TObject<{
+    idField: import("@sinclair/typebox").TString;
+    actionField: import("@sinclair/typebox").TString;
+    timestampField: import("@sinclair/typebox").TString;
+    actorField: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    targetField: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    commentField: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    statusField: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    title: import("@sinclair/typebox").TString;
+    tone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"compact" | "comfortable">[]>>;
+}>;
+export type ResourceDetailProps = Static<typeof resourceDetailPropsSchema>;
+export type ActivityFeedProps = Static<typeof activityFeedPropsSchema>;
+/** 显式升级目录；旧目录、表单操作及默认权限不变。 */
+export declare function createBusinessSurfaceDefinitions(base?: SurfaceCatalog): SurfaceCatalog;

package/dist/business-definitions.js

@@ -0,0 +1,53 @@
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { styledSurfaceDefinitions } from './builtin-definitions.js';
+import { surfaceDesignContract } from './design-contract.js';
+const field = Type.String({ minLength: 1, maxLength: 64, pattern: '^[A-Za-z][A-Za-z0-9_-]*$' });
+const presentation = {
+    title: Type.String({ minLength: 1, maxLength: 80 }),
+    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 resourceDetailPropsSchema = Type.Object({
+    ...presentation,
+    fields: Type.Array(Type.Object({
+        field, label: Type.String({ minLength: 1, maxLength: 60 }),
+        format: Type.Optional(Type.Union(['text', 'number', 'date', 'boolean'].map((value) => Type.Literal(value)))),
+    }, { additionalProperties: false }), { minItems: 1, maxItems: 16 }),
+}, { additionalProperties: false });
+export const activityFeedPropsSchema = Type.Object({
+    ...presentation,
+    idField: field, actionField: field, timestampField: field,
+    actorField: Type.Optional(field), targetField: Type.Optional(field),
+    commentField: Type.Optional(field), statusField: Type.Optional(field),
+}, { additionalProperties: false });
+const definitions = [
+    {
+        type: 'resource-detail', dataKind: 'record', propsSchema: resourceDetailPropsSchema,
+        description: 'Read-only detail of one authorized record. Bind a permitted resource-one source with pointer "". Select up to sixteen distinct readable fields; never provide record values in props.',
+        examples: [{ title: 'Contact details', fields: [{ field: 'name', label: 'Name' }], density: 'compact' }],
+        getReferencedFields: (props) => {
+            const fields = Value.Decode(resourceDetailPropsSchema, props).fields.map((item) => item.field);
+            if (new Set(fields).size !== fields.length)
+                throw new Error('Detail fields must be distinct');
+            return fields;
+        },
+    },
+    {
+        type: 'activity-feed', dataKind: 'items', propsSchema: activityFeedPropsSchema,
+        description: 'Read-only activity timeline from an authorized resource-list /items binding. Explicitly map readable ID, action and timestamp fields; optional actor/target/comment/status fields also require read permission. No comment composer or mutations. Backend owns ordering and event authenticity; this is not proof of an audit trail.',
+        examples: [{ title: 'Recent activity', idField: 'id', actionField: 'action', timestampField: 'at', tone: 'info' }],
+        getReferencedFields: (props) => {
+            const p = Value.Decode(activityFeedPropsSchema, props);
+            return [p.idField, p.actionField, p.timestampField, p.actorField, p.targetField, p.commentField, p.statusField]
+                .filter((name) => typeof name === 'string');
+        },
+    },
+];
+/** 显式升级目录；旧目录、表单操作及默认权限不变。 */
+export function createBusinessSurfaceDefinitions(base = styledSurfaceDefinitions) {
+    const reserved = new Set(definitions.map((widget) => widget.type));
+    if (base.widgets.some((widget) => reserved.has(widget.type)))
+        throw new Error('Business widget type is already registered');
+    return { version: `${base.version}+business/v1`, widgets: [...base.widgets, ...definitions] };
+}

package/dist/business.d.ts

@@ -0,0 +1,3 @@
+import { type SurfaceRenderCatalog } from './catalog.js';
+/** 同一份 DOM-free 定义用于模型提示、服务端校验及真实组件。 */
+export declare function createBusinessSurfaceCatalog(base?: SurfaceRenderCatalog): SurfaceRenderCatalog;

package/dist/business.js

@@ -0,0 +1,17 @@
+import { defineSurfaceCatalog, styledSurfaceCatalog } from './catalog.js';
+import { createBusinessSurfaceDefinitions } from './business-definitions.js';
+import ResourceDetailWidget from './components/ResourceDetailWidget.svelte';
+import ActivityFeedWidget from './components/ActivityFeedWidget.svelte';
+/** 同一份 DOM-free 定义用于模型提示、服务端校验及真实组件。 */
+export function createBusinessSurfaceCatalog(base = styledSurfaceCatalog) {
+    const definitions = createBusinessSurfaceDefinitions(base);
+    const components = new Map(base.widgets.map((widget) => [widget.type, widget.component]));
+    components.set('resource-detail', ResourceDetailWidget);
+    components.set('activity-feed', ActivityFeedWidget);
+    return defineSurfaceCatalog({ ...definitions, widgets: definitions.widgets.map((widget) => {
+            const component = components.get(widget.type);
+            if (!component)
+                throw new Error(`Missing renderer for ${widget.type}`);
+            return { ...widget, component };
+        }) });
+}

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;