@colixsystems/widget-sdk 0.90.0 → 0.91.0

package/README.md

@@ -35,6 +35,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
 | **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
+| **CORE** | `useSpeechToText(options?)` | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
@@ -61,6 +62,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
+`v0.91.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.91.0 (contract 1.64.0)
+
+**New `useSpeechToText()` hook — dictate into text with the device's on-device recogniser.** A new CORE hook reading a new `speech` capability on the existing `ctx.device` slice. Returns `{ transcript, partial, listening, supported, error, start, stop, abort, reset }`. Capture is **imperative** — call `start()` from a user gesture (a `Pressable.onPress`); the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` accumulates finalised speech across utterances; `partial` holds the guess the recogniser has not committed yet (empty unless `options.interimResults`). `stop()` finalises and keeps what was heard, `abort()` discards the current utterance, `reset()` clears both. `options` (`{ lang, continuous, interimResults }`) pass through to the host. Rejections surface as a structured `SpeechToTextError` (new named export) with a stable `.code` (`PERMISSION_DENIED` / `NO_SPEECH` / `LANGUAGE_UNSUPPORTED` / `NETWORK` / `ABORTED` / `UNSUPPORTED` / `INTERNAL`). It needs **no manifest scope** and **no `requestedScopes` entry**.
+
+Recognition runs **on device**: no audio is uploaded, nothing reaches our servers, and no AI credit is spent — so the hook is available to every workspace regardless of its AI data-residency policy. The web Player brokers it via the browser's `SpeechRecognition`; the Expo export via `expo-speech-recognition`, whose config plugin declares the microphone and speech permissions the runtime needs. Both hosts emit the same Web Speech error vocabulary, so one mapping serves both.
+
+**Always gate your mic affordance on `supported`.** Firefox ships no `SpeechRecognition` at all, so `supported` is `false` there and `start()` rejects with `UNSUPPORTED` — render the plain text field instead of a dead button. The `speech` capability is optional and forwarded independently of `geolocation`, so a host that brokers one still brokers the other.
+
+Additive — one new hook, one new optional device capability, one new error class; no existing export changed signature.
+
 `v0.90.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
 ### What's new in 0.89.0 (contract unchanged)

package/dist/contract.cjs

@@ -1194,6 +1194,35 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // Host-brokered on-device speech recognition. Optional slice; the hook
+  // reports supported:false rather than throwing at render.
+  {
+    name: "useSpeechToText",
+    signature: "useSpeechToText(options?)",
+    description:
+      "Dictate into text with the device's ON-DEVICE speech recogniser. Returns { transcript, partial, listening, supported, " +
+      "error, start, stop, abort, reset }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a mic button); " +
+      "the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` " +
+      "accumulates finalised speech; `partial` holds the uncommitted guess (empty unless options.interimResults). stop() " +
+      "finalises and keeps what was heard, abort() discards it, reset() clears both. Recognition runs ON DEVICE — no audio is " +
+      "uploaded and no AI credit is spent. start() rejects with a SpeechToTextError whose .code is one of PERMISSION_DENIED | " +
+      "NO_SPEECH | LANGUAGE_UNSUPPORTED | NETWORK | ABORTED | UNSUPPORTED | INTERNAL. options: { lang, continuous, " +
+      "interimResults }. Check `supported` before rendering a mic button — a browser without SpeechRecognition (Firefox) " +
+      "reports false. Identical on web (SpeechRecognition) and the Expo export (expo-speech-recognition).",
+    returnShape: {
+      transcript: "string  // finalised speech, accumulated",
+      partial: "string  // uncommitted guess; '' unless interimResults",
+      listening: "boolean",
+      supported: "boolean  // false when the host brokers no recogniser",
+      error: "SpeechToTextError | null",
+      start: "() => Promise<void>  // rejects with SpeechToTextError",
+      stop: "() => Promise<void>  // finalise, keep the transcript",
+      abort: "() => void  // cancel, discard the utterance",
+      reset: "() => void  // clear transcript + partial + error",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1769,11 +1798,15 @@ const WIDGET_CONTEXT_SHAPE = {
   device: {
     description:
       "Optional host-brokered device capabilities. " +
-      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
-      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
-      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
+      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> } }. " +
+      "Backs useGeolocation() and useSpeechToText(). The web Player brokers them via navigator.geolocation and " +
+      "window.SpeechRecognition; the Expo export via expo-location and expo-speech-recognition. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
+      "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
+      "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted).",
     required: false,
-    fields: { geolocation: "object" },
+    fields: { geolocation: "object", speech: "object" },
   },
 };
 
@@ -2822,7 +2855,7 @@ const CONTRACT = deepFreeze({
   //    published widget keeps validating. The script's `triggerType` global
   //    now names the trigger that actually FIRED the run ('manual' and 'app'
   //    included), which is what makes a multi-trigger script able to branch.
-  version: "1.63.0",
+  version: "1.64.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1194,6 +1194,35 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // Host-brokered on-device speech recognition. Optional slice; the hook
+  // reports supported:false rather than throwing at render.
+  {
+    name: "useSpeechToText",
+    signature: "useSpeechToText(options?)",
+    description:
+      "Dictate into text with the device's ON-DEVICE speech recogniser. Returns { transcript, partial, listening, supported, " +
+      "error, start, stop, abort, reset }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a mic button); " +
+      "the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` " +
+      "accumulates finalised speech; `partial` holds the uncommitted guess (empty unless options.interimResults). stop() " +
+      "finalises and keeps what was heard, abort() discards it, reset() clears both. Recognition runs ON DEVICE — no audio is " +
+      "uploaded and no AI credit is spent. start() rejects with a SpeechToTextError whose .code is one of PERMISSION_DENIED | " +
+      "NO_SPEECH | LANGUAGE_UNSUPPORTED | NETWORK | ABORTED | UNSUPPORTED | INTERNAL. options: { lang, continuous, " +
+      "interimResults }. Check `supported` before rendering a mic button — a browser without SpeechRecognition (Firefox) " +
+      "reports false. Identical on web (SpeechRecognition) and the Expo export (expo-speech-recognition).",
+    returnShape: {
+      transcript: "string  // finalised speech, accumulated",
+      partial: "string  // uncommitted guess; '' unless interimResults",
+      listening: "boolean",
+      supported: "boolean  // false when the host brokers no recogniser",
+      error: "SpeechToTextError | null",
+      start: "() => Promise<void>  // rejects with SpeechToTextError",
+      stop: "() => Promise<void>  // finalise, keep the transcript",
+      abort: "() => void  // cancel, discard the utterance",
+      reset: "() => void  // clear transcript + partial + error",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1769,11 +1798,15 @@ const WIDGET_CONTEXT_SHAPE = {
   device: {
     description:
       "Optional host-brokered device capabilities. " +
-      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
-      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
-      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
+      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> } }. " +
+      "Backs useGeolocation() and useSpeechToText(). The web Player brokers them via navigator.geolocation and " +
+      "window.SpeechRecognition; the Expo export via expo-location and expo-speech-recognition. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
+      "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
+      "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted).",
     required: false,
-    fields: { geolocation: "object" },
+    fields: { geolocation: "object", speech: "object" },
   },
 };
 
@@ -2822,7 +2855,7 @@ const CONTRACT = deepFreeze({
   //    published widget keeps validating. The script's `triggerType` global
   //    now names the trigger that actually FIRED the run ('manual' and 'app'
   //    included), which is what makes a multi-trigger script able to branch.
-  version: "1.63.0",
+  version: "1.64.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -916,6 +916,234 @@ export function useGeolocation(options) {
   };
 }
 
+/**
+ * Error surfaced by `useSpeechToText()` (thrown by `start()` and stored in the
+ * hook's `error` slot). Carries a stable `code` so widgets branch on the error
+ * class without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED"    — the user or OS refused microphone access.
+ *   - "NO_SPEECH"            — capture ended without any speech detected.
+ *   - "LANGUAGE_UNSUPPORTED" — no recogniser exists for the requested language.
+ *   - "NETWORK"              — the recogniser needed the network and failed.
+ *   - "ABORTED"              — capture was cancelled (abort(), or a new start()).
+ *   - "UNSUPPORTED"          — this host does not broker speech recognition.
+ *   - "INTERNAL"             — anything else.
+ */
+export class SpeechToTextError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "SpeechToTextError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+// Both hosts emit the Web Speech API's error vocabulary (the Expo export's
+// recogniser mirrors it deliberately), so one map serves web and native.
+const SPEECH_ERROR_CODES = {
+  "not-allowed": "PERMISSION_DENIED",
+  "service-not-allowed": "PERMISSION_DENIED",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  "no-speech": "NO_SPEECH",
+  NO_SPEECH: "NO_SPEECH",
+  // Android's recogniser reports a silence timeout instead of "no-speech".
+  "speech-timeout": "NO_SPEECH",
+  "language-not-supported": "LANGUAGE_UNSUPPORTED",
+  LANGUAGE_UNSUPPORTED: "LANGUAGE_UNSUPPORTED",
+  network: "NETWORK",
+  NETWORK: "NETWORK",
+  aborted: "ABORTED",
+  ABORTED: "ABORTED",
+  UNSUPPORTED: "UNSUPPORTED",
+};
+
+/** Coerce a thrown/emitted value into a SpeechToTextError with a stable code. */
+function toSpeechToTextError(err) {
+  if (err instanceof SpeechToTextError) return err;
+  const raw =
+    err && err.code !== undefined && err.code !== null ? err.code : null;
+  const code = (raw !== null && SPEECH_ERROR_CODES[raw]) || "INTERNAL";
+  const message =
+    (err && typeof err.message === "string" && err.message) ||
+    "Speech recognition failed";
+  return new SpeechToTextError(code, message, { cause: err });
+}
+
+/**
+ * Dictate into text with the device's on-device speech recogniser. Returns
+ * `{ transcript, partial, listening, supported, error, start, stop, abort,
+ * reset }`.
+ *
+ * Capture is IMPERATIVE — call `start()` from a user gesture (a tap on a mic
+ * button). Both the browser and the mobile OS gate the microphone prompt on a
+ * user gesture, so the hook never listens on mount.
+ *
+ * `transcript` accumulates finalised speech; `partial` holds the in-flight
+ * guess the recogniser has not committed yet (empty unless
+ * `options.interimResults`). `stop()` finalises and keeps what was heard;
+ * `abort()` discards it. `reset()` clears both back to empty.
+ *
+ * Recognition runs ON DEVICE — no audio is uploaded and no AI credit is spent.
+ * The SAME hook drives both platforms: the web Player brokers it through the
+ * browser's SpeechRecognition, the Expo export through
+ * expo-speech-recognition.
+ *
+ * Safe-by-default: on a host that does not inject `ctx.device.speech` (or a
+ * browser without SpeechRecognition), `supported` is false and `start()`
+ * rejects with `code: "UNSUPPORTED"` rather than throwing at render, so a
+ * widget can call the hook unconditionally and hide its mic button.
+ */
+export function useSpeechToText(options) {
+  const ctx = useWidgetContextOrThrow("useSpeechToText");
+  const [transcript, setTranscript] = useState("");
+  const [partial, setPartial] = useState("");
+  const [listening, setListening] = useState(false);
+  const [error, setError] = useState(null);
+
+  // `ctx` is a fresh identity every host render — hold the live client and
+  // options in refs so the returned callbacks stay stable.
+  const clientRef = useRef(ctx.device && ctx.device.speech);
+  clientRef.current = ctx.device && ctx.device.speech;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  // The live capture session, so stop/abort/unmount can reach it.
+  const sessionRef = useRef(null);
+  const runRef = useRef(0);
+
+  const supported = Boolean(
+    clientRef.current &&
+    typeof clientRef.current.start === "function" &&
+    (typeof clientRef.current.isSupported !== "function" ||
+      clientRef.current.isSupported()),
+  );
+
+  // Abandoning a mounted recogniser leaves the mic hot on both hosts, so
+  // release it when the widget unmounts.
+  useEffect(
+    () => () => {
+      runRef.current += 1;
+      const session = sessionRef.current;
+      sessionRef.current = null;
+      if (session && typeof session.abort === "function") {
+        try {
+          session.abort();
+        } catch {
+          /* the host is already tearing the session down */
+        }
+      }
+    },
+    [],
+  );
+
+  const reset = useCallback(() => {
+    setTranscript("");
+    setPartial("");
+    setError(null);
+  }, []);
+
+  const stop = useCallback(async () => {
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    setListening(false);
+    setPartial("");
+    if (session && typeof session.stop === "function") await session.stop();
+  }, []);
+
+  const abort = useCallback(() => {
+    runRef.current += 1;
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    setListening(false);
+    setPartial("");
+    if (session && typeof session.abort === "function") session.abort();
+  }, []);
+
+  const start = useCallback(async () => {
+    const client = clientRef.current;
+    if (
+      !client ||
+      typeof client.start !== "function" ||
+      (typeof client.isSupported === "function" && !client.isSupported())
+    ) {
+      const e = new SpeechToTextError(
+        "UNSUPPORTED",
+        "This host does not provide speech recognition.",
+      );
+      setError(e);
+      setListening(false);
+      throw e;
+    }
+    // A second start() supersedes the first: drop the old session's events.
+    const myRun = ++runRef.current;
+    const previous = sessionRef.current;
+    sessionRef.current = null;
+    if (previous && typeof previous.abort === "function") previous.abort();
+
+    setError(null);
+    setPartial("");
+    setListening(true);
+    try {
+      const session = await client.start(optionsRef.current || {}, {
+        onResult: (result) => {
+          if (runRef.current !== myRun) return;
+          const text =
+            result && typeof result.transcript === "string"
+              ? result.transcript
+              : "";
+          if (result && result.isFinal) {
+            setPartial("");
+            // Append rather than replace: a continuous session emits one final
+            // result per utterance, not a growing whole.
+            setTranscript((prev) => (prev ? `${prev} ${text}`.trim() : text));
+          } else {
+            setPartial(text);
+          }
+        },
+        onError: (err) => {
+          if (runRef.current !== myRun) return;
+          sessionRef.current = null;
+          setError(toSpeechToTextError(err));
+          setPartial("");
+          setListening(false);
+        },
+        onEnd: () => {
+          if (runRef.current !== myRun) return;
+          sessionRef.current = null;
+          setPartial("");
+          setListening(false);
+        },
+      });
+      if (runRef.current !== myRun) {
+        // Superseded while the host was still opening the mic.
+        if (session && typeof session.abort === "function") session.abort();
+        return;
+      }
+      sessionRef.current = session || null;
+    } catch (err) {
+      const se = toSpeechToTextError(err);
+      if (runRef.current === myRun) {
+        sessionRef.current = null;
+        setError(se);
+        setListening(false);
+      }
+      throw se;
+    }
+  }, []);
+
+  return {
+    transcript,
+    partial,
+    listening,
+    supported,
+    error,
+    start,
+    stop,
+    abort,
+    reset,
+  };
+}
+
 /* ============================================================================
  * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
  *

package/dist/index.d.ts

@@ -590,8 +590,22 @@ export interface WidgetContext<TProps = unknown> {
   toast?: {
     showToast(args: { kind?: string; message: string }): void;
   };
-  /** Optional host-brokered device capabilities; backs useGeolocation. */
+  /**
+   * Optional host-brokered device capabilities; backs useGeolocation and
+   * useSpeechToText.
+   */
   device?: {
+    speech?: {
+      isSupported?(): boolean;
+      start(
+        options: SpeechToTextOptions,
+        handlers: {
+          onResult(result: { transcript: string; isFinal: boolean }): void;
+          onError(error: unknown): void;
+          onEnd(): void;
+        },
+      ): Promise<{ stop(): void | Promise<void>; abort(): void }>;
+    };
     geolocation?: {
       getCurrentPosition(options?: GeolocationOptions): Promise<{
         latitude: number;
@@ -1267,6 +1281,68 @@ export class GeolocationError extends Error {
   );
 }
 
+/** Pass-through options for `useSpeechToText(...)`. */
+export interface SpeechToTextOptions {
+  /** BCP-47 tag, e.g. "sv-SE". Defaults to the host's UI language. */
+  lang?: string;
+  /** Keep listening across pauses instead of stopping at the first result. */
+  continuous?: boolean;
+  /** Emit uncommitted guesses to `partial` while the user is still speaking. */
+  interimResults?: boolean;
+}
+
+export interface SpeechToTextResult {
+  /** Finalised speech, accumulated across utterances in this session. */
+  transcript: string;
+  /** The uncommitted guess; `""` unless `interimResults` was requested. */
+  partial: string;
+  listening: boolean;
+  /** False when the host brokers no recogniser (e.g. Firefox). */
+  supported: boolean;
+  error: SpeechToTextError | null;
+  /** Begin listening — call from a user gesture. Rejects with SpeechToTextError. */
+  start(): Promise<void>;
+  /** Stop listening and keep what was heard. */
+  stop(): Promise<void>;
+  /** Cancel listening and discard the current utterance. */
+  abort(): void;
+  /** Clear `transcript`, `partial`, and `error`. */
+  reset(): void;
+}
+
+/**
+ * Dictate into text with the device's ON-DEVICE speech recogniser. Capture is
+ * imperative (call `start()` from a user gesture; it never listens on mount).
+ * The same hook drives both platforms — the web Player brokers it via
+ * `window.SpeechRecognition`, the Expo export via `expo-speech-recognition`.
+ * No audio is uploaded and no AI credit is spent. Safe to call on a host that
+ * brokers no recogniser: `supported` is then false and `start()` rejects with
+ * `code: "UNSUPPORTED"`, so gate the mic button on `supported`.
+ */
+export function useSpeechToText(
+  options?: SpeechToTextOptions,
+): SpeechToTextResult;
+
+/**
+ * Error surfaced by `useSpeechToText()` — thrown by `start()` and stored in the
+ * hook's `error` slot. `code` is a stable categorisation.
+ */
+export class SpeechToTextError extends Error {
+  code:
+    | "PERMISSION_DENIED"
+    | "NO_SPEECH"
+    | "LANGUAGE_UNSUPPORTED"
+    | "NETWORK"
+    | "ABORTED"
+    | "UNSUPPORTED"
+    | "INTERNAL";
+  constructor(
+    code: SpeechToTextError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable

package/dist/index.js

@@ -56,6 +56,8 @@ export {
   useContainerWidth,
   useGeolocation,
   GeolocationError,
+  useSpeechToText,
+  SpeechToTextError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";

package/dist/index.native.js

@@ -56,6 +56,8 @@ export {
   useContainerWidth,
   useGeolocation,
   GeolocationError,
+  useSpeechToText,
+  SpeechToTextError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js"
   },
   "engines": {
     "node": ">=18"