@colixsystems/widget-sdk 0.191.0 → 0.192.0

package/README.md

@@ -77,7 +77,27 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.191.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**.
+`v0.192.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.192.0 (contract 1.153.0)
+
+**New `useAudioRecorder()` and `useAudioPlayer(uri)` hooks: record and play audio clips on both hosts.** A voice note or voice message no longer needs a `widget.web.jsx` / `widget.native.jsx` split around `expo-audio`.
+
+`useAudioRecorder()` returns `{ supported, permission, recording, durationMs, level, error, start, stop, cancel }`. Call `start()` from a tap; the microphone prompt never opens on mount. `stop()` resolves `{ file, uri, durationMs, mime }` (or `null` when nothing was recording): `file` is the upload part for the host, so pass it to `upload(file)` from `useFilestoreUpload()`, and `uri` previews the clip before you upload it. `cancel()` discards the clip. `permission` is `"granted"`, `"denied"` or `"undetermined"`, and `level` is the input level from 0 to 1 for a meter. Errors are an `AudioRecorderError` (`PERMISSION_DENIED`, `UNSUPPORTED`, `INTERNAL`).
+
+`useAudioPlayer(uri)` returns `{ supported, loading, playing, positionMs, durationMs, error, play, pause, seek }`. `durationMs` is `null` until it is known. When the clip ends, `playing` turns false and `positionMs` returns to 0, so `play()` replays it. Call `play()` from a tap: browsers refuse playback otherwise, and the hook rejects with an `AudioPlayerError` whose code is `BLOCKED` (the others are `UNSUPPORTED`, `LOAD_FAILED` and `INTERNAL`).
+
+```jsx
+const recorder = useAudioRecorder();
+const { upload } = useFilestoreUpload({ spaceType: "project" });
+// start: <Pressable onPress={() => recorder.start().catch(() => {})}>
+// stop:  try { const clip = await recorder.stop(); if (clip) await upload(clip.file); } catch { /* show it failed */ }
+
+const player = useAudioPlayer(url);
+// <Pressable onPress={() => (player.playing ? player.pause() : player.play().catch(() => {}))}>
+```
+
+The web Player records AAC (`audio/mp4`) where the browser can, and Opus in WebM or Ogg otherwise. iOS cannot play Opus, so an Opus or Vorbis clip a signed-in user uploads with compression on (the default) is converted to AAC (`.m4a`) on upload. An anonymous upload, a clip over 25 MB or 15 minutes, or one uploaded with `compress: false` is stored as recorded. The native export always records AAC. Both hooks need no scope. The host brokers them as the new optional `ctx.device.audioRecorder` and `ctx.device.audioPlayer` slices (MediaRecorder and an `<audio>` element on web, `expo-audio` on native). Additive.
 
 ### What's new in 0.191.0 (contract 1.152.0)
 

package/dist/audio.js

@@ -0,0 +1,448 @@
+// Host-brokered audio: `useAudioRecorder()` and `useAudioPlayer(uri)`.
+//
+// One source for both hosts. The web Player brokers ctx.device.audioRecorder
+// with MediaRecorder and ctx.device.audioPlayer with an <audio> element; the
+// Expo export brokers both with expo-audio. A widget never splits itself by
+// platform to record or play a clip.
+//
+// This file avoids JSX so it can ship as a plain .js without a transform.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useWidgetContextOrThrow } from "./hooks.js";
+
+// How often the recorder's duration and input level are read while recording.
+const RECORDER_POLL_MS = 100;
+
+// Input level is reported in dBFS; this floor reads as silence.
+const LEVEL_FLOOR_DB = -60;
+
+/**
+ * Error surfaced by `useAudioRecorder()` (thrown by `start()` / `stop()` and
+ * stored in the hook's `error` slot).
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED" — the user or the OS refused microphone access.
+ *   - "UNSUPPORTED"       — this host cannot record (no broker, no microphone).
+ *   - "INTERNAL"          — anything else.
+ */
+export class AudioRecorderError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "AudioRecorderError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+/**
+ * Error surfaced by `useAudioPlayer()` (thrown by `play()` / `seek()` and
+ * stored in the hook's `error` slot).
+ *
+ * `code` is one of:
+ *   - "UNSUPPORTED" — this host cannot play audio.
+ *   - "LOAD_FAILED" — the clip could not be fetched or decoded.
+ *   - "BLOCKED"     — the host refused to start playback outside a user gesture.
+ *   - "INTERNAL"    — anything else.
+ */
+export class AudioPlayerError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "AudioPlayerError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+const RECORDER_CODES = new Set(["PERMISSION_DENIED", "UNSUPPORTED"]);
+const PLAYER_CODES = new Set(["UNSUPPORTED", "LOAD_FAILED", "BLOCKED"]);
+
+function coerceError(ErrorClass, knownCodes, fallbackMessage, err) {
+  if (err instanceof ErrorClass) return err;
+  const raw = err && err.code;
+  const code = knownCodes.has(raw) ? raw : "INTERNAL";
+  const message =
+    (err && typeof err.message === "string" && err.message) || fallbackMessage;
+  return new ErrorClass(code, message, { cause: err });
+}
+
+const toRecorderError = (err) =>
+  coerceError(AudioRecorderError, RECORDER_CODES, "Recording failed", err);
+
+const toPlayerError = (err) =>
+  coerceError(AudioPlayerError, PLAYER_CODES, "Playback failed", err);
+
+/** dBFS → 0..1, so a level meter needs no knowledge of either host's scale. */
+function normaliseInputLevel(levelDb) {
+  if (typeof levelDb !== "number" || !Number.isFinite(levelDb)) return 0;
+  const ratio = (levelDb - LEVEL_FLOOR_DB) / -LEVEL_FLOOR_DB;
+  return Math.min(1, Math.max(0, ratio));
+}
+
+const PERMISSION_STATES = new Set(["granted", "denied", "undetermined"]);
+
+function isUsable(client, method) {
+  return Boolean(
+    client &&
+      typeof client[method] === "function" &&
+      (typeof client.isSupported !== "function" || client.isSupported()),
+  );
+}
+
+function releaseQuietly(release) {
+  if (typeof release !== "function") return;
+  try {
+    release();
+  } catch {
+    /* the host already released it */
+  }
+}
+
+/**
+ * Record a clip from the microphone. Returns `{ supported, permission,
+ * recording, durationMs, level, error, start, stop, cancel }`.
+ *
+ * Capture is IMPERATIVE — call `start()` from a user gesture. Both the
+ * browser and the mobile OS gate the microphone prompt on one, so the hook
+ * never records on mount.
+ *
+ * `stop()` resolves `{ file, uri, durationMs, mime }`, or `null` when nothing
+ * was recording. `file` is already the upload part for the host (a `File` on
+ * web, expo-file-system's `File` on native) — pass it to `upload(file)` from
+ * `useFilestoreUpload()`. `uri` plays the clip locally through
+ * `useAudioPlayer(uri)` before it is uploaded; the hook releases it on the
+ * next `start()`, on `cancel()` and on unmount. `cancel()` discards the clip.
+ *
+ * `permission` is "granted" | "denied" | "undetermined"; `level` is the input
+ * level from 0 (silence) to 1, for a live meter.
+ *
+ * Safe-by-default: on a host that brokers no recorder `supported` is false
+ * and `start()` rejects with `code: "UNSUPPORTED"`, so a widget can call the
+ * hook unconditionally and disable its record control.
+ */
+export function useAudioRecorder() {
+  const ctx = useWidgetContextOrThrow("useAudioRecorder");
+  const [permission, setPermission] = useState("undetermined");
+  const [recording, setRecording] = useState(false);
+  const [durationMs, setDurationMs] = useState(0);
+  const [level, setLevel] = useState(0);
+  const [error, setError] = useState(null);
+
+  // `ctx` is a fresh identity every host render — hold the live client in a
+  // ref so the returned callbacks stay stable.
+  const clientRef = useRef(ctx.device && ctx.device.audioRecorder);
+  clientRef.current = ctx.device && ctx.device.audioRecorder;
+  const sessionRef = useRef(null);
+  const startingRef = useRef(null);
+  const pollRef = useRef(null);
+  const clipReleaseRef = useRef(null);
+  const runRef = useRef(0);
+
+  const supported = isUsable(clientRef.current, "start");
+
+  const stopPolling = useCallback(() => {
+    if (pollRef.current !== null) clearInterval(pollRef.current);
+    pollRef.current = null;
+  }, []);
+
+  const releaseClip = useCallback(() => {
+    const release = clipReleaseRef.current;
+    clipReleaseRef.current = null;
+    releaseQuietly(release);
+  }, []);
+
+  const discardSession = useCallback(() => {
+    runRef.current += 1;
+    startingRef.current = null;
+    stopPolling();
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    if (session && typeof session.cancel === "function") {
+      try {
+        session.cancel();
+      } catch {
+        /* the host is already tearing the session down */
+      }
+    }
+  }, [stopPolling]);
+
+  useEffect(() => {
+    const client = clientRef.current;
+    if (!client || typeof client.getPermission !== "function") return undefined;
+    let live = true;
+    Promise.resolve()
+      .then(() => client.getPermission())
+      .then((state) => {
+        // A start() that already answered the prompt outranks this read.
+        if (live && PERMISSION_STATES.has(state)) {
+          setPermission((current) =>
+            current === "undetermined" ? state : current,
+          );
+        }
+      })
+      .catch(() => {
+        /* unknown stays "undetermined" */
+      });
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  // An abandoned recorder leaves the microphone hot on both hosts.
+  useEffect(
+    () => () => {
+      discardSession();
+      releaseClip();
+    },
+    [discardSession, releaseClip],
+  );
+
+  const start = useCallback(() => {
+    if (sessionRef.current) return Promise.resolve();
+    // A double tap while the permission prompt is open joins the first start.
+    if (startingRef.current) return startingRef.current;
+    const client = clientRef.current;
+    if (!isUsable(client, "start")) {
+      const e = new AudioRecorderError(
+        "UNSUPPORTED",
+        "This host does not provide audio recording.",
+      );
+      setError(e);
+      return Promise.reject(e);
+    }
+    const run = (runRef.current += 1);
+    setError(null);
+    releaseClip();
+    // A broker that throws synchronously settles the IIFE before it returns.
+    let settled = false;
+    const opening = (async () => {
+      try {
+        const session = await client.start();
+        if (run !== runRef.current) {
+          if (session && typeof session.cancel === "function") session.cancel();
+          return;
+        }
+        sessionRef.current = session;
+        setPermission("granted");
+        setDurationMs(0);
+        setLevel(0);
+        setRecording(true);
+        pollRef.current = setInterval(() => {
+          const live = sessionRef.current;
+          if (!live || typeof live.getStatus !== "function") return;
+          const status = live.getStatus() || {};
+          if (typeof status.durationMs === "number") {
+            setDurationMs(status.durationMs);
+          }
+          // The host ended it (a lost headset, a phone call); stop() keeps it.
+          if (status.ended) {
+            stopPolling();
+            setRecording(false);
+            setLevel(0);
+            return;
+          }
+          setLevel(normaliseInputLevel(status.levelDb));
+        }, RECORDER_POLL_MS);
+      } catch (err) {
+        const re = toRecorderError(err);
+        if (run === runRef.current) {
+          if (re.code === "PERMISSION_DENIED") setPermission("denied");
+          setError(re);
+        }
+        throw re;
+      } finally {
+        settled = true;
+        if (run === runRef.current) startingRef.current = null;
+      }
+    })();
+    if (!settled) startingRef.current = opening;
+    return opening;
+  }, [releaseClip, stopPolling]);
+
+  const stop = useCallback(async () => {
+    // A stop pressed while the permission prompt is open ends that recording.
+    if (!sessionRef.current && startingRef.current) {
+      await startingRef.current.catch(() => {});
+    }
+    const session = sessionRef.current;
+    if (!session) return null;
+    const run = (runRef.current += 1);
+    sessionRef.current = null;
+    stopPolling();
+    setRecording(false);
+    setLevel(0);
+    let clip;
+    try {
+      clip = await session.stop();
+    } catch (err) {
+      const re = toRecorderError(err);
+      if (run === runRef.current) setError(re);
+      throw re;
+    }
+    if (!clip) return null;
+    // A cancel(), a new start() or an unmount meanwhile discards this clip.
+    if (run !== runRef.current) {
+      releaseQuietly(clip.release);
+      return null;
+    }
+    releaseClip();
+    clipReleaseRef.current =
+      typeof clip.release === "function" ? clip.release : null;
+    setDurationMs(clip.durationMs);
+    return {
+      file: clip.file,
+      uri: clip.uri,
+      durationMs: clip.durationMs,
+      mime: clip.mime,
+    };
+  }, [releaseClip, stopPolling]);
+
+  const cancel = useCallback(() => {
+    discardSession();
+    releaseClip();
+    setRecording(false);
+    setDurationMs(0);
+    setLevel(0);
+  }, [discardSession, releaseClip]);
+
+  return {
+    supported,
+    permission,
+    recording,
+    durationMs,
+    level,
+    error,
+    start,
+    stop,
+    cancel,
+  };
+}
+
+const IDLE_PLAYBACK = {
+  loaded: false,
+  playing: false,
+  positionMs: 0,
+  durationMs: null,
+};
+
+/**
+ * Play one audio clip. Returns `{ supported, loading, playing, positionMs,
+ * durationMs, error, play, pause, seek }`.
+ *
+ * `uri` is any playable URL — a stored file's URL, or the `uri` a
+ * `useAudioRecorder()` clip resolves for local preview. Changing it loads the
+ * new clip; a falsy `uri` loads nothing. `durationMs` is `null` until the
+ * host knows the length. When the clip ends, `playing` turns false and
+ * `positionMs` returns to 0, so `play()` replays it. `seek(ms)` moves the
+ * playhead. Call `play()` from a user gesture — browsers refuse to start
+ * audio otherwise and the hook rejects with `code: "BLOCKED"`.
+ *
+ * Safe-by-default: on a host that brokers no player `supported` is false and
+ * `play()` rejects with `code: "UNSUPPORTED"`.
+ */
+export function useAudioPlayer(uri) {
+  const ctx = useWidgetContextOrThrow("useAudioPlayer");
+  const [playback, setPlayback] = useState(IDLE_PLAYBACK);
+  const [error, setError] = useState(null);
+
+  const clientRef = useRef(ctx.device && ctx.device.audioPlayer);
+  clientRef.current = ctx.device && ctx.device.audioPlayer;
+  const handleRef = useRef(null);
+
+  const supported = isUsable(clientRef.current, "load");
+  const source = typeof uri === "string" && uri ? uri : null;
+
+  useEffect(() => {
+    setPlayback(IDLE_PLAYBACK);
+    setError(null);
+    const client = clientRef.current;
+    if (!source || !isUsable(client, "load")) return undefined;
+    let live = true;
+    let handle = null;
+    try {
+      handle = client.load(source, (status) => {
+        if (!live || !status) return;
+        if (status.error) {
+          setError(toPlayerError(status.error));
+          return;
+        }
+        setPlayback({
+          loaded: Boolean(status.loaded),
+          playing: Boolean(status.playing),
+          positionMs:
+            typeof status.positionMs === "number" ? status.positionMs : 0,
+          durationMs:
+            typeof status.durationMs === "number" &&
+            Number.isFinite(status.durationMs)
+              ? status.durationMs
+              : null,
+        });
+      });
+    } catch (err) {
+      setError(toPlayerError(err));
+    }
+    handleRef.current = handle;
+    return () => {
+      live = false;
+      if (handleRef.current === handle) handleRef.current = null;
+      releaseQuietly(handle && handle.release);
+    };
+  }, [source]);
+
+  const requireHandle = useCallback(() => {
+    const handle = handleRef.current;
+    if (handle) return handle;
+    const unsupported = !isUsable(clientRef.current, "load");
+    const e = new AudioPlayerError(
+      unsupported ? "UNSUPPORTED" : "LOAD_FAILED",
+      unsupported
+        ? "This host does not provide audio playback."
+        : "There is no clip to play.",
+    );
+    setError(e);
+    throw e;
+  }, []);
+
+  const play = useCallback(async () => {
+    const handle = requireHandle();
+    setError(null);
+    try {
+      await handle.play();
+    } catch (err) {
+      const pe = toPlayerError(err);
+      setError(pe);
+      throw pe;
+    }
+  }, [requireHandle]);
+
+  const pause = useCallback(() => {
+    const handle = handleRef.current;
+    if (handle) handle.pause();
+  }, []);
+
+  const seek = useCallback(
+    async (ms) => {
+      const handle = requireHandle();
+      const target = Math.max(0, Number(ms) || 0);
+      try {
+        await handle.seek(target);
+      } catch (err) {
+        const pe = toPlayerError(err);
+        setError(pe);
+        throw pe;
+      }
+    },
+    [requireHandle],
+  );
+
+  return {
+    supported,
+    loading: Boolean(source) && supported && !playback.loaded && !error,
+    playing: playback.playing,
+    positionMs: playback.positionMs,
+    durationMs: playback.durationMs,
+    error,
+    play,
+    pause,
+    seek,
+  };
+}

package/dist/contract.cjs

@@ -2212,6 +2212,64 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-10590 — host-brokered audio recording + playback. Optional slices; the
+  // hooks report supported:false rather than throwing at render.
+  {
+    name: "useAudioRecorder",
+    signature: "useAudioRecorder()",
+    description:
+      "Record a clip from the microphone. Returns { supported, permission, recording, durationMs, level, error, start, stop, " +
+      "cancel }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a record button); the browser and the " +
+      "mobile OS gate the microphone prompt on a gesture, so it NEVER records on mount. stop() resolves { file, uri, " +
+      "durationMs, mime }, or NULL when nothing was recording; cancel() discards the clip. `file` is already the upload part " +
+      "for the host (a File on web, expo-file-system's File on native) — pass it straight to upload(file) from " +
+      "useFilestoreUpload(). `uri` plays the clip locally through useAudioPlayer(uri) before it is uploaded; the hook " +
+      "releases it on the next start(), on cancel() and on unmount. `permission` is granted | denied | undetermined; " +
+      "`level` is the input level from 0 (silence) to 1, for a live meter. start() and stop() reject with an " +
+      "AudioRecorderError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. The web records AAC (audio/mp4) " +
+      "where the browser can, otherwise Opus in WebM/Ogg — an Opus or Vorbis clip uploaded to the File library or the asset " +
+      "library by a signed-in user is converted to AAC (audio/mp4, .m4a) on upload so it plays on every host, unless the " +
+      "upload opts out of compression (compress: false) or the clip is over 25 MB or 15 minutes. The Expo export always records AAC. Check " +
+      "`supported` before enabling the record control. Identical on web (MediaRecorder) and the Expo export (expo-audio).",
+    returnShape: {
+      supported: "boolean  // false when the host brokers no recorder",
+      permission: "'granted' | 'denied' | 'undetermined'",
+      recording: "boolean",
+      durationMs: "number  // length of the current (or last) recording",
+      level: "number  // input level 0..1 while recording",
+      error: "AudioRecorderError | null",
+      start: "() => Promise<void>  // rejects with AudioRecorderError",
+      stop: "() => Promise<{ file, uri, durationMs, mime } | null>  // null if not recording",
+      cancel: "() => void  // stop and discard the clip",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useAudioPlayer",
+    signature: "useAudioPlayer(uri)",
+    description:
+      "Play one audio clip. Returns { supported, loading, playing, positionMs, durationMs, error, play, pause, seek }. `uri` " +
+      "is any playable URL — a stored file's URL (useFilestoreFile(id).url) or the local `uri` a useAudioRecorder() clip " +
+      "resolves; changing it loads the new clip and a falsy uri loads nothing. `durationMs` is null until the host knows the " +
+      "length. When the clip ends, `playing` turns false and `positionMs` returns to 0, so play() replays it. seek(ms) moves " +
+      "the playhead. Call play() from a user gesture — browsers refuse to start audio otherwise. play() and seek() reject " +
+      "with an AudioPlayerError whose .code is one of UNSUPPORTED | LOAD_FAILED | BLOCKED | INTERNAL. Plays MP3, AAC/M4A and " +
+      "WAV on both hosts; WebM/Ogg do not play on iOS. Identical on web (<audio>) and the Expo export (expo-audio).",
+    returnShape: {
+      supported: "boolean  // false when the host brokers no player",
+      loading: "boolean  // true until the host has loaded the clip",
+      playing: "boolean",
+      positionMs: "number",
+      durationMs: "number | null  // null until known",
+      error: "AudioPlayerError | null",
+      play: "() => Promise<void>  // rejects with AudioPlayerError",
+      pause: "() => void",
+      seek: "(positionMs) => Promise<void>",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   // sc-6448 — host-brokered camera capture / photo picking. Optional slice;
   // the hook reports supported:false rather than throwing at render.
   {
@@ -3154,10 +3212,17 @@ const WIDGET_CONTEXT_SHAPE = {
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
       "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
-      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> }, " +
+      "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
+      "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
+      "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
+      "audioRecorder.start rejects with .code PERMISSION_DENIED | UNSUPPORTED | INTERNAL; getStatus().levelDb is the input level in dBFS " +
+      "(null when unknown); `ended` is true once the host stopped the recording itself (a lost headset, a call), and stop() then " +
+      "still resolves that clip. audioPlayer reports the end of a clip as playing:false at positionMs 0. " +
       "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
       "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
       "cache and hands them to the OS print sheet. " +
@@ -3189,6 +3254,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3380,7 +3447,8 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "media",
     description:
-      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx.",
+      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx. " +
+      "To record or play a clip on BOTH hosts, prefer the SDK's useAudioRecorder() / useAudioPlayer(uri) — no platform split needed.",
   },
   {
     specifier: "expo-video",
@@ -4998,7 +5066,11 @@ const CONTRACT = deepFreeze({
   // 1.152.0: additive (sc-10580) — new `useLinkPreview(url)` returns
   //    `{ preview, loading, error, available }` from the new optional
   //    `linkPreviews` slice (@colixsystems/link-preview-client).
-  version: "1.152.0",
+  // 1.153.0: additive (sc-10590) — new `useAudioRecorder()` and
+  //    `useAudioPlayer(uri)`, backed by the optional `device.audioRecorder` /
+  //    `device.audioPlayer` slices (MediaRecorder + <audio> on web, expo-audio
+  //    on native), with `AudioRecorderError` / `AudioPlayerError`.
+  version: "1.153.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2212,6 +2212,64 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-10590 — host-brokered audio recording + playback. Optional slices; the
+  // hooks report supported:false rather than throwing at render.
+  {
+    name: "useAudioRecorder",
+    signature: "useAudioRecorder()",
+    description:
+      "Record a clip from the microphone. Returns { supported, permission, recording, durationMs, level, error, start, stop, " +
+      "cancel }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a record button); the browser and the " +
+      "mobile OS gate the microphone prompt on a gesture, so it NEVER records on mount. stop() resolves { file, uri, " +
+      "durationMs, mime }, or NULL when nothing was recording; cancel() discards the clip. `file` is already the upload part " +
+      "for the host (a File on web, expo-file-system's File on native) — pass it straight to upload(file) from " +
+      "useFilestoreUpload(). `uri` plays the clip locally through useAudioPlayer(uri) before it is uploaded; the hook " +
+      "releases it on the next start(), on cancel() and on unmount. `permission` is granted | denied | undetermined; " +
+      "`level` is the input level from 0 (silence) to 1, for a live meter. start() and stop() reject with an " +
+      "AudioRecorderError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. The web records AAC (audio/mp4) " +
+      "where the browser can, otherwise Opus in WebM/Ogg — an Opus or Vorbis clip uploaded to the File library or the asset " +
+      "library by a signed-in user is converted to AAC (audio/mp4, .m4a) on upload so it plays on every host, unless the " +
+      "upload opts out of compression (compress: false) or the clip is over 25 MB or 15 minutes. The Expo export always records AAC. Check " +
+      "`supported` before enabling the record control. Identical on web (MediaRecorder) and the Expo export (expo-audio).",
+    returnShape: {
+      supported: "boolean  // false when the host brokers no recorder",
+      permission: "'granted' | 'denied' | 'undetermined'",
+      recording: "boolean",
+      durationMs: "number  // length of the current (or last) recording",
+      level: "number  // input level 0..1 while recording",
+      error: "AudioRecorderError | null",
+      start: "() => Promise<void>  // rejects with AudioRecorderError",
+      stop: "() => Promise<{ file, uri, durationMs, mime } | null>  // null if not recording",
+      cancel: "() => void  // stop and discard the clip",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useAudioPlayer",
+    signature: "useAudioPlayer(uri)",
+    description:
+      "Play one audio clip. Returns { supported, loading, playing, positionMs, durationMs, error, play, pause, seek }. `uri` " +
+      "is any playable URL — a stored file's URL (useFilestoreFile(id).url) or the local `uri` a useAudioRecorder() clip " +
+      "resolves; changing it loads the new clip and a falsy uri loads nothing. `durationMs` is null until the host knows the " +
+      "length. When the clip ends, `playing` turns false and `positionMs` returns to 0, so play() replays it. seek(ms) moves " +
+      "the playhead. Call play() from a user gesture — browsers refuse to start audio otherwise. play() and seek() reject " +
+      "with an AudioPlayerError whose .code is one of UNSUPPORTED | LOAD_FAILED | BLOCKED | INTERNAL. Plays MP3, AAC/M4A and " +
+      "WAV on both hosts; WebM/Ogg do not play on iOS. Identical on web (<audio>) and the Expo export (expo-audio).",
+    returnShape: {
+      supported: "boolean  // false when the host brokers no player",
+      loading: "boolean  // true until the host has loaded the clip",
+      playing: "boolean",
+      positionMs: "number",
+      durationMs: "number | null  // null until known",
+      error: "AudioPlayerError | null",
+      play: "() => Promise<void>  // rejects with AudioPlayerError",
+      pause: "() => void",
+      seek: "(positionMs) => Promise<void>",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   // sc-6448 — host-brokered camera capture / photo picking. Optional slice;
   // the hook reports supported:false rather than throwing at render.
   {
@@ -3150,10 +3208,17 @@ const WIDGET_CONTEXT_SHAPE = {
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
       "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
-      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> }, " +
+      "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
+      "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
+      "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
+      "audioRecorder.start rejects with .code PERMISSION_DENIED | UNSUPPORTED | INTERNAL; getStatus().levelDb is the input level in dBFS " +
+      "(null when unknown); `ended` is true once the host stopped the recording itself (a lost headset, a call), and stop() then " +
+      "still resolves that clip. audioPlayer reports the end of a clip as playing:false at positionMs 0. " +
       "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
       "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
       "cache and hands them to the OS print sheet. " +
@@ -3185,6 +3250,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3376,7 +3443,8 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "media",
     description:
-      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx.",
+      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx. " +
+      "To record or play a clip on BOTH hosts, prefer the SDK's useAudioRecorder() / useAudioPlayer(uri) — no platform split needed.",
   },
   {
     specifier: "expo-video",
@@ -4994,7 +5062,11 @@ const CONTRACT = deepFreeze({
   // 1.152.0: additive (sc-10580) — new `useLinkPreview(url)` returns
   //    `{ preview, loading, error, available }` from the new optional
   //    `linkPreviews` slice (@colixsystems/link-preview-client).
-  version: "1.152.0",
+  // 1.153.0: additive (sc-10590) — new `useAudioRecorder()` and
+  //    `useAudioPlayer(uri)`, backed by the optional `device.audioRecorder` /
+  //    `device.audioPlayer` slices (MediaRecorder + <audio> on web, expo-audio
+  //    on native), with `AudioRecorderError` / `AudioPlayerError`.
+  version: "1.153.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -717,10 +717,40 @@ export interface WidgetContext<TProps = unknown> {
     showToast(args: { kind?: string; message: string }): void;
   };
   /**
-   * Optional host-brokered device capabilities; backs useGeolocation and
-   * useSpeechToText.
+   * Optional host-brokered device capabilities; backs useGeolocation,
+   * useSpeechToText, useAudioRecorder and useAudioPlayer.
    */
   device?: {
+    /** sc-10590 — backs useAudioRecorder. */
+    audioRecorder?: {
+      isSupported?(): boolean;
+      getPermission?(): Promise<AudioPermissionState>;
+      start(): Promise<{
+        /** `ended`: the host stopped it itself; stop() still resolves the clip. */
+        getStatus(): { durationMs: number; levelDb: number | null; ended?: boolean };
+        stop(): Promise<AudioClip & { release?(): void }>;
+        cancel(): void;
+      }>;
+    };
+    /** sc-10590 — backs useAudioPlayer. */
+    audioPlayer?: {
+      isSupported?(): boolean;
+      load(
+        uri: string,
+        onStatus: (status: {
+          loaded: boolean;
+          playing: boolean;
+          positionMs: number;
+          durationMs: number | null;
+          error?: { code?: string; message?: string };
+        }) => void,
+      ): {
+        play(): Promise<void>;
+        pause(): void;
+        seek(positionMs: number): Promise<void>;
+        release(): void;
+      };
+    };
     speech?: {
       isSupported?(): boolean;
       start(
@@ -1930,6 +1960,94 @@ export class SpeechToTextError extends Error {
   );
 }
 
+/** Microphone permission as `useAudioRecorder()` reports it. */
+export type AudioPermissionState = "granted" | "denied" | "undetermined";
+
+/** A finished recording, as `useAudioRecorder().stop()` resolves it. */
+export interface AudioClip {
+  /**
+   * The upload part for this host: a `File` on web, expo-file-system's `File`
+   * on native (not `instanceof Blob` at runtime) — append it, don't branch on it.
+   */
+  file: unknown;
+  /** Plays the clip locally via `useAudioPlayer(uri)` until the hook releases it. */
+  uri: string;
+  durationMs: number;
+  /** e.g. "audio/mp4" or "audio/webm". */
+  mime: string;
+}
+
+export interface AudioRecorderResult {
+  /** False when the host brokers no recorder; disable the record control. */
+  supported: boolean;
+  permission: AudioPermissionState;
+  recording: boolean;
+  /** Length of the current (or last) recording. */
+  durationMs: number;
+  /** Input level from 0 (silence) to 1, for a live meter. */
+  level: number;
+  error: AudioRecorderError | null;
+  /** Start recording — call from a user gesture. Rejects with AudioRecorderError. */
+  start(): Promise<void>;
+  /** Finish and keep the clip; `null` when nothing was recording. */
+  stop(): Promise<AudioClip | null>;
+  /** Stop and discard the clip. */
+  cancel(): void;
+}
+
+/**
+ * Record a clip from the microphone. The web Player brokers it via
+ * MediaRecorder, the Expo export via `expo-audio`. Capture is imperative (call
+ * `start()` from a user gesture). Safe to call on a host that brokers no
+ * recorder: `supported` is then false and `start()` rejects with
+ * `code: "UNSUPPORTED"`.
+ */
+export function useAudioRecorder(): AudioRecorderResult;
+
+/** Error surfaced by `useAudioRecorder()`. */
+export class AudioRecorderError extends Error {
+  code: "PERMISSION_DENIED" | "UNSUPPORTED" | "INTERNAL";
+  constructor(
+    code: AudioRecorderError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
+export interface AudioPlayerResult {
+  /** False when the host brokers no player. */
+  supported: boolean;
+  /** True from a new `uri` until the host has loaded it. */
+  loading: boolean;
+  playing: boolean;
+  positionMs: number;
+  /** `null` until the host knows the clip's length. */
+  durationMs: number | null;
+  error: AudioPlayerError | null;
+  /** Start or resume — call from a user gesture. Rejects with AudioPlayerError. */
+  play(): Promise<void>;
+  pause(): void;
+  seek(positionMs: number): Promise<void>;
+}
+
+/**
+ * Play one clip from `uri` (a stored file's URL, or a recording's local
+ * `uri`). The web Player brokers it via an `<audio>` element, the Expo export
+ * via `expo-audio`. When the clip ends, `playing` turns false and
+ * `positionMs` returns to 0.
+ */
+export function useAudioPlayer(uri: string | null | undefined): AudioPlayerResult;
+
+/** Error surfaced by `useAudioPlayer()`. */
+export class AudioPlayerError extends Error {
+  code: "UNSUPPORTED" | "LOAD_FAILED" | "BLOCKED" | "INTERNAL";
+  constructor(
+    code: AudioPlayerError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Options for `useCamera(...)`. Both are HINTS the host honours where it can:
  * the Expo export applies them, the web file input applies neither — so never

package/dist/index.js

@@ -108,6 +108,14 @@ export {
 // the web variant and index.native.js picks the native variant.
 export { useClipboard, ClipboardError } from "./clipboard.js";
 export { useToast } from "./toast.js";
+// sc-10590 — one host-brokered source for both entries: each host injects
+// ctx.device.audioRecorder / audioPlayer, so neither file splits by platform.
+export {
+  useAudioRecorder,
+  AudioRecorderError,
+  useAudioPlayer,
+  AudioPlayerError,
+} from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box

package/dist/index.native.js

@@ -106,6 +106,14 @@ export {
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";
+// sc-10590 — one host-brokered source for both entries: each host injects
+// ctx.device.audioRecorder / audioPlayer, so neither file splits by platform.
+export {
+  useAudioRecorder,
+  AudioRecorderError,
+  useAudioPlayer,
+  AudioPlayerError,
+} from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.191.0",
+  "version": "0.192.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -2212,6 +2212,64 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-10590 — host-brokered audio recording + playback. Optional slices; the
+  // hooks report supported:false rather than throwing at render.
+  {
+    name: "useAudioRecorder",
+    signature: "useAudioRecorder()",
+    description:
+      "Record a clip from the microphone. Returns { supported, permission, recording, durationMs, level, error, start, stop, " +
+      "cancel }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a record button); the browser and the " +
+      "mobile OS gate the microphone prompt on a gesture, so it NEVER records on mount. stop() resolves { file, uri, " +
+      "durationMs, mime }, or NULL when nothing was recording; cancel() discards the clip. `file` is already the upload part " +
+      "for the host (a File on web, expo-file-system's File on native) — pass it straight to upload(file) from " +
+      "useFilestoreUpload(). `uri` plays the clip locally through useAudioPlayer(uri) before it is uploaded; the hook " +
+      "releases it on the next start(), on cancel() and on unmount. `permission` is granted | denied | undetermined; " +
+      "`level` is the input level from 0 (silence) to 1, for a live meter. start() and stop() reject with an " +
+      "AudioRecorderError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. The web records AAC (audio/mp4) " +
+      "where the browser can, otherwise Opus in WebM/Ogg — an Opus or Vorbis clip uploaded to the File library or the asset " +
+      "library by a signed-in user is converted to AAC (audio/mp4, .m4a) on upload so it plays on every host, unless the " +
+      "upload opts out of compression (compress: false) or the clip is over 25 MB or 15 minutes. The Expo export always records AAC. Check " +
+      "`supported` before enabling the record control. Identical on web (MediaRecorder) and the Expo export (expo-audio).",
+    returnShape: {
+      supported: "boolean  // false when the host brokers no recorder",
+      permission: "'granted' | 'denied' | 'undetermined'",
+      recording: "boolean",
+      durationMs: "number  // length of the current (or last) recording",
+      level: "number  // input level 0..1 while recording",
+      error: "AudioRecorderError | null",
+      start: "() => Promise<void>  // rejects with AudioRecorderError",
+      stop: "() => Promise<{ file, uri, durationMs, mime } | null>  // null if not recording",
+      cancel: "() => void  // stop and discard the clip",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useAudioPlayer",
+    signature: "useAudioPlayer(uri)",
+    description:
+      "Play one audio clip. Returns { supported, loading, playing, positionMs, durationMs, error, play, pause, seek }. `uri` " +
+      "is any playable URL — a stored file's URL (useFilestoreFile(id).url) or the local `uri` a useAudioRecorder() clip " +
+      "resolves; changing it loads the new clip and a falsy uri loads nothing. `durationMs` is null until the host knows the " +
+      "length. When the clip ends, `playing` turns false and `positionMs` returns to 0, so play() replays it. seek(ms) moves " +
+      "the playhead. Call play() from a user gesture — browsers refuse to start audio otherwise. play() and seek() reject " +
+      "with an AudioPlayerError whose .code is one of UNSUPPORTED | LOAD_FAILED | BLOCKED | INTERNAL. Plays MP3, AAC/M4A and " +
+      "WAV on both hosts; WebM/Ogg do not play on iOS. Identical on web (<audio>) and the Expo export (expo-audio).",
+    returnShape: {
+      supported: "boolean  // false when the host brokers no player",
+      loading: "boolean  // true until the host has loaded the clip",
+      playing: "boolean",
+      positionMs: "number",
+      durationMs: "number | null  // null until known",
+      error: "AudioPlayerError | null",
+      play: "() => Promise<void>  // rejects with AudioPlayerError",
+      pause: "() => void",
+      seek: "(positionMs) => Promise<void>",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   // sc-6448 — host-brokered camera capture / photo picking. Optional slice;
   // the hook reports supported:false rather than throwing at render.
   {
@@ -3150,10 +3208,17 @@ const WIDGET_CONTEXT_SHAPE = {
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
       "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
-      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> }, " +
+      "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
+      "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
+      "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
+      "audioRecorder.start rejects with .code PERMISSION_DENIED | UNSUPPORTED | INTERNAL; getStatus().levelDb is the input level in dBFS " +
+      "(null when unknown); `ended` is true once the host stopped the recording itself (a lost headset, a call), and stop() then " +
+      "still resolves that clip. audioPlayer reports the end of a clip as playing:false at positionMs 0. " +
       "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
       "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
       "cache and hands them to the OS print sheet. " +
@@ -3185,6 +3250,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3376,7 +3443,8 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "media",
     description:
-      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx.",
+      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx. " +
+      "To record or play a clip on BOTH hosts, prefer the SDK's useAudioRecorder() / useAudioPlayer(uri) — no platform split needed.",
   },
   {
     specifier: "expo-video",
@@ -4994,7 +5062,11 @@ const CONTRACT = deepFreeze({
   // 1.152.0: additive (sc-10580) — new `useLinkPreview(url)` returns
   //    `{ preview, loading, error, available }` from the new optional
   //    `linkPreviews` slice (@colixsystems/link-preview-client).
-  version: "1.152.0",
+  // 1.153.0: additive (sc-10590) — new `useAudioRecorder()` and
+  //    `useAudioPlayer(uri)`, backed by the optional `device.audioRecorder` /
+  //    `device.audioPlayer` slices (MediaRecorder + <audio> on web, expo-audio
+  //    on native), with `AudioRecorderError` / `AudioPlayerError`.
+  version: "1.153.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,