@juspay/svelte-ui-components 4.23.0 → 4.25.0

package/dist/Checkbox/Checkbox.svelte

@@ -1,10 +1,11 @@
 <script lang="ts">
+  import { flushSync } from 'svelte';
   import type { CheckboxProperties } from './properties';
   import checkmarkSvg from '../assets/checkmark.svg?raw';
   import minusSvg from '../assets/minus.svg?raw';
 
   let {
-    text,
+    text = '',
     checked = $bindable(false),
     disabled = false,
     indeterminate = $bindable(false),
@@ -16,9 +17,13 @@
     ariaControls,
     ariaLabel,
     controlled = false,
-    attributes
+    attributes,
+    name,
+    value
   }: CheckboxProperties = $props();
 
+  let nativeInputEl: HTMLInputElement | null = $state(null);
+
   // Visible text wins over `ariaLabel`, which is what `properties.ts` has always
   // promised and what WCAG 2.5.3 requires: a control showing "Accept terms" must
   // carry that text in its accessible name, so letting an explicit label replace
@@ -44,15 +49,45 @@
     // for. Nothing is flipped locally, so a parent that declines the change
     // (a controlled table selection that rejects a row) keeps the box, the
     // native input and aria-checked all agreeing with the value it passed.
+    // No `input`/`change` dispatch here either: the input's checked state
+    // genuinely has not changed, so firing one would tell listeners (a
+    // parent `<form>`, a consumer's own `onchange`) about a flip that did
+    // not happen.
     if (controlled) {
       onclick?.(!checked);
       return;
     }
-    checked = !checked;
-    if (indeterminate) {
-      indeterminate = false;
-    }
+    // `flushSync` (rather than `await tick()`) applies the reactive
+    // `input.checked` write before the dispatch below runs, without handing
+    // control back to the event loop first. A keyboard repeat or a rapid
+    // double click stays a single synchronous call stack from gesture to
+    // dispatch: nothing can interleave a second `handleClick` in the middle
+    // (the race an `await` gap would allow), a screen reader sees the
+    // `input`/`change` pair land in the same tick as the key press it
+    // expects them tied to, and there is no unmount gap for `nativeInputEl`
+    // to go stale in.
+    flushSync(() => {
+      checked = !checked;
+      if (indeterminate) {
+        indeterminate = false;
+      }
+    });
     onclick?.(checked);
+    // The box (role="checkbox") is the only element the user can actually
+    // reach — the native input is aria-hidden, tabindex="-1" and
+    // pointer-events: none, purely a form-submission mirror. Because it
+    // never receives a real user click, the browser never fires a native
+    // `change` on it either, so a parent `<form>` listener (or a consumer's
+    // own `input.addEventListener('change', ...)`) never learns the value
+    // moved. `input`/`change` are dispatched manually to restore that signal.
+    // `composed: true` matters as much as `bubbles: true` here: native `input`/
+    // `change` are composed, and this component ships inside a shadow root
+    // (Checkbox.wc.svelte's `shadow: 'open'`) for every <sui-checkbox> consumer.
+    // `bubbles` alone stops at the shadow boundary; without `composed` the event
+    // never reaches a light-DOM `<form>`, silently defeating the whole point of
+    // wiring `name`/`value` onto this input for every web-component consumer.
+    nativeInputEl?.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    nativeInputEl?.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
   }
 
   function handleKeyDown(e: KeyboardEvent): void {
@@ -84,9 +119,12 @@
     class="native-checkbox"
     {checked}
     {disabled}
+    name={name ?? null}
+    value={value ?? null}
     tabindex={-1}
     aria-hidden="true"
     onclick={(e: MouseEvent) => e.stopPropagation()}
+    bind:this={nativeInputEl}
     data-pw={typeof testId === 'string' ? `${testId}-native-input` : null}
     testID={typeof testId === 'string' ? `${testId}-native-input` : null}
   />

package/dist/Checkbox/properties.d.ts

@@ -1,9 +1,15 @@
 import type { Snippet } from 'svelte';
-export type CheckboxProperties = MandatoryCheckboxProperties & OptionalCheckboxProperties & CheckboxEventProperties;
+export type CheckboxProperties = OptionalCheckboxProperties & CheckboxEventProperties;
 export type MandatoryCheckboxProperties = {
-    text: string;
+    text?: string;
 };
 export type OptionalCheckboxProperties = {
+    /** Visible label. Optional, defaulting to `''` (unlabelled) -- matching Toggle's
+     *  own `text` contract (Toggle/properties.ts) -- so a form-only checkbox
+     *  (`<Checkbox name="agree" />`) does not need an empty string just to compile.
+     *  A checkbox with no visible text needs `ariaLabel` for an accessible name;
+     *  see `ariaLabel` below. */
+    text?: string;
     checked?: boolean;
     disabled?: boolean;
     indeterminate?: boolean;
@@ -27,6 +33,16 @@ export type OptionalCheckboxProperties = {
      *  `aria-controls` to point at, or a consumer's own test attribute. Spread
      *  last, so a value here wins over the component's own `data-pw`. */
     attributes?: Record<string, string>;
+    /** Native `name` on the underlying `<input type="checkbox">`, so the control
+     *  participates in a surrounding `<form>`'s submission. Omitted by default:
+     *  the input stays nameless and outside `FormData`, exactly as before this
+     *  prop existed. */
+    name?: string;
+    /** Native `value` submitted when checked. Defaults to `"on"` — the native
+     *  checkbox default — when omitted, so setting `name` alone is enough to
+     *  form-associate a plain "checked or not" checkbox. An unchecked checkbox
+     *  never appears in `FormData`, matching native behaviour. */
+    value?: string;
 };
 export type CheckboxEventProperties = {
     onclick?: (checked: boolean) => void;

package/dist/MarkdownText/MarkdownText.svelte

@@ -9,11 +9,12 @@
     classes,
     tableLabel,
     tableWrapperClass,
-    sanitize
+    sanitize,
+    unwrapFence = false
   }: MarkdownTextProperties = $props();
 
   let html = $derived(
-    renderMarkdown(markdown, { breaks, tableLabel, tableWrapperClass, sanitize })
+    renderMarkdown(markdown, { breaks, tableLabel, tableWrapperClass, sanitize, unwrapFence })
   );
 </script>
 

package/dist/MarkdownText/markdown.d.ts

@@ -1,6 +1,11 @@
 import type { RenderMarkdownOptions } from './properties';
 /**
- * Markdown → HTML with the sanitizing pipeline above. Pure string transform —
- * no DOM involved — so it renders identically on server and client.
+ * Removes a fence that wraps the entire body and is labelled `markdown` or
+ * `md`, which is how models overwhelmingly emit a markdown answer. Returns the
+ * source untouched in every other case.
+ *
+ * An unlabelled fence is deliberately not unwrapped: it may be code the author
+ * meant to show, and there is nothing in the source to tell the two apart.
  */
+export declare function unwrapMarkdownFence(source: string): string;
 export declare function renderMarkdown(markdown: string, options?: RenderMarkdownOptions): string;

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,18 +331,118 @@ 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.
  */
+/**
+ * Matches a body that is ENTIRELY one fence labelled as markdown.
+ *
+ * Anchored at both ends on purpose. A peer's live implementation used an
+ * unanchored, global regex, so a message that *explained* markdown by quoting a
+ * fenced sample had the sample unwrapped and rendered as live markup. Anchoring
+ * means a fence with anything before or after it is left alone.
+ *
+ * The trailing whitespace is `\s*`, not `[ \t]*\s*` -- `[ \t]` is already a
+ * subset of `\s`, so pairing them let the engine try every split between the
+ * two quantifiers over the same characters. On uncontrolled input (this runs
+ * on chat/model text) that is a polynomial-time blow-up: a closing delimiter
+ * followed by many tabs and then one stray character made a single `.exec`
+ * call take seconds instead of a fraction of a millisecond.
+ *
+ * Groups: 1 = the opening run, 2 = the info string, 3 = the body, 4 = the closing run.
+ */
+/*
+ * Hoisted rather than built per call. Both carry only `m` -- no `g` or `y` --
+ * so they hold no `lastIndex` between calls and are safe to share.
+ */
+const INNER_BACKTICK_FENCE = /^[ \t]*`{3,}/m;
+const INNER_TILDE_FENCE = /^[ \t]*~{3,}/m;
+const WHOLE_BODY_MARKDOWN_FENCE = /^\s*(`{3,}|~{3,})[ \t]*(markdown|md)[ \t]*\r?\n([\s\S]*?)\r?\n?(`{3,}|~{3,})\s*$/i;
+/**
+ * Removes a fence that wraps the entire body and is labelled `markdown` or
+ * `md`, which is how models overwhelmingly emit a markdown answer. Returns the
+ * source untouched in every other case.
+ *
+ * An unlabelled fence is deliberately not unwrapped: it may be code the author
+ * meant to show, and there is nothing in the source to tell the two apart.
+ */
+export function unwrapMarkdownFence(source) {
+    const match = WHOLE_BODY_MARKDOWN_FENCE.exec(source);
+    if (match === null) {
+        return source;
+    }
+    const opening = match[1];
+    const body = match[3];
+    const closing = match[4];
+    // CommonMark lets a closing fence be LONGER than its opening, so the closing
+    // run is its own group and is checked here rather than by a `\1`
+    // backreference. The backreference did not refuse a longer close -- it
+    // matched the last three ticks and swept the extra one into the body, so
+    // `# Heading` came back as "# Heading\n`". Content corruption, not a refusal.
+    // Same character, and at least as long, is the actual rule.
+    if (closing[0] !== opening[0] || closing.length < opening.length) {
+        return source;
+    }
+    // A body still containing a fence run means the outer delimiters may not be a
+    // wrapper at all -- the regex is lazy to the LAST delimiter, so this shape is
+    // ambiguous. Refusing keeps a message quoting fenced code from being
+    // reinterpreted as markup, which is the failure this feature exists to avoid.
+    const innerFence = opening[0] === '~' ? INNER_TILDE_FENCE : INNER_BACKTICK_FENCE;
+    if (innerFence.test(body)) {
+        return source;
+    }
+    return body;
+}
 export function renderMarkdown(markdown, options = {}) {
-    const instance = instanceFor(options);
-    const output = options.inline === true ? instance.parseInline(markdown) : instance.parse(markdown);
-    if (typeof output !== 'string') {
+    /* 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 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

@@ -29,6 +29,21 @@ export type OptionalMarkdownTextProperties = {
      * whitespace-only string, keeps only `markdown-table-wrapper`.
      */
     tableWrapperClass?: string;
+    /**
+     * Remove a fence that wraps the ENTIRE value and is labelled `markdown` or
+     * `md`, then render what was inside it as markdown.
+     *
+     * Models very often return a whole answer wrapped that way, which renders as
+     * a code block showing source rather than as a document. Off by default,
+     * because unwrapping is not always right: a message quoting a fenced sample
+     * would be reinterpreted as live markup, which is exactly what an
+     * unanchored implementation elsewhere did.
+     *
+     * Only the whole-body case is unwrapped. A fence with anything before or
+     * after it, an unlabelled fence, a fence labelled as another language, and a
+     * body that still contains a fence delimiter are all left alone.
+     */
+    unwrapFence?: boolean;
     /**
      * Narrow which URL protocols survive on rendered links/images. See
      * `MarkdownSanitizeOptions`.
@@ -94,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;
@@ -115,6 +174,8 @@ export type RenderMarkdownOptions = {
     tableLabel?: string;
     /** Class name for the scroll region wrapping each table. See `MarkdownTextProperties.tableWrapperClass`. */
     tableWrapperClass?: string;
+    /** Unwrap a whole-body ```markdown fence. See `MarkdownTextProperties.unwrapFence`. */
+    unwrapFence?: boolean;
     /** Narrow the protocol allow-list. See `MarkdownSanitizeOptions`. */
     sanitize?: MarkdownSanitizeOptions;
 };

package/dist/Select/Select.svelte

@@ -36,7 +36,8 @@
     hierarchy = 'default',
     leftIcon,
     leftIconTestId,
-    usePortal = false
+    usePortal = false,
+    name
   }: SelectProperties = $props();
 
   function normalizeItems(source: SelectItem[] | string[]): SelectItem[] {
@@ -518,6 +519,16 @@
   bind:this={containerEl}
   {...typeof testId === 'string' ? { 'data-pw': testId, testID: testId } : {}}
 >
+  {#if typeof name === 'string' && name.length > 0}
+    <!-- No native <select> exists to carry `name`/`value` -- this is a custom
+         combobox/listbox. One hidden input per selected id mirrors a native
+         `<select multiple>`, which likewise submits one FormData entry per
+         selected <option> under the same name; `disabled` matches native
+         behaviour by excluding all of them from the submission. -->
+    {#each value as id (id)}
+      <input type="hidden" {name} value={id} {disabled} />
+    {/each}
+  {/if}
   <div class="select-control" class:has-clear={showClearButton}>
     <div
       class="select-trigger"

package/dist/Select/properties.d.ts

@@ -134,6 +134,17 @@ export type OptionalSelectProperties = {
      * `--select-dropdown-z-index` if it must sit above an even higher overlay.
      */
     usePortal?: boolean;
+    /**
+     * Native `name` for form submission. Select has no underlying `<select>` —
+     * it is a custom combobox/listbox — so setting this renders one
+     * `<input type="hidden">` per entry in `value`, each carrying the
+     * selected item's `id` as its value. Omitted by default: no hidden inputs
+     * are rendered and nothing changes for an existing consumer. Mirrors a
+     * native `<select multiple>`, which likewise submits one entry per
+     * selected `<option>` under the same name; an empty `value` array
+     * submits nothing, matching a native select with no selection.
+     */
+    name?: string;
 };
 export type SelectEventProperties = {
     onchange?: (value: string[]) => void;

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;
+}