statewire 0.13.1 → 0.14.0

package/dist/statewire.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire.js","names":["useMemo","useRef","useState","useSyncExternalStore","createTapRoot","flushTapSync","resource","useContextProvider","useResource","useResources","withKey","ResourceElement","LIVE_CONNECTION","useStatewireCore","Statewire","TERMINAL","SessionStorageContext","useSessionTransport","transport","session","StatewireClient","SessionStorage","SessionTransport","useStatewire","Commands","options","Options","TState","TCommands","Helpers","latest","current","storage","undefined","value","core","subscribe","listener","state","getState","isBusy","getBusy","failed","getFailed","connection","failures","NonNullable","Error","commands","CommandsProxy","setContext","contextValue","Record","retryFailed","entry","FailedCommand","retry","discardFailed","discard","StatewireResource","root","disposed","constructor","ClientRoot","getValue","Connection","Promise","dispose","unmount","initialState","optimistic","Optimistic","materialize","Materialize","onStateChange","ctx","changes","Changes","onCommandChange","update","CommandUpdate","onConnectionChange","failureCovered","ConnectionState","status","cause","attempt","nextRetryAt","lastError","message","payload","reconnect","ConnectionStatus","draft","command","Command","OptimisticContext","ts","seq","clientId","SendFailure","fate","code","predecessorLost","OnSessionLost","pending","ReadonlyArray","method","params","meta","failure","SessionCommand","SessionRecord","nextSeq","ctxNextSeq","verdicts","SessionVerdict","type","load","save","record","lock","fn","T","HeadersOption","HeadersInit","staleAuth","SSEOptions","sessionStore","url","isNew","headers","fetch","globalThis","onSessionLost","onChange","onDone","WSOptions","protocols","query","webSocket","WebSocket"],"sources":["../src/statewire.ts"],"sourcesContent":["import { useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport {\n  createTapRoot,\n  flushTapSync,\n  resource,\n  useContextProvider,\n  useResource,\n  useResources,\n  withKey,\n} from \"@assistant-ui/tap\";\nimport type { ResourceElement } from \"@assistant-ui/tap\";\nimport { LIVE_CONNECTION, useStatewireCore } from \"./client/core\";\nimport type { Statewire } from \"./types\";\nimport type { TERMINAL } from \"./client/connection\";\nimport { SessionStorageContext } from \"./client/sessionStore\";\n\nconst useSessionTransport = ({\n  transport,\n  session,\n}: {\n  transport: ResourceElement<Statewire<any, any>>;\n  session: StatewireClient.SessionStorage | undefined;\n}): Statewire<unknown> =>\n  useContextProvider(SessionStorageContext, session, () =>\n    // oxlint-disable-next-line react-hooks/rules-of-hooks\n    useResource(transport),\n  );\n\n// The transport owns the session; it reads the storage off the context this\n// wrapper's own fiber provides, so plain-React callers get a provider too.\nconst SessionTransport = resource(useSessionTransport);\n\nexport const useStatewire = <\n  TState,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: StatewireClient.Options<TState, TCommands>,\n): StatewireClient.Helpers<TState, TCommands> => {\n  const latest = useRef(options);\n  latest.current = options;\n\n  const session = useResources(\n    options.storage?.session !== undefined\n      ? [withKey(\"session\", options.storage.session)]\n      : [],\n  )[0];\n  const value = useResource(\n    SessionTransport({ transport: options.transport, session }),\n  );\n  const core = useStatewireCore(() => latest.current, value);\n  const [subscribe] = useState(\n    () => (listener: () => void) =>\n      core.subscribe(() => flushTapSync(listener)),\n  );\n\n  const state = useSyncExternalStore(\n    subscribe,\n    core.getState,\n    core.getState,\n  ) as TState;\n  const isBusy = useSyncExternalStore(subscribe, core.getBusy, core.getBusy);\n  const failed = useSyncExternalStore(\n    subscribe,\n    core.getFailed,\n    core.getFailed,\n  );\n  const connection = value.connection ?? LIVE_CONNECTION;\n\n  return useMemo(() => {\n    const failures = (): NonNullable<typeof value.failures> => {\n      if (!value.failures) {\n        throw new Error(\"statewire: this transport has no failed-send lane\");\n      }\n      return value.failures;\n    };\n    return {\n      state,\n      getState: core.getState as () => TState,\n      connection,\n      commands: core.commands as Statewire.CommandsProxy<TCommands>,\n      isBusy,\n      setContext: (contextValue: Record<string, unknown>) => {\n        if (!value.setContext) {\n          throw new Error(\n            \"statewire: this transport has no client context channel\",\n          );\n        }\n        value.setContext(contextValue);\n      },\n      failed,\n      retryFailed: (entry: StatewireClient.FailedCommand) =>\n        failures().retry(entry),\n      discardFailed: (entry: StatewireClient.FailedCommand) =>\n        failures().discard(entry),\n    };\n  }, [state, isBusy, failed, connection, core, value]);\n};\n\nexport const StatewireResource = <\n  TState,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: StatewireClient.Options<TState, TCommands>,\n): ResourceElement<StatewireClient.Helpers<TState, TCommands>> =>\n  resource(useStatewire<TState, TCommands>)(options);\n\nexport class StatewireClient<\n  TState,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n> {\n  private readonly root;\n  private disposed = false;\n\n  constructor(options: StatewireClient.Options<TState, TCommands>) {\n    const ClientRoot = () => useStatewire<TState, TCommands>(options);\n    this.root = createTapRoot(ClientRoot);\n  }\n\n  get state(): TState {\n    return this.root.getValue().getState();\n  }\n\n  get connection(): StatewireClient.Connection {\n    return this.root.getValue().connection;\n  }\n\n  get commands(): Statewire.CommandsProxy<TCommands> {\n    return this.root.getValue().commands;\n  }\n\n  get isBusy(): boolean {\n    return this.root.getValue().isBusy;\n  }\n\n  setContext(value: Record<string, unknown>): void {\n    this.root.getValue().setContext(value);\n  }\n\n  get failed(): readonly StatewireClient.FailedCommand[] {\n    return this.root.getValue().failed;\n  }\n\n  retryFailed(entry: StatewireClient.FailedCommand): Promise<unknown> {\n    return this.root.getValue().retryFailed(entry);\n  }\n\n  discardFailed(entry: StatewireClient.FailedCommand): void {\n    this.root.getValue().discardFailed(entry);\n  }\n\n  subscribe(listener: () => void): () => void {\n    return this.root.subscribe(listener);\n  }\n\n  dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.root.unmount();\n  }\n}\n\nexport namespace StatewireClient {\n  export type Options<\n    TState,\n    TCommands extends Statewire.Commands = Statewire.Commands,\n  > = {\n    transport: ResourceElement<Statewire<TState, TCommands>>;\n    /** Durable session: the mounted storage holds this client's lane identity and its un-durable commands, which resend on the next attach. */\n    storage?:\n      | { session?: ResourceElement<SessionStorage> | undefined }\n      | undefined;\n    /** Served as the canonical state until the attach snapshot; own commands fold over it. */\n    initialState?: TState;\n    optimistic?: Optimistic<NonNullable<TState>, TCommands>;\n    materialize?: Materialize<NonNullable<TState>>;\n    onStateChange?: (\n      state: NonNullable<TState>,\n      ctx: { changes: Statewire.Changes },\n    ) => void;\n    onCommandChange?: (\n      update: Statewire.CommandUpdate<TCommands>,\n      ctx: { state: NonNullable<TState> },\n    ) => void;\n    onConnectionChange?: (connection: Connection) => void;\n    /** Drops a retained failed entry once a canonical snapshot shows its effect landed; checked against each new snapshot. */\n    failureCovered?: (\n      state: NonNullable<TState>,\n      entry: FailedCommand,\n    ) => boolean;\n  };\n\n  export type Helpers<\n    TState,\n    TCommands extends Statewire.Commands = Statewire.Commands,\n  > = {\n    /** The statewire's state type — remote statewires include `undefined` until the first attach snapshot applies. */\n    state: TState;\n    /** Identity-stable across renders; reads the current canonical state without subscribing the caller. */\n    getState: () => TState;\n    connection: Connection;\n    commands: Statewire.CommandsProxy<TCommands>;\n    /** Negation of the server's broadcast idle level (a transport without idle is always busy). */\n    isBusy: boolean;\n    /** Replace this client's ambient context on the server; throws on transports without a client context channel. */\n    setContext: (value: Record<string, unknown>) => void;\n    /** Non-accepted sends retained in the session record; reload with it. */\n    failed: readonly FailedCommand[];\n    /** Re-enqueues the entry's command on fresh clocks and removes the entry. */\n    retryFailed: (entry: FailedCommand) => Promise<unknown>;\n    /** Removes the entry. */\n    discardFailed: (entry: FailedCommand) => void;\n  };\n\n  export type ConnectionState =\n    | { status: \"connecting\" }\n    | { status: \"live\" }\n    | { status: \"idle\" }\n    | {\n        status: \"reconnecting\";\n        cause: \"dropped\" | \"evicted\" | \"error\" | \"unauthorized\";\n        attempt: number;\n        nextRetryAt: number;\n        lastError?: string;\n        message?: string;\n      }\n    | { status: \"gone\"; message?: string; payload?: unknown };\n  export type Connection = ConnectionState & { reconnect: () => void };\n  export type ConnectionStatus = Connection[\"status\"];\n\n  /**\n   * Mutate the draft in place; the client records the next state plus the exact\n   * changed paths. Re-run against the new base on every rebase.\n   */\n  export type Optimistic<\n    TState,\n    TCommands extends Statewire.Commands = Statewire.Commands,\n  > = (\n    draft: TState,\n    command: Statewire.Command<TCommands>,\n    ctx: OptimisticContext,\n  ) => void;\n\n  export type OptimisticContext = {\n    ts: number;\n    seq: number;\n    clientId?: string;\n  };\n\n  /**\n   * Mutate the draft to make server-accepted, still-uncommitted intents in\n   * the state concrete (e.g. dispatch records into messages). Runs after the\n   * optimistic folds on every published state.\n   */\n  export type Materialize<TState> = (draft: TState) => void;\n\n  /**\n   * fate: \"aborted\" = never sent, \"rejected\" = the server refused it\n   * (`code` \"unknown-command\" | \"invalid-params\" for the static rejects,\n   * code-less for handler rejects), \"lost\" = sent but no verdict will ever\n   * arrive — the record is gone (a proven seq gap) or the channel died: it\n   * may or may not have run, \"failed\" = the handler ran and threw,\n   * \"crashed\" = the handler died involuntarily, \"expired\" = settled —\n   * result, rejected, failed, or crashed — but the verdict outlived the\n   * server's retention.\n   * cause is which channel settled it: \"server\" = the server's answer;\n   * the rest are channel deaths the client settled locally.\n   */\n  export type SendFailure =\n    | {\n        fate: \"rejected\";\n        cause: \"server\";\n        code?: string;\n        message?: string;\n        payload?: unknown;\n      }\n    | { fate: \"failed\"; cause: \"server\"; message?: string }\n    | { fate: \"crashed\"; cause: \"server\" }\n    | { fate: \"expired\"; cause: \"server\" }\n    | {\n        fate: \"aborted\";\n        cause: \"unmount\" | \"stream-gone\" | \"session-lost\";\n        predecessorLost?: true;\n      }\n    | {\n        fate: \"lost\";\n        cause: \"unmount\" | \"stream-gone\" | \"session-lost\";\n      };\n\n  /** Held commands a proven record gap settled `{fate: \"lost\", cause: \"session-lost\"}`; return \"requeue\" to re-enqueue them on the reset clocks. */\n  export type OnSessionLost = (\n    pending: ReadonlyArray<{\n      method: string;\n      params: readonly unknown[];\n      ts: number;\n      seq: number;\n      clientId?: string;\n    }>,\n  ) => \"requeue\" | \"drop\";\n\n  /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */\n  export type FailedCommand = {\n    readonly command: string;\n    readonly params: readonly unknown[];\n    readonly meta?: unknown;\n    readonly failure: SendFailure;\n    readonly ts: number;\n    readonly seq: number;\n  };\n\n  /** A command as persisted while un-durable: its lane seq plus the wire statement. */\n  export type SessionCommand = {\n    seq: number;\n    method: string;\n    params: unknown[];\n    meta?: unknown;\n  };\n\n  /** The persisted session: the lane identity, the lane clocks, and the commands the server has not marked durable. */\n  export type SessionRecord = {\n    clientId: string;\n    nextSeq: number;\n    ctxNextSeq: number;\n    commands: readonly SessionCommand[];\n    /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */\n    verdicts?: readonly SessionVerdict[];\n    /** Non-accepted sends retained for the user; survive record rebases and resets. */\n    failed?: readonly FailedCommand[];\n  };\n\n  /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */\n  export type SessionVerdict = {\n    seq: number;\n    type: (typeof TERMINAL)[number];\n    code?: string;\n    message?: string;\n    payload?: unknown;\n    meta?: unknown;\n  };\n\n  /** Session storage seam; `save` must persist synchronously in the caller's flow. */\n  export type SessionStorage = {\n    load: () => SessionRecord | null;\n    save: (record: SessionRecord) => void;\n    /** Serializes record mutations across sharers; presence marks the storage shared. */\n    lock?: <T>(fn: () => T | Promise<T>) => Promise<T>;\n    /** Notifies of record saves by other sharers; returns unsubscribe. Required alongside `lock`. */\n    subscribe?: (listener: () => void) => () => void;\n  };\n\n  /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */\n  export type HeadersOption =\n    | HeadersInit\n    | ((ctx: { staleAuth: boolean }) => HeadersInit | Promise<HeadersInit>);\n\n  export type SSEOptions = {\n    sessionStore?: SessionStorage | undefined;\n    url: string;\n    /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */\n    isNew?: boolean;\n    headers?: HeadersOption;\n    fetch?: typeof globalThis.fetch;\n    onSessionLost?: OnSessionLost;\n    onChange?: (connection: Connection) => void;\n    /** The broadcast idle flag's rising edge: the instance went quiet. */\n    onDone?: () => void;\n  };\n\n  export type WSOptions = {\n    sessionStore?: SessionStorage | undefined;\n    url: string;\n    /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */\n    isNew?: boolean;\n    headers?: HeadersOption;\n    protocols?: string | string[];\n    query?:\n      | Record<string, string>\n      | (() => Record<string, string> | Promise<Record<string, string>>);\n    webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;\n    onSessionLost?: OnSessionLost;\n    onChange?: (connection: Connection) => void;\n    /** The broadcast idle flag's rising edge: the instance went quiet. */\n    onDone?: () => void;\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"statewire.js","names":["useMemo","useRef","useState","useSyncExternalStore","createTapRoot","flushTapSync","resource","useContextProvider","useResource","useResources","withKey","ResourceElement","CONNECTED_CONNECTION","useStatewireCore","Statewire","TERMINAL","SessionStorageContext","useSessionTransport","transport","session","StatewireClient","SessionStorage","SessionTransport","useStatewire","Commands","options","Options","TState","TCommands","Helpers","latest","current","storage","undefined","value","core","subscribe","listener","state","getState","isBusy","getBusy","failed","getFailed","connection","failures","NonNullable","Error","commands","CommandsProxy","setContext","contextValue","Record","retryFailed","entry","FailedCommand","retry","discardFailed","discard","StatewireResource","root","disposed","constructor","ClientRoot","getValue","Connection","Promise","dispose","unmount","initialState","optimistic","Optimistic","materialize","Materialize","onStateChange","ctx","changes","Changes","onCommandChange","update","CommandUpdate","onConnectionChange","failureCovered","ConnectionState","status","reason","message","payload","attempt","cause","nextRetryAt","lastError","reconnect","degraded","ConnectionStatus","draft","command","Command","OptimisticContext","ts","seq","clientId","SendFailure","fate","code","predecessorLost","OnSessionLost","pending","ReadonlyArray","method","params","meta","failure","SessionCommand","SessionRecord","nextSeq","ctxNextSeq","verdicts","SessionVerdict","type","load","save","record","lock","fn","T","HeadersOption","HeadersInit","staleAuth","SSEOptions","sessionStore","url","isNew","headers","fetch","globalThis","onSessionLost","onChange","onDone","WSOptions","protocols","query","webSocket","WebSocket"],"sources":["../src/statewire.ts"],"sourcesContent":["import { useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport {\n  createTapRoot,\n  flushTapSync,\n  resource,\n  useContextProvider,\n  useResource,\n  useResources,\n  withKey,\n} from \"@assistant-ui/tap\";\nimport type { ResourceElement } from \"@assistant-ui/tap\";\nimport { CONNECTED_CONNECTION, useStatewireCore } from \"./client/core\";\nimport type { Statewire } from \"./types\";\nimport type { TERMINAL } from \"./client/connection\";\nimport { SessionStorageContext } from \"./client/sessionStore\";\n\nconst useSessionTransport = ({\n  transport,\n  session,\n}: {\n  transport: ResourceElement<Statewire<any, any>>;\n  session: StatewireClient.SessionStorage | undefined;\n}): Statewire<unknown> =>\n  useContextProvider(SessionStorageContext, session, () =>\n    // oxlint-disable-next-line react-hooks/rules-of-hooks\n    useResource(transport),\n  );\n\n// The transport owns the session; it reads the storage off the context this\n// wrapper's own fiber provides, so plain-React callers get a provider too.\nconst SessionTransport = resource(useSessionTransport);\n\nexport const useStatewire = <\n  TState,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: StatewireClient.Options<TState, TCommands>,\n): StatewireClient.Helpers<TState, TCommands> => {\n  const latest = useRef(options);\n  latest.current = options;\n\n  const session = useResources(\n    options.storage?.session !== undefined\n      ? [withKey(\"session\", options.storage.session)]\n      : [],\n  )[0];\n  const value = useResource(\n    SessionTransport({ transport: options.transport, session }),\n  );\n  const core = useStatewireCore(() => latest.current, value);\n  const [subscribe] = useState(\n    () => (listener: () => void) =>\n      core.subscribe(() => flushTapSync(listener)),\n  );\n\n  const state = useSyncExternalStore(\n    subscribe,\n    core.getState,\n    core.getState,\n  ) as TState;\n  const isBusy = useSyncExternalStore(subscribe, core.getBusy, core.getBusy);\n  const failed = useSyncExternalStore(\n    subscribe,\n    core.getFailed,\n    core.getFailed,\n  );\n  const connection = value.connection ?? CONNECTED_CONNECTION;\n\n  return useMemo(() => {\n    const failures = (): NonNullable<typeof value.failures> => {\n      if (!value.failures) {\n        throw new Error(\"statewire: this transport has no failed-send lane\");\n      }\n      return value.failures;\n    };\n    return {\n      state,\n      getState: core.getState as () => TState,\n      connection,\n      commands: core.commands as Statewire.CommandsProxy<TCommands>,\n      isBusy,\n      setContext: (contextValue: Record<string, unknown>) => {\n        if (!value.setContext) {\n          throw new Error(\n            \"statewire: this transport has no client context channel\",\n          );\n        }\n        value.setContext(contextValue);\n      },\n      failed,\n      retryFailed: (entry: StatewireClient.FailedCommand) =>\n        failures().retry(entry),\n      discardFailed: (entry: StatewireClient.FailedCommand) =>\n        failures().discard(entry),\n    };\n  }, [state, isBusy, failed, connection, core, value]);\n};\n\nexport const StatewireResource = <\n  TState,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n>(\n  options: StatewireClient.Options<TState, TCommands>,\n): ResourceElement<StatewireClient.Helpers<TState, TCommands>> =>\n  resource(useStatewire<TState, TCommands>)(options);\n\nexport class StatewireClient<\n  TState,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n> {\n  private readonly root;\n  private disposed = false;\n\n  constructor(options: StatewireClient.Options<TState, TCommands>) {\n    const ClientRoot = () => useStatewire<TState, TCommands>(options);\n    this.root = createTapRoot(ClientRoot);\n  }\n\n  get state(): TState {\n    return this.root.getValue().getState();\n  }\n\n  get connection(): StatewireClient.Connection {\n    return this.root.getValue().connection;\n  }\n\n  get commands(): Statewire.CommandsProxy<TCommands> {\n    return this.root.getValue().commands;\n  }\n\n  get isBusy(): boolean {\n    return this.root.getValue().isBusy;\n  }\n\n  setContext(value: Record<string, unknown>): void {\n    this.root.getValue().setContext(value);\n  }\n\n  get failed(): readonly StatewireClient.FailedCommand[] {\n    return this.root.getValue().failed;\n  }\n\n  retryFailed(entry: StatewireClient.FailedCommand): Promise<unknown> {\n    return this.root.getValue().retryFailed(entry);\n  }\n\n  discardFailed(entry: StatewireClient.FailedCommand): void {\n    this.root.getValue().discardFailed(entry);\n  }\n\n  subscribe(listener: () => void): () => void {\n    return this.root.subscribe(listener);\n  }\n\n  dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.root.unmount();\n  }\n}\n\nexport namespace StatewireClient {\n  export type Options<\n    TState,\n    TCommands extends Statewire.Commands = Statewire.Commands,\n  > = {\n    transport: ResourceElement<Statewire<TState, TCommands>>;\n    /** Durable session: the mounted storage holds this client's lane identity and its un-durable commands, which resend on the next attach. */\n    storage?:\n      | { session?: ResourceElement<SessionStorage> | undefined }\n      | undefined;\n    /** Served as the canonical state until the attach snapshot; own commands fold over it. */\n    initialState?: TState;\n    optimistic?: Optimistic<NonNullable<TState>, TCommands>;\n    materialize?: Materialize<NonNullable<TState>>;\n    onStateChange?: (\n      state: NonNullable<TState>,\n      ctx: { changes: Statewire.Changes },\n    ) => void;\n    onCommandChange?: (\n      update: Statewire.CommandUpdate<TCommands>,\n      ctx: { state: NonNullable<TState> },\n    ) => void;\n    onConnectionChange?: (connection: Connection) => void;\n    /** Drops a retained failed entry once a canonical snapshot shows its effect landed; checked against each new snapshot. */\n    failureCovered?: (\n      state: NonNullable<TState>,\n      entry: FailedCommand,\n    ) => boolean;\n  };\n\n  export type Helpers<\n    TState,\n    TCommands extends Statewire.Commands = Statewire.Commands,\n  > = {\n    /** The statewire's state type — remote statewires include `undefined` until the first attach snapshot applies. */\n    state: TState;\n    /** Identity-stable across renders; reads the current canonical state without subscribing the caller. */\n    getState: () => TState;\n    connection: Connection;\n    commands: Statewire.CommandsProxy<TCommands>;\n    /** Negation of the server's broadcast idle level (a transport without idle is always busy). */\n    isBusy: boolean;\n    /** Replace this client's ambient context on the server; throws on transports without a client context channel. */\n    setContext: (value: Record<string, unknown>) => void;\n    /** Non-accepted sends retained in the session record; reload with it. */\n    failed: readonly FailedCommand[];\n    /** Re-enqueues the entry's command on fresh clocks and removes the entry. */\n    retryFailed: (entry: FailedCommand) => Promise<unknown>;\n    /** Removes the entry. */\n    discardFailed: (entry: FailedCommand) => void;\n  };\n\n  /** `cause`/`nextRetryAt`/`lastError` are present only while waiting out the backoff timer; a dial in flight carries `attempt` alone. */\n  export type ConnectionState =\n    | {\n        status: \"disconnected\";\n        reason: \"deferred\" | \"idle\" | \"gone\";\n        message?: string;\n        payload?: unknown;\n      }\n    | {\n        status: \"connecting\";\n        /** 0 = the episode's first dial, >0 = retry. */\n        attempt: number;\n        cause?: \"dropped\" | \"evicted\" | \"error\" | \"unauthorized\";\n        nextRetryAt?: number;\n        lastError?: string;\n        message?: string;\n      }\n    | { status: \"connected\" };\n  export type Connection = ConnectionState & {\n    reconnect: () => void;\n    /** True while retrying (`connecting` with `attempt > 0`) or parked `gone`. */\n    degraded: boolean;\n  };\n  export type ConnectionStatus = Connection[\"status\"];\n\n  /**\n   * Mutate the draft in place; the client records the next state plus the exact\n   * changed paths. Re-run against the new base on every rebase.\n   */\n  export type Optimistic<\n    TState,\n    TCommands extends Statewire.Commands = Statewire.Commands,\n  > = (\n    draft: TState,\n    command: Statewire.Command<TCommands>,\n    ctx: OptimisticContext,\n  ) => void;\n\n  export type OptimisticContext = {\n    ts: number;\n    seq: number;\n    clientId?: string;\n  };\n\n  /**\n   * Mutate the draft to make server-accepted, still-uncommitted intents in\n   * the state concrete (e.g. dispatch records into messages). Runs after the\n   * optimistic folds on every published state.\n   */\n  export type Materialize<TState> = (draft: TState) => void;\n\n  /**\n   * fate: \"aborted\" = never sent, \"rejected\" = the server refused it\n   * (`code` \"unknown-command\" | \"invalid-params\" for the static rejects,\n   * code-less for handler rejects), \"lost\" = sent but no verdict will ever\n   * arrive — the record is gone (a proven seq gap) or the channel died: it\n   * may or may not have run, \"failed\" = the handler ran and threw,\n   * \"crashed\" = the handler died involuntarily, \"expired\" = settled —\n   * result, rejected, failed, or crashed — but the verdict outlived the\n   * server's retention.\n   * cause is which channel settled it: \"server\" = the server's answer;\n   * the rest are channel deaths the client settled locally.\n   */\n  export type SendFailure =\n    | {\n        fate: \"rejected\";\n        cause: \"server\";\n        code?: string;\n        message?: string;\n        payload?: unknown;\n      }\n    | { fate: \"failed\"; cause: \"server\"; message?: string }\n    | { fate: \"crashed\"; cause: \"server\" }\n    | { fate: \"expired\"; cause: \"server\" }\n    | {\n        fate: \"aborted\";\n        cause: \"unmount\" | \"stream-gone\" | \"session-lost\";\n        predecessorLost?: true;\n      }\n    | {\n        fate: \"lost\";\n        cause: \"unmount\" | \"stream-gone\" | \"session-lost\";\n      };\n\n  /** Held commands a proven record gap settled `{fate: \"lost\", cause: \"session-lost\"}`; return \"requeue\" to re-enqueue them on the reset clocks. */\n  export type OnSessionLost = (\n    pending: ReadonlyArray<{\n      method: string;\n      params: readonly unknown[];\n      ts: number;\n      seq: number;\n      clientId?: string;\n    }>,\n  ) => \"requeue\" | \"drop\";\n\n  /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */\n  export type FailedCommand = {\n    readonly command: string;\n    readonly params: readonly unknown[];\n    readonly meta?: unknown;\n    readonly failure: SendFailure;\n    readonly ts: number;\n    readonly seq: number;\n  };\n\n  /** A command as persisted while un-durable: its lane seq plus the wire statement. */\n  export type SessionCommand = {\n    seq: number;\n    method: string;\n    params: unknown[];\n    meta?: unknown;\n  };\n\n  /** The persisted session: the lane identity, the lane clocks, and the commands the server has not marked durable. */\n  export type SessionRecord = {\n    clientId: string;\n    nextSeq: number;\n    ctxNextSeq: number;\n    commands: readonly SessionCommand[];\n    /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */\n    verdicts?: readonly SessionVerdict[];\n    /** Non-accepted sends retained for the user; survive record rebases and resets. */\n    failed?: readonly FailedCommand[];\n  };\n\n  /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */\n  export type SessionVerdict = {\n    seq: number;\n    type: (typeof TERMINAL)[number];\n    code?: string;\n    message?: string;\n    payload?: unknown;\n    meta?: unknown;\n  };\n\n  /** Session storage seam; `save` must persist synchronously in the caller's flow. */\n  export type SessionStorage = {\n    load: () => SessionRecord | null;\n    save: (record: SessionRecord) => void;\n    /** Serializes record mutations across sharers; presence marks the storage shared. */\n    lock?: <T>(fn: () => T | Promise<T>) => Promise<T>;\n    /** Notifies of record saves by other sharers; returns unsubscribe. Required alongside `lock`. */\n    subscribe?: (listener: () => void) => () => void;\n  };\n\n  /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */\n  export type HeadersOption =\n    | HeadersInit\n    | ((ctx: { staleAuth: boolean }) => HeadersInit | Promise<HeadersInit>);\n\n  export type SSEOptions = {\n    sessionStore?: SessionStorage | undefined;\n    url: string;\n    /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */\n    isNew?: boolean;\n    headers?: HeadersOption;\n    fetch?: typeof globalThis.fetch;\n    onSessionLost?: OnSessionLost;\n    onChange?: (connection: Connection) => void;\n    /** The broadcast idle flag's rising edge: the instance went quiet. */\n    onDone?: () => void;\n  };\n\n  export type WSOptions = {\n    sessionStore?: SessionStorage | undefined;\n    url: string;\n    /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */\n    isNew?: boolean;\n    headers?: HeadersOption;\n    protocols?: string | string[];\n    query?:\n      | Record<string, string>\n      | (() => Record<string, string> | Promise<Record<string, string>>);\n    webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;\n    onSessionLost?: OnSessionLost;\n    onChange?: (connection: Connection) => void;\n    /** The broadcast idle flag's rising edge: the instance went quiet. */\n    onDone?: () => void;\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statewire",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "State over the wire: snapshot-first delta streaming and command submission for any state and any command",
   "license": "MIT",
   "repository": {

package/src/client/connection.ts

@@ -108,11 +108,35 @@ export type Conn = {
   reconnect: () => void;
 };
 
+export const degradedOf = (state: ConnectionState): boolean =>
+  (state.status === "connecting" && state.attempt > 0) ||
+  (state.status === "disconnected" && state.reason === "gone");
+
+const sameState = (a: ConnectionState, b: ConnectionState): boolean => {
+  if (a.status !== b.status) return false;
+  if (a.status === "connecting" && b.status === "connecting") {
+    return (
+      a.attempt === b.attempt &&
+      a.cause === b.cause &&
+      a.nextRetryAt === b.nextRetryAt &&
+      a.lastError === b.lastError
+    );
+  }
+  if (a.status === "disconnected" && b.status === "disconnected") {
+    return a.reason === b.reason;
+  }
+  return true;
+};
+
 const setStatus = (c: Conn, next: ConnectionState) => {
-  const changed = next.status !== c.connection.status;
-  c.connection = { ...next, reconnect: c.reconnect };
+  if (sameState(next, c.connection)) return;
+  c.connection = {
+    ...next,
+    reconnect: c.reconnect,
+    degraded: degradedOf(next),
+  };
   c.notify(c.connection);
-  if (changed) c.onChange(c.connection);
+  c.onChange(c.connection);
 };
 
 const protocolError = (message: string): never => {
@@ -274,7 +298,7 @@ const handleHello = (c: Conn, env: StatewireEnvelope) => {
   c.liveAt = Date.now();
   c.authDenials = 0;
   c.episode = null;
-  setStatus(c, { status: "live" });
+  setStatus(c, { status: "connected" });
 };
 
 let warnedUnknownSynFact = false;
@@ -349,7 +373,7 @@ const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
     c.ctx.onIdle(true);
     c.attempt = 0;
     c.episode = null;
-    setStatus(c, { status: "idle" });
+    setStatus(c, { status: "disconnected", reason: "idle" });
     return "idle";
   }
   // An auth denial gets one immediate redial; a consecutive repeat parks as gone.
@@ -366,7 +390,8 @@ const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
     return "reattach";
   }
   setStatus(c, {
-    status: "gone",
+    status: "disconnected",
+    reason: "gone",
     ...(finish.message !== undefined && { message: finish.message }),
     ...(finish.payload !== undefined && { payload: finish.payload }),
   });
@@ -385,14 +410,17 @@ export const handleEnvelope = (
   }
   deliverEnvelope(c, env);
   if (env.fin !== undefined) return settleFin(c, env.fin);
-  if (c.connection.status !== "live") {
+  if (c.connection.status !== "connected") {
     c.attempt = 0;
     c.episode = null;
-    setStatus(c, { status: "live" });
+    setStatus(c, { status: "connected" });
   }
   return null;
 };
 
+const dialing = (c: Conn) =>
+  setStatus(c, { status: "connecting", attempt: c.attempt });
+
 const scheduleRetry = (
   c: Conn,
   failure: string | undefined,
@@ -404,11 +432,12 @@ const scheduleRetry = (
   c.liveAt = null;
   c.attempt += 1;
   c.episode ??= { cause: "dropped" };
-  const delay = immediate ? 0 : backoff(c.attempt);
+  if (immediate) return 0;
+  const delay = backoff(c.attempt);
   setStatus(c, {
-    status: "reconnecting",
-    ...c.episode,
+    status: "connecting",
     attempt: c.attempt,
+    ...c.episode,
     nextRetryAt: Date.now() + delay,
     ...(failure !== undefined && { lastError: failure }),
   });
@@ -417,13 +446,12 @@ const scheduleRetry = (
 
 const reconnectConn = (c: Conn) => {
   if (!c.lifetime) return;
-  if (c.connection.status === "gone" || c.connection.status === "idle") {
+  if (c.connection.status === "disconnected") {
+    // A reconnect out of a park starts a fresh episode: first dial, attempt 0.
     c.attempt = 0;
     c.authDenials = 0;
-    c.episode = { cause: "dropped" };
-    flushTapSync(() => {
-      scheduleRetry(c, undefined, true);
-    });
+    c.episode = null;
+    flushTapSync(() => dialing(c));
   }
   openGate(c.gate);
   c.abort?.abort();
@@ -437,6 +465,8 @@ const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
     c.parked = false;
   }
   while (alive()) {
+    // The dial is in flight: attempt alone, no backoff fields.
+    flushTapSync(() => dialing(c));
     const abort = new AbortController();
     c.abort = abort;
     c.awaitingHello = true;
@@ -500,7 +530,13 @@ export const useStatewireConn = (props: {
       attemptOnce: (abort) => latest.current.attemptOnce(conn, abort),
       notify: setConnection,
       reconnect: () => reconnectConn(conn),
-      connection: { status: "connecting", reconnect: () => conn.reconnect() },
+      connection: {
+        ...((props.isNew ?? false)
+          ? { status: "disconnected", reason: "deferred" }
+          : { status: "connecting", attempt: 0 }),
+        degraded: false,
+        reconnect: () => conn.reconnect(),
+      },
     };
     return conn;
   });
@@ -512,9 +548,12 @@ export const useStatewireConn = (props: {
     c.authDenials = 0;
     c.liveAt = null;
     c.episode = null;
-    if (c.connection.status !== "connecting") {
-      setStatus(c, { status: "connecting" });
-    }
+    setStatus(
+      c,
+      c.parked
+        ? { status: "disconnected", reason: "deferred" }
+        : { status: "connecting", attempt: 0 },
+    );
     const lifetime = new AbortController();
     c.lifetime = lifetime;
     c.gate = newGate();

package/src/client/core.ts

@@ -10,8 +10,9 @@ import { StatewireSendError } from "../types";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 
-export const LIVE_CONNECTION: StatewireClient.Connection = {
-  status: "live",
+export const CONNECTED_CONNECTION: StatewireClient.Connection = {
+  status: "connected",
+  degraded: false,
   reconnect: () => {},
 };
 
@@ -160,7 +161,7 @@ const recompute = (c: Core) => {
 };
 
 const getConnection = (c: Core): StatewireClient.Connection =>
-  c.value?.connection ?? LIVE_CONNECTION;
+  c.value?.connection ?? CONNECTED_CONNECTION;
 
 const flush = (c: Core, scheduled = false) => {
   if (!c.value) return;

package/src/client/session.ts

@@ -713,7 +713,8 @@ const pump = async (s: Session) => {
       if (buildLanes(s) === null) return;
       if (s.attach !== "attached" || !transport) {
         if (
-          transport?.connection.status === "idle" ||
+          (transport?.connection.status === "disconnected" &&
+            transport.connection.reason === "idle") ||
           (transport?.parked && s.pending.length > 0)
         ) {
           transport.connection.reconnect();

package/src/host/http.ts

@@ -16,6 +16,36 @@ const LEASE_HEADER = "Statewire-Lease";
 const VERSION_HEADER = "Statewire-Version";
 const VERSION = "1";
 const encoder = new TextEncoder();
+export const MAX_FRAME_BODY_BYTES = 8 * 1024 * 1024;
+
+const readFrameBody = async (request: Request): Promise<string | null> => {
+  const declared = request.headers.get("content-length");
+  if (declared !== null && Number(declared) > MAX_FRAME_BODY_BYTES) {
+    await request.body?.cancel("frame body too large").catch(() => {});
+    return null;
+  }
+  if (request.body === null) return "";
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > MAX_FRAME_BODY_BYTES) {
+      await reader.cancel("frame body too large").catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return new TextDecoder().decode(body);
+};
 
 const invalidClientIdReason = (clientId: string): string | null => {
   if (clientId === "") return "id must be non-empty";
@@ -176,9 +206,13 @@ const postStream = async (
 ): Promise<Response> => {
   const client = clientIdResponse(request);
   if ("response" in client) return client.response;
+  const raw = await readFrameBody(request);
+  if (raw === null) {
+    return Response.json({ detail: "frame body too large" }, { status: 413 });
+  }
   let body: unknown;
   try {
-    body = JSON.parse(await request.text());
+    body = JSON.parse(raw);
   } catch {
     return Response.json({ detail: "body must be JSON" }, { status: 400 });
   }
@@ -264,9 +298,13 @@ export const frames = async (
   if (h.disposed || h.finished !== null || rec === undefined || !live) {
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
+  const raw = await readFrameBody(request);
+  if (raw === null) {
+    return Response.json({ error: "frame body too large" }, { status: 413 });
+  }
   let frame: ParsedFrame;
   try {
-    frame = parseFrame(await request.text(), false);
+    frame = parseFrame(raw, false);
   } catch (error) {
     if (!(error instanceof Error) || error.name !== "StatewireViolation") {
       throw error;

package/src/host/socket.ts

@@ -53,6 +53,14 @@ export type Conn = {
   lease: string | null;
 };
 
+type PendingConn = {
+  socket: StatewireHostInternal.Socket;
+  open: boolean;
+  authorizing: boolean;
+  timer: ReturnType<typeof setTimeout> | null;
+  connection: StatewireHostInternal.SocketConnection | null;
+};
+
 // ─── frame parsing ──────────────────────────────────────
 
 const violation = (reason: string): never => {
@@ -247,11 +255,13 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
 
 export type SocketHostState = {
   heartbeatMs: number;
+  wsInitTimeoutMs: number;
   clientRecordLimit: number;
   finOnIdle: boolean;
   authorize: StatewireHostInternal.SocketHostOptions["authorize"];
   clients: Map<string, ClientRec>;
   conns: Set<Conn>;
+  pendingConns: Set<PendingConn>;
   pendingOps: WireOp[];
   pendingApplied: Map<string, number[]>;
   pendingCmds: Map<string, StatewireCmd[]>;
@@ -267,6 +277,7 @@ export type SocketHostState = {
   connect: (
     clientId: string,
     socket: StatewireHostInternal.Socket,
+    options?: StatewireHostInternal.SocketConnectOptions,
   ) => StatewireHostInternal.SocketConnection | null;
   finish: (fin: StatewireHost.Fin) => void;
   stream: (request: Request) => Promise<Response>;
@@ -667,6 +678,198 @@ const message = (h: SocketHostState, conn: Conn, data: string) => {
   }
 };
 
+const closePending = (
+  h: SocketHostState,
+  pending: PendingConn,
+  code?: number,
+  reason?: string,
+) => {
+  if (!pending.open) return;
+  pending.open = false;
+  h.pendingConns.delete(pending);
+  if (pending.timer !== null) clearTimeout(pending.timer);
+  try {
+    pending.socket.close(code, reason);
+  } catch {
+    /* peer already gone */
+  }
+};
+
+const sendPending = (pending: PendingConn, data: string): boolean => {
+  if (!pending.open) return false;
+  try {
+    pending.socket.send(data);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const rejectPendingAuthorization = (
+  h: SocketHostState,
+  pending: PendingConn,
+  error: unknown,
+) => {
+  const response = error instanceof Response ? error : null;
+  const unauthorized = response?.status === 401 || response?.status === 403;
+  const status = response?.status;
+  const message = unauthorized
+    ? "unauthorized"
+    : response?.statusText ||
+      (status === undefined ? "authorization failed" : `HTTP ${status}`);
+  sendPending(
+    pending,
+    JSON.stringify({
+      fin: {
+        reason: unauthorized ? "unauthorized" : "error",
+        message,
+        ...(status !== undefined && { status }),
+      },
+    }),
+  );
+  closePending(h, pending, unauthorized ? 1008 : 1011, message);
+};
+
+const normalizedHeaders = (
+  headers: Record<string, string>,
+): Record<string, string> => Object.fromEntries(new Headers(headers));
+
+const connectAuthorized = (
+  h: SocketHostState,
+  clientId: string,
+  socket: StatewireHostInternal.Socket,
+  options: StatewireHostInternal.SocketConnectOptions,
+): StatewireHostInternal.SocketConnection | null => {
+  const authorize = h.authorize;
+  if (authorize === undefined || options.authorized === true) {
+    const registration = register(
+      h,
+      clientId,
+      socket,
+      options.authorized === true,
+    );
+    return registration?.connection ?? null;
+  }
+  const refuse = (code: number, reason: string) => {
+    try {
+      socket.close(code, reason);
+    } catch {
+      /* peer already gone */
+    }
+    return null;
+  };
+  if (h.disposed) return refuse(1001, "disposed");
+  if (!CLIENT_ID_RE.test(clientId)) return refuse(1008, "invalid client id");
+  flush(h);
+  if (h.finished !== null) {
+    try {
+      socket.send(JSON.stringify({ fin: h.finished }));
+    } catch {
+      /* peer already gone */
+    }
+    return refuse(1000, "finished");
+  }
+  const pending: PendingConn = {
+    socket,
+    open: true,
+    authorizing: false,
+    timer: null,
+    connection: null,
+  };
+  h.pendingConns.add(pending);
+  pending.timer = setTimeout(
+    () =>
+      rejectPendingAuthorization(
+        h,
+        pending,
+        new Response(null, { status: 401 }),
+      ),
+    h.wsInitTimeoutMs,
+  );
+  (pending.timer as unknown as { unref?: () => void }).unref?.();
+  return {
+    clientId,
+    message: (data) => {
+      if (pending.connection !== null) {
+        pending.connection.message(data);
+        return;
+      }
+      if (!pending.open || h.disposed || h.finished !== null) return;
+      if (pending.authorizing) {
+        closePending(h, pending, 1008, "authorization pending");
+        return;
+      }
+      let frame: ParsedFrame;
+      try {
+        frame = parseFrame(data, true);
+      } catch (error) {
+        const reason = violationReason(error);
+        if (reason === null) throw error;
+        sendPending(
+          pending,
+          JSON.stringify({
+            fin: {
+              reason: "error",
+              message: `protocol violation: ${reason}`,
+            },
+          }),
+        );
+        closePending(h, pending, 1008, reason);
+        return;
+      }
+      if (frame.headers === null) {
+        rejectPendingAuthorization(
+          h,
+          pending,
+          new Response(null, { status: 401 }),
+        );
+        return;
+      }
+      let headers: Record<string, string>;
+      try {
+        headers = normalizedHeaders(frame.headers);
+      } catch {
+        sendPending(
+          pending,
+          JSON.stringify({
+            fin: {
+              reason: "error",
+              message: "protocol violation: malformed headers",
+            },
+          }),
+        );
+        closePending(h, pending, 1008, "malformed headers");
+        return;
+      }
+      pending.authorizing = true;
+      Promise.resolve()
+        .then(() => authorize({ headers }))
+        .then(() => {
+          if (!pending.open || h.disposed || h.finished !== null) return;
+          options.onAuthorized?.();
+          pending.open = false;
+          h.pendingConns.delete(pending);
+          if (pending.timer !== null) clearTimeout(pending.timer);
+          const registration = register(h, clientId, socket, true);
+          if (registration === null) return;
+          pending.connection = registration.connection;
+          if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
+          const admission = admitFrame(h, registration.rec, frame);
+          if (admission.type === "refused") {
+            sendTo(h, registration.conn, JSON.stringify(admission.syn));
+          }
+        })
+        .catch((error: unknown) => {
+          if (pending.open) rejectPendingAuthorization(h, pending, error);
+        });
+    },
+    close: () => {
+      if (pending.connection !== null) pending.connection.close();
+      else closePending(h, pending);
+    },
+  };
+};
+
 const gcClients = (h: SocketHostState) => {
   let excess = h.clients.size - h.clientRecordLimit;
   if (excess <= 0) return;
@@ -690,6 +893,7 @@ export const register = (
   h: SocketHostState,
   clientId: string,
   socket: StatewireHostInternal.Socket,
+  sawFrame = false,
 ): Registration | null => {
   const refuse = (code: number, reason: string) => {
     try {
@@ -732,7 +936,7 @@ export const register = (
     clientId,
     socket,
     open: true,
-    sawFrame: false,
+    sawFrame,
     lastSentAt: 0,
     lease: null,
   };
@@ -768,14 +972,18 @@ const connect = (
   h: SocketHostState,
   clientId: string,
   socket: StatewireHostInternal.Socket,
+  options: StatewireHostInternal.SocketConnectOptions = {},
 ): StatewireHostInternal.SocketConnection | null => {
-  const registration = register(h, clientId, socket);
-  return registration?.connection ?? null;
+  return connectAuthorized(h, clientId, socket, options);
 };
 
 const finish = (h: SocketHostState, fin: StatewireHost.Fin) => {
   if (h.finished !== null || h.disposed) return;
   h.finished = fin;
+  for (const pending of [...h.pendingConns]) {
+    sendPending(pending, JSON.stringify({ fin }));
+    closePending(h, pending, 1000, fin.reason);
+  }
   flush(h, fin);
 };
 
@@ -803,11 +1011,13 @@ const useSocketHost = (
   const [h] = useState((): SocketHostState => {
     const host: SocketHostState = {
       heartbeatMs: 15_000,
+      wsInitTimeoutMs: 5_000,
       clientRecordLimit: CLIENT_RECORD_LIMIT,
       finOnIdle: false,
       authorize: undefined,
       clients: new Map(),
       conns: new Set(),
+      pendingConns: new Set(),
       pendingOps: [],
       pendingApplied: new Map(),
       pendingCmds: new Map(),
@@ -823,7 +1033,8 @@ const useSocketHost = (
         host.flushScheduled = false;
         flush(host);
       }),
-      connect: (clientId, socket) => connect(host, clientId, socket),
+      connect: (clientId, socket, connectOptions) =>
+        connect(host, clientId, socket, connectOptions),
       finish: (fin) => finish(host, fin),
       stream: (request) => serveStream(host, request),
       frames: (request) => serveFrames(host, request),
@@ -831,6 +1042,7 @@ const useSocketHost = (
     return host;
   });
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
+  h.wsInitTimeoutMs = options?.wsInitTimeoutMs ?? 5_000;
   h.clientRecordLimit = options?.clientRecordLimit ?? CLIENT_RECORD_LIMIT;
   h.finOnIdle = options?.finOnIdle ?? false;
   h.authorize = options?.authorize;
@@ -862,8 +1074,10 @@ export const StatewireSocketHost = (
   const root = createTapRoot(SocketHostRoot);
   let disposed = false;
   return {
-    connect: (clientId, socket) =>
-      flushTapSync(() => root.getValue().connect(clientId, socket)),
+    connect: (clientId, socket, connectOptions) =>
+      flushTapSync(() =>
+        root.getValue().connect(clientId, socket, connectOptions),
+      ),
     stream: (request) => flushTapSync(() => root.getValue().stream(request)),
     frames: (request) => flushTapSync(() => root.getValue().frames(request)),
     finish: (fin) => flushTapSync(() => root.getValue().finish(fin)),