@skopon-cool/form-sdk 0.3.1 → 0.4.0

package/dist/runtime/buildFormRuntimeSnapshot.d.ts

@@ -0,0 +1,16 @@
+import type { FormBlock, FormBlockOption } from '../types/index';
+import type { FormRuntimeDataPayload } from './types';
+export type LiveOptionsMap = ReadonlyMap<string, FormBlockOption[]>;
+export interface BuildFormRuntimeSnapshotInput {
+    title?: string;
+    description?: string;
+    blocks: FormBlock[];
+    values: Record<string, unknown>;
+    liveOptions?: LiveOptionsMap;
+    formChange?: string[];
+}
+/**
+ * 构建 form_runtime_data 快照：form_schema（block 格式）+ 扁平 form_values + form_change。
+ */
+export declare function buildFormRuntimeSnapshot(input: BuildFormRuntimeSnapshotInput): FormRuntimeDataPayload;
+//# sourceMappingURL=buildFormRuntimeSnapshot.d.ts.map

package/dist/runtime/buildFormRuntimeSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildFormRuntimeSnapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/buildFormRuntimeSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAErD,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;AA0BnE,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,SAAS,EAAE,CAAA;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,sBAAsB,CAiBxB"}

package/dist/runtime/formLiveOptionsContext.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+import type { FormBlockOption } from '../types/index';
+export type PublishLiveOptionsFn = (fieldName: string, options: FormBlockOption[]) => void;
+export interface FormLiveOptionsContextValue {
+    publishLiveOptions: PublishLiveOptionsFn;
+    /** 当前 live options 的不可变快照（供读取）。 */
+    liveOptions: ReadonlyMap<string, FormBlockOption[]>;
+    /** 最近一次签名变化导致的变更字段（debounce 归集前由 Provider 消费后清空）。 */
+    pendingChangeFields: readonly string[];
+    /** 版本号：live options 有实质变更时递增，用于触发上报 effect。 */
+    version: number;
+    clearPendingChangeFields: () => void;
+}
+export interface FormLiveOptionsProviderProps {
+    children: ReactNode;
+}
+export declare function FormLiveOptionsProvider({ children }: FormLiveOptionsProviderProps): import("react").JSX.Element;
+/** 无 Provider 时 no-op（编辑器预览不受影响）。 */
+export declare function useFormLiveOptions(): FormLiveOptionsContextValue;
+//# sourceMappingURL=formLiveOptionsContext.d.ts.map

package/dist/runtime/formLiveOptionsContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formLiveOptionsContext.d.ts","sourceRoot":"","sources":["../../src/runtime/formLiveOptionsContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,MAAM,MAAM,oBAAoB,GAAG,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,eAAe,EAAE,KACvB,IAAI,CAAA;AAET,MAAM,WAAW,2BAA2B;IAC1C,kBAAkB,EAAE,oBAAoB,CAAA;IACxC,mCAAmC;IACnC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;IACnD,qDAAqD;IACrD,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;IACf,wBAAwB,EAAE,MAAM,IAAI,CAAA;CACrC;AAsBD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,EAAE,4BAA4B,+BA6DjF;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,IAAI,2BAA2B,CAEhE"}

package/dist/runtime/formRuntimeConnection.d.ts

@@ -0,0 +1,35 @@
+import type { FormAutoControlEventData, FormRuntimeEnvelope, FormRuntimeOutboundType } from './types';
+export type FormAutoControlHandler = (data: FormAutoControlEventData, envelope: FormRuntimeEnvelope<FormAutoControlEventData>) => void;
+/** 测试用：清空所有单例连接。 */
+export declare function resetFormRuntimeConnectionsForTests(): void;
+export declare function acquireFormRuntimeConnection(url: string): FormRuntimeConnection;
+export declare class FormRuntimeConnection {
+    private readonly url;
+    private ws;
+    private refCount;
+    private connectRequested;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private releaseTimer;
+    private sendQueue;
+    private readonly handlers;
+    constructor(url: string);
+    acquire(): void;
+    release(): void;
+    /** 强制关闭（测试用），跳过宽限期。 */
+    forceClose(): void;
+    subscribe(askUserMessageId: string, handler: FormAutoControlHandler): () => void;
+    /** 懒建连：首个会话 connect() 时才真正打开 socket。 */
+    connect(): void;
+    send(askUserMessageId: string, type: FormRuntimeOutboundType, data: Record<string, unknown>): void;
+    private openSocket;
+    private teardown;
+    private disposeSocket;
+    private enqueue;
+    private flushQueue;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private clearReleaseTimer;
+    private handleMessage;
+}
+//# sourceMappingURL=formRuntimeConnection.d.ts.map

package/dist/runtime/formRuntimeConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formRuntimeConnection.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,SAAS,CAAA;AAMhB,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,mBAAmB,CAAC,wBAAwB,CAAC,KACpD,IAAI,CAAA;AAIT,oBAAoB;AACpB,wBAAgB,mCAAmC,IAAI,IAAI,CAK1D;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAS/E;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;gBAE9D,GAAG,EAAE,MAAM;IAIvB,OAAO,IAAI,IAAI;IAKf,OAAO,IAAI,IAAI;IAcf,uBAAuB;IACvB,UAAU,IAAI,IAAI;IAQlB,SAAS,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAiBhF,wCAAwC;IACxC,OAAO,IAAI,IAAI;IASf,IAAI,CACF,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAqBP,OAAO,CAAC,UAAU;IA2BlB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,aAAa;CAyBtB"}

package/dist/runtime/formRuntimeContext.d.ts

@@ -1,9 +1,9 @@
 import { type ReactNode } from 'react';
 import type { FormRuntimeWsClient } from './formRuntimeWs';
-import type { FormRuntimeEventData } from './types';
+import type { FormRuntimeDataPayload, FormRuntimeEventData } from './types';
 export interface FormRuntimeContextValue {
     reportEvent: (event: FormRuntimeEventData) => void;
-    reportData: (values: Record<string, unknown>) => void;
+    reportData: (payload: FormRuntimeDataPayload) => void;
     /**
      * 在自动控上下文中执行 fn。若 fn 返回 Promise，depth 保持到 settle，
      * 使异步 submit 内的 reportEvent 仍为 form_auto_control_bac_event。

package/dist/runtime/formRuntimeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formRuntimeContext.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEnD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACrD;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,aAAa,EAAE,MAAM,OAAO,CAAA;CAC7B;AA6BD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAClC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,+BAkE1B;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,uBAAuB,CAExD"}
+{"version":3,"file":"formRuntimeContext.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE3E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,UAAU,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAA;IACrD;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,aAAa,EAAE,MAAM,OAAO,CAAA;CAC7B;AA+BD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAClC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,+BAkE1B;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,uBAAuB,CAExD"}

package/dist/runtime/formRuntimeWs.d.ts

@@ -1,27 +1,22 @@
-import type { FormAutoControlEventData, FormRuntimeEnvelope, FormRuntimeOutboundType } from './types';
-export type FormAutoControlHandler = (data: FormAutoControlEventData, envelope: FormRuntimeEnvelope<FormAutoControlEventData>) => void;
+import { type FormAutoControlHandler } from './formRuntimeConnection';
+import type { FormRuntimeOutboundType } from './types';
+export type { FormAutoControlHandler } from './formRuntimeConnection';
 export interface FormRuntimeWsClientOptions {
     url: string;
     askUserMessageId: string;
     onAutoControl?: FormAutoControlHandler;
 }
+/**
+ * Per-card runtime 会话：绑定 ask_user_message_id，代理到按 URL 的全局单例连接。
+ */
 export declare class FormRuntimeWsClient {
-    private readonly url;
     private readonly askUserMessageId;
-    private readonly onAutoControl?;
-    private ws;
+    private readonly connection;
+    private readonly unsubscribe;
     private closed;
-    private reconnectAttempt;
-    private reconnectTimer;
-    private sendQueue;
     constructor(options: FormRuntimeWsClientOptions);
     connect(): void;
     send(type: FormRuntimeOutboundType, data: Record<string, unknown>): void;
     close(): void;
-    private enqueue;
-    private flushQueue;
-    private scheduleReconnect;
-    private clearReconnectTimer;
-    private handleMessage;
 }
 //# sourceMappingURL=formRuntimeWs.d.ts.map

package/dist/runtime/formRuntimeWs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formRuntimeWs.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeWs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,SAAS,CAAA;AAKhB,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,mBAAmB,CAAC,wBAAwB,CAAC,KACpD,IAAI,CAAA;AAET,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,sBAAsB,CAAA;CACvC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAwB;IACvD,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,SAAS,CAAe;gBAEpB,OAAO,EAAE,0BAA0B;IAM/C,OAAO,IAAI,IAAI;IA0Bf,IAAI,CACF,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAqBP,KAAK,IAAI,IAAI;IAkBb,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;CAgBtB"}
+{"version":3,"file":"formRuntimeWs.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeWs.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAE5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAErE,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,sBAAsB,CAAA;CACvC;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IACxC,OAAO,CAAC,MAAM,CAAQ;gBAEV,OAAO,EAAE,0BAA0B;IAS/C,OAAO,IAAI,IAAI;IAKf,IAAI,CACF,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAKP,KAAK,IAAI,IAAI;CAMd"}

package/dist/runtime/types.d.ts

@@ -17,4 +17,15 @@ export interface FormRuntimeEnvelope<T = Record<string, unknown>> {
     ask_user_message_id: string;
     data: T;
 }
+/** form_runtime_data 的 data 载荷（Init / Refresh / Submit）。 */
+export interface FormRuntimeDataPayload {
+    form_schema: {
+        title?: string;
+        description?: string;
+        blocks: unknown[];
+    };
+    form_values: Record<string, unknown>;
+    /** 本次被更新的字段名；Init/Submit 为空数组。 */
+    form_change: string[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAElF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,iBAAiB,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,uBAAuB,GAC/B,mBAAmB,GACnB,oBAAoB,GACpB,6BAA6B,CAAA;AAEjC,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,MAAM,CAAA;IAC3B,IAAI,EAAE,CAAC,CAAA;CACR"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAElF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,iBAAiB,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,uBAAuB,GAC/B,mBAAmB,GACnB,oBAAoB,GACpB,6BAA6B,CAAA;AAEjC,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,MAAM,CAAA;IAC3B,IAAI,EAAE,CAAC,CAAA;CACR;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,MAAM,EAAE,OAAO,EAAE,CAAA;KAClB,CAAA;IACD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB"}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Skopon form rendering SDK (A2UI + form_definition) with submit helpers",
   "type": "module",
   "sideEffects": [

package/src/catalog/skoponCaseSelect.tsx

@@ -5,6 +5,7 @@ import type { ComponentContext } from '@a2ui/web_core/v0_9'
 import { createBinderlessComponentImplementation } from '@a2ui/react/v0_9'
 import { z } from 'zod'
 import type { FormCaseFilter } from '../types/index'
+import { useFormLiveOptions } from '../runtime/formLiveOptionsContext'
 import { useA2uiPreviewMode } from './a2uiPreviewContext'
 import { asStringArray, clampStringArraySelection, isCardSelectionDisabled, readOptionalSelectCount, toggleStringArraySelection, useSkoponBoundField } from './useSkoponBoundField'
 import { type CaseSearchItem, useCaseSearch } from './caseSearchContext'
@@ -110,6 +111,7 @@ function CaseCard({
 function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const caseSearch = useCaseSearch()
+  const { publishLiveOptions } = useFormLiveOptions()
   const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
     component: 'SkoponCaseSelect',
     changeAction: 'click',
@@ -167,6 +169,15 @@ function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
         setTotal(result.total)
         setPage(result.page)
         setPageSize(result.pageSize)
+        if (fieldName) {
+          publishLiveOptions(
+            fieldName,
+            result.list.map((item) => ({
+              value: item.caseUniqueId,
+              label: item.name || item.caseUniqueId,
+            })),
+          )
+        }
       } catch (err) {
         if (seq !== requestSeqRef.current) return
         setItems([])
@@ -176,7 +187,7 @@ function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
         if (seq === requestSeqRef.current) setLoading(false)
       }
     },
-    [caseSearch, filterSig],
+    [caseSearch, filterSig, fieldName, publishLiveOptions],
   )
 
   useEffect(() => {

package/src/catalog/skoponResumeSelect.tsx

@@ -5,6 +5,7 @@ import type { ComponentContext } from '@a2ui/web_core/v0_9'
 import { createBinderlessComponentImplementation } from '@a2ui/react/v0_9'
 import { z } from 'zod'
 import type { FormResumeFilter } from '../types/index'
+import { useFormLiveOptions } from '../runtime/formLiveOptionsContext'
 import { useA2uiPreviewMode } from './a2uiPreviewContext'
 import { asStringArray, clampStringArraySelection, isCardSelectionDisabled, readOptionalSelectCount, toggleStringArraySelection, useSkoponBoundField } from './useSkoponBoundField'
 import {
@@ -163,6 +164,7 @@ function ResumeCard({
 function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const resumeSearch = useResumeSearch()
+  const { publishLiveOptions } = useFormLiveOptions()
   const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
     component: 'SkoponResumeSelect',
     changeAction: 'click',
@@ -213,6 +215,15 @@ function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
         setTotal(result.total)
         setPage(result.page)
         setPageSize(result.pageSize)
+        if (fieldName) {
+          publishLiveOptions(
+            fieldName,
+            result.list.map((item) => ({
+              value: item.resumeUniqueId,
+              label: item.name || item.resumeUniqueId,
+            })),
+          )
+        }
       } catch (err) {
         if (seq !== requestSeqRef.current) return
         setItems([])
@@ -222,7 +233,7 @@ function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
         if (seq === requestSeqRef.current) setLoading(false)
       }
     },
-    [resumeSearch, filterSig],
+    [resumeSearch, filterSig, fieldName, publishLiveOptions],
   )
 
   useEffect(() => {

package/src/catalog/useSkoponBoundField.ts

@@ -59,8 +59,16 @@ export function useSkoponBoundField(
   } = options
 
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const pendingDebouncedValueRef = useRef<unknown>(undefined)
+  const hasPendingDebouncedRef = useRef(false)
   const runtimeRef = useRef(runtime)
   runtimeRef.current = runtime
+  const changeActionRef = useRef(changeAction)
+  changeActionRef.current = changeAction
+  const componentRef = useRef(component)
+  componentRef.current = component
+  const fieldNameRef = useRef(fieldName)
+  fieldNameRef.current = fieldName
 
   useEffect(() => {
     return () => {
@@ -68,6 +76,16 @@ export function useSkoponBoundField(
         clearTimeout(debounceTimerRef.current)
         debounceTimerRef.current = null
       }
+      // unmount 时 flush 未发出的最后一次 change，避免丢事件
+      if (hasPendingDebouncedRef.current && fieldNameRef.current) {
+        hasPendingDebouncedRef.current = false
+        runtimeRef.current.reportEvent({
+          action: changeActionRef.current,
+          component: componentRef.current,
+          field: fieldNameRef.current,
+          value: pendingDebouncedValueRef.current,
+        })
+      }
     }
   }, [])
 
@@ -91,6 +109,7 @@ export function useSkoponBoundField(
     (next: unknown) => {
       if (!fieldName) return
       const emit = () => {
+        hasPendingDebouncedRef.current = false
         runtimeRef.current.reportEvent({
           action: changeAction,
           component,
@@ -102,6 +121,8 @@ export function useSkoponBoundField(
         emit()
         return
       }
+      pendingDebouncedValueRef.current = next
+      hasPendingDebouncedRef.current = true
       if (debounceTimerRef.current != null) {
         clearTimeout(debounceTimerRef.current)
       }

package/src/components/AskUserFormCard.tsx

@@ -8,6 +8,7 @@ import {
 import { buildAskUserSurface } from '../adapter/resolveSurface'
 import {
   buildAnswerAgentBody,
+  validateAnswerAgentBody,
   type AskUserAnswerAgentContext,
 } from '../submit/buildAnswerAgentBody'
 import {
@@ -30,10 +31,17 @@ import { FormRuntimeProvider, useFormRuntime } from '../runtime/formRuntimeConte
 import { FormRuntimeWsClient } from '../runtime/formRuntimeWs'
 import { executeFormAutoControl } from '../runtime/formAutoControl'
 import type { FormAutoControlEventData } from '../runtime/types'
+import { buildFormRuntimeSnapshot } from '../runtime/buildFormRuntimeSnapshot'
+import {
+  FormLiveOptionsProvider,
+  useFormLiveOptions,
+} from '../runtime/formLiveOptionsContext'
 import SkoponFormRenderer, { type SkoponFormRendererRef } from './SkoponFormRenderer'
 import CurlSubmitBlock from './CurlSubmitBlock'
 import SkoponFormProvider from './SkoponFormProvider'
 
+const REFRESH_REPORT_DEBOUNCE_MS = 80
+
 function formatSubmitErrorMessage(status: number, body: unknown): string {
   if (body && typeof body === 'object' && body !== null && 'message' in body) {
     const msg = (body as { message: unknown }).message
@@ -100,6 +108,9 @@ function AskUserFormCardBody({
   const onNotifyRef = useRef(onNotify)
   onNotifyRef.current = onNotify
   const runtime = useFormRuntime()
+  const liveOptionsCtx = useFormLiveOptions()
+  const lastInitKeyRef = useRef('')
+  const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const resolvedFormUniqueId = formUniqueId?.trim() ?? ''
   const resolvedAskUserMessageId = askUserMessageId?.trim() ?? ''
@@ -121,6 +132,10 @@ function AskUserFormCardBody({
     mountedRef.current = true
     return () => {
       mountedRef.current = false
+      if (refreshTimerRef.current != null) {
+        clearTimeout(refreshTimerRef.current)
+        refreshTimerRef.current = null
+      }
     }
   }, [])
 
@@ -192,12 +207,25 @@ function AskUserFormCardBody({
       .map((block) => block.name!.trim())
   }, [usePayloadFallback, payloadDef, renderBlocks])
 
+  const surfaceTitle = intersection?.title ?? payloadDef?.title ?? ''
+  const surfaceDescription = intersection?.description ?? payloadDef?.description ?? ''
+
   const surfaceDoc = useMemo(() => {
     if (renderBlocks.length === 0) return null
-    const title = intersection?.title ?? payloadDef?.title ?? ''
-    const description = intersection?.description ?? payloadDef?.description ?? ''
-    return buildAskUserSurface({ title, description }, renderBlocks)
-  }, [intersection, payloadDef, renderBlocks])
+    return buildAskUserSurface(
+      { title: surfaceTitle, description: surfaceDescription },
+      renderBlocks,
+    )
+  }, [surfaceTitle, surfaceDescription, renderBlocks])
+
+  const docKey = useMemo(() => {
+    if (!surfaceDoc) return ''
+    try {
+      return JSON.stringify(surfaceDoc)
+    } catch {
+      return String(surfaceDoc)
+    }
+  }, [surfaceDoc])
 
   const surfaceId = resolvedFormUniqueId
     ? `ask-user-${resolvedFormUniqueId}`
@@ -210,6 +238,76 @@ function AskUserFormCardBody({
     return () => onSurfaceReadyChange(false)
   }, [hasFormSurface, onSurfaceReadyChange])
 
+  const collectAnswer = useCallback(() => {
+    const cardValues = rendererRef.current?.getValues(fieldNames) ?? {}
+    return { ...cardValues, ...extraValues }
+  }, [fieldNames, extraValues])
+
+  const reportSnapshot = useCallback(
+    (formChange: string[]) => {
+      const snapshot = buildFormRuntimeSnapshot({
+        title: surfaceTitle,
+        description: surfaceDescription,
+        blocks: renderBlocks,
+        values: collectAnswer(),
+        liveOptions: liveOptionsCtx.liveOptions,
+        formChange,
+      })
+      runtime.reportData(snapshot)
+    },
+    [
+      surfaceTitle,
+      surfaceDescription,
+      renderBlocks,
+      collectAnswer,
+      liveOptionsCtx.liveOptions,
+      runtime,
+    ],
+  )
+
+  // Init：surface 就绪或 doc 内容变化时上报（form_change: []）
+  useEffect(() => {
+    if (!hasFormSurface || !docKey) return
+    const initKey = `${surfaceId}::${docKey}`
+    if (lastInitKeyRef.current === initKey) return
+    lastInitKeyRef.current = initKey
+    // 等下一帧，确保 SkoponFormRenderer dataModel 已就绪
+    const timer = setTimeout(() => {
+      if (!mountedRef.current) return
+      reportSnapshot([])
+    }, 0)
+    return () => clearTimeout(timer)
+  }, [hasFormSurface, surfaceId, docKey, reportSnapshot])
+
+  // Refresh：live options 变更后 debounce 上报（form_change 为变更字段）
+  useEffect(() => {
+    if (!hasFormSurface || liveOptionsCtx.version === 0) return
+    if (liveOptionsCtx.pendingChangeFields.length === 0) return
+    if (refreshTimerRef.current != null) {
+      clearTimeout(refreshTimerRef.current)
+    }
+    refreshTimerRef.current = setTimeout(() => {
+      refreshTimerRef.current = null
+      if (!mountedRef.current) return
+      const changed = [...liveOptionsCtx.pendingChangeFields]
+      liveOptionsCtx.clearPendingChangeFields()
+      if (changed.length === 0) return
+      reportSnapshot(changed)
+    }, REFRESH_REPORT_DEBOUNCE_MS)
+    return () => {
+      if (refreshTimerRef.current != null) {
+        clearTimeout(refreshTimerRef.current)
+        refreshTimerRef.current = null
+      }
+    }
+  }, [
+    hasFormSurface,
+    liveOptionsCtx.version,
+    liveOptionsCtx.pendingChangeFields,
+    liveOptionsCtx.clearPendingChangeFields,
+    reportSnapshot,
+  ])
+
   const handleSubmit = useCallback(async () => {
     if (submitting) return
     setSubmitting(true)
@@ -222,18 +320,17 @@ function AskUserFormCardBody({
       }
       const answer = { ...cardValues, ...extraValues }
 
-      runtime.reportData(answer)
-      runtime.reportEvent({
-        action: 'submit',
-        component: 'SubmitButton',
-      })
-
       if (submitMode === 'post') {
         const url = (callbackUrl ?? '').trim()
         if (!url) {
           onNotifyRef.current?.('error', 'callback_url 为空，无法提交')
           return
         }
+        reportSnapshot([])
+        runtime.reportEvent({
+          action: 'submit',
+          component: 'SubmitButton',
+        })
         const result = await submitFormJson(url, answer, {
           headers: resolvedSubmitHeaders,
         })
@@ -252,6 +349,16 @@ function AskUserFormCardBody({
         form: formDef ?? payloadDef,
         answer,
       })
+      const agentError = validateAnswerAgentBody(body)
+      if (agentError) {
+        onNotifyRef.current?.('error', agentError)
+        return
+      }
+      reportSnapshot([])
+      runtime.reportEvent({
+        action: 'submit',
+        component: 'SubmitButton',
+      })
       const result = await submitAnswerAgent(body, {
         headers: resolvedSubmitHeaders,
       })
@@ -270,6 +377,7 @@ function AskUserFormCardBody({
     fieldNames,
     renderBlocks,
     extraValues,
+    reportSnapshot,
     runtime,
     submitMode,
     callbackUrl,
@@ -383,7 +491,6 @@ export default function AskUserFormCard(props: AskUserFormCardProps) {
   const resolvedAskUserMessageId = props.askUserMessageId?.trim() ?? ''
   const realtimeWsUrl = useMemo(() => resolveRealtimeWsUrl(), [])
   const [surfaceReady, setSurfaceReady] = useState(false)
-  const [wsClient, setWsClient] = useState<FormRuntimeWsClient | null>(null)
   const autoControlHandlerRef = useRef<((data: FormAutoControlEventData) => void) | null>(null)
 
   const onSurfaceReadyChange = useCallback((ready: boolean) => {
@@ -397,38 +504,41 @@ export default function AskUserFormCard(props: AskUserFormCardProps) {
     [],
   )
 
-  const shouldConnect = Boolean(
-    realtimeWsUrl && resolvedAskUserMessageId && surfaceReady,
-  )
-
-  useEffect(() => {
-    if (!shouldConnect || !realtimeWsUrl || !resolvedAskUserMessageId) {
-      setWsClient(null)
-      return
-    }
-    const client = new FormRuntimeWsClient({
+  // 有 URL + id 即创建会话并挂到 Provider：表单刚可交互时 send 可入队，
+  // 不必等 setState(surfaceReady) / connect 完成。
+  const wsClient = useMemo(() => {
+    if (!realtimeWsUrl || !resolvedAskUserMessageId) return null
+    return new FormRuntimeWsClient({
       url: realtimeWsUrl,
       askUserMessageId: resolvedAskUserMessageId,
       onAutoControl: (data) => {
         autoControlHandlerRef.current?.(data)
       },
     })
-    client.connect()
-    setWsClient(client)
+  }, [realtimeWsUrl, resolvedAskUserMessageId])
+
+  useEffect(() => {
+    if (!wsClient) return
     return () => {
-      client.close()
-      setWsClient(null)
+      wsClient.close()
     }
-  }, [shouldConnect, realtimeWsUrl, resolvedAskUserMessageId])
+  }, [wsClient])
+
+  useEffect(() => {
+    if (!wsClient || !surfaceReady) return
+    wsClient.connect()
+  }, [wsClient, surfaceReady])
 
   return (
     <SkoponFormProvider>
       <FormRuntimeProvider client={wsClient}>
-        <AskUserFormCardBody
-          {...props}
-          onSurfaceReadyChange={onSurfaceReadyChange}
-          onAutoControlReady={onAutoControlReady}
-        />
+        <FormLiveOptionsProvider>
+          <AskUserFormCardBody
+            {...props}
+            onSurfaceReadyChange={onSurfaceReadyChange}
+            onAutoControlReady={onAutoControlReady}
+          />
+        </FormLiveOptionsProvider>
       </FormRuntimeProvider>
     </SkoponFormProvider>
   )