@svadmin/surface 0.8.19 → 0.9.0

package/dist/components/ResourceFormWidget.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import type { SurfaceWidgetRendererProps } from '../catalog.js';
+  import { getSurfaceWorkflowHost } from '../workflows/context.js';
+  import ResourceFormBody from './ResourceFormBody.svelte';
+  let { widgetId, props, locale = 'en-US' }: SurfaceWidgetRendererProps = $props();
+  const host = getSurfaceWorkflowHost();
+  const action = $derived(host?.getAction(String(props['actionId'])));
+  const zh = $derived(locale.startsWith('zh'));
+</script>
+
+{#if host && action}
+  {#key `${action.id}:${action.version}`}
+    <ResourceFormBody {widgetId} {host} {action} title={typeof props['title'] === 'string' ? props['title'] : action.label} {locale} />
+  {/key}
+{:else}
+  <section role="status" data-surface-form-unavailable>
+    {zh ? '该表单尚未连接到已授权的业务操作。' : 'This form is not connected to an authorized business action.'}
+  </section>
+{/if}

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

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

package/dist/components/ResourceTableWidget.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { Value } from '@sinclair/typebox/value';
+  import { surfaceTable } from '../styled-system/recipes/index.js';
   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';
@@ -10,7 +11,7 @@
   import TableHeader from '@svadmin/ui/components/ui/table/table-header.svelte';
   import TableRow from '@svadmin/ui/components/ui/table/table-row.svelte';
   import Table from '@svadmin/ui/components/ui/table/table.svelte';
-  import { resourceTablePropsSchema } from '../builtin-schemas.js';
+  import { styledResourceTablePropsSchema as resourceTablePropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
   import { resolveSurfaceMessages } from '../localization.js';
   import { asRecordArray, displayTableValue } from '../widget-data.js';
@@ -19,27 +20,28 @@
   const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
 
   const tableProps = $derived(Value.Decode(resourceTablePropsSchema, props));
+  const tableClasses = $derived(tableProps.density === undefined ? undefined : surfaceTable({ density: tableProps.density }));
   const records = $derived(data.status === 'ready' ? asRecordArray(data.value) : null);
 </script>
 
-<Card>
-  <CardHeader>
+<Card class={tableClasses?.root} data-surface-density={tableProps.density}>
+  <CardHeader class={tableClasses?.header}>
     <CardTitle>{tableProps.title}</CardTitle>
   </CardHeader>
-  <CardContent>
+  <CardContent class={tableClasses?.content}>
     {#if data.status === 'loading'}
-      <div class="table-state table-loading" role="status">{activeMessages.tableLoading}</div>
+      <div class={"table-state table-loading " + (tableClasses?.state ?? "")} role="status">{activeMessages.tableLoading}</div>
     {:else if data.status === 'empty'}
-      <p class="table-state" role="status">{tableProps.emptyLabel ?? activeMessages.tableNoRecords}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="status">{tableProps.emptyLabel ?? activeMessages.tableNoRecords}</p>
     {:else if data.status === 'error'}
-      <p class="table-state" role="alert">{data.error.message}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="alert">{data.error.message}</p>
     {:else if data.status === 'ready' && records?.ok}
       <div class="surface-table">
-        <Table aria-label={tableProps.title}>
+        <Table density={tableProps.density ?? "comfortable"} aria-label={tableProps.title}>
           <TableHeader>
             <TableRow>
               {#each tableProps.columns as column (column.field)}
-                <TableHead scope="col">{column.label}</TableHead>
+                <TableHead class={tableClasses?.head} scope="col">{column.label}</TableHead>
               {/each}
             </TableRow>
           </TableHeader>
@@ -47,7 +49,7 @@
             {#each records.value as record, index (index)}
               <TableRow>
                 {#each tableProps.columns as column (column.field)}
-                  <TableCell>{displayTableValue(record[column.field], {
+                  <TableCell class={tableClasses?.cell}>{displayTableValue(record[column.field], {
                     format: column.format,
                     locale,
                     messages: activeMessages,
@@ -59,7 +61,7 @@
         </Table>
       </div>
     {:else}
-      <p class="table-state" role="alert">{records && !records.ok ? activeMessages.tableInvalidData : activeMessages.tableUnavailable}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="alert">{records && !records.ok ? activeMessages.tableInvalidData : activeMessages.tableUnavailable}</p>
     {/if}
   </CardContent>
 </Card>
@@ -67,7 +69,7 @@
 <style>
   .table-state {
     display: grid;
-    min-height: 8rem;
+    min-height: var(--svadmin-table-state-height, 8rem);
     margin: 0;
     place-items: center;
     color: var(--muted-foreground);

package/dist/components/SurfaceEditPreview.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+  import { useTranslation } from '@svadmin/core/i18n';
+  import { applySurfaceEditProposal } from '../edits.js';
+  import type { SurfaceRevision } from '../edits.js';
+  import { defaultSurfaceCatalog } from '../catalog.js';
+  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 '../styles/editor.css';
+
+  export interface SurfaceEditPreviewProps {
+    readonly revision: SurfaceRevision;
+    readonly proposal?: unknown;
+    readonly streaming?: boolean;
+    readonly policy: SurfacePolicy;
+    readonly catalog?: SurfaceRenderCatalog;
+    readonly dataProvider?: SurfaceDataProvider;
+    readonly scopeKey?: string;
+    readonly locale?: string;
+    readonly density?: 'compact' | 'comfortable';
+    /** 用户确认后返回候选快照。宿主负责持久化 CAS 与服务端授权。 */
+    readonly onApply?: (candidate: SurfaceRevision) => void | Promise<void>;
+  }
+
+  let {
+    revision, proposal, streaming = false, policy, catalog = defaultSurfaceCatalog,
+    dataProvider, scopeKey = '', locale, density = 'comfortable', onApply,
+  }: SurfaceEditPreviewProps = $props();
+  const i18n = useTranslation();
+  const activeLocale = $derived(locale ?? i18n.locale);
+  const labels = $derived(activeLocale.startsWith('zh') ? {
+    title: '界面修改提案', current: '当前版本', preview: '预览修改', back: '返回当前',
+    apply: '确认应用', loading: '正在接收提案；当前界面保持不变', empty: '尚无修改提案',
+    invalid: '提案未通过校验，不能应用', ready: '提案已校验，尚未应用',
+    previewing: '正在预览，尚未应用', applying: '正在应用', failed: '应用失败，请重新确认后重试',
+    readonly: '当前宿主未配置应用操作',
+  } : {
+    title: 'Surface edit proposal', current: 'Current revision', preview: 'Preview changes', back: 'Back to current',
+    apply: 'Apply changes', loading: 'Receiving proposal; current surface is unchanged', empty: 'No edit proposal',
+    invalid: 'Proposal is invalid and cannot be applied', ready: 'Validated proposal; not applied',
+    previewing: 'Preview only; not applied', applying: 'Applying changes', failed: 'Application failed; confirm again to retry',
+    readonly: 'No apply handler is configured',
+  });
+  const candidate = $derived(streaming || proposal === undefined || proposal === null || proposal === ''
+    ? null : applySurfaceEditProposal(revision, proposal, catalog, policy));
+  const candidateKey = $derived(candidate?.ok ? JSON.stringify([scopeKey, candidate.value]) : '');
+  let selectedPreview = $state('');
+  let applying = $state(false);
+  let failureKey = $state('');
+  const previewing = $derived(candidateKey !== '' && selectedPreview === candidateKey && !streaming);
+  const visibleSpec = $derived(previewing && candidate?.ok ? candidate.value.spec : revision.spec);
+  const status = $derived(streaming ? labels.loading : applying ? labels.applying : candidate === null
+    ? labels.empty : !candidate.ok ? labels.invalid : previewing ? labels.previewing : labels.ready);
+
+  async function apply(): Promise<void> {
+    if (streaming || applying || !onApply) return;
+    // 点击时使用最新 revision/policy 重新校验，不复用旧预览作为权限凭据。
+    const latest = applySurfaceEditProposal(revision, proposal, catalog, policy);
+    if (!latest.ok) return;
+    const submittedKey = candidateKey;
+    applying = true;
+    failureKey = '';
+    try {
+      await onApply(latest.value);
+      selectedPreview = '';
+    } catch {
+      failureKey = submittedKey;
+    } finally {
+      applying = false;
+    }
+  }
+</script>
+
+<section class="svadmin-surface-editor {editorClasses[density]}" aria-label={labels.title} data-density={density}>
+  <div data-part="toolbar">
+    <div>
+      <h3 data-part="title">{labels.title}</h3>
+      <p data-part="status" role="status" aria-live="polite">{status} · {labels.current} {revision.revision}</p>
+    </div>
+    <div data-part="actions">
+      <button type="button" class={editorButtonClasses.secondary}
+        disabled={streaming || applying || !candidate?.ok} aria-pressed={previewing}
+        onclick={() => { selectedPreview = previewing ? '' : candidateKey; }}
+      >{previewing ? labels.back : labels.preview}</button>
+      <button type="button" class={editorButtonClasses.primary}
+        disabled={streaming || applying || !candidate?.ok || !onApply}
+        title={onApply ? undefined : labels.readonly} onclick={apply}
+      >{applying ? labels.applying : labels.apply}</button>
+    </div>
+  </div>
+  {#if candidate && !candidate.ok}
+    <div data-part="error" role="alert">
+      {labels.invalid}
+      <ul>{#each candidate.issues as issue, index (`${issue.code}:${issue.path}:${index}`)}
+        <li><code>{issue.code}</code>: {issue.message}</li>
+      {/each}</ul>
+    </div>
+  {/if}
+  {#if failureKey !== '' && failureKey === candidateKey}
+    <div data-part="error" role="alert">{labels.failed}</div>
+  {/if}
+  <div data-part="viewport" data-preview={previewing}>
+    <SurfaceRenderer spec={visibleSpec} {policy} {catalog} {scopeKey} locale={activeLocale}
+      {...(dataProvider === undefined ? {} : { dataProvider })} />
+  </div>
+</section>

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

@@ -0,0 +1,20 @@
+import type { SurfaceRevision } from '../edits.js';
+import type { SurfaceRenderCatalog } from '../catalog.js';
+import type { SurfaceDataProvider, SurfacePolicy } from '../types.js';
+import '../styles/editor.css';
+export interface SurfaceEditPreviewProps {
+    readonly revision: SurfaceRevision;
+    readonly proposal?: unknown;
+    readonly streaming?: boolean;
+    readonly policy: SurfacePolicy;
+    readonly catalog?: SurfaceRenderCatalog;
+    readonly dataProvider?: SurfaceDataProvider;
+    readonly scopeKey?: string;
+    readonly locale?: string;
+    readonly density?: 'compact' | 'comfortable';
+    /** 用户确认后返回候选快照。宿主负责持久化 CAS 与服务端授权。 */
+    readonly onApply?: (candidate: SurfaceRevision) => void | Promise<void>;
+}
+declare const SurfaceEditPreview: import("svelte").Component<SurfaceEditPreviewProps, {}, "">;
+type SurfaceEditPreview = ReturnType<typeof SurfaceEditPreview>;
+export default SurfaceEditPreview;

package/dist/components/SurfaceRenderer.svelte

@@ -1,22 +1,30 @@
 <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 '../styled-system/recipes/index.js';
+  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 +35,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 +46,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 +56,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

@@ -13,6 +13,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;