@svadmin/surface 0.8.19 → 0.10.0

package/dist/components/SurfaceRenderer.svelte

@@ -1,22 +1,31 @@
 <script lang="ts">
-  import { canAccessAsync, captureAdminContext } from '@svadmin/core';
+  import { captureAdminContext, getLogoutVersion } from '@svadmin/core';
   import { useTranslation } from '@svadmin/core/i18n';
-  import { untrack } from 'svelte';
-  import { resolveSurfaceWidgetData } from '../binding.js';
+  import { onDestroy, untrack } from 'svelte';
+  import { SvelteMap } from 'svelte/reactivity';
+  import { resolveSurfaceSourceData } from '../binding.js';
   import { defaultSurfaceCatalog } from '../catalog.js';
   import type { SurfaceRenderCatalog } from '../catalog.js';
   import { loadSurfaceSource } from '../runtime.js';
   import { resolveSurfaceMessages } from '../localization.js';
   import type { SurfaceMessages } from '../localization.js';
   import type {
-    SurfaceDataError,
-    SurfaceDataProvider,
-    SurfaceDataSource,
-    SurfacePolicy,
-    SurfaceSourceDataState,
-    SurfaceValidationIssue,
+    SurfaceDataError, SurfaceDataProvider, SurfacePolicy,
+    SurfaceSourceDataState, SurfaceValidationIssue, JsonObject,
   } from '../types.js';
   import { validateSurfaceSpec } from '../validation.js';
+  import { createSurfaceSourceCache, sameSourceIdentity, snapshotSurfaceSource } from '../source-cache.js';
+  import type { SurfaceSourceRequest } from '../source-cache.js';
+  import { surfaceMetric } from '../recipes.js';
+  import '../styles.css';
+  import { withoutSurfaceAppearance } from '../workflows/catalog.js';
+
+  function appearanceClasses(props: JsonObject): string {
+    const appearance = props['appearance'] as { tone?: 'neutral' | 'success' | 'warning' | 'danger' | 'info'; density?: 'compact' | 'comfortable' } | undefined;
+    if (!appearance) return '';
+    const classes = surfaceMetric(appearance);
+    return `surface-appearance ${classes.root} ${classes.card}`;
+  }
 
   export type SurfaceRendererError =
     | { readonly type: 'validation'; readonly issues: readonly SurfaceValidationIssue[] }
@@ -27,6 +36,10 @@
     readonly policy: SurfacePolicy;
     readonly catalog?: SurfaceRenderCatalog;
     readonly dataProvider?: SurfaceDataProvider;
+    /** 可信宿主的用户/租户/授权会话标识；禁止使用凭证或模型提供的值。 */
+    readonly scopeKey?: string;
+    /** 与独立增量加载接口保持兼容；任一作用域标识变化都会清空状态。 */
+    readonly dataScopeKey?: string | number;
     readonly locale?: string;
     readonly messages?: Partial<SurfaceMessages>;
     readonly class?: string;
@@ -34,14 +47,8 @@
   }
 
   let {
-    spec,
-    policy,
-    catalog = defaultSurfaceCatalog,
-    dataProvider,
-    locale,
-    messages,
-    class: className = '',
-    onError,
+    spec, policy, catalog = defaultSurfaceCatalog, dataProvider, scopeKey = '', dataScopeKey,
+    locale, messages, class: className = '', onError,
   }: SurfaceRendererProps = $props();
 
   const adminContext = captureAdminContext();
@@ -50,182 +57,133 @@
   const activeMessages = $derived(resolveSurfaceMessages(activeLocale, messages));
   const validation = $derived(validateSurfaceSpec(spec, catalog, policy));
   const widgetRegistrations = $derived(new Map(catalog.widgets.map((widget) => [widget.type, widget])));
-  const currentSpec = $derived(validation.ok ? validation.value : null);
-  const sourceGenerations: Record<string, number> = Object.create(null) as Record<string, number>;
-  let sourceStates = $state.raw<Record<string, SurfaceSourceDataState>>({});
-
-  function nextGeneration(sourceId: string): number {
-    const generation = (sourceGenerations[sourceId] ?? 0) + 1;
-    sourceGenerations[sourceId] = generation;
-    return generation;
-  }
-
-  function setSourceState(sourceId: string, state: SurfaceSourceDataState): void {
-    sourceStates = { ...sourceStates, [sourceId]: state };
-  }
-
-  function providerFor(resource: string): SurfaceDataProvider {
-    return dataProvider ?? adminContext.getDataProviderForResource(resource);
-  }
-
-  async function authorize(resource: string, action: 'list' | 'show') {
-    return canAccessAsync(resource, action);
-  }
+  const sourceStates = new SvelteMap<string, SurfaceSourceDataState>();
+  let destroyed = false;
+  let previousScope: readonly unknown[] = [];
+  let widgetScopeRevision = $state(0);
+  const sessionIdentity = $derived([
+    validation.ok ? validation.value.surfaceId : undefined,
+    catalog.version, scopeKey, dataScopeKey, getLogoutVersion(),
+    adminContext.tenantCacheKey?.__svadminTenant,
+    adminContext.authProvider, adminContext.accessControlProvider,
+  ]);
+  // 复用 PR #428 的请求所有权与会话隔离实现，不维护第二套缓存。
+  const sourceCache = createSurfaceSourceCache({
+    set: (id, state) => { sourceStates.set(id, state); },
+    remove: (id) => { sourceStates.delete(id); },
+    onError: (state) => { onError?.({ type: 'data', error: state.error }); },
+  });
 
   function providerError(sourceId: string, failure: unknown): SurfaceSourceDataState {
     const message = failure instanceof Error ? failure.message : activeMessages.providerUnavailable;
-    return {
-      status: 'error',
-      sourceId,
-      error: { code: 'provider_failed', sourceId, message },
-    };
+    return { status: 'error', sourceId, error: { code: 'provider_failed', sourceId, message } };
   }
 
-  async function loadSource(source: SurfaceDataSource): Promise<void> {
-    const generation = nextGeneration(source.id);
-    setSourceState(source.id, { status: 'loading', sourceId: source.id });
-
-    let result: SurfaceSourceDataState;
-    try {
-      const resourcePolicy = Object.hasOwn(policy.resources, source.resource)
-        ? policy.resources[source.resource]
-        : undefined;
+  const sourceRequests: SurfaceSourceRequest[] = $derived.by(() => {
+    if (!validation.ok) return [];
+    const accessControl = adminContext.accessControlProvider;
+    const scope = sessionIdentity;
+    return validation.value.dataSources.map((source): SurfaceSourceRequest => {
+      const resourcePolicy = Object.hasOwn(policy.resources, source.resource) ? policy.resources[source.resource] : undefined;
       if (!resourcePolicy) throw new Error(`Resource "${source.resource}" is not allowed`);
-      result = await loadSurfaceSource({
-        source,
-        resourcePolicy,
-        provider: providerFor(source.resource),
-        authorize,
-      });
-    } catch (failure) {
-      result = providerError(source.id, failure);
-    }
-
-    if (sourceGenerations[source.id] !== generation) return;
-    setSourceState(source.id, result);
-    if (result.status === 'error') onError?.({ type: 'data', error: result.error });
-  }
-
-  async function loadSources(sources: readonly SurfaceDataSource[]): Promise<void> {
-    await Promise.all(sources.map(loadSource));
-  }
-
-  function invalidateCurrentSources(): void {
-    for (const sourceId of Object.keys(sourceGenerations)) nextGeneration(sourceId);
-    sourceStates = {};
-  }
+      const snapshot = snapshotSurfaceSource(source, resourcePolicy);
+      let provider: SurfaceDataProvider | undefined;
+      let providerFailure: unknown;
+      try {
+        provider = dataProvider ?? adminContext.getDataProviderForResource(source.resource);
+      } catch (failure) { providerFailure = failure; }
+      const identity = [snapshot.key, provider, provider?.getList, provider?.getOne, ...scope];
+      const isCurrent = () => !destroyed && sourceRequests.some((request) =>
+        request.id === snapshot.source.id && sameSourceIdentity(request.identity, identity));
+      return {
+        id: snapshot.source.id, identity, isCurrent,
+        async load(isRequestCurrent) {
+          if (!provider) return providerError(snapshot.source.id, providerFailure);
+          try {
+            return await loadSurfaceSource({
+              source: snapshot.source, resourcePolicy: snapshot.resourcePolicy, provider,
+              async authorize(resource, action) {
+                if (!isRequestCurrent()) return { can: false };
+                // 授权检查与缓存身份必须使用同一个所属上下文，不能回退到无关全局授权。
+                const meta = adminContext.getProviderMeta(resource);
+                const decision = accessControl
+                  ? await accessControl.can({ resource, action, ...(meta === undefined ? {} : { meta }) })
+                  : { can: true };
+                return isRequestCurrent() ? decision : { can: false };
+              },
+            });
+          } catch (failure) { return providerError(snapshot.source.id, failure); }
+        },
+      };
+    });
+  });
 
   export async function refresh(sourceId?: string): Promise<void> {
-    const activeSpec = currentSpec;
-    if (!activeSpec) return;
-    const sources = sourceId === undefined
-      ? activeSpec.dataSources
-      : activeSpec.dataSources.filter((source) => source.id === sourceId);
-    await loadSources(sources);
+    if (!validation.ok) { sourceCache.clear(); return; }
+    await untrack(() => sourceCache.reconcile(sourceRequests, sourceId ?? true));
   }
 
-  $effect(() => {
+  $effect.pre(() => {
     const validatedSpec = validation;
-    void dataProvider;
-    invalidateCurrentSources();
-    if (!validatedSpec.ok) {
-      onError?.({ type: 'validation', issues: validatedSpec.issues });
-      return;
-    }
-
+    const requests = sourceRequests;
+    const scope = sessionIdentity;
     untrack(() => {
-      void loadSources(validatedSpec.value.dataSources);
+      if (!sameSourceIdentity(previousScope, scope)) {
+        previousScope = [...scope];
+        widgetScopeRevision += 1;
+      }
+      if (!validatedSpec.ok) {
+        sourceCache.clear();
+        onError?.({ type: 'validation', issues: validatedSpec.issues });
+        return;
+      }
+      void sourceCache.reconcile(requests);
     });
   });
+  onDestroy(() => { destroyed = true; sourceCache.dispose(); });
 </script>
 
 {#if validation.ok}
-  <section
-    class="surface {className}"
-    aria-labelledby="surface-{validation.value.surfaceId}-title"
-    data-surface-id={validation.value.surfaceId}
-  >
-    <header class="surface-header">
-      <h2 id="surface-{validation.value.surfaceId}-title">{validation.value.title}</h2>
-    </header>
+  <section class="surface {className}" aria-labelledby="surface-{validation.value.surfaceId}-title" data-surface-id={validation.value.surfaceId}>
+    <header class="surface-header"><h2 id="surface-{validation.value.surfaceId}-title">{validation.value.title}</h2></header>
     <div class="surface-grid surface-gap-{validation.value.layout.gap ?? 'md'}">
-      {#each validation.value.widgets as widget (widget.id)}
-        {@const registration = widgetRegistrations.get(widget.type)}
-        {@const WidgetComponent = registration?.component}
-        <div
-          class="surface-widget surface-span-{widget.placement?.columnSpan ?? 12}"
-          data-testid="surface-widget-{widget.id}"
-        >
-          {#if WidgetComponent}
-            <WidgetComponent
-              widgetId={widget.id}
-              props={widget.props}
-              data={resolveSurfaceWidgetData(widget, sourceStates)}
-              locale={activeLocale}
-              messages={activeMessages}
-            />
-          {/if}
-        </div>
-      {/each}
+      {#key widgetScopeRevision}
+        {#each validation.value.widgets as widget (widget.id)}
+          {@const registration = widgetRegistrations.get(widget.type)}
+          {@const WidgetComponent = registration?.component}
+          {@const semantic = registration?.presentation === 'surface-appearance/v1'}
+          <div class="surface-widget surface-span-{widget.placement?.columnSpan ?? 12} {semantic ? appearanceClasses(widget.props) : ''}" data-testid="surface-widget-{widget.id}">
+            {#if WidgetComponent}
+              <WidgetComponent widgetId={widget.id} props={semantic ? withoutSurfaceAppearance(widget.props) : widget.props}
+                data={resolveSurfaceSourceData(widget, widget.binding ? sourceStates.get(widget.binding.sourceId) : undefined)}
+                locale={activeLocale} messages={activeMessages} />
+            {/if}
+          </div>
+        {/each}
+      {/key}
     </div>
   </section>
 {:else}
   <section class="surface-error {className}" role="alert" data-surface-error>
     <h2>{activeMessages.renderErrorTitle}</h2>
-    <ul>
-      {#each validation.issues as issue, issueIndex (`${issue.code}:${issue.path}:${issueIndex}`)}
-        <li><code>{issue.code}</code>: {issue.message}</li>
-      {/each}
-    </ul>
+    <ul>{#each validation.issues as issue, issueIndex (`${issue.code}:${issue.path}:${issueIndex}`)}
+      <li><code>{issue.code}</code>: {issue.message}</li>
+    {/each}</ul>
   </section>
 {/if}
 
 <style>
-  .surface,
-  .surface-error {
-    width: 100%;
-    min-width: 0;
-  }
-
-  .surface-header {
-    margin-bottom: 1rem;
-  }
-
-  .surface-header h2,
-  .surface-error h2 {
-    margin: 0;
-    color: var(--foreground);
-    font-size: clamp(1.25rem, 2vw, 1.75rem);
-    line-height: 1.2;
-  }
-
-  .surface-grid {
-    display: grid;
-    grid-template-columns: repeat(12, minmax(0, 1fr));
-  }
-
+  .surface, .surface-error { width: 100%; min-width: 0; }
+  .surface-header { margin-bottom: 1rem; }
+  .surface-header h2, .surface-error h2 { margin: 0; color: var(--foreground); font-size: clamp(1.25rem, 2vw, 1.75rem); line-height: 1.2; }
+  .surface-grid { display: grid; grid-template-columns: repeat(12, minmax(0, 1fr)); }
   .surface-gap-sm { gap: 0.5rem; }
   .surface-gap-md { gap: 1rem; }
   .surface-gap-lg { gap: 1.5rem; }
-
-  .surface-widget {
-    grid-column: 1 / -1;
-    min-width: 0;
-  }
-
-  .surface-error {
-    padding: 1rem;
-    border: 1px solid var(--destructive);
-    border-radius: 0.75rem;
-    background: var(--card);
-    color: var(--destructive);
-  }
-
-  .surface-error ul {
-    margin: 0.75rem 0 0;
-    padding-left: 1.25rem;
-  }
-
+  .surface-widget { grid-column: 1 / -1; min-width: 0; }
+  .surface-appearance { border-block: 1px solid var(--border); border-inline-end: 1px solid var(--border); border-inline-start-style: solid; border-radius: 0.75rem; background: var(--card); }
+  .surface-error { padding: 1rem; border: 1px solid var(--destructive); border-radius: 0.75rem; background: var(--card); color: var(--destructive); }
+  .surface-error ul { margin: 0.75rem 0 0; padding-left: 1.25rem; }
   @media (min-width: 48rem) {
     .surface-span-1 { grid-column: span 1; }
     .surface-span-2 { grid-column: span 2; }

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[];
@@ -13,6 +14,10 @@ export interface SurfaceRendererProps {
     readonly policy: SurfacePolicy;
     readonly catalog?: SurfaceRenderCatalog;
     readonly dataProvider?: SurfaceDataProvider;
+    /** 可信宿主的用户/租户/授权会话标识；禁止使用凭证或模型提供的值。 */
+    readonly scopeKey?: string;
+    /** 与独立增量加载接口保持兼容；任一作用域标识变化都会清空状态。 */
+    readonly dataScopeKey?: string | number;
     readonly locale?: string;
     readonly messages?: Partial<SurfaceMessages>;
     readonly class?: string;

package/dist/components/SurfaceWorkflowProvider.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import { setContext, type Snippet } from 'svelte';
+  import { SURFACE_WORKFLOW_CONTEXT, type SurfaceWorkflowHost } from '../workflows/context.js';
+  import type { SurfaceActionDescriptor, SurfaceActionProposal } from '../workflows/types.js';
+  import type { SurfaceWorkflowTransport } from '../workflows/client.js';
+  let { actions, transport, scopeKey, surfaceId, revision, enabled = false, onCommitted, children }: {
+    actions: readonly SurfaceActionDescriptor[]; transport: SurfaceWorkflowTransport;
+    scopeKey: string; surfaceId: string; revision: number;
+    /** Opt-in only after a complete validated surface is explicitly accepted. */
+    enabled?: boolean; onCommitted?: (proposal: SurfaceActionProposal) => void; children: Snippet;
+  } = $props();
+  const host: SurfaceWorkflowHost = {
+    getScope: () => ({ transport, scopeKey, surfaceId, revision, enabled }),
+    getAction: (id) => actions.find((action) => action.id === id),
+    committed: (proposal) => onCommitted?.(proposal),
+  };
+  setContext(SURFACE_WORKFLOW_CONTEXT, host);
+</script>
+
+{#key scopeKey}
+  {@render children()}
+{/key}

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

@@ -0,0 +1,17 @@
+import { type Snippet } from 'svelte';
+import type { SurfaceActionDescriptor, SurfaceActionProposal } from '../workflows/types.js';
+import type { SurfaceWorkflowTransport } from '../workflows/client.js';
+type $$ComponentProps = {
+    actions: readonly SurfaceActionDescriptor[];
+    transport: SurfaceWorkflowTransport;
+    scopeKey: string;
+    surfaceId: string;
+    revision: number;
+    /** Opt-in only after a complete validated surface is explicitly accepted. */
+    enabled?: boolean;
+    onCommitted?: (proposal: SurfaceActionProposal) => void;
+    children: Snippet;
+};
+declare const SurfaceWorkflowProvider: import("svelte").Component<$$ComponentProps, {}, "">;
+type SurfaceWorkflowProvider = ReturnType<typeof SurfaceWorkflowProvider>;
+export default SurfaceWorkflowProvider;

package/dist/components/SvarGridWidget.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import SvarDataGrid from '@svadmin/ui/components/SvarDataGrid.svelte';
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { SVAR_SURFACE_CONTEXT, type SvarSurfaceContext } from '../svar-context.js';
+  import { decodeSvarGridProps } from '../svar-schema.js';
+  import { asRecordArray } from '../widget-data.js';
+  import { resolveSurfaceMessages } from '../localization.js';
+
+  let { widgetId, props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
+  const host = getContext<SvarSurfaceContext | undefined>(SVAR_SURFACE_CONTEXT);
+  const labels = $derived(resolveSurfaceMessages(locale, messages));
+  const config = $derived(decodeSvarGridProps(props));
+  const records = $derived(data.status === 'ready' ? asRecordArray(data.value) : undefined);
+  const columns = $derived(config.columns.map(column => ({
+    key: column.field, label: column.label,
+    ...(column.width === undefined ? {} : { width: column.width }),
+    ...(column.format === undefined ? {} : { format: column.format }),
+  })));
+  const Grid = $derived(host?.Grid);
+  const Theme = $derived(host?.Theme);
+</script>
+
+<section aria-labelledby="svar-surface-{widgetId}" class="surface-data-grid">
+  <h3 id="svar-surface-{widgetId}">{config.title}</h3>
+  {#if !Grid || !Theme}
+    <p role="alert">{locale.startsWith('zh') ? '宿主尚未配置 SVAR 引擎' : 'The host has not configured the SVAR engine'}</p>
+  {:else if data.status === 'error'}
+    <p role="alert">{data.error.message}</p>
+  {:else if data.status === 'unbound' || (records && !records.ok)}
+    <p role="alert">{labels.tableInvalidData}</p>
+  {:else}
+    <SvarDataGrid {Grid} {Theme} {columns} items={records?.ok ? records.value : []}
+      primaryKey={config.rowKey ?? 'id'} height={config.height ?? 360} density={config.density ?? 'comfortable'}
+      freezeLeft={config.freezeLeft ?? 0} freezeRight={config.freezeRight ?? 0}
+      loading={data.status === 'loading'} label={config.title} {locale}
+      scopeKey={`${host?.scopeKey ?? 0}:${widgetId}:${'sourceId' in data ? data.sourceId : ''}`}
+      loadingLabel={labels.tableLoading} emptyLabel={config.emptyLabel ?? labels.tableNoRecords}
+      selectable={false} />
+  {/if}
+</section>
+
+<style>
+  .surface-data-grid { min-width: 0; padding: 1rem; background: var(--card, Canvas); color: var(--foreground, CanvasText); border: 1px solid var(--border, GrayText); border-radius: var(--radius, 8px); }
+  h3 { margin: 0 0 0.75rem; font-size: 1rem; }
+  [role='alert'] { color: var(--destructive, CanvasText); }
+</style>

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

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

package/dist/components/SvarSurfaceProvider.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import { setContext, type Snippet } from 'svelte';
+  import { SVAR_SURFACE_CONTEXT, type SvarSurfaceContext } from '../svar-context.js';
+  let { Grid, Theme, scopeKey = 0, children }: {
+    Grid: SvarSurfaceContext['Grid']; Theme: SvarSurfaceContext['Theme']; scopeKey?: string | number; children: Snippet;
+  } = $props();
+  setContext<SvarSurfaceContext>(SVAR_SURFACE_CONTEXT, {
+    get Grid() { return Grid; }, get Theme() { return Theme; }, get scopeKey() { return scopeKey; },
+  });
+</script>
+
+{@render children()}

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

@@ -0,0 +1,11 @@
+import { type Snippet } from 'svelte';
+import { type SvarSurfaceContext } from '../svar-context.js';
+type $$ComponentProps = {
+    Grid: SvarSurfaceContext['Grid'];
+    Theme: SvarSurfaceContext['Theme'];
+    scopeKey?: string | number;
+    children: Snippet;
+};
+declare const SvarSurfaceProvider: import("svelte").Component<$$ComponentProps, {}, "">;
+type SvarSurfaceProvider = ReturnType<typeof SvarSurfaceProvider>;
+export default SvarSurfaceProvider;

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/edits.d.ts

@@ -0,0 +1,57 @@
+import type { SurfaceAgentMessage } from './agent.js';
+import type { JsonObject, SurfaceCatalog, SurfaceDataSource, SurfaceGridLayout, SurfacePolicy, SurfaceSpec, SurfaceValidationIssue, SurfaceWidget } from './types.js';
+export declare const SURFACE_EDIT_SCHEMA_VERSION: "surface-edit/v1";
+export declare const SURFACE_EDIT_LIMITS: {
+    readonly maxOperations: 64;
+};
+export type SurfaceEditOperation = {
+    readonly op: 'set-title';
+    readonly value: string;
+} | {
+    readonly op: 'set-layout';
+    readonly value: SurfaceGridLayout;
+} | {
+    readonly op: 'upsert-widget';
+    readonly widget: SurfaceWidget;
+} | {
+    readonly op: 'remove-widget';
+    readonly id: string;
+} | {
+    readonly op: 'upsert-source';
+    readonly source: SurfaceDataSource;
+} | {
+    readonly op: 'remove-source';
+    readonly id: string;
+} | {
+    readonly op: 'reorder-widgets';
+    readonly ids: readonly string[];
+};
+export interface SurfaceEditProposal {
+    readonly schemaVersion: typeof SURFACE_EDIT_SCHEMA_VERSION;
+    readonly catalogVersion: string;
+    readonly surfaceId: string;
+    readonly baseRevision: number;
+    readonly operations: readonly SurfaceEditOperation[];
+}
+export interface SurfaceRevision {
+    readonly revision: number;
+    readonly spec: SurfaceSpec;
+}
+export interface SurfaceEditIssue extends Omit<SurfaceValidationIssue, 'code'> {
+    readonly code: SurfaceValidationIssue['code'] | 'revision_conflict' | 'invalid_edit';
+}
+export type SurfaceRevisionResult = {
+    readonly ok: true;
+    readonly value: SurfaceRevision;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SurfaceEditIssue[];
+};
+export declare function createSurfaceRevision(spec: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy, revision?: number): SurfaceRevisionResult;
+/**
+ * 只生成下一版候选快照，不保存、不渲染、不访问 DataProvider。
+ * 服务端保存时仍必须对 revision 做原子 compare-and-swap，并重新授权。
+ */
+export declare function applySurfaceEditProposal(current: SurfaceRevision, input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceRevisionResult;
+export declare function createSurfaceEditSchema(): JsonObject;
+export declare function buildSurfaceEditMessages(request: string, current: SurfaceRevision, catalog: SurfaceCatalog, policy: SurfacePolicy): readonly SurfaceAgentMessage[];