@skopon-cool/form-sdk 0.3.0 → 0.3.2

package/dist/runtime/formAutoControl.d.ts

@@ -8,6 +8,7 @@ export interface FormAutoControlTargets {
 }
 export interface FormAutoControlHelpers {
     reportEvent: (event: FormRuntimeEventData) => void;
+    /** 支持同步或返回 Promise（async submit 期间保持 autoControlDepth） */
     runAutoControl: <T>(fn: () => T) => T;
 }
 /** 执行下行 form_auto_control_event；缺参或未知 action 时 warn 并忽略。 */

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

@@ -1 +1 @@
-{"version":3,"file":"formAutoControl.d.ts","sourceRoot":"","sources":["../../src/runtime/formAutoControl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE7E,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACpD,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7D,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,yCAAyC;IACzC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;CACtC;AAiCD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAyDN"}
+{"version":3,"file":"formAutoControl.d.ts","sourceRoot":"","sources":["../../src/runtime/formAutoControl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE7E,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACpD,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7D,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,yCAAyC;IACzC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,0DAA0D;IAC1D,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;CACtC;AAiCD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAyDN"}

package/dist/runtime/formRuntimeContext.d.ts

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

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,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,aAAa,EAAE,MAAM,OAAO,CAAA;CAC7B;AAqBD,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,+BAwD1B;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,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"}

package/dist/runtime/formRuntimeWs.d.ts

@@ -18,6 +18,8 @@ export declare class FormRuntimeWsClient {
     connect(): void;
     send(type: FormRuntimeOutboundType, data: Record<string, unknown>): void;
     close(): void;
+    /** 关闭当前 socket 且不触发重连（清掉 onclose），建新连或主动 close 时用。 */
+    private disposeSocket;
     private enqueue;
     private flushQueue;
     private scheduleReconnect;

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,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;IA2Bf,IAAI,CACF,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAqBP,KAAK,IAAI,IAAI;IAOb,sDAAsD;IACtD,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;CAgBtB"}

package/package.json

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

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 {
@@ -222,18 +223,18 @@ 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
         }
+        // 确认可 POST 后再上报，避免空 callback 仍发 data/submit
+        runtime.reportData(answer)
+        runtime.reportEvent({
+          action: 'submit',
+          component: 'SubmitButton',
+        })
         const result = await submitFormJson(url, answer, {
           headers: resolvedSubmitHeaders,
         })
@@ -252,6 +253,16 @@ function AskUserFormCardBody({
         form: formDef ?? payloadDef,
         answer,
       })
+      const agentError = validateAnswerAgentBody(body)
+      if (agentError) {
+        onNotifyRef.current?.('error', agentError)
+        return
+      }
+      runtime.reportData(answer)
+      runtime.reportEvent({
+        action: 'submit',
+        component: 'SubmitButton',
+      })
       const result = await submitAnswerAgent(body, {
         headers: resolvedSubmitHeaders,
       })
@@ -383,7 +394,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,29 +407,30 @@ 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 即创建 client 并挂到 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>

package/src/runtime/formAutoControl.test.ts

@@ -5,6 +5,32 @@ import { describe, it, expect, vi } from 'vitest'
 import { executeFormAutoControl } from './formAutoControl'
 import type { FormAutoControlEventData } from './types'
 
+/** 模拟 FormRuntimeProvider.runAutoControl：Promise settle 前保持 depth。 */
+function createDepthTrackingRunAutoControl(depthRef: { current: number }) {
+  return <T,>(fn: () => T): T => {
+    depthRef.current += 1
+    let syncResult: T
+    try {
+      syncResult = fn()
+    } catch (error) {
+      depthRef.current = Math.max(0, depthRef.current - 1)
+      throw error
+    }
+    if (
+      syncResult != null &&
+      (typeof syncResult === 'object' || typeof syncResult === 'function') &&
+      typeof (syncResult as PromiseLike<unknown>).then === 'function'
+    ) {
+      const promise = Promise.resolve(syncResult).finally(() => {
+        depthRef.current = Math.max(0, depthRef.current - 1)
+      })
+      return promise as T
+    }
+    depthRef.current = Math.max(0, depthRef.current - 1)
+    return syncResult
+  }
+}
+
 describe('executeFormAutoControl', () => {
   it('writes values and reports bac change event', () => {
     const setValues = vi.fn()
@@ -68,4 +94,34 @@ describe('executeFormAutoControl', () => {
     )
     expect(submit).toHaveBeenCalled()
   })
+
+  it('keeps autoControl depth until async submit settles', async () => {
+    const depthRef = { current: 0 }
+    const runAutoControl = createDepthTrackingRunAutoControl(depthRef)
+    let resolveSubmit!: () => void
+    const submit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveSubmit = resolve
+        }),
+    )
+
+    executeFormAutoControl(
+      { action: 'submit' },
+      {
+        setValues: vi.fn(),
+        getValues: () => ({}),
+        submit,
+        rootElement: null,
+      },
+      { reportEvent: vi.fn(), runAutoControl },
+    )
+
+    expect(submit).toHaveBeenCalled()
+    expect(depthRef.current).toBe(1)
+    resolveSubmit()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(depthRef.current).toBe(0)
+  })
 })

package/src/runtime/formAutoControl.ts

@@ -10,6 +10,7 @@ export interface FormAutoControlTargets {
 
 export interface FormAutoControlHelpers {
   reportEvent: (event: FormRuntimeEventData) => void
+  /** 支持同步或返回 Promise（async submit 期间保持 autoControlDepth） */
   runAutoControl: <T>(fn: () => T) => T
 }
 
@@ -64,8 +65,8 @@ export function executeFormAutoControl(
 
   helpers.runAutoControl(() => {
     if (action === 'submit') {
-      void targets.submit()
-      return
+      // 返回 Promise，使 runAutoControl 在 settle 前保持 depth
+      return targets.submit()
     }
 
     const field = typeof data.field === 'string' ? data.field.trim() : ''

package/src/runtime/formRuntimeContext.tsx

@@ -12,12 +12,24 @@ import type { FormRuntimeEventData } from './types'
 export interface FormRuntimeContextValue {
   reportEvent: (event: FormRuntimeEventData) => void
   reportData: (values: Record<string, unknown>) => void
+  /**
+   * 在自动控上下文中执行 fn。若 fn 返回 Promise，depth 保持到 settle，
+   * 使异步 submit 内的 reportEvent 仍为 form_auto_control_bac_event。
+   */
   runAutoControl: <T>(fn: () => T) => T
   isAutoControl: () => boolean
 }
 
 const FormRuntimeContext = createContext<FormRuntimeContextValue | null>(null)
 
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as PromiseLike<unknown>).then === 'function'
+  )
+}
+
 const noopRuntime: FormRuntimeContextValue = {
   reportEvent: () => {},
   reportData: () => {},
@@ -72,11 +84,21 @@ export function FormRuntimeProvider({
 
   const runAutoControl = useCallback(<T,>(fn: () => T): T => {
     autoControlDepthRef.current += 1
+    let syncResult: T
     try {
-      return fn()
-    } finally {
+      syncResult = fn()
+    } catch (error) {
       autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+      throw error
+    }
+    if (isThenable(syncResult)) {
+      const promise = Promise.resolve(syncResult).finally(() => {
+        autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+      })
+      return promise as T
     }
+    autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+    return syncResult
   }, [])
 
   const isAutoControl = useCallback(

package/src/runtime/formRuntimeWs.ts

@@ -37,6 +37,7 @@ export class FormRuntimeWsClient {
   connect(): void {
     if (this.closed || typeof WebSocket === 'undefined') return
     this.clearReconnectTimer()
+    this.disposeSocket()
     try {
       const ws = new WebSocket(this.url)
       this.ws = ws
@@ -48,7 +49,7 @@ export class FormRuntimeWsClient {
         this.handleMessage(event.data)
       }
       ws.onclose = () => {
-        this.ws = null
+        if (this.ws === ws) this.ws = null
         this.scheduleReconnect()
       }
       ws.onerror = () => {
@@ -88,18 +89,22 @@ export class FormRuntimeWsClient {
     this.closed = true
     this.clearReconnectTimer()
     this.sendQueue = []
-    if (this.ws) {
-      this.ws.onopen = null
-      this.ws.onmessage = null
-      this.ws.onclose = null
-      this.ws.onerror = null
-      try {
-        this.ws.close()
-      } catch {
-        // ignore
-      }
-      this.ws = null
+    this.disposeSocket()
+  }
+
+  /** 关闭当前 socket 且不触发重连（清掉 onclose），建新连或主动 close 时用。 */
+  private disposeSocket(): void {
+    if (!this.ws) return
+    this.ws.onopen = null
+    this.ws.onmessage = null
+    this.ws.onclose = null
+    this.ws.onerror = null
+    try {
+      this.ws.close()
+    } catch {
+      // ignore
     }
+    this.ws = null
   }
 
   private enqueue(serialized: string): void {