@juspay/svelte-ui-components 4.24.0 → 4.26.0

package/dist/MarkdownText/markdown.js

@@ -115,9 +115,19 @@ function tagAllowed(allowed, tag) {
  * consumer can hand this anything at runtime, so anything other than the one
  * recognised opt-in degrades to today's escaping rather than throwing — an
  * unrecognised value must never be the reason content silently disappears.
+ *
+ * `'sanitize'` without a sanitizer resolves to `'escape'` for the same reason:
+ * the unsafe path stays unreachable by omission rather than by discipline.
  */
-function resolveRawHtmlMode(rawHtml) {
-    return rawHtml === 'strip' ? 'strip' : 'escape';
+function resolveRawHtmlStrategy(sanitize) {
+    const rawHtml = sanitize?.rawHtml;
+    if (rawHtml === 'strip') {
+        return 'strip';
+    }
+    if (rawHtml === 'sanitize' && typeof sanitize?.htmlSanitizer === 'function') {
+        return 'passthrough';
+    }
+    return 'escape';
 }
 // An inert, server-compatible HTML parser handles quoted delimiters, entities
 // and raw-text elements. Escaping its text nodes prevents decoded entities from
@@ -139,7 +149,23 @@ function rawHtmlText(node) {
 function createSanitizingRenderer(protocols, allowedTags, disableTaskLists, rawHtml) {
     return {
         html(token) {
-            return rawHtml === 'strip' ? rawHtmlText(parseFragment(token.text)) : escapeHtml(token.text);
+            if (rawHtml === 'strip') {
+                return rawHtmlText(parseFragment(token.text));
+            }
+            /*
+             * Emitted verbatim, and sanitized later in one pass over the whole
+             * document. Sanitizing here instead looks safer and is not: marked splits
+             * a block-level container into separate opening and closing tokens with
+             * the markdown between them as its own block, so a sanitizer -- which
+             * parses its input and serialises the tree back -- sees `<div class="x">`
+             * alone, balances it into `<div class="x"></div>`, and drops the lone
+             * `</div>`. The content the author wrapped then renders OUTSIDE its
+             * container. See markdown.test.ts, 'one pass over the assembled output'.
+             */
+            if (rawHtml === 'passthrough') {
+                return token.text;
+            }
+            return escapeHtml(token.text);
         },
         link(token) {
             if (hasSafeProtocol(token.href, protocols.links) && tagAllowed(allowedTags, 'a')) {
@@ -273,12 +299,19 @@ function wrapTables(html, label, wrapperClass) {
         : `<div class="${classAttr}" tabindex="0">`;
     return html.replace(TABLE_OPEN, `${open}<table>`).replace(TABLE_CLOSE, '</table></div>');
 }
-function instanceFor(options) {
+function instanceFor(options, rawHtml) {
     const breaks = options.breaks === true;
     const protocols = resolveProtocolSets(options.sanitize);
     const allowedTags = resolveTagAllowList(options.sanitize?.allowedTags);
     const disableTaskLists = options.sanitize?.disableTaskLists === true;
-    const rawHtml = resolveRawHtmlMode(options.sanitize?.rawHtml);
+    /*
+     * The strategy is what the renderer closes over, and it is a string, so the
+     * cache keeps working even though a caller now supplies a function: two
+     * consumers passing different sanitizers share one instance because that
+     * instance no longer knows about either of them. Keying on function identity
+     * would instead grow the map without bound, since the idiomatic call site
+     * passes a fresh inline arrow on every render.
+     */
     const key = [
         breaks ? 'breaks' : 'default',
         [...protocols.links].sort().join(','),
@@ -298,6 +331,26 @@ function instanceFor(options) {
     }
     return instance;
 }
+/** marked's parse can be configured to return a promise; this pipeline never is. */
+function parseWith(markdown, options, rawHtml) {
+    const instance = instanceFor(options, rawHtml);
+    const output = options.inline === true ? instance.parseInline(markdown) : instance.parse(markdown);
+    return typeof output === 'string' ? output : null;
+}
+/**
+ * A consumer's sanitizer is arbitrary code. `null` here means it did not return
+ * usable markup, and the caller falls back to the escaping path that was always
+ * there -- never to the unsanitized assembly.
+ */
+function runSanitizer(html, htmlSanitizer) {
+    try {
+        const sanitized = htmlSanitizer(html);
+        return typeof sanitized === 'string' ? sanitized : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Markdown → HTML with the sanitizing pipeline above. Pure string transform —
  * no DOM involved — so it renders identically on server and client.
@@ -362,14 +415,34 @@ export function unwrapMarkdownFence(source) {
     return body;
 }
 export function renderMarkdown(markdown, options = {}) {
+    /* Unwrapping happens before parsing, so the sanitizer sees the document the
+       author meant rather than a fence around it. */
     const source = options.unwrapFence === true ? unwrapMarkdownFence(markdown) : markdown;
-    const instance = instanceFor(options);
-    const output = options.inline === true ? instance.parseInline(source) : instance.parse(source);
-    if (typeof output !== 'string') {
+    const rawHtml = resolveRawHtmlStrategy(options.sanitize);
+    const parsed = parseWith(source, options, rawHtml);
+    if (parsed === null) {
         return '';
     }
-    /* Inline parsing produces no block elements, so there is no table to wrap. */
+    /*
+     * One pass, over the assembled document, because that is the only string in
+     * which a raw-HTML container and the markdown it wraps are both present and
+     * balanced. The cost is the contract: the sanitizer also sees markdown-
+     * generated HTML, so a configuration restrictive enough to strip `<p>` or
+     * `<code>` will strip them here too. Documented on `htmlSanitizer`.
+     */
+    let output = parsed;
+    if (rawHtml === 'passthrough') {
+        const htmlSanitizer = options.sanitize?.htmlSanitizer;
+        const sanitized = typeof htmlSanitizer === 'function' ? runSanitizer(parsed, htmlSanitizer) : null;
+        output = sanitized ?? parseWith(source, options, 'escape') ?? '';
+    }
+    /*
+     * After sanitization, so the library's own link hardening cannot be stripped
+     * by the caller's configuration -- and so it reaches links that arrived as
+     * raw HTML rather than markdown syntax.
+     */
     const linked = annotateExternalLinks(output);
+    /* Inline parsing produces no block elements, so there is no table to wrap. */
     return options.inline === true
         ? linked
         : wrapTables(linked, options.tableLabel, options.tableWrapperClass);

package/dist/MarkdownText/properties.d.ts

@@ -109,13 +109,57 @@ export type MarkdownSanitizeOptions = {
      * keep their existing rendering. Neither mode inserts source HTML into the DOM.
      */
     rawHtml?: MarkdownRawHtmlMode;
+    /**
+     * Sanitizer consulted only while `rawHtml` is `'sanitize'`. It is called ONCE
+     * per render, with the whole assembled document, and what it returns is what
+     * gets rendered.
+     *
+     * Note what that means: it sees markdown-generated HTML too, not only the raw
+     * HTML the author wrote. A configuration restrictive enough to drop `<p>`,
+     * `<code>` or `<table>` will drop them here as well, so allow the tags this
+     * component emits. It is not called per raw-HTML token, because marked splits
+     * a block-level container into separate opening and closing tokens -- and a
+     * sanitizer handed `<div class="x">` on its own balances it to
+     * `<div class="x"></div>`, which puts the content the author wrapped outside
+     * its container.
+     *
+     * This library deliberately does not implement HTML sanitization and does not
+     * depend on a sanitizer. Escaping everything is a provably safe default, and a
+     * sanitizer written here could only subtract from it: mutation XSS, namespace
+     * confusion and parse-then-reparse divergence are a specialist problem, and a
+     * home-grown one inside a package this many projects install would be the most
+     * dangerous file in it. Injection keeps that code in your dependency tree,
+     * where it can be audited and updated on its own schedule.
+     *
+     * It also keeps the contract honest: this signature says the returned string
+     * is YOUR responsibility. Pass DOMPurify's `sanitize`, or anything you trust.
+     * Note that the library's URL protocol allow-list guards markdown-syntax links
+     * and images only: a `javascript:` href written as raw HTML is emitted exactly
+     * as your sanitizer returns it, because re-checking that would mean parsing
+     * and rewriting the output -- the sanitization this option exists to delegate.
+     *
+     * If it throws or returns a non-string, the document is re-rendered with
+     * `'escape'` instead; the unsanitized assembly is never emitted.
+     *
+     * It must work on the server as well as in the browser. `MarkdownText`
+     * renders this through `{@html}` from a `$derived`, so a sanitizer that only
+     * works client-side (DOMPurify without a DOM, say) throws during SSR, falls
+     * back to escaped output there, and succeeds on hydration -- the two renders
+     * then disagree. Give it a server implementation, or leave `rawHtml` alone on
+     * server-rendered pages.
+     */
+    htmlSanitizer?: (html: string) => string;
 };
 /**
  * `'escape'` renders raw HTML as visible escaped text (the default, and what
- * the component has always done); `'strip'` removes it. See
+ * the component has always done); `'strip'` removes it; `'sanitize'` keeps raw
+ * HTML in place and hands the assembled document to
+ * `MarkdownSanitizeOptions.htmlSanitizer`, rendering what comes back. With no
+ * sanitizer supplied, `'sanitize'` behaves exactly like `'escape'` -- the unsafe
+ * path is unreachable by omission rather than by discipline. See
  * `MarkdownSanitizeOptions.rawHtml`.
  */
-export type MarkdownRawHtmlMode = 'escape' | 'strip';
+export type MarkdownRawHtmlMode = 'escape' | 'strip' | 'sanitize';
 export type RenderMarkdownOptions = {
     /** Render single newlines as `<br>` (GFM "breaks" mode). */
     breaks?: boolean;

package/dist/SpeechSynthesis/controller.svelte.d.ts

@@ -0,0 +1,89 @@
+import type { SpeechSynthesisEngineLike, SpeechSynthesisOptions, SpeechUtteranceOptions } from './types';
+export declare const DEFAULT_ERROR_TIMEOUT_MS = 4000;
+/**
+ * Clamps a caller-supplied numeric option into `[min, max]`, falling back to `fallback` for
+ * a non-finite value (`NaN`, `+/-Infinity`) rather than clamping garbage into range silently.
+ * Exported (and kept free of the class) so range enforcement is unit-testable without a
+ * browser or an engine.
+ */
+export declare function clampSpeechNumber(value: number, range: {
+    readonly min: number;
+    readonly max: number;
+    readonly fallback: number;
+}): number;
+/** Floors a caller-supplied toast delay at zero, falling back to the default for non-finite input. */
+export declare function clampErrorTimeoutMs(value: number): number;
+/**
+ * Wraps the real `speechSynthesis` global so the controller only ever talks to
+ * `SpeechSynthesisEngineLike` -- never a live `SpeechSynthesisUtterance` (which extends
+ * EventTarget). `speak()` builds and wires a real utterance internally per call; nothing
+ * outside this function ever sees it.
+ *
+ * `window.speechSynthesis` is a single page-wide singleton, so voice-change notification is
+ * wired with `addEventListener('voiceschanged', ...)` rather than the single-slot
+ * `.onvoiceschanged =` property -- the latter would let a second controller's registration
+ * silently overwrite a first controller's, since both would be assigning the same DOM
+ * property on the same object. `addEventListener` registration is additive: each call to
+ * this function adds its own listener, and the engine's own `onvoiceschanged` setter -- the
+ * injected-engine contract stays a plain property, unrelated to how this wrapper talks to
+ * the real DOM object underneath -- removes exactly that listener when the controller tears
+ * down (`set onvoiceschanged(null)`), never another instance's.
+ */
+export declare function createBrowserEngine(synth: SpeechSynthesis): SpeechSynthesisEngineLike;
+/**
+ * Headless text-to-speech over the browser's `speechSynthesis` API. The symmetric
+ * counterpart to `SpeechToTextController`: support detection, the voiceschanged dance for
+ * voice enumeration, toggle-to-stop orchestration (calling `speak()` while already speaking
+ * stops instead of starting a new utterance), and a self-hiding error toast. Rendering
+ * stays entirely with the host.
+ */
+export declare class SpeechSynthesisController {
+    /** True between the confirmed start and end of an utterance. */
+    speaking: boolean;
+    /** Often empty until the platform's voiceschanged fires -- see `initialize()`. */
+    voices: readonly SpeechSynthesisVoice[];
+    errorMessage: string;
+    errorVisible: boolean;
+    supported: boolean;
+    private readonly options;
+    private readonly messages;
+    private readonly errorMessages;
+    private engine;
+    private everInitialized;
+    private internalSpeaking;
+    private errorTimer;
+    private speechGeneration;
+    constructor(options?: SpeechSynthesisOptions);
+    /**
+     * Detects the API and starts tracking voices. Safe to call again; `speak` calls it
+     * lazily if the host never did. Re-initializing onto a *different* engine (a
+     * `getSynthesisEngine` swap, not merely calling this twice against the same one) tears the
+     * previous engine down first -- otherwise it would keep speaking with its `onvoiceschanged`
+     * handler still live, and a later `stop()`/`destroy()` would only ever reach the new engine.
+     */
+    initialize(): boolean;
+    /**
+     * Speaks `text`. Calling this while already speaking stops instead of starting a new
+     * utterance -- the same toggle-to-stop behavior as a mic button's start/stop click.
+     */
+    speak(text: string, options?: SpeechUtteranceOptions): void;
+    stop(): void;
+    /** Clears the toast timer and tears the engine connection down. */
+    destroy(): void;
+    /** Stops a superseded engine and detaches its listener; invalidates any utterance still in flight on it. */
+    private teardownEngine;
+    private refreshVoices;
+    /**
+     * Runs voice selection (the caller-supplied `selectVoice` hook, or the built-in default)
+     * guarded the same way `getSynthesisEngine` is guarded in `initialize()`: a throwing hook
+     * must not propagate out of `speak()` and strand the caller's utterance, so it is reported
+     * via `onDiagnostic` and selection falls back to the built-in default instead.
+     */
+    private resolveVoice;
+    private handleStart;
+    private handleEnd;
+    private handleUtteranceError;
+    private setSpeaking;
+    private showError;
+    private diagnose;
+}

package/dist/SpeechSynthesis/controller.svelte.js

@@ -0,0 +1,385 @@
+// The engine fires these when OUR OWN stop()/re-speak cancels an in-flight utterance --
+// expected traffic (per the Web Speech spec, cancel() interrupts via onerror, not onend),
+// not a failure worth surfacing as a toast.
+const SILENT_ERROR_CODES = ['canceled', 'interrupted'];
+const DEFAULT_ERROR_MESSAGES = {
+    'not-allowed': 'Speech playback is blocked. Allow audio in your browser settings to hear this read aloud.',
+    'audio-busy': 'Audio output is busy. Please try again.',
+    'audio-hardware': 'No audio output device found.',
+    network: 'A network error interrupted speech playback. Please check your connection and try again.',
+    'synthesis-failed': 'Could not read this text aloud. Please try again.',
+    'synthesis-unavailable': 'Speech playback is unavailable right now. Please try again.',
+    'language-unavailable': 'The requested language is not available for speech playback.',
+    'voice-unavailable': 'The requested voice is not available for speech playback.',
+    'text-too-long': 'This text is too long to read aloud.',
+    'invalid-argument': 'Could not read this text aloud due to an invalid option.'
+};
+const DEFAULT_MESSAGES = {
+    unsupported: 'Speech playback is not supported in this browser.',
+    fallback: 'Could not read this text aloud. Please try again.'
+};
+export const DEFAULT_ERROR_TIMEOUT_MS = 4000;
+// Web Speech spec ranges for SpeechSynthesisUtterance.rate/pitch/volume -- a value outside
+// these throws or is silently ignored depending on the browser, so the controller clamps
+// instead of leaving that behavior to chance.
+const RATE_RANGE = { min: 0.1, max: 10, fallback: 1 };
+const PITCH_RANGE = { min: 0, max: 2, fallback: 1 };
+const VOLUME_RANGE = { min: 0, max: 1, fallback: 1 };
+function errorDetail(raw) {
+    return raw instanceof Error ? raw.message : String(raw);
+}
+/**
+ * Clamps a caller-supplied numeric option into `[min, max]`, falling back to `fallback` for
+ * a non-finite value (`NaN`, `+/-Infinity`) rather than clamping garbage into range silently.
+ * Exported (and kept free of the class) so range enforcement is unit-testable without a
+ * browser or an engine.
+ */
+export function clampSpeechNumber(value, range) {
+    if (!Number.isFinite(value)) {
+        return range.fallback;
+    }
+    return Math.min(range.max, Math.max(range.min, value));
+}
+/** Floors a caller-supplied toast delay at zero, falling back to the default for non-finite input. */
+export function clampErrorTimeoutMs(value) {
+    if (!Number.isFinite(value)) {
+        return DEFAULT_ERROR_TIMEOUT_MS;
+    }
+    return Math.max(0, value);
+}
+/**
+ * Wraps the real `speechSynthesis` global so the controller only ever talks to
+ * `SpeechSynthesisEngineLike` -- never a live `SpeechSynthesisUtterance` (which extends
+ * EventTarget). `speak()` builds and wires a real utterance internally per call; nothing
+ * outside this function ever sees it.
+ *
+ * `window.speechSynthesis` is a single page-wide singleton, so voice-change notification is
+ * wired with `addEventListener('voiceschanged', ...)` rather than the single-slot
+ * `.onvoiceschanged =` property -- the latter would let a second controller's registration
+ * silently overwrite a first controller's, since both would be assigning the same DOM
+ * property on the same object. `addEventListener` registration is additive: each call to
+ * this function adds its own listener, and the engine's own `onvoiceschanged` setter -- the
+ * injected-engine contract stays a plain property, unrelated to how this wrapper talks to
+ * the real DOM object underneath -- removes exactly that listener when the controller tears
+ * down (`set onvoiceschanged(null)`), never another instance's.
+ */
+export function createBrowserEngine(synth) {
+    let voicesChangedHandler = null;
+    let listening = false;
+    const dispatch = () => {
+        voicesChangedHandler?.();
+    };
+    return {
+        get speaking() {
+            return synth.speaking;
+        },
+        get onvoiceschanged() {
+            return voicesChangedHandler;
+        },
+        set onvoiceschanged(handler) {
+            voicesChangedHandler = handler;
+            if (handler === null) {
+                if (listening) {
+                    synth.removeEventListener('voiceschanged', dispatch);
+                    listening = false;
+                }
+            }
+            else if (!listening) {
+                synth.addEventListener('voiceschanged', dispatch);
+                listening = true;
+            }
+        },
+        getVoices: () => synth.getVoices(),
+        cancel: () => synth.cancel(),
+        speak: (request, callbacks) => {
+            // `createBrowserEngine` is exported, so a caller can reach it directly and
+            // run it somewhere `SpeechSynthesisUtterance` does not exist. The
+            // controller's own path guards `window` before ever getting here; this
+            // guard is for the direct caller, and reports through the normal error
+            // channel rather than throwing out of `speak()`.
+            if (typeof SpeechSynthesisUtterance !== 'function') {
+                callbacks.onerror('synthesis-unavailable');
+                return;
+            }
+            const utterance = new SpeechSynthesisUtterance(request.text);
+            utterance.lang = request.lang;
+            utterance.rate = request.rate;
+            utterance.pitch = request.pitch;
+            utterance.volume = request.volume;
+            utterance.voice = request.voice;
+            utterance.onstart = () => callbacks.onstart();
+            utterance.onend = () => callbacks.onend();
+            utterance.onerror = (event) => callbacks.onerror(event.error);
+            synth.speak(utterance);
+        }
+    };
+}
+function defaultSynthesisEngine() {
+    if (typeof window === 'undefined' || !('speechSynthesis' in window)) {
+        return null;
+    }
+    return createBrowserEngine(window.speechSynthesis);
+}
+/** The primary language subtag (BCP 47), lowercased -- the part before the first '-', which
+ *  may be two letters ('en') or three ('fil', 'haw', 'yue'), not always the first two characters. */
+function primarySubtag(lang) {
+    const dashIndex = lang.indexOf('-');
+    const subtag = dashIndex === -1 ? lang : lang.slice(0, dashIndex);
+    return subtag.toLowerCase();
+}
+/** Platform default among voices matching `lang`'s primary subtag, else the first such match, else the platform default overall, else null. */
+function defaultSelectVoice(voices, lang) {
+    const subtag = primarySubtag(lang);
+    const matching = subtag.length > 0 ? voices.filter((voice) => primarySubtag(voice.lang) === subtag) : [];
+    const pool = matching.length > 0 ? matching : voices;
+    const preferred = pool.find((voice) => voice.default);
+    return preferred ?? pool[0] ?? null;
+}
+/**
+ * Headless text-to-speech over the browser's `speechSynthesis` API. The symmetric
+ * counterpart to `SpeechToTextController`: support detection, the voiceschanged dance for
+ * voice enumeration, toggle-to-stop orchestration (calling `speak()` while already speaking
+ * stops instead of starting a new utterance), and a self-hiding error toast. Rendering
+ * stays entirely with the host.
+ */
+export class SpeechSynthesisController {
+    /** True between the confirmed start and end of an utterance. */
+    speaking = $state(false);
+    /** Often empty until the platform's voiceschanged fires -- see `initialize()`. */
+    voices = $state([]);
+    errorMessage = $state('');
+    errorVisible = $state(false);
+    supported = $state(false);
+    options;
+    messages;
+    errorMessages;
+    engine = null;
+    everInitialized = false;
+    internalSpeaking = false;
+    errorTimer = null;
+    // Bumped per speak()/stop(); callbacks captured by a superseded utterance compare
+    // against it so a late onend/onerror cannot affect state for a newer utterance
+    // (mirrors SpeechToTextController's instanceGeneration guard).
+    speechGeneration = 0;
+    constructor(options = {}) {
+        this.options = options;
+        this.messages = { ...DEFAULT_MESSAGES, ...options.messages };
+        this.errorMessages = { ...DEFAULT_ERROR_MESSAGES, ...options.errorMessages };
+    }
+    /**
+     * Detects the API and starts tracking voices. Safe to call again; `speak` calls it
+     * lazily if the host never did. Re-initializing onto a *different* engine (a
+     * `getSynthesisEngine` swap, not merely calling this twice against the same one) tears the
+     * previous engine down first -- otherwise it would keep speaking with its `onvoiceschanged`
+     * handler still live, and a later `stop()`/`destroy()` would only ever reach the new engine.
+     */
+    initialize() {
+        this.everInitialized = true;
+        const getEngine = this.options.getSynthesisEngine ?? defaultSynthesisEngine;
+        let engine;
+        try {
+            engine = getEngine();
+        }
+        catch (error) {
+            this.diagnose('initializeFailed', { error: errorDetail(error) });
+            engine = null;
+        }
+        if (this.engine !== null && this.engine !== engine) {
+            this.teardownEngine(this.engine);
+        }
+        this.supported = engine !== null;
+        this.engine = engine;
+        if (engine === null) {
+            return false;
+        }
+        engine.onvoiceschanged = () => {
+            this.refreshVoices();
+        };
+        this.refreshVoices();
+        return true;
+    }
+    /**
+     * Speaks `text`. Calling this while already speaking stops instead of starting a new
+     * utterance -- the same toggle-to-stop behavior as a mic button's start/stop click.
+     */
+    speak(text, options = {}) {
+        if (this.internalSpeaking) {
+            this.stop();
+            return;
+        }
+        if (!this.everInitialized) {
+            this.initialize();
+        }
+        if (!this.supported || this.engine === null) {
+            this.showError(this.messages.unsupported);
+            return;
+        }
+        if (text.length === 0) {
+            return;
+        }
+        const lang = options.lang ?? this.options.lang ?? '';
+        const request = {
+            text,
+            lang,
+            rate: clampSpeechNumber(options.rate ?? this.options.rate ?? RATE_RANGE.fallback, RATE_RANGE),
+            pitch: clampSpeechNumber(options.pitch ?? this.options.pitch ?? PITCH_RANGE.fallback, PITCH_RANGE),
+            volume: clampSpeechNumber(options.volume ?? this.options.volume ?? VOLUME_RANGE.fallback, VOLUME_RANGE),
+            // `??` would treat an explicit `voice: null` (opt out of voice selection) the same as
+            // an absent option, silently overriding it with resolveVoice() -- checked against the
+            // key being unset instead, so `null` passes through untouched.
+            voice: typeof options.voice === 'undefined' ? this.resolveVoice(lang) : options.voice
+        };
+        this.speechGeneration += 1;
+        const generation = this.speechGeneration;
+        const isCurrent = () => generation === this.speechGeneration;
+        const callbacks = {
+            onstart: () => {
+                if (isCurrent()) {
+                    this.handleStart();
+                }
+            },
+            onend: () => {
+                if (isCurrent()) {
+                    this.handleEnd();
+                }
+            },
+            onerror: (code) => {
+                if (isCurrent()) {
+                    this.handleUtteranceError(code);
+                }
+            }
+        };
+        this.internalSpeaking = true;
+        this.errorMessage = '';
+        this.errorVisible = false;
+        try {
+            this.engine.speak(request, callbacks);
+        }
+        catch (error) {
+            this.internalSpeaking = false;
+            this.diagnose('speakThrew', { error: errorDetail(error) });
+            this.showError(this.messages.fallback);
+        }
+    }
+    stop() {
+        // Invalidate any in-flight utterance's callbacks before cancel() can fire them -- cancel()
+        // itself may synchronously trigger onerror('canceled'), which must NOT re-run through
+        // handleUtteranceError (that would double-fire onSpeakingChange with a redundant `false`).
+        // The diagnostic for a self-initiated stop is emitted here instead, since the generation
+        // bump means the engine round-trip can no longer be trusted to deliver it.
+        this.speechGeneration += 1;
+        if (this.internalSpeaking) {
+            this.internalSpeaking = false;
+            this.setSpeaking(false);
+            this.diagnose('utteranceCanceled', { code: 'canceled' });
+        }
+        if (this.engine !== null) {
+            this.engine.cancel();
+        }
+    }
+    /** Clears the toast timer and tears the engine connection down. */
+    destroy() {
+        this.speechGeneration += 1;
+        if (this.errorTimer !== null) {
+            clearTimeout(this.errorTimer);
+            this.errorTimer = null;
+        }
+        if (this.engine !== null) {
+            try {
+                this.engine.cancel();
+            }
+            catch (cancelError) {
+                this.diagnose('cancelErrorOnDestroy', { error: errorDetail(cancelError) });
+            }
+            this.engine.onvoiceschanged = null;
+            this.engine = null;
+        }
+        this.internalSpeaking = false;
+        // cancel() firing onerror is not guaranteed (a superseded generation may swallow it),
+        // so clear the public state too -- a consumer's speaking indicator must not survive teardown.
+        if (this.speaking) {
+            this.setSpeaking(false);
+        }
+    }
+    /** Stops a superseded engine and detaches its listener; invalidates any utterance still in flight on it. */
+    teardownEngine(engine) {
+        this.speechGeneration += 1;
+        if (this.internalSpeaking) {
+            this.internalSpeaking = false;
+            this.setSpeaking(false);
+            this.diagnose('utteranceCanceled', { code: 'canceled' });
+        }
+        try {
+            engine.cancel();
+        }
+        catch (cancelError) {
+            this.diagnose('cancelErrorOnReplace', { error: errorDetail(cancelError) });
+        }
+        engine.onvoiceschanged = null;
+    }
+    refreshVoices() {
+        if (this.engine === null) {
+            return;
+        }
+        // Copied rather than assigned through. `getSynthesisEngine` is a documented
+        // seam for tests, demos and non-browser hosts, so an engine returning a
+        // stable array it mutates in place is a supported shape -- and a raw array
+        // mutated behind a `$state` proxy is not reliably observed. The real
+        // `speechSynthesis.getVoices()` returns a fresh array (WebIDL sequence),
+        // which is why the browser path never showed this. A copy costs nothing and
+        // removes the aliasing entirely.
+        this.voices = [...this.engine.getVoices()];
+        this.diagnose('voicesChanged', { count: this.voices.length });
+    }
+    /**
+     * Runs voice selection (the caller-supplied `selectVoice` hook, or the built-in default)
+     * guarded the same way `getSynthesisEngine` is guarded in `initialize()`: a throwing hook
+     * must not propagate out of `speak()` and strand the caller's utterance, so it is reported
+     * via `onDiagnostic` and selection falls back to the built-in default instead.
+     */
+    resolveVoice(lang) {
+        const selectVoice = this.options.selectVoice ?? defaultSelectVoice;
+        try {
+            return selectVoice(this.voices, lang);
+        }
+        catch (error) {
+            this.diagnose('selectVoiceThrew', { error: errorDetail(error) });
+            return defaultSelectVoice(this.voices, lang);
+        }
+    }
+    handleStart() {
+        this.internalSpeaking = true;
+        this.setSpeaking(true);
+    }
+    handleEnd() {
+        this.internalSpeaking = false;
+        this.setSpeaking(false);
+    }
+    handleUtteranceError(code) {
+        this.internalSpeaking = false;
+        this.setSpeaking(false);
+        if (SILENT_ERROR_CODES.includes(code)) {
+            this.diagnose('utteranceCanceled', { code });
+            return;
+        }
+        this.showError(this.errorMessages[code] ?? this.messages.fallback, code);
+    }
+    setSpeaking(speaking) {
+        this.speaking = speaking;
+        this.options.onSpeakingChange?.(speaking);
+    }
+    showError(message, code = null) {
+        this.errorMessage = message;
+        this.errorVisible = true;
+        if (this.errorTimer !== null) {
+            clearTimeout(this.errorTimer);
+        }
+        this.errorTimer = setTimeout(() => {
+            this.errorVisible = false;
+        }, clampErrorTimeoutMs(this.options.errorTimeoutMs ?? DEFAULT_ERROR_TIMEOUT_MS));
+        this.options.onError?.(message, code);
+    }
+    diagnose(event, detail) {
+        this.options.onDiagnostic?.(event, detail);
+    }
+}