@juspay/svelte-ui-components 4.24.0 → 4.25.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);
+    }
+}

package/dist/SpeechSynthesis/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The browser's `speechSynthesis` surface, reduced to what the controller drives. Unlike
+ * SpeechRecognition, lib.dom does declare this API -- but jsdom does not implement it at
+ * runtime, and the real SpeechSynthesisUtterance extends EventTarget, which would force
+ * every fake in tests to also fake addEventListener/removeEventListener/dispatchEvent.
+ * Utterance construction and event wiring are pushed inside the engine (`speak` takes a
+ * plain data request plus a callback bag) so a fake never has to impersonate a live DOM
+ * object -- only this flat surface -- and can be injected for tests and demos.
+ */
+export type SpeechSynthesisEngineLike = {
+    readonly speaking: boolean;
+    onvoiceschanged: (() => void) | null;
+    getVoices: () => readonly SpeechSynthesisVoice[];
+    speak: (request: SpeechUtteranceRequest, callbacks: SpeechUtteranceCallbacks) => void;
+    cancel: () => void;
+};
+export type SpeechUtteranceRequest = {
+    text: string;
+    lang: string;
+    rate: number;
+    pitch: number;
+    volume: number;
+    voice: SpeechSynthesisVoice | null;
+};
+export type SpeechUtteranceCallbacks = {
+    onstart: () => void;
+    onend: () => void;
+    onerror: (code: string) => void;
+};
+/** Per-call overrides for `speak()`; falls back to the controller's own options, then platform defaults. */
+export type SpeechUtteranceOptions = {
+    lang?: string;
+    rate?: number;
+    pitch?: number;
+    volume?: number;
+    voice?: SpeechSynthesisVoice | null;
+};
+/** User-facing copy the controller emits outside the per-error-code map. */
+export type SpeechSynthesisMessages = {
+    unsupported: string;
+    fallback: string;
+};
+export type SpeechSynthesisOptions = {
+    lang?: string;
+    rate?: number;
+    pitch?: number;
+    volume?: number;
+    /**
+     * Picks the voice for an utterance when neither the call nor the controller names one.
+     * Defaults to the platform's default voice among those matching `lang`, else the first
+     * voice matching `lang`, else the platform default overall, else null (let the engine
+     * pick). A caller-supplied list of preferred voice names is exactly this hook, called
+     * with the enumerated voices -- there is no baked-in preferred-voice list.
+     */
+    selectVoice?: (voices: readonly SpeechSynthesisVoice[], lang: string) => SpeechSynthesisVoice | null;
+    /** How long an error toast stays visible. */
+    errorTimeoutMs?: number;
+    /** Per-synthesis-error-code messages, merged over the built-in map. */
+    errorMessages?: Record<string, string>;
+    /** Copy overrides, merged over the built-in defaults. */
+    messages?: Partial<SpeechSynthesisMessages>;
+    /** Resolves the synthesis engine; defaults to the browser's. Injectable for tests. */
+    getSynthesisEngine?: () => SpeechSynthesisEngineLike | null;
+    onSpeakingChange?: (speaking: boolean) => void;
+    onError?: (message: string, code: string | null) => void;
+    /** Non-fatal internals worth logging; hosts wire this to their telemetry. */
+    onDiagnostic?: (event: string, detail: Record<string, string | number | boolean | null>) => void;
+};

package/dist/SpeechSynthesis/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -102,6 +102,7 @@ export { default as Gallery } from './Gallery/Gallery.svelte';
 export { ChatController } from './Chat/controller.svelte';
 export { partyOf } from './Chat/roles';
 export { SpeechToTextController } from './SpeechToText/controller.svelte';
+export { SpeechSynthesisController } from './SpeechSynthesis/controller.svelte';
 export { createCopyState } from './Snippet/copyState.svelte';
 export type * from './Button/properties';
 export type * from './Modal/properties';
@@ -189,6 +190,7 @@ export type * from './_chart/narrationHighlighter';
 export type * from './Chat/properties';
 export type * from './Chat/types';
 export type * from './SpeechToText/types';
+export type * from './SpeechSynthesis/types';
 export type * from './ChatHeader/properties';
 export type * from './ChatMessage/properties';
 export type * from './ChatMessageList/properties';

package/dist/index.js

@@ -102,6 +102,7 @@ export { default as Gallery } from './Gallery/Gallery.svelte';
 export { ChatController } from './Chat/controller.svelte';
 export { partyOf } from './Chat/roles';
 export { SpeechToTextController } from './SpeechToText/controller.svelte';
+export { SpeechSynthesisController } from './SpeechSynthesis/controller.svelte';
 export { createCopyState } from './Snippet/copyState.svelte';
 export { createSoundKit } from './SoundKit/SoundKit';
 export { validateInput, lockBodyScroll, unlockBodyScroll } from './utils';

package/dist-wc/index.js

@@ -40136,8 +40136,9 @@ function resolveTagAllowList(e) {
 function tagAllowed(e, t) {
 	return e === null || e.has(t);
 }
-function resolveRawHtmlMode(e) {
-	return e === "strip" ? "strip" : "escape";
+function resolveRawHtmlStrategy(e) {
+	let t = e?.rawHtml;
+	return t === "strip" ? "strip" : t === "sanitize" && typeof e?.htmlSanitizer == "function" ? "passthrough" : "escape";
 }
 function rawHtmlText(e) {
 	return "value" in e ? escapeHtml(e.value) : "content" in e ? rawHtmlText(e.content) : "childNodes" in e ? e.childNodes.map(rawHtmlText).join("") : "";
@@ -40145,7 +40146,7 @@ function rawHtmlText(e) {
 function createSanitizingRenderer(e, t, n, i) {
 	return {
 		html(e) {
-			return i === "strip" ? rawHtmlText(parseFragment(e.text)) : escapeHtml(e.text);
+			return i === "strip" ? rawHtmlText(parseFragment(e.text)) : i === "passthrough" ? e.text : escapeHtml(e.text);
 		},
 		link(n) {
 			return hasSafeProtocol(n.href, e.links) && tagAllowed(t, "a") ? !1 : escapeHtml(n.text);
@@ -40197,21 +40198,33 @@ function wrapTables(e, t, n) {
 	let i = typeof n == "string" ? n.trim() : "", a = i.length > 0 ? `${DEFAULT_TABLE_WRAPPER_CLASS} ${escapeHtml(i)}` : DEFAULT_TABLE_WRAPPER_CLASS, o = typeof t == "string" && t.length > 0 ? `<div class="${a}" tabindex="0" role="region" aria-label="${escapeHtml(t)}">` : `<div class="${a}" tabindex="0">`;
 	return e.replace(TABLE_OPEN, `${o}<table>`).replace(TABLE_CLOSE, "</table></div>");
 }
-function instanceFor(e) {
-	let t = e.breaks === !0, n = resolveProtocolSets(e.sanitize), i = resolveTagAllowList(e.sanitize?.allowedTags), a = e.sanitize?.disableTaskLists === !0, o = resolveRawHtmlMode(e.sanitize?.rawHtml), s = [
-		t ? "breaks" : "default",
-		[...n.links].sort().join(","),
-		[...n.images].sort().join(","),
-		i ? [...i].sort().join(",") : "*",
-		a ? "no-tasks" : "tasks",
-		o
+function instanceFor(e, t) {
+	let n = e.breaks === !0, i = resolveProtocolSets(e.sanitize), a = resolveTagAllowList(e.sanitize?.allowedTags), o = e.sanitize?.disableTaskLists === !0, s = [
+		n ? "breaks" : "default",
+		[...i.links].sort().join(","),
+		[...i.images].sort().join(","),
+		a ? [...a].sort().join(",") : "*",
+		o ? "no-tasks" : "tasks",
+		t
 	].join("|"), c = instances.get(s);
 	return c || (c = new q({
 		gfm: !0,
-		breaks: t,
-		renderer: createSanitizingRenderer(n, i, a, o)
+		breaks: n,
+		renderer: createSanitizingRenderer(i, a, o, t)
 	}), instances.set(s, c)), c;
 }
+function parseWith(e, t, n) {
+	let i = instanceFor(t, n), a = t.inline === !0 ? i.parseInline(e) : i.parse(e);
+	return typeof a == "string" ? a : null;
+}
+function runSanitizer(e, t) {
+	try {
+		let n = t(e);
+		return typeof n == "string" ? n : null;
+	} catch {
+		return null;
+	}
+}
 function unwrapMarkdownFence(e) {
 	let t = WHOLE_BODY_MARKDOWN_FENCE.exec(e);
 	if (t === null) return e;
@@ -40219,10 +40232,15 @@ function unwrapMarkdownFence(e) {
 	return a[0] !== n[0] || a.length < n.length || (n[0] === "~" ? INNER_TILDE_FENCE : INNER_BACKTICK_FENCE).test(i) ? e : i;
 }
 function renderMarkdown(e, t = {}) {
-	let n = t.unwrapFence === !0 ? unwrapMarkdownFence(e) : e, i = instanceFor(t), a = t.inline === !0 ? i.parseInline(n) : i.parse(n);
-	if (typeof a != "string") return "";
-	let o = annotateExternalLinks(a);
-	return t.inline === !0 ? o : wrapTables(o, t.tableLabel, t.tableWrapperClass);
+	let n = t.unwrapFence === !0 ? unwrapMarkdownFence(e) : e, i = resolveRawHtmlStrategy(t.sanitize), a = parseWith(n, t, i);
+	if (a === null) return "";
+	let o = a;
+	if (i === "passthrough") {
+		let e = t.sanitize?.htmlSanitizer;
+		o = (typeof e == "function" ? runSanitizer(a, e) : null) ?? parseWith(n, t, "escape") ?? "";
+	}
+	let s = annotateExternalLinks(o);
+	return t.inline === !0 ? s : wrapTables(s, t.tableLabel, t.tableWrapperClass);
 }
 var SAFE_LINK_PROTOCOLS, SAFE_IMAGE_PROTOCOLS, NUMERIC_REFERENCE, NAMED_WHITESPACE_REFERENCE, STRIPPED_BY_URL_PARSER, instances, EXTERNAL_ANCHOR_PATTERN, TABLE_OPEN, TABLE_CLOSE, DEFAULT_TABLE_WRAPPER_CLASS, INNER_BACKTICK_FENCE, INNER_TILDE_FENCE, WHOLE_BODY_MARKDOWN_FENCE, init_markdown = __esmMin((() => {
 	init_marked_esm(), init_dist(), SAFE_LINK_PROTOCOLS = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/svelte-ui-components",
-  "version": "4.24.0",
+  "version": "4.25.0",
   "description": "A themeable Svelte 5 UI component library with CSS custom property driven styling",
   "keywords": [
     "svelte",