@svadmin/surface 0.14.3 → 0.17.0

package/README.md

@@ -119,6 +119,31 @@ if (response.ok && response.value.action === 'propose') {
 
 Use the same task-scoped catalog for generation, validation and rendering. JSON Schema narrows generation but does not replace cross-source binding checks, field policy or server authorization. The schema is not claimed to match every vendor's restricted structured-output subset.
 
+### Inline chat answers
+
+A chat host can answer with prose plus one inline card instead of a JSON-only reply. Pass `{ presentation: 'chat' }`, then split the streamed answer with `splitSurfaceAgentText()`:
+
+```ts
+import {
+  SURFACE_AGENT_FENCE_TAG,
+  buildSurfaceAgentMessages,
+  parseSurfaceAgentResponse,
+  splitSurfaceAgentText,
+} from '@svadmin/surface';
+
+const messages = buildSurfaceAgentMessages(request, catalog, policy, { presentation: 'chat' });
+// 边生成边切分；未闭合的 surface 围栏返回 complete: false。
+for (const segment of splitSurfaceAgentText(streamedText, { streaming: true })) {
+  if (segment.kind === 'text') renderMarkdown(segment.text);
+  else if (segment.complete) {
+    const parsed = parseSurfaceAgentResponse(segment.json, catalog, policy);
+    if (parsed.ok && parsed.value.action === 'propose') renderPreview(parsed.value.spec);
+  }
+}
+```
+
+Only fences tagged `surface` (```` ```surface ````) are treated as proposals; every other fence stays in the prose, so ordinary JSON or shell snippets are never mistaken for a card. An unterminated fence becomes an incomplete segment only while `streaming` is true, which keeps partial JSON out of the renderer while the answer is still generating. Segmentation is presentation only: it does not validate, query data, render, or replace the host approval step.
+
 `buildSurfaceAgentPrompt()` and `parseSurfaceAgentProposal()` remain compatible with the legacy proposal-only `surface-agent/v1` envelope. The new message API uses `surface-agent/v2` with a structured `cannot-fulfill` alternative. `createSurfaceAgentStream()` buffers bounded text and validates at `finish()`; it does **not** render partial JSON or implement OpenUI Lang streaming.
 
 ## Revisioned edits and explicit preview

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "surface": "0.14.x",
+  "surface": "0.17.x",
   "minimumSupported": {
     "@svadmin/core": "0.53.0",
     "@svadmin/ui": "0.73.0",

package/dist/agent-text.d.ts

@@ -0,0 +1,27 @@
+/** 聊天回答里标记界面提案的围栏标签，例如 ```surface。 */
+export declare const SURFACE_AGENT_FENCE_TAG = "surface";
+/** 聊天回答切分后的片段：普通正文，或一段待校验的界面提案 JSON。 */
+export type SurfaceAgentTextSegment = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'proposal';
+    readonly json: string;
+    readonly complete: boolean;
+};
+export interface SurfaceAgentTextOptions {
+    /** 生成尚未结束时，未闭合的 surface 围栏作为未完成提案返回。 */
+    readonly streaming?: boolean;
+}
+/**
+ * 把聊天回答切成正文与界面提案，供宿主内联渲染。
+ *
+ * 只识别 `surface` 标签的围栏；其它围栏（例如 json 代码块）原样留在正文里，
+ * 避免把普通代码误当成界面提案。片段内容不做校验，宿主仍需按 catalog 和
+ * policy 调用 `parseSurfaceAgentResponse()` 或 `parseSurfaceAgentProposal()`。
+ *
+ * @param text 模型输出的完整或增量文本。
+ * @param options 生成中时传入 `streaming: true`，未闭合围栏按未完成提案返回。
+ * @returns 按出现顺序排列的片段；正文与提案互不重叠，围栏行不出现在正文里。
+ */
+export declare function splitSurfaceAgentText(text: string, options?: SurfaceAgentTextOptions): readonly SurfaceAgentTextSegment[];

package/dist/agent-text.js

@@ -0,0 +1,94 @@
+import { SURFACE_AGENT_LIMITS } from './agent-contract.js';
+/** 聊天回答里标记界面提案的围栏标签，例如 ```surface。 */
+export const SURFACE_AGENT_FENCE_TAG = 'surface';
+const OPEN_FENCE = /^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)[^`]*$/u;
+const CLOSE_FENCE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/u;
+function openingFence(line) {
+    const match = OPEN_FENCE.exec(line);
+    if (!match?.[1])
+        return undefined;
+    return { marker: match[1], tag: (match[2] ?? '').toLowerCase(), line };
+}
+function closesFence(line, fence) {
+    const match = CLOSE_FENCE.exec(line);
+    if (!match?.[1])
+        return false;
+    return match[1][0] === fence.marker[0] && match[1].length >= fence.marker.length;
+}
+/**
+ * 把聊天回答切成正文与界面提案，供宿主内联渲染。
+ *
+ * 只识别 `surface` 标签的围栏；其它围栏（例如 json 代码块）原样留在正文里，
+ * 避免把普通代码误当成界面提案。片段内容不做校验，宿主仍需按 catalog 和
+ * policy 调用 `parseSurfaceAgentResponse()` 或 `parseSurfaceAgentProposal()`。
+ *
+ * @param text 模型输出的完整或增量文本。
+ * @param options 生成中时传入 `streaming: true`，未闭合围栏按未完成提案返回。
+ * @returns 按出现顺序排列的片段；正文与提案互不重叠，围栏行不出现在正文里。
+ */
+export function splitSurfaceAgentText(text, options = {}) {
+    if (typeof text !== 'string' || text.length === 0)
+        return [];
+    // 超长输入按上限截断扫描，其余内容作为正文交还宿主，避免无界遍历。
+    const bounded = text.slice(0, SURFACE_AGENT_LIMITS.maxInputCharacters);
+    const overflow = text.slice(bounded.length);
+    const segments = [];
+    let prose = [];
+    let fence;
+    let proposal;
+    const flushProse = () => {
+        const value = prose.join('\n');
+        prose = [];
+        if (value === '')
+            return;
+        segments.push({ kind: 'text', text: value });
+    };
+    const flushProposal = (complete) => {
+        if (proposal === undefined || fence === undefined)
+            return;
+        flushProse();
+        segments.push({ kind: 'proposal', json: proposal.join('\n').trim(), complete });
+        proposal = undefined;
+        fence = undefined;
+    };
+    for (const line of bounded.split(/\r?\n/u)) {
+        if (proposal !== undefined && fence !== undefined) {
+            if (closesFence(line, fence))
+                flushProposal(true);
+            else
+                proposal.push(line);
+            continue;
+        }
+        if (fence !== undefined) {
+            // 其它围栏内的内容原样保留，围栏内的 surface 字样不是提案。
+            prose.push(line);
+            if (closesFence(line, fence))
+                fence = undefined;
+            continue;
+        }
+        const open = openingFence(line);
+        if (open === undefined) {
+            prose.push(line);
+            continue;
+        }
+        fence = open;
+        if (open.tag === SURFACE_AGENT_FENCE_TAG)
+            proposal = [];
+        else
+            prose.push(line);
+    }
+    if (proposal !== undefined && fence !== undefined) {
+        if (options.streaming === true)
+            flushProposal(false);
+        else {
+            // 非流式输出里未闭合的围栏是残缺内容，交还正文而不是静默丢弃。
+            prose.push(fence.line, ...proposal);
+            fence = undefined;
+            proposal = undefined;
+        }
+    }
+    flushProse();
+    if (overflow.length > 0)
+        segments.push({ kind: 'text', text: overflow });
+    return segments;
+}

package/dist/agent.d.ts

@@ -37,8 +37,14 @@ export declare function parseSurfaceAgentProposal(input: unknown, catalog: Surfa
 export declare function parseSurfaceAgentResponse(input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceAgentResponseResult;
 /** 兼容旧 v1 输出，同时补齐从组件契约派生的完整参数/结构 schema。 */
 export declare function buildSurfaceAgentPrompt(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): string;
+/** 模型回答的呈现方式：纯 JSON 信封，或聊天正文加一个内联界面提案。 */
+export type SurfaceAgentPresentation = 'json' | 'chat';
+export interface SurfaceAgentMessageOptions {
+    /** 默认 `json`，保持既有调用方的行为不变。 */
+    readonly presentation?: SurfaceAgentPresentation;
+}
 /** 系统契约与用户需求分开传递；不绑定某个模型厂商或 CSS 编译器。 */
-export declare function buildSurfaceAgentMessages(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): readonly SurfaceAgentMessage[];
+export declare function buildSurfaceAgentMessages(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy, options?: SurfaceAgentMessageOptions): readonly SurfaceAgentMessage[];
 export interface SurfaceAgentStream {
     /** 接收文本，不解析、不渲染、不查询数据。 */
     push(chunk: string): {

package/dist/agent.js

@@ -1,6 +1,7 @@
 import { Type } from 'typebox';
 import { Compile } from 'typebox/compile';
 import { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_AGENT_SCHEMA_VERSION, createSurfaceAgentResponseSchema, createSurfaceCatalogManifest, createSurfaceGenerationSpecSchema, surfaceCannotFulfillSchema, surfaceSchemaToJson, } from './agent-contract.js';
+import { SURFACE_AGENT_FENCE_TAG } from './agent-text.js';
 import { validateSurfaceSpec, surfaceSchemaIssues } from './validation.js';
 import { parseSurfaceJson, surfaceWireError } from './wire.js';
 export { SURFACE_AGENT_SCHEMA_VERSION } from './agent-contract.js';
@@ -77,9 +78,12 @@ export function buildSurfaceAgentPrompt(request, catalog, policy) {
     return boundedPrompt(`${request}\n\n[svadmin surface agent protocol]\nReturn only a human-reviewable fenced JSON proposal. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${JSON.stringify(schema)}\nIf the request cannot be represented safely, explain the limitation without inventing fields or capabilities. For machine-readable cannot-fulfill responses use the surface-agent/v2 message API.`);
 }
 /** 系统契约与用户需求分开传递；不绑定某个模型厂商或 CSS 编译器。 */
-export function buildSurfaceAgentMessages(request, catalog, policy) {
+export function buildSurfaceAgentMessages(request, catalog, policy, options = {}) {
     validateRequest(request);
-    const content = boundedPrompt(`[svadmin surface agent protocol]\nReturn exactly one JSON object matching the output schema, without markdown or prose. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${JSON.stringify(createSurfaceAgentResponseSchema(catalog, policy))}\nIf the request cannot be represented, return action "cannot-fulfill" with a reason and a short message. Never invent capabilities or return an incomplete spec.`);
+    const schema = JSON.stringify(createSurfaceAgentResponseSchema(catalog, policy));
+    const content = options.presentation === 'chat'
+        ? boundedPrompt(`[svadmin surface agent protocol]\nAnswer the user in short prose first, then embed exactly one interface proposal in a \`\`\`${SURFACE_AGENT_FENCE_TAG} fenced block matching the output schema. Emit at most one such block, do not add other fenced blocks, and do not repeat the JSON outside the fence. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${schema}\nIf the request cannot be represented, answer in prose and omit the fenced block; never invent capabilities or return an incomplete spec.`)
+        : boundedPrompt(`[svadmin surface agent protocol]\nReturn exactly one JSON object matching the output schema, without markdown or prose. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${schema}\nIf the request cannot be represented, return action "cannot-fulfill" with a reason and a short message. Never invent capabilities or return an incomplete spec.`);
     return [{ role: 'system', content }, { role: 'user', content: request }];
 }
 /** 有界传输缓冲，不冒充 OpenUI 增量渲染；半成品不进入运行时。 */

package/dist/builtin-schemas.d.ts

@@ -37,13 +37,13 @@ export type ResourceTableProps = Static<typeof resourceTablePropsSchema>;
 export type BarChartProps = Static<typeof barChartPropsSchema>;
 export type LineChartProps = Static<typeof lineChartPropsSchema>;
 export declare const styledMetricPropsSchema: Type.TUnion<[Type.TObject<{
-    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "danger" | "neutral">[]>>;
     label: Type.TString;
     format: Type.TLiteral<"currency">;
     currency: Type.TString;
     description: Type.TOptional<Type.TString>;
 }>, Type.TObject<{
-    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "danger" | "neutral">[]>>;
     label: Type.TString;
     format: Type.TUnion<[Type.TLiteral<"number">, Type.TLiteral<"percent">]>;
     currency: Type.TOptional<Type.TNever>;

package/dist/business-definitions.d.ts

@@ -7,7 +7,7 @@ export declare const resourceDetailPropsSchema: Type.TObject<{
         format: Type.TOptional<Type.TUnion<Type.TLiteral<string>[]>>;
     }>>;
     title: Type.TString;
-    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "danger" | "neutral">[]>>;
 }>;
 export declare const activityFeedPropsSchema: Type.TObject<{
     idField: Type.TString;
@@ -18,7 +18,7 @@ export declare const activityFeedPropsSchema: Type.TObject<{
     commentField: Type.TOptional<Type.TString>;
     statusField: Type.TOptional<Type.TString>;
     title: Type.TString;
-    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "danger" | "neutral">[]>>;
 }>;
 export type ResourceDetailProps = Static<typeof resourceDetailPropsSchema>;
 export type ActivityFeedProps = Static<typeof activityFeedPropsSchema>;

package/dist/components/ActivityFeedWidget.svelte

@@ -5,7 +5,7 @@
   import { asSurfaceActivities } from '../business-data.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
   import { surfaceMetric } from '../recipes.js';
-  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
 
   let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
   const baseProps = $derived(Object.fromEntries(Object.entries(props).filter(([key]) => key !== 'appearance')));
@@ -23,7 +23,7 @@
   {:else if data.status === 'empty'}
     <p role="status">{text.activityEmpty}</p>
   {:else if data.status === 'error'}
-    <p role="alert">{text.activityUnavailable}</p>
+    <p role="alert">{surfaceErrorMessage(data.error, text, text.activityUnavailable, text.activityInvalidData)}</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 })} />

package/dist/components/BarChartWidget.svelte

@@ -7,7 +7,7 @@
   import Card from '@svadmin/ui/components/ui/card/card.svelte';
   import { barChartPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
-  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
   import { asChartPoints, compactChartLabel } from '../widget-data.js';
 
   let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
@@ -32,7 +32,7 @@
     {:else if data.status === 'empty'}
       <p class="chart-state" role="status">{activeMessages.chartNoData}</p>
     {:else if data.status === 'error'}
-      <p class="chart-state" role="alert">{data.error.message}</p>
+      <p class="chart-state" role="alert">{surfaceErrorMessage(data.error, activeMessages, activeMessages.chartUnavailable, activeMessages.chartInvalidData)}</p>
     {:else if data.status === 'ready' && points?.ok}
       <div class="chart-frame" role="img" aria-label={chartProps.title}>
         <BarChart data={chartData} showValues={chartProps.showValues ?? true} />

package/dist/components/LineChartWidget.svelte

@@ -7,7 +7,7 @@
   import Card from '@svadmin/ui/components/ui/card/card.svelte';
   import { lineChartPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
-  import { formatSurfaceMessage, resolveSurfaceMessages } from '../localization.js';
+  import { formatSurfaceMessage, resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
   import { asChartPoints, compactChartLabel } from '../widget-data.js';
 
   let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
@@ -32,7 +32,7 @@
     {:else if data.status === 'empty'}
       <p class="chart-state" role="status">{activeMessages.chartNoData}</p>
     {:else if data.status === 'error'}
-      <p class="chart-state" role="alert">{data.error.message}</p>
+      <p class="chart-state" role="alert">{surfaceErrorMessage(data.error, activeMessages, activeMessages.chartUnavailable, activeMessages.chartInvalidData)}</p>
     {:else if data.status === 'ready' && points?.ok}
       <div class="chart-frame" role="img" aria-label={chartProps.title}>
         <LineChart

package/dist/components/MetricWidget.svelte

@@ -5,7 +5,7 @@
   import StatsCard from '@svadmin/ui/components/StatsCard.svelte';
   import { styledMetricPropsSchema as metricPropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
-  import { resolveSurfaceMessages } from '../localization.js';
+  import { resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
 
   let { widgetId, props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
   const activeMessages = $derived(resolveSurfaceMessages(locale, messages));
@@ -42,7 +42,7 @@
   {:else}
     <div class={"metric-state " + (metricClasses?.state ?? "")} role={data.status === 'error' ? 'alert' : 'status'}>
       <strong>{metricProps.label}</strong>
-      <span>{data.status === 'error' ? data.error.message : data.status === 'empty' ? activeMessages.metricNoData : activeMessages.metricInvalidData}</span>
+      <span>{data.status === 'error' ? surfaceErrorMessage(data.error, activeMessages, activeMessages.providerUnavailable, activeMessages.metricInvalidData) : data.status === 'empty' ? activeMessages.metricNoData : activeMessages.metricInvalidData}</span>
     </div>
   {/if}
 </article>

package/dist/components/ResourceDetailWidget.svelte

@@ -8,7 +8,7 @@
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
   import type { JsonObject } from '../types.js';
   import { surfaceMetric } from '../recipes.js';
-  import { resolveSurfaceMessages } from '../localization.js';
+  import { resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
   import { displayTableValue } from '../widget-data.js';
 
   let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
@@ -30,7 +30,7 @@
     {:else if data.status === 'empty'}
       <p role="status">{text.detailEmpty}</p>
     {:else if data.status === 'error'}
-      <p role="alert">{text.detailUnavailable}</p>
+      <p role="alert">{surfaceErrorMessage(data.error, text, text.detailUnavailable, text.detailInvalidData)}</p>
     {:else if record}
       <dl aria-label={p.title}>
         {#each p.fields as item, index (`${index}:${item.field}`)}

package/dist/components/ResourceTableWidget.svelte

@@ -14,7 +14,7 @@
   import Table from '@svadmin/ui/components/ui/table/table.svelte';
   import { styledResourceTablePropsSchema as resourceTablePropsSchema } from '../builtin-schemas.js';
   import type { SurfaceWidgetRendererProps } from '../catalog.js';
-  import { resolveSurfaceMessages } from '../localization.js';
+  import { resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
   import { asRecordArray, displayTableValue } from '../widget-data.js';
 
   let { props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
@@ -35,7 +35,7 @@
     {:else if data.status === 'empty'}
       <p class={"table-state " + (tableClasses?.state ?? "")} role="status">{tableProps.emptyLabel ?? activeMessages.tableNoRecords}</p>
     {:else if data.status === 'error'}
-      <p class={"table-state " + (tableClasses?.state ?? "")} role="alert">{data.error.message}</p>
+      <p class={"table-state " + (tableClasses?.state ?? "")} role="alert">{surfaceErrorMessage(data.error, activeMessages, activeMessages.tableUnavailable, activeMessages.tableInvalidData)}</p>
     {:else if data.status === 'ready' && records?.ok}
       <div class="surface-table">
         <Table aria-label={tableProps.title}>

package/dist/components/SurfaceRenderer.svelte

@@ -11,7 +11,7 @@
   import type { SurfaceMessages } from '../localization.js';
   import type {
     SurfaceDataError, SurfaceDataProvider, SurfacePolicy,
-    SurfaceSourceDataState, SurfaceValidationIssue, JsonObject,
+    SurfaceSourceDataState, SurfaceValidationIssue, SurfaceWidgetDataState, JsonObject,
   } from '../types.js';
   import { validateSurfaceSpec } from '../validation.js';
   import { createSurfaceSourceCache, sameSourceIdentity, snapshotSurfaceSource } from '../source-cache.js';
@@ -55,6 +55,18 @@
   const i18n = useTranslation();
   const activeLocale = $derived(locale ?? i18n.locale);
   const activeMessages = $derived(resolveSurfaceMessages(activeLocale, messages));
+  // 统一呈现边界：错误状态只暴露本地化文案，宿主诊断仍留在 onError。
+  function presentSurfaceData(data: SurfaceWidgetDataState): SurfaceWidgetDataState {
+    if (data.status !== 'error') return data;
+    const message = data.error.code === 'access_denied'
+      ? activeMessages.accessDenied
+      : data.error.code === 'provider_result_not_json' || data.error.code === 'binding_pointer_not_found'
+        ? activeMessages.invalidData
+        : activeMessages.providerUnavailable;
+    return data.error.message === message
+      ? data
+      : { ...data, error: { ...data.error, message } };
+  }
   const validation = $derived(validateSurfaceSpec(spec, catalog, policy));
   const widgetRegistrations = $derived(new Map(catalog.widgets.map((widget) => [widget.type, widget])));
   const sourceStates = new SvelteMap<string, SurfaceSourceDataState>();
@@ -69,14 +81,16 @@
   ]);
   // 复用 PR #428 的请求所有权与会话隔离实现，不维护第二套缓存。
   const sourceCache = createSurfaceSourceCache({
+    // 缓存只保存原始 source 状态；本地化等呈现规则统一在渲染边界执行。
     set: (id, state) => { sourceStates.set(id, state); },
     remove: (id) => { sourceStates.delete(id); },
-    onError: (state) => { onError?.({ type: 'data', error: state.error }); },
+    onError: (state, diagnostic) => { onError?.({ type: 'data', error: diagnostic ?? 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 } };
+  function providerError(sourceId: string): SurfaceSourceDataState {
+    return { status: 'error', sourceId, error: {
+      code: 'provider_failed', sourceId, message: activeMessages.providerUnavailable,
+    } };
   }
 
   const sourceRequests: SurfaceSourceRequest[] = $derived.by(() => {
@@ -97,11 +111,18 @@
         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);
+        async load(isRequestCurrent, reportDiagnostic) {
+          if (!provider) {
+            reportDiagnostic?.({
+              code: 'provider_failed', sourceId: snapshot.source.id,
+              message: providerFailure instanceof Error ? providerFailure.message : 'Data provider request failed',
+            });
+            return providerError(snapshot.source.id);
+          }
           try {
             return await loadSurfaceSource({
               source: snapshot.source, resourcePolicy: snapshot.resourcePolicy, provider,
+              ...(reportDiagnostic === undefined ? {} : { reportDiagnostic }),
               async authorize(resource, action) {
                 if (!isRequestCurrent()) return { can: false };
                 // 授权检查与缓存身份必须使用同一个所属上下文，不能回退到无关全局授权。
@@ -112,7 +133,13 @@
                 return isRequestCurrent() ? decision : { can: false };
               },
             });
-          } catch (failure) { return providerError(snapshot.source.id, failure); }
+          } catch (failure) {
+            reportDiagnostic?.({
+              code: 'provider_failed', sourceId: snapshot.source.id,
+              message: failure instanceof Error ? failure.message : 'Data provider request failed',
+            });
+            return providerError(snapshot.source.id);
+          }
         },
       };
     });
@@ -155,7 +182,7 @@
           <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)}
+                data={presentSurfaceData(resolveSurfaceSourceData(widget, widget.binding ? sourceStates.get(widget.binding.sourceId) : undefined))}
                 locale={activeLocale} messages={activeMessages} />
             {/if}
           </div>

package/dist/components/SvarGridWidget.svelte

@@ -5,7 +5,7 @@
   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';
+  import { resolveSurfaceMessages, surfaceErrorMessage } from '../localization.js';
 
   let { widgetId, props, data, locale = 'en-US', messages }: SurfaceWidgetRendererProps = $props();
   const host = getContext<SvarSurfaceContext | undefined>(SVAR_SURFACE_CONTEXT);
@@ -24,9 +24,9 @@
 <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>
+    <p role="alert">{labels.tableEngineUnavailable}</p>
   {:else if data.status === 'error'}
-    <p role="alert">{data.error.message}</p>
+    <p role="alert">{surfaceErrorMessage(data.error, labels, labels.tableUnavailable, labels.tableInvalidData)}</p>
   {:else if data.status === 'unbound' || (records && !records.ok)}
     <p role="alert">{labels.tableInvalidData}</p>
   {:else}

package/dist/index.d.ts

@@ -3,6 +3,9 @@ export type { JsonObject, JsonPrimitive, JsonValue, ResourceListDataSource, Reso
 export { validateSurfaceSpec } from './validation.js';
 export type { SurfaceMessages } from './localization.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
+export { SURFACE_AGENT_FENCE_TAG, splitSurfaceAgentText, } from './agent-text.js';
+export type { SurfaceAgentTextSegment, SurfaceAgentTextOptions, } from './agent-text.js';
+export type { SurfaceAgentMessageOptions, SurfaceAgentPresentation, } from './agent.js';
 export type { SurfaceAgentProposal, SurfaceAgentProposalV2, SurfaceAgentCannotFulfill, SurfaceAgentResponse, SurfaceAgentResponseResult, SurfaceAgentMessage, SurfaceAgentStream, SurfaceAgentValidationResult, } from './agent.js';
 export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';
 export type { SurfaceCatalogManifest } from './agent-contract.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
+export { SURFACE_AGENT_FENCE_TAG, splitSurfaceAgentText, } from './agent-text.js';
 export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';
 export { SURFACE_EDIT_SCHEMA_VERSION, SURFACE_EDIT_LIMITS, createSurfaceRevision, applySurfaceEditProposal, createSurfaceEditSchema, buildSurfaceEditMessages, } from './edits.js';
 // 只导出 JSON schema，不将可选 SVAR 渲染器加载到协议入口。

package/dist/json-render.js

@@ -71,7 +71,7 @@ export function jsonRenderSpecToSurfaceSpec(input, catalog, policy) {
         if (!element)
             return { ok: false, issues: [issue(jsonPointer(['elements', childId]), 'Missing child element')] };
         const widget = readWidgetElement(element, childId);
-        if ('error' in widget)
+        if (typeof widget.error === 'string')
             return { ok: false, issues: [issue(jsonPointer(['elements', childId]), widget.error)] };
         widgets.push(widget);
     }

package/dist/localization.d.ts

@@ -1,6 +1,9 @@
+import type { SurfaceDataError } from './types.js';
 export interface SurfaceMessages {
     readonly renderErrorTitle: string;
     readonly providerUnavailable: string;
+    readonly accessDenied?: string;
+    readonly invalidData?: string;
     readonly metricNoData: string;
     readonly metricInvalidData: string;
     readonly chartLoading: string;
@@ -11,6 +14,7 @@ export interface SurfaceMessages {
     readonly tableNoRecords: string;
     readonly tableInvalidData: string;
     readonly tableUnavailable: string;
+    readonly tableEngineUnavailable: string;
     readonly detailLoading?: string;
     readonly detailEmpty?: string;
     readonly detailUnavailable?: string;
@@ -26,3 +30,4 @@ export interface 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;
+export declare function surfaceErrorMessage(error: Pick<SurfaceDataError, 'code'>, messages: Required<SurfaceMessages>, unavailable: string, invalid: string): string;

package/dist/localization.js

@@ -1,6 +1,8 @@
 const englishMessages = {
     renderErrorTitle: 'Surface could not be rendered',
     providerUnavailable: 'Data provider is unavailable',
+    accessDenied: 'Access denied',
+    invalidData: 'Surface data is invalid',
     metricNoData: 'No data',
     metricInvalidData: 'Metric data is invalid',
     chartLoading: 'Loading {title}',
@@ -11,6 +13,7 @@ const englishMessages = {
     tableNoRecords: 'No records',
     tableInvalidData: 'Table data is invalid',
     tableUnavailable: 'Table data is unavailable',
+    tableEngineUnavailable: 'The host has not configured the SVAR engine',
     detailLoading: 'Loading record',
     detailEmpty: 'No record',
     detailUnavailable: 'Record is unavailable',
@@ -27,6 +30,8 @@ const englishMessages = {
 const simplifiedChineseMessages = {
     renderErrorTitle: '无法渲染 Surface',
     providerUnavailable: '数据提供器不可用',
+    accessDenied: '无权访问',
+    invalidData: 'Surface 数据无效',
     metricNoData: '暂无数据',
     metricInvalidData: '指标数据无效',
     chartLoading: '正在加载{title}',
@@ -37,6 +42,7 @@ const simplifiedChineseMessages = {
     tableNoRecords: '暂无记录',
     tableInvalidData: '表格数据无效',
     tableUnavailable: '表格数据不可用',
+    tableEngineUnavailable: '宿主尚未配置 SVAR 引擎',
     detailLoading: '正在加载记录',
     detailEmpty: '暂无记录',
     detailUnavailable: '记录不可用',
@@ -63,3 +69,10 @@ export function formatSurfaceMessage(template, params) {
     }
     return formattedMessage;
 }
+export function surfaceErrorMessage(error, messages, unavailable, invalid) {
+    if (error.code === 'access_denied')
+        return messages.accessDenied;
+    if (error.code === 'provider_result_not_json' || error.code === 'binding_pointer_not_found')
+        return invalid;
+    return unavailable;
+}

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { SurfaceDataProvider, SurfaceDataSource, SurfaceResourcePolicy, SurfaceWidgetDataState } from './types.js';
+import type { SurfaceDataError, SurfaceDataProvider, SurfaceDataSource, SurfaceResourcePolicy, SurfaceWidgetDataState } from './types.js';
 export type SurfaceReadAction = 'list' | 'show';
 export interface SurfaceAccessDecision {
     readonly can: boolean;
@@ -10,6 +10,8 @@ export interface LoadSurfaceSourceRequest {
     readonly resourcePolicy: SurfaceResourcePolicy;
     readonly provider: SurfaceDataProvider;
     readonly authorize: SurfaceAuthorizer;
+    /** Internal host hook for diagnostics; never used as user-visible state. */
+    readonly reportDiagnostic?: (diagnostic: SurfaceDataError) => void;
 }
 export type SurfaceLoadedSourceState = Extract<SurfaceWidgetDataState, {
     status: 'ready' | 'error';

package/dist/runtime.js

@@ -46,6 +46,10 @@ function projectRecords(records, readableFields) {
 function sourceError(sourceId, code, message) {
     return { status: 'error', sourceId, error: { code, sourceId, message } };
 }
+function reportedError(request, code, message, diagnosticMessage) {
+    request.reportDiagnostic?.({ code, sourceId: request.source.id, message: diagnosticMessage });
+    return sourceError(request.source.id, code, message);
+}
 function listParams(source) {
     const sorters = source.sorters?.map((sorter) => ({ ...sorter })) ?? [];
     const filters = source.filters?.map((filter) => {
@@ -112,10 +116,11 @@ export async function loadSurfaceSource(request) {
     }
     catch (accessFailure) {
         const message = accessFailure instanceof Error ? accessFailure.message : 'Access check failed';
-        return sourceError(source.id, 'access_check_failed', message);
+        return reportedError(request, 'access_check_failed', 'Access check failed', message);
+    }
+    if (!accessDecision.can) {
+        return reportedError(request, 'access_denied', 'Access denied', accessDecision.reason ?? 'Access denied');
     }
-    if (!accessDecision.can)
-        return sourceError(source.id, 'access_denied', accessDecision.reason ?? 'Access denied');
     try {
         return source.type === 'resource-list'
             ? await loadListSource(source, resourcePolicy, provider)
@@ -123,6 +128,6 @@ export async function loadSurfaceSource(request) {
     }
     catch (providerFailure) {
         const message = providerFailure instanceof Error ? providerFailure.message : 'Data provider request failed';
-        return sourceError(source.id, 'provider_failed', message);
+        return reportedError(request, 'provider_failed', 'Data provider request failed', message);
     }
 }

package/dist/source-cache.d.ts

@@ -1,4 +1,7 @@
-import type { SurfaceDataSource, SurfaceResourcePolicy, SurfaceSourceDataState } from './types.js';
+import type { SurfaceDataSource, SurfaceDataError, SurfaceResourcePolicy, SurfaceSourceDataState } from './types.js';
+type SurfaceDataDiagnostic = Extract<SurfaceSourceDataState, {
+    status: 'error';
+}>['error'];
 /** Only query/projection inputs belong in this key, never widget or layout data. */
 export declare function snapshotSurfaceSource(source: SurfaceDataSource, policy: SurfaceResourcePolicy): {
     source: SurfaceDataSource;
@@ -9,7 +12,7 @@ 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>;
+    readonly load: (isCurrent: () => boolean, reportDiagnostic?: (diagnostic: SurfaceDataDiagnostic) => void) => Promise<SurfaceSourceDataState>;
     /** Also guards prop changes that happen before Svelte's next effect flush. */
     readonly isCurrent: () => boolean;
 }
@@ -19,7 +22,7 @@ interface SourceCacheSink {
     readonly remove: (sourceId: string) => void;
     readonly onError: (state: Extract<SurfaceSourceDataState, {
         status: 'error';
-    }>) => void;
+    }>, diagnostic?: SurfaceDataError) => void;
 }
 /** Per-renderer reconciliation, not a cross-user or cross-component data cache. */
 export declare function createSurfaceSourceCache(sink: SourceCacheSink): {

package/dist/source-cache.js

@@ -1,3 +1,17 @@
+function stableSourceState(state) {
+    if (state.status !== 'error')
+        return state;
+    const message = state.error.code === 'access_denied'
+        ? 'Access denied'
+        : state.error.code === 'access_check_failed'
+            ? 'Access check failed'
+            : state.error.code === 'provider_failed'
+                ? 'Data provider request failed'
+                : state.error.message;
+    return message === state.error.message
+        ? state
+        : { ...state, error: { ...state.error, message } };
+}
 /** Only query/projection inputs belong in this key, never widget or layout data. */
 export function snapshotSurfaceSource(source, policy) {
     const snapshot = source.type === 'resource-one'
@@ -79,15 +93,23 @@ export function createSurfaceSourceCache(sink) {
                 return;
             }
             let state;
+            let diagnostic;
+            const reportDiagnostic = (next) => {
+                diagnostic ??= next;
+            };
             try {
-                state = await request.load(current);
+                state = await request.load(current, reportDiagnostic);
             }
             catch (failure) {
+                const message = failure instanceof Error ? failure.message : 'Data provider request failed';
+                diagnostic = {
+                    code: 'provider_failed', sourceId: request.id, message,
+                };
                 state = {
                     status: 'error', sourceId: request.id,
                     error: {
                         code: 'provider_failed', sourceId: request.id,
-                        message: failure instanceof Error ? failure.message : 'Data provider request failed',
+                        message: 'Data provider request failed',
                     },
                 };
             }
@@ -95,9 +117,10 @@ export function createSurfaceSourceCache(sink) {
                 retire();
                 return;
             }
+            state = stableSourceState(state);
             sink.set(request.id, state);
             if (state.status === 'error')
-                sink.onError(state);
+                sink.onError(state, diagnostic);
         })();
         return entry.pending;
     }

package/dist/workflows/catalog.d.ts

@@ -2,7 +2,7 @@ import { Type } from 'typebox';
 import type { SurfaceCatalog, SurfaceWidgetDefinition, JsonObject } from '../types.js';
 import type { SurfaceActionDescriptor } from './types.js';
 export declare const surfaceAppearanceSchema: Type.TObject<{
-    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "neutral" | "danger">[]>>;
+    tone: Type.TOptional<Type.TUnion<Type.TLiteral<"info" | "warning" | "success" | "danger" | "neutral">[]>>;
 }>;
 export declare function withoutSurfaceAppearance(props: JsonObject): JsonObject;
 /** Adds frame-level semantic appearance to every registered widget without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/surface",
-  "version": "0.14.3",
+  "version": "0.17.0",
   "description": "Validated declarative surfaces for svadmin dashboards",
   "type": "module",
   "sideEffects": [
@@ -74,8 +74,8 @@
     }
   },
   "peerDependencies": {
-    "@svadmin/core": ">=0.53.0 <0.63.0",
-    "@svadmin/ui": ">=0.73.0 <0.89.0",
+    "@svadmin/core": ">=0.53.0 <0.67.0",
+    "@svadmin/ui": ">=0.73.0 <0.93.0",
     "svelte": "^5.56.10"
   },
   "dependencies": {
@@ -86,7 +86,7 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/svelte": "^5.4.2",
     "@testing-library/user-event": "^14.6.6",
-    "happy-dom": "^20.11.12",
+    "happy-dom": "^21.0.4",
     "postcss": "^8.5.26",
     "vitest": "^4.1.11"
   },