@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/foundation/net/index.js

@@ -1,14 +1,14 @@
 import { JitterStrategy, BackoffStrategy, shouldRetry, computeRetryDelay } from "../resilience/index.js";
-import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
-import { shallowRef, toValue, onMounted, watch, onScopeDispose } from "vue";
+import { t as toError } from "../../chunks/ToError-vXncXe19.js";
+import { shallowRef, toValue, onMounted, watch, onScopeDispose, unref } from "vue";
 const ConnectionState = {
   /** Refers to a first connection attempt in flight — nothing has been established yet. */
   Connecting: "connecting",
   /** Refers to an established connection that is passing traffic. */
   Open: "open",
-  /** Refers to a dropped connection with a retry pending or in flight — the distinction the wire ready-state cannot express. */
+  /** Refers to a dropped connection with a retry pending or in flight — what the wire ready-state cannot express. */
   Reconnecting: "reconnecting",
-  /** Refers to a connection that is down and not coming back — closed by the caller, unsupported, or out of retries. */
+  /** Refers to a connection down for good — closed by the caller, unsupported, or out of retries. */
   Closed: "closed"
 };
 const EventSourceReadyState = {
@@ -388,7 +388,9 @@ function createSocketClient(url, options = {}) {
     on("open", () => {
       scheduler.reset();
       setState(ConnectionState.Open);
+      if (closedByCaller || connection !== target) return;
       onOpen?.();
+      if (closedByCaller || connection !== target) return;
       flushQueue(target);
       startHeartbeat();
     });
@@ -793,7 +795,7 @@ function usePolling(fn, options = {}) {
   function build() {
     teardown();
     const current = toValue(options);
-    const next = createPoller(() => toValue(fn)(), {
+    const next = createPoller(() => unref(fn)(), {
       ...current,
       intervalMs: current.intervalMs,
       onStateChange: (value) => {

package/dist/foundation/net/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/net/ConnectionState.ts","../../../src/foundation/net/Reconnect.ts","../../../src/foundation/net/CreateEventStream.ts","../../../src/foundation/net/UseEventStream.ts","../../../src/foundation/net/CreateSocketClient.ts","../../../src/foundation/net/UseSocket.ts","../../../src/foundation/net/Liveness.ts","../../../src/foundation/net/CreatePoller.ts","../../../src/foundation/net/UsePolling.ts"],"sourcesContent":["// The connection vocabulary shared by every long-lived transport in this slice, plus the two sets of WIRE\n// ready-state numbers the platform uses.\n//\n// WHY A SEPARATE STATE FROM THE WIRE NUMBER: `EventSource.readyState` and `WebSocket.readyState` are both\n// small integers, they overlap numerically, and they mean DIFFERENT things — `2` is `CLOSED` for an\n// `EventSource` and `CLOSING` for a `WebSocket`. Worse, neither can express \"the socket is down and this\n// wrapper is waiting out a backoff delay before the next attempt\", which is the state a UI most wants to\n// render (\"reconnecting…\"). `EventSource` reports that situation as `CONNECTING`, indistinguishable from the\n// very first connect. So consumers get this string union and never see a raw integer.\n//\n// WHY THE NUMBERS ARE SPELLED OUT HERE RATHER THAN READ OFF THE GLOBALS: `WebSocket.OPEN` is a static member\n// of a class that does not exist under SSR, in a node test, or in a browser with the API disabled. Reading it\n// at module scope is a `ReferenceError` at import time — the exact failure this slice promises never to have.\n// The values are fixed by the WHATWG spec and cannot drift, so hardcoding them is both safe and the only\n// SSR-correct option.\n\n/** Describes a long-lived connection's state, uniformly across SSE, WebSocket, and polling. */\nexport const ConnectionState = {\n  /** Refers to a first connection attempt in flight — nothing has been established yet. */\n  Connecting: 'connecting',\n  /** Refers to an established connection that is passing traffic. */\n  Open: 'open',\n  /** Refers to a dropped connection with a retry pending or in flight — the distinction the wire ready-state cannot express. */\n  Reconnecting: 'reconnecting',\n  /** Refers to a connection that is down and not coming back — closed by the caller, unsupported, or out of retries. */\n  Closed: 'closed',\n} as const;\n\nexport type ConnectionState = (typeof ConnectionState)[keyof typeof ConnectionState];\n\n/**\n * Provides the `EventSource.readyState` values from the WHATWG spec. Note `Closed` here is TERMINAL — the\n * browser only reports it once it has abandoned its own reconnection, which is precisely the signal\n * `createEventStream` waits for before taking the retry over.\n */\nexport const EventSourceReadyState = {\n  /** Refers to the connection being established — including the browser's OWN automatic reconnection. */\n  Connecting: 0,\n  /** Refers to an open, streaming connection. */\n  Open: 1,\n  /** Refers to a connection the browser will not retry: a fatal error, or an explicit `close()`. */\n  Closed: 2,\n} as const;\n\n/** Provides the `WebSocket.readyState` values from the WHATWG spec — note `Closing` occupies `2`, where `EventSource` puts `Closed`. */\nexport const SocketReadyState = {\n  /** Refers to a handshake in progress; `send()` throws here, which is why this slice queues instead. */\n  Connecting: 0,\n  /** Refers to an open socket ready for frames. */\n  Open: 1,\n  /** Refers to a close handshake in progress; frames sent now are discarded. */\n  Closing: 2,\n  /** Refers to a closed or failed socket. */\n  Closed: 3,\n} as const;\n","// The one place in this slice that decides WHEN to reconnect — and it decides nothing itself. Every delay\n// comes from `foundation/resilience`'s `computeRetryDelay`, and every \"should we even try again\" answer comes\n// from its `shouldRetry`. That slice owns retry POLICY (growth, jitter, cap, attempt budget); this scheduler\n// owns only the timer and the attempt counter. Changing how backoff behaves means editing `resilience`, never\n// this file — the same split `foundation/async`'s `retryAsync` follows.\n//\n// WHY A SHARED SCHEDULER RATHER THAN A `setTimeout` IN EACH TRANSPORT: both `createEventStream` and\n// `createSocketClient` need identical bookkeeping — the attempt count, the previous delay (decorrelated\n// jitter is a function of it), a cancellable handle, and a reset on success. Written twice they drift, and\n// the half that drifts is always the reset: a client that forgets to zero its counter after a successful\n// reconnect spends the rest of the session waiting the maximum delay after every blip.\n//\n// THE STACKING GUARD IS THE LOAD-BEARING PART. `schedule()` refuses to arm a second timer while one is\n// pending. Both transports can be told about the same failure through more than one path — a WebSocket that\n// errors then closes fires BOTH handlers, and an `EventSource` can report an error while a retry is already\n// waiting — and without this guard each path arms its own timer, so a single drop produces two connections.\n// Two sockets both \"work\", which is why this bug survives review: the symptom is duplicated messages and a\n// doubled server load, not an obvious failure.\n//\n// `shouldRetry` IS QUERIED WITH STATUS `0`. It grades HTTP statuses, and a dropped stream has none — `0` is\n// exactly the \"network / unknown\" code `resilience` reserves for that, and it is a member of\n// `DefaultTransientStatuses`, so a default policy treats a drop as transient. A caller who genuinely wants a\n// stream that never reconnects passes `retry: false` rather than fighting the status vocabulary.\n\nimport { BackoffStrategy, JitterStrategy, computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\n/** The status handed to `shouldRetry` for a transport-level drop — `resilience`'s \"network / unknown\" code. */\nconst TransportFailureStatus = 0;\n\n/**\n * Provides the default reconnect policy for a long-lived connection: unbounded attempts, exponential growth\n * from 1s, capped at 30s, with equal jitter.\n *\n * Differs from `DefaultRetryPolicy` in two ways that matter for a STREAM rather than a request. Attempts are\n * unbounded because a stream's failure mode is a server restart or a laptop lid, and giving up after two\n * tries leaves a dead page that no amount of waiting fixes — a request can surface an error to the caller,\n * a background stream has nobody to tell. And the jitter is `Equal`, not `Full`: full jitter can pick a delay\n * near zero, so a single client reconnecting to a flapping server hammers it immediately, whereas equal\n * jitter guarantees a floor of half the computed delay while still spreading a whole fleet apart.\n */\nexport const DefaultReconnectPolicy: RetryPolicy = {\n  maxRetries: Number.POSITIVE_INFINITY,\n  backoff: BackoffStrategy.Exponential,\n  baseDelayMs: 1_000,\n  maxDelayMs: 30_000,\n  jitter: JitterStrategy.Equal,\n};\n\n/** Configures a {@link createReconnectScheduler} instance. Every member is optional. */\nexport interface ReconnectSchedulerOptions {\n  /** The retry policy driving the delays, or `false` to disable reconnection entirely. Default {@link DefaultReconnectPolicy}. */\n  readonly retry?: RetryPolicy | false;\n\n  /** The randomness feeding jitter — injectable so a test can pin an exact delay. Default `Math.random`. */\n  readonly random?: () => number;\n\n  /** Fires when an attempt is armed, before the wait — the seam for logging \"reconnecting in 4s (attempt 3)\". */\n  readonly onScheduled?: (attempt: number, delayMs: number) => void;\n}\n\n/** Schedules reconnection attempts with `foundation/resilience` backoff, at most one in flight. */\nexport interface ReconnectScheduler {\n  /** The number of consecutive attempts armed since the last {@link ReconnectScheduler.reset}. */\n  readonly attempts: number;\n\n  /** The delay (ms) of the attempt currently waiting, or `undefined` when none is pending. */\n  readonly pendingDelayMs: number | undefined;\n\n  /**\n   * Arms the next attempt after a `resilience`-computed delay.\n   *\n   * @param run - Invoked once the delay elapses. Not invoked if {@link ReconnectScheduler.cancel} lands first.\n   * @returns `true` when an attempt is pending afterwards — including when one was ALREADY pending and this\n   * call was absorbed by the stacking guard; `false` when reconnection is disabled or the budget is spent.\n   */\n  schedule(run: () => void): boolean;\n\n  /** Zeroes the attempt counter after a successful connection, so the next drop starts from the base delay again. */\n  reset(): void;\n\n  /** Cancels a pending attempt and clears its timer. Idempotent, and safe when nothing is pending. */\n  cancel(): void;\n}\n\n/**\n * Creates the reconnect scheduler shared by this slice's transports — one pending attempt at most, delays\n * and budget delegated wholly to `foundation/resilience`.\n *\n * @param options - The retry policy, randomness source, and scheduling hook.\n * @returns A scheduler; call `cancel()` when the owning transport closes, or its timer outlives it.\n */\nexport function createReconnectScheduler(options: ReconnectSchedulerOptions = {}): ReconnectScheduler {\n  const { retry = DefaultReconnectPolicy, random = Math.random, onScheduled } = options;\n\n  let attempts = 0;\n  let previousDelayMs = 0;\n  let pendingDelayMs: number | undefined;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  return {\n    get attempts() {\n      return attempts;\n    },\n\n    get pendingDelayMs() {\n      return pendingDelayMs;\n    },\n\n    schedule(run: () => void): boolean {\n      if (retry === false) return false;\n      // The stacking guard — see this file's header. Reporting `true` is correct: an attempt IS pending.\n      if (timer !== undefined) return true;\n      if (!shouldRetry(retry, attempts, TransportFailureStatus)) return false;\n\n      const attempt = attempts + 1;\n      const delayMs = computeRetryDelay(retry, attempt, previousDelayMs, random);\n\n      attempts = attempt;\n      previousDelayMs = delayMs;\n      pendingDelayMs = delayMs;\n\n      timer = setTimeout(() => {\n        // Blank both handles BEFORE running, so a `run` that fails and immediately re-schedules is not\n        // rejected by the stacking guard against its own already-fired timer.\n        timer = undefined;\n        pendingDelayMs = undefined;\n        run();\n      }, delayMs);\n\n      onScheduled?.(attempt, delayMs);\n      return true;\n    },\n\n    reset(): void {\n      attempts = 0;\n      previousDelayMs = 0;\n    },\n\n    cancel(): void {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      pendingDelayMs = undefined;\n    },\n  };\n}\n","// Server-Sent Events with typed named-event handlers and a reconnect that does NOT fight the browser's own.\n//\n// THE DOUBLE-RECONNECT TRAP, which is the whole reason this wrapper is subtle. `EventSource` already\n// reconnects by itself: on an ordinary drop the browser sets `readyState` back to `CONNECTING`, waits out its\n// own delay (the server can set it with a `retry:` field), and re-opens the SAME `EventSource` object. It\n// fires `error` while doing so. So the naive wrapper — \"on error, make a new `EventSource`\" — ends up with\n// TWO live connections for one drop: the browser's retry on the old object, plus the wrapper's new one. Each\n// subsequent drop doubles again. The symptom is duplicated events and a server that sees connection counts\n// climb, never a thrown error, which is why this ships to production so often.\n//\n// HOW THIS AVOIDS IT: the `error` handler branches on `source.readyState`, which is the only signal that\n// distinguishes the two cases.\n//   - `CONNECTING` (0) — the browser owns this retry and is already running it. The wrapper arms NO timer and\n//     builds NO `EventSource`; it only reports the error with `owner: 'browser'` and shows `reconnecting`.\n//   - `CLOSED` (2) — the browser has given up for good (a non-2xx response, a wrong content type, a bad\n//     CORS preflight; none of these are retried by the spec). Only here does the wrapper take over: it\n//     detaches its listeners, closes the dead object, and schedules a fresh connect on `resilience` backoff.\n// The two owners are therefore mutually exclusive by construction, and `ReconnectOwner` reports which one is\n// acting so a consumer can log it. The scheduler's own stacking guard backstops the invariant.\n//\n// WHY THE FATAL CASE STILL RETRIES AT ALL: the browser abandons the stream on a 502 from a proxy that is\n// restarting, or on the 401 that follows an expired token — both routinely fix themselves. Leaving the page\n// permanently dead because a gateway blinked is worse than a bounded reconnect, and a caller who disagrees\n// passes `retry: false`.\n//\n// NAMED EVENTS ARE A MAP, NOT A SWITCH. A server sending `event: order-updated` delivers to a listener\n// registered for that exact name, and NOT to `onmessage` — a detail that silently breaks the \"I subscribed to\n// onMessage but receive nothing\" case. `options.events` registers one real listener per key, and the generic\n// parameter types each payload independently.\n\nimport { toError } from '../errors';\nimport type { RetryPolicy } from '../resilience';\n\nimport { ConnectionState, EventSourceReadyState } from './ConnectionState';\nimport { createReconnectScheduler } from './Reconnect';\n\n/**\n * The minimal `EventSource` surface this wrapper drives. Narrow on purpose: a test double or a polyfill can\n * satisfy it in a few lines, and the real `EventSource` satisfies it structurally.\n */\nexport interface EventStreamSource {\n  /** The wire ready-state — see {@link EventSourceReadyState}. The branch the double-reconnect guard turns on. */\n  readonly readyState: number;\n\n  /** Closes the connection and stops the browser's own reconnection. */\n  close(): void;\n\n  /** Registers a listener for `open`, `error`, `message`, or a server-named event. */\n  addEventListener(type: string, listener: (event: Event) => void): void;\n\n  /** Removes a previously registered listener. */\n  removeEventListener(type: string, listener: (event: Event) => void): void;\n}\n\n/** Builds the underlying source — injectable so tests and polyfills need no global. */\nexport type EventStreamSourceFactory = (url: string, init: { withCredentials: boolean }) => EventStreamSource;\n\n/** Identifies who is retrying a broken stream — the guard against reconnecting on top of the browser. */\nexport const ReconnectOwner = {\n  /** Refers to the browser's own `EventSource` retry already being in flight; this wrapper stands down. */\n  Browser: 'browser',\n  /** Refers to the browser having given up, with this wrapper's `resilience`-scheduled retry pending. */\n  Wrapper: 'wrapper',\n  /** Refers to nobody retrying — reconnection is disabled, the attempt budget is spent, or the stream was closed. */\n  None: 'none',\n} as const;\n\nexport type ReconnectOwner = (typeof ReconnectOwner)[keyof typeof ReconnectOwner];\n\n/** Describes a stream failure — above all, who (if anyone) is going to do something about it. */\nexport interface EventStreamErrorContext {\n  /** Whoever is retrying this failure. See {@link ReconnectOwner}. */\n  readonly owner: ReconnectOwner;\n\n  /** The wrapper's consecutive attempt count; `0` while the browser owns the retry, since the wrapper has armed nothing. */\n  readonly attempt: number;\n\n  /** The connection state after this failure was handled. */\n  readonly state: ConnectionState;\n}\n\n/**\n * Maps each server event name to the payload it carries — the generic every handler in\n * {@link EventStreamOptions.events} is typed from.\n */\nexport type EventStreamPayloads = Record<string, unknown>;\n\n/** Maps event names to their handlers, each typed by that event's payload. */\nexport type EventStreamHandlers<TEvents extends EventStreamPayloads> = {\n  readonly [K in keyof TEvents & string]?: (data: TEvents[K], event: MessageEvent<string>) => void;\n};\n\n/** Configures a {@link createEventStream} call. Every member is optional. */\nexport interface EventStreamOptions<TEvents extends EventStreamPayloads = EventStreamPayloads> {\n  /** Handlers for server-NAMED events (`event: order-updated`). These never reach {@link EventStreamOptions.onMessage}. */\n  readonly events?: EventStreamHandlers<TEvents>;\n\n  /** Handles unnamed events only — the default `message` type. */\n  readonly onMessage?: (data: unknown, event: MessageEvent<string>) => void;\n\n  /** Fires each time the connection opens, including after every reconnect. */\n  readonly onOpen?: () => void;\n\n  /** Fires on every failure, with the context saying who is retrying it. */\n  readonly onError?: (error: Error, context: EventStreamErrorContext) => void;\n\n  /** Fires on every connection-state transition — the seam for a \"reconnecting…\" indicator. */\n  readonly onStateChange?: (state: ConnectionState) => void;\n\n  /** Whether to send credentials cross-origin. Default `false`. */\n  readonly withCredentials?: boolean;\n\n  /**\n   * Decodes a frame's `data` text. Default: `JSON.parse`, falling back to the RAW STRING when the text is not\n   * JSON — SSE carries text, and plain-text frames and sentinels like `[DONE]` are common enough that\n   * throwing on them would be hostile. Supply this to be strict, or to decode another format.\n   */\n  readonly parse?: (raw: string) => unknown;\n\n  /** The reconnect policy for failures the browser abandons, or `false` to never reconnect. Default `DefaultReconnectPolicy`. */\n  readonly retry?: RetryPolicy | false;\n\n  /** The randomness feeding backoff jitter — injectable for deterministic tests. Default `Math.random`. */\n  readonly random?: () => number;\n\n  /** The source factory. Default constructs a global `EventSource`; inject a double in tests. */\n  readonly eventSource?: EventStreamSourceFactory;\n}\n\n/** Controls a live Server-Sent Events subscription. */\nexport interface EventStream {\n  /** The current connection state — `reconnecting` covers both the browser's retry and this wrapper's. */\n  readonly readyState: ConnectionState;\n\n  /** Whether an `EventSource` implementation was available at all; `false` under SSR, where the stream is inert. */\n  readonly supported: boolean;\n\n  /** The wrapper's consecutive reconnect attempts, zeroed on every successful open. */\n  readonly attempts: number;\n\n  /** Closes the stream, cancels any pending reconnect, and detaches every listener. Idempotent; suppresses all further reconnection. */\n  close(): void;\n}\n\n/** Decodes frame text as JSON, falling back to the raw string — see {@link EventStreamOptions.parse}. */\nfunction parseFrame(raw: string): unknown {\n  try {\n    return JSON.parse(raw) as unknown;\n  } catch {\n    return raw;\n  }\n}\n\n/** Reads a listener's event as a message frame; non-string `data` is coerced so a double can pass plain objects. */\nfunction frameTextOf(event: Event): { text: string; message: MessageEvent<string> } {\n  const message = event as MessageEvent<string>;\n  const data: unknown = message.data;\n  return { text: typeof data === 'string' ? data : String(data), message };\n}\n\n/** Resolves the source factory: the injected one, else the global `EventSource`, else `undefined` (SSR / unsupported). */\nfunction resolveSourceFactory(injected?: EventStreamSourceFactory): EventStreamSourceFactory | undefined {\n  if (injected !== undefined) return injected;\n  if (typeof EventSource === 'undefined') return undefined;\n  return (url, init) => new EventSource(url, init);\n}\n\n/**\n * Opens a Server-Sent Events stream with typed named-event handlers and a reconnect that defers to the\n * browser's own — see this file's header for how the double-reconnect is avoided.\n *\n * Never throws, at import time or at call time. Where `EventSource` does not exist (SSR, a locked-down\n * runtime) the returned stream reports `supported: false` and state `closed`, and every method is a no-op —\n * a defined answer rather than an exception a render cannot catch.\n *\n * @typeParam TEvents - Maps each server event name to its payload type.\n * @param url - The stream endpoint.\n * @param options - Handlers, retry policy, parsing, and injection seams.\n * @returns The stream handle. ALWAYS call `close()` when done — an open `EventSource` survives navigation\n * within an SPA and keeps both the connection and every captured handler alive.\n */\nexport function createEventStream<TEvents extends EventStreamPayloads = EventStreamPayloads>(\n  url: string,\n  options: EventStreamOptions<TEvents> = {},\n): EventStream {\n  const {\n    events,\n    onMessage,\n    onOpen,\n    onError,\n    onStateChange,\n    withCredentials = false,\n    parse = parseFrame,\n    retry,\n    random,\n    eventSource,\n  } = options;\n\n  const factory = resolveSourceFactory(eventSource);\n  const scheduler = createReconnectScheduler({ retry, random });\n\n  let state: ConnectionState = ConnectionState.Connecting;\n  let source: EventStreamSource | undefined;\n  let detach: (() => void) | undefined;\n  let closed = false;\n\n  /** Publishes a state transition, skipping no-op repeats so a consumer's `onStateChange` is not spammed. */\n  const setState = (next: ConnectionState): void => {\n    if (state === next) return;\n    state = next;\n    onStateChange?.(next);\n  };\n\n  /** Reports a failure, tolerating a throwing consumer handler — a bad listener must not break the transport. */\n  const report = (error: unknown, owner: ReconnectOwner, attempt: number): void => {\n    try {\n      onError?.(toError(error), { owner, attempt, state });\n    } catch {\n      // Swallowed by contract: this runs from a DOM event handler, where a throw is unhandleable noise.\n    }\n  };\n\n  /** Binds every listener to a source and returns the matching detach — one closure so no listener can be missed. */\n  const bind = (target: EventStreamSource): (() => void) => {\n    const bound: [type: string, listener: (event: Event) => void][] = [];\n\n    /** Registers a listener and records it for the paired detach. */\n    const on = (type: string, listener: (event: Event) => void): void => {\n      target.addEventListener(type, listener);\n      bound.push([type, listener]);\n    };\n\n    on('open', () => {\n      // A successful open zeroes the attempt counter — otherwise a long-lived stream that blipped once\n      // spends the rest of the session starting from the maximum delay.\n      scheduler.reset();\n      setState(ConnectionState.Open);\n      onOpen?.();\n    });\n\n    // The `error` event itself carries nothing useful — the spec gives it no reason, no status, no body.\n    // Everything actionable is in `readyState`, which is why only the source is passed on.\n    on('error', () => handleError(target));\n\n    if (onMessage !== undefined) {\n      on('message', (event) => {\n        const { text, message } = frameTextOf(event);\n        onMessage(parse(text), message);\n      });\n    }\n\n    for (const name of Object.keys(events ?? {})) {\n      const handler = (events as Record<string, ((data: unknown, event: MessageEvent<string>) => void) | undefined>)[\n        name\n      ];\n      if (handler === undefined) continue;\n      on(name, (event) => {\n        const { text, message } = frameTextOf(event);\n        handler(parse(text), message);\n      });\n    }\n\n    return () => {\n      for (const entry of bound) target.removeEventListener(entry[0], entry[1]);\n      bound.length = 0;\n    };\n  };\n\n  /** Opens a source and binds it; a constructor throw (a malformed URL) is reported, not propagated. */\n  const connect = (): void => {\n    if (closed || factory === undefined) return;\n\n    setState(scheduler.attempts === 0 ? ConnectionState.Connecting : ConnectionState.Reconnecting);\n\n    let opened: EventStreamSource;\n    try {\n      opened = factory(url, { withCredentials });\n    } catch (error) {\n      const scheduled = scheduler.schedule(connect);\n      setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n      report(error, scheduled ? ReconnectOwner.Wrapper : ReconnectOwner.None, scheduler.attempts);\n      return;\n    }\n\n    source = opened;\n    detach = bind(opened);\n  };\n\n  /** The double-reconnect guard itself: branch on the wire ready-state, and never retry what the browser is already retrying. */\n  function handleError(target: EventStreamSource): void {\n    if (closed) return;\n\n    // The browser is mid-reconnect on this very object. Arming anything here is the duplicate-connection bug.\n    if (target.readyState === EventSourceReadyState.Connecting) {\n      setState(ConnectionState.Reconnecting);\n      report(new Error(`The event stream to ${url} dropped; the browser is reconnecting.`), ReconnectOwner.Browser, 0);\n      return;\n    }\n\n    // `CLOSED` — the browser will do nothing further. Tear the dead object down completely before replacing\n    // it: an un-detached listener on a closed source still pins every closure it captured.\n    detach?.();\n    detach = undefined;\n    target.close();\n    source = undefined;\n\n    const scheduled = scheduler.schedule(connect);\n    setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n    report(\n      new Error(`The event stream to ${url} failed and the browser stopped retrying.`),\n      scheduled ? ReconnectOwner.Wrapper : ReconnectOwner.None,\n      scheduler.attempts,\n    );\n  }\n\n  if (factory === undefined) {\n    // Unsupported: a defined, inert answer. No throw, no listeners, no timers.\n    state = ConnectionState.Closed;\n    return {\n      get readyState() {\n        return state;\n      },\n      supported: false,\n      get attempts() {\n        return 0;\n      },\n      close: () => undefined,\n    };\n  }\n\n  connect();\n\n  return {\n    get readyState() {\n      return state;\n    },\n    supported: true,\n    get attempts() {\n      return scheduler.attempts;\n    },\n    close(): void {\n      if (closed) return;\n      closed = true;\n      scheduler.cancel();\n      detach?.();\n      detach = undefined;\n      source?.close();\n      source = undefined;\n      setState(ConnectionState.Closed);\n    },\n  };\n}\n","// Vue binding for `createEventStream` — one stream per scope, closed when the scope is disposed.\n//\n// THE LIFETIME RULE THIS ENFORCES: an `EventSource` is a live HTTP connection that outlives the component\n// that opened it. Nothing about unmounting a tree closes it, so a route change away from a page holding an\n// un-closed stream leaves the connection open, the handlers subscribed, and the reconnect timer armed — and\n// navigating back opens a SECOND one. Binding the stream to `onMounted` / `onScopeDispose` makes the teardown\n// automatic.\n//\n// OPENED FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `createEventStream` resolves `EventSource` inside\n// the call, and an immediate watcher also runs during a server render. `onMounted` is client-only by\n// construction, so the SSR pass reports `closed` / `supported: true` and the stream opens at hydration.\n//\n// HANDLERS ARE READ THROUGH `toValue` AT CALL TIME, the Vue counterpart of the original's handlers-in-a-ref.\n// A component's `setup` runs once, so a plain options object is already stable — but a caller that wants\n// genuinely live handlers can pass a ref or getter and every callback re-reads it per event, with the stream\n// itself staying put.\n//\n// OPTIONS ARE READ ONCE, when the stream opens. Changing `retry`, `events`, or `withCredentials` after mount\n// does NOT rebuild the stream; only `url` does. Options are configuration, not state — a consumer that must\n// genuinely swap them at runtime should remount with a `key`. This mirrors `useSyncChannel` in\n// `foundation/sync`.\n//\n// A `null` URL MEANS \"NOT YET\", not \"broken\" — the shape every real app needs while it waits for a token or a\n// route param. No stream is opened, and the state reads `closed`.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { ConnectionState } from './ConnectionState';\nimport {\n  createEventStream,\n  type EventStream,\n  type EventStreamOptions,\n  type EventStreamPayloads,\n} from './CreateEventStream';\n\n/** The live view a scope gets over its stream. */\nexport interface EventStreamHandle {\n  /** The current connection state, updating on every transition. */\n  readonly readyState: Readonly<ShallowRef<ConnectionState>>;\n\n  /** Whether `EventSource` exists in this runtime; `false` under SSR and in a locked-down browser. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /** Closes the stream early. The scope-disposal cleanup calls it anyway. */\n  readonly close: () => void;\n}\n\n/**\n * Opens a Server-Sent Events stream for the lifetime of the scope.\n *\n * The stream is closed when the scope is disposed and re-opened whenever `url` changes. Pass `null` to hold\n * off connecting (waiting for auth, a route param, a feature flag) — a ref or getter is how that flips.\n *\n * @typeParam TEvents - Maps each server event name to its payload type.\n * @param url - The stream endpoint, or `null` to stay disconnected.\n * @param options - Handlers and configuration, read once when the stream opens; handler callbacks are re-read\n *   per event, so a ref or getter keeps them live.\n * @returns The connection state, support flag, and `close`.\n */\nexport function useEventStream<TEvents extends EventStreamPayloads = EventStreamPayloads>(\n  url: MaybeRefOrGetter<string | null>,\n  options: MaybeRefOrGetter<EventStreamOptions<TEvents>> = {},\n): EventStreamHandle {\n  const readyState = shallowRef<ConnectionState>(\n    toValue(url) === null ? ConnectionState.Closed : ConnectionState.Connecting,\n  );\n  const supported = shallowRef(true);\n\n  let stream: EventStream | null = null;\n\n  function teardown(): void {\n    stream?.close();\n    stream = null;\n  }\n\n  function open(): void {\n    teardown();\n\n    const endpoint = toValue(url);\n    if (endpoint === null) {\n      readyState.value = ConnectionState.Closed;\n      return;\n    }\n\n    const current = toValue(options);\n    const next = createEventStream<TEvents>(endpoint, {\n      ...current,\n      // Every consumer callback is re-read through `toValue` at call time, which is what lets the watcher\n      // depend on `url` alone. `onStateChange` is additionally intercepted to drive this scope's own state.\n      onStateChange: (state) => {\n        readyState.value = state;\n        toValue(options).onStateChange?.(state);\n      },\n      onOpen: () => toValue(options).onOpen?.(),\n      onError: (error, context) => toValue(options).onError?.(error, context),\n      onMessage: (data, event) => toValue(options).onMessage?.(data, event),\n    });\n\n    stream = next;\n    supported.value = next.supported;\n    readyState.value = next.readyState;\n  }\n\n  onMounted(open);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `EventSource` is absent.\n  watch(() => toValue(url), open);\n  onScopeDispose(teardown);\n\n  const close = (): void => {\n    stream?.close();\n  };\n\n  return { readyState, supported, close };\n}\n","// A WebSocket client that fixes the three bugs every hand-rolled one has: dropped early sends, an\n// intentional close that reconnects anyway, and a half-open socket nobody notices.\n//\n// (1) MESSAGES SENT WHILE `CONNECTING` ARE LOST. A `WebSocket` is not usable the moment it is constructed —\n// the handshake takes a round trip, and `send()` during `CONNECTING` throws `InvalidStateError`. The bug is\n// not the throw; it is that the throw happens in code that looks obviously correct (`const s =\n// createSocket(); s.send(hello)`) and disappears on a fast local connection, so it ships. This client QUEUES\n// anything sent before `OPEN` and flushes it, in order, on open — the same queue that covers sends during a\n// reconnect, when the socket is `CONNECTING` again for seconds at a time.\n//\n// The queue is BOUNDED (`queueLimit`, default 100) and drops the OLDEST frame when full. Unbounded is not an\n// option: a tab left open through an hour-long outage would otherwise accumulate every frame the app ever\n// tried to send and hand the server all of them at once on reconnect. Oldest-first is the right end to drop\n// for the state-update traffic sockets usually carry, where the newest frame supersedes the ones behind it —\n// a caller whose messages are commands rather than state should keep `queueLimit` small and watch\n// `queuedCount`.\n//\n// (2) AN INTENTIONAL `close()` MUST NOT RECONNECT. `onclose` fires for a network drop and for a deliberate\n// close identically, so a reconnect handler wired to it fights every logout, unmount, and navigation — the\n// socket keeps coming back, usually with the OLD credentials. A single `closedByCaller` flag, set before the\n// close is requested, is the whole fix; every reconnect path checks it.\n//\n// (3) A HALF-OPEN SOCKET REPORTS `OPEN` FOREVER. When a peer vanishes without a close frame — a laptop lid, a\n// dropped NAT entry, a killed load balancer — TCP has nothing to report, so `onclose` never fires and\n// `readyState` stays `OPEN`. The connection is dead and the app cannot tell. The only detector is an\n// application-level heartbeat: send a ping, require traffic back within a deadline, treat silence as death\n// and reconnect. Note the ping MUST be application-level — the WebSocket protocol has real ping/pong frames,\n// but browsers expose no API to send one, so a server-side-only heartbeat cannot be observed from here.\n//\n// ANY INBOUND FRAME CLEARS THE PONG DEADLINE, not just a frame matching some pong shape. A socket delivering\n// data is alive by definition, so requiring a specific reply would kill healthy busy connections whose pong\n// is merely queued behind other traffic. This also means a server needs no pong support at all for the\n// heartbeat to be useful on a chatty socket.\n//\n// All reconnect delays come from `Reconnect.ts`, hence from `foundation/resilience`. None are computed here.\n\nimport { toError } from '../errors';\nimport type { RetryPolicy } from '../resilience';\n\nimport { ConnectionState, SocketReadyState } from './ConnectionState';\nimport { createReconnectScheduler } from './Reconnect';\n\n/** The default cap on frames buffered while the socket is not open. */\nconst DefaultQueueLimit = 100;\n\n/** The default ping frame — an application-level heartbeat, since browsers cannot send protocol pings. */\nconst DefaultPingFrame = (): string => JSON.stringify({ type: 'ping' });\n\n/**\n * The minimal `WebSocket` surface this client drives. Narrow on purpose: a test double satisfies it in a few\n * lines, and the real `WebSocket` satisfies it structurally.\n */\nexport interface SocketConnection {\n  /** The wire ready-state — see {@link SocketReadyState}. Gates every send. */\n  readonly readyState: number;\n\n  /** Sends one text frame. Throws while `CONNECTING`, which is exactly what the queue exists to prevent. */\n  send(data: string): void;\n\n  /** Starts the close handshake. */\n  close(code?: number, reason?: string): void;\n\n  /** Registers a listener for `open`, `close`, `error`, or `message`. */\n  addEventListener(type: string, listener: (event: Event) => void): void;\n\n  /** Removes a previously registered listener. */\n  removeEventListener(type: string, listener: (event: Event) => void): void;\n}\n\n/** Builds the underlying socket — injectable so tests and polyfills need no global. */\nexport type SocketFactory = (url: string, protocols?: string | readonly string[]) => SocketConnection;\n\n/** Configures the liveness heartbeat that detects a half-open socket. */\nexport interface SocketHeartbeatOptions {\n  /** The interval (ms) between pings. */\n  readonly intervalMs: number;\n\n  /** The silence (ms) tolerated after a ping before the socket is declared dead and reconnected. Default: the interval. */\n  readonly timeoutMs?: number;\n\n  /** Builds the ping frame. Default `{\"type\":\"ping\"}`. Return the exact text your server expects. */\n  readonly ping?: () => string;\n}\n\n/** Configures a {@link createSocketClient} call. Every member is optional. */\nexport interface SocketClientOptions<TIn = unknown, TOut = unknown> {\n  /** The subprotocols offered during the handshake. */\n  readonly protocols?: string | readonly string[];\n\n  /** Receives every decoded inbound message. Frames that fail to decode go to {@link SocketClientOptions.onError} instead. */\n  readonly onMessage?: (message: TIn, event: MessageEvent) => void;\n\n  /** Fires each time the socket opens, including after every reconnect and BEFORE the queue is flushed. */\n  readonly onOpen?: () => void;\n\n  /** Fires on every close, with `wasClean` distinguishing a handshake close from a drop. */\n  readonly onClose?: (event: CloseEvent) => void;\n\n  /** Fires on a socket error, a decode failure, or a send that the transport rejected. */\n  readonly onError?: (error: Error) => void;\n\n  /** Fires on every connection-state transition — the seam for a \"reconnecting…\" indicator. */\n  readonly onStateChange?: (state: ConnectionState) => void;\n\n  /** Encodes an outbound message. Default `JSON.stringify`. */\n  readonly serialize?: (message: TOut) => string;\n\n  /** Decodes an inbound frame. Default `JSON.parse`. A throw here is reported, and the frame is dropped. */\n  readonly deserialize?: (raw: string) => TIn;\n\n  /** The reconnect policy, or `false` to never reconnect. Default `DefaultReconnectPolicy`. */\n  readonly retry?: RetryPolicy | false;\n\n  /** The half-open detector. Omit to disable heartbeating entirely. */\n  readonly heartbeat?: SocketHeartbeatOptions;\n\n  /** The cap on frames buffered while not open; the oldest is dropped when full. Default `100`. */\n  readonly queueLimit?: number;\n\n  /** The randomness feeding backoff jitter — injectable for deterministic tests. Default `Math.random`. */\n  readonly random?: () => number;\n\n  /** The socket factory. Default constructs a global `WebSocket`; inject a double in tests. */\n  readonly socket?: SocketFactory;\n}\n\n/** Controls a live WebSocket connection. */\nexport interface SocketClient<TOut = unknown> {\n  /** The current connection state. */\n  readonly readyState: ConnectionState;\n\n  /** Whether a `WebSocket` implementation was available at all; `false` under SSR, where the client is inert. */\n  readonly supported: boolean;\n\n  /** The number of frames buffered awaiting an open socket — non-zero means back-pressure or an outage. */\n  readonly queuedCount: number;\n\n  /** The consecutive reconnect attempts, zeroed on every successful open. */\n  readonly attempts: number;\n\n  /**\n   * Sends a message, queueing it when the socket is not open yet.\n   *\n   * @param message - The payload, encoded by `serialize`.\n   * @returns `true` when the frame went out immediately, `false` when it was queued or dropped.\n   */\n  send(message: TOut): boolean;\n\n  /** Closes the socket, cancels reconnection permanently, clears the heartbeat, and detaches every listener. Idempotent. */\n  close(code?: number, reason?: string): void;\n}\n\n/** Resolves the socket factory: the injected one, else the global `WebSocket`, else `undefined` (SSR / unsupported). */\nfunction resolveSocketFactory(injected?: SocketFactory): SocketFactory | undefined {\n  if (injected !== undefined) return injected;\n  if (typeof WebSocket === 'undefined') return undefined;\n  return (url, protocols) => new WebSocket(url, protocols as string | string[] | undefined);\n}\n\n/**\n * Opens a JSON WebSocket with a send queue, `resilience`-scheduled reconnection, and a half-open detector —\n * see this file's header for the three bugs each of those exists to prevent.\n *\n * Never throws, at import time or at call time. Where `WebSocket` does not exist (SSR) the returned client\n * reports `supported: false` and state `closed`, `send` returns `false`, and `close` is a no-op.\n *\n * @typeParam TIn - The decoded inbound message type.\n * @typeParam TOut - The outbound message type.\n * @param url - The socket endpoint (`ws://` or `wss://`).\n * @param options - Handlers, retry policy, heartbeat, codecs, and injection seams.\n * @returns The client handle. ALWAYS call `close()` when done — an abandoned socket keeps its connection, its\n * heartbeat timers, and every captured handler alive.\n */\nexport function createSocketClient<TIn = unknown, TOut = unknown>(\n  url: string,\n  options: SocketClientOptions<TIn, TOut> = {},\n): SocketClient<TOut> {\n  const {\n    protocols,\n    onMessage,\n    onOpen,\n    onClose,\n    onError,\n    onStateChange,\n    serialize = (message: TOut) => JSON.stringify(message),\n    deserialize = (raw: string) => JSON.parse(raw) as TIn,\n    retry,\n    heartbeat,\n    queueLimit = DefaultQueueLimit,\n    random,\n    socket: socketFactory,\n  } = options;\n\n  const factory = resolveSocketFactory(socketFactory);\n  const scheduler = createReconnectScheduler({ retry, random });\n\n  /** Frames buffered while the socket is not `OPEN`, oldest first. */\n  const queue: string[] = [];\n\n  let state: ConnectionState = ConnectionState.Connecting;\n  let connection: SocketConnection | undefined;\n  let detach: (() => void) | undefined;\n  let closedByCaller = false;\n  let pingTimer: ReturnType<typeof setInterval> | undefined;\n  let pongTimer: ReturnType<typeof setTimeout> | undefined;\n\n  /** Publishes a state transition, skipping no-op repeats. */\n  const setState = (next: ConnectionState): void => {\n    if (state === next) return;\n    state = next;\n    onStateChange?.(next);\n  };\n\n  /** Reports an error, tolerating a throwing consumer handler — a bad listener must not break the transport. */\n  const report = (error: unknown): void => {\n    try {\n      onError?.(toError(error));\n    } catch {\n      // Swallowed by contract: this runs from a DOM event handler, where a throw is unhandleable noise.\n    }\n  };\n\n  /** Stops both heartbeat timers. Runs on every close and every drop, so neither can outlive its socket. */\n  const stopHeartbeat = (): void => {\n    if (pingTimer !== undefined) {\n      clearInterval(pingTimer);\n      pingTimer = undefined;\n    }\n    if (pongTimer !== undefined) {\n      clearTimeout(pongTimer);\n      pongTimer = undefined;\n    }\n  };\n\n  /** Clears the pong deadline — called for ANY inbound frame, since traffic is proof of life. */\n  const noteTraffic = (): void => {\n    if (pongTimer !== undefined) {\n      clearTimeout(pongTimer);\n      pongTimer = undefined;\n    }\n  };\n\n  /** Tears the current socket down and reconnects — the path for a drop, NOT for a caller's close. */\n  const recycle = (): void => {\n    if (closedByCaller) return;\n\n    stopHeartbeat();\n    // Detach BEFORE closing: our own `close` would otherwise fire the close handler, which would schedule a\n    // second reconnect on top of this one.\n    detach?.();\n    detach = undefined;\n    const dying = connection;\n    connection = undefined;\n    try {\n      dying?.close();\n    } catch {\n      // A socket already dead rejects `close()` in some runtimes; nothing to recover.\n    }\n\n    const scheduled = scheduler.schedule(connect);\n    setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n  };\n\n  /** Starts the heartbeat for a freshly opened socket, if one is configured. */\n  const startHeartbeat = (): void => {\n    if (heartbeat === undefined) return;\n\n    const { intervalMs, timeoutMs = heartbeat.intervalMs, ping = DefaultPingFrame } = heartbeat;\n    if (!Number.isFinite(intervalMs) || intervalMs <= 0) return;\n\n    pingTimer = setInterval(() => {\n      const live = connection;\n      if (live === undefined || live.readyState !== SocketReadyState.Open) return;\n\n      try {\n        live.send(ping());\n      } catch (error) {\n        report(error);\n      }\n\n      // Arm the deadline only if one is not already running: back-to-back pings with no traffic between them\n      // must not each reset the clock, or a dead socket is never detected.\n      if (pongTimer !== undefined) return;\n      pongTimer = setTimeout(() => {\n        pongTimer = undefined;\n        report(new Error(`The socket to ${url} missed its heartbeat; treating it as half-open.`));\n        recycle();\n      }, timeoutMs);\n    }, intervalMs);\n  };\n\n  /** Writes every buffered frame in order, on open. A frame the socket rejects is reported and dropped, not re-queued. */\n  const flushQueue = (target: SocketConnection): void => {\n    const pending = queue.splice(0, queue.length);\n    for (const frame of pending) {\n      try {\n        target.send(frame);\n      } catch (error) {\n        report(error);\n      }\n    }\n  };\n\n  /** Binds every listener to a socket and returns the matching detach — one closure so no listener can be missed. */\n  const bind = (target: SocketConnection): (() => void) => {\n    const bound: [type: string, listener: (event: Event) => void][] = [];\n\n    /** Registers a listener and records it for the paired detach. */\n    const on = (type: string, listener: (event: Event) => void): void => {\n      target.addEventListener(type, listener);\n      bound.push([type, listener]);\n    };\n\n    on('open', () => {\n      scheduler.reset();\n      setState(ConnectionState.Open);\n      onOpen?.();\n      // Flush AFTER `onOpen`, so a handler that sends a subscribe/auth frame on connect lands ahead of the\n      // backlog rather than behind it — the ordering a protocol with a handshake requires.\n      flushQueue(target);\n      startHeartbeat();\n    });\n\n    on('message', (event) => {\n      noteTraffic();\n      if (onMessage === undefined) return;\n\n      const message = event as MessageEvent;\n      const data: unknown = message.data;\n      if (typeof data !== 'string') {\n        // Binary frames are out of scope for a JSON client; reporting beats silently dropping.\n        report(new Error(`The socket to ${url} delivered a non-text frame, which this client cannot decode.`));\n        return;\n      }\n\n      let decoded: TIn;\n      try {\n        decoded = deserialize(data);\n      } catch (error) {\n        report(error);\n        return;\n      }\n      onMessage(decoded, message);\n    });\n\n    on('error', () => {\n      // The `error` event carries no detail by design (it would leak cross-origin information). The close\n      // that follows is what actually drives reconnection.\n      report(new Error(`The socket to ${url} reported an error.`));\n    });\n\n    on('close', (event) => {\n      stopHeartbeat();\n      onClose?.(event as CloseEvent);\n      if (closedByCaller) return;\n\n      detach?.();\n      detach = undefined;\n      connection = undefined;\n\n      const scheduled = scheduler.schedule(connect);\n      setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n    });\n\n    return () => {\n      for (const entry of bound) target.removeEventListener(entry[0], entry[1]);\n      bound.length = 0;\n    };\n  };\n\n  /** Opens a socket and binds it; a constructor throw (a bad URL scheme) is reported and retried, not propagated. */\n  function connect(): void {\n    if (closedByCaller || factory === undefined) return;\n\n    setState(scheduler.attempts === 0 ? ConnectionState.Connecting : ConnectionState.Reconnecting);\n\n    let opened: SocketConnection;\n    try {\n      opened = factory(url, protocols);\n    } catch (error) {\n      report(error);\n      const scheduled = scheduler.schedule(connect);\n      setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n      return;\n    }\n\n    connection = opened;\n    detach = bind(opened);\n  }\n\n  if (factory === undefined) {\n    // Unsupported: a defined, inert answer. No throw, no listeners, no timers.\n    state = ConnectionState.Closed;\n    return {\n      get readyState() {\n        return state;\n      },\n      supported: false,\n      get queuedCount() {\n        return 0;\n      },\n      get attempts() {\n        return 0;\n      },\n      send: () => false,\n      close: () => undefined,\n    };\n  }\n\n  connect();\n\n  return {\n    get readyState() {\n      return state;\n    },\n    supported: true,\n    get queuedCount() {\n      return queue.length;\n    },\n    get attempts() {\n      return scheduler.attempts;\n    },\n\n    send(message: TOut): boolean {\n      // A closed client silently drops rather than buffering forever — nothing will ever flush the queue.\n      if (closedByCaller) return false;\n\n      let frame: string;\n      try {\n        frame = serialize(message);\n      } catch (error) {\n        report(error);\n        return false;\n      }\n\n      const live = connection;\n      if (live !== undefined && live.readyState === SocketReadyState.Open) {\n        try {\n          live.send(frame);\n          return true;\n        } catch (error) {\n          // The socket claimed `OPEN` and refused anyway (a race with a close). Queue it for the reconnect\n          // rather than losing it.\n          report(error);\n        }\n      }\n\n      queue.push(frame);\n      if (queue.length > queueLimit) queue.splice(0, queue.length - queueLimit);\n      return false;\n    },\n\n    close(code?: number, reason?: string): void {\n      if (closedByCaller) return;\n      // Set BEFORE requesting the close, so the `close` event this triggers sees the flag and stands down.\n      closedByCaller = true;\n      scheduler.cancel();\n      stopHeartbeat();\n      queue.length = 0;\n\n      const dying = connection;\n      connection = undefined;\n      try {\n        dying?.close(code, reason);\n      } catch {\n        // A socket already dead rejects `close()` in some runtimes; nothing to recover.\n      }\n      detach?.();\n      detach = undefined;\n      setState(ConnectionState.Closed);\n    },\n  };\n}\n","// Vue binding for `createSocketClient` — one socket per scope, closed when the scope is disposed.\n//\n// THE LIFETIME RULE THIS ENFORCES: a `WebSocket` abandoned by its component stays connected, keeps its\n// heartbeat interval running, and keeps reconnecting on backoff — forever, since nothing else holds a\n// reference with which to close it. In an SPA that is one leaked socket per visit to the page, and the server\n// sees the connection count climb with no matching users. Binding the client to `onMounted` /\n// `onScopeDispose` makes the teardown automatic.\n//\n// OPENED FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `createSocketClient` resolves `WebSocket` inside\n// the call, and an immediate watcher also runs during a server render, where that global does not exist.\n//\n// THE RETURNED `send` IS ALWAYS SAFE TO CALL. It reads the current client from the closure, so it never goes\n// stale, and it works BEFORE the socket finishes connecting — the client's queue is what makes that true (see\n// `CreateSocketClient.ts`, bug 1). Calling it after disposal is a no-op rather than a crash, which matters\n// because an in-flight event handler routinely outlives the tree.\n//\n// HANDLERS ARE READ THROUGH `toValue` AT CALL TIME, options are read once, and a `null` URL means \"not yet\" —\n// same three rules as `useEventStream`, for the same reasons.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { ConnectionState } from './ConnectionState';\nimport { createSocketClient, type SocketClient, type SocketClientOptions } from './CreateSocketClient';\n\n/** The live view a scope gets over its socket. */\nexport interface SocketHandle<TOut> {\n  /** The current connection state, updating on every transition. */\n  readonly readyState: Readonly<ShallowRef<ConnectionState>>;\n\n  /** Whether `WebSocket` exists in this runtime; `false` under SSR. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /**\n   * Sends a message, queueing it while the socket is still connecting.\n   *\n   * @returns `true` when the frame went out immediately, `false` when queued, dropped, or disposed.\n   */\n  readonly send: (message: TOut) => boolean;\n\n  /** Closes the socket early and suppresses reconnection. The scope-disposal cleanup calls it anyway. */\n  readonly close: () => void;\n}\n\n/**\n * Opens a JSON WebSocket for the lifetime of the scope.\n *\n * The socket is closed when the scope is disposed and re-opened whenever `url` changes. Pass `null` to hold\n * off connecting (waiting for auth, a route param, a feature flag) — a ref or getter is how that flips.\n *\n * @typeParam TIn - The decoded inbound message type.\n * @typeParam TOut - The outbound message type.\n * @param url - The socket endpoint, or `null` to stay disconnected.\n * @param options - Handlers and configuration, read once when the socket opens; handler callbacks are re-read\n *   per message, so a ref or getter keeps them live.\n * @returns The connection state, support flag, and `send` / `close`.\n */\nexport function useSocket<TIn = unknown, TOut = unknown>(\n  url: MaybeRefOrGetter<string | null>,\n  options: MaybeRefOrGetter<SocketClientOptions<TIn, TOut>> = {},\n): SocketHandle<TOut> {\n  const readyState = shallowRef<ConnectionState>(\n    toValue(url) === null ? ConnectionState.Closed : ConnectionState.Connecting,\n  );\n  const supported = shallowRef(true);\n\n  let client: SocketClient<TOut> | null = null;\n\n  function teardown(): void {\n    client?.close();\n    client = null;\n  }\n\n  function open(): void {\n    teardown();\n\n    const endpoint = toValue(url);\n    if (endpoint === null) {\n      readyState.value = ConnectionState.Closed;\n      return;\n    }\n\n    const current = toValue(options);\n    const next = createSocketClient<TIn, TOut>(endpoint, {\n      ...current,\n      // Every consumer callback is re-read through `toValue` at call time, which is what lets the watcher\n      // depend on `url` alone. `onStateChange` is additionally intercepted to drive this scope's own state.\n      onStateChange: (state) => {\n        readyState.value = state;\n        toValue(options).onStateChange?.(state);\n      },\n      onOpen: () => toValue(options).onOpen?.(),\n      onClose: (event) => toValue(options).onClose?.(event),\n      onError: (error) => toValue(options).onError?.(error),\n      onMessage: (message, event) => toValue(options).onMessage?.(message, event),\n    });\n\n    client = next;\n    supported.value = next.supported;\n    readyState.value = next.readyState;\n  }\n\n  onMounted(open);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `WebSocket` is absent.\n  watch(() => toValue(url), open);\n  onScopeDispose(teardown);\n\n  const send = (message: TOut): boolean => client?.send(message) ?? false;\n\n  const close = (): void => {\n    client?.close();\n  };\n\n  return { readyState, supported, send, close };\n}\n","// Connectivity as a NON-VUE signal, for the factories in this slice that are plain functions and cannot\n// call a composable.\n//\n// RELATIONSHIP TO `foundation/device`'s `useOnlineStatus` — READ BEFORE ADDING ANOTHER TRACKER. That\n// composable is and remains THE Vue binding for connectivity; nothing here replaces it, and a component must\n// keep using it. But `createPoller` and `waitForOnline` are framework-agnostic factories called from timers,\n// effects, and `catch` blocks, where a composable is illegal. `device` keeps its reader module-private, so the\n// choice was to export a reader from `device` (widening a slice this one has no business editing, and one\n// another lane may be touching) or to keep a five-line reader here. This is the five-line reader, and it\n// MIRRORS the composable's\n// semantics deliberately: same optimistic default, same guarded read, same two events. If either changes,\n// change both.\n//\n// WHAT `navigator.onLine` IS WORTH, restated because every caller gets this wrong: `false` is trustworthy\n// (the browser knows there is no link); `true` only means a link exists — a captive portal, a dead VPN, or a\n// server that is simply down all report `true`. So this drives \"stop polling, nothing can succeed\" and\n// \"wait before retrying\", never \"we are online, therefore this will work\".\n//\n// `waitForOnline` RESOLVES A VERDICT AND NEVER THROWS, which is a deliberate deviation from `withTimeout` in\n// `foundation/async` (that one rejects with a `TimeoutError`). Every call site for this function is ALREADY\n// inside a failure path — a mutation just failed and the caller is deciding whether to retry. Rejecting\n// there forces a nested try/catch around the recovery logic to distinguish \"still offline\" from a real\n// fault, and a missed catch turns a recoverable failure into an unhandled rejection. A boolean reads as the\n// question actually being asked: `if (await waitForOnline({ timeoutMs: 5_000 })) retry();`.\n\n/**\n * Reads `navigator.onLine`, defaulting to online when there is no `navigator` (SSR), when the property is\n * missing (a partial polyfill), or when the read throws.\n *\n * Mirrors `useOnlineStatus`'s reader exactly — see this file's header for why the duplication is deliberate.\n *\n * @returns `true` while the browser reports a network link; optimistically `true` when unreadable.\n */\nexport function readOnlineStatus(): boolean {\n  try {\n    if (typeof navigator === 'undefined') return true;\n    return navigator.onLine !== false;\n  } catch {\n    return true;\n  }\n}\n\n/**\n * Subscribes to connectivity changes via the window `online` / `offline` events.\n *\n * A no-op returning a no-op disposer when there is no `window` (SSR), so callers need no environment branch.\n * The listener receives the new status, never a raw `Event`.\n *\n * @param listener - Invoked with `true` on `online` and `false` on `offline`.\n * @returns A disposer that detaches both listeners; safe to call more than once.\n */\nexport function subscribeOnline(listener: (online: boolean) => void): () => void {\n  if (typeof window === 'undefined') return () => undefined;\n\n  const target = window;\n  const onOnline = (): void => listener(true);\n  const onOffline = (): void => listener(false);\n\n  target.addEventListener('online', onOnline);\n  target.addEventListener('offline', onOffline);\n\n  let detached = false;\n  return () => {\n    if (detached) return;\n    detached = true;\n    target.removeEventListener('online', onOnline);\n    target.removeEventListener('offline', onOffline);\n  };\n}\n\n/** Configures a {@link waitForOnline} call. Every member is optional. */\nexport interface WaitForOnlineOptions {\n  /** The maximum wait (ms) before giving up and resolving `false`. Omit, or pass a non-positive value, to wait indefinitely. */\n  readonly timeoutMs?: number;\n\n  /** Abandons the wait early, resolving `false` — an abort is a \"stop waiting\" verdict here, never a rejection. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Waits for connectivity to come back, resolving `true` the moment it does.\n *\n * Resolves `true` immediately when already online, and `false` when the timeout lapses or the signal aborts —\n * never rejects, and never leaves a timer or a listener behind on any of those paths. Under SSR, or wherever\n * connectivity cannot be observed, it resolves `true` at once rather than hanging on an event that can never\n * arrive.\n *\n * Remember what a `true` verdict is worth (see this file's header): it says a link exists, not that the\n * server is reachable. Use it to gate a retry, then let the retry decide.\n *\n * @param options - The deadline and cancellation signal.\n * @returns `true` when connectivity is (or becomes) available; `false` on timeout or abort.\n */\nexport function waitForOnline(options: WaitForOnlineOptions = {}): Promise<boolean> {\n  const { timeoutMs, signal } = options;\n\n  if (readOnlineStatus()) return Promise.resolve(true);\n  if (signal?.aborted === true) return Promise.resolve(false);\n  // Nothing to listen on — an indefinite wait here could never be satisfied, so answer with the current read\n  // instead of hanging forever.\n  if (typeof window === 'undefined') return Promise.resolve(readOnlineStatus());\n\n  return new Promise<boolean>((resolve) => {\n    let settled = false;\n    let unsubscribe: (() => void) | undefined;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let onAbort: (() => void) | undefined;\n\n    /** The single teardown every exit path runs — timer, connectivity listeners, and abort listener alike. */\n    const cleanup = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      unsubscribe?.();\n      unsubscribe = undefined;\n      if (signal !== undefined && onAbort !== undefined) {\n        signal.removeEventListener('abort', onAbort);\n        onAbort = undefined;\n      }\n    };\n\n    /** Settles once and only once — three racing sources can all fire in the same tick. */\n    const finish = (online: boolean): void => {\n      if (settled) return;\n      settled = true;\n      cleanup();\n      resolve(online);\n    };\n\n    unsubscribe = subscribeOnline((online) => {\n      if (online) finish(true);\n    });\n\n    if (timeoutMs !== undefined && timeoutMs > 0 && Number.isFinite(timeoutMs)) {\n      timer = setTimeout(() => {\n        timer = undefined;\n        finish(false);\n      }, timeoutMs);\n    }\n\n    if (signal !== undefined) {\n      const listener = (): void => finish(false);\n      onAbort = listener;\n      signal.addEventListener('abort', listener, { once: true });\n    }\n  });\n}\n","// Interval polling that stops burning quota when nobody is looking.\n//\n// WHY A HIDDEN TAB MUST NOT POLL: a background tab is invisible, not closed. A 10-second poll left running\n// across a workday is thousands of requests nobody will ever see the result of — paid for in the user's\n// battery, the user's mobile data, and the API's rate limit, which is then unavailable to the tab the user is\n// actually looking at. Browsers throttle background timers, but throttling is not stopping: the requests\n// still go out, just less punctually. So this suspends on `visibilitychange` and, by default, refreshes\n// immediately on return, since data that went stale while hidden is the first thing the returning user reads.\n//\n// WHY OFFLINE MUST NOT POLL: every tick during an outage is a guaranteed failure. Left running it produces a\n// stream of errors that drowns the log, trips error-rate alerting, and — where the poll feeds a UI — flickers\n// a failure banner on a schedule. Suspending costs nothing, because the `online` event fires the moment there\n// is anything to poll for.\n//\n// SUSPENSION IS REASON-COUNTED, NOT A BOOLEAN, and this is the non-obvious part. Three independent things can\n// suspend the poller — the caller's `pause()`, a hidden tab, an offline browser — and with one flag they\n// overwrite each other: the tab regains focus, clears the flag, and silently resumes a poller the CALLER\n// paused, which is a real bug (a modal that paused polling reopens to a poller running behind it). A set of\n// reasons makes the rule exact: the poller ticks only when the set is empty, and `resume()` clears only the\n// caller's reason.\n//\n// TICKS DO NOT OVERLAP. Scheduling is a `setTimeout` CHAIN, re-armed after each run settles, not a\n// `setInterval`. With an interval, a poll slower than its period stacks: requests overlap, responses arrive\n// out of order, and the slowest response wins the UI — worse the more congested the network is, which is\n// exactly when it hurts. The chain makes `intervalMs` the gap BETWEEN runs, so a slow backend degrades to\n// polling less often instead of DDoSing itself.\n//\n// CONNECTIVITY IS READ THROUGH `Liveness.ts`, whose header explains why this slice has a non-Vue reader at\n// all instead of `foundation/device`'s `useOnlineStatus`.\n\nimport { toError } from '../errors';\n\nimport { readOnlineStatus, subscribeOnline } from './Liveness';\n\n/** The default gap between polls. */\nconst DefaultIntervalMs = 30_000;\n\n/** Names why a poller is suspended — a set of these, not a flag, so the reasons cannot overwrite each other. */\nconst SuspendReason = {\n  /** Refers to the caller's own `pause()`. Cleared only by `resume()`. */\n  Manual: 'manual',\n  /** Refers to a hidden tab. Cleared by `visibilitychange`. */\n  Hidden: 'hidden',\n  /** Refers to an offline browser. Cleared by the `online` event. */\n  Offline: 'offline',\n} as const;\n\ntype SuspendReason = (typeof SuspendReason)[keyof typeof SuspendReason];\n\n/** Describes what a poller is doing right now. */\nexport const PollerState = {\n  /** Refers to a poller created but not started. */\n  Idle: 'idle',\n  /** Refers to a poller with a tick scheduled or running. */\n  Running: 'running',\n  /** Refers to a started poller held by at least one suspend reason — paused, hidden, or offline. */\n  Paused: 'paused',\n  /** Refers to a stopped poller: timers cleared, listeners detached, restartable with `start()`. */\n  Stopped: 'stopped',\n} as const;\n\nexport type PollerState = (typeof PollerState)[keyof typeof PollerState];\n\n/** The work a poller repeats. A returned promise is awaited, so the next tick is scheduled only after it settles. */\nexport type PollFn = () => unknown;\n\n/** Configures a {@link createPoller} call. Every member is optional. */\nexport interface PollerOptions {\n  /** The gap (ms) between the end of one poll and the start of the next. Default `30000`. */\n  readonly intervalMs?: number;\n\n  /** Whether to start polling immediately on creation. Default `true`; `false` waits for `start()`. */\n  readonly autoStart?: boolean;\n\n  /** Whether to run one poll at once on start, rather than after the first interval. Default `false`. */\n  readonly immediate?: boolean;\n\n  /** Whether to suspend while the tab is hidden. Default `true`. */\n  readonly pauseWhenHidden?: boolean;\n\n  /** Whether to suspend while the browser reports no network link. Default `true`. */\n  readonly pauseWhenOffline?: boolean;\n\n  /** Whether returning from a suspension polls at once instead of waiting a full interval. Default `true` — the data is already stale. */\n  readonly refreshOnResume?: boolean;\n\n  /** Receives an error thrown or rejected by the poll. The chain continues regardless — a failed poll is not a reason to stop polling. */\n  readonly onError?: (error: Error) => void;\n\n  /** Fires on every state transition — the seam for a \"paused (offline)\" indicator. */\n  readonly onStateChange?: (state: PollerState) => void;\n}\n\n/** Controls a running poll loop. */\nexport interface Poller {\n  /** The current state. `paused` covers all three suspend reasons. */\n  readonly state: PollerState;\n\n  /** Starts (or restarts) polling. A no-op while already running. */\n  start(): void;\n\n  /** Suspends polling until `resume()`. Independent of the automatic hidden / offline suspensions. */\n  pause(): void;\n\n  /** Clears the caller's suspension. Polling stays suspended if the tab is still hidden or the browser still offline. */\n  resume(): void;\n\n  /** Stops polling, clears the pending timer, and detaches the visibility and connectivity listeners. Idempotent. */\n  stop(): void;\n}\n\n/** Reads `document.visibilityState`, defaulting to visible where there is no document (SSR) or the read throws. */\nfunction readHidden(): boolean {\n  try {\n    if (typeof document === 'undefined') return false;\n    return document.visibilityState === 'hidden';\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Subscribes to `visibilitychange`, reporting whether the document is now hidden.\n *\n * A no-op returning a no-op disposer where there is no `document`, so callers need no environment branch.\n */\nfunction subscribeVisibility(listener: (hidden: boolean) => void): () => void {\n  if (typeof document === 'undefined') return () => undefined;\n\n  const target = document;\n  const onChange = (): void => listener(readHidden());\n  target.addEventListener('visibilitychange', onChange);\n\n  let detached = false;\n  return () => {\n    if (detached) return;\n    detached = true;\n    target.removeEventListener('visibilitychange', onChange);\n  };\n}\n\n/**\n * Creates a poller that repeats `fn` on an interval and suspends itself while the tab is hidden or the\n * browser is offline — see this file's header for why both of those are non-negotiable.\n *\n * Never throws: an error from `fn` goes to `onError` and the loop continues, because a poll that failed once\n * is the poll most worth retrying. Ticks never overlap.\n *\n * @param fn - The work to repeat; a returned promise is awaited before the next tick is scheduled.\n * @param options - Interval, suspension behaviour, and hooks.\n * @returns The poller handle. ALWAYS call `stop()` when done — a live poller holds a timer and two document /\n * window listeners.\n */\nexport function createPoller(fn: PollFn, options: PollerOptions = {}): Poller {\n  const {\n    intervalMs = DefaultIntervalMs,\n    autoStart = true,\n    immediate = false,\n    pauseWhenHidden = true,\n    pauseWhenOffline = true,\n    refreshOnResume = true,\n    onError,\n    onStateChange,\n  } = options;\n\n  const suspended = new Set<SuspendReason>();\n\n  let state: PollerState = PollerState.Idle;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let running = false;\n  let inFlight = false;\n  let unsubscribeVisibility: (() => void) | undefined;\n  let unsubscribeOnline: (() => void) | undefined;\n\n  /** Publishes a state transition, skipping no-op repeats. */\n  const setState = (next: PollerState): void => {\n    if (state === next) return;\n    state = next;\n    onStateChange?.(next);\n  };\n\n  /** Clears the pending tick, if any. Never touches the listeners — suspension keeps them. */\n  const clearPending = (): void => {\n    if (timer !== undefined) {\n      clearTimeout(timer);\n      timer = undefined;\n    }\n  };\n\n  /** Arms the next tick. Refuses while stopped or suspended, which is what makes every suspend path a one-liner. */\n  const scheduleNext = (): void => {\n    if (!running || suspended.size > 0 || timer !== undefined) return;\n    timer = setTimeout(() => {\n      timer = undefined;\n      void tick();\n    }, intervalMs);\n  };\n\n  /** Runs one poll and re-arms — the chain that replaces `setInterval`. */\n  async function tick(): Promise<void> {\n    if (!running || suspended.size > 0 || inFlight) return;\n\n    inFlight = true;\n    try {\n      await fn();\n    } catch (error) {\n      try {\n        onError?.(toError(error));\n      } catch {\n        // Swallowed by contract: a throwing error handler must not break the loop it was told about.\n      }\n    } finally {\n      inFlight = false;\n    }\n\n    // Re-checked AFTER the await: the poll may have been stopped or suspended while it was in flight, and\n    // arming a timer for a poller that is already gone is exactly how a \"stopped\" poller keeps ticking.\n    scheduleNext();\n  }\n\n  /** Adds a suspend reason and parks the loop. */\n  const suspend = (reason: SuspendReason): void => {\n    if (suspended.has(reason)) return;\n    suspended.add(reason);\n    clearPending();\n    if (running) setState(PollerState.Paused);\n  };\n\n  /** Removes a suspend reason and, once none remain, resumes — immediately when `refreshOnResume`. */\n  const unsuspend = (reason: SuspendReason): void => {\n    if (!suspended.delete(reason)) return;\n    if (!running || suspended.size > 0) return;\n\n    setState(PollerState.Running);\n    if (refreshOnResume) void tick();\n    else scheduleNext();\n  };\n\n  /** Attaches the visibility and connectivity listeners and seeds the matching suspend reasons. */\n  const attachEnvironment = (): void => {\n    if (pauseWhenHidden) {\n      if (readHidden()) suspended.add(SuspendReason.Hidden);\n      unsubscribeVisibility = subscribeVisibility((hidden) => {\n        if (hidden) suspend(SuspendReason.Hidden);\n        else unsuspend(SuspendReason.Hidden);\n      });\n    }\n\n    if (pauseWhenOffline) {\n      if (!readOnlineStatus()) suspended.add(SuspendReason.Offline);\n      unsubscribeOnline = subscribeOnline((online) => {\n        if (online) unsuspend(SuspendReason.Offline);\n        else suspend(SuspendReason.Offline);\n      });\n    }\n  };\n\n  /** Detaches both environment listeners. Idempotent. */\n  const detachEnvironment = (): void => {\n    unsubscribeVisibility?.();\n    unsubscribeVisibility = undefined;\n    unsubscribeOnline?.();\n    unsubscribeOnline = undefined;\n  };\n\n  const poller: Poller = {\n    get state() {\n      return state;\n    },\n\n    start(): void {\n      if (running) return;\n      running = true;\n      // A restart begins from a clean slate — a stale `hidden` reason left over from the previous run would\n      // otherwise park the poller forever, since the event that would clear it has already fired.\n      suspended.clear();\n      attachEnvironment();\n\n      if (suspended.size > 0) {\n        setState(PollerState.Paused);\n        return;\n      }\n\n      setState(PollerState.Running);\n      if (immediate) void tick();\n      else scheduleNext();\n    },\n\n    pause(): void {\n      suspend(SuspendReason.Manual);\n    },\n\n    resume(): void {\n      unsuspend(SuspendReason.Manual);\n    },\n\n    stop(): void {\n      if (!running && state === PollerState.Stopped) return;\n      running = false;\n      clearPending();\n      detachEnvironment();\n      suspended.clear();\n      setState(PollerState.Stopped);\n    },\n  };\n\n  if (autoStart) poller.start();\n\n  return poller;\n}\n","// Vue binding for `createPoller` — one loop per scope, stopped when the scope is disposed.\n//\n// THE LIFETIME RULE THIS ENFORCES: a poller holds a timer plus a `visibilitychange` and two connectivity\n// listeners. A disposed scope that never stopped its poller keeps all four, keeps issuing requests, and keeps\n// writing into state that no longer renders — except it also costs a request every interval, forever.\n//\n// BUILT FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `createPoller` attaches its `visibilitychange`\n// listener to `document` and its connectivity listeners to `window`; an immediate watcher also runs during a\n// server render, where neither exists. `onMounted` is client-only by construction.\n//\n// `fn` IS READ THROUGH `toValue` AT CALL TIME rather than captured. A component's `setup` runs once, so the\n// React original's infinite-restart hazard (a fresh `fn` identity every render, each render caused by the\n// previous poll's own state write) simply cannot occur here — but reading it per tick is still the right\n// contract, because it lets a caller pass a getter whose target changes without rebuilding the loop.\n//\n// The suspend rules (hidden tab, offline) belong to the poller itself, not to this composable, so a\n// framework-free caller gets identical behaviour — see `CreatePoller.ts`. In particular this composable does\n// NOT call `useOnlineStatus`: doing so would update reactive state on every connectivity flip merely to tell\n// the poller something it already knows from the same events.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { PollerState, createPoller, type PollFn, type Poller, type PollerOptions } from './CreatePoller';\n\n/** The live view a scope gets over its poll loop. */\nexport interface PollingHandle {\n  /** The current poller state, updating on every transition. `paused` covers manual, hidden, and offline. */\n  readonly state: Readonly<ShallowRef<PollerState>>;\n\n  /** Suspends polling until `resume()`. */\n  readonly pause: () => void;\n\n  /** Clears the manual suspension; polling stays suspended if the tab is hidden or the browser offline. */\n  readonly resume: () => void;\n\n  /** Stops the loop and detaches its listeners. The scope-disposal cleanup calls it anyway. */\n  readonly stop: () => void;\n}\n\n/**\n * Runs `fn` on an interval for the lifetime of the scope, suspended automatically while the tab is hidden or\n * the browser is offline.\n *\n * The loop stops when the scope is disposed and is rebuilt whenever `intervalMs` changes. `fn` is read fresh\n * on each tick, so a getter whose target changes needs no rebuild.\n *\n * @param fn - The work to repeat; a returned promise is awaited before the next tick is scheduled.\n * @param options - Interval and suspension behaviour, read once when the loop is built; handler callbacks are\n *   re-read per emission, so a ref or getter keeps them live.\n * @returns The poller state and `pause` / `resume` / `stop`.\n */\nexport function usePolling(\n  fn: MaybeRefOrGetter<PollFn>,\n  options: MaybeRefOrGetter<PollerOptions> = {},\n): PollingHandle {\n  const state = shallowRef<PollerState>(PollerState.Idle);\n\n  let poller: Poller | null = null;\n\n  function teardown(): void {\n    poller?.stop();\n    poller = null;\n  }\n\n  function build(): void {\n    teardown();\n\n    const current = toValue(options);\n    const next = createPoller(() => toValue(fn)(), {\n      ...current,\n      intervalMs: current.intervalMs,\n      onStateChange: (value) => {\n        state.value = value;\n        toValue(options).onStateChange?.(value);\n      },\n      onError: (error) => toValue(options).onError?.(error),\n    });\n\n    poller = next;\n    state.value = next.state;\n  }\n\n  onMounted(build);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `document` and `window` are\n  // absent. `intervalMs` alone is the rebuild trigger — the platform cannot retune a live interval.\n  watch(() => toValue(options).intervalMs, build);\n  onScopeDispose(teardown);\n\n  const pause = (): void => {\n    poller?.pause();\n  };\n\n  const resume = (): void => {\n    poller?.resume();\n  };\n\n  const stop = (): void => {\n    poller?.stop();\n  };\n\n  return { state, pause, resume, stop };\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/net/ConnectionState.ts","../../../src/foundation/net/Reconnect.ts","../../../src/foundation/net/CreateEventStream.ts","../../../src/foundation/net/hooks/UseEventStream.ts","../../../src/foundation/net/CreateSocketClient.ts","../../../src/foundation/net/hooks/UseSocket.ts","../../../src/foundation/net/Liveness.ts","../../../src/foundation/net/CreatePoller.ts","../../../src/foundation/net/hooks/UsePolling.ts"],"sourcesContent":["// The connection vocabulary shared by every long-lived transport in this slice, plus the two sets of WIRE\n// ready-state numbers the platform uses.\n//\n// WHY A SEPARATE STATE FROM THE WIRE NUMBER: `EventSource.readyState` and `WebSocket.readyState` are both\n// small integers, they overlap numerically, and they mean DIFFERENT things — `2` is `CLOSED` for an\n// `EventSource` and `CLOSING` for a `WebSocket`. Worse, neither can express \"the socket is down and this\n// wrapper is waiting out a backoff delay before the next attempt\", which is the state a UI most wants to\n// render (\"reconnecting…\"). `EventSource` reports that situation as `CONNECTING`, indistinguishable from the\n// very first connect. So consumers get this string union and never see a raw integer.\n//\n// WHY THE NUMBERS ARE SPELLED OUT HERE RATHER THAN READ OFF THE GLOBALS: `WebSocket.OPEN` is a static member\n// of a class that does not exist under SSR, in a node test, or in a browser with the API disabled. Reading it\n// at module scope is a `ReferenceError` at import time — the exact failure this slice promises never to have.\n// The values are fixed by the WHATWG spec and cannot drift, so hardcoding them is both safe and the only\n// SSR-correct option.\n\n/** Describes a long-lived connection's state, uniformly across SSE, WebSocket, and polling. */\nexport const ConnectionState = {\n  /** Refers to a first connection attempt in flight — nothing has been established yet. */\n  Connecting: 'connecting',\n  /** Refers to an established connection that is passing traffic. */\n  Open: 'open',\n  /** Refers to a dropped connection with a retry pending or in flight — what the wire ready-state cannot express. */\n  Reconnecting: 'reconnecting',\n  /** Refers to a connection down for good — closed by the caller, unsupported, or out of retries. */\n  Closed: 'closed',\n} as const;\n\nexport type ConnectionState = (typeof ConnectionState)[keyof typeof ConnectionState];\n\n/**\n * Provides the `EventSource.readyState` values from the WHATWG spec. Note `Closed` here is TERMINAL — the\n * browser only reports it once it has abandoned its own reconnection, which is precisely the signal\n * `createEventStream` waits for before taking the retry over.\n */\nexport const EventSourceReadyState = {\n  /** Refers to the connection being established — including the browser's OWN automatic reconnection. */\n  Connecting: 0,\n  /** Refers to an open, streaming connection. */\n  Open: 1,\n  /** Refers to a connection the browser will not retry: a fatal error, or an explicit `close()`. */\n  Closed: 2,\n} as const;\n\n/**\n * Provides the `WebSocket.readyState` values from the WHATWG spec — `Closing` occupies `2`, where\n * `EventSource` puts `Closed`.\n */\nexport const SocketReadyState = {\n  /** Refers to a handshake in progress; `send()` throws here, which is why this slice queues instead. */\n  Connecting: 0,\n  /** Refers to an open socket ready for frames. */\n  Open: 1,\n  /** Refers to a close handshake in progress; frames sent now are discarded. */\n  Closing: 2,\n  /** Refers to a closed or failed socket. */\n  Closed: 3,\n} as const;\n","// The one place in this slice that decides WHEN to reconnect — and it decides nothing itself. Every delay\n// comes from `foundation/resilience`'s `computeRetryDelay`, and every \"should we even try again\" answer comes\n// from its `shouldRetry`. That slice owns retry POLICY (growth, jitter, cap, attempt budget); this scheduler\n// owns only the timer and the attempt counter. Changing how backoff behaves means editing `resilience`, never\n// this file — the same split `foundation/async`'s `retryAsync` follows.\n//\n// WHY A SHARED SCHEDULER RATHER THAN A `setTimeout` IN EACH TRANSPORT: both `createEventStream` and\n// `createSocketClient` need identical bookkeeping — the attempt count, the previous delay (decorrelated\n// jitter is a function of it), a cancellable handle, and a reset on success. Written twice they drift, and\n// the half that drifts is always the reset: a client that forgets to zero its counter after a successful\n// reconnect spends the rest of the session waiting the maximum delay after every blip.\n//\n// THE STACKING GUARD IS THE LOAD-BEARING PART. `schedule()` refuses to arm a second timer while one is\n// pending. Both transports can be told about the same failure through more than one path — a WebSocket that\n// errors then closes fires BOTH handlers, and an `EventSource` can report an error while a retry is already\n// waiting — and without this guard each path arms its own timer, so a single drop produces two connections.\n// Two sockets both \"work\", which is why this bug survives review: the symptom is duplicated messages and a\n// doubled server load, not an obvious failure.\n//\n// `shouldRetry` IS QUERIED WITH STATUS `0`. It grades HTTP statuses, and a dropped stream has none — `0` is\n// exactly the \"network / unknown\" code `resilience` reserves for that, and it is a member of\n// `DefaultTransientStatuses`, so a default policy treats a drop as transient. A caller who genuinely wants a\n// stream that never reconnects passes `retry: false` rather than fighting the status vocabulary.\n\nimport { BackoffStrategy, JitterStrategy, computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\n/** The status handed to `shouldRetry` for a transport-level drop — `resilience`'s \"network / unknown\" code. */\nconst TransportFailureStatus = 0;\n\n/**\n * Provides the default reconnect policy for a long-lived connection: unbounded attempts, exponential growth\n * from 1s, capped at 30s, with equal jitter.\n *\n * Differs from `DefaultRetryPolicy` in two ways that matter for a STREAM rather than a request. Attempts are\n * unbounded because a stream's failure mode is a server restart or a laptop lid, and giving up after two\n * tries leaves a dead page that no amount of waiting fixes — a request can surface an error to the caller,\n * a background stream has nobody to tell. And the jitter is `Equal`, not `Full`: full jitter can pick a delay\n * near zero, so a single client reconnecting to a flapping server hammers it immediately, whereas equal\n * jitter guarantees a floor of half the computed delay while still spreading a whole fleet apart.\n */\nexport const DefaultReconnectPolicy: RetryPolicy = {\n  maxRetries: Number.POSITIVE_INFINITY,\n  backoff: BackoffStrategy.Exponential,\n  baseDelayMs: 1_000,\n  maxDelayMs: 30_000,\n  jitter: JitterStrategy.Equal,\n};\n\n/** Configures a {@link createReconnectScheduler} instance. Every member is optional. */\nexport interface ReconnectSchedulerOptions {\n  /** Retry policy driving the delays, or `false` to disable reconnection. Default {@link DefaultReconnectPolicy}. */\n  readonly retry?: RetryPolicy | false;\n\n  /** The randomness feeding jitter — injectable so a test can pin an exact delay. Default `Math.random`. */\n  readonly random?: () => number;\n\n  /** Fires when an attempt is armed, before the wait — the seam for logging \"reconnecting in 4s (attempt 3)\". */\n  readonly onScheduled?: (attempt: number, delayMs: number) => void;\n}\n\n/** Schedules reconnection attempts with `foundation/resilience` backoff, at most one in flight. */\nexport interface ReconnectScheduler {\n  /** The number of consecutive attempts armed since the last {@link ReconnectScheduler.reset}. */\n  readonly attempts: number;\n\n  /** The delay (ms) of the attempt currently waiting, or `undefined` when none is pending. */\n  readonly pendingDelayMs: number | undefined;\n\n  /**\n   * Arms the next attempt after a `resilience`-computed delay.\n   *\n   * @param run - Invoked once the delay elapses. Not invoked if {@link ReconnectScheduler.cancel} lands first.\n   * @returns `true` when an attempt is pending afterwards — including when one was ALREADY pending and this\n   * call was absorbed by the stacking guard; `false` when reconnection is disabled or the budget is spent.\n   */\n  schedule(run: () => void): boolean;\n\n  /** Zeroes the attempt counter after a successful connection, so the next drop starts from the base delay again. */\n  reset(): void;\n\n  /** Cancels a pending attempt and clears its timer. Idempotent, and safe when nothing is pending. */\n  cancel(): void;\n}\n\n/**\n * Creates the reconnect scheduler shared by this slice's transports — one pending attempt at most, delays\n * and budget delegated wholly to `foundation/resilience`.\n *\n * @param options - The retry policy, randomness source, and scheduling hook.\n * @returns A scheduler; call `cancel()` when the owning transport closes, or its timer outlives it.\n */\nexport function createReconnectScheduler(options: ReconnectSchedulerOptions = {}): ReconnectScheduler {\n  const { retry = DefaultReconnectPolicy, random = Math.random, onScheduled } = options;\n\n  let attempts = 0;\n  let previousDelayMs = 0;\n  let pendingDelayMs: number | undefined;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  return {\n    get attempts() {\n      return attempts;\n    },\n\n    get pendingDelayMs() {\n      return pendingDelayMs;\n    },\n\n    schedule(run: () => void): boolean {\n      if (retry === false) return false;\n      // The stacking guard — see this file's header. Reporting `true` is correct: an attempt IS pending.\n      if (timer !== undefined) return true;\n      if (!shouldRetry(retry, attempts, TransportFailureStatus)) return false;\n\n      const attempt = attempts + 1;\n      const delayMs = computeRetryDelay(retry, attempt, previousDelayMs, random);\n\n      attempts = attempt;\n      previousDelayMs = delayMs;\n      pendingDelayMs = delayMs;\n\n      timer = setTimeout(() => {\n        // Blank both handles BEFORE running, so a `run` that fails and immediately re-schedules is not\n        // rejected by the stacking guard against its own already-fired timer.\n        timer = undefined;\n        pendingDelayMs = undefined;\n        run();\n      }, delayMs);\n\n      onScheduled?.(attempt, delayMs);\n      return true;\n    },\n\n    reset(): void {\n      attempts = 0;\n      previousDelayMs = 0;\n    },\n\n    cancel(): void {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      pendingDelayMs = undefined;\n    },\n  };\n}\n","// Server-Sent Events with typed named-event handlers and a reconnect that does NOT fight the browser's own.\n//\n// THE DOUBLE-RECONNECT TRAP, which is the whole reason this wrapper is subtle. `EventSource` already\n// reconnects by itself: on an ordinary drop the browser sets `readyState` back to `CONNECTING`, waits out its\n// own delay (the server can set it with a `retry:` field), and re-opens the SAME `EventSource` object. It\n// fires `error` while doing so. So the naive wrapper — \"on error, make a new `EventSource`\" — ends up with\n// TWO live connections for one drop: the browser's retry on the old object, plus the wrapper's new one. Each\n// subsequent drop doubles again. The symptom is duplicated events and a server that sees connection counts\n// climb, never a thrown error, which is why this ships to production so often.\n//\n// HOW THIS AVOIDS IT: the `error` handler branches on `source.readyState`, which is the only signal that\n// distinguishes the two cases.\n//   - `CONNECTING` (0) — the browser owns this retry and is already running it. The wrapper arms NO timer and\n//     builds NO `EventSource`; it only reports the error with `owner: 'browser'` and shows `reconnecting`.\n//   - `CLOSED` (2) — the browser has given up for good (a non-2xx response, a wrong content type, a bad\n//     CORS preflight; none of these are retried by the spec). Only here does the wrapper take over: it\n//     detaches its listeners, closes the dead object, and schedules a fresh connect on `resilience` backoff.\n// The two owners are therefore mutually exclusive by construction, and `ReconnectOwner` reports which one is\n// acting so a consumer can log it. The scheduler's own stacking guard backstops the invariant.\n//\n// WHY THE FATAL CASE STILL RETRIES AT ALL: the browser abandons the stream on a 502 from a proxy that is\n// restarting, or on the 401 that follows an expired token — both routinely fix themselves. Leaving the page\n// permanently dead because a gateway blinked is worse than a bounded reconnect, and a caller who disagrees\n// passes `retry: false`.\n//\n// NAMED EVENTS ARE A MAP, NOT A SWITCH. A server sending `event: order-updated` delivers to a listener\n// registered for that exact name, and NOT to `onmessage` — a detail that silently breaks the \"I subscribed to\n// onMessage but receive nothing\" case. `options.events` registers one real listener per key, and the generic\n// parameter types each payload independently.\n\nimport { toError } from '../errors';\nimport type { RetryPolicy } from '../resilience';\n\nimport { ConnectionState, EventSourceReadyState } from './ConnectionState';\nimport { createReconnectScheduler } from './Reconnect';\n\n/**\n * The minimal `EventSource` surface this wrapper drives. Narrow on purpose: a test double or a polyfill can\n * satisfy it in a few lines, and the real `EventSource` satisfies it structurally.\n */\nexport interface EventStreamSource {\n  /** The wire ready-state — see {@link EventSourceReadyState}. The branch the double-reconnect guard turns on. */\n  readonly readyState: number;\n\n  /** Closes the connection and stops the browser's own reconnection. */\n  close(): void;\n\n  /** Registers a listener for `open`, `error`, `message`, or a server-named event. */\n  addEventListener(type: string, listener: (event: Event) => void): void;\n\n  /** Removes a previously registered listener. */\n  removeEventListener(type: string, listener: (event: Event) => void): void;\n}\n\n/** Builds the underlying source — injectable so tests and polyfills need no global. */\nexport type EventStreamSourceFactory = (url: string, init: { withCredentials: boolean }) => EventStreamSource;\n\n/** Identifies who is retrying a broken stream — the guard against reconnecting on top of the browser. */\nexport const ReconnectOwner = {\n  /** Refers to the browser's own `EventSource` retry already being in flight; this wrapper stands down. */\n  Browser: 'browser',\n  /** Refers to the browser having given up, with this wrapper's `resilience`-scheduled retry pending. */\n  Wrapper: 'wrapper',\n  /** Refers to nobody retrying — reconnection is disabled, the attempt budget is spent, or the stream was closed. */\n  None: 'none',\n} as const;\n\nexport type ReconnectOwner = (typeof ReconnectOwner)[keyof typeof ReconnectOwner];\n\n/** Describes a stream failure — above all, who (if anyone) is going to do something about it. */\nexport interface EventStreamErrorContext {\n  /** Whoever is retrying this failure. See {@link ReconnectOwner}. */\n  readonly owner: ReconnectOwner;\n\n  /** The wrapper's consecutive attempt count; `0` while the browser owns the retry, since nothing is armed yet. */\n  readonly attempt: number;\n\n  /** The connection state after this failure was handled. */\n  readonly state: ConnectionState;\n}\n\n/**\n * Maps each server event name to the payload it carries — the generic every handler in\n * {@link EventStreamOptions.events} is typed from.\n */\nexport type EventStreamPayloads = Record<string, unknown>;\n\n/** Maps event names to their handlers, each typed by that event's payload. */\nexport type EventStreamHandlers<TEvents extends EventStreamPayloads> = {\n  readonly [K in keyof TEvents & string]?: (data: TEvents[K], event: MessageEvent<string>) => void;\n};\n\n/** Configures a {@link createEventStream} call. Every member is optional. */\nexport interface EventStreamOptions<TEvents extends EventStreamPayloads = EventStreamPayloads> {\n  /** Handlers for server-NAMED events (`event: order-updated`). Never reach {@link EventStreamOptions.onMessage}. */\n  readonly events?: EventStreamHandlers<TEvents>;\n\n  /** Handles unnamed events only — the default `message` type. */\n  readonly onMessage?: (data: unknown, event: MessageEvent<string>) => void;\n\n  /** Fires each time the connection opens, including after every reconnect. */\n  readonly onOpen?: () => void;\n\n  /** Fires on every failure, with the context saying who is retrying it. */\n  readonly onError?: (error: Error, context: EventStreamErrorContext) => void;\n\n  /** Fires on every connection-state transition — the seam for a \"reconnecting…\" indicator. */\n  readonly onStateChange?: (state: ConnectionState) => void;\n\n  /** Whether to send credentials cross-origin. Default `false`. */\n  readonly withCredentials?: boolean;\n\n  /**\n   * Decodes a frame's `data` text. Default: `JSON.parse`, falling back to the RAW STRING when the text is not\n   * JSON — SSE carries text, and plain-text frames and sentinels like `[DONE]` are common enough that\n   * throwing on them would be hostile. Supply this to be strict, or to decode another format.\n   */\n  readonly parse?: (raw: string) => unknown;\n\n  /**\n   * The reconnect policy for failures the browser abandons, or `false` to never reconnect.\n   * Default `DefaultReconnectPolicy`.\n   */\n  readonly retry?: RetryPolicy | false;\n\n  /** The randomness feeding backoff jitter — injectable for deterministic tests. Default `Math.random`. */\n  readonly random?: () => number;\n\n  /** The source factory. Default constructs a global `EventSource`; inject a double in tests. */\n  readonly eventSource?: EventStreamSourceFactory;\n}\n\n/** Controls a live Server-Sent Events subscription. */\nexport interface EventStream {\n  /** The current connection state — `reconnecting` covers both the browser's retry and this wrapper's. */\n  readonly readyState: ConnectionState;\n\n  /** Whether an `EventSource` implementation was available at all; `false` under SSR, where the stream is inert. */\n  readonly supported: boolean;\n\n  /** The wrapper's consecutive reconnect attempts, zeroed on every successful open. */\n  readonly attempts: number;\n\n  /**\n   * Closes the stream, cancels any pending reconnect, and detaches every listener. Idempotent; suppresses all\n   * further reconnection.\n   */\n  close(): void;\n}\n\n/** Decodes frame text as JSON, falling back to the raw string — see {@link EventStreamOptions.parse}. */\nfunction parseFrame(raw: string): unknown {\n  try {\n    return JSON.parse(raw) as unknown;\n  } catch {\n    return raw;\n  }\n}\n\n/** Reads a listener's event as a message frame; non-string `data` is coerced so a double can pass plain objects. */\nfunction frameTextOf(event: Event): { text: string; message: MessageEvent<string> } {\n  const message = event as MessageEvent<string>;\n  const data: unknown = message.data;\n  return { text: typeof data === 'string' ? data : String(data), message };\n}\n\n/** Resolves the source factory: the injected one, else global `EventSource`, else `undefined` (SSR / unsupported). */\nfunction resolveSourceFactory(injected?: EventStreamSourceFactory): EventStreamSourceFactory | undefined {\n  if (injected !== undefined) return injected;\n  if (typeof EventSource === 'undefined') return undefined;\n  return (url, init) => new EventSource(url, init);\n}\n\n/**\n * Opens a Server-Sent Events stream with typed named-event handlers and a reconnect that defers to the\n * browser's own — see this file's header for how the double-reconnect is avoided.\n *\n * Never throws, at import time or at call time. Where `EventSource` does not exist (SSR, a locked-down\n * runtime) the returned stream reports `supported: false` and state `closed`, and every method is a no-op —\n * a defined answer rather than an exception a render cannot catch.\n *\n * @typeParam TEvents - Maps each server event name to its payload type.\n * @param url - The stream endpoint.\n * @param options - Handlers, retry policy, parsing, and injection seams.\n * @returns The stream handle. ALWAYS call `close()` when done — an open `EventSource` survives navigation\n * within an SPA and keeps both the connection and every captured handler alive.\n */\nexport function createEventStream<TEvents extends EventStreamPayloads = EventStreamPayloads>(\n  url: string,\n  options: EventStreamOptions<TEvents> = {},\n): EventStream {\n  const {\n    events,\n    onMessage,\n    onOpen,\n    onError,\n    onStateChange,\n    withCredentials = false,\n    parse = parseFrame,\n    retry,\n    random,\n    eventSource,\n  } = options;\n\n  const factory = resolveSourceFactory(eventSource);\n  const scheduler = createReconnectScheduler({ retry, random });\n\n  let state: ConnectionState = ConnectionState.Connecting;\n  let source: EventStreamSource | undefined;\n  let detach: (() => void) | undefined;\n  let closed = false;\n\n  /** Publishes a state transition, skipping no-op repeats so a consumer's `onStateChange` is not spammed. */\n  const setState = (next: ConnectionState): void => {\n    if (state === next) return;\n    state = next;\n    onStateChange?.(next);\n  };\n\n  /** Reports a failure, tolerating a throwing consumer handler — a bad listener must not break the transport. */\n  const report = (error: unknown, owner: ReconnectOwner, attempt: number): void => {\n    try {\n      onError?.(toError(error), { owner, attempt, state });\n    } catch {\n      // Swallowed by contract: this runs from a DOM event handler, where a throw is unhandleable noise.\n    }\n  };\n\n  /** Binds every listener to a source and returns the matching detach — one closure so no listener can be missed. */\n  const bind = (target: EventStreamSource): (() => void) => {\n    const bound: [type: string, listener: (event: Event) => void][] = [];\n\n    /** Registers a listener and records it for the paired detach. */\n    const on = (type: string, listener: (event: Event) => void): void => {\n      target.addEventListener(type, listener);\n      bound.push([type, listener]);\n    };\n\n    on('open', () => {\n      // A successful open zeroes the attempt counter — otherwise a long-lived stream that blipped once\n      // spends the rest of the session starting from the maximum delay.\n      scheduler.reset();\n      setState(ConnectionState.Open);\n      onOpen?.();\n    });\n\n    // The `error` event itself carries nothing useful — the spec gives it no reason, no status, no body.\n    // Everything actionable is in `readyState`, which is why only the source is passed on.\n    on('error', () => handleError(target));\n\n    if (onMessage !== undefined) {\n      on('message', (event) => {\n        const { text, message } = frameTextOf(event);\n        onMessage(parse(text), message);\n      });\n    }\n\n    for (const name of Object.keys(events ?? {})) {\n      const handler = (events as Record<string, ((data: unknown, event: MessageEvent<string>) => void) | undefined>)[\n        name\n      ];\n      if (handler === undefined) continue;\n      on(name, (event) => {\n        const { text, message } = frameTextOf(event);\n        handler(parse(text), message);\n      });\n    }\n\n    return () => {\n      for (const entry of bound) target.removeEventListener(entry[0], entry[1]);\n      bound.length = 0;\n    };\n  };\n\n  /** Opens a source and binds it; a constructor throw (a malformed URL) is reported, not propagated. */\n  const connect = (): void => {\n    if (closed || factory === undefined) return;\n\n    setState(scheduler.attempts === 0 ? ConnectionState.Connecting : ConnectionState.Reconnecting);\n\n    let opened: EventStreamSource;\n    try {\n      opened = factory(url, { withCredentials });\n    } catch (error) {\n      const scheduled = scheduler.schedule(connect);\n      setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n      report(error, scheduled ? ReconnectOwner.Wrapper : ReconnectOwner.None, scheduler.attempts);\n      return;\n    }\n\n    source = opened;\n    detach = bind(opened);\n  };\n\n  /** The double-reconnect guard: branch on the wire ready-state, never retry what the browser is already retrying. */\n  function handleError(target: EventStreamSource): void {\n    if (closed) return;\n\n    // The browser is mid-reconnect on this very object. Arming anything here is the duplicate-connection bug.\n    if (target.readyState === EventSourceReadyState.Connecting) {\n      setState(ConnectionState.Reconnecting);\n      report(new Error(`The event stream to ${url} dropped; the browser is reconnecting.`), ReconnectOwner.Browser, 0);\n      return;\n    }\n\n    // `CLOSED` — the browser will do nothing further. Tear the dead object down completely before replacing\n    // it: an un-detached listener on a closed source still pins every closure it captured.\n    detach?.();\n    detach = undefined;\n    target.close();\n    source = undefined;\n\n    const scheduled = scheduler.schedule(connect);\n    setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n    report(\n      new Error(`The event stream to ${url} failed and the browser stopped retrying.`),\n      scheduled ? ReconnectOwner.Wrapper : ReconnectOwner.None,\n      scheduler.attempts,\n    );\n  }\n\n  if (factory === undefined) {\n    // Unsupported: a defined, inert answer. No throw, no listeners, no timers.\n    state = ConnectionState.Closed;\n    return {\n      get readyState() {\n        return state;\n      },\n      supported: false,\n      get attempts() {\n        return 0;\n      },\n      close: () => undefined,\n    };\n  }\n\n  connect();\n\n  return {\n    get readyState() {\n      return state;\n    },\n    supported: true,\n    get attempts() {\n      return scheduler.attempts;\n    },\n    close(): void {\n      if (closed) return;\n      closed = true;\n      scheduler.cancel();\n      detach?.();\n      detach = undefined;\n      source?.close();\n      source = undefined;\n      setState(ConnectionState.Closed);\n    },\n  };\n}\n","// Vue binding for `createEventStream` — one stream per scope, closed when the scope is disposed.\n//\n// THE LIFETIME RULE THIS ENFORCES: an `EventSource` is a live HTTP connection that outlives the component\n// that opened it. Nothing about unmounting a tree closes it, so a route change away from a page holding an\n// un-closed stream leaves the connection open, the handlers subscribed, and the reconnect timer armed — and\n// navigating back opens a SECOND one. Binding the stream to `onMounted` / `onScopeDispose` makes the teardown\n// automatic.\n//\n// OPENED FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `createEventStream` resolves `EventSource` inside\n// the call, and an immediate watcher also runs during a server render. `onMounted` is client-only by\n// construction, so the SSR pass reports `closed` / `supported: true` and the stream opens at hydration.\n//\n// HANDLERS ARE READ THROUGH `toValue` AT CALL TIME, the Vue counterpart of the original's handlers-in-a-ref.\n// A component's `setup` runs once, so a plain options object is already stable — but a caller that wants\n// genuinely live handlers can pass a ref or getter and every callback re-reads it per event, with the stream\n// itself staying put.\n//\n// OPTIONS ARE READ ONCE, when the stream opens. Changing `retry`, `events`, or `withCredentials` after mount\n// does NOT rebuild the stream; only `url` does. Options are configuration, not state — a consumer that must\n// genuinely swap them at runtime should remount with a `key`. This mirrors `useSyncChannel` in\n// `foundation/channels`.\n//\n// A `null` URL MEANS \"NOT YET\", not \"broken\" — the shape every real app needs while it waits for a token or a\n// route param. No stream is opened, and the state reads `closed`.\n\nimport { onMounted, onScopeDispose, shallowRef, toValue, watch, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport { ConnectionState } from '../ConnectionState';\nimport {\n  createEventStream,\n  type EventStream,\n  type EventStreamOptions,\n  type EventStreamPayloads,\n} from '../CreateEventStream';\n\n/** The live view a scope gets over its stream. */\nexport interface EventStreamHandle {\n  /** The current connection state, updating on every transition. */\n  readonly readyState: Readonly<ShallowRef<ConnectionState>>;\n\n  /** Whether `EventSource` exists in this runtime; `false` under SSR and in a locked-down browser. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /** Closes the stream early. The scope-disposal cleanup calls it anyway. */\n  readonly close: () => void;\n}\n\n/**\n * Opens a Server-Sent Events stream for the lifetime of the scope.\n *\n * The stream is closed when the scope is disposed and re-opened whenever `url` changes. Pass `null` to hold\n * off connecting (waiting for auth, a route param, a feature flag) — a ref or getter is how that flips.\n *\n * @typeParam TEvents - Maps each server event name to its payload type.\n * @param url - The stream endpoint, or `null` to stay disconnected.\n * @param options - Handlers and configuration, read once when the stream opens; handler callbacks are re-read\n *   per event, so a ref or getter keeps them live.\n * @returns The connection state, support flag, and `close`.\n */\nexport function useEventStream<TEvents extends EventStreamPayloads = EventStreamPayloads>(\n  url: MaybeRefOrGetter<string | null>,\n  options: MaybeRefOrGetter<EventStreamOptions<TEvents>> = {},\n): EventStreamHandle {\n  const readyState = shallowRef<ConnectionState>(\n    toValue(url) === null ? ConnectionState.Closed : ConnectionState.Connecting,\n  );\n  const supported = shallowRef(true);\n\n  let stream: EventStream | null = null;\n\n  function teardown(): void {\n    stream?.close();\n    stream = null;\n  }\n\n  function open(): void {\n    teardown();\n\n    const endpoint = toValue(url);\n    if (endpoint === null) {\n      readyState.value = ConnectionState.Closed;\n      return;\n    }\n\n    const current = toValue(options);\n    const next = createEventStream<TEvents>(endpoint, {\n      ...current,\n      // Every consumer callback is re-read through `toValue` at call time, which is what lets the watcher\n      // depend on `url` alone. `onStateChange` is additionally intercepted to drive this scope's own state.\n      onStateChange: (state) => {\n        readyState.value = state;\n        toValue(options).onStateChange?.(state);\n      },\n      onOpen: () => toValue(options).onOpen?.(),\n      onError: (error, context) => toValue(options).onError?.(error, context),\n      onMessage: (data, event) => toValue(options).onMessage?.(data, event),\n    });\n\n    stream = next;\n    supported.value = next.supported;\n    readyState.value = next.readyState;\n  }\n\n  onMounted(open);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `EventSource` is absent.\n  watch(() => toValue(url), open);\n  onScopeDispose(teardown);\n\n  const close = (): void => {\n    stream?.close();\n  };\n\n  return { readyState, supported, close };\n}\n","// A WebSocket client that fixes the three bugs every hand-rolled one has: dropped early sends, an\n// intentional close that reconnects anyway, and a half-open socket nobody notices.\n//\n// (1) MESSAGES SENT WHILE `CONNECTING` ARE LOST. A `WebSocket` is not usable the moment it is constructed —\n// the handshake takes a round trip, and `send()` during `CONNECTING` throws `InvalidStateError`. The bug is\n// not the throw; it is that the throw happens in code that looks obviously correct (`const s =\n// createSocket(); s.send(hello)`) and disappears on a fast local connection, so it ships. This client QUEUES\n// anything sent before `OPEN` and flushes it, in order, on open — the same queue that covers sends during a\n// reconnect, when the socket is `CONNECTING` again for seconds at a time.\n//\n// The queue is BOUNDED (`queueLimit`, default 100) and drops the OLDEST frame when full. Unbounded is not an\n// option: a tab left open through an hour-long outage would otherwise accumulate every frame the app ever\n// tried to send and hand the server all of them at once on reconnect. Oldest-first is the right end to drop\n// for the state-update traffic sockets usually carry, where the newest frame supersedes the ones behind it —\n// a caller whose messages are commands rather than state should keep `queueLimit` small and watch\n// `queuedCount`.\n//\n// (2) AN INTENTIONAL `close()` MUST NOT RECONNECT. `onclose` fires for a network drop and for a deliberate\n// close identically, so a reconnect handler wired to it fights every logout, unmount, and navigation — the\n// socket keeps coming back, usually with the OLD credentials. A single `closedByCaller` flag, set before the\n// close is requested, is the whole fix; every reconnect path checks it.\n//\n// (3) A HALF-OPEN SOCKET REPORTS `OPEN` FOREVER. When a peer vanishes without a close frame — a laptop lid, a\n// dropped NAT entry, a killed load balancer — TCP has nothing to report, so `onclose` never fires and\n// `readyState` stays `OPEN`. The connection is dead and the app cannot tell. The only detector is an\n// application-level heartbeat: send a ping, require traffic back within a deadline, treat silence as death\n// and reconnect. Note the ping MUST be application-level — the WebSocket protocol has real ping/pong frames,\n// but browsers expose no API to send one, so a server-side-only heartbeat cannot be observed from here.\n//\n// ANY INBOUND FRAME CLEARS THE PONG DEADLINE, not just a frame matching some pong shape. A socket delivering\n// data is alive by definition, so requiring a specific reply would kill healthy busy connections whose pong\n// is merely queued behind other traffic. This also means a server needs no pong support at all for the\n// heartbeat to be useful on a chatty socket.\n//\n// All reconnect delays come from `Reconnect.ts`, hence from `foundation/resilience`. None are computed here.\n\nimport { toError } from '../errors';\nimport type { RetryPolicy } from '../resilience';\n\nimport { ConnectionState, SocketReadyState } from './ConnectionState';\nimport { createReconnectScheduler } from './Reconnect';\n\n/** The default cap on frames buffered while the socket is not open. */\nconst DefaultQueueLimit = 100;\n\n/** The default ping frame — an application-level heartbeat, since browsers cannot send protocol pings. */\nconst DefaultPingFrame = (): string => JSON.stringify({ type: 'ping' });\n\n/**\n * The minimal `WebSocket` surface this client drives. Narrow on purpose: a test double satisfies it in a few\n * lines, and the real `WebSocket` satisfies it structurally.\n */\nexport interface SocketConnection {\n  /** The wire ready-state — see {@link SocketReadyState}. Gates every send. */\n  readonly readyState: number;\n\n  /** Sends one text frame. Throws while `CONNECTING`, which is exactly what the queue exists to prevent. */\n  send(data: string): void;\n\n  /** Starts the close handshake. */\n  close(code?: number, reason?: string): void;\n\n  /** Registers a listener for `open`, `close`, `error`, or `message`. */\n  addEventListener(type: string, listener: (event: Event) => void): void;\n\n  /** Removes a previously registered listener. */\n  removeEventListener(type: string, listener: (event: Event) => void): void;\n}\n\n/** Builds the underlying socket — injectable so tests and polyfills need no global. */\nexport type SocketFactory = (url: string, protocols?: string | ReadonlyArray<string>) => SocketConnection;\n\n/** Configures the liveness heartbeat that detects a half-open socket. */\nexport interface SocketHeartbeatOptions {\n  /** The interval (ms) between pings. */\n  readonly intervalMs: number;\n\n  /** The silence (ms) after a ping before the socket is declared dead and reconnected. Default: the interval. */\n  readonly timeoutMs?: number;\n\n  /** Builds the ping frame. Default `{\"type\":\"ping\"}`. Return the exact text your server expects. */\n  readonly ping?: () => string;\n}\n\n/** Configures a {@link createSocketClient} call. Every member is optional. */\nexport interface SocketClientOptions<TIn = unknown, TOut = unknown> {\n  /** The subprotocols offered during the handshake. */\n  readonly protocols?: string | ReadonlyArray<string>;\n\n  /** Receives every decoded inbound message. Frames that fail to decode go to {@link SocketClientOptions.onError}. */\n  readonly onMessage?: (message: TIn, event: MessageEvent) => void;\n\n  /** Fires each time the socket opens, including after every reconnect and BEFORE the queue is flushed. */\n  readonly onOpen?: () => void;\n\n  /** Fires on every close, with `wasClean` distinguishing a handshake close from a drop. */\n  readonly onClose?: (event: CloseEvent) => void;\n\n  /** Fires on a socket error, a decode failure, or a send that the transport rejected. */\n  readonly onError?: (error: Error) => void;\n\n  /** Fires on every connection-state transition — the seam for a \"reconnecting…\" indicator. */\n  readonly onStateChange?: (state: ConnectionState) => void;\n\n  /** Encodes an outbound message. Default `JSON.stringify`. */\n  readonly serialize?: (message: TOut) => string;\n\n  /** Decodes an inbound frame. Default `JSON.parse`. A throw here is reported, and the frame is dropped. */\n  readonly deserialize?: (raw: string) => TIn;\n\n  /** The reconnect policy, or `false` to never reconnect. Default `DefaultReconnectPolicy`. */\n  readonly retry?: RetryPolicy | false;\n\n  /** The half-open detector. Omit to disable heartbeating entirely. */\n  readonly heartbeat?: SocketHeartbeatOptions;\n\n  /** The cap on frames buffered while not open; the oldest is dropped when full. Default `100`. */\n  readonly queueLimit?: number;\n\n  /** The randomness feeding backoff jitter — injectable for deterministic tests. Default `Math.random`. */\n  readonly random?: () => number;\n\n  /** The socket factory. Default constructs a global `WebSocket`; inject a double in tests. */\n  readonly socket?: SocketFactory;\n}\n\n/** Controls a live WebSocket connection. */\nexport interface SocketClient<TOut = unknown> {\n  /** The current connection state. */\n  readonly readyState: ConnectionState;\n\n  /** Whether a `WebSocket` implementation was available at all; `false` under SSR, where the client is inert. */\n  readonly supported: boolean;\n\n  /** The number of frames buffered awaiting an open socket — non-zero means back-pressure or an outage. */\n  readonly queuedCount: number;\n\n  /** The consecutive reconnect attempts, zeroed on every successful open. */\n  readonly attempts: number;\n\n  /**\n   * Sends a message, queueing it when the socket is not open yet.\n   *\n   * @param message - The payload, encoded by `serialize`.\n   * @returns `true` when the frame went out immediately, `false` when it was queued or dropped.\n   */\n  send(message: TOut): boolean;\n\n  /** Closes the socket, cancels reconnection permanently, clears the heartbeat, detaches all listeners. Idempotent. */\n  close(code?: number, reason?: string): void;\n}\n\n/** Resolves the socket factory: the injected one, else the global `WebSocket`, else `undefined` (SSR / unsupported). */\nfunction resolveSocketFactory(injected?: SocketFactory): SocketFactory | undefined {\n  if (injected !== undefined) return injected;\n  if (typeof WebSocket === 'undefined') return undefined;\n  return (url, protocols) => new WebSocket(url, protocols as string | string[] | undefined);\n}\n\n/**\n * Opens a JSON WebSocket with a send queue, `resilience`-scheduled reconnection, and a half-open detector —\n * see this file's header for the three bugs each of those exists to prevent.\n *\n * Never throws, at import time or at call time. Where `WebSocket` does not exist (SSR) the returned client\n * reports `supported: false` and state `closed`, `send` returns `false`, and `close` is a no-op.\n *\n * @typeParam TIn - The decoded inbound message type.\n * @typeParam TOut - The outbound message type.\n * @param url - The socket endpoint (`ws://` or `wss://`).\n * @param options - Handlers, retry policy, heartbeat, codecs, and injection seams.\n * @returns The client handle. ALWAYS call `close()` when done — an abandoned socket keeps its connection, its\n * heartbeat timers, and every captured handler alive.\n */\nexport function createSocketClient<TIn = unknown, TOut = unknown>(\n  url: string,\n  options: SocketClientOptions<TIn, TOut> = {},\n): SocketClient<TOut> {\n  const {\n    protocols,\n    onMessage,\n    onOpen,\n    onClose,\n    onError,\n    onStateChange,\n    serialize = (message: TOut) => JSON.stringify(message),\n    deserialize = (raw: string) => JSON.parse(raw) as TIn,\n    retry,\n    heartbeat,\n    queueLimit = DefaultQueueLimit,\n    random,\n    socket: socketFactory,\n  } = options;\n\n  const factory = resolveSocketFactory(socketFactory);\n  const scheduler = createReconnectScheduler({ retry, random });\n\n  /** Frames buffered while the socket is not `OPEN`, oldest first. */\n  const queue: string[] = [];\n\n  let state: ConnectionState = ConnectionState.Connecting;\n  let connection: SocketConnection | undefined;\n  let detach: (() => void) | undefined;\n  let closedByCaller = false;\n  let pingTimer: ReturnType<typeof setInterval> | undefined;\n  let pongTimer: ReturnType<typeof setTimeout> | undefined;\n\n  /** Publishes a state transition, skipping no-op repeats. */\n  const setState = (next: ConnectionState): void => {\n    if (state === next) return;\n    state = next;\n    onStateChange?.(next);\n  };\n\n  /** Reports an error, tolerating a throwing consumer handler — a bad listener must not break the transport. */\n  const report = (error: unknown): void => {\n    try {\n      onError?.(toError(error));\n    } catch {\n      // Swallowed by contract: this runs from a DOM event handler, where a throw is unhandleable noise.\n    }\n  };\n\n  /** Stops both heartbeat timers. Runs on every close and every drop, so neither can outlive its socket. */\n  const stopHeartbeat = (): void => {\n    if (pingTimer !== undefined) {\n      clearInterval(pingTimer);\n      pingTimer = undefined;\n    }\n    if (pongTimer !== undefined) {\n      clearTimeout(pongTimer);\n      pongTimer = undefined;\n    }\n  };\n\n  /** Clears the pong deadline — called for ANY inbound frame, since traffic is proof of life. */\n  const noteTraffic = (): void => {\n    if (pongTimer !== undefined) {\n      clearTimeout(pongTimer);\n      pongTimer = undefined;\n    }\n  };\n\n  /** Tears the current socket down and reconnects — the path for a drop, NOT for a caller's close. */\n  const recycle = (): void => {\n    if (closedByCaller) return;\n\n    stopHeartbeat();\n    // Detach BEFORE closing: our own `close` would otherwise fire the close handler, which would schedule a\n    // second reconnect on top of this one.\n    detach?.();\n    detach = undefined;\n    const dying = connection;\n    connection = undefined;\n    try {\n      dying?.close();\n    } catch {\n      // A socket already dead rejects `close()` in some runtimes; nothing to recover.\n    }\n\n    const scheduled = scheduler.schedule(connect);\n    setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n  };\n\n  /** Starts the heartbeat for a freshly opened socket, if one is configured. */\n  const startHeartbeat = (): void => {\n    if (heartbeat === undefined) return;\n\n    const { intervalMs, timeoutMs = heartbeat.intervalMs, ping = DefaultPingFrame } = heartbeat;\n    if (!Number.isFinite(intervalMs) || intervalMs <= 0) return;\n\n    pingTimer = setInterval(() => {\n      const live = connection;\n      if (live === undefined || live.readyState !== SocketReadyState.Open) return;\n\n      try {\n        live.send(ping());\n      } catch (error) {\n        report(error);\n      }\n\n      // Arm the deadline only if one is not already running: back-to-back pings with no traffic between them\n      // must not each reset the clock, or a dead socket is never detected.\n      if (pongTimer !== undefined) return;\n      pongTimer = setTimeout(() => {\n        pongTimer = undefined;\n        report(new Error(`The socket to ${url} missed its heartbeat; treating it as half-open.`));\n        recycle();\n      }, timeoutMs);\n    }, intervalMs);\n  };\n\n  /** Writes every buffered frame in order on open. A rejected frame is reported and dropped, never re-queued. */\n  const flushQueue = (target: SocketConnection): void => {\n    const pending = queue.splice(0, queue.length);\n    for (const frame of pending) {\n      try {\n        target.send(frame);\n      } catch (error) {\n        report(error);\n      }\n    }\n  };\n\n  /** Binds every listener to a socket and returns the matching detach — one closure so no listener can be missed. */\n  const bind = (target: SocketConnection): (() => void) => {\n    const bound: [type: string, listener: (event: Event) => void][] = [];\n\n    /** Registers a listener and records it for the paired detach. */\n    const on = (type: string, listener: (event: Event) => void): void => {\n      target.addEventListener(type, listener);\n      bound.push([type, listener]);\n    };\n\n    on('open', () => {\n      scheduler.reset();\n      setState(ConnectionState.Open);\n      if (closedByCaller || connection !== target) return;\n      onOpen?.();\n      if (closedByCaller || connection !== target) return;\n      // Flush AFTER `onOpen`, so a handler that sends a subscribe/auth frame on connect lands ahead of the\n      // backlog rather than behind it — the ordering a protocol with a handshake requires.\n      flushQueue(target);\n      startHeartbeat();\n    });\n\n    on('message', (event) => {\n      noteTraffic();\n      if (onMessage === undefined) return;\n\n      const message = event as MessageEvent;\n      const data: unknown = message.data;\n      if (typeof data !== 'string') {\n        // Binary frames are out of scope for a JSON client; reporting beats silently dropping.\n        report(new Error(`The socket to ${url} delivered a non-text frame, which this client cannot decode.`));\n        return;\n      }\n\n      let decoded: TIn;\n      try {\n        decoded = deserialize(data);\n      } catch (error) {\n        report(error);\n        return;\n      }\n      onMessage(decoded, message);\n    });\n\n    on('error', () => {\n      // The `error` event carries no detail by design (it would leak cross-origin information). The close\n      // that follows is what actually drives reconnection.\n      report(new Error(`The socket to ${url} reported an error.`));\n    });\n\n    on('close', (event) => {\n      stopHeartbeat();\n      onClose?.(event as CloseEvent);\n      if (closedByCaller) return;\n\n      detach?.();\n      detach = undefined;\n      connection = undefined;\n\n      const scheduled = scheduler.schedule(connect);\n      setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n    });\n\n    return () => {\n      for (const entry of bound) target.removeEventListener(entry[0], entry[1]);\n      bound.length = 0;\n    };\n  };\n\n  /** Opens a socket and binds it; a constructor throw (a bad URL scheme) is reported and retried, not propagated. */\n  function connect(): void {\n    if (closedByCaller || factory === undefined) return;\n\n    setState(scheduler.attempts === 0 ? ConnectionState.Connecting : ConnectionState.Reconnecting);\n\n    let opened: SocketConnection;\n    try {\n      opened = factory(url, protocols);\n    } catch (error) {\n      report(error);\n      const scheduled = scheduler.schedule(connect);\n      setState(scheduled ? ConnectionState.Reconnecting : ConnectionState.Closed);\n      return;\n    }\n\n    connection = opened;\n    detach = bind(opened);\n  }\n\n  if (factory === undefined) {\n    // Unsupported: a defined, inert answer. No throw, no listeners, no timers.\n    state = ConnectionState.Closed;\n    return {\n      get readyState() {\n        return state;\n      },\n      supported: false,\n      get queuedCount() {\n        return 0;\n      },\n      get attempts() {\n        return 0;\n      },\n      send: () => false,\n      close: () => undefined,\n    };\n  }\n\n  connect();\n\n  return {\n    get readyState() {\n      return state;\n    },\n    supported: true,\n    get queuedCount() {\n      return queue.length;\n    },\n    get attempts() {\n      return scheduler.attempts;\n    },\n\n    send(message: TOut): boolean {\n      // A closed client silently drops rather than buffering forever — nothing will ever flush the queue.\n      if (closedByCaller) return false;\n\n      let frame: string;\n      try {\n        frame = serialize(message);\n      } catch (error) {\n        report(error);\n        return false;\n      }\n\n      const live = connection;\n      if (live !== undefined && live.readyState === SocketReadyState.Open) {\n        try {\n          live.send(frame);\n          return true;\n        } catch (error) {\n          // The socket claimed `OPEN` and refused anyway (a race with a close). Queue it for the reconnect\n          // rather than losing it.\n          report(error);\n        }\n      }\n\n      queue.push(frame);\n      if (queue.length > queueLimit) queue.splice(0, queue.length - queueLimit);\n      return false;\n    },\n\n    close(code?: number, reason?: string): void {\n      if (closedByCaller) return;\n      // Set BEFORE requesting the close, so the `close` event this triggers sees the flag and stands down.\n      closedByCaller = true;\n      scheduler.cancel();\n      stopHeartbeat();\n      queue.length = 0;\n\n      const dying = connection;\n      connection = undefined;\n      try {\n        dying?.close(code, reason);\n      } catch {\n        // A socket already dead rejects `close()` in some runtimes; nothing to recover.\n      }\n      detach?.();\n      detach = undefined;\n      setState(ConnectionState.Closed);\n    },\n  };\n}\n","// Vue binding for `createSocketClient` — one socket per scope, closed when the scope is disposed.\n//\n// THE LIFETIME RULE THIS ENFORCES: a `WebSocket` abandoned by its component stays connected, keeps its\n// heartbeat interval running, and keeps reconnecting on backoff — forever, since nothing else holds a\n// reference with which to close it. In an SPA that is one leaked socket per visit to the page, and the server\n// sees the connection count climb with no matching users. Binding the client to `onMounted` /\n// `onScopeDispose` makes the teardown automatic.\n//\n// OPENED FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `createSocketClient` resolves `WebSocket` inside\n// the call, and an immediate watcher also runs during a server render, where that global does not exist.\n//\n// THE RETURNED `send` IS ALWAYS SAFE TO CALL. It reads the current client from the closure, so it never goes\n// stale, and it works BEFORE the socket finishes connecting — the client's queue is what makes that true (see\n// `CreateSocketClient.ts`, bug 1). Calling it after disposal is a no-op rather than a crash, which matters\n// because an in-flight event handler routinely outlives the tree.\n//\n// HANDLERS ARE READ THROUGH `toValue` AT CALL TIME, options are read once, and a `null` URL means \"not yet\" —\n// same three rules as `useEventStream`, for the same reasons.\n\nimport { onMounted, onScopeDispose, shallowRef, toValue, watch, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport { ConnectionState } from '../ConnectionState';\nimport { createSocketClient, type SocketClient, type SocketClientOptions } from '../CreateSocketClient';\n\n/** The live view a scope gets over its socket. */\nexport interface SocketHandle<TOut> {\n  /** The current connection state, updating on every transition. */\n  readonly readyState: Readonly<ShallowRef<ConnectionState>>;\n\n  /** Whether `WebSocket` exists in this runtime; `false` under SSR. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /**\n   * Sends a message, queueing it while the socket is still connecting.\n   *\n   * @returns `true` when the frame went out immediately, `false` when queued, dropped, or disposed.\n   */\n  readonly send: (message: TOut) => boolean;\n\n  /** Closes the socket early and suppresses reconnection. The scope-disposal cleanup calls it anyway. */\n  readonly close: () => void;\n}\n\n/**\n * Opens a JSON WebSocket for the lifetime of the scope.\n *\n * The socket is closed when the scope is disposed and re-opened whenever `url` changes. Pass `null` to hold\n * off connecting (waiting for auth, a route param, a feature flag) — a ref or getter is how that flips.\n *\n * @typeParam TIn - The decoded inbound message type.\n * @typeParam TOut - The outbound message type.\n * @param url - The socket endpoint, or `null` to stay disconnected.\n * @param options - Handlers and configuration, read once when the socket opens; handler callbacks are re-read\n *   per message, so a ref or getter keeps them live.\n * @returns The connection state, support flag, and `send` / `close`.\n */\nexport function useSocket<TIn = unknown, TOut = unknown>(\n  url: MaybeRefOrGetter<string | null>,\n  options: MaybeRefOrGetter<SocketClientOptions<TIn, TOut>> = {},\n): SocketHandle<TOut> {\n  const readyState = shallowRef<ConnectionState>(\n    toValue(url) === null ? ConnectionState.Closed : ConnectionState.Connecting,\n  );\n  const supported = shallowRef(true);\n\n  let client: SocketClient<TOut> | null = null;\n\n  function teardown(): void {\n    client?.close();\n    client = null;\n  }\n\n  function open(): void {\n    teardown();\n\n    const endpoint = toValue(url);\n    if (endpoint === null) {\n      readyState.value = ConnectionState.Closed;\n      return;\n    }\n\n    const current = toValue(options);\n    const next = createSocketClient<TIn, TOut>(endpoint, {\n      ...current,\n      // Every consumer callback is re-read through `toValue` at call time, which is what lets the watcher\n      // depend on `url` alone. `onStateChange` is additionally intercepted to drive this scope's own state.\n      onStateChange: (state) => {\n        readyState.value = state;\n        toValue(options).onStateChange?.(state);\n      },\n      onOpen: () => toValue(options).onOpen?.(),\n      onClose: (event) => toValue(options).onClose?.(event),\n      onError: (error) => toValue(options).onError?.(error),\n      onMessage: (message, event) => toValue(options).onMessage?.(message, event),\n    });\n\n    client = next;\n    supported.value = next.supported;\n    readyState.value = next.readyState;\n  }\n\n  onMounted(open);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `WebSocket` is absent.\n  watch(() => toValue(url), open);\n  onScopeDispose(teardown);\n\n  const send = (message: TOut): boolean => client?.send(message) ?? false;\n\n  const close = (): void => {\n    client?.close();\n  };\n\n  return { readyState, supported, send, close };\n}\n","// Connectivity as a NON-VUE signal, for the factories in this slice that are plain functions and cannot\n// call a composable.\n//\n// RELATIONSHIP TO `foundation/device`'s `useOnlineStatus` — READ BEFORE ADDING ANOTHER TRACKER. That\n// composable is and remains THE Vue binding for connectivity; nothing here replaces it, and a component must\n// keep using it. But `createPoller` and `waitForOnline` are framework-agnostic factories called from timers,\n// effects, and `catch` blocks, where a composable is illegal. `device` keeps its reader module-private, so the\n// choice was to export a reader from `device` (widening a slice this one has no business editing, and one\n// another lane may be touching) or to keep a five-line reader here. This is the five-line reader, and it\n// MIRRORS the composable's\n// semantics deliberately: same optimistic default, same guarded read, same two events. If either changes,\n// change both.\n//\n// WHAT `navigator.onLine` IS WORTH, restated because every caller gets this wrong: `false` is trustworthy\n// (the browser knows there is no link); `true` only means a link exists — a captive portal, a dead VPN, or a\n// server that is simply down all report `true`. So this drives \"stop polling, nothing can succeed\" and\n// \"wait before retrying\", never \"we are online, therefore this will work\".\n//\n// `waitForOnline` RESOLVES A VERDICT AND NEVER THROWS, which is a deliberate deviation from `withTimeout` in\n// `foundation/async` (that one rejects with a `TimeoutError`). Every call site for this function is ALREADY\n// inside a failure path — a mutation just failed and the caller is deciding whether to retry. Rejecting\n// there forces a nested try/catch around the recovery logic to distinguish \"still offline\" from a real\n// fault, and a missed catch turns a recoverable failure into an unhandled rejection. A boolean reads as the\n// question actually being asked: `if (await waitForOnline({ timeoutMs: 5_000 })) retry();`.\n\n/**\n * Reads `navigator.onLine`, defaulting to online when there is no `navigator` (SSR), when the property is\n * missing (a partial polyfill), or when the read throws.\n *\n * Mirrors `useOnlineStatus`'s reader exactly — see this file's header for why the duplication is deliberate.\n *\n * @returns `true` while the browser reports a network link; optimistically `true` when unreadable.\n */\nexport function readOnlineStatus(): boolean {\n  try {\n    if (typeof navigator === 'undefined') return true;\n    return navigator.onLine !== false;\n  } catch {\n    return true;\n  }\n}\n\n/**\n * Subscribes to connectivity changes via the window `online` / `offline` events.\n *\n * A no-op returning a no-op disposer when there is no `window` (SSR), so callers need no environment branch.\n * The listener receives the new status, never a raw `Event`.\n *\n * @param listener - Invoked with `true` on `online` and `false` on `offline`.\n * @returns A disposer that detaches both listeners; safe to call more than once.\n */\nexport function subscribeOnline(listener: (online: boolean) => void): () => void {\n  if (typeof window === 'undefined') return () => undefined;\n\n  const target = window;\n  const onOnline = (): void => listener(true);\n  const onOffline = (): void => listener(false);\n\n  target.addEventListener('online', onOnline);\n  target.addEventListener('offline', onOffline);\n\n  let detached = false;\n  return () => {\n    if (detached) return;\n    detached = true;\n    target.removeEventListener('online', onOnline);\n    target.removeEventListener('offline', onOffline);\n  };\n}\n\n/** Configures a {@link waitForOnline} call. Every member is optional. */\nexport interface WaitForOnlineOptions {\n  /** Max wait (ms) before resolving `false`. Omit, or pass a non-positive value, to wait indefinitely. */\n  readonly timeoutMs?: number;\n\n  /** Abandons the wait early, resolving `false` — an abort is a \"stop waiting\" verdict here, never a rejection. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Waits for connectivity to come back, resolving `true` the moment it does.\n *\n * Resolves `true` immediately when already online, and `false` when the timeout lapses or the signal aborts —\n * never rejects, and never leaves a timer or a listener behind on any of those paths. Under SSR, or wherever\n * connectivity cannot be observed, it resolves `true` at once rather than hanging on an event that can never\n * arrive.\n *\n * Remember what a `true` verdict is worth (see this file's header): it says a link exists, not that the\n * server is reachable. Use it to gate a retry, then let the retry decide.\n *\n * @param options - The deadline and cancellation signal.\n * @returns `true` when connectivity is (or becomes) available; `false` on timeout or abort.\n */\nexport function waitForOnline(options: WaitForOnlineOptions = {}): Promise<boolean> {\n  const { timeoutMs, signal } = options;\n\n  if (readOnlineStatus()) return Promise.resolve(true);\n  if (signal?.aborted === true) return Promise.resolve(false);\n  // Nothing to listen on — an indefinite wait here could never be satisfied, so answer with the current read\n  // instead of hanging forever.\n  if (typeof window === 'undefined') return Promise.resolve(readOnlineStatus());\n\n  return new Promise<boolean>((resolve) => {\n    let settled = false;\n    let unsubscribe: (() => void) | undefined;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let onAbort: (() => void) | undefined;\n\n    /** The single teardown every exit path runs — timer, connectivity listeners, and abort listener alike. */\n    const cleanup = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      unsubscribe?.();\n      unsubscribe = undefined;\n      if (signal !== undefined && onAbort !== undefined) {\n        signal.removeEventListener('abort', onAbort);\n        onAbort = undefined;\n      }\n    };\n\n    /** Settles once and only once — three racing sources can all fire in the same tick. */\n    const finish = (online: boolean): void => {\n      if (settled) return;\n      settled = true;\n      cleanup();\n      resolve(online);\n    };\n\n    unsubscribe = subscribeOnline((online) => {\n      if (online) finish(true);\n    });\n\n    if (timeoutMs !== undefined && timeoutMs > 0 && Number.isFinite(timeoutMs)) {\n      timer = setTimeout(() => {\n        timer = undefined;\n        finish(false);\n      }, timeoutMs);\n    }\n\n    if (signal !== undefined) {\n      const listener = (): void => finish(false);\n      onAbort = listener;\n      signal.addEventListener('abort', listener, { once: true });\n    }\n  });\n}\n","// Interval polling that stops burning quota when nobody is looking.\n//\n// WHY A HIDDEN TAB MUST NOT POLL: a background tab is invisible, not closed. A 10-second poll left running\n// across a workday is thousands of requests nobody will ever see the result of — paid for in the user's\n// battery, the user's mobile data, and the API's rate limit, which is then unavailable to the tab the user is\n// actually looking at. Browsers throttle background timers, but throttling is not stopping: the requests\n// still go out, just less punctually. So this suspends on `visibilitychange` and, by default, refreshes\n// immediately on return, since data that went stale while hidden is the first thing the returning user reads.\n//\n// WHY OFFLINE MUST NOT POLL: every tick during an outage is a guaranteed failure. Left running it produces a\n// stream of errors that drowns the log, trips error-rate alerting, and — where the poll feeds a UI — flickers\n// a failure banner on a schedule. Suspending costs nothing, because the `online` event fires the moment there\n// is anything to poll for.\n//\n// SUSPENSION IS REASON-COUNTED, NOT A BOOLEAN, and this is the non-obvious part. Three independent things can\n// suspend the poller — the caller's `pause()`, a hidden tab, an offline browser — and with one flag they\n// overwrite each other: the tab regains focus, clears the flag, and silently resumes a poller the CALLER\n// paused, which is a real bug (a modal that paused polling reopens to a poller running behind it). A set of\n// reasons makes the rule exact: the poller ticks only when the set is empty, and `resume()` clears only the\n// caller's reason.\n//\n// TICKS DO NOT OVERLAP. Scheduling is a `setTimeout` CHAIN, re-armed after each run settles, not a\n// `setInterval`. With an interval, a poll slower than its period stacks: requests overlap, responses arrive\n// out of order, and the slowest response wins the UI — worse the more congested the network is, which is\n// exactly when it hurts. The chain makes `intervalMs` the gap BETWEEN runs, so a slow backend degrades to\n// polling less often instead of DDoSing itself.\n//\n// CONNECTIVITY IS READ THROUGH `Liveness.ts`, whose header explains why this slice has a non-Vue reader at\n// all instead of `foundation/device`'s `useOnlineStatus`.\n\nimport { toError } from '../errors';\n\nimport { readOnlineStatus, subscribeOnline } from './Liveness';\n\n/** The default gap between polls. */\nconst DefaultIntervalMs = 30_000;\n\n/** Names why a poller is suspended — a set of these, not a flag, so the reasons cannot overwrite each other. */\nconst SuspendReason = {\n  /** Refers to the caller's own `pause()`. Cleared only by `resume()`. */\n  Manual: 'manual',\n  /** Refers to a hidden tab. Cleared by `visibilitychange`. */\n  Hidden: 'hidden',\n  /** Refers to an offline browser. Cleared by the `online` event. */\n  Offline: 'offline',\n} as const;\n\ntype SuspendReason = (typeof SuspendReason)[keyof typeof SuspendReason];\n\n/** Describes what a poller is doing right now. */\nexport const PollerState = {\n  /** Refers to a poller created but not started. */\n  Idle: 'idle',\n  /** Refers to a poller with a tick scheduled or running. */\n  Running: 'running',\n  /** Refers to a started poller held by at least one suspend reason — paused, hidden, or offline. */\n  Paused: 'paused',\n  /** Refers to a stopped poller: timers cleared, listeners detached, restartable with `start()`. */\n  Stopped: 'stopped',\n} as const;\n\nexport type PollerState = (typeof PollerState)[keyof typeof PollerState];\n\n/** The work a poller repeats. A returned promise is awaited, so the next tick is scheduled only after it settles. */\nexport type PollFn = () => unknown;\n\n/** Configures a {@link createPoller} call. Every member is optional. */\nexport interface PollerOptions {\n  /** The gap (ms) between the end of one poll and the start of the next. Default `30000`. */\n  readonly intervalMs?: number;\n\n  /** Whether to start polling immediately on creation. Default `true`; `false` waits for `start()`. */\n  readonly autoStart?: boolean;\n\n  /** Whether to run one poll at once on start, rather than after the first interval. Default `false`. */\n  readonly immediate?: boolean;\n\n  /** Whether to suspend while the tab is hidden. Default `true`. */\n  readonly pauseWhenHidden?: boolean;\n\n  /** Whether to suspend while the browser reports no network link. Default `true`. */\n  readonly pauseWhenOffline?: boolean;\n\n  /**\n   * Whether returning from a suspension polls at once instead of waiting a full interval. Default `true` — the\n   * data is already stale.\n   */\n  readonly refreshOnResume?: boolean;\n\n  /**\n   * Receives an error thrown or rejected by the poll. The chain continues regardless — a failed poll is not a\n   * reason to stop polling.\n   */\n  readonly onError?: (error: Error) => void;\n\n  /** Fires on every state transition — the seam for a \"paused (offline)\" indicator. */\n  readonly onStateChange?: (state: PollerState) => void;\n}\n\n/** Controls a running poll loop. */\nexport interface Poller {\n  /** The current state. `paused` covers all three suspend reasons. */\n  readonly state: PollerState;\n\n  /** Starts (or restarts) polling. A no-op while already running. */\n  start(): void;\n\n  /** Suspends polling until `resume()`. Independent of the automatic hidden / offline suspensions. */\n  pause(): void;\n\n  /** Clears the caller's suspension. Polling stays suspended while the tab is hidden or the browser offline. */\n  resume(): void;\n\n  /** Stops polling, clears the pending timer, and detaches the visibility and connectivity listeners. Idempotent. */\n  stop(): void;\n}\n\n/** Reads `document.visibilityState`, defaulting to visible where there is no document (SSR) or the read throws. */\nfunction readHidden(): boolean {\n  try {\n    if (typeof document === 'undefined') return false;\n    return document.visibilityState === 'hidden';\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Subscribes to `visibilitychange`, reporting whether the document is now hidden.\n *\n * A no-op returning a no-op disposer where there is no `document`, so callers need no environment branch.\n */\nfunction subscribeVisibility(listener: (hidden: boolean) => void): () => void {\n  if (typeof document === 'undefined') return () => undefined;\n\n  const target = document;\n  const onChange = (): void => listener(readHidden());\n  target.addEventListener('visibilitychange', onChange);\n\n  let detached = false;\n  return () => {\n    if (detached) return;\n    detached = true;\n    target.removeEventListener('visibilitychange', onChange);\n  };\n}\n\n/**\n * Creates a poller that repeats `fn` on an interval and suspends itself while the tab is hidden or the\n * browser is offline — see this file's header for why both of those are non-negotiable.\n *\n * Never throws: an error from `fn` goes to `onError` and the loop continues, because a poll that failed once\n * is the poll most worth retrying. Ticks never overlap.\n *\n * @param fn - The work to repeat; a returned promise is awaited before the next tick is scheduled.\n * @param options - Interval, suspension behaviour, and hooks.\n * @returns The poller handle. ALWAYS call `stop()` when done — a live poller holds a timer and two document /\n * window listeners.\n */\nexport function createPoller(fn: PollFn, options: PollerOptions = {}): Poller {\n  const {\n    intervalMs = DefaultIntervalMs,\n    autoStart = true,\n    immediate = false,\n    pauseWhenHidden = true,\n    pauseWhenOffline = true,\n    refreshOnResume = true,\n    onError,\n    onStateChange,\n  } = options;\n\n  const suspended = new Set<SuspendReason>();\n\n  let state: PollerState = PollerState.Idle;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let running = false;\n  let inFlight = false;\n  let unsubscribeVisibility: (() => void) | undefined;\n  let unsubscribeOnline: (() => void) | undefined;\n\n  /** Publishes a state transition, skipping no-op repeats. */\n  const setState = (next: PollerState): void => {\n    if (state === next) return;\n    state = next;\n    onStateChange?.(next);\n  };\n\n  /** Clears the pending tick, if any. Never touches the listeners — suspension keeps them. */\n  const clearPending = (): void => {\n    if (timer !== undefined) {\n      clearTimeout(timer);\n      timer = undefined;\n    }\n  };\n\n  /** Arms the next tick. Refuses while stopped or suspended, which is what makes every suspend path a one-liner. */\n  const scheduleNext = (): void => {\n    if (!running || suspended.size > 0 || timer !== undefined) return;\n    timer = setTimeout(() => {\n      timer = undefined;\n      void tick();\n    }, intervalMs);\n  };\n\n  /** Runs one poll and re-arms — the chain that replaces `setInterval`. */\n  async function tick(): Promise<void> {\n    if (!running || suspended.size > 0 || inFlight) return;\n\n    inFlight = true;\n    try {\n      await fn();\n    } catch (error) {\n      try {\n        onError?.(toError(error));\n      } catch {\n        // Swallowed by contract: a throwing error handler must not break the loop it was told about.\n      }\n    } finally {\n      inFlight = false;\n    }\n\n    // Re-checked AFTER the await: the poll may have been stopped or suspended while it was in flight, and\n    // arming a timer for a poller that is already gone is exactly how a \"stopped\" poller keeps ticking.\n    scheduleNext();\n  }\n\n  /** Adds a suspend reason and parks the loop. */\n  const suspend = (reason: SuspendReason): void => {\n    if (suspended.has(reason)) return;\n    suspended.add(reason);\n    clearPending();\n    if (running) setState(PollerState.Paused);\n  };\n\n  /** Removes a suspend reason and, once none remain, resumes — immediately when `refreshOnResume`. */\n  const unsuspend = (reason: SuspendReason): void => {\n    if (!suspended.delete(reason)) return;\n    if (!running || suspended.size > 0) return;\n\n    setState(PollerState.Running);\n    if (refreshOnResume) void tick();\n    else scheduleNext();\n  };\n\n  /** Attaches the visibility and connectivity listeners and seeds the matching suspend reasons. */\n  const attachEnvironment = (): void => {\n    if (pauseWhenHidden) {\n      if (readHidden()) suspended.add(SuspendReason.Hidden);\n      unsubscribeVisibility = subscribeVisibility((hidden) => {\n        if (hidden) suspend(SuspendReason.Hidden);\n        else unsuspend(SuspendReason.Hidden);\n      });\n    }\n\n    if (pauseWhenOffline) {\n      if (!readOnlineStatus()) suspended.add(SuspendReason.Offline);\n      unsubscribeOnline = subscribeOnline((online) => {\n        if (online) unsuspend(SuspendReason.Offline);\n        else suspend(SuspendReason.Offline);\n      });\n    }\n  };\n\n  /** Detaches both environment listeners. Idempotent. */\n  const detachEnvironment = (): void => {\n    unsubscribeVisibility?.();\n    unsubscribeVisibility = undefined;\n    unsubscribeOnline?.();\n    unsubscribeOnline = undefined;\n  };\n\n  const poller: Poller = {\n    get state() {\n      return state;\n    },\n\n    start(): void {\n      if (running) return;\n      running = true;\n      // A restart begins from a clean slate — a stale `hidden` reason left over from the previous run would\n      // otherwise park the poller forever, since the event that would clear it has already fired.\n      suspended.clear();\n      attachEnvironment();\n\n      if (suspended.size > 0) {\n        setState(PollerState.Paused);\n        return;\n      }\n\n      setState(PollerState.Running);\n      if (immediate) void tick();\n      else scheduleNext();\n    },\n\n    pause(): void {\n      suspend(SuspendReason.Manual);\n    },\n\n    resume(): void {\n      unsuspend(SuspendReason.Manual);\n    },\n\n    stop(): void {\n      if (!running && state === PollerState.Stopped) return;\n      running = false;\n      clearPending();\n      detachEnvironment();\n      suspended.clear();\n      setState(PollerState.Stopped);\n    },\n  };\n\n  if (autoStart) poller.start();\n\n  return poller;\n}\n","import {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  unref,\n  watch,\n  type MaybeRef,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { PollerState, createPoller, type PollFn, type Poller, type PollerOptions } from '../CreatePoller';\n\n/** The live view a scope gets over its poll loop. */\nexport interface PollingHandle {\n  /** The current poller state, updating on every transition. `paused` covers manual, hidden, and offline. */\n  readonly state: Readonly<ShallowRef<PollerState>>;\n\n  /** Suspends polling until `resume()`. */\n  readonly pause: () => void;\n\n  /** Clears the manual suspension; polling stays suspended if the tab is hidden or the browser offline. */\n  readonly resume: () => void;\n\n  /** Stops the loop and detaches its listeners. The scope-disposal cleanup calls it anyway. */\n  readonly stop: () => void;\n}\n\n/**\n * Runs `fn` on an interval for the lifetime of the scope, suspended automatically while the tab is hidden or\n * the browser is offline.\n *\n * The loop stops when the scope is disposed and is rebuilt whenever `intervalMs` changes. `fn` is read fresh\n * on each tick, so a ref whose target changes needs no rebuild.\n *\n * @param fn - The work to repeat; a returned promise is awaited before the next tick is scheduled.\n * @param options - Interval and suspension behaviour, read once when the loop is built; handler callbacks are\n *   re-read per emission, so a ref or getter keeps them live.\n * @returns The poller state and `pause` / `resume` / `stop`.\n */\nexport function usePolling(fn: MaybeRef<PollFn>, options: MaybeRefOrGetter<PollerOptions> = {}): PollingHandle {\n  const state = shallowRef<PollerState>(PollerState.Idle);\n\n  let poller: Poller | null = null;\n\n  function teardown(): void {\n    poller?.stop();\n    poller = null;\n  }\n\n  function build(): void {\n    teardown();\n\n    const current = toValue(options);\n    const next = createPoller(() => unref(fn)(), {\n      ...current,\n      intervalMs: current.intervalMs,\n      onStateChange: (value) => {\n        state.value = value;\n        toValue(options).onStateChange?.(value);\n      },\n      onError: (error) => toValue(options).onError?.(error),\n    });\n\n    poller = next;\n    state.value = next.state;\n  }\n\n  onMounted(build);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `document` and `window` are\n  // absent. `intervalMs` alone is the rebuild trigger — the platform cannot retune a live interval.\n  watch(() => toValue(options).intervalMs, build);\n  onScopeDispose(teardown);\n\n  const pause = (): void => {\n    poller?.pause();\n  };\n\n  const resume = (): void => {\n    poller?.resume();\n  };\n\n  const stop = (): void => {\n    poller?.stop();\n  };\n\n  return { state, pause, resume, stop };\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/notifications/NotificationFailureCode.d.ts

@@ -0,0 +1,7 @@
+/** Closed failure vocabulary for NotificationFailure. */
+export declare const NotificationFailureCode: {
+    readonly Denied: "denied";
+    readonly Unsupported: "unsupported";
+    readonly Failed: "failed";
+};
+export type NotificationFailureCode = (typeof NotificationFailureCode)[keyof typeof NotificationFailureCode];

package/dist/foundation/notifications/NotificationPermission.d.ts

@@ -6,7 +6,18 @@
  * - `default` — not decided yet. The only state where {@link requestNotificationPermission} shows a prompt.
  * - `unsupported` — no Notification API here: SSR, a non-supporting browser, or an unreadable implementation.
  */
-export type NotificationPermissionState = 'granted' | 'denied' | 'default' | 'unsupported';
+export declare const NotificationPermissionState: {
+    /** Notifications will be shown. */
+    readonly Granted: "granted";
+    /** The user refused. The prompt will not reappear; only browser settings can undo it. */
+    readonly Denied: "denied";
+    /** Not decided yet — the only state where {@link requestNotificationPermission} shows a prompt. */
+    readonly Default: "default";
+    /** No Notification API here: SSR, a non-supporting browser, or an unreadable implementation. */
+    readonly Unsupported: "unsupported";
+};
+/** The state of this origin's notification grant. */
+export type NotificationPermissionState = (typeof NotificationPermissionState)[keyof typeof NotificationPermissionState];
 /**
  * Whether the environment exposes a constructible `Notification`. False under SSR and on non-supporting
  * browsers. Exported for the sibling modules; absent from the barrel — callers ask

package/dist/foundation/notifications/Notify.d.ts

@@ -1,25 +1,8 @@
-/**
- * The outcome of a notification attempt.
- *
- * - `shown` — handed to the OS, carrying the live handle. "Handed off", not "seen": the platform reports
- *   neither whether it was rendered nor whether the user looked at it.
- * - `denied` — the API exists but this origin holds no grant (refused, or never asked).
- * - `unsupported` — no Notification API here: SSR, or a non-supporting browser.
- * - `failed` — construction threw, carrying the normalized `Error`.
- */
-export type NotifyResult = {
-    readonly status: 'shown';
-    readonly notification: Notification;
-} | {
-    readonly status: 'denied';
-} | {
-    readonly status: 'unsupported';
-} | {
-    readonly status: 'failed';
-    readonly error: Error;
-};
-/** The `status` discriminant of a {@link NotifyResult} — for a consumer's own switch or status→copy map. */
-export type NotifyStatus = NotifyResult['status'];
+import { NotificationShowResult } from './models/NotificationShowResult';
+import { NotificationFailure } from './models/NotificationFailure';
+export type { NotificationFailure } from './models/NotificationFailure';
+export type { NotificationShowResult } from './models/NotificationShowResult';
+export type NotifyStatus = 'shown' | NotificationFailure['status'];
 /** Tunes a notification. Every member is optional; a bare `notify(title)` is valid. */
 export interface NotifyOptions {
     /** Body text rendered under the title. */
@@ -53,7 +36,7 @@ export interface NotifyOptions {
     readonly onClick?: (event: Event) => void;
 }
 /**
- * Shows an OS-level notification and returns a {@link NotifyResult}. Never throws.
+ * Shows an OS-level notification and returns a {@link NotificationShowResult}. Never throws.
  *
  * Requires a granted permission — this call never prompts. Pair it with `getNotificationPermission` /
  * `requestNotificationPermission` (or the `useNotificationPermission` hook) and treat `denied` as "ask first",
@@ -63,4 +46,4 @@ export interface NotifyOptions {
  * @param options Body, icon, tag, and the {@link NotifyOptions.autoCloseMs} / {@link NotifyOptions.onClick}
  *   conveniences this module adds on top of the platform dictionary.
  */
-export declare function notify(title: string, options?: NotifyOptions): NotifyResult;
+export declare function notify(title: string, options?: NotifyOptions): NotificationShowResult;

package/dist/foundation/notifications/QueryPermission.d.ts

@@ -6,7 +6,18 @@
  * - `unsupported` — no Permissions API, an unknown permission name, or an unreadable answer. Not a state the
  *   platform has; the wrapper's own "no usable answer".
  */
-export type PermissionQueryState = 'granted' | 'denied' | 'prompt' | 'unsupported';
+export declare const PermissionQueryState: {
+    /** The user allowed the capability; using it raises no prompt. */
+    readonly Granted: "granted";
+    /** The user refused. Only browser settings can undo it — stop asking. */
+    readonly Denied: "denied";
+    /** Not decided yet; requesting the capability will show a prompt. */
+    readonly Prompt: "prompt";
+    /** No usable answer came back — no Permissions API, an unknown name, or an off-spec state. Not `prompt`. */
+    readonly Unsupported: "unsupported";
+};
+/** The state of a queried permission. */
+export type PermissionQueryState = (typeof PermissionQueryState)[keyof typeof PermissionQueryState];
 /**
  * A permission name. The DOM's `PermissionName` union supplies autocomplete for the well-known names, and the
  * `string` arm keeps the door open for the ones a given engine ships ahead of the type definitions