@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/speech/SpeechRecognitionResult.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Why a recognition session ended badly. Eight arms, four of them sharing `foundation/media`'s vocabulary.
+ *
+ * - `denied` — the microphone is blocked, by the user or by the browser / OS. Not retryable without a settings
+ *   change, so re-prompting on a timer only annoys.
+ * - `unavailable` — no usable input device. A desktop with no microphone, or an unplugged one.
+ * - `no-speech` — the engine listened and heard nothing. Ordinary, and the most common ending of all: expect it
+ *   whenever a user presses the button and hesitates.
+ * - `network` — the recognition service was unreachable. Chrome performs recognition SERVER-SIDE, so this is
+ *   routine offline, and no amount of retrying fixes it without a connection.
+ * - `aborted` — the app stopped the session (`abort()`, an unmount). A decision, not a failure.
+ * - `language-unsupported` — the service will not transcribe the requested `lang`.
+ * - `unsupported` — no recognition API here: SSR, or Firefox, which does not implement it.
+ * - `failed` — anything else, including an unreadable event.
+ */
+export type SpeechRecognitionStatus = 'denied' | 'unavailable' | 'no-speech' | 'network' | 'aborted' | 'language-unsupported' | 'unsupported' | 'failed';
+/** A recognition failure: the classified status plus a normalized `Error` for logs and telemetry. */
+export interface SpeechRecognitionFailure {
+    /** What went wrong, in terms a UI can branch on. */
+    readonly status: SpeechRecognitionStatus;
+    /** The normalized error, always present — carrying the raw platform code in its message. */
+    readonly error: Error;
+}
+/** One transcription update — interim or final — as handed to a recognizer's callbacks. */
+export interface SpeechTranscript {
+    /** The recognized text. */
+    readonly transcript: string;
+    /** `true` once the engine has committed to this phrase; `false` while it is still revising it. */
+    readonly isFinal: boolean;
+    /** The engine's `0`–`1` confidence. Chrome reports `0` for interim results — a hint, never a gate. */
+    readonly confidence: number;
+}
+/**
+ * Classifies a recognition `error` event into its {@link SpeechRecognitionFailure}.
+ *
+ * Matched on the `error` string rather than an `instanceof`, for the same reason `foundation/media` matches
+ * `DOMException` names: the event type is non-standard, differs between Chrome and Safari, and a test double
+ * throws a plain `{ error: 'no-speech' }`.
+ *
+ * Never throws. An unreadable event becomes `failed` carrying an `Error` that says so.
+ *
+ * @param event The `error` event the engine delivered.
+ * @returns The classified failure.
+ */
+export declare function toSpeechRecognitionFailure(event: unknown): SpeechRecognitionFailure;

package/dist/foundation/speech/SpeechRecognitionTypes.d.ts

@@ -0,0 +1,67 @@
+/** One candidate transcription of a recognized phrase. `maxAlternatives` decides how many a result carries. */
+export interface SpeechRecognitionAlternativeLike {
+    /** The recognized text. May be empty for a result the engine could not resolve. */
+    readonly transcript: string;
+    /** The engine's `0`–`1` confidence. Chrome reports `0` for interim results; treat it as a hint, never a gate. */
+    readonly confidence: number;
+}
+/**
+ * One phrase's worth of recognition — an array-like of alternatives, best first. Indexing is checked
+ * (`noUncheckedIndexedAccess`), so `result[0]` is `… | undefined` and every read here is guarded.
+ */
+export interface SpeechRecognitionResultLike {
+    /** `true` once the engine has committed to this phrase; `false` while it is still revising it. */
+    readonly isFinal: boolean;
+    /** How many alternatives this result carries. */
+    readonly length: number;
+    /** The alternatives, best first. */
+    readonly [index: number]: SpeechRecognitionAlternativeLike;
+}
+/** The growing array-like of results a session has produced. Not reset between events — see `resultIndex`. */
+export interface SpeechRecognitionResultListLike {
+    /** How many results the session has produced so far. */
+    readonly length: number;
+    /** The results, oldest first. */
+    readonly [index: number]: SpeechRecognitionResultLike;
+}
+/** The `result` event. The results list is cumulative, so `resultIndex` is what makes an update readable. */
+export interface SpeechRecognitionEventLike {
+    /** Index of the first result CHANGED by this event. Everything before it was already delivered. */
+    readonly resultIndex: number;
+    /** Every result of the session so far, including ones delivered by earlier events. */
+    readonly results: SpeechRecognitionResultListLike;
+}
+/** The `error` event. `error` is the code the status table maps; `message` is engine-authored and often empty. */
+export interface SpeechRecognitionErrorEventLike {
+    /** The error code — `not-allowed`, `no-speech`, `audio-capture`, `network`, `aborted`, … */
+    readonly error: string;
+    /** An engine-authored detail string. Absent or empty in Chrome for most codes. */
+    readonly message?: string;
+}
+/** The recognition instance itself — the members this slice sets, calls, or listens to, and nothing else. */
+export interface SpeechRecognitionLike {
+    /** BCP-47 language tag to transcribe. Same vocabulary as `foundation/i18n`'s locale. */
+    lang: string;
+    /** When `true` the session keeps listening past the first phrase. Chrome still ends it on a long silence. */
+    continuous: boolean;
+    /** When `true` the engine emits revisable partial results before committing to a phrase. */
+    interimResults: boolean;
+    /** How many alternatives each result should carry. */
+    maxAlternatives: number;
+    /** Fired for every interim revision and every committed phrase. */
+    onresult: ((event: SpeechRecognitionEventLike) => void) | null;
+    /** Fired for a denial, a missing microphone, a network failure, an abort, or silence. */
+    onerror: ((event: SpeechRecognitionErrorEventLike) => void) | null;
+    /** Fired once the engine is actually listening — always later than the `start()` call that asked for it. */
+    onstart: (() => void) | null;
+    /** Fired when the session ends, for ANY reason: `stop`, `abort`, an error, or the engine's own silence timeout. */
+    onend: (() => void) | null;
+    /** Begins a session. Throws `InvalidStateError` if one is already running — every call here is guarded. */
+    start(): void;
+    /** Ends the session, delivering whatever the engine has already recognized. */
+    stop(): void;
+    /** Ends the session immediately, discarding pending results. */
+    abort(): void;
+}
+/** The `SpeechRecognition` / `webkitSpeechRecognition` constructor, as read off the global scope. */
+export type SpeechRecognitionConstructor = new () => SpeechRecognitionLike;

package/dist/foundation/speech/SpeechResult.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The outcome of a {@link speak} attempt. Four arms because an utterance has four meaningfully different endings.
+ *
+ * - `spoken` — the engine reached the end of the text. It does NOT mean anyone heard it: the device may be muted.
+ * - `cancelled` — something called `cancelSpeech` (or the handle's `cancel`) before it finished. A decision, not
+ *   an error, and never reported as one.
+ * - `unsupported` — no `speechSynthesis` / `SpeechSynthesisUtterance` here: SSR, or a stripped webview.
+ * - `failed` — anything else, carrying the normalized `Error`.
+ */
+export type SpeakResult = {
+    readonly status: 'spoken';
+} | {
+    readonly status: 'cancelled';
+} | {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/** The `status` discriminant of a {@link SpeakResult} — for a consumer's own switch or status→copy map. */
+export type SpeakStatus = SpeakResult['status'];
+/**
+ * Classifies a `SpeechSynthesisUtterance` `error` event into its {@link SpeakResult}.
+ *
+ * Exported for the sibling `Speak` module and its tests; absent from the barrel, where `speak` is the surface a
+ * consumer wants. Never throws — an unrecognized or unreadable code becomes `failed` with an `Error` naming what
+ * arrived, so even a hostile event produces a usable result.
+ *
+ * @param event The `error` event the platform delivered.
+ * @returns `cancelled` for a cancellation code, `failed` for everything else.
+ */
+export declare function toSpeakFailure(event: unknown): SpeakResult;

package/dist/foundation/speech/SpeechSupport.d.ts

@@ -0,0 +1,69 @@
+import { SpeechRecognitionConstructor } from './SpeechRecognitionTypes';
+/** What this environment can do. Two independent answers — no browser guarantees both, and Firefox gives one. */
+export interface SpeechSupport {
+    /** Whether `speak` can reach a real `speechSynthesis` AND a real `SpeechSynthesisUtterance`. */
+    readonly synthesis: boolean;
+    /** Whether `createSpeechRecognizer` can reach a real (possibly `webkit`-prefixed) `SpeechRecognition`. */
+    readonly recognition: boolean;
+}
+/** A `SpeechSynthesisUtterance`-shaped constructor, as read off the global scope. */
+export type UtteranceConstructor = new (text?: string) => SpeechSynthesisUtterance;
+/**
+ * Reads `speechSynthesis` when it exists and carries `member` as a callable.
+ *
+ * Members are asked for one at a time because they fail one at a time: a polyfill can implement `speak` and
+ * `cancel` while omitting `pause` / `resume` (which several mobile engines genuinely do not honour). Guarded
+ * end-to-end; returns `undefined` under SSR. Internal to the slice — used by the sibling modules, absent from the
+ * barrel.
+ *
+ * @param member The method the caller is about to invoke, or `speak` when it only needs to read a flag.
+ * @returns The `SpeechSynthesis` object, or `undefined` when it or `member` is unusable.
+ */
+export declare function speechSynthesisWith(member: 'speak' | 'cancel' | 'pause' | 'resume' | 'getVoices'): SpeechSynthesis | undefined;
+/**
+ * Reads the `SpeechSynthesisUtterance` constructor.
+ *
+ * Separate from {@link speechSynthesisWith} because it is a separate global that can be separately missing.
+ * Internal to the slice; absent from the barrel.
+ *
+ * @returns The constructor, or `undefined` under SSR / on a partial implementation.
+ */
+export declare function utteranceConstructor(): UtteranceConstructor | undefined;
+/**
+ * Reads the `SpeechRecognition` constructor, unprefixed first, then `webkit`-prefixed.
+ *
+ * Unprefixed wins where both exist: it is the one newer Chrome maintains, and an engine shipping both aliases
+ * them anyway. Internal to the slice; absent from the barrel.
+ *
+ * @returns The constructor, or `undefined` under SSR and in Firefox.
+ */
+export declare function speechRecognitionConstructor(): SpeechRecognitionConstructor | undefined;
+/**
+ * Whether this environment can speak text aloud.
+ *
+ * Never throws. `false` under SSR, and `false` on a page carrying only one of the two required globals.
+ *
+ * @returns `true` when `speak` will reach a real engine.
+ */
+export declare function canSpeak(): boolean;
+/**
+ * Whether this environment can transcribe speech.
+ *
+ * A capability answer, NOT a permission answer: Chrome exposes the constructor to every page and only refuses at
+ * `start()` — with `not-allowed` for a blocked microphone, or `service-not-allowed` on an insecure origin. Treat
+ * `true` as "the button is worth rendering", never as "this will work".
+ *
+ * Never throws. `false` under SSR and in Firefox, which does not implement recognition at all.
+ *
+ * @returns `true` when a recognizer can be constructed.
+ */
+export declare function canRecognizeSpeech(): boolean;
+/**
+ * Reports both capabilities at once — the shape a consumer branches on when it renders a speak button, a dictate
+ * button, or both.
+ *
+ * Never throws. Both `false` under SSR.
+ *
+ * @returns The two independent answers.
+ */
+export declare function getSpeechSupport(): SpeechSupport;

package/dist/foundation/speech/UseSpeechRecognition.d.ts

@@ -0,0 +1,45 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { RecognizerStartResult, SpeechRecognizerOptions } from './CreateSpeechRecognizer';
+import { SpeechRecognitionFailure } from './SpeechRecognitionResult';
+/** Options for {@link useSpeechRecognition} — the recognizer's own, with the composable layering state on top. */
+export type UseSpeechRecognitionOptions = SpeechRecognizerOptions;
+/** What {@link useSpeechRecognition} returns. */
+export interface SpeechRecognitionControls {
+    /** Whether this browser can transcribe at all. `false` under SSR and in Firefox — gate the button on it. */
+    readonly supported: Readonly<ShallowRef<boolean>>;
+    /** Whether the engine is listening. `false` in the gap between `start()` and the engine actually opening the microphone. */
+    readonly listening: Readonly<ShallowRef<boolean>>;
+    /** Every committed phrase of the session, space-joined. Survives an ended session; cleared by `reset`. */
+    readonly transcript: Readonly<ShallowRef<string>>;
+    /** The current uncommitted text. Requires `interimResults`; cleared when the phrase commits or the session ends. */
+    readonly interimTranscript: Readonly<ShallowRef<string>>;
+    /** The last classified failure, or `null`. Cleared when a new session starts. `no-speech` lands here too. */
+    readonly error: Readonly<ShallowRef<SpeechRecognitionFailure | null>>;
+    /** Begins a session. Safe to call twice — the second answers `already-started`. */
+    readonly start: () => RecognizerStartResult;
+    /** Ends the session, keeping what the engine already recognized. */
+    readonly stop: () => void;
+    /** Ends the session immediately, discarding pending results. */
+    readonly abort: () => void;
+    /** Clears `transcript`, `interimTranscript`, and `error`. Does not touch the session. */
+    readonly reset: () => void;
+}
+/**
+ * Transcribes speech into accumulating reactive state, aborting the session when the scope is disposed.
+ *
+ * ```vue
+ * const dictation = useSpeechRecognition({ interimResults: true, continuous: true });
+ * <button :disabled="!dictation.supported.value" @click="dictation.start()">
+ *   {{ dictation.listening.value ? 'Listening…' : 'Dictate' }}
+ * </button>
+ * <p>{{ dictation.transcript.value }} <em>{{ dictation.interimTranscript.value }}</em></p>
+ * ```
+ *
+ * `lang` defaults to the active `LocaleProvider` locale, so a localized app transcribes the language its user is
+ * reading. Nothing throws.
+ *
+ * @param options Session shape and pass-through callbacks — each is called in addition to the state updates.
+ *   A ref or getter is read at call time, so a reactive options source is followed.
+ * @returns The transcript state plus the four controls.
+ */
+export declare function useSpeechRecognition(options?: MaybeRefOrGetter<UseSpeechRecognitionOptions | undefined>): SpeechRecognitionControls;

package/dist/foundation/speech/UseSpeechSynthesis.d.ts

@@ -0,0 +1,37 @@
+import { ShallowRef } from 'vue';
+import { SpeakOptions } from './Speak';
+import { SpeakResult } from './SpeechResult';
+/** What {@link useSpeechSynthesis} returns. */
+export interface SpeechSynthesisControls {
+    /** Whether this browser can speak. `false` under SSR — render the button only once this is `true`. */
+    readonly supported: Readonly<ShallowRef<boolean>>;
+    /** The installed voices. Starts empty and fills in asynchronously; see `ListVoices` for why that is normal. */
+    readonly voices: Readonly<ShallowRef<readonly SpeechSynthesisVoice[]>>;
+    /** Whether this composable has an utterance in flight. Not the engine's global flag — another component's speech is not this one's. */
+    readonly speaking: Readonly<ShallowRef<boolean>>;
+    /** Whether this composable paused the engine. */
+    readonly paused: Readonly<ShallowRef<boolean>>;
+    /** Speaks text, resolving to the outcome. Never throws. Defaults `lang` to the active locale. */
+    readonly speak: (text: string, options?: SpeakOptions) => Promise<SpeakResult>;
+    /** Stops all speech in the document — the platform has no narrower cancel. In-flight `speak` calls settle as `cancelled`. */
+    readonly cancel: () => void;
+    /** Pauses the engine. See `SpeechControls` for Chrome-on-Android's pause-is-cancel behaviour. */
+    readonly pause: () => void;
+    /** Resumes a paused engine. */
+    readonly resume: () => void;
+}
+/**
+ * Speaks text and owns the lifecycle — cancelling this composable's in-flight speech when the scope is disposed.
+ *
+ * ```vue
+ * const speech = useSpeechSynthesis();
+ * <button :disabled="!speech.supported.value" @click="speech.speak(article)">
+ *   {{ speech.speaking.value ? 'Stop' : 'Read aloud' }}
+ * </button>
+ * ```
+ *
+ * Inherits the slice's never-throws contract — a rejected promise is not one of the outcomes.
+ *
+ * @returns The state plus the four controls.
+ */
+export declare function useSpeechSynthesis(): SpeechSynthesisControls;

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

@@ -0,0 +1,10 @@
+export { canSpeak, canRecognizeSpeech, getSpeechSupport, type SpeechSupport } from './SpeechSupport';
+export { type SpeakResult, type SpeakStatus } from './SpeechResult';
+export { speak, type SpeakOptions, type SpeechHandle } from './Speak';
+export { cancelSpeech, pauseSpeech, resumeSpeech, isSpeaking, isSpeechPaused } from './SpeechControls';
+export { listVoices, listVoicesSync, findVoice, voicesForLang, DefaultVoicesTimeoutMs, type ListVoicesOptions, } from './ListVoices';
+export { useSpeechSynthesis, type SpeechSynthesisControls, } from './UseSpeechSynthesis';
+export { type SpeechRecognitionStatus, type SpeechRecognitionFailure, type SpeechTranscript, } from './SpeechRecognitionResult';
+export { createSpeechRecognizer, type SpeechRecognizer, type SpeechRecognizerOptions, type RecognizerStartResult, } from './CreateSpeechRecognizer';
+export { useSpeechRecognition, type SpeechRecognitionControls, type UseSpeechRecognitionOptions, } from './UseSpeechRecognition';
+export type { SpeechRecognitionLike, SpeechRecognitionEventLike, SpeechRecognitionErrorEventLike, SpeechRecognitionResultLike, SpeechRecognitionResultListLike, SpeechRecognitionAlternativeLike, SpeechRecognitionConstructor, } from './SpeechRecognitionTypes';