@colixsystems/widget-sdk 0.191.0 → 0.193.0

package/README.md

@@ -53,7 +53,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **AGENTS** | `useAgent(agentRef)` | `{ send, cancel, reset, messages, sending, resuming, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). Sending is IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. On mount the hook DOES reopen the caller's most recent thread with this agent, so a refresh or a navigation keeps the conversation instead of starting a blank one; that resume only READS and spends no credit. `resuming` is true while it runs — render a loading state, not an empty thread. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance), and the new thread is the one a later mount resumes. **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
-| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). For a live list of the signed-in user's own rows pass `{ kind: "granted" }`: every row they read through a grant to them or one of their groups, plus `onAccessGained(record)` / `onAccessLost({ id })` as rows enter and leave that set. Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
@@ -77,7 +77,49 @@ 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.193.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.193.0 (contract 1.154.0)
+
+**`useDatastoreSubscription` can keep a list of the user's own rows live.** Pass `{ scope: { kind: "granted" } }` and the hook streams every row of the table the signed-in user can read through a grant to them or to one of their groups — their conversations, their cases. Without it such a list had to poll: a whole-table subscribe needs read on every row, and one record scope per row runs out of subscriptions.
+
+Two new handlers report changes to the set itself. `onAccessGained(record)` fires with the full row when a grant starts letting the user read it, for example when they are added to a conversation. `onAccessLost({ id })` fires when they can no longer read it, and no further event for that row arrives. Merge `onCreated` / `onUpdated` / `onAccessGained` into your list by `id`, and remove the row on `onDeleted` or `onAccessLost`:
+
+```jsx
+const { data, refetch } = useDatastoreQuery(conversationsTableId);
+const [live, setLive] = useState([]);
+useEffect(() => setLive(data), [data]);
+const upsert = (row) => setLive((list) => [row, ...list.filter((r) => r.id !== row.id)]);
+const drop = ({ id }) => setLive((list) => list.filter((r) => r.id !== id));
+const { status } = useDatastoreSubscription(
+  conversationsTableId,
+  { onCreated: upsert, onUpdated: upsert, onAccessGained: upsert, onDeleted: drop, onAccessLost: drop },
+  { scope: { kind: "granted" } },
+);
+// Poll with refetch() only while status === "fallback".
+```
+
+A logged-out visitor's granted subscribe resolves to `{ status: "fallback" }`. Backed by datastore-client 0.21.0. Additive; works identically in the web Player and the native export.
+
+### 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

@@ -2060,6 +2060,13 @@ const HOOKS = [
       "table governed by per-record grants, since a scope-less subscribe must " +
       "prove read-every-row. A `parent` scope requires the column be an " +
       "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }. { kind: 'granted' } streams every row the " +
+      "signed-in user can read through a grant to them or to one of their " +
+      "groups — the way to keep a list of 'my conversations' or 'my cases' " +
+      "live — and adds two handlers: onAccessGained(record) when a row " +
+      "becomes readable (the full row) and onAccessLost({ id }) when it stops " +
+      "being readable, after which no further event for it arrives. A " +
+      "logged-out visitor's granted subscribe resolves to " +
       "{ status: 'fallback' }.",
     returnShape: {
       status:
@@ -2212,6 +2219,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 +3219,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 +3261,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3380,7 +3454,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 +5073,15 @@ 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`.
+  // 1.154.0: additive (sc-10589) — `useDatastoreSubscription` accepts
+  //    `scope: { kind: "granted" }` (the rows the signed-in user reads through
+  //    a user or group grant) and the `onAccessGained` / `onAccessLost`
+  //    handlers that report rows entering and leaving that set.
+  version: "1.154.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2060,6 +2060,13 @@ const HOOKS = [
       "table governed by per-record grants, since a scope-less subscribe must " +
       "prove read-every-row. A `parent` scope requires the column be an " +
       "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }. { kind: 'granted' } streams every row the " +
+      "signed-in user can read through a grant to them or to one of their " +
+      "groups — the way to keep a list of 'my conversations' or 'my cases' " +
+      "live — and adds two handlers: onAccessGained(record) when a row " +
+      "becomes readable (the full row) and onAccessLost({ id }) when it stops " +
+      "being readable, after which no further event for it arrives. A " +
+      "logged-out visitor's granted subscribe resolves to " +
       "{ status: 'fallback' }.",
     returnShape: {
       status:
@@ -2212,6 +2219,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 +3215,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 +3257,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3376,7 +3450,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 +5069,15 @@ 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`.
+  // 1.154.0: additive (sc-10589) — `useDatastoreSubscription` accepts
+  //    `scope: { kind: "granted" }` (the rows the signed-in user reads through
+  //    a user or group grant) and the `onAccessGained` / `onAccessLost`
+  //    handlers that report rows entering and leaving that set.
+  version: "1.154.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3979,10 +3979,13 @@ export function useCanWrite(tableId, options) {
  * rather than crashing at render (widget-parity skill).
  *
  * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
- * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
- * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent", relation_column?: string, record_id: string } }} [options]
+ * @param {{ onCreated?, onUpdated?, onDeleted?, onAccessGained?, onAccessLost? }} [handlers]  Per-event callbacks; each receives the snake_case record.
+ * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent"|"granted", relation_column?: string, record_id?: string } }} [options]
  *   `scope` narrows the stream below whole-table — required for a table
  *   governed by per-record grants. Re-subscribes on its VALUES, not identity.
+ *   `{ kind: "granted" }` streams every row the signed-in user reads through
+ *   a user or group grant; `onAccessGained` / `onAccessLost` report rows
+ *   entering (the full row) and leaving (`{ id }`) that set.
  * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
  */
 export function useDatastoreSubscription(table, handlers, options) {
@@ -4051,6 +4054,8 @@ export function useDatastoreSubscription(table, handlers, options) {
         onCreated: (r) => handlersRef.current?.onCreated?.(r),
         onUpdated: (r) => handlersRef.current?.onUpdated?.(r),
         onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
+        onAccessGained: (r) => handlersRef.current?.onAccessGained?.(r),
+        onAccessLost: (r) => handlersRef.current?.onAccessLost?.(r),
         onStatus: (s) => setStatus(s),
       },
       Object.keys(subscribeOptions).length > 0 ? subscribeOptions : undefined,

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(
@@ -1388,6 +1418,10 @@ export interface DatastoreSubscriptionHandlers {
   onCreated?: (record: Record<string, unknown>) => void;
   onUpdated?: (record: Record<string, unknown>) => void;
   onDeleted?: (record: Record<string, unknown>) => void;
+  /** Granted scope: a row the user can now read, in full. */
+  onAccessGained?: (record: Record<string, unknown>) => void;
+  /** Granted scope: a row the user can no longer read; nothing follows it. */
+  onAccessLost?: (record: { id: string }) => void;
 }
 
 // sc-6270: see SubscriptionScope in @colixsystems/datastore-client. A scoped
@@ -1395,7 +1429,8 @@ export interface DatastoreSubscriptionHandlers {
 // which is what lets a per-record-ACL table stream at all.
 export type DatastoreSubscriptionScope =
   | { kind: "record"; record_id: string }
-  | { kind: "parent"; relation_column: string; record_id: string };
+  | { kind: "parent"; relation_column: string; record_id: string }
+  | { kind: "granted" };
 
 export interface DatastoreSubscriptionOptions {
   fallbackAfterMs?: number;
@@ -1410,9 +1445,10 @@ export interface DatastoreSubscriptionOptions {
  * REST polling instead. Never throws — degrades to `{ status: "fallback" }` on
  * a host whose datastore client predates realtime.
  *
- * `options.scope` narrows the stream to one record or to a parent's
- * inheriting children; re-subscribes when the scope's values change, not on
- * every render.
+ * `options.scope` narrows the stream to one record, to a parent's
+ * inheriting children, or (`{ kind: "granted" }`) to the rows the signed-in
+ * user reads through a user or group grant; re-subscribes when the scope's
+ * values change, not on every render.
  */
 export function useDatastoreSubscription(
   tableId: string | null | undefined,
@@ -1930,6 +1966,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.193.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

@@ -2060,6 +2060,13 @@ const HOOKS = [
       "table governed by per-record grants, since a scope-less subscribe must " +
       "prove read-every-row. A `parent` scope requires the column be an " +
       "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }. { kind: 'granted' } streams every row the " +
+      "signed-in user can read through a grant to them or to one of their " +
+      "groups — the way to keep a list of 'my conversations' or 'my cases' " +
+      "live — and adds two handlers: onAccessGained(record) when a row " +
+      "becomes readable (the full row) and onAccessLost({ id }) when it stops " +
+      "being readable, after which no further event for it arrives. A " +
+      "logged-out visitor's granted subscribe resolves to " +
       "{ status: 'fallback' }.",
     returnShape: {
       status:
@@ -2212,6 +2219,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 +3215,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 +3257,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3376,7 +3450,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 +5069,15 @@ 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`.
+  // 1.154.0: additive (sc-10589) — `useDatastoreSubscription` accepts
+  //    `scope: { kind: "granted" }` (the rows the signed-in user reads through
+  //    a user or group grant) and the `onAccessGained` / `onAccessLost`
+  //    handlers that report rows entering and leaving that set.
+  version: "1.154.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,