@colixsystems/widget-sdk 0.190.0 → 0.192.0

package/dist/index.d.ts

@@ -697,6 +697,8 @@ export interface WidgetContext<TProps = unknown> {
   identification: IdentificationClient;
   /** sc-7991 — injected @colixsystems/agents-client backing useAgent(). */
   agents?: { conversations(agentId: string): unknown };
+  /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
+  linkPreviews?: { get(url: string): Promise<LinkPreview> };
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
   renderer: { renderNode(node: unknown): unknown };
   events: { emit(eventName: string, payload?: unknown): void };
@@ -715,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(
@@ -1535,6 +1567,36 @@ export function useTranslate(): {
   available: boolean;
 };
 
+/**
+ * The preview of one page, with the wire's snake_case names. A page with
+ * nothing to show has every field except `url` null. `image_url` loads
+ * directly in an <Image> and needs no auth headers.
+ */
+export interface LinkPreview {
+  url: string;
+  title: string | null;
+  description: string | null;
+  site_name: string | null;
+  image_url: string | null;
+}
+
+/**
+ * Preview a link: the page's title, description, site name and image, fetched
+ * by the platform so the device never contacts the linked site.
+ *
+ * A `url` that is not an absolute http(s) URL returns `preview: null` without
+ * a request. `available` is false on a host that brokers no link-preview
+ * client; the hook then never fetches. Results are shared across every widget
+ * for up to an hour, and concurrent requests for one URL are made once. A
+ * RATE_LIMITED failure is retried once after `retryAfter` (clamped to 1–60 s).
+ */
+export function useLinkPreview(url: string | null | undefined): {
+  preview: LinkPreview | null;
+  loading: boolean;
+  error: LinkPreviewError | null;
+  available: boolean;
+};
+
 export interface TranslateOptions {
   /** Target language code. Defaults to the app user's selected language. */
   target?: string;
@@ -1898,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
@@ -2198,6 +2348,26 @@ export class AgentError extends Error {
   constructor(code: string, message: string, opts?: { cause?: unknown });
 }
 
+/**
+ * Error surfaced by `useLinkPreview().error`. A page that simply has no
+ * preview is not an error. `retryAfter` (seconds) is set on RATE_LIMITED.
+ */
+export class LinkPreviewError extends Error {
+  code:
+    | "VALIDATION"
+    | "AUTH_REQUIRED"
+    | "RATE_LIMITED"
+    | "NETWORK"
+    | "INTERNAL"
+    | (string & {});
+  retryAfter: number | null;
+  constructor(
+    code: string,
+    message: string,
+    opts?: { cause?: unknown; retryAfter?: number | null },
+  );
+}
+
 export class TranslateError extends Error {
   code:
     | "UNSUPPORTED"

package/dist/index.js

@@ -71,6 +71,8 @@ export {
   useI18n,
   useTranslate,
   TranslateError,
+  useLinkPreview,
+  LinkPreviewError,
   useUser,
   useUserPhoto,
   useFill,
@@ -106,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

@@ -71,6 +71,8 @@ export {
   useI18n,
   useTranslate,
   TranslateError,
+  useLinkPreview,
+  LinkPreviewError,
   useUser,
   useUserPhoto,
   useFill,
@@ -104,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.190.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

@@ -784,6 +784,31 @@ const HOOKS = [
     requiredContextSlice: ["i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useLinkPreview",
+    signature: "useLinkPreview(url)",
+    description:
+      "Preview a link the way a messenger does: the page's title, description, site name and image. The PLATFORM fetches the page, so the " +
+      "device never contacts the linked site, and private or internal addresses are refused. Returns { preview, loading, error, available }. " +
+      "`preview` is { url, title, description, site_name, image_url } with the wire's snake_case names, or null while loading. A page with " +
+      "nothing to show (unreachable, not HTML, too slow) resolves with every field but url null — that is NOT an error: render the plain link. " +
+      "image_url is a signed URL that loads directly in <Image> with no auth headers. A url that is not an absolute http(s) URL returns " +
+      "preview: null with no request, so pass the link you found in the text straight in. Results are memoized for up to an hour across every " +
+      "widget and concurrent calls for one URL make one request, so a list of messages may call it per row. error is a LinkPreviewError whose " +
+      ".code is VALIDATION | AUTH_REQUIRED | RATE_LIMITED | NETWORK | INTERNAL; render the plain link on any error. A RATE_LIMITED failure is " +
+      "retried ONCE automatically after the server's retryAfter (clamped to 1–60 s), so the card can still appear. `available` is false on a " +
+      "host that brokers no link-preview client; the hook then never fetches. Never block a message on it: render the text first and add the " +
+      "preview card when it arrives. Reads ctx.linkPreviews. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      preview:
+        "{ url: string, title: string | null, description: string | null, site_name: string | null, image_url: string | null } | null",
+      loading: "boolean",
+      error: "LinkPreviewError | null",
+      available: "boolean  // false when the host brokers no link-preview client",
+    },
+    requiredContextSlice: ["linkPreviews.get"],
+    scopes: null,
+  },
   {
     name: "useStableQuery",
     signature: "useStableQuery(buildQuery)",
@@ -2187,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.
   {
@@ -2922,6 +3005,15 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { conversations: "function" },
   },
+  linkPreviews: {
+    description:
+      "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
+      "Backs useLinkPreview(). The server fetches the page; a page with nothing to show resolves with null fields rather than rejecting. " +
+      "image_url is absolute on every host and needs no auth headers. Any signed-in principal may call it (the app user, or the studio " +
+      "user previewing on the canvas). Absent on a host that brokers none, where useLinkPreview() degrades to available: false.",
+    required: false,
+    fields: { get: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -3116,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. " +
@@ -3151,6 +3250,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3342,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",
@@ -4957,7 +5059,14 @@ const CONTRACT = deepFreeze({
   //    `{ typingUserIds, setTyping, status }`: the other users typing in one
   //    record, over the datastore client's single realtime socket. A host
   //    whose client lacks `records(t).typing` reads `status: "unavailable"`.
-  version: "1.151.0",
+  // 1.152.0: additive (sc-10580) — new `useLinkPreview(url)` returns
+  //    `{ preview, loading, error, available }` from the new optional
+  //    `linkPreviews` slice (@colixsystems/link-preview-client).
+  // 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,