@svadmin/surface 0.8.19 → 0.10.0

package/dist/schema.d.ts

@@ -0,0 +1,108 @@
+export declare const surfaceIdSchema: import("@sinclair/typebox").TString;
+export declare const surfaceFilterSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+    field: import("@sinclair/typebox").TString;
+    operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"eq">, import("@sinclair/typebox").TLiteral<"ne">, import("@sinclair/typebox").TLiteral<"lt">, import("@sinclair/typebox").TLiteral<"lte">, import("@sinclair/typebox").TLiteral<"gt">, import("@sinclair/typebox").TLiteral<"gte">, import("@sinclair/typebox").TLiteral<"contains">, import("@sinclair/typebox").TLiteral<"startswith">, import("@sinclair/typebox").TLiteral<"endswith">]>;
+    value: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>;
+}>, import("@sinclair/typebox").TObject<{
+    field: import("@sinclair/typebox").TString;
+    operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"in">, import("@sinclair/typebox").TLiteral<"nin">]>;
+    value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>>;
+}>, import("@sinclair/typebox").TObject<{
+    field: import("@sinclair/typebox").TString;
+    operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"null">, import("@sinclair/typebox").TLiteral<"nnull">]>;
+}>]>;
+export declare const surfaceListSourceSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    type: import("@sinclair/typebox").TLiteral<"resource-list">;
+    resource: import("@sinclair/typebox").TString;
+    pageSize: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    sorters: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        field: import("@sinclair/typebox").TString;
+        order: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"asc">, import("@sinclair/typebox").TLiteral<"desc">]>;
+    }>>>;
+    filters: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+        field: import("@sinclair/typebox").TString;
+        operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"eq">, import("@sinclair/typebox").TLiteral<"ne">, import("@sinclair/typebox").TLiteral<"lt">, import("@sinclair/typebox").TLiteral<"lte">, import("@sinclair/typebox").TLiteral<"gt">, import("@sinclair/typebox").TLiteral<"gte">, import("@sinclair/typebox").TLiteral<"contains">, import("@sinclair/typebox").TLiteral<"startswith">, import("@sinclair/typebox").TLiteral<"endswith">]>;
+        value: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>;
+    }>, import("@sinclair/typebox").TObject<{
+        field: import("@sinclair/typebox").TString;
+        operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"in">, import("@sinclair/typebox").TLiteral<"nin">]>;
+        value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>>;
+    }>, import("@sinclair/typebox").TObject<{
+        field: import("@sinclair/typebox").TString;
+        operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"null">, import("@sinclair/typebox").TLiteral<"nnull">]>;
+    }>]>>>;
+}>;
+export declare const surfaceOneSourceSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    type: import("@sinclair/typebox").TLiteral<"resource-one">;
+    resource: import("@sinclair/typebox").TString;
+    recordId: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>;
+}>;
+export declare const surfaceLayoutSchema: import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"grid">;
+    columns: import("@sinclair/typebox").TLiteral<12>;
+    gap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"sm">, import("@sinclair/typebox").TLiteral<"md">, import("@sinclair/typebox").TLiteral<"lg">]>>;
+}>;
+export declare const surfaceWidgetSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    type: import("@sinclair/typebox").TString;
+    props: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+    binding: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        sourceId: import("@sinclair/typebox").TString;
+        pointer: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    placement: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        columnSpan: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>;
+}>;
+export declare const surfaceSpecSchema: import("@sinclair/typebox").TObject<{
+    schemaVersion: import("@sinclair/typebox").TString;
+    catalogVersion: import("@sinclair/typebox").TString;
+    surfaceId: import("@sinclair/typebox").TString;
+    title: import("@sinclair/typebox").TString;
+    layout: import("@sinclair/typebox").TObject<{
+        type: import("@sinclair/typebox").TLiteral<"grid">;
+        columns: import("@sinclair/typebox").TLiteral<12>;
+        gap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"sm">, import("@sinclair/typebox").TLiteral<"md">, import("@sinclair/typebox").TLiteral<"lg">]>>;
+    }>;
+    dataSources: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        type: import("@sinclair/typebox").TLiteral<"resource-list">;
+        resource: import("@sinclair/typebox").TString;
+        pageSize: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        sorters: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            order: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"asc">, import("@sinclair/typebox").TLiteral<"desc">]>;
+        }>>>;
+        filters: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"eq">, import("@sinclair/typebox").TLiteral<"ne">, import("@sinclair/typebox").TLiteral<"lt">, import("@sinclair/typebox").TLiteral<"lte">, import("@sinclair/typebox").TLiteral<"gt">, import("@sinclair/typebox").TLiteral<"gte">, import("@sinclair/typebox").TLiteral<"contains">, import("@sinclair/typebox").TLiteral<"startswith">, import("@sinclair/typebox").TLiteral<"endswith">]>;
+            value: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>;
+        }>, import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"in">, import("@sinclair/typebox").TLiteral<"nin">]>;
+            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>>;
+        }>, import("@sinclair/typebox").TObject<{
+            field: import("@sinclair/typebox").TString;
+            operator: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"null">, import("@sinclair/typebox").TLiteral<"nnull">]>;
+        }>]>>>;
+    }>, import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        type: import("@sinclair/typebox").TLiteral<"resource-one">;
+        resource: import("@sinclair/typebox").TString;
+        recordId: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>;
+    }>]>>;
+    widgets: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        type: import("@sinclair/typebox").TString;
+        props: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+        binding: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            sourceId: import("@sinclair/typebox").TString;
+            pointer: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
+        placement: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            columnSpan: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        }>>;
+    }>>;
+}>;

package/dist/schema.js

@@ -0,0 +1,73 @@
+import { Type } from '@sinclair/typebox';
+import { SURFACE_LIMITS } from './types.js';
+// 结构定义只维护一份：运行时校验与 AI 输出 schema 共用，策略校验仍在 validation.ts。
+export const surfaceIdSchema = Type.String({
+    minLength: 1,
+    maxLength: SURFACE_LIMITS.maxIdLength,
+    pattern: '^[A-Za-z][A-Za-z0-9_-]*$',
+});
+const fieldSchema = Type.String({ minLength: 1, maxLength: SURFACE_LIMITS.maxIdLength });
+const jsonPrimitiveSchema = Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]);
+export const surfaceFilterSchema = Type.Union([
+    Type.Object({
+        field: fieldSchema,
+        operator: Type.Union([
+            Type.Literal('eq'), Type.Literal('ne'), Type.Literal('lt'), Type.Literal('lte'),
+            Type.Literal('gt'), Type.Literal('gte'), Type.Literal('contains'),
+            Type.Literal('startswith'), Type.Literal('endswith'),
+        ]),
+        value: jsonPrimitiveSchema,
+    }, { additionalProperties: false }),
+    Type.Object({
+        field: fieldSchema,
+        operator: Type.Union([Type.Literal('in'), Type.Literal('nin')]),
+        value: Type.Array(jsonPrimitiveSchema),
+    }, { additionalProperties: false }),
+    Type.Object({
+        field: fieldSchema,
+        operator: Type.Union([Type.Literal('null'), Type.Literal('nnull')]),
+    }, { additionalProperties: false }),
+]);
+export const surfaceListSourceSchema = Type.Object({
+    id: surfaceIdSchema,
+    type: Type.Literal('resource-list'),
+    resource: surfaceIdSchema,
+    pageSize: Type.Optional(Type.Integer({ minimum: 1 })),
+    sorters: Type.Optional(Type.Array(Type.Object({
+        field: fieldSchema,
+        order: Type.Union([Type.Literal('asc'), Type.Literal('desc')]),
+    }, { additionalProperties: false }))),
+    filters: Type.Optional(Type.Array(surfaceFilterSchema)),
+}, { additionalProperties: false });
+export const surfaceOneSourceSchema = Type.Object({
+    id: surfaceIdSchema,
+    type: Type.Literal('resource-one'),
+    resource: surfaceIdSchema,
+    recordId: Type.Union([Type.String(), Type.Number()]),
+}, { additionalProperties: false });
+export const surfaceLayoutSchema = Type.Object({
+    type: Type.Literal('grid'),
+    columns: Type.Literal(12),
+    gap: Type.Optional(Type.Union([Type.Literal('sm'), Type.Literal('md'), Type.Literal('lg')])),
+}, { additionalProperties: false });
+export const surfaceWidgetSchema = Type.Object({
+    id: surfaceIdSchema,
+    type: surfaceIdSchema,
+    props: Type.Record(Type.String(), Type.Unknown()),
+    binding: Type.Optional(Type.Object({
+        sourceId: surfaceIdSchema,
+        pointer: Type.Optional(Type.String()),
+    }, { additionalProperties: false })),
+    placement: Type.Optional(Type.Object({
+        columnSpan: Type.Optional(Type.Integer({ minimum: 1, maximum: 12 })),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+export const surfaceSpecSchema = Type.Object({
+    schemaVersion: Type.String(),
+    catalogVersion: Type.String({ minLength: 1 }),
+    surfaceId: surfaceIdSchema,
+    title: Type.String({ minLength: 1, maxLength: SURFACE_LIMITS.maxTitleLength }),
+    layout: surfaceLayoutSchema,
+    dataSources: Type.Array(Type.Union([surfaceListSourceSchema, surfaceOneSourceSchema])),
+    widgets: Type.Array(surfaceWidgetSchema),
+}, { additionalProperties: false });

package/dist/server-sqlite.d.ts

@@ -0,0 +1 @@
+export { SqliteSurfaceWorkflowStore } from './workflows/sqlite-store.js';

package/dist/server-sqlite.js

@@ -0,0 +1,2 @@
+// Isolated Node adapter: importing @svadmin/surface never imports node:sqlite.
+export { SqliteSurfaceWorkflowStore } from './workflows/sqlite-store.js';

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+export { defineSurfaceAction } from './workflows/action-contracts.js';
+export { createSurfaceWorkflowService } from './workflows/service.js';
+export { SurfaceWorkflowError } from './workflows/types.js';
+export type { SurfaceActionDescriptor, SurfaceRegisteredAction, SurfaceActionProposal, SurfaceActionStatus, SurfaceWorkflowContext, SurfaceWorkflowStore, SurfaceWorkflowTransaction, SurfaceWorkflowAuditEvent, SurfaceStoredRevision, SurfaceWorkflowOptions, } from './workflows/types.js';

package/dist/server.js

@@ -0,0 +1,4 @@
+// This entry is server-only. Never re-export it from the DOM-free browser contract entry.
+export { defineSurfaceAction } from './workflows/action-contracts.js';
+export { createSurfaceWorkflowService } from './workflows/service.js';
+export { SurfaceWorkflowError } from './workflows/types.js';

package/dist/source-cache.d.ts

@@ -0,0 +1,30 @@
+import type { SurfaceDataSource, SurfaceResourcePolicy, SurfaceSourceDataState } from './types.js';
+/** Only query/projection inputs belong in this key, never widget or layout data. */
+export declare function snapshotSurfaceSource(source: SurfaceDataSource, policy: SurfaceResourcePolicy): {
+    source: SurfaceDataSource;
+    resourcePolicy: SurfaceResourcePolicy;
+    key: string;
+};
+export interface SurfaceSourceRequest {
+    readonly id: string;
+    /** Values compare by Object.is; provider and permission identities are not serialized. */
+    readonly identity: readonly unknown[];
+    readonly load: (isCurrent: () => boolean) => Promise<SurfaceSourceDataState>;
+    /** Also guards prop changes that happen before Svelte's next effect flush. */
+    readonly isCurrent: () => boolean;
+}
+export declare function sameSourceIdentity(left: readonly unknown[], right: readonly unknown[]): boolean;
+interface SourceCacheSink {
+    readonly set: (sourceId: string, state: SurfaceSourceDataState) => void;
+    readonly remove: (sourceId: string) => void;
+    readonly onError: (state: Extract<SurfaceSourceDataState, {
+        status: 'error';
+    }>) => void;
+}
+/** Per-renderer reconciliation, not a cross-user or cross-component data cache. */
+export declare function createSurfaceSourceCache(sink: SourceCacheSink): {
+    reconcile: (requests: readonly SurfaceSourceRequest[], force?: true | string) => Promise<void>;
+    clear: () => void;
+    dispose(): void;
+};
+export {};

package/dist/source-cache.js

@@ -0,0 +1,135 @@
+/** Only query/projection inputs belong in this key, never widget or layout data. */
+export function snapshotSurfaceSource(source, policy) {
+    const snapshot = source.type === 'resource-one'
+        ? { id: source.id, type: source.type, resource: source.resource, recordId: source.recordId }
+        : {
+            id: source.id,
+            type: source.type,
+            resource: source.resource,
+            pageSize: source.pageSize ?? 10,
+            sorters: (source.sorters ?? []).map(({ field, order }) => ({ field, order })),
+            filters: (source.filters ?? []).map((filter) => {
+                if (filter.operator === 'null' || filter.operator === 'nnull') {
+                    return { field: filter.field, operator: filter.operator };
+                }
+                if (filter.operator === 'in' || filter.operator === 'nin') {
+                    return { field: filter.field, operator: filter.operator, value: [...filter.value] };
+                }
+                return { ...filter };
+            }),
+        };
+    const resourcePolicy = {
+        readFields: [...new Set(policy.readFields)].sort(),
+        filterFields: [...new Set(policy.filterFields ?? [])].sort(),
+        sortFields: [...new Set(policy.sortFields ?? [])].sort(),
+        allowGetOne: policy.allowGetOne ?? false,
+        ...(policy.maxPageSize === undefined ? {} : { maxPageSize: policy.maxPageSize }),
+    };
+    // Tuples give deterministic keys even when JSON object property order changes.
+    // Array order (notably multi-column sorting) intentionally remains significant.
+    const query = snapshot.type === 'resource-one'
+        ? [snapshot.type, snapshot.resource, snapshot.recordId]
+        : [
+            snapshot.type, snapshot.resource, snapshot.pageSize,
+            snapshot.sorters?.map(({ field, order }) => [field, order]),
+            snapshot.filters?.map((filter) => [
+                filter.field, filter.operator, 'value' in filter ? filter.value : null,
+            ]),
+        ];
+    return {
+        source: snapshot,
+        resourcePolicy,
+        key: JSON.stringify([query, resourcePolicy]),
+    };
+}
+export function sameSourceIdentity(left, right) {
+    return left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
+}
+/** Per-renderer reconciliation, not a cross-user or cross-component data cache. */
+export function createSurfaceSourceCache(sink) {
+    const entries = new Map();
+    let disposed = false;
+    function clear() {
+        const ids = [...entries.keys()];
+        entries.clear(); // Retire every pending owner before emitting state changes.
+        for (const id of ids)
+            sink.remove(id);
+    }
+    function start(request) {
+        const entry = { identity: [...request.identity], pending: Promise.resolve() };
+        entries.set(request.id, entry);
+        const current = () => {
+            try {
+                return !disposed && entries.get(request.id) === entry && request.isCurrent();
+            }
+            catch {
+                return false;
+            }
+        };
+        const retire = () => {
+            if (entries.get(request.id) !== entry)
+                return;
+            entries.delete(request.id);
+            sink.remove(request.id);
+        };
+        sink.set(request.id, { status: 'loading', sourceId: request.id });
+        entry.pending = (async () => {
+            if (!current()) {
+                retire();
+                return;
+            }
+            let state;
+            try {
+                state = await request.load(current);
+            }
+            catch (failure) {
+                state = {
+                    status: 'error', sourceId: request.id,
+                    error: {
+                        code: 'provider_failed', sourceId: request.id,
+                        message: failure instanceof Error ? failure.message : 'Data provider request failed',
+                    },
+                };
+            }
+            if (!current()) {
+                retire();
+                return;
+            }
+            sink.set(request.id, state);
+            if (state.status === 'error')
+                sink.onError(state);
+        })();
+        return entry.pending;
+    }
+    async function reconcile(requests, force) {
+        if (disposed)
+            return;
+        const activeIds = new Set(requests.map((request) => request.id));
+        for (const id of entries.keys()) {
+            if (!activeIds.has(id)) {
+                entries.delete(id);
+                sink.remove(id);
+            }
+        }
+        const pending = [];
+        for (const request of requests) {
+            const existing = entries.get(request.id);
+            if (force === true || force === request.id || !existing
+                || !sameSourceIdentity(existing.identity, request.identity)) {
+                pending.push(start(request));
+            }
+            else if (force === undefined) {
+                pending.push(existing.pending);
+            }
+        }
+        await Promise.all(pending);
+    }
+    return {
+        reconcile,
+        clear,
+        dispose() {
+            disposed = true;
+            clear();
+        },
+    };
+}

package/dist/styles/editor.css

@@ -0,0 +1,124 @@
+@layer theme, base, components, utilities;
+
+@layer theme.sv-surface{
+  .svadmin-surface-editor {
+    --svsurface-colors-background: var(--card, #ffffff);
+    --svsurface-colors-foreground: var(--foreground, #18181b);
+    --svsurface-colors-muted: var(--muted-foreground, #52525b);
+    --svsurface-colors-border: var(--border, #d4d4d8);
+    --svsurface-colors-primary: var(--primary, #2563eb);
+    --svsurface-colors-on-primary: var(--primary-foreground, #ffffff);
+    --svsurface-colors-destructive: var(--destructive, #b91c1c);
+    --svsurface-spacing-sm: 0.5rem;
+    --svsurface-spacing-md: 0.75rem;
+    --svsurface-spacing-lg: 1rem;
+    --svsurface-radii-control: 0.375rem;
+    --svsurface-radii-panel: 0.75rem;
+}
+}
+
+@layer components.sv-surface{
+  @layer _base{
+
+    .svsurface-surface-editor {
+      border: 1px solid;
+      border-color: var(--svsurface-colors-border);
+      border-radius: var(--svsurface-radii-panel);
+      box-sizing: border-box;
+      background-color: var(--svsurface-colors-background);
+      color: var(--svsurface-colors-foreground);
+      font-family: inherit;
+      width: 100%;
+      min-width: 0;
+}
+
+    .svsurface-surface-editor [data-part="title"] {
+      margin: 0;
+      font-size: 1rem;
+      font-weight: 600;
+      overflow-wrap: anywhere;
+}
+
+    .svsurface-surface-editor [data-part="status"] {
+      margin: 0.25rem 0 0;
+      color: var(--svsurface-colors-muted);
+      font-size: 0.875rem;
+}
+
+    .svsurface-surface-editor [data-part="error"] {
+      border: 1px solid;
+      padding: var(--svsurface-spacing-md);
+      border-color: var(--svsurface-colors-destructive);
+      border-radius: var(--svsurface-radii-control);
+      color: var(--svsurface-colors-destructive);
+      overflow-wrap: anywhere;
+      margin-bottom: var(--svsurface-spacing-lg);
+}
+
+    .svsurface-surface-editor [data-part="toolbar"] {
+      gap: var(--svsurface-spacing-md);
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: var(--svsurface-spacing-lg);
+}
+
+    .svsurface-surface-editor [data-part="actions"] {
+      gap: var(--svsurface-spacing-sm);
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+}
+
+    .svsurface-surface-editor [data-part="viewport"] {
+      min-width: 0;
+}
+
+    .svsurface-surface-editor-button {
+      border: 1px solid;
+      padding: 0.5rem 0.875rem;
+      font: inherit;
+      border-color: var(--svsurface-colors-border);
+      border-radius: var(--svsurface-radii-control);
+      appearance: none;
+      -webkit-appearance: none;
+      font-size: 0.875rem;
+      line-height: 1.25;
+      cursor: pointer;
+      white-space: normal;
+      min-height: 2.5rem;
+      max-width: 100%;
+}
+
+    .svsurface-surface-editor-button:is(:disabled, [disabled], [data-disabled], [aria-disabled=true]) {
+      opacity: 0.5;
+      cursor: not-allowed;
+}
+
+    .svsurface-surface-editor-button:is(:focus-visible, [data-focus-visible]) {
+      outline: 2px solid;
+      outline-color: var(--svsurface-colors-primary);
+      outline-offset: 2px;
+}
+}
+
+  .svsurface-surface-editor--density_comfortable {
+    padding: var(--svsurface-spacing-lg);
+}
+
+  .svsurface-surface-editor--density_compact {
+    padding: var(--svsurface-spacing-md);
+}
+
+  .svsurface-surface-editor-button--variant_secondary {
+    background-color: var(--svsurface-colors-background);
+    color: var(--svsurface-colors-foreground);
+}
+
+  .svsurface-surface-editor-button--variant_primary {
+    border-color: var(--svsurface-colors-primary);
+    background-color: var(--svsurface-colors-primary);
+    color: var(--svsurface-colors-on-primary);
+}
+}

package/dist/styles/editor.d.ts

@@ -0,0 +1,8 @@
+export declare const editorClasses: {
+    readonly compact: "svsurface-surface-editor svsurface-surface-editor--density_compact";
+    readonly comfortable: "svsurface-surface-editor svsurface-surface-editor--density_comfortable";
+};
+export declare const editorButtonClasses: {
+    readonly secondary: "svsurface-surface-editor-button svsurface-surface-editor-button--variant_secondary";
+    readonly primary: "svsurface-surface-editor-button svsurface-surface-editor-button--variant_primary";
+};

package/dist/styles/editor.js

@@ -0,0 +1,9 @@
+// 本地有限变体，与 editor.css 一起维护。
+export const editorClasses = {
+    "compact": "svsurface-surface-editor svsurface-surface-editor--density_compact",
+    "comfortable": "svsurface-surface-editor svsurface-surface-editor--density_comfortable"
+};
+export const editorButtonClasses = {
+    "secondary": "svsurface-surface-editor-button svsurface-surface-editor-button--variant_secondary",
+    "primary": "svsurface-surface-editor-button svsurface-surface-editor-button--variant_primary"
+};

package/dist/styles.css

@@ -0,0 +1,43 @@
+/* 独立的有限语义样式；保持旧 UI peer 和无宿主编译器的消费方式。 */
+.svadmin-surface-metric__root,
+.svadmin-surface-table__root { min-width: 0; }
+.svadmin-surface-tone--neutral { --svadmin-surface-accent: var(--border); }
+.svadmin-surface-tone--success { --svadmin-surface-accent: var(--success); }
+.svadmin-surface-tone--warning { --svadmin-surface-accent: var(--warning); }
+.svadmin-surface-tone--danger { --svadmin-surface-accent: var(--destructive); }
+.svadmin-surface-tone--info { --svadmin-surface-accent: var(--info); }
+.svadmin-surface-density--compact {
+  --svadmin-surface-padding: 0.75rem;
+  --svadmin-surface-cell-padding: 0.25rem;
+  --svadmin-surface-cell-font: 0.75rem;
+  --svadmin-metric-state-padding: 0.75rem;
+  --svadmin-metric-state-height: 4.5rem;
+  --svadmin-table-state-height: 6rem;
+}
+.svadmin-surface-density--comfortable {
+  --svadmin-surface-padding: 1.25rem;
+  --svadmin-surface-cell-padding: 0.5rem;
+  --svadmin-surface-cell-font: 0.875rem;
+  --svadmin-metric-state-padding: 1.25rem;
+  --svadmin-metric-state-height: 6rem;
+  --svadmin-table-state-height: 8rem;
+}
+.svadmin-surface-metric__card.svadmin-surface-metric__card {
+  border-inline-start: 3px solid var(--svadmin-surface-accent);
+  padding: var(--svadmin-surface-padding);
+}
+.svadmin-surface-metric__description,
+.svadmin-surface-table__state { color: var(--muted-foreground); }
+.svadmin-surface-metric__state {
+  --svadmin-metric-state-border-width: 3px;
+  --svadmin-metric-state-accent: var(--svadmin-surface-accent);
+}
+.svadmin-surface-table__header.svadmin-surface-density--compact,
+.svadmin-surface-table__content.svadmin-surface-density--compact { padding-inline: 0.75rem; }
+.svadmin-surface-table__header.svadmin-surface-density--comfortable,
+.svadmin-surface-table__content.svadmin-surface-density--comfortable { padding-inline: 1rem; }
+.svadmin-surface-table__head[data-slot="table-head"],
+.svadmin-surface-table__cell[data-slot="table-cell"] {
+  padding-block: var(--svadmin-surface-cell-padding);
+  font-size: var(--svadmin-surface-cell-font);
+}

package/dist/svar-catalog.d.ts

@@ -0,0 +1,3 @@
+import { type SurfaceRenderCatalog } from './catalog.js';
+/** 扩展独立目录版本，不改变默认目录，也不允许覆盖其他可信组件注册。 */
+export declare function createSvarSurfaceCatalog(base?: SurfaceRenderCatalog): SurfaceRenderCatalog;

package/dist/svar-catalog.js

@@ -0,0 +1,7 @@
+import { defaultSurfaceCatalog, defineSurfaceCatalog } from './catalog.js';
+import SvarGridWidget from './components/SvarGridWidget.svelte';
+import { svarGridDefinition } from './svar-schema.js';
+/** 扩展独立目录版本，不改变默认目录，也不允许覆盖其他可信组件注册。 */
+export function createSvarSurfaceCatalog(base = defaultSurfaceCatalog) {
+    return defineSurfaceCatalog({ version: `${base.version}+svar/v1`, widgets: [...base.widgets, { ...svarGridDefinition, component: SvarGridWidget }] });
+}

package/dist/svar-context.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'svelte';
+import type SvarDataGrid from '@svadmin/ui/components/SvarDataGrid.svelte';
+export declare const SVAR_SURFACE_CONTEXT: unique symbol;
+export interface SvarSurfaceContext {
+    readonly Grid: ComponentProps<typeof SvarDataGrid>['Grid'];
+    readonly Theme: ComponentProps<typeof SvarDataGrid>['Theme'];
+    /** 非敏感的宿主作用域版本；不会写入 Surface spec。 */
+    readonly scopeKey: string | number;
+}

package/dist/svar-context.js

@@ -0,0 +1 @@
+export const SVAR_SURFACE_CONTEXT = Symbol('svadmin.surface.svar');

package/dist/svar-schema.d.ts

@@ -0,0 +1,21 @@
+import { type Static } from '@sinclair/typebox';
+import type { JsonObject, SurfaceWidgetDefinition } from './types.js';
+/** JSON-only 契约；宿主引擎、回调、URL 和写操作不属于 AI 可以生成的属性。 */
+export declare const svarGridPropsSchema: import("@sinclair/typebox").TObject<{
+    title: import("@sinclair/typebox").TString;
+    rowKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    height: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    density: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"compact">, import("@sinclair/typebox").TLiteral<"comfortable">]>>;
+    freezeLeft: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    freezeRight: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    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;
+        width: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"plain">, import("@sinclair/typebox").TLiteral<"number">, import("@sinclair/typebox").TLiteral<"percent">, import("@sinclair/typebox").TLiteral<"date">, import("@sinclair/typebox").TLiteral<"datetime">, import("@sinclair/typebox").TLiteral<"boolean">]>>;
+    }>>;
+}>;
+export type SvarGridProps = Static<typeof svarGridPropsSchema>;
+export declare function decodeSvarGridProps(props: JsonObject): SvarGridProps;
+export declare const svarGridDefinition: SurfaceWidgetDefinition;

package/dist/svar-schema.js

@@ -0,0 +1,36 @@
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+const field = Type.String({ minLength: 1, maxLength: 64, pattern: '^[A-Za-z][A-Za-z0-9_-]*$' });
+/** JSON-only 契约；宿主引擎、回调、URL 和写操作不属于 AI 可以生成的属性。 */
+export const svarGridPropsSchema = Type.Object({
+    title: Type.String({ minLength: 1, maxLength: 80 }),
+    rowKey: Type.Optional(field),
+    height: Type.Optional(Type.Integer({ minimum: 160, maximum: 1200 })),
+    density: Type.Optional(Type.Union([Type.Literal('compact'), Type.Literal('comfortable')])),
+    freezeLeft: Type.Optional(Type.Integer({ minimum: 0, maximum: 8 })),
+    freezeRight: Type.Optional(Type.Integer({ minimum: 0, maximum: 8 })),
+    emptyLabel: Type.Optional(Type.String({ minLength: 1, maxLength: 80 })),
+    columns: Type.Array(Type.Object({
+        field, label: Type.String({ minLength: 1, maxLength: 60 }),
+        width: Type.Optional(Type.Integer({ minimum: 60, maximum: 640 })),
+        format: Type.Optional(Type.Union([Type.Literal('plain'), Type.Literal('number'), Type.Literal('percent'), Type.Literal('date'), Type.Literal('datetime'), Type.Literal('boolean')])),
+    }, { additionalProperties: false }), { minItems: 1, maxItems: 16 }),
+}, { additionalProperties: false });
+export function decodeSvarGridProps(props) {
+    const value = Value.Decode(svarGridPropsSchema, props);
+    const keys = value.columns.map(column => column.field);
+    if (new Set(keys).size !== keys.length)
+        throw new Error('Duplicate grid columns');
+    if ((value.freezeLeft ?? 0) + (value.freezeRight ?? 0) > keys.length || (value.freezeRight ?? 0) >= keys.length) {
+        throw new Error('Frozen columns must leave a scrollable grid');
+    }
+    return value;
+}
+export const svarGridDefinition = {
+    type: 'data-grid', dataKind: 'items', propsSchema: svarGridPropsSchema,
+    getReferencedFields(props) {
+        const value = decodeSvarGridProps(props);
+        // 行标识也是一次字段读取，必须与显示列一样经过宿主白名单检查。
+        return [...new Set([value.rowKey ?? 'id', ...value.columns.map(column => column.field)])];
+    },
+};