@svadmin/surface 0.9.0 → 0.11.0

package/README.md

@@ -6,11 +6,17 @@
 
 ## 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. Hosts do not need Panda or Tailwind compiler plugins to consume precompiled component styles.
+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';
@@ -137,7 +143,7 @@ The Svelte `SurfaceEditPreview` component accepts a controlled revision and untr
 
 It leaves the current surface intact during streaming, offers a separate preview/back action, and revalidates at the explicit apply click. It calls `onApply(candidate)` only for a valid proposal. The host performs any persistence with server authorization and atomic revision compare-and-swap, then updates `revision` and clears `proposal`. Missing handlers, invalid proposals and pending callbacks disable application. A rejected callback reports an error without changing the controlled revision. Changing scope does not authorize an old proposal: the host must discard old proposals as described above.
 
-The new preview controls use Panda build-time tokens/recipes and import their compiled CSS. `@svadmin/surface/editor.css` is also available for explicit CSS collection. Only finite density/button variants are emitted; host styles can override the existing complete-color semantic CSS variables. The integrated main already uses the compiler-free native/Panda build from PR #430; this preview adds its own scoped recipes without restoring Tailwind dependencies. The separate `@svadmin/surface/styles.css` entry for `styledSurfaceCatalog` remains available; see `STYLING.md`.
+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
 
@@ -182,4 +188,4 @@ Limits are eight data sources, 24 widgets, 100 rows per page, eight filters, thr
 
 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.
 
-See `docs/architecture/openui-surface-phase2.md` for the original feature scope and `docs/architecture/surface-integration-provenance.md` for its integration with the current native/Panda main. 中文指南见文档站的“声明式 Surface”。
+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

@@ -24,8 +24,10 @@ import { styledSurfaceCatalog, STYLED_SURFACE_CATALOG_VERSION } from '@svadmin/s
 
 以上只是 widget 片段；完整 spec 仍需要 schemaVersion、catalogVersion、数据源、绑定及布局等必要字段。
 
-Surface 自行打包预生成的 recipe 助手与 styles.css，避免让旧 UI peer 安装必须提供新增的 JS 导出入口。构建本仓库时先构建 UI 样式，再构建 Surface；消费发布包时不需要安装 Panda 或 Tailwind。配合尚未包含新 recipe CSS 的 UI 版本时必须加载 Surface 的 styles.css。
+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 定义或可执行代码。字段权限、只读查询、版本匹配和宿主确认要求不因样式变体而改变。
 
-本次是两类 Surface 组件的 recipes 试点；其他 UI 继续使用保留的原生兼容样式。OpenUI Lang 的解析、流式渲染适配、全量 UI recipe 重写以及 DTCG 文件转换器不在本次已实现范围。不能把 CSS 编译器移除等同于以上功能已经完成。
+此次仅替换样式基础设施。OpenUI 入口、catalog/schema 校验、workflow 授权与执行、提案预览及宿主确认逻辑保持不变；去除样式编译器不代表增加新的协议能力。

package/compatibility.json

@@ -1,16 +1,16 @@
 {
-  "surface": "0.9.x",
+  "surface": "0.11.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",
@@ -38,6 +38,17 @@
     "./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

@@ -13,7 +13,7 @@ export interface SurfaceCatalogManifest {
     readonly catalogVersion: string;
     readonly widgets: readonly {
         readonly type: string;
-        readonly dataKind: 'none' | 'scalar' | 'items';
+        readonly dataKind: 'none' | 'scalar' | 'items' | 'record';
         readonly description?: string;
         readonly propsSchema: JsonObject;
         readonly examples?: readonly JsonObject[];

package/dist/agent-contract.js

@@ -100,8 +100,10 @@ export function createSurfaceCatalogManifest(catalog) {
             throw new Error(`Invalid or duplicate surface widget type "${widget.type}"`);
         }
         known.add(widget.type);
-        if (!['none', 'scalar', 'items'].includes(widget.dataKind))
+        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`);
@@ -171,7 +173,8 @@ export function createSurfaceGenerationSpecSchema(catalog, policy) {
             ...(widget.dataKind === 'none' ? {} : {
                 binding: Type.Object({
                     sourceId: surfaceIdSchema,
-                    pointer: widget.dataKind === 'items' ? Type.Literal('/items') : literals([...scalarPointers]),
+                    pointer: widget.dataKind === 'items' ? Type.Literal('/items')
+                        : widget.dataKind === 'record' ? Type.Literal('') : literals([...scalarPointers]),
                 }, { additionalProperties: false }),
             }),
         }, { additionalProperties: false, ...(widget.description ? { description: widget.description } : {}) });

package/dist/builtin-schemas.js

@@ -1,4 +1,4 @@
-import { surfaceDesignContract } from './styled-system/design-contract.js';
+import { surfaceDesignContract } from './design-contract.js';
 import { Type } from "@sinclair/typebox";
 const catalogFieldSchema = Type.String({
     minLength: 1,

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/components/ActivityFeedWidget.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+  import { Value } from '@sinclair/typebox/value';
+  import ActivityFeed from '@svadmin/ui/components/ActivityFeed.svelte';
+  import { activityFeedPropsSchema } from '../business-definitions.js';
+  import { asSurfaceActivities } from '../business-data.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { surfaceMetric } from '../recipes.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
+
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const baseProps = $derived(Object.fromEntries(Object.entries(props).filter(([key]) => key !== 'appearance')));
+  const p = $derived(Value.Decode(activityFeedPropsSchema, baseProps));
+  const appearance = $derived(typeof props['appearance'] === 'object' && props['appearance'] !== null ? props['appearance'] as { tone?: typeof p.tone; density?: typeof p.density } : undefined);
+  const tone = $derived(appearance?.tone ?? p.tone ?? 'neutral');
+  const density = $derived(appearance?.density ?? p.density ?? 'comfortable');
+  const classes = $derived(surfaceMetric({ tone, density }));
+  const text = $derived(resolveSurfaceMessages(locale, messages));
+  const activities = $derived(data.status === 'ready' ? asSurfaceActivities(data.value, p, text.activityUnknownActor) : null);
+</script>
+
+<section class={classes.root + ' ' + classes.card} aria-label={p.title} data-surface-business="activity-feed" data-surface-density={density}>
+  {#if data.status === 'loading'}
+    <p role="status">{text.activityLoading}</p>
+  {:else if data.status === 'empty'}
+    <p role="status">{text.activityEmpty}</p>
+  {:else if data.status === 'error'}
+    <p role="alert">{text.activityUnavailable}</p>
+  {:else if activities?.ok}
+    <ActivityFeed activities={activities.value} allowComment={false} title={p.title} emptyLabel={text.activityEmpty}
+      countLabel={formatSurfaceMessage(text.activityCount, { count: activities.value.length })} />
+  {:else}
+    <p role="alert">{text.activityInvalidData}</p>
+  {/if}
+</section>

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

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

package/dist/components/MetricWidget.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { Value } from '@sinclair/typebox/value';
-  import { surfaceMetric } from '../styled-system/recipes/index.js';
+  import { surfaceMetric } from '../recipes.js';
+  import '../styles.css';
   import StatsCard from '@svadmin/ui/components/StatsCard.svelte';
   import { styledMetricPropsSchema as metricPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';

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

@@ -1,3 +1,4 @@
+import '../styles.css';
 import type { SurfaceWidgetRendererProps } from '../catalog.js';
 declare const MetricWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
 type MetricWidget = ReturnType<typeof MetricWidget>;

package/dist/components/ResourceDetailWidget.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+  import { Value } from '@sinclair/typebox/value';
+  import Card from '@svadmin/ui/components/ui/card/card.svelte';
+  import CardHeader from '@svadmin/ui/components/ui/card/card-header.svelte';
+  import CardTitle from '@svadmin/ui/components/ui/card/card-title.svelte';
+  import CardContent from '@svadmin/ui/components/ui/card/card-content.svelte';
+  import { resourceDetailPropsSchema } from '../business-definitions.js';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import type { JsonObject } from '../types.js';
+  import { surfaceMetric } from '../recipes.js';
+  import { resolveSurfaceMessages } from '../localization.js';
+  import { displayTableValue } from '../widget-data.js';
+
+  let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const baseProps = $derived(Object.fromEntries(Object.entries(props).filter(([key]) => key !== 'appearance')));
+  const p = $derived(Value.Decode(resourceDetailPropsSchema, baseProps));
+  const appearance = $derived(typeof props['appearance'] === 'object' && props['appearance'] !== null ? props['appearance'] as { tone?: typeof p.tone; density?: typeof p.density } : undefined);
+  const tone = $derived(appearance?.tone ?? p.tone ?? 'neutral');
+  const density = $derived(appearance?.density ?? p.density ?? 'comfortable');
+  const classes = $derived(surfaceMetric({ tone, density }));
+  const text = $derived(resolveSurfaceMessages(locale, messages));
+  const record = $derived(data.status === 'ready' && data.value !== null && typeof data.value === 'object' && !Array.isArray(data.value)
+    ? data.value as JsonObject : null);
+</script>
+
+<Card class={classes.root + ' ' + classes.card} data-surface-business="resource-detail" data-surface-density={density}>
+  <CardHeader><CardTitle>{p.title}</CardTitle></CardHeader>
+  <CardContent>
+    {#if data.status === 'loading'}
+      <p role="status">{text.detailLoading}</p>
+    {:else if data.status === 'empty'}
+      <p role="status">{text.detailEmpty}</p>
+    {:else if data.status === 'error'}
+      <p role="alert">{text.detailUnavailable}</p>
+    {:else if record}
+      <dl aria-label={p.title} data-density={density}>
+        {#each p.fields as item, index (`${index}:${item.field}`)}
+          <div>
+            <dt>{item.label}</dt>
+            <dd>{displayTableValue(record[item.field], { format: item.format, locale, messages: text })}</dd>
+          </div>
+        {/each}
+      </dl>
+    {:else}
+      <p role="alert">{text.detailInvalidData}</p>
+    {/if}
+  </CardContent>
+</Card>
+
+<style>
+  dl { display: grid; gap: 1rem; margin: 0; grid-template-columns: repeat(auto-fit, minmax(min(100%, 12rem), 1fr)); }
+  dl > div { min-width: 0; }
+  dt { color: var(--muted-foreground); font-size: .8125rem; }
+  dd { margin: .25rem 0 0; color: var(--foreground); overflow-wrap: anywhere; font-variant-numeric: tabular-nums; }
+  dl[data-density='compact'] { gap: .5rem; }
+</style>

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

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

package/dist/components/ResourceFormBody.svelte

@@ -6,7 +6,7 @@
   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 { editorClasses, editorButtonClasses } from '../styles/editor.js';
   import '../styles/editor.css';
   let { widgetId, host, action, title, locale }: {
     widgetId: string; host: SurfaceWorkflowHost; action: SurfaceActionDescriptor; title: string; locale: string;

package/dist/components/ResourceTableWidget.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { Value } from '@sinclair/typebox/value';
-  import { surfaceTable } from '../styled-system/recipes/index.js';
+  import { surfaceTable } from '../recipes.js';
+  import '../styles.css';
   import CardContent from '@svadmin/ui/components/ui/card/card-content.svelte';
   import CardHeader from '@svadmin/ui/components/ui/card/card-header.svelte';
   import CardTitle from '@svadmin/ui/components/ui/card/card-title.svelte';

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

@@ -1,3 +1,4 @@
+import '../styles.css';
 import type { SurfaceWidgetRendererProps } from '../catalog.js';
 declare const ResourceTableWidget: import("svelte").Component<SurfaceWidgetRendererProps, {}, "">;
 type ResourceTableWidget = ReturnType<typeof ResourceTableWidget>;

package/dist/components/SurfaceEditPreview.svelte

@@ -6,7 +6,7 @@
   import type { SurfaceRenderCatalog } from '../catalog.js';
   import type { SurfaceDataProvider, SurfacePolicy } from '../types.js';
   import SurfaceRenderer from './SurfaceRenderer.svelte';
-  import { editorClasses, editorButtonClasses } from '../styles/editor.generated.js';
+  import { editorClasses, editorButtonClasses } from '../styles/editor.js';
   import '../styles/editor.css';
 
   export interface SurfaceEditPreviewProps {

package/dist/components/SurfaceRenderer.svelte

@@ -16,7 +16,8 @@
   import { validateSurfaceSpec } from '../validation.js';
   import { createSurfaceSourceCache, sameSourceIdentity, snapshotSurfaceSource } from '../source-cache.js';
   import type { SurfaceSourceRequest } from '../source-cache.js';
-  import { surfaceMetric } from '../styled-system/recipes/index.js';
+  import { surfaceMetric } from '../recipes.js';
+  import '../styles.css';
   import { withoutSurfaceAppearance } from '../workflows/catalog.js';
 
   function appearanceClasses(props: JsonObject): string {

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

@@ -1,6 +1,7 @@
 import type { SurfaceRenderCatalog } from '../catalog.js';
 import type { SurfaceMessages } from '../localization.js';
 import type { SurfaceDataError, SurfaceDataProvider, SurfacePolicy, SurfaceValidationIssue } from '../types.js';
+import '../styles.css';
 export type SurfaceRendererError = {
     readonly type: 'validation';
     readonly issues: readonly SurfaceValidationIssue[];

package/dist/design-contract.d.ts

@@ -0,0 +1,2 @@
+export { surfaceDesignContract } from '@svadmin/ui/design-contract';
+export type { SurfaceTone, SurfaceDensity } from '@svadmin/ui/design-contract';

package/dist/design-contract.js

@@ -0,0 +1,2 @@
+// 唯一事实源是 UI 的纯数据入口，不加载 Svelte 或浏览器代码。
+export { surfaceDesignContract } from '@svadmin/ui/design-contract';

package/dist/localization.d.ts

@@ -11,8 +11,18 @@ export interface SurfaceMessages {
     readonly tableNoRecords: string;
     readonly tableInvalidData: string;
     readonly tableUnavailable: string;
+    readonly detailLoading?: string;
+    readonly detailEmpty?: string;
+    readonly detailUnavailable?: string;
+    readonly detailInvalidData?: string;
+    readonly activityLoading?: string;
+    readonly activityEmpty?: string;
+    readonly activityUnavailable?: string;
+    readonly activityInvalidData?: string;
+    readonly activityUnknownActor?: string;
+    readonly activityCount?: string;
     readonly booleanTrue: string;
     readonly booleanFalse: string;
 }
-export declare function resolveSurfaceMessages(locale: string, overrides?: Partial<SurfaceMessages>): SurfaceMessages;
+export declare function resolveSurfaceMessages(locale: string, overrides?: Partial<SurfaceMessages>): Required<SurfaceMessages>;
 export declare function formatSurfaceMessage(template: string, params: Readonly<Record<string, string | number>>): string;

package/dist/localization.js

@@ -11,6 +11,16 @@ const englishMessages = {
     tableNoRecords: 'No records',
     tableInvalidData: 'Table data is invalid',
     tableUnavailable: 'Table data is unavailable',
+    detailLoading: 'Loading record',
+    detailEmpty: 'No record',
+    detailUnavailable: 'Record is unavailable',
+    detailInvalidData: 'Record data is invalid',
+    activityLoading: 'Loading activity',
+    activityEmpty: 'No recent activity',
+    activityUnavailable: 'Activity is unavailable',
+    activityInvalidData: 'Activity data is invalid',
+    activityUnknownActor: 'Unknown actor',
+    activityCount: '{count} events',
     booleanTrue: 'Yes',
     booleanFalse: 'No',
 };
@@ -27,6 +37,16 @@ const simplifiedChineseMessages = {
     tableNoRecords: '暂无记录',
     tableInvalidData: '表格数据无效',
     tableUnavailable: '表格数据不可用',
+    detailLoading: '正在加载记录',
+    detailEmpty: '暂无记录',
+    detailUnavailable: '记录不可用',
+    detailInvalidData: '记录数据无效',
+    activityLoading: '正在加载动态',
+    activityEmpty: '暂无动态',
+    activityUnavailable: '动态不可用',
+    activityInvalidData: '动态数据无效',
+    activityUnknownActor: '未知操作者',
+    activityCount: '{count} 条动态',
     booleanTrue: '是',
     booleanFalse: '否',
 };

package/dist/openui.js

@@ -43,6 +43,21 @@ function element(value) {
         && typeof value.typeName === 'string'
         && !!value.props && typeof value.props === 'object';
 }
+function surfaceDataSource(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const source = value;
+    if (typeof source['id'] !== 'string' || typeof source['resource'] !== 'string')
+        return false;
+    if (source['type'] === 'resource-one') {
+        return typeof source['recordId'] === 'string' || typeof source['recordId'] === 'number';
+    }
+    if (source['type'] !== 'resource-list')
+        return false;
+    if (source['pageSize'] !== undefined && typeof source['pageSize'] !== 'number')
+        return false;
+    return true;
+}
 export function createSurfaceOpenUIStream(options) {
     const { catalog, policy } = options;
     const schema = createSurfaceOpenUISchema(catalog);
@@ -77,7 +92,8 @@ export function createSurfaceOpenUIStream(options) {
         for (const source of sources) {
             if (source === null && !final)
                 continue;
-            if (!element(source) || source.typeName !== 'Source' || source.partial || !isJsonValue(source.props['value'])) {
+            if (!element(source) || source.typeName !== 'Source' || source.partial
+                || !isJsonValue(source.props['value']) || !surfaceDataSource(source.props['value'])) {
                 throw new SurfaceOpenUIError('syntax', 'Invalid Source node');
             }
             dataSources.push(source.props['value']);

package/dist/recipes.d.ts

@@ -0,0 +1,20 @@
+import type { SurfaceDensity, SurfaceTone } from './design-contract.js';
+export declare function surfaceMetric({ tone, density, }?: {
+    tone?: SurfaceTone | undefined;
+    density?: SurfaceDensity | undefined;
+}): {
+    root: string;
+    card: string;
+    description: string;
+    state: string;
+};
+export declare function surfaceTable({ density }?: {
+    density?: SurfaceDensity | undefined;
+}): {
+    root: string;
+    header: string;
+    content: string;
+    head: string;
+    cell: string;
+    state: string;
+};

package/dist/recipes.js

@@ -0,0 +1,20 @@
+// 有限语义变体与静态 CSS 配套；不接受模型提供的 class/style。
+export function surfaceMetric({ tone = 'neutral', density = 'comfortable', } = {}) {
+    return {
+        root: 'svadmin-surface-metric__root',
+        card: `svadmin-surface-metric__card svadmin-surface-tone--${tone} svadmin-surface-density--${density}`,
+        description: 'svadmin-surface-metric__description',
+        state: `svadmin-surface-metric__state svadmin-surface-tone--${tone} svadmin-surface-density--${density}`,
+    };
+}
+export function surfaceTable({ density = 'comfortable' } = {}) {
+    const variant = `svadmin-surface-density--${density}`;
+    return {
+        root: 'svadmin-surface-table__root',
+        header: `svadmin-surface-table__header ${variant}`,
+        content: `svadmin-surface-table__content ${variant}`,
+        head: `svadmin-surface-table__head ${variant}`,
+        cell: `svadmin-surface-table__cell ${variant}`,
+        state: `svadmin-surface-table__state ${variant}`,
+    };
+}