@wow-two-beta/ui-vue 0.0.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/speech/SpeechSupport.ts","../../../src/foundation/speech/SpeechResult.ts","../../../src/foundation/speech/SpeechControls.ts","../../../src/foundation/speech/Speak.ts","../../../src/foundation/speech/ListVoices.ts","../../../src/foundation/speech/UseSpeechSynthesis.ts","../../../src/foundation/speech/SpeechRecognitionResult.ts","../../../src/foundation/speech/CreateSpeechRecognizer.ts","../../../src/foundation/speech/UseSpeechRecognition.ts"],"sourcesContent":["// Feature detection for BOTH halves of the speech vector, kept in one file because the two answers are\n// independent and a consumer that assumes otherwise ships a broken button. Firefox synthesizes speech perfectly\n// and recognizes none; a page in a sandboxed iframe can have neither. `getSpeechSupport()` therefore reports two\n// booleans, never one.\n//\n// Every read goes through an `unknown` cast rather than the DOM lib's `declare var speechSynthesis: SpeechSynthesis`\n// — outside a browser that global is genuinely missing, so the typed view is a lie this module must not act on.\n// The same posture as `foundation/media`'s `isKnownInsecureContext`.\n//\n// SYNTHESIS NEEDS TWO GLOBALS, not one. `speechSynthesis` is the controller and `SpeechSynthesisUtterance` is the\n// value it speaks; a page with the first and not the second (a partial polyfill, a stripped webview) would pass a\n// naive `'speechSynthesis' in window` check and then throw on `new SpeechSynthesisUtterance(...)` inside a click\n// handler. `canSpeak()` requires both.\n//\n// RECOGNITION IS PREFIXED. Chrome and Safari expose `webkitSpeechRecognition`; the unprefixed name exists in\n// newer Chrome. Both are checked, unprefixed first. Firefox exposes neither and is not a bug to work around —\n// there is no polyfill short of shipping audio to a server yourself.\n\nimport type { SpeechRecognitionConstructor } from './SpeechRecognitionTypes';\n\n/** What this environment can do. Two independent answers — no browser guarantees both, and Firefox gives one. */\nexport interface SpeechSupport {\n  /** Whether `speak` can reach a real `speechSynthesis` AND a real `SpeechSynthesisUtterance`. */\n  readonly synthesis: boolean;\n\n  /** Whether `createSpeechRecognizer` can reach a real (possibly `webkit`-prefixed) `SpeechRecognition`. */\n  readonly recognition: boolean;\n}\n\n/** A `SpeechSynthesisUtterance`-shaped constructor, as read off the global scope. */\nexport type UtteranceConstructor = new (text?: string) => SpeechSynthesisUtterance;\n\n/**\n * Reads `speechSynthesis` when it exists and carries `member` as a callable.\n *\n * Members are asked for one at a time because they fail one at a time: a polyfill can implement `speak` and\n * `cancel` while omitting `pause` / `resume` (which several mobile engines genuinely do not honour). Guarded\n * end-to-end; returns `undefined` under SSR. Internal to the slice — used by the sibling modules, absent from the\n * barrel.\n *\n * @param member The method the caller is about to invoke, or `speak` when it only needs to read a flag.\n * @returns The `SpeechSynthesis` object, or `undefined` when it or `member` is unusable.\n */\nexport function speechSynthesisWith(\n  member: 'speak' | 'cancel' | 'pause' | 'resume' | 'getVoices',\n): SpeechSynthesis | undefined {\n  try {\n    const candidate: unknown = (globalThis as { speechSynthesis?: unknown }).speechSynthesis;\n    if (typeof candidate !== 'object' || candidate === null) return undefined;\n\n    const api = candidate as SpeechSynthesis;\n    if (typeof api[member] !== 'function') return undefined;\n    return api;\n  } catch {\n    // A throwing global getter (a partial polyfill, a locked-down webview) reads as absent — the same posture as\n    // `foundation/media`'s `mediaDevicesWith` and `foundation/errors`' guarded member reads.\n    return undefined;\n  }\n}\n\n/**\n * Reads the `SpeechSynthesisUtterance` constructor.\n *\n * Separate from {@link speechSynthesisWith} because it is a separate global that can be separately missing.\n * Internal to the slice; absent from the barrel.\n *\n * @returns The constructor, or `undefined` under SSR / on a partial implementation.\n */\nexport function utteranceConstructor(): UtteranceConstructor | undefined {\n  try {\n    const candidate: unknown = (globalThis as { SpeechSynthesisUtterance?: unknown }).SpeechSynthesisUtterance;\n    return typeof candidate === 'function' ? (candidate as UtteranceConstructor) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Reads the `SpeechRecognition` constructor, unprefixed first, then `webkit`-prefixed.\n *\n * Unprefixed wins where both exist: it is the one newer Chrome maintains, and an engine shipping both aliases\n * them anyway. Internal to the slice; absent from the barrel.\n *\n * @returns The constructor, or `undefined` under SSR and in Firefox.\n */\nexport function speechRecognitionConstructor(): SpeechRecognitionConstructor | undefined {\n  try {\n    // Neither name exists in `lib.dom.d.ts`, so the cast goes through `unknown` — a direct assertion off\n    // `typeof globalThis` would be comparing against properties TypeScript does not know exist.\n    const scope = globalThis as unknown as {\n      SpeechRecognition?: unknown;\n      webkitSpeechRecognition?: unknown;\n    };\n\n    const candidate: unknown = scope.SpeechRecognition ?? scope.webkitSpeechRecognition;\n    return typeof candidate === 'function' ? (candidate as SpeechRecognitionConstructor) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Whether this environment can speak text aloud.\n *\n * Never throws. `false` under SSR, and `false` on a page carrying only one of the two required globals.\n *\n * @returns `true` when `speak` will reach a real engine.\n */\nexport function canSpeak(): boolean {\n  return speechSynthesisWith('speak') !== undefined && utteranceConstructor() !== undefined;\n}\n\n/**\n * Whether this environment can transcribe speech.\n *\n * A capability answer, NOT a permission answer: Chrome exposes the constructor to every page and only refuses at\n * `start()` — with `not-allowed` for a blocked microphone, or `service-not-allowed` on an insecure origin. Treat\n * `true` as \"the button is worth rendering\", never as \"this will work\".\n *\n * Never throws. `false` under SSR and in Firefox, which does not implement recognition at all.\n *\n * @returns `true` when a recognizer can be constructed.\n */\nexport function canRecognizeSpeech(): boolean {\n  return speechRecognitionConstructor() !== undefined;\n}\n\n/**\n * Reports both capabilities at once — the shape a consumer branches on when it renders a speak button, a dictate\n * button, or both.\n *\n * Never throws. Both `false` under SSR.\n *\n * @returns The two independent answers.\n */\nexport function getSpeechSupport(): SpeechSupport {\n  return { synthesis: canSpeak(), recognition: canRecognizeSpeech() };\n}\n","// The result vocabulary of the synthesis half, and the error-code table that produces it.\n//\n// The table's whole job is separating \"the app stopped this\" from \"the engine failed\". `speechSynthesis.cancel()`\n// reaches the utterance as an `error` event carrying `canceled` or `interrupted` — the same event shape a genuine\n// synthesis failure arrives in — so a consumer that reads every `error` as a failure raises a toast every time a\n// component unmounts mid-sentence. `cancelled` is therefore a status of its own, and never carries an `Error`.\n//\n// (`canceled`, one `l`, is the platform's spelling. The status this slice exposes is `cancelled` — matching the\n// repo's own English, and `foundation/share`'s `dismissed`, which draws the same line for the same reason.)\n//\n// Codes deliberately landing on `failed`, all carrying the real `Error`:\n//  - `audio-busy` / `audio-hardware` — the output device is unavailable. Retryable, but not by us.\n//  - `synthesis-unavailable` / `synthesis-failed` — the engine gave up on text it accepted.\n//  - `language-unavailable` / `voice-unavailable` — the requested `lang` / `voice` has no engine behind it. A\n//    consumer bug worth surfacing: silently falling back to the default voice hides a wrong language tag.\n//  - `text-too-long` / `invalid-argument` / `not-allowed` — programmer errors, and `not-allowed` specifically\n//    means synthesis was refused without a user gesture. All three deserve the error, not a soothing status.\n\n/**\n * The outcome of a {@link speak} attempt. Four arms because an utterance has four meaningfully different endings.\n *\n * - `spoken` — the engine reached the end of the text. It does NOT mean anyone heard it: the device may be muted.\n * - `cancelled` — something called `cancelSpeech` (or the handle's `cancel`) before it finished. A decision, not\n *   an error, and never reported as one.\n * - `unsupported` — no `speechSynthesis` / `SpeechSynthesisUtterance` here: SSR, or a stripped webview.\n * - `failed` — anything else, carrying the normalized `Error`.\n */\nexport type SpeakResult =\n  | { readonly status: 'spoken' }\n  | { readonly status: 'cancelled' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'failed'; readonly error: Error };\n\n/** The `status` discriminant of a {@link SpeakResult} — for a consumer's own switch or status→copy map. */\nexport type SpeakStatus = SpeakResult['status'];\n\n/** Codes that mean the app (or the user) stopped the utterance, rather than the engine failing to speak it. */\nconst CancellationCodes: ReadonlySet<string> = new Set(['canceled', 'cancelled', 'interrupted']);\n\n/**\n * Reads a caught / delivered value's `error` code as a string. Guarded: a throwing getter or a `Proxy` trap reads\n * as absent rather than escalating inside the handler that is already dealing with a failure.\n */\nfunction errorCodeOf(event: unknown): string | undefined {\n  if (event === null || (typeof event !== 'object' && typeof event !== 'function')) return undefined;\n\n  try {\n    const code: unknown = (event as Record<string, unknown>)['error'];\n    return typeof code === 'string' ? code : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Classifies a `SpeechSynthesisUtterance` `error` event into its {@link SpeakResult}.\n *\n * Exported for the sibling `Speak` module and its tests; absent from the barrel, where `speak` is the surface a\n * consumer wants. Never throws — an unrecognized or unreadable code becomes `failed` with an `Error` naming what\n * arrived, so even a hostile event produces a usable result.\n *\n * @param event The `error` event the platform delivered.\n * @returns `cancelled` for a cancellation code, `failed` for everything else.\n */\nexport function toSpeakFailure(event: unknown): SpeakResult {\n  const code = errorCodeOf(event);\n  if (code !== undefined && CancellationCodes.has(code)) return { status: 'cancelled' };\n\n  // The raw event rides along as `cause`, which `foundation/errors`' chain walkers already traverse safely\n  // (cycle-guarded, depth-capped) — so a log keeps the platform's own object without this module trusting it.\n  const error = new Error(`speech synthesis failed: ${code ?? 'unknown'}`, { cause: event });\n  return { status: 'failed', error };\n}\n","// The queue-level controls of the synthesis half — and the CANCEL GENERATION that lets `speak` tell \"the engine\n// reached the end of the text\" from \"something stopped it\".\n//\n// WHY A COUNTER EXISTS AT ALL: the platform has no per-utterance cancel. `speechSynthesis.cancel()` clears the\n// WHOLE queue, and what an interrupted utterance receives afterwards is engine-dependent — Chrome fires `end`\n// (byte-for-byte indistinguishable from a natural finish), Firefox fires `error` with `canceled`. An\n// `end`-means-spoken reading therefore reports success for a sentence the user cut off. Every `speak` records the\n// counter before speaking and re-reads it on settle: a bump in between means a cancel reached it, whoever called\n// it — this component's unmount, another component's button, or the handle's own `cancel()`.\n//\n// The bump happens BEFORE the platform call, not after. An engine (or a test double) that dispatches `end`\n// synchronously from inside `cancel()` would otherwise run the handler while the counter still held its old\n// value, and the utterance would report `spoken` for speech that was just cut off. Ordering the bump first makes\n// the observation correct for both dispatch timings; the cost is that a `cancel()` which throws still counts as\n// an intent to cancel, which is the right way round.\n//\n// EVERY CONTROL IS GLOBAL, and that is the platform's design, not a shortcut here: there is one utterance queue\n// per document. `cancelSpeech()` from one component silences another component's speech. Components that must\n// not interfere cannot be fixed at this layer — they have to coordinate above it.\n//\n// Platform caveat worth knowing before shipping a pause button: on Chrome for Android, `pause()` behaves like\n// `cancel()` — the utterance does not resume. `pauseSpeech` reports only that the call was made.\n\nimport { speechSynthesisWith } from './SpeechSupport';\n\n/** Bumped by every cancel that reaches a real engine. Read by `speak` to classify its own ending. */\nlet cancels = 0;\n\n/**\n * The current cancel generation.\n *\n * Internal to the slice — `Speak` samples it before speaking and compares on settle. Absent from the barrel: the\n * number means nothing on its own, and a consumer comparing two samples is reimplementing `speak`.\n *\n * @returns A monotonically increasing count of cancels that reached the engine.\n */\nexport function cancelGeneration(): number {\n  return cancels;\n}\n\n/**\n * Stops all speech and empties the utterance queue.\n *\n * GLOBAL: this silences every utterance in the document, not just the caller's. Any in-flight `speak` settles as\n * `cancelled` rather than `spoken` or `failed`.\n *\n * Never throws. A no-op under SSR.\n *\n * @returns `true` when a real engine was reached; `false` under SSR or when the call itself failed.\n */\nexport function cancelSpeech(): boolean {\n  const synth = speechSynthesisWith('cancel');\n  if (synth === undefined) return false;\n\n  cancels += 1;\n  try {\n    synth.cancel();\n    return true;\n  } catch {\n    // A `cancel()` that throws leaves speech running, and the generation already bumped — so an utterance that\n    // survives will report `cancelled`. That is the safe way to be wrong: a cancelled-looking result for speech\n    // the app asked to stop, rather than a `spoken` for speech it did not hear the end of.\n    return false;\n  }\n}\n\n/**\n * Pauses the current utterance, leaving the queue intact.\n *\n * Never throws. A no-op under SSR, and on engines that expose no `pause` (some mobile webviews). See the module\n * header for Chrome-on-Android's pause-is-cancel behaviour.\n *\n * @returns `true` when the call reached a real engine.\n */\nexport function pauseSpeech(): boolean {\n  const synth = speechSynthesisWith('pause');\n  if (synth === undefined) return false;\n\n  try {\n    synth.pause();\n    return true;\n  } catch {\n    // A partial implementation refusing the call is reported, never thrown — the caller is a click handler.\n    return false;\n  }\n}\n\n/**\n * Resumes speech paused by {@link pauseSpeech}.\n *\n * Never throws. A no-op under SSR.\n *\n * @returns `true` when the call reached a real engine.\n */\nexport function resumeSpeech(): boolean {\n  const synth = speechSynthesisWith('resume');\n  if (synth === undefined) return false;\n\n  try {\n    synth.resume();\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Whether the engine is speaking right now.\n *\n * Reads the platform's own flag rather than a locally tracked one, so it stays true for speech this module did\n * not start. Note it stays `true` while PAUSED — that is the spec's definition, not a bug; pair it with\n * {@link isSpeechPaused}.\n *\n * Never throws. `false` under SSR.\n *\n * @returns The engine's `speaking` flag.\n */\nexport function isSpeaking(): boolean {\n  const synth = speechSynthesisWith('speak');\n  if (synth === undefined) return false;\n\n  try {\n    return synth.speaking === true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Whether the engine is in a paused state.\n *\n * Never throws. `false` under SSR.\n *\n * @returns The engine's `paused` flag.\n */\nexport function isSpeechPaused(): boolean {\n  const synth = speechSynthesisWith('speak');\n  if (synth === undefined) return false;\n\n  try {\n    return synth.paused === true;\n  } catch {\n    return false;\n  }\n}\n","// One call, four outcomes, no throw — the speaking half of the vector.\n//\n// DEFINING CONTRACT: NOTHING HERE THROWS. `speak` is called straight from a click handler, where a rejection is\n// an unhandled error in the consumer's app and the user hears nothing and sees nothing. Every path — missing API,\n// a cancel, an engine failure, a hostile option object — settles to a `SpeakResult` the caller switches on.\n//\n// THE RETURN IS BOTH A RESULT AND A HANDLE. `await speak(text)` gives the `SpeakResult`; keeping the return value\n// gives `cancel` / `pause` / `resume` for speech that is still running. One object does both because the two are\n// wanted at different moments by the same caller, and a separate `speakWithHandle` would duplicate the module.\n// The handle is a `PromiseLike`, not a `Promise` subclass — awaiting is all a consumer needs, and `.spoken` is\n// there for anyone who wants the real promise.\n//\n// The handle's controls are HONESTLY GLOBAL: the platform has no per-utterance cancel, so `handle.cancel()` is\n// `cancelSpeech()` and clears the whole queue. Naming it on the handle is a convenience, not a narrowing.\n//\n// TWO ENGINE BUGS THIS MODULE ABSORBS:\n//  - Utterance garbage collection. Chrome and WebKit have collected a `SpeechSynthesisUtterance` whose only\n//    reference was the engine's own queue, and the utterance then falls silent with NO `end` event — a promise\n//    that never settles. A module-level `Set` holds every in-flight utterance until it settles, which is the\n//    known workaround and costs one reference per active utterance.\n//  - Out-of-range `rate` / `pitch` / `volume`. The spec has the setter throw; engines disagree on whether they\n//    throw or clamp. Values are clamped here BEFORE assignment, and a non-finite value is dropped rather than\n//    clamped — `NaN` means the caller computed something wrong, and the engine default is a better answer than\n//    an arbitrary pick from either end of the range.\n//\n// NOT worked around: Chrome stops synthesis after roughly 15 seconds of continuous speech. The known fix is a\n// `pause()`/`resume()` heartbeat on a timer, which interferes with the global queue every consumer shares. Long\n// text should be split into sentence-sized utterances by the caller instead.\n\nimport { toError } from '../errors';\n\nimport { cancelGeneration, cancelSpeech, pauseSpeech, resumeSpeech } from './SpeechControls';\nimport { speechSynthesisWith, utteranceConstructor } from './SpeechSupport';\nimport { toSpeakFailure, type SpeakResult } from './SpeechResult';\n\n/** Tunes one utterance. Every field is optional; an omitted one leaves the engine's own default in place. */\nexport interface SpeakOptions {\n  /** The voice to speak with — an entry from `listVoices()`. Omitted means the engine's default for `lang`. */\n  readonly voice?: SpeechSynthesisVoice;\n\n  /** BCP-47 language tag (`en-US`, `de`). Same vocabulary as `foundation/i18n`'s locale, which `useSpeechSynthesis` defaults it to. */\n  readonly lang?: string;\n\n  /** Speed, `0.1`–`10`, default `1`. Clamped to that range; a non-finite value is ignored. */\n  readonly rate?: number;\n\n  /** Pitch, `0`–`2`, default `1`. Clamped to that range; a non-finite value is ignored. */\n  readonly pitch?: number;\n\n  /** Volume, `0`–`1`, default `1`. Clamped to that range; a non-finite value is ignored. */\n  readonly volume?: number;\n}\n\n/**\n * The return of {@link speak}: awaitable for the outcome, and callable for control while it runs.\n *\n * All three controls are GLOBAL — the platform exposes no per-utterance cancel or pause, so they act on the\n * document's whole utterance queue.\n */\nexport interface SpeechHandle extends PromiseLike<SpeakResult> {\n  /** The underlying promise, for a caller that wants to store or pass it. Never rejects. */\n  readonly spoken: Promise<SpeakResult>;\n\n  /** Stops this utterance — and every other queued one. Settles the handle as `cancelled`. */\n  readonly cancel: () => void;\n\n  /** Pauses the engine. See `SpeechControls` for Chrome-on-Android's pause-is-cancel behaviour. */\n  readonly pause: () => void;\n\n  /** Resumes a paused engine. */\n  readonly resume: () => void;\n}\n\n/**\n * Holds a reference to every utterance the engine is still working on, defeating the GC bug described in the\n * module header. Cleared on settle, so a page that speaks all day does not accumulate.\n */\nconst inFlight = new Set<SpeechSynthesisUtterance>();\n\n/** Clamps to a spec range, dropping non-finite values so the engine keeps its own default. */\nfunction clamp(value: number | undefined, min: number, max: number): number | undefined {\n  if (value === undefined || !Number.isFinite(value)) return undefined;\n  return Math.min(max, Math.max(min, value));\n}\n\n/** Applies `options` to `utterance`, guarded — an engine may refuse a setter, and a refusal must not throw. */\nfunction configure(utterance: SpeechSynthesisUtterance, options: SpeakOptions | undefined): void {\n  if (options === undefined) return;\n\n  try {\n    if (options.voice !== undefined) utterance.voice = options.voice;\n    if (options.lang !== undefined) utterance.lang = options.lang;\n\n    const rate = clamp(options.rate, 0.1, 10);\n    if (rate !== undefined) utterance.rate = rate;\n\n    const pitch = clamp(options.pitch, 0, 2);\n    if (pitch !== undefined) utterance.pitch = pitch;\n\n    const volume = clamp(options.volume, 0, 1);\n    if (volume !== undefined) utterance.volume = volume;\n  } catch {\n    // A setter that refused its value leaves the engine default in place, which is speakable. Losing the tuning\n    // is strictly better than losing the utterance.\n  }\n}\n\n/** Wraps a promise and a set of controls into the awaitable handle. */\nfunction toHandle(spoken: Promise<SpeakResult>, controls: Omit<SpeechHandle, 'spoken' | 'then'>): SpeechHandle {\n  return {\n    spoken,\n    cancel: controls.cancel,\n    pause: controls.pause,\n    resume: controls.resume,\n    then: <TResult1 = SpeakResult, TResult2 = never>(\n      onFulfilled?: ((value: SpeakResult) => TResult1 | PromiseLike<TResult1>) | null,\n      onRejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,\n    ): PromiseLike<TResult1 | TResult2> => spoken.then(onFulfilled, onRejected),\n  };\n}\n\n/** The controls of a handle for speech that never started — every one a no-op. */\nfunction inertControls(): Omit<SpeechHandle, 'spoken' | 'then'> {\n  const noop = (): void => {\n    // Nothing is speaking, so there is nothing to cancel, pause, or resume.\n  };\n  return { cancel: noop, pause: noop, resume: noop };\n}\n\n/**\n * Speaks `text` aloud, settling when the utterance ends.\n *\n * ```ts\n * const result = await speak('Order confirmed', { lang: 'en-GB', rate: 1.1 });\n * if (result.status === 'unsupported') showTextInstead();\n *\n * const handle = speak(longArticle);\n * stopButton.onclick = () => handle.cancel(); // settles as `cancelled`\n * ```\n *\n * Call it from a user gesture where possible: some engines refuse synthesis without one (arriving as `failed`\n * with a `not-allowed` code, since the API was present).\n *\n * Never throws, never rejects.\n *\n * @param text The text to speak. Empty text is handed to the engine unchanged — engines differ on whether they\n *   fire `end` for it, which is exactly the kind of thing a caller should not have to guess about mid-sentence.\n * @param options Voice, language, and prosody. Out-of-range prosody is clamped; see {@link SpeakOptions}.\n * @returns The awaitable handle — `spoken` / `cancelled` / `unsupported` / `failed`, plus the live controls.\n */\nexport function speak(text: string, options?: SpeakOptions): SpeechHandle {\n  const synth = speechSynthesisWith('speak');\n  const Utterance = utteranceConstructor();\n\n  // Both globals or nothing: an engine with no `SpeechSynthesisUtterance` cannot be given anything to say.\n  if (synth === undefined || Utterance === undefined) {\n    return toHandle(Promise.resolve({ status: 'unsupported' }), inertControls());\n  }\n\n  let settle!: (result: SpeakResult) => void;\n  const spoken = new Promise<SpeakResult>((resolve) => {\n    settle = resolve;\n  });\n\n  let settled = false;\n  let utterance: SpeechSynthesisUtterance | undefined;\n\n  /** Settles once and drops the GC-guard reference. Engines fire both `end` and `error` in some cancel paths. */\n  const finish = (result: SpeakResult): void => {\n    if (settled) return;\n    settled = true;\n    if (utterance !== undefined) inFlight.delete(utterance);\n    settle(result);\n  };\n\n  try {\n    utterance = new Utterance(text);\n  } catch (cause) {\n    // A constructor that refused the text (a hostile value, a stripped polyfill) is a failure of this call, not\n    // an absence of the feature — `unsupported` would send the caller looking for the wrong fix.\n    return toHandle(Promise.resolve({ status: 'failed', error: toError(cause) }), inertControls());\n  }\n\n  configure(utterance, options);\n\n  // Sampled BEFORE `speak`, so any cancel from this point on — ours or another component's — is observable when\n  // the ending arrives. See `SpeechControls` for why an `end` event alone cannot answer this.\n  const generation = cancelGeneration();\n  const wasCancelled = (): boolean => cancelGeneration() !== generation;\n\n  utterance.onend = (): void => {\n    finish(wasCancelled() ? { status: 'cancelled' } : { status: 'spoken' });\n  };\n\n  utterance.onerror = (event): void => {\n    // A cancel we already know about wins over the code: engines disagree on which code a cancelled utterance\n    // carries (`canceled`, `interrupted`, and Safari has shipped others), and the counter is not a guess.\n    finish(wasCancelled() ? { status: 'cancelled' } : toSpeakFailure(event));\n  };\n\n  inFlight.add(utterance);\n\n  try {\n    synth.speak(utterance);\n  } catch (cause) {\n    finish({ status: 'failed', error: toError(cause) });\n  }\n\n  return toHandle(spoken, {\n    cancel: (): void => {\n      cancelSpeech();\n    },\n    pause: (): void => {\n      pauseSpeech();\n    },\n    resume: (): void => {\n      resumeSpeech();\n    },\n  });\n}\n","// THE most common bug in this API, and the reason this file exists: `speechSynthesis.getVoices()` returns an\n// EMPTY ARRAY on first call. The voice list is populated asynchronously — Chrome fetches remote voices, and every\n// engine loads them off the main thread — so a component that renders `getVoices()` on mount renders an empty\n// picker, forever, because nothing re-renders it when the list lands. The signal is a `voiceschanged` event, and\n// the fix a consumer eventually writes by hand is exactly `listVoices`.\n//\n// `listVoices` therefore returns a PROMISE that waits for the list, with three subtleties the naive version\n// misses, each of which turns the wait back into an empty array:\n//  1. `voiceschanged` can fire with the list STILL empty. Chrome fires it once during initialization before any\n//     voice is registered. Resolving there hands back exactly the empty array this function exists to avoid, so\n//     an empty payload is ignored and the wait continues.\n//  2. Some engines never fire the event at all — they simply populate the list a few hundred milliseconds in.\n//     The timeout therefore RE-READS `getVoices()` rather than resolving with what it had at subscribe time, so a\n//     silent late population still lands.\n//  3. The wait must be bounded. On a device with genuinely no voices the event never comes, and an unbounded\n//     promise would hang the component that awaited it. `DefaultVoicesTimeoutMs` bounds it and resolves with\n//     whatever exists — possibly nothing, which is a truthful answer a UI can render.\n//\n// The subscription supports BOTH wiring styles. Older WebKit exposes only the `onvoiceschanged` property and no\n// `addEventListener` for it; where the property is used, the previous handler is chained and restored on\n// unsubscribe rather than clobbered, so this slice cannot silently break a consumer's own listener.\n//\n// Language matching lives here too (`voicesForLang`), because \"the voices for this locale\" is what a caller\n// actually wants and BCP-47 tags do not compare with `===`: a `de` request must match a `de-DE` voice, and engines\n// report tags in mixed case and occasionally with an underscore (`en_US`).\n\nimport { speechSynthesisWith } from './SpeechSupport';\n\n/** How long {@link listVoices} waits for a populated list before answering with whatever exists. */\nexport const DefaultVoicesTimeoutMs = 1000;\n\n/** The empty answer, shared so an unsupported environment does not allocate a new array per call. */\nconst NoVoices: readonly SpeechSynthesisVoice[] = [];\n\n/** Tunes the wait for an asynchronously-populated voice list. */\nexport interface ListVoicesOptions {\n  /** How long to wait for `voiceschanged` before resolving with whatever exists. Defaults to `1000`. */\n  readonly timeoutMs?: number;\n}\n\n/** Reads the engine's current list, guarded — a partial polyfill can return a non-array or throw outright. */\nfunction readVoices(synth: SpeechSynthesis): readonly SpeechSynthesisVoice[] {\n  try {\n    const voices: unknown = synth.getVoices();\n    return Array.isArray(voices) ? (voices as SpeechSynthesisVoice[]) : NoVoices;\n  } catch {\n    return NoVoices;\n  }\n}\n\n/**\n * The synchronous snapshot of the installed voices.\n *\n * OFTEN EMPTY on first paint — that is the platform behaviour this module exists to absorb, not a failure. Use it\n * only where an empty answer is acceptable (a re-render triggered by something else); prefer {@link listVoices}\n * anywhere the answer drives UI.\n *\n * Never throws. `[]` under SSR.\n *\n * @returns The voices the engine has registered so far.\n */\nexport function listVoicesSync(): readonly SpeechSynthesisVoice[] {\n  const synth = speechSynthesisWith('getVoices');\n  return synth === undefined ? NoVoices : readVoices(synth);\n}\n\n/**\n * Subscribes to `voiceschanged`.\n *\n * Exported for the sibling composable, which re-reads the list when the engine revises it (Chrome does, after remote\n * voices load). Absent from the barrel — a consumer wants `useSpeechSynthesis`'s `voices`, not an event.\n *\n * Never throws. A no-op under SSR, where the returned unsubscribe is still safe to call.\n *\n * @param listener Called whenever the engine reports a change. Receives no arguments; re-read the list.\n * @returns The unsubscribe function.\n */\nexport function onVoicesChanged(listener: () => void): () => void {\n  const noop = (): void => {\n    // Nothing was subscribed, so there is nothing to tear down.\n  };\n\n  const synth = speechSynthesisWith('getVoices');\n  if (synth === undefined) return noop;\n\n  try {\n    if (typeof synth.addEventListener === 'function') {\n      synth.addEventListener('voiceschanged', listener);\n      return (): void => {\n        try {\n          synth.removeEventListener('voiceschanged', listener);\n        } catch {\n          // A polyfill that accepted the listener but refuses to remove it leaves one live closure. Throwing from\n          // an unsubscribe — usually an effect cleanup — would be far worse than that leak.\n        }\n      };\n    }\n\n    // Older WebKit: property-only wiring. Chain rather than clobber, so a consumer's own handler survives us.\n    const previous = synth.onvoiceschanged;\n    synth.onvoiceschanged = function (this: SpeechSynthesis, event: Event): void {\n      if (typeof previous === 'function') previous.call(this, event);\n      listener();\n    };\n    return (): void => {\n      synth.onvoiceschanged = previous;\n    };\n  } catch {\n    return noop;\n  }\n}\n\n/**\n * Lists the installed voices, WAITING for the asynchronously-populated list rather than returning the empty array\n * a first `getVoices()` hands back.\n *\n * Resolves immediately when the list is already populated — the common case on every call after the first.\n *\n * ```ts\n * const voices = await listVoices();\n * const german = voices.filter((voice) => voice.lang.startsWith('de'));\n * ```\n *\n * Never throws, never rejects. Resolves to `[]` under SSR, and to `[]` on a device that genuinely has no voices\n * (after the timeout).\n *\n * @param options The wait bound. Defaults to {@link DefaultVoicesTimeoutMs}.\n * @returns The voices, or `[]`.\n */\nexport function listVoices(options?: ListVoicesOptions): Promise<readonly SpeechSynthesisVoice[]> {\n  const synth = speechSynthesisWith('getVoices');\n  if (synth === undefined) return Promise.resolve(NoVoices);\n\n  const immediate = readVoices(synth);\n  if (immediate.length > 0) return Promise.resolve(immediate);\n\n  return new Promise<readonly SpeechSynthesisVoice[]>((resolve) => {\n    let settled = false;\n\n    // `settle` closes over `unsubscribe` and `timer`, both declared below. Safe because neither the subscription\n    // nor the timer can call back synchronously — `onVoicesChanged` only registers, and a timeout is a task.\n    const settle = (): void => {\n      if (settled) return;\n      settled = true;\n      clearTimeout(timer);\n      unsubscribe();\n      // Re-read rather than close over an earlier snapshot: on the timeout path this is what catches an engine\n      // that populated the list without ever firing the event.\n      resolve(readVoices(synth));\n    };\n\n    const unsubscribe = onVoicesChanged((): void => {\n      // An event carrying an empty list is not an answer — keep waiting for a real one, or for the deadline.\n      if (readVoices(synth).length === 0) return;\n      settle();\n    });\n\n    const timer = setTimeout(settle, options?.timeoutMs ?? DefaultVoicesTimeoutMs);\n  });\n}\n\n/** Normalizes a BCP-47 tag for comparison: trimmed, lower-cased, and `en_US`-style separators repaired. */\nfunction normalizeTag(tag: string): string {\n  return tag.trim().toLowerCase().replace(/_/g, '-');\n}\n\n/** The primary language subtag — `de` from `de-AT`. The unit a fallback match is made on. */\nfunction primarySubtag(tag: string): string {\n  return normalizeTag(tag).split('-')[0] ?? '';\n}\n\n/** Sorts the engine's default voice first within a tier; otherwise preserves the engine's own order. */\nfunction defaultFirst(voices: readonly SpeechSynthesisVoice[]): readonly SpeechSynthesisVoice[] {\n  return [...voices].sort((left, right) => Number(right.default === true) - Number(left.default === true));\n}\n\n/**\n * Filters voices to a language tag, exact matches first, then same-primary-subtag ones.\n *\n * Pure — takes the list rather than fetching it, so it is trivially testable and reusable on a list a consumer\n * already holds. Tag comparison is case-insensitive and tolerates the `en_US` separator some engines report.\n *\n * The two tiers are kept in order rather than collapsed because they are not equivalent: `en-GB` text read by an\n * `en-US` voice is understandable, so it belongs in the list — but never ahead of an actual `en-GB` voice.\n *\n * @param voices The list to filter, typically from {@link listVoices}.\n * @param lang A BCP-47 tag (`de`, `en-GB`). Same vocabulary as `foundation/i18n`'s locale.\n * @returns The matching voices, best match first. Empty when nothing matches.\n */\nexport function voicesForLang(\n  voices: readonly SpeechSynthesisVoice[],\n  lang: string,\n): readonly SpeechSynthesisVoice[] {\n  const wanted = normalizeTag(lang);\n  if (wanted === '') return NoVoices;\n\n  const wantedPrimary = primarySubtag(wanted);\n  const exact: SpeechSynthesisVoice[] = [];\n  const related: SpeechSynthesisVoice[] = [];\n\n  for (const voice of voices) {\n    const tag = typeof voice.lang === 'string' ? normalizeTag(voice.lang) : '';\n    if (tag === '') continue;\n\n    if (tag === wanted) exact.push(voice);\n    else if (primarySubtag(tag) === wantedPrimary) related.push(voice);\n  }\n\n  return [...defaultFirst(exact), ...defaultFirst(related)];\n}\n\n/**\n * Picks the best voice for a language tag, waiting for the voice list the same way {@link listVoices} does.\n *\n * ```ts\n * const voice = await findVoice('de-DE');\n * await speak('Guten Tag', { voice, lang: 'de-DE' });\n * ```\n *\n * Never throws, never rejects.\n *\n * @param lang A BCP-47 tag.\n * @param options The wait bound, forwarded to {@link listVoices}.\n * @returns The best match, or `undefined` when the language has no voice installed (SSR included).\n */\nexport async function findVoice(lang: string, options?: ListVoicesOptions): Promise<SpeechSynthesisVoice | undefined> {\n  const voices = await listVoices(options);\n  return voicesForLang(voices, lang).at(0);\n}\n","// The Vue binding of the synthesis half — and the reason it exists is the TEARDOWN. Speech is not part of the\n// DOM: a component that starts an utterance and then navigates away keeps talking, out of any view, until the\n// text runs out. Nothing in Vue tears that down, because nothing in Vue knows about it. This composable cancels\n// its own in-flight speech in `onScopeDispose`, which is the single most valuable line in the file.\n//\n// \"ITS OWN\" is load-bearing. The platform's cancel is global — one utterance queue per document — so cancelling\n// unconditionally on teardown would silence a sibling component that is mid-sentence. The composable counts the\n// utterances IT started that have not settled and cancels only when that count is above zero. Two components\n// speaking at once still interfere (the platform gives no way not to), but a component that never spoke cannot\n// silence one that did.\n//\n// `supported` is a `shallowRef` seeded `false` and synced in `onMounted`, the idiom `foundation/hooks`'\n// `useMediaQuery` uses and the Vue counterpart of the original's `useSyncExternalStore`: `false` during SSR and\n// the real answer once mounted, as an update rather than a hydration mismatch. Nothing subscribes because a\n// browser cannot gain a speech engine mid-session — and `canSpeak` reads `window`, so it must not run at setup.\n//\n// `voices` is likewise filled after mount. `getVoices()` returns a FRESH ARRAY on every call, so re-reading it\n// as a derived value would produce a new identity each time; it lives in a `shallowRef`, seeded by `listVoices`\n// (which waits out the empty-first-call problem) and refreshed on `voiceschanged` — Chrome revises the list once\n// remote voices load.\n\nimport { onMounted, onScopeDispose, shallowRef, type ShallowRef } from 'vue';\n\nimport { useLocale } from '../i18n';\n\nimport { listVoices, listVoicesSync, onVoicesChanged } from './ListVoices';\nimport { speak as speakText, type SpeakOptions } from './Speak';\nimport { cancelSpeech, pauseSpeech, resumeSpeech } from './SpeechControls';\nimport type { SpeakResult } from './SpeechResult';\nimport { canSpeak } from './SpeechSupport';\n\n/** What {@link useSpeechSynthesis} returns. */\nexport interface SpeechSynthesisControls {\n  /** Whether this browser can speak. `false` under SSR — render the button only once this is `true`. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /** The installed voices. Starts empty and fills in asynchronously; see `ListVoices` for why that is normal. */\n  readonly voices: Readonly<ShallowRef<readonly SpeechSynthesisVoice[]>>;\n\n  /** Whether this composable has an utterance in flight. Not the engine's global flag — another component's speech is not this one's. */\n  readonly speaking: Readonly<ShallowRef<boolean>>;\n\n  /** Whether this composable paused the engine. */\n  readonly paused: Readonly<ShallowRef<boolean>>;\n\n  /** Speaks text, resolving to the outcome. Never throws. Defaults `lang` to the active locale. */\n  readonly speak: (text: string, options?: SpeakOptions) => Promise<SpeakResult>;\n\n  /** Stops all speech in the document — the platform has no narrower cancel. In-flight `speak` calls settle as `cancelled`. */\n  readonly cancel: () => void;\n\n  /** Pauses the engine. See `SpeechControls` for Chrome-on-Android's pause-is-cancel behaviour. */\n  readonly pause: () => void;\n\n  /** Resumes a paused engine. */\n  readonly resume: () => void;\n}\n\n/**\n * The initial voice list. Empty rather than `listVoicesSync()`, for the same reason `supported` starts `false`:\n * a server renders nothing and a client would render a full picker, and the mismatch is a hydration error —\n * quite apart from `listVoicesSync` reaching for a global the server does not have. The mount hook fills it in\n * on the very next tick.\n */\nconst NoVoices: readonly SpeechSynthesisVoice[] = [];\n\n/**\n * Speaks text and owns the lifecycle — cancelling this composable's in-flight speech when the scope is disposed.\n *\n * ```vue\n * const speech = useSpeechSynthesis();\n * <button :disabled=\"!speech.supported.value\" @click=\"speech.speak(article)\">\n *   {{ speech.speaking.value ? 'Stop' : 'Read aloud' }}\n * </button>\n * ```\n *\n * Inherits the slice's never-throws contract — a rejected promise is not one of the outcomes.\n *\n * @returns The state plus the four controls.\n */\nexport function useSpeechSynthesis(): SpeechSynthesisControls {\n  const { locale } = useLocale();\n\n  const voices = shallowRef<readonly SpeechSynthesisVoice[]>(NoVoices);\n  const speaking = shallowRef(false);\n  const paused = shallowRef(false);\n  const supported = shallowRef(false);\n\n  /** Guards state writes after teardown. */\n  let disposed = false;\n\n  /** How many utterances THIS composable started and has not seen settle. Drives both `speaking` and the cancel. */\n  let inFlight = 0;\n\n  const speak = async (text: string, options?: SpeakOptions): Promise<SpeakResult> => {\n    inFlight += 1;\n    if (!disposed) {\n      speaking.value = true;\n      paused.value = false;\n    }\n\n    // `lang` falls back to the app's active locale rather than the browser UI language: a localized app should\n    // read its own text in the language the user is reading, not the one the OS was installed in.\n    const result = await speakText(text, { ...options, lang: options?.lang ?? locale.value });\n\n    inFlight = Math.max(0, inFlight - 1);\n    // Only the LAST utterance clears the flag — a consumer queueing three sentences is speaking until all three\n    // have settled.\n    if (!disposed && inFlight === 0) {\n      speaking.value = false;\n      paused.value = false;\n    }\n\n    return result;\n  };\n\n  const cancel = (): void => {\n    cancelSpeech();\n    if (!disposed) paused.value = false;\n  };\n\n  const pause = (): void => {\n    if (pauseSpeech() && !disposed) paused.value = true;\n  };\n\n  const resume = (): void => {\n    if (resumeSpeech() && !disposed) paused.value = false;\n  };\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    supported.value = canSpeak();\n\n    const apply = (next: readonly SpeechSynthesisVoice[]): void => {\n      if (!disposed) voices.value = next;\n    };\n\n    // Waits out the empty-first-call problem; resolves immediately once the list is populated.\n    void listVoices().then(apply);\n\n    unsubscribe = onVoicesChanged((): void => {\n      apply(listVoicesSync());\n    });\n  });\n\n  onScopeDispose(() => {\n    disposed = true;\n    unsubscribe?.();\n    unsubscribe = undefined;\n    // The whole point of the composable. Only when THIS one has something in flight — the platform's cancel is\n    // global, and a teardown is no reason to silence another component.\n    if (inFlight > 0) cancelSpeech();\n  });\n\n  return { supported, voices, speaking, paused, speak, cancel, pause, resume };\n}\n","// The result vocabulary of the recognition half, and the error-code table that produces it. THIS TABLE IS THE\n// MODULE'S REAL VALUE: one `error` event carries at least six situations that a user resolves in six different\n// ways — a blocked microphone (browser settings), no microphone at all (plug one in), a dropped network (Chrome\n// streams audio to a Google server, so recognition dies offline while synthesis keeps working), silence (speak\n// louder), an abort the app itself asked for (say nothing), and a language the service will not transcribe (pick\n// another). A consumer that renders one \"speech recognition failed\" message for all six is unhelpable.\n//\n// The vocabulary deliberately REUSES `foundation/media`'s words where the situation is the same one: `denied` for\n// a refused permission, `unavailable` for a missing device, `unsupported` for a missing API, `failed` for the\n// rest. A microphone denial is a microphone denial whether it arrived through `getUserMedia` or through\n// recognition, and two spellings of it would force every consumer to write the mapping twice.\n//\n// Codes mapped away from their literal name, each for a reason:\n//  - `service-not-allowed` → `denied`. Chrome sends this when the BROWSER or OS blocks the speech service rather\n//    than the user — including on an insecure origin. Different cause, identical remedy path for the user, and\n//    splitting it would give consumers a status with no distinct copy to write.\n//  - `audio-capture` → `unavailable`. The literal meaning is \"no input device was usable\", which is\n//    `foundation/media`'s `unavailable`, not a failure.\n//  - `bad-grammar` → `failed`. It means the app supplied a grammar the engine rejected — a programmer error that\n//    deserves the real `Error`, and this slice does not expose grammars at all.\n//\n// `aborted` is a first-class status rather than an error for the same reason `foundation/share` keeps\n// `dismissed`: it is what the app's own `abort()` produces (an unmount, a cancel button), and reporting the app's\n// own decision back to the user as a failure raises a toast for something nobody did wrong.\n\n/**\n * Why a recognition session ended badly. Eight arms, four of them sharing `foundation/media`'s vocabulary.\n *\n * - `denied` — the microphone is blocked, by the user or by the browser / OS. Not retryable without a settings\n *   change, so re-prompting on a timer only annoys.\n * - `unavailable` — no usable input device. A desktop with no microphone, or an unplugged one.\n * - `no-speech` — the engine listened and heard nothing. Ordinary, and the most common ending of all: expect it\n *   whenever a user presses the button and hesitates.\n * - `network` — the recognition service was unreachable. Chrome performs recognition SERVER-SIDE, so this is\n *   routine offline, and no amount of retrying fixes it without a connection.\n * - `aborted` — the app stopped the session (`abort()`, an unmount). A decision, not a failure.\n * - `language-unsupported` — the service will not transcribe the requested `lang`.\n * - `unsupported` — no recognition API here: SSR, or Firefox, which does not implement it.\n * - `failed` — anything else, including an unreadable event.\n */\nexport type SpeechRecognitionStatus =\n  | 'denied'\n  | 'unavailable'\n  | 'no-speech'\n  | 'network'\n  | 'aborted'\n  | 'language-unsupported'\n  | 'unsupported'\n  | 'failed';\n\n/** A recognition failure: the classified status plus a normalized `Error` for logs and telemetry. */\nexport interface SpeechRecognitionFailure {\n  /** What went wrong, in terms a UI can branch on. */\n  readonly status: SpeechRecognitionStatus;\n\n  /** The normalized error, always present — carrying the raw platform code in its message. */\n  readonly error: Error;\n}\n\n/** One transcription update — interim or final — as handed to a recognizer's callbacks. */\nexport interface SpeechTranscript {\n  /** The recognized text. */\n  readonly transcript: string;\n\n  /** `true` once the engine has committed to this phrase; `false` while it is still revising it. */\n  readonly isFinal: boolean;\n\n  /** The engine's `0`–`1` confidence. Chrome reports `0` for interim results — a hint, never a gate. */\n  readonly confidence: number;\n}\n\n/** Platform error code → status. Everything absent from this table lands on `failed` with the real code kept. */\nconst StatusByCode: Readonly<Record<string, SpeechRecognitionStatus>> = {\n  'not-allowed': 'denied',\n  'service-not-allowed': 'denied',\n  'audio-capture': 'unavailable',\n  'no-speech': 'no-speech',\n  network: 'network',\n  aborted: 'aborted',\n  'language-not-supported': 'language-unsupported',\n};\n\n/** Reads a member as a string, guarded — a throwing getter reads as absent rather than as a second failure. */\nfunction stringMember(value: unknown, key: string): string | undefined {\n  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return undefined;\n\n  try {\n    const member: unknown = (value as Record<string, unknown>)[key];\n    return typeof member === 'string' ? member : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Classifies a recognition `error` event into its {@link SpeechRecognitionFailure}.\n *\n * Matched on the `error` string rather than an `instanceof`, for the same reason `foundation/media` matches\n * `DOMException` names: the event type is non-standard, differs between Chrome and Safari, and a test double\n * throws a plain `{ error: 'no-speech' }`.\n *\n * Never throws. An unreadable event becomes `failed` carrying an `Error` that says so.\n *\n * @param event The `error` event the engine delivered.\n * @returns The classified failure.\n */\nexport function toSpeechRecognitionFailure(event: unknown): SpeechRecognitionFailure {\n  const code = stringMember(event, 'error');\n  const detail = stringMember(event, 'message');\n  const status = code === undefined ? 'failed' : (StatusByCode[code] ?? 'failed');\n\n  const message =\n    detail === undefined || detail === ''\n      ? `speech recognition error: ${code ?? 'unknown'}`\n      : `speech recognition error: ${code ?? 'unknown'} — ${detail}`;\n\n  // The raw event rides as `cause`; `foundation/errors`' chain walkers traverse it safely (cycle-guarded).\n  return { status, error: new Error(message, { cause: event }) };\n}\n","// The recognition instance, wrapped so a consumer never touches the prefixed global, never gets a raw event, and\n// never has a call throw at it.\n//\n// DEFINING CONTRACT: NOTHING HERE THROWS. That matters more here than anywhere else in the slice, because the\n// native `start()` throws `InvalidStateError` for the most ordinary mistake there is — pressing the mic button\n// twice. `start()` returns `already-started` for that, and every other call is guarded.\n//\n// STATE IS TRACKED IN THREE VALUES, not two. `starting` exists because `start()` returns long before the engine\n// is listening: the `start` event arrives after the browser has (possibly) prompted for the microphone and opened\n// the audio device. A two-state flag would report `idle` during that window and let a second `start()` through,\n// straight into the `InvalidStateError` this wrapper exists to prevent.\n//\n// EVERY CONSUMER CALLBACK IS INVOKED THROUGH `report`, which swallows a throw. These callbacks run inside the\n// browser's own event dispatch, where an exception becomes an unhandled error in the page with no relation to the\n// code that caused it — the same reason `foundation/share`'s `reportShareError` exists.\n//\n// NO AUTO-RESTART, deliberately. With `continuous: true` Chrome still ends the session after a stretch of\n// silence, and the obvious fix is restarting inside `onend`. That loop is a trap: it re-opens the microphone\n// indefinitely, keeps Chrome streaming audio to a remote service, and turns a `denied` into a hot loop of denials.\n// The session ends, `onEnd` fires, and the consumer decides.\n//\n// PRIVACY, stated plainly because a wrapper this convenient hides it: in Chrome, recognition is NOT on-device.\n// Audio is sent to a Google server and the transcript comes back. Anything spoken into this API leaves the\n// machine. Safari's implementation differs, and Firefox has none at all.\n\nimport { toError } from '../errors';\n\nimport { speechRecognitionConstructor } from './SpeechSupport';\nimport { toSpeechRecognitionFailure, type SpeechRecognitionFailure, type SpeechTranscript } from './SpeechRecognitionResult';\nimport type { SpeechRecognitionEventLike, SpeechRecognitionLike } from './SpeechRecognitionTypes';\n\n/**\n * The outcome of a {@link SpeechRecognizer.start} call.\n *\n * - `started` — the engine accepted the request. Listening begins later, at the `onStart` callback.\n * - `already-started` — a session is running or starting. The native call would have thrown here.\n * - `unsupported` — no recognition API (SSR, Firefox).\n * - `failed` — the engine refused, carrying the normalized `Error`.\n */\nexport type RecognizerStartResult =\n  | { readonly status: 'started' }\n  | { readonly status: 'already-started' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'failed'; readonly error: Error };\n\n/** Configuration and callbacks for a recognizer. Applied once, at creation — see {@link createSpeechRecognizer}. */\nexport interface SpeechRecognizerOptions {\n  /** BCP-47 tag to transcribe (`en-US`, `uz`). Same vocabulary as `foundation/i18n`'s locale. Defaults to the engine's. */\n  readonly lang?: string;\n\n  /** Keep listening past the first phrase. Defaults to `false`. Chrome still ends the session on long silence. */\n  readonly continuous?: boolean;\n\n  /** Emit revisable partial results while the user is still speaking. Defaults to `false`. */\n  readonly interimResults?: boolean;\n\n  /** How many alternatives each result carries. Defaults to the engine's (`1`). */\n  readonly maxAlternatives?: number;\n\n  /** Every update, interim and final — the one callback that sees the whole stream. A throw from it is swallowed. */\n  readonly onResult?: (result: SpeechTranscript) => void;\n\n  /** Committed phrases only. The callback most consumers want. A throw from it is swallowed. */\n  readonly onFinal?: (transcript: string) => void;\n\n  /** The current uncommitted text, joined across pending results. Requires `interimResults`. */\n  readonly onInterim?: (transcript: string) => void;\n\n  /** A classified failure. `no-speech` and `aborted` arrive here too — neither is worth a toast. */\n  readonly onError?: (failure: SpeechRecognitionFailure) => void;\n\n  /** The engine is now listening — later than the `start()` that asked for it, and after any permission prompt. */\n  readonly onStart?: () => void;\n\n  /** The session ended, for ANY reason: `stop`, `abort`, an error, or the engine's own silence timeout. */\n  readonly onEnd?: () => void;\n}\n\n/** A wrapped recognition session. Every method is total — nothing throws, nothing needs a `try`. */\nexport interface SpeechRecognizer {\n  /** Whether a real engine is behind this recognizer. `false` under SSR, in Firefox, and if construction failed. */\n  readonly supported: boolean;\n\n  /** Whether the engine is listening right now — `false` during the gap between `start()` and the `start` event. */\n  readonly listening: boolean;\n\n  /** Begins a session. Safe to call twice: the second call answers `already-started` instead of throwing. */\n  readonly start: () => RecognizerStartResult;\n\n  /** Ends the session, keeping results the engine has already recognized. A no-op when idle. */\n  readonly stop: () => void;\n\n  /** Ends the session immediately, discarding pending results. A no-op when idle. Use this on unmount. */\n  readonly abort: () => void;\n}\n\n/** Hands a consumer's callback its argument, absorbing a throw so it cannot escape into the browser's dispatch. */\nfunction report<TArgument>(callback: ((argument: TArgument) => void) | undefined, argument: TArgument): void {\n  if (callback === undefined) return;\n\n  try {\n    callback(argument);\n  } catch {\n    // The consumer's own handler failed. Nothing useful is left to do with that, and the session must continue.\n  }\n}\n\n/** The recognizer handed back where no engine exists — every call answers, none of them reach anything. */\nfunction inertRecognizer(start: () => RecognizerStartResult): SpeechRecognizer {\n  const noop = (): void => {\n    // No session can exist, so there is nothing to stop or abort.\n  };\n\n  return { supported: false, listening: false, start, stop: noop, abort: noop };\n}\n\n/**\n * Creates a wrapped speech recognizer.\n *\n * ```ts\n * const recognizer = createSpeechRecognizer({\n *   lang: 'en-US',\n *   interimResults: true,\n *   onFinal: (text) => append(text),\n *   onError: (failure) => { if (failure.status === 'denied') showMicrophoneHelp(); },\n * });\n *\n * if (recognizer.supported) recognizer.start();\n * ```\n *\n * Options are applied ONCE, at creation: the platform reads `lang` / `continuous` / `interimResults` when a\n * session starts and offers no way to reconfigure a running one, so changing them means creating a new\n * recognizer. `useSpeechRecognition` does exactly that when its `lang` changes.\n *\n * Never throws. Always returns a usable object — check `supported`, or read the `start()` result.\n *\n * @param options Language, session shape, and callbacks.\n * @returns The recognizer. `supported: false` under SSR, in Firefox, and where the constructor exists but refuses.\n */\nexport function createSpeechRecognizer(options?: SpeechRecognizerOptions): SpeechRecognizer {\n  const Recognition = speechRecognitionConstructor();\n  if (Recognition === undefined) return inertRecognizer(() => ({ status: 'unsupported' }));\n\n  let instance: SpeechRecognitionLike;\n  try {\n    instance = new Recognition();\n  } catch (cause) {\n    // The constructor exists but refuses to instantiate (a policy-blocked iframe is the realistic case).\n    // `supported` reports false because nothing can be started — but `start()` hands back the REAL error rather\n    // than a soothing `unsupported`, which would send a developer hunting for a browser that already has the API.\n    const error = toError(cause);\n    return inertRecognizer(() => ({ status: 'failed', error }));\n  }\n\n  try {\n    if (options?.lang !== undefined) instance.lang = options.lang;\n    instance.continuous = options?.continuous ?? false;\n    instance.interimResults = options?.interimResults ?? false;\n    if (options?.maxAlternatives !== undefined) instance.maxAlternatives = options.maxAlternatives;\n  } catch {\n    // A partial implementation refusing a setter keeps its own defaults, which still transcribe something.\n  }\n\n  let state: 'idle' | 'starting' | 'listening' = 'idle';\n\n  /** Walks the results this event changed, emitting one update per result and one joined interim string. */\n  const emitResults = (event: SpeechRecognitionEventLike): void => {\n    try {\n      const results = event.results;\n      const length = typeof results?.length === 'number' ? results.length : 0;\n      // `results` is CUMULATIVE across the session, so a walk from 0 would re-emit every phrase on every event.\n      const first = Number.isInteger(event.resultIndex) ? Math.max(0, event.resultIndex) : 0;\n\n      let interim = '';\n\n      for (let index = first; index < length; index += 1) {\n        const result = results[index];\n        if (result === undefined) continue;\n\n        // Alternative 0 is the engine's best guess; the rest exist only when `maxAlternatives` asked for them.\n        const alternative = result[0];\n        if (alternative === undefined) continue;\n\n        const transcript = typeof alternative.transcript === 'string' ? alternative.transcript : '';\n        const confidence = typeof alternative.confidence === 'number' ? alternative.confidence : 0;\n        const isFinal = result.isFinal === true;\n\n        report(options?.onResult, { transcript, isFinal, confidence });\n        if (isFinal) report(options?.onFinal, transcript);\n        else if (transcript !== '') interim = interim === '' ? transcript : `${interim} ${transcript}`;\n      }\n\n      if (interim !== '') report(options?.onInterim, interim);\n    } catch {\n      // A hostile or half-implemented event shape costs this one update, never the session.\n    }\n  };\n\n  try {\n    instance.onstart = (): void => {\n      state = 'listening';\n      report<void>(options?.onStart, undefined);\n    };\n\n    instance.onend = (): void => {\n      state = 'idle';\n      report<void>(options?.onEnd, undefined);\n    };\n\n    instance.onerror = (event): void => {\n      // No state change here: every error is followed by `end`, which is the single place the session closes.\n      report(options?.onError, toSpeechRecognitionFailure(event));\n    };\n\n    instance.onresult = emitResults;\n  } catch {\n    // An instance that refuses handler assignment can still be started; it just reports nothing.\n  }\n\n  return {\n    supported: true,\n\n    get listening(): boolean {\n      return state === 'listening';\n    },\n\n    start: (): RecognizerStartResult => {\n      // Pre-empts the native `InvalidStateError` — including during `starting`, the window a two-state flag misses.\n      if (state !== 'idle') return { status: 'already-started' };\n\n      try {\n        instance.start();\n        state = 'starting';\n        return { status: 'started' };\n      } catch (cause) {\n        // The engine still considers a previous session open (an `abort` whose `end` has not arrived), or the\n        // page has no microphone permission to hand over.\n        state = 'idle';\n        return { status: 'failed', error: toError(cause) };\n      }\n    },\n\n    stop: (): void => {\n      if (state === 'idle') return;\n\n      try {\n        instance.stop();\n      } catch {\n        // Stopping something the engine already stopped is not a failure worth surfacing.\n      }\n    },\n\n    abort: (): void => {\n      if (state === 'idle') return;\n      state = 'idle';\n\n      try {\n        instance.abort();\n      } catch {\n        // Same as `stop`. The local state is cleared first, so a refusing engine cannot strand this wrapper.\n      }\n    },\n  };\n}\n","// The Vue binding of the recognition half. Like its synthesis sibling, the line that earns the file is the\n// TEARDOWN: a live recognition session holds the microphone open and — in Chrome — keeps streaming audio to a\n// remote service. A component that navigates away mid-session leaves the recording indicator on, so\n// `onScopeDispose` calls `abort()`, not `stop()`: `stop()` asks for one last transcript nobody is left to\n// receive.\n//\n// THE RECOGNIZER IS CREATED LAZILY, ON FIRST `start()`, not during `setup` and not in `onMounted`. Constructing\n// during `setup` would reach for `SpeechRecognition` on the server, where the global does not exist;\n// constructing in `onMounted` would build one for every consumer who never presses the button, and would hold\n// the constructor open on a component that only renders a disabled control. A lazy getter avoids all three,\n// and `start()` can only ever be called from the client.\n//\n// CHANGING `lang` REBUILDS IT. The platform reads the language when a session starts and offers no way to\n// reconfigure a running recognizer, so a locale switch aborts the current instance and drops it; the next\n// `start()` builds one with the new tag. Aborting mid-session is the honest behaviour — the alternative is\n// transcribing the rest of the sentence in the previous language.\n//\n// TRANSCRIPT ACCUMULATES ACROSS THE SESSION; interim text does not. A final result is appended to `transcript`\n// and clears `interimTranscript`, so a consumer renders `transcript + interimTranscript` and gets the natural\n// \"committed text, then greyed-out live text\" without tracking anything itself. `reset()` clears both.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { useLocale } from '../i18n';\n\nimport {\n  createSpeechRecognizer,\n  type RecognizerStartResult,\n  type SpeechRecognizer,\n  type SpeechRecognizerOptions,\n} from './CreateSpeechRecognizer';\nimport type { SpeechRecognitionFailure } from './SpeechRecognitionResult';\nimport { canRecognizeSpeech } from './SpeechSupport';\n\n/** Options for {@link useSpeechRecognition} — the recognizer's own, with the composable layering state on top. */\nexport type UseSpeechRecognitionOptions = SpeechRecognizerOptions;\n\n/** What {@link useSpeechRecognition} returns. */\nexport interface SpeechRecognitionControls {\n  /** Whether this browser can transcribe at all. `false` under SSR and in Firefox — gate the button on it. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /** Whether the engine is listening. `false` in the gap between `start()` and the engine actually opening the microphone. */\n  readonly listening: Readonly<ShallowRef<boolean>>;\n\n  /** Every committed phrase of the session, space-joined. Survives an ended session; cleared by `reset`. */\n  readonly transcript: Readonly<ShallowRef<string>>;\n\n  /** The current uncommitted text. Requires `interimResults`; cleared when the phrase commits or the session ends. */\n  readonly interimTranscript: Readonly<ShallowRef<string>>;\n\n  /** The last classified failure, or `null`. Cleared when a new session starts. `no-speech` lands here too. */\n  readonly error: Readonly<ShallowRef<SpeechRecognitionFailure | null>>;\n\n  /** Begins a session. Safe to call twice — the second answers `already-started`. */\n  readonly start: () => RecognizerStartResult;\n\n  /** Ends the session, keeping what the engine already recognized. */\n  readonly stop: () => void;\n\n  /** Ends the session immediately, discarding pending results. */\n  readonly abort: () => void;\n\n  /** Clears `transcript`, `interimTranscript`, and `error`. Does not touch the session. */\n  readonly reset: () => void;\n}\n\n/** Appends a committed phrase, space-joined, skipping the empty results an engine occasionally commits. */\nfunction appendPhrase(previous: string, phrase: string): string {\n  const next = phrase.trim();\n  if (next === '') return previous;\n  return previous === '' ? next : `${previous} ${next}`;\n}\n\n/**\n * Transcribes speech into accumulating reactive state, aborting the session when the scope is disposed.\n *\n * ```vue\n * const dictation = useSpeechRecognition({ interimResults: true, continuous: true });\n * <button :disabled=\"!dictation.supported.value\" @click=\"dictation.start()\">\n *   {{ dictation.listening.value ? 'Listening…' : 'Dictate' }}\n * </button>\n * <p>{{ dictation.transcript.value }} <em>{{ dictation.interimTranscript.value }}</em></p>\n * ```\n *\n * `lang` defaults to the active `LocaleProvider` locale, so a localized app transcribes the language its user is\n * reading. Nothing throws.\n *\n * @param options Session shape and pass-through callbacks — each is called in addition to the state updates.\n *   A ref or getter is read at call time, so a reactive options source is followed.\n * @returns The transcript state plus the four controls.\n */\nexport function useSpeechRecognition(\n  options?: MaybeRefOrGetter<UseSpeechRecognitionOptions | undefined>,\n): SpeechRecognitionControls {\n  const { locale } = useLocale();\n\n  const transcript = shallowRef('');\n  const interimTranscript = shallowRef('');\n  const listening = shallowRef(false);\n  const error = shallowRef<SpeechRecognitionFailure | null>(null);\n\n  // `false` until mount, exactly as the original's SSR snapshot: `canRecognizeSpeech` reads `window`, and a\n  // server that claimed support would render a button the client immediately has to disable. Nothing subscribes\n  // because a browser cannot gain a recognition engine mid-session.\n  const supported = shallowRef(false);\n\n  /** Guards state writes after teardown — the pass-through callbacks still fire, the reactive state does not. */\n  let disposed = false;\n  let recognizer: SpeechRecognizer | null = null;\n\n  function getRecognizer(): SpeechRecognizer {\n    if (recognizer !== null) return recognizer;\n\n    const created = createSpeechRecognizer({\n      lang: toValue(options)?.lang ?? locale.value,\n      continuous: toValue(options)?.continuous,\n      // Interim results default ON here, unlike the bare recognizer: a composable exposing `interimTranscript`\n      // that is permanently empty is a worse default than one that costs a few extra updates.\n      interimResults: toValue(options)?.interimResults ?? true,\n      maxAlternatives: toValue(options)?.maxAlternatives,\n\n      onStart: (): void => {\n        if (!disposed) {\n          listening.value = true;\n          error.value = null;\n        }\n        toValue(options)?.onStart?.();\n      },\n\n      onEnd: (): void => {\n        if (!disposed) {\n          listening.value = false;\n          // Uncommitted text belongs to a session that no longer exists; keeping it would render as live speech.\n          interimTranscript.value = '';\n        }\n        toValue(options)?.onEnd?.();\n      },\n\n      onError: (failure): void => {\n        if (!disposed) error.value = failure;\n        toValue(options)?.onError?.(failure);\n      },\n\n      onResult: (result): void => {\n        if (!disposed) {\n          if (result.isFinal) {\n            transcript.value = appendPhrase(transcript.value, result.transcript);\n            interimTranscript.value = '';\n          } else {\n            interimTranscript.value = result.transcript;\n          }\n        }\n        toValue(options)?.onResult?.(result);\n      },\n\n      onFinal: (text): void => {\n        toValue(options)?.onFinal?.(text);\n      },\n\n      onInterim: (text): void => {\n        toValue(options)?.onInterim?.(text);\n      },\n    });\n\n    recognizer = created;\n    return created;\n  }\n\n  const start = (): RecognizerStartResult => getRecognizer().start();\n\n  // `stop` / `abort` read the field instead of the getter: nothing can be running if nothing was ever built, and\n  // constructing a recognizer in order to stop it would open the very session being cancelled.\n  const stop = (): void => {\n    recognizer?.stop();\n  };\n\n  const abort = (): void => {\n    recognizer?.abort();\n  };\n\n  const reset = (): void => {\n    transcript.value = '';\n    interimTranscript.value = '';\n    error.value = null;\n  };\n\n  onMounted(() => {\n    supported.value = canRecognizeSpeech();\n  });\n\n  // Config is applied at construction, so a change means a new instance. Aborting first is deliberate: a session\n  // already running under the old language cannot be re-tagged mid-sentence. Non-immediate, so nothing is\n  // aborted on the server — there is nothing to abort there anyway.\n  watch(\n    [\n      () => toValue(options)?.lang ?? locale.value,\n      () => toValue(options)?.continuous ?? false,\n      () => toValue(options)?.interimResults ?? true,\n    ],\n    () => {\n      recognizer?.abort();\n      recognizer = null;\n    },\n  );\n\n  onScopeDispose(() => {\n    disposed = true;\n    // `abort`, never `stop`: nothing is left to receive a final transcript, and the microphone must close now.\n    recognizer?.abort();\n    recognizer = null;\n  });\n\n  return { supported, listening, transcript, interimTranscript, error, start, stop, abort, reset };\n}\n"],"names":["NoVoices","inFlight","speak","speakText"],"mappings":";;;AA2CO,SAAS,oBACd,QAC6B;AAC7B,MAAI;AACF,UAAM,YAAsB,WAA6C;AACzE,QAAI,OAAO,cAAc,YAAY,cAAc,KAAM,QAAO;AAEhE,UAAM,MAAM;AACZ,QAAI,OAAO,IAAI,MAAM,MAAM,WAAY,QAAO;AAC9C,WAAO;AAAA,EACT,QAAQ;AAGN,WAAO;AAAA,EACT;AACF;AAUO,SAAS,uBAAyD;AACvE,MAAI;AACF,UAAM,YAAsB,WAAsD;AAClF,WAAO,OAAO,cAAc,aAAc,YAAqC;AAAA,EACjF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAUO,SAAS,+BAAyE;AACvF,MAAI;AAGF,UAAM,QAAQ;AAKd,UAAM,YAAqB,MAAM,qBAAqB,MAAM;AAC5D,WAAO,OAAO,cAAc,aAAc,YAA6C;AAAA,EACzF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASO,SAAS,WAAoB;AAClC,SAAO,oBAAoB,OAAO,MAAM,UAAa,2BAA2B;AAClF;AAaO,SAAS,qBAA8B;AAC5C,SAAO,mCAAmC;AAC5C;AAUO,SAAS,mBAAkC;AAChD,SAAO,EAAE,WAAW,SAAA,GAAY,aAAa,qBAAmB;AAClE;ACpGA,MAAM,oBAAyC,oBAAI,IAAI,CAAC,YAAY,aAAa,aAAa,CAAC;AAM/F,SAAS,YAAY,OAAoC;AACvD,MAAI,UAAU,QAAS,OAAO,UAAU,YAAY,OAAO,UAAU,WAAa,QAAO;AAEzF,MAAI;AACF,UAAM,OAAiB,MAAkC,OAAO;AAChE,WAAO,OAAO,SAAS,WAAW,OAAO;AAAA,EAC3C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAYO,SAAS,eAAe,OAA6B;AAC1D,QAAM,OAAO,YAAY,KAAK;AAC9B,MAAI,SAAS,UAAa,kBAAkB,IAAI,IAAI,EAAG,QAAO,EAAE,QAAQ,YAAA;AAIxE,QAAM,QAAQ,IAAI,MAAM,4BAA4B,QAAQ,SAAS,IAAI,EAAE,OAAO,OAAO;AACzF,SAAO,EAAE,QAAQ,UAAU,MAAA;AAC7B;AC9CA,IAAI,UAAU;AAUP,SAAS,mBAA2B;AACzC,SAAO;AACT;AAYO,SAAS,eAAwB;AACtC,QAAM,QAAQ,oBAAoB,QAAQ;AAC1C,MAAI,UAAU,OAAW,QAAO;AAEhC,aAAW;AACX,MAAI;AACF,UAAM,OAAA;AACN,WAAO;AAAA,EACT,QAAQ;AAIN,WAAO;AAAA,EACT;AACF;AAUO,SAAS,cAAuB;AACrC,QAAM,QAAQ,oBAAoB,OAAO;AACzC,MAAI,UAAU,OAAW,QAAO;AAEhC,MAAI;AACF,UAAM,MAAA;AACN,WAAO;AAAA,EACT,QAAQ;AAEN,WAAO;AAAA,EACT;AACF;AASO,SAAS,eAAwB;AACtC,QAAM,QAAQ,oBAAoB,QAAQ;AAC1C,MAAI,UAAU,OAAW,QAAO;AAEhC,MAAI;AACF,UAAM,OAAA;AACN,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAaO,SAAS,aAAsB;AACpC,QAAM,QAAQ,oBAAoB,OAAO;AACzC,MAAI,UAAU,OAAW,QAAO;AAEhC,MAAI;AACF,WAAO,MAAM,aAAa;AAAA,EAC5B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASO,SAAS,iBAA0B;AACxC,QAAM,QAAQ,oBAAoB,OAAO;AACzC,MAAI,UAAU,OAAW,QAAO;AAEhC,MAAI;AACF,WAAO,MAAM,WAAW;AAAA,EAC1B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;ACnEA,MAAM,+BAAe,IAAA;AAGrB,SAAS,MAAM,OAA2B,KAAa,KAAiC;AACtF,MAAI,UAAU,UAAa,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO;AAC3D,SAAO,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,CAAC;AAC3C;AAGA,SAAS,UAAU,WAAqC,SAAyC;AAC/F,MAAI,YAAY,OAAW;AAE3B,MAAI;AACF,QAAI,QAAQ,UAAU,OAAW,WAAU,QAAQ,QAAQ;AAC3D,QAAI,QAAQ,SAAS,OAAW,WAAU,OAAO,QAAQ;AAEzD,UAAM,OAAO,MAAM,QAAQ,MAAM,KAAK,EAAE;AACxC,QAAI,SAAS,OAAW,WAAU,OAAO;AAEzC,UAAM,QAAQ,MAAM,QAAQ,OAAO,GAAG,CAAC;AACvC,QAAI,UAAU,OAAW,WAAU,QAAQ;AAE3C,UAAM,SAAS,MAAM,QAAQ,QAAQ,GAAG,CAAC;AACzC,QAAI,WAAW,OAAW,WAAU,SAAS;AAAA,EAC/C,QAAQ;AAAA,EAGR;AACF;AAGA,SAAS,SAAS,QAA8B,UAA+D;AAC7G,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,SAAS;AAAA,IACjB,OAAO,SAAS;AAAA,IAChB,QAAQ,SAAS;AAAA,IACjB,MAAM,CACJ,aACA,eACqC,OAAO,KAAK,aAAa,UAAU;AAAA,EAAA;AAE9E;AAGA,SAAS,gBAAuD;AAC9D,QAAM,OAAO,MAAY;AAAA,EAEzB;AACA,SAAO,EAAE,QAAQ,MAAM,OAAO,MAAM,QAAQ,KAAA;AAC9C;AAuBO,SAAS,MAAM,MAAc,SAAsC;AACxE,QAAM,QAAQ,oBAAoB,OAAO;AACzC,QAAM,YAAY,qBAAA;AAGlB,MAAI,UAAU,UAAa,cAAc,QAAW;AAClD,WAAO,SAAS,QAAQ,QAAQ,EAAE,QAAQ,cAAA,CAAe,GAAG,eAAe;AAAA,EAC7E;AAEA,MAAI;AACJ,QAAM,SAAS,IAAI,QAAqB,CAAC,YAAY;AACnD,aAAS;AAAA,EACX,CAAC;AAED,MAAI,UAAU;AACd,MAAI;AAGJ,QAAM,SAAS,CAAC,WAA8B;AAC5C,QAAI,QAAS;AACb,cAAU;AACV,QAAI,cAAc,OAAW,UAAS,OAAO,SAAS;AACtD,WAAO,MAAM;AAAA,EACf;AAEA,MAAI;AACF,gBAAY,IAAI,UAAU,IAAI;AAAA,EAChC,SAAS,OAAO;AAGd,WAAO,SAAS,QAAQ,QAAQ,EAAE,QAAQ,UAAU,OAAO,QAAQ,KAAK,GAAG,GAAG,eAAe;AAAA,EAC/F;AAEA,YAAU,WAAW,OAAO;AAI5B,QAAM,aAAa,iBAAA;AACnB,QAAM,eAAe,MAAe,iBAAA,MAAuB;AAE3D,YAAU,QAAQ,MAAY;AAC5B,WAAO,aAAA,IAAiB,EAAE,QAAQ,gBAAgB,EAAE,QAAQ,UAAU;AAAA,EACxE;AAEA,YAAU,UAAU,CAAC,UAAgB;AAGnC,WAAO,aAAA,IAAiB,EAAE,QAAQ,gBAAgB,eAAe,KAAK,CAAC;AAAA,EACzE;AAEA,WAAS,IAAI,SAAS;AAEtB,MAAI;AACF,UAAM,MAAM,SAAS;AAAA,EACvB,SAAS,OAAO;AACd,WAAO,EAAE,QAAQ,UAAU,OAAO,QAAQ,KAAK,GAAG;AAAA,EACpD;AAEA,SAAO,SAAS,QAAQ;AAAA,IACtB,QAAQ,MAAY;AAClB,mBAAA;AAAA,IACF;AAAA,IACA,OAAO,MAAY;AACjB,kBAAA;AAAA,IACF;AAAA,IACA,QAAQ,MAAY;AAClB,mBAAA;AAAA,IACF;AAAA,EAAA,CACD;AACH;AC9LO,MAAM,yBAAyB;AAGtC,MAAMA,aAA4C,CAAA;AASlD,SAAS,WAAW,OAAyD;AAC3E,MAAI;AACF,UAAM,SAAkB,MAAM,UAAA;AAC9B,WAAO,MAAM,QAAQ,MAAM,IAAK,SAAoCA;AAAAA,EACtE,QAAQ;AACN,WAAOA;AAAAA,EACT;AACF;AAaO,SAAS,iBAAkD;AAChE,QAAM,QAAQ,oBAAoB,WAAW;AAC7C,SAAO,UAAU,SAAYA,aAAW,WAAW,KAAK;AAC1D;AAaO,SAAS,gBAAgB,UAAkC;AAChE,QAAM,OAAO,MAAY;AAAA,EAEzB;AAEA,QAAM,QAAQ,oBAAoB,WAAW;AAC7C,MAAI,UAAU,OAAW,QAAO;AAEhC,MAAI;AACF,QAAI,OAAO,MAAM,qBAAqB,YAAY;AAChD,YAAM,iBAAiB,iBAAiB,QAAQ;AAChD,aAAO,MAAY;AACjB,YAAI;AACF,gBAAM,oBAAoB,iBAAiB,QAAQ;AAAA,QACrD,QAAQ;AAAA,QAGR;AAAA,MACF;AAAA,IACF;AAGA,UAAM,WAAW,MAAM;AACvB,UAAM,kBAAkB,SAAiC,OAAoB;AAC3E,UAAI,OAAO,aAAa,WAAY,UAAS,KAAK,MAAM,KAAK;AAC7D,eAAA;AAAA,IACF;AACA,WAAO,MAAY;AACjB,YAAM,kBAAkB;AAAA,IAC1B;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAmBO,SAAS,WAAW,SAAuE;AAChG,QAAM,QAAQ,oBAAoB,WAAW;AAC7C,MAAI,UAAU,OAAW,QAAO,QAAQ,QAAQA,UAAQ;AAExD,QAAM,YAAY,WAAW,KAAK;AAClC,MAAI,UAAU,SAAS,EAAG,QAAO,QAAQ,QAAQ,SAAS;AAE1D,SAAO,IAAI,QAAyC,CAAC,YAAY;AAC/D,QAAI,UAAU;AAId,UAAM,SAAS,MAAY;AACzB,UAAI,QAAS;AACb,gBAAU;AACV,mBAAa,KAAK;AAClB,kBAAA;AAGA,cAAQ,WAAW,KAAK,CAAC;AAAA,IAC3B;AAEA,UAAM,cAAc,gBAAgB,MAAY;AAE9C,UAAI,WAAW,KAAK,EAAE,WAAW,EAAG;AACpC,aAAA;AAAA,IACF,CAAC;AAED,UAAM,QAAQ,WAAW,QAAQ,SAAS,aAAa,sBAAsB;AAAA,EAC/E,CAAC;AACH;AAGA,SAAS,aAAa,KAAqB;AACzC,SAAO,IAAI,OAAO,cAAc,QAAQ,MAAM,GAAG;AACnD;AAGA,SAAS,cAAc,KAAqB;AAC1C,SAAO,aAAa,GAAG,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK;AAC5C;AAGA,SAAS,aAAa,QAA0E;AAC9F,SAAO,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,MAAM,UAAU,OAAO,MAAM,YAAY,IAAI,IAAI,OAAO,KAAK,YAAY,IAAI,CAAC;AACzG;AAeO,SAAS,cACd,QACA,MACiC;AACjC,QAAM,SAAS,aAAa,IAAI;AAChC,MAAI,WAAW,GAAI,QAAOA;AAE1B,QAAM,gBAAgB,cAAc,MAAM;AAC1C,QAAM,QAAgC,CAAA;AACtC,QAAM,UAAkC,CAAA;AAExC,aAAW,SAAS,QAAQ;AAC1B,UAAM,MAAM,OAAO,MAAM,SAAS,WAAW,aAAa,MAAM,IAAI,IAAI;AACxE,QAAI,QAAQ,GAAI;AAEhB,QAAI,QAAQ,OAAQ,OAAM,KAAK,KAAK;AAAA,aAC3B,cAAc,GAAG,MAAM,cAAe,SAAQ,KAAK,KAAK;AAAA,EACnE;AAEA,SAAO,CAAC,GAAG,aAAa,KAAK,GAAG,GAAG,aAAa,OAAO,CAAC;AAC1D;AAgBA,eAAsB,UAAU,MAAc,SAAwE;AACpH,QAAM,SAAS,MAAM,WAAW,OAAO;AACvC,SAAO,cAAc,QAAQ,IAAI,EAAE,GAAG,CAAC;AACzC;ACpKA,MAAM,WAA4C,CAAA;AAgB3C,SAAS,qBAA8C;AAC5D,QAAM,EAAE,OAAA,IAAW,UAAA;AAEnB,QAAM,SAAS,WAA4C,QAAQ;AACnE,QAAM,WAAW,WAAW,KAAK;AACjC,QAAM,SAAS,WAAW,KAAK;AAC/B,QAAM,YAAY,WAAW,KAAK;AAGlC,MAAI,WAAW;AAGf,MAAIC,YAAW;AAEf,QAAMC,UAAQ,OAAO,MAAc,YAAiD;AAClF,IAAAD,aAAY;AACZ,QAAI,CAAC,UAAU;AACb,eAAS,QAAQ;AACjB,aAAO,QAAQ;AAAA,IACjB;AAIA,UAAM,SAAS,MAAME,MAAU,MAAM,EAAE,GAAG,SAAS,MAAM,SAAS,QAAQ,OAAO,MAAA,CAAO;AAExF,IAAAF,YAAW,KAAK,IAAI,GAAGA,YAAW,CAAC;AAGnC,QAAI,CAAC,YAAYA,cAAa,GAAG;AAC/B,eAAS,QAAQ;AACjB,aAAO,QAAQ;AAAA,IACjB;AAEA,WAAO;AAAA,EACT;AAEA,QAAM,SAAS,MAAY;AACzB,iBAAA;AACA,QAAI,CAAC,SAAU,QAAO,QAAQ;AAAA,EAChC;AAEA,QAAM,QAAQ,MAAY;AACxB,QAAI,YAAA,KAAiB,CAAC,iBAAiB,QAAQ;AAAA,EACjD;AAEA,QAAM,SAAS,MAAY;AACzB,QAAI,aAAA,KAAkB,CAAC,iBAAiB,QAAQ;AAAA,EAClD;AAEA,MAAI;AAEJ,YAAU,MAAM;AACd,cAAU,QAAQ,SAAA;AAElB,UAAM,QAAQ,CAAC,SAAgD;AAC7D,UAAI,CAAC,SAAU,QAAO,QAAQ;AAAA,IAChC;AAGA,SAAK,WAAA,EAAa,KAAK,KAAK;AAE5B,kBAAc,gBAAgB,MAAY;AACxC,YAAM,gBAAgB;AAAA,IACxB,CAAC;AAAA,EACH,CAAC;AAED,iBAAe,MAAM;AACnB,eAAW;AACX,kBAAA;AACA,kBAAc;AAGd,QAAIA,YAAW,EAAG,cAAA;AAAA,EACpB,CAAC;AAED,SAAO,EAAE,WAAW,QAAQ,UAAU,eAAQC,SAAO,QAAQ,OAAO,OAAA;AACtE;ACpFA,MAAM,eAAkE;AAAA,EACtE,eAAe;AAAA,EACf,uBAAuB;AAAA,EACvB,iBAAiB;AAAA,EACjB,aAAa;AAAA,EACb,SAAS;AAAA,EACT,SAAS;AAAA,EACT,0BAA0B;AAC5B;AAGA,SAAS,aAAa,OAAgB,KAAiC;AACrE,MAAI,UAAU,QAAS,OAAO,UAAU,YAAY,OAAO,UAAU,WAAa,QAAO;AAEzF,MAAI;AACF,UAAM,SAAmB,MAAkC,GAAG;AAC9D,WAAO,OAAO,WAAW,WAAW,SAAS;AAAA,EAC/C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAcO,SAAS,2BAA2B,OAA0C;AACnF,QAAM,OAAO,aAAa,OAAO,OAAO;AACxC,QAAM,SAAS,aAAa,OAAO,SAAS;AAC5C,QAAM,SAAS,SAAS,SAAY,WAAY,aAAa,IAAI,KAAK;AAEtE,QAAM,UACJ,WAAW,UAAa,WAAW,KAC/B,6BAA6B,QAAQ,SAAS,KAC9C,6BAA6B,QAAQ,SAAS,MAAM,MAAM;AAGhE,SAAO,EAAE,QAAQ,OAAO,IAAI,MAAM,SAAS,EAAE,OAAO,MAAA,CAAO,EAAA;AAC7D;ACrBA,SAAS,OAAkB,UAAuD,UAA2B;AAC3G,MAAI,aAAa,OAAW;AAE5B,MAAI;AACF,aAAS,QAAQ;AAAA,EACnB,QAAQ;AAAA,EAER;AACF;AAGA,SAAS,gBAAgB,OAAsD;AAC7E,QAAM,OAAO,MAAY;AAAA,EAEzB;AAEA,SAAO,EAAE,WAAW,OAAO,WAAW,OAAO,OAAO,MAAM,MAAM,OAAO,KAAA;AACzE;AAyBO,SAAS,uBAAuB,SAAqD;AAC1F,QAAM,cAAc,6BAAA;AACpB,MAAI,gBAAgB,OAAW,QAAO,gBAAgB,OAAO,EAAE,QAAQ,gBAAgB;AAEvF,MAAI;AACJ,MAAI;AACF,eAAW,IAAI,YAAA;AAAA,EACjB,SAAS,OAAO;AAId,UAAM,QAAQ,QAAQ,KAAK;AAC3B,WAAO,gBAAgB,OAAO,EAAE,QAAQ,UAAU,QAAQ;AAAA,EAC5D;AAEA,MAAI;AACF,QAAI,SAAS,SAAS,OAAW,UAAS,OAAO,QAAQ;AACzD,aAAS,aAAa,SAAS,cAAc;AAC7C,aAAS,iBAAiB,SAAS,kBAAkB;AACrD,QAAI,SAAS,oBAAoB,OAAW,UAAS,kBAAkB,QAAQ;AAAA,EACjF,QAAQ;AAAA,EAER;AAEA,MAAI,QAA2C;AAG/C,QAAM,cAAc,CAAC,UAA4C;AAC/D,QAAI;AACF,YAAM,UAAU,MAAM;AACtB,YAAM,SAAS,OAAO,SAAS,WAAW,WAAW,QAAQ,SAAS;AAEtE,YAAM,QAAQ,OAAO,UAAU,MAAM,WAAW,IAAI,KAAK,IAAI,GAAG,MAAM,WAAW,IAAI;AAErF,UAAI,UAAU;AAEd,eAAS,QAAQ,OAAO,QAAQ,QAAQ,SAAS,GAAG;AAClD,cAAM,SAAS,QAAQ,KAAK;AAC5B,YAAI,WAAW,OAAW;AAG1B,cAAM,cAAc,OAAO,CAAC;AAC5B,YAAI,gBAAgB,OAAW;AAE/B,cAAM,aAAa,OAAO,YAAY,eAAe,WAAW,YAAY,aAAa;AACzF,cAAM,aAAa,OAAO,YAAY,eAAe,WAAW,YAAY,aAAa;AACzF,cAAM,UAAU,OAAO,YAAY;AAEnC,eAAO,SAAS,UAAU,EAAE,YAAY,SAAS,YAAY;AAC7D,YAAI,QAAS,QAAO,SAAS,SAAS,UAAU;AAAA,iBACvC,eAAe,GAAI,WAAU,YAAY,KAAK,aAAa,GAAG,OAAO,IAAI,UAAU;AAAA,MAC9F;AAEA,UAAI,YAAY,GAAI,QAAO,SAAS,WAAW,OAAO;AAAA,IACxD,QAAQ;AAAA,IAER;AAAA,EACF;AAEA,MAAI;AACF,aAAS,UAAU,MAAY;AAC7B,cAAQ;AACR,aAAa,SAAS,SAAS,MAAS;AAAA,IAC1C;AAEA,aAAS,QAAQ,MAAY;AAC3B,cAAQ;AACR,aAAa,SAAS,OAAO,MAAS;AAAA,IACxC;AAEA,aAAS,UAAU,CAAC,UAAgB;AAElC,aAAO,SAAS,SAAS,2BAA2B,KAAK,CAAC;AAAA,IAC5D;AAEA,aAAS,WAAW;AAAA,EACtB,QAAQ;AAAA,EAER;AAEA,SAAO;AAAA,IACL,WAAW;AAAA,IAEX,IAAI,YAAqB;AACvB,aAAO,UAAU;AAAA,IACnB;AAAA,IAEA,OAAO,MAA6B;AAElC,UAAI,UAAU,OAAQ,QAAO,EAAE,QAAQ,kBAAA;AAEvC,UAAI;AACF,iBAAS,MAAA;AACT,gBAAQ;AACR,eAAO,EAAE,QAAQ,UAAA;AAAA,MACnB,SAAS,OAAO;AAGd,gBAAQ;AACR,eAAO,EAAE,QAAQ,UAAU,OAAO,QAAQ,KAAK,EAAA;AAAA,MACjD;AAAA,IACF;AAAA,IAEA,MAAM,MAAY;AAChB,UAAI,UAAU,OAAQ;AAEtB,UAAI;AACF,iBAAS,KAAA;AAAA,MACX,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IAEA,OAAO,MAAY;AACjB,UAAI,UAAU,OAAQ;AACtB,cAAQ;AAER,UAAI;AACF,iBAAS,MAAA;AAAA,MACX,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EAAA;AAEJ;AC3LA,SAAS,aAAa,UAAkB,QAAwB;AAC9D,QAAM,OAAO,OAAO,KAAA;AACpB,MAAI,SAAS,GAAI,QAAO;AACxB,SAAO,aAAa,KAAK,OAAO,GAAG,QAAQ,IAAI,IAAI;AACrD;AAoBO,SAAS,qBACd,SAC2B;AAC3B,QAAM,EAAE,OAAA,IAAW,UAAA;AAEnB,QAAM,aAAa,WAAW,EAAE;AAChC,QAAM,oBAAoB,WAAW,EAAE;AACvC,QAAM,YAAY,WAAW,KAAK;AAClC,QAAM,QAAQ,WAA4C,IAAI;AAK9D,QAAM,YAAY,WAAW,KAAK;AAGlC,MAAI,WAAW;AACf,MAAI,aAAsC;AAE1C,WAAS,gBAAkC;AACzC,QAAI,eAAe,KAAM,QAAO;AAEhC,UAAM,UAAU,uBAAuB;AAAA,MACrC,MAAM,QAAQ,OAAO,GAAG,QAAQ,OAAO;AAAA,MACvC,YAAY,QAAQ,OAAO,GAAG;AAAA;AAAA;AAAA,MAG9B,gBAAgB,QAAQ,OAAO,GAAG,kBAAkB;AAAA,MACpD,iBAAiB,QAAQ,OAAO,GAAG;AAAA,MAEnC,SAAS,MAAY;AACnB,YAAI,CAAC,UAAU;AACb,oBAAU,QAAQ;AAClB,gBAAM,QAAQ;AAAA,QAChB;AACA,gBAAQ,OAAO,GAAG,UAAA;AAAA,MACpB;AAAA,MAEA,OAAO,MAAY;AACjB,YAAI,CAAC,UAAU;AACb,oBAAU,QAAQ;AAElB,4BAAkB,QAAQ;AAAA,QAC5B;AACA,gBAAQ,OAAO,GAAG,QAAA;AAAA,MACpB;AAAA,MAEA,SAAS,CAAC,YAAkB;AAC1B,YAAI,CAAC,SAAU,OAAM,QAAQ;AAC7B,gBAAQ,OAAO,GAAG,UAAU,OAAO;AAAA,MACrC;AAAA,MAEA,UAAU,CAAC,WAAiB;AAC1B,YAAI,CAAC,UAAU;AACb,cAAI,OAAO,SAAS;AAClB,uBAAW,QAAQ,aAAa,WAAW,OAAO,OAAO,UAAU;AACnE,8BAAkB,QAAQ;AAAA,UAC5B,OAAO;AACL,8BAAkB,QAAQ,OAAO;AAAA,UACnC;AAAA,QACF;AACA,gBAAQ,OAAO,GAAG,WAAW,MAAM;AAAA,MACrC;AAAA,MAEA,SAAS,CAAC,SAAe;AACvB,gBAAQ,OAAO,GAAG,UAAU,IAAI;AAAA,MAClC;AAAA,MAEA,WAAW,CAAC,SAAe;AACzB,gBAAQ,OAAO,GAAG,YAAY,IAAI;AAAA,MACpC;AAAA,IAAA,CACD;AAED,iBAAa;AACb,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,MAA6B,cAAA,EAAgB,MAAA;AAI3D,QAAM,OAAO,MAAY;AACvB,gBAAY,KAAA;AAAA,EACd;AAEA,QAAM,QAAQ,MAAY;AACxB,gBAAY,MAAA;AAAA,EACd;AAEA,QAAM,QAAQ,MAAY;AACxB,eAAW,QAAQ;AACnB,sBAAkB,QAAQ;AAC1B,UAAM,QAAQ;AAAA,EAChB;AAEA,YAAU,MAAM;AACd,cAAU,QAAQ,mBAAA;AAAA,EACpB,CAAC;AAKD;AAAA,IACE;AAAA,MACE,MAAM,QAAQ,OAAO,GAAG,QAAQ,OAAO;AAAA,MACvC,MAAM,QAAQ,OAAO,GAAG,cAAc;AAAA,MACtC,MAAM,QAAQ,OAAO,GAAG,kBAAkB;AAAA,IAAA;AAAA,IAE5C,MAAM;AACJ,kBAAY,MAAA;AACZ,mBAAa;AAAA,IACf;AAAA,EAAA;AAGF,iBAAe,MAAM;AACnB,eAAW;AAEX,gBAAY,MAAA;AACZ,iBAAa;AAAA,EACf,CAAC;AAED,SAAO,EAAE,WAAW,WAAW,YAAY,mBAAmB,OAAO,OAAO,MAAM,OAAO,MAAA;AAC3F;"}

package/dist/foundation/storage/NamespacedBroker.d.ts

@@ -0,0 +1,7 @@
+import { StorageBroker } from './StorageBroker';
+/**
+ * Wraps `inner` so every key is transparently prefixed with `namespace` (joined by `:`). Reads, writes, and
+ * removes all address the namespaced key, so two brokers with distinct namespaces over the same backing store
+ * never observe each other's values. Delegates JSON handling and failure-tolerance to `inner` unchanged.
+ */
+export declare function namespacedBroker(inner: StorageBroker, namespace: string): StorageBroker;

package/dist/foundation/storage/StorageBroker.d.ts

@@ -0,0 +1,17 @@
+/** Defines a JSON key/value persistence seam the storage hooks read and write through. */
+export interface StorageBroker {
+    /** Reads and parses the value stored under `key`, or null when absent or unreadable. */
+    read<T>(key: string): T | null;
+    /** Serializes `value` to JSON and writes it under `key`; a quota or serialization failure is swallowed. */
+    write<T>(key: string, value: T): void;
+    /** Removes any value stored under `key`. */
+    remove(key: string): void;
+}
+/**
+ * The production broker — persists through the browser's `localStorage` as JSON, SSR-safe and failure-tolerant.
+ * A read that is absent, malformed, or blocked returns null; a write that exceeds quota or fails to serialize is
+ * swallowed. Never throws, so a caller never has to guard the storage call.
+ */
+export declare const localStorageStorageBroker: StorageBroker;
+/** Builds an isolated in-memory `StorageBroker` backed by a `Map` — the test double, with no cross-tab sync and no DOM. */
+export declare function memoryStorageBroker(): StorageBroker;

package/dist/foundation/storage/VersionedStore.d.ts

@@ -0,0 +1,42 @@
+import { StorageBroker } from './StorageBroker';
+/** Upgrades a value from one schema version to the next. Receives the prior shape as `unknown`; returns the next. */
+export type Migration = (previous: unknown) => unknown;
+/** A map from *source* version to the migration that upgrades it to the following version (`n` upgrades `n`→`n+1`). */
+export type MigrationMap = Readonly<Record<number, Migration>>;
+/** Configures a versioned store. */
+export interface VersionedStoreOptions<T> {
+    /** The storage key the envelope is persisted under. */
+    readonly key: string;
+    /** The current schema version (a positive integer). A stored value below this is migrated up on read. */
+    readonly version: number;
+    /** The value returned when nothing is stored or the stored value cannot be recovered. */
+    readonly initial: T;
+    /** Migrations keyed by source version; `migrations[n]` upgrades a v`n` value to v`n+1`. */
+    readonly migrations?: MigrationMap;
+    /** The backing persistence seam; defaults to `localStorageStorageBroker`. */
+    readonly broker?: StorageBroker;
+}
+/** A versioned view over a storage key — hydrate-with-migration on read, envelope-stamp on write. */
+export interface VersionedStore<T> {
+    /** The storage key this store owns. */
+    readonly key: string;
+    /** The current schema version. */
+    readonly version: number;
+    /** Reads and, if needed, migrates the stored value; returns `initial` on absence or any unrecoverable state. */
+    read(): T;
+    /** Writes `value` stamped with the current version. */
+    write(value: T): void;
+    /** Removes the stored value. */
+    clear(): void;
+}
+/**
+ * Builds a {@link VersionedStore} over `key`. On `read`, a stored value is interpreted as:
+ * - **current version** → returned as-is;
+ * - **older version** → each `migrations[n]` is applied in turn from the stored version up to `version`, the
+ *   upgraded value is written back, and returned. A gap in the chain (a missing `migrations[n]`) yields `initial`;
+ * - **newer version** (a rollback to older code) → `initial`, leaving the forward-written value untouched;
+ * - **legacy bare value** (no envelope) → treated as version `0` and migrated the same way.
+ *
+ * Any thrown error inside migration or the broker degrades to `initial`, mirroring the broker's never-throw contract.
+ */
+export declare function createVersionedStore<T>(options: VersionedStoreOptions<T>): VersionedStore<T>;

package/dist/foundation/storage/index.d.ts

@@ -0,0 +1,3 @@
+export { type StorageBroker, localStorageStorageBroker, memoryStorageBroker, } from './StorageBroker';
+export { namespacedBroker } from './NamespacedBroker';
+export { type Migration, type MigrationMap, type VersionedStore, type VersionedStoreOptions, createVersionedStore, } from './VersionedStore';

package/dist/foundation/storage/index.js

@@ -0,0 +1,65 @@
+import { l as localStorageStorageBroker } from "../../chunks/StorageBroker-COC81ZGB.js";
+import { m } from "../../chunks/StorageBroker-COC81ZGB.js";
+const NAMESPACE_SEPARATOR = ":";
+function namespacedBroker(inner, namespace) {
+  const scope = (key) => `${namespace}${NAMESPACE_SEPARATOR}${key}`;
+  return {
+    read(key) {
+      return inner.read(scope(key));
+    },
+    write(key, value) {
+      inner.write(scope(key), value);
+    },
+    remove(key) {
+      inner.remove(scope(key));
+    }
+  };
+}
+function isEnvelope(value) {
+  return typeof value === "object" && value !== null && "v" in value && "data" in value && typeof value.v === "number";
+}
+function createVersionedStore(options) {
+  const { key, version, initial, migrations = {} } = options;
+  const broker = options.broker ?? localStorageStorageBroker;
+  function migrate(fromVersion, data) {
+    let current = data;
+    for (let from = fromVersion; from < version; from++) {
+      const step = migrations[from];
+      if (step === void 0) return null;
+      current = step(current);
+    }
+    return { data: current };
+  }
+  return {
+    key,
+    version,
+    read() {
+      try {
+        const stored = broker.read(key);
+        if (stored === null) return initial;
+        const { v, data } = isEnvelope(stored) ? stored : { v: 0, data: stored };
+        if (v === version) return data;
+        if (v > version) return initial;
+        const migrated = migrate(v, data);
+        if (migrated === null) return initial;
+        broker.write(key, { v: version, data: migrated.data });
+        return migrated.data;
+      } catch {
+        return initial;
+      }
+    },
+    write(value) {
+      broker.write(key, { v: version, data: value });
+    },
+    clear() {
+      broker.remove(key);
+    }
+  };
+}
+export {
+  createVersionedStore,
+  localStorageStorageBroker,
+  m as memoryStorageBroker,
+  namespacedBroker
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/storage/NamespacedBroker.ts","../../../src/foundation/storage/VersionedStore.ts"],"sourcesContent":["// A `StorageBroker` decorator that prefixes every key with a namespace. Wrapping a shared broker (one\n// `localStorage`) in a namespace keeps unrelated features — or two tenants in the same app — from colliding on\n// a bare key like `\"draft\"`, without any hook change: the persistence hooks still see a plain `StorageBroker`.\n// Composes with any broker (production, memory, or another namespace) since it only rewrites keys.\n\nimport type { StorageBroker } from './StorageBroker';\n\n/** The separator between a namespace and the caller's key. */\nconst NAMESPACE_SEPARATOR = ':';\n\n/**\n * Wraps `inner` so every key is transparently prefixed with `namespace` (joined by `:`). Reads, writes, and\n * removes all address the namespaced key, so two brokers with distinct namespaces over the same backing store\n * never observe each other's values. Delegates JSON handling and failure-tolerance to `inner` unchanged.\n */\nexport function namespacedBroker(inner: StorageBroker, namespace: string): StorageBroker {\n  const scope = (key: string): string => `${namespace}${NAMESPACE_SEPARATOR}${key}`;\n\n  return {\n    read<T>(key: string): T | null {\n      return inner.read<T>(scope(key));\n    },\n\n    write<T>(key: string, value: T): void {\n      inner.write(scope(key), value);\n    },\n\n    remove(key: string): void {\n      inner.remove(scope(key));\n    },\n  };\n}\n","// A versioned wrapper over a `StorageBroker`. Persisted client state outlives the code that wrote it: a user\n// carries last month's `localStorage` into today's deploy. A `VersionedStore` stamps each value with a schema\n// `version` and, on read, walks a migration chain from the stored version up to the current one — so an old\n// shape is upgraded in place instead of silently mis-parsed. It inherits the broker's failure-tolerance: any\n// unrecoverable state (missing migration, a future version, a broken read) degrades to `initial`, never a throw.\n\nimport { localStorageStorageBroker, type StorageBroker } from './StorageBroker';\n\n/** Upgrades a value from one schema version to the next. Receives the prior shape as `unknown`; returns the next. */\nexport type Migration = (previous: unknown) => unknown;\n\n/** A map from *source* version to the migration that upgrades it to the following version (`n` upgrades `n`→`n+1`). */\nexport type MigrationMap = Readonly<Record<number, Migration>>;\n\n/** Configures a versioned store. */\nexport interface VersionedStoreOptions<T> {\n  /** The storage key the envelope is persisted under. */\n  readonly key: string;\n\n  /** The current schema version (a positive integer). A stored value below this is migrated up on read. */\n  readonly version: number;\n\n  /** The value returned when nothing is stored or the stored value cannot be recovered. */\n  readonly initial: T;\n\n  /** Migrations keyed by source version; `migrations[n]` upgrades a v`n` value to v`n+1`. */\n  readonly migrations?: MigrationMap;\n\n  /** The backing persistence seam; defaults to `localStorageStorageBroker`. */\n  readonly broker?: StorageBroker;\n}\n\n/** A versioned view over a storage key — hydrate-with-migration on read, envelope-stamp on write. */\nexport interface VersionedStore<T> {\n  /** The storage key this store owns. */\n  readonly key: string;\n\n  /** The current schema version. */\n  readonly version: number;\n\n  /** Reads and, if needed, migrates the stored value; returns `initial` on absence or any unrecoverable state. */\n  read(): T;\n\n  /** Writes `value` stamped with the current version. */\n  write(value: T): void;\n\n  /** Removes the stored value. */\n  clear(): void;\n}\n\n/** The persisted shape: the schema version alongside the caller's data. */\ninterface Envelope {\n  readonly v: number;\n  readonly data: unknown;\n}\n\n/** Recognises a value as a version envelope (vs a legacy bare value written before versioning). */\nfunction isEnvelope(value: unknown): value is Envelope {\n  return typeof value === 'object' && value !== null && 'v' in value && 'data' in value && typeof (value as Envelope).v === 'number';\n}\n\n/**\n * Builds a {@link VersionedStore} over `key`. On `read`, a stored value is interpreted as:\n * - **current version** → returned as-is;\n * - **older version** → each `migrations[n]` is applied in turn from the stored version up to `version`, the\n *   upgraded value is written back, and returned. A gap in the chain (a missing `migrations[n]`) yields `initial`;\n * - **newer version** (a rollback to older code) → `initial`, leaving the forward-written value untouched;\n * - **legacy bare value** (no envelope) → treated as version `0` and migrated the same way.\n *\n * Any thrown error inside migration or the broker degrades to `initial`, mirroring the broker's never-throw contract.\n */\nexport function createVersionedStore<T>(options: VersionedStoreOptions<T>): VersionedStore<T> {\n  const { key, version, initial, migrations = {} } = options;\n  const broker = options.broker ?? localStorageStorageBroker;\n\n  /** Runs the migration chain from `fromVersion` to the current `version`; null when a step is missing. */\n  function migrate(fromVersion: number, data: unknown): { data: unknown } | null {\n    let current = data;\n    for (let from = fromVersion; from < version; from++) {\n      const step = migrations[from];\n      if (step === undefined) return null; // chain gap — cannot safely interpret the old shape\n      current = step(current);\n    }\n    return { data: current };\n  }\n\n  return {\n    key,\n    version,\n\n    read(): T {\n      try {\n        const stored = broker.read<unknown>(key);\n        if (stored === null) return initial;\n\n        const { v, data } = isEnvelope(stored) ? stored : { v: 0, data: stored };\n\n        if (v === version) return data as T;\n        if (v > version) return initial; // forward-written by newer code — don't guess\n\n        const migrated = migrate(v, data);\n        if (migrated === null) return initial;\n\n        // Persist the upgrade so the next read is a fast, migration-free hit.\n        broker.write<Envelope>(key, { v: version, data: migrated.data });\n        return migrated.data as T;\n      } catch {\n        return initial;\n      }\n    },\n\n    write(value: T): void {\n      broker.write<Envelope>(key, { v: version, data: value });\n    },\n\n    clear(): void {\n      broker.remove(key);\n    },\n  };\n}\n"],"names":[],"mappings":";;AAQA,MAAM,sBAAsB;AAOrB,SAAS,iBAAiB,OAAsB,WAAkC;AACvF,QAAM,QAAQ,CAAC,QAAwB,GAAG,SAAS,GAAG,mBAAmB,GAAG,GAAG;AAE/E,SAAO;AAAA,IACL,KAAQ,KAAuB;AAC7B,aAAO,MAAM,KAAQ,MAAM,GAAG,CAAC;AAAA,IACjC;AAAA,IAEA,MAAS,KAAa,OAAgB;AACpC,YAAM,MAAM,MAAM,GAAG,GAAG,KAAK;AAAA,IAC/B;AAAA,IAEA,OAAO,KAAmB;AACxB,YAAM,OAAO,MAAM,GAAG,CAAC;AAAA,IACzB;AAAA,EAAA;AAEJ;AC0BA,SAAS,WAAW,OAAmC;AACrD,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,SAAS,UAAU,SAAS,OAAQ,MAAmB,MAAM;AAC5H;AAYO,SAAS,qBAAwB,SAAsD;AAC5F,QAAM,EAAE,KAAK,SAAS,SAAS,aAAa,CAAA,MAAO;AACnD,QAAM,SAAS,QAAQ,UAAU;AAGjC,WAAS,QAAQ,aAAqB,MAAyC;AAC7E,QAAI,UAAU;AACd,aAAS,OAAO,aAAa,OAAO,SAAS,QAAQ;AACnD,YAAM,OAAO,WAAW,IAAI;AAC5B,UAAI,SAAS,OAAW,QAAO;AAC/B,gBAAU,KAAK,OAAO;AAAA,IACxB;AACA,WAAO,EAAE,MAAM,QAAA;AAAA,EACjB;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IAEA,OAAU;AACR,UAAI;AACF,cAAM,SAAS,OAAO,KAAc,GAAG;AACvC,YAAI,WAAW,KAAM,QAAO;AAE5B,cAAM,EAAE,GAAG,KAAA,IAAS,WAAW,MAAM,IAAI,SAAS,EAAE,GAAG,GAAG,MAAM,OAAA;AAEhE,YAAI,MAAM,QAAS,QAAO;AAC1B,YAAI,IAAI,QAAS,QAAO;AAExB,cAAM,WAAW,QAAQ,GAAG,IAAI;AAChC,YAAI,aAAa,KAAM,QAAO;AAG9B,eAAO,MAAgB,KAAK,EAAE,GAAG,SAAS,MAAM,SAAS,MAAM;AAC/D,eAAO,SAAS;AAAA,MAClB,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IAEA,MAAM,OAAgB;AACpB,aAAO,MAAgB,KAAK,EAAE,GAAG,SAAS,MAAM,OAAO;AAAA,IACzD;AAAA,IAEA,QAAc;AACZ,aAAO,OAAO,GAAG;AAAA,IACnB;AAAA,EAAA;AAEJ;"}

package/dist/foundation/storage/zustand/ZustandPersist.d.ts

@@ -0,0 +1,36 @@
+import { StorageBroker } from '../StorageBroker';
+/** The persisted envelope zustand writes — the store state plus zustand's own persist version. Mirrors `zustand/middleware`. */
+export interface StorageValue<S> {
+    /** The persisted store state. */
+    readonly state: S;
+    /** zustand's persist schema version (owned by the store's `persist` options), if set. */
+    readonly version?: number;
+}
+/**
+ * The post-JSON storage contract zustand's `persist` reads and writes through (mirror of zustand v5's
+ * `PersistStorage<S>`). Values are already-parsed `StorageValue` objects — no string encoding here, since the
+ * backing `StorageBroker` owns JSON serialization.
+ */
+export interface PersistStorage<S> {
+    /** Reads the persisted envelope for `name`, or null when absent or unreadable. */
+    getItem(name: string): StorageValue<S> | null;
+    /** Persists `value` under `name`. */
+    setItem(name: string, value: StorageValue<S>): void;
+    /** Removes any persisted value under `name`. */
+    removeItem(name: string): void;
+}
+/**
+ * Adapts `broker` into a zustand `PersistStorage<S>`. Because the broker already serializes to and from JSON,
+ * the returned storage hands zustand the parsed `StorageValue` directly (no `createJSONStorage` wrapper needed).
+ * It inherits the broker's failure-tolerance: an absent, malformed, or blocked read yields null, which zustand
+ * treats as "no persisted state" and falls back to the store's initial state.
+ *
+ * @example
+ * import { create } from 'zustand';
+ * import { persist } from 'zustand/middleware';
+ * import { localStorageStorageBroker } from '@wow-two-beta/ui-vue/foundation/storage';
+ * import { brokerPersistStorage } from '@wow-two-beta/ui-vue/foundation/storage/zustand';
+ *
+ * const useStore = create(persist(init, { name: 'app', storage: brokerPersistStorage(localStorageStorageBroker) }));
+ */
+export declare function brokerPersistStorage<S>(broker: StorageBroker): PersistStorage<S>;

package/dist/foundation/storage/zustand/index.d.ts

@@ -0,0 +1 @@
+export { type StorageValue, type PersistStorage, brokerPersistStorage, } from './ZustandPersist';

package/dist/foundation/storage/zustand/index.js

@@ -0,0 +1,11 @@
+function brokerPersistStorage(broker) {
+  return {
+    getItem: (name) => broker.read(name),
+    setItem: (name, value) => broker.write(name, value),
+    removeItem: (name) => broker.remove(name)
+  };
+}
+export {
+  brokerPersistStorage
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/storage/zustand/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/foundation/storage/zustand/ZustandPersist.ts"],"sourcesContent":["// zustand-persist adapter. Bridges a `StorageBroker` into the storage seam zustand's `persist` middleware\n// expects, so a zustand store persists through the SAME swappable broker as the rest of the SDK: the in-memory\n// double in tests, a `namespacedBroker` for isolation, or the SSR-safe `localStorage` broker in production — with\n// no store change. Versioning/migration stays with zustand's own `version`/`migrate` persist options (this\n// adapter is the *storage* seam, not a second migration system — use `createVersionedStore` for plain values).\n//\n// zustand is NOT a dependency here: the `PersistStorage`/`StorageValue` shapes below are a structural mirror of\n// zustand v5's (`zustand/middleware`). The object returned by `brokerPersistStorage` is structurally assignable\n// to zustand's real `PersistStorage<S>` on the consumer side, so the consumer simply brings zustand and passes\n// this in: `persist(init, { name, storage: brokerPersistStorage(broker) })`. Keep these types in sync with zustand v5.\n\nimport type { StorageBroker } from '../StorageBroker';\n\n/** The persisted envelope zustand writes — the store state plus zustand's own persist version. Mirrors `zustand/middleware`. */\nexport interface StorageValue<S> {\n  /** The persisted store state. */\n  readonly state: S;\n\n  /** zustand's persist schema version (owned by the store's `persist` options), if set. */\n  readonly version?: number;\n}\n\n/**\n * The post-JSON storage contract zustand's `persist` reads and writes through (mirror of zustand v5's\n * `PersistStorage<S>`). Values are already-parsed `StorageValue` objects — no string encoding here, since the\n * backing `StorageBroker` owns JSON serialization.\n */\nexport interface PersistStorage<S> {\n  /** Reads the persisted envelope for `name`, or null when absent or unreadable. */\n  getItem(name: string): StorageValue<S> | null;\n\n  /** Persists `value` under `name`. */\n  setItem(name: string, value: StorageValue<S>): void;\n\n  /** Removes any persisted value under `name`. */\n  removeItem(name: string): void;\n}\n\n/**\n * Adapts `broker` into a zustand `PersistStorage<S>`. Because the broker already serializes to and from JSON,\n * the returned storage hands zustand the parsed `StorageValue` directly (no `createJSONStorage` wrapper needed).\n * It inherits the broker's failure-tolerance: an absent, malformed, or blocked read yields null, which zustand\n * treats as \"no persisted state\" and falls back to the store's initial state.\n *\n * @example\n * import { create } from 'zustand';\n * import { persist } from 'zustand/middleware';\n * import { localStorageStorageBroker } from '@wow-two-beta/ui-vue/foundation/storage';\n * import { brokerPersistStorage } from '@wow-two-beta/ui-vue/foundation/storage/zustand';\n *\n * const useStore = create(persist(init, { name: 'app', storage: brokerPersistStorage(localStorageStorageBroker) }));\n */\nexport function brokerPersistStorage<S>(broker: StorageBroker): PersistStorage<S> {\n  return {\n    getItem: (name) => broker.read<StorageValue<S>>(name),\n    setItem: (name, value) => broker.write(name, value),\n    removeItem: (name) => broker.remove(name),\n  };\n}\n"],"names":[],"mappings":"AAoDO,SAAS,qBAAwB,QAA0C;AAChF,SAAO;AAAA,IACL,SAAS,CAAC,SAAS,OAAO,KAAsB,IAAI;AAAA,IACpD,SAAS,CAAC,MAAM,UAAU,OAAO,MAAM,MAAM,KAAK;AAAA,IAClD,YAAY,CAAC,SAAS,OAAO,OAAO,IAAI;AAAA,EAAA;AAE5C;"}

package/dist/foundation/sync/CreateSyncChannel.d.ts

@@ -0,0 +1,16 @@
+import { SyncChannel, SyncChannelOptions } from './SyncChannel';
+/**
+ * Opens this tab's endpoint on the named cross-tab channel. Messages posted here reach every other tab on the
+ * same origin with a channel of the same name — and never this tab, on either transport.
+ *
+ * Prefers `BroadcastChannel`, falls back to a `storage`-event channel written through a `StorageBroker`, and
+ * degrades to an inert no-op under SSR or when neither exists. Nothing throws: an unavailable API, a
+ * non-cloneable payload, blocked storage, and a listener that throws are all absorbed, so a single-tab app and
+ * a server render both behave as if the channel simply has no peers.
+ *
+ * @typeParam TMessage - The payload shape agreed between tabs; a compile-time contract, not a runtime guarantee.
+ * @param name - Channel name; peers are every endpoint sharing it on the origin.
+ * @param options - Transport selection, storage seam, key prefix, pinned id, and clock.
+ * @returns The endpoint: `post`, `subscribe`, `close`, plus its resolved identity and transport.
+ */
+export declare function createSyncChannel<TMessage>(name: string, options?: SyncChannelOptions): SyncChannel<TMessage>;

package/dist/foundation/sync/LeaderElection.d.ts

@@ -0,0 +1,88 @@
+import { Guid } from '../identifiers';
+import { SyncChannel, SyncChannelOptions } from './SyncChannel';
+/**
+ * Carries the election's traffic. Each signal repeats its sender's id in the payload rather than relying on the
+ * envelope, so the messages stay self-describing when read in devtools or replayed through another transport.
+ */
+export type LeaderSignal = 
+/** Asserts live leadership; resets every follower's expiry watchdog. */
+{
+    readonly kind: 'heartbeat';
+    readonly id: Guid;
+}
+/** Announces a bid for the empty throne; a live leader answers it with a heartbeat. */
+ | {
+    readonly kind: 'claim';
+    readonly id: Guid;
+}
+/** Surrenders leadership deliberately, so peers re-elect at once instead of waiting out the expiry. */
+ | {
+    readonly kind: 'resign';
+    readonly id: Guid;
+};
+/** Names a participant's position in the election. */
+export type LeaderRole = 'follower' | 'candidate' | 'leader';
+/** Defines the options that tune an election's timing and transport. */
+export interface LeaderElectionOptions {
+    /** Sets how often the leader re-asserts, in milliseconds; defaults to 1000. */
+    readonly heartbeatInterval?: number;
+    /** Sets how long a follower tolerates silence before claiming, in milliseconds; defaults to 3500. */
+    readonly timeout?: number;
+    /** Sets how long a candidate collects rival claims, in milliseconds; defaults to 150. */
+    readonly claimWindow?: number;
+    /**
+     * Supplies the channel to run on instead of opening one — the seam tests use to join a `memorySyncHub`. An
+     * injected channel is NOT closed by `close`; its owner keeps that duty.
+     */
+    readonly channel?: SyncChannel<LeaderSignal>;
+    /** Tunes the channel opened when `channel` is omitted; ignored when one is supplied. */
+    readonly channelOptions?: SyncChannelOptions;
+}
+/** Represents this tab's participation in a named election. */
+export interface LeaderElection {
+    /** Identifies this participant — the same id as the underlying channel's endpoint. */
+    readonly id: Guid;
+    /** Reports whether this tab currently holds the lease. */
+    readonly isLeader: boolean;
+    /** Reports this tab's position — `candidate` is the transient state inside a claim window. */
+    readonly role: LeaderRole;
+    /**
+     * Registers `listener` for the moment this tab takes leadership. Fires IMMEDIATELY and synchronously if it is
+     * already the leader when subscribing, so a late subscriber cannot miss the transition it was waiting for.
+     *
+     * @param listener - Invoked on becoming leader; a throw is swallowed.
+     * @returns An idempotent disposer.
+     */
+    onBecomeLeader(listener: () => void): () => void;
+    /**
+     * Registers `listener` for the moment this tab loses leadership — superseded by a lower id, or after
+     * `release`. Not fired by `close`, which is a teardown rather than a state change.
+     *
+     * @param listener - Invoked on losing leadership; a throw is swallowed.
+     * @returns An idempotent disposer.
+     */
+    onLoseLeader(listener: () => void): () => void;
+    /**
+     * Surrenders leadership deliberately and tells peers to re-elect at once. This tab stays in the election and
+     * may win again later — typically after `timeout`, by which point a peer has long since taken over.
+     */
+    release(): void;
+    /**
+     * Leaves the election entirely: resigns first if leading, then drops every timer and listener. Idempotent.
+     * Does not fire `onLoseLeader`. Closes the underlying channel only when this election opened it.
+     */
+    close(): void;
+}
+/**
+ * Joins the named election, in which exactly one participating tab holds leadership at a time.
+ *
+ * Leadership is a lease kept alive by a heartbeat, so a tab that dies without resigning is superseded once its
+ * lease expires — the reclaim path is the reason this exists. Ties are broken by lowest id, which for the
+ * time-ordered v7 ids minted here means the longest-open tab wins. Starts campaigning immediately; nothing
+ * throws, and under SSR or with no cross-tab transport the sole participant simply becomes leader.
+ *
+ * @param name - Election name; tabs sharing it on the origin compete for one leadership.
+ * @param options - Timing, and the channel to run on.
+ * @returns The participant handle: state, transition events, `release`, and `close`.
+ */
+export declare function createLeaderElection(name: string, options?: LeaderElectionOptions): LeaderElection;

package/dist/foundation/sync/MemorySyncHub.d.ts

@@ -0,0 +1,29 @@
+import { Guid } from '../identifiers';
+import { SyncChannel } from './SyncChannel';
+/** Represents an isolated in-process message bus standing in for one origin's set of browser tabs. */
+export interface MemorySyncHub {
+    /**
+     * Opens a new endpoint on `name` — the test's equivalent of opening another tab. Two calls with the same
+     * name yield two peers that can talk to each other but not to themselves.
+     *
+     * @typeParam TMessage - The payload shape shared by the endpoints on this channel.
+     * @param name - Channel name; only endpoints sharing it exchange messages.
+     * @param id - Pins the endpoint's id, for deterministic leader tie-breaks; minted as a v7 GUID when omitted.
+     * @returns A `SyncChannel` backed by this hub.
+     */
+    channel<TMessage>(name: string, id?: Guid): SyncChannel<TMessage>;
+    /** Counts the endpoints that are still open, across every channel name — the leak check after a teardown. */
+    readonly openCount: number;
+    /** Closes every endpoint and empties the hub, so one test cannot leak peers into the next. */
+    reset(): void;
+}
+/**
+ * Builds an isolated in-memory hub whose channels deliver synchronously and never touch a browser API.
+ *
+ * Use it to test cross-tab logic — including this slice's own leader election — under `vi.useFakeTimers`, where
+ * the real `BroadcastChannel`'s event-loop delivery would otherwise race the faked clock. Each hub is a closed
+ * world: two hubs never see each other's traffic.
+ *
+ * @returns A hub that mints `SyncChannel` endpoints and can be reset between tests.
+ */
+export declare function memorySyncHub(): MemorySyncHub;