@colixsystems/widget-sdk 0.190.0 → 0.192.0

package/README.md

@@ -43,6 +43,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useCamera(options)` (optional: options) | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
+| **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreFigure(table, { aggregate, column, filter })` (optional: options) | `{ value, text, truncated, loading, fetching, error, refetch }` | `records(table).list` (a count reads the envelope total; a sum or average up to 1000 rows) — `datastore.read:*`. One count / sum / average for a `<Stat>`, computed exactly as the built-in Stat widget does. |
@@ -76,7 +77,46 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.190.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)
+
+**New `useLinkPreview(url)` hook: show a preview card for a link.** It returns `{ preview, loading, error, available }`, where `preview` is `{ url, title, description, site_name, image_url }` (the wire's snake_case names) once it loads. The platform fetches the page, so the device showing the link never contacts the linked site. `image_url` is a signed URL that loads directly in an `<Image>` with no auth headers.
+
+A page with nothing to show (unreachable, not HTML, too slow) is not an error: it resolves with every field but `url` set to `null`, and you render the plain link. A `url` that is not an absolute `http:`/`https:` URL returns `preview: null` without a request, so you can pass the first link you found in a message straight in. Results are kept for up to an hour and shared by every widget, and concurrent calls for one URL make one request, so a message list may call the hook per row. `error` is a `LinkPreviewError` whose `.code` is `VALIDATION`, `AUTH_REQUIRED`, `RATE_LIMITED`, `NETWORK` or `INTERNAL`; render the plain link on any error. A `RATE_LIMITED` failure is retried once, automatically, after the `retryAfter` the server sends (clamped to 1–60 s), so a long list of links still fills in. `available` is `false` on a host that brokers no link-preview client, and the hook then never fetches.
+
+```jsx
+const { preview } = useLinkPreview(firstLink);
+// {preview && preview.title && (
+//   <View>
+//     {preview.image_url && <Image source={{ uri: preview.image_url }} style={{ width: 64, height: 64 }} />}
+//     <Text>{preview.title}</Text>
+//     {preview.site_name && <Text>{preview.site_name}</Text>}
+//   </View>
+// )}
+```
+
+It needs no scope. The host injects `@colixsystems/link-preview-client` as the new optional `ctx.linkPreviews` slice. Additive; works identically in the web Player and the native export.
 
 ### What's new in 0.190.0 (contract 1.151.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,
+  };
+}