@colixsystems/widget-sdk 0.190.0 → 0.192.0

package/dist/contract.cjs

@@ -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.
   {
@@ -2926,6 +3009,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. " +
@@ -3120,10 +3212,17 @@ const WIDGET_CONTEXT_SHAPE = {
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
       "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
-      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> }, " +
+      "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
+      "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
+      "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
+      "audioRecorder.start rejects with .code PERMISSION_DENIED | UNSUPPORTED | INTERNAL; getStatus().levelDb is the input level in dBFS " +
+      "(null when unknown); `ended` is true once the host stopped the recording itself (a lost headset, a call), and stop() then " +
+      "still resolves that clip. audioPlayer reports the end of a clip as playing:false at positionMs 0. " +
       "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
       "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
       "cache and hands them to the OS print sheet. " +
@@ -3155,6 +3254,8 @@ const WIDGET_CONTEXT_SHAPE = {
       imageEditor: "object",
       barcode: "object",
       pdfViewer: "object",
+      audioRecorder: "object",
+      audioPlayer: "object",
     },
   },
 };
@@ -3346,7 +3447,8 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "media",
     description:
-      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx.",
+      "Native audio playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <audio> element in widget.web.jsx. " +
+      "To record or play a clip on BOTH hosts, prefer the SDK's useAudioRecorder() / useAudioPlayer(uri) — no platform split needed.",
   },
   {
     specifier: "expo-video",
@@ -4961,7 +5063,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,

package/dist/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,

package/dist/hooks.js

@@ -1047,6 +1047,236 @@ export function useTranslate() {
   return { translate, translating, error, language: locale, available: client !== null };
 }
 
+/**
+ * Structured error surfaced by `useLinkPreview().error`. `code` is one of:
+ *   - "VALIDATION"    — 400 (the server refused the URL)
+ *   - "AUTH_REQUIRED" — 401 (no signed-in principal)
+ *   - "RATE_LIMITED"  — 429 (too many previews; `retryAfter` is in seconds)
+ *   - "NETWORK"       — no answer from the server (offline, timeout)
+ *   - "INTERNAL"      — anything else
+ * A page that simply has no preview is NOT an error.
+ */
+export class LinkPreviewError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "LinkPreviewError";
+    this.code = code;
+    this.retryAfter =
+      opts && typeof opts.retryAfter === "number" ? opts.retryAfter : null;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+const LINK_PREVIEW_CODES = new Set([
+  "VALIDATION",
+  "AUTH_REQUIRED",
+  "RATE_LIMITED",
+  "NETWORK",
+  "INTERNAL",
+]);
+
+function toLinkPreviewError(err) {
+  if (err instanceof LinkPreviewError) return err;
+  const status = err && typeof err.status === "number" ? err.status : null;
+  let code = "INTERNAL";
+  if (err && LINK_PREVIEW_CODES.has(err.code)) code = err.code;
+  else if (status === 400) code = "VALIDATION";
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 429) code = "RATE_LIMITED";
+  const message =
+    err && typeof err.message === "string" && err.message
+      ? err.message
+      : "Link preview failed";
+  return new LinkPreviewError(code, message, {
+    cause: err,
+    retryAfter: err && typeof err.retryAfter === "number" ? err.retryAfter : null,
+  });
+}
+
+// `URL` is avoided on purpose: React Native's polyfill lacks `protocol`.
+const PREVIEWABLE_URL = /^https?:\/\/[^\s/?#]+(?:[/?#]\S*)?$/i;
+
+function previewableUrl(url) {
+  if (typeof url !== "string") return null;
+  const trimmed = url.trim();
+  return PREVIEWABLE_URL.test(trimmed) ? trimmed : null;
+}
+
+// Shared by every widget instance so a chat with fifty copies of one link
+// asks once. Errors are never memoized: a later mount may succeed.
+const LINK_PREVIEW_MEMO_MAX = 500;
+// Well inside the signed image URL's lifetime, so a cached image still loads.
+const LINK_PREVIEW_MEMO_TTL_MS = 60 * 60 * 1000;
+const linkPreviewMemo = new Map();
+const linkPreviewInFlight = new Map();
+
+const LINK_PREVIEW_RETRY_MIN_S = 1;
+const LINK_PREVIEW_RETRY_MAX_S = 60;
+
+function isFreshLinkPreview(entry) {
+  return Date.now() - entry.storedAt <= LINK_PREVIEW_MEMO_TTL_MS;
+}
+
+// Render-safe: never reorders or evicts, so rendering stays pure.
+function linkPreviewMemoPeek(url) {
+  const entry = linkPreviewMemo.get(url);
+  return entry !== undefined && isFreshLinkPreview(entry) ? entry.preview : undefined;
+}
+
+// Effect-only: marks the entry recently used and drops it once stale.
+function linkPreviewMemoTouch(url) {
+  const entry = linkPreviewMemo.get(url);
+  if (entry === undefined) return undefined;
+  linkPreviewMemo.delete(url);
+  if (!isFreshLinkPreview(entry)) return undefined;
+  linkPreviewMemo.set(url, entry);
+  return entry.preview;
+}
+
+function linkPreviewRetryDelayMs(error) {
+  if (!error || error.code !== "RATE_LIMITED") return null;
+  const seconds = error.retryAfter;
+  if (typeof seconds !== "number" || !Number.isFinite(seconds)) return null;
+  const clamped = Math.min(
+    LINK_PREVIEW_RETRY_MAX_S,
+    Math.max(LINK_PREVIEW_RETRY_MIN_S, seconds),
+  );
+  return clamped * 1000;
+}
+
+function linkPreviewMemoWrite(url, preview) {
+  linkPreviewMemo.delete(url);
+  if (linkPreviewMemo.size >= LINK_PREVIEW_MEMO_MAX) {
+    const oldest = linkPreviewMemo.keys().next();
+    if (!oldest.done) linkPreviewMemo.delete(oldest.value);
+  }
+  linkPreviewMemo.set(url, { preview, storedAt: Date.now() });
+}
+
+function requestLinkPreview(client, url) {
+  const pending = linkPreviewInFlight.get(url);
+  if (pending) return pending;
+  let started;
+  try {
+    started = Promise.resolve(client.get(url));
+  } catch (err) {
+    started = Promise.reject(err);
+  }
+  const request = started
+    .then((preview) => {
+      linkPreviewMemoWrite(url, preview);
+      return preview;
+    })
+    .finally(() => {
+      if (linkPreviewInFlight.get(url) === request) linkPreviewInFlight.delete(url);
+    });
+  linkPreviewInFlight.set(url, request);
+  return request;
+}
+
+/** Exposed so tests (and a host teardown) can drop the session memo. */
+export function _resetLinkPreviewMemo() {
+  linkPreviewMemo.clear();
+  linkPreviewInFlight.clear();
+}
+
+/**
+ * Preview a link: the page's title, description, site name and image, fetched
+ * by the platform (the device never contacts the linked site). Returns
+ * `{ preview, loading, error, available }`.
+ *
+ *   const { preview } = useLinkPreview(firstUrlInMessage);
+ *   // preview: { url, title, description, site_name, image_url } | null
+ *
+ * `preview` keeps the wire's snake_case names. A page with nothing to show
+ * resolves with every field but `url` null — render the plain link then.
+ * `image_url` loads directly in an <Image>; it needs no auth headers.
+ *
+ * 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 throws and 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 the server's
+ * `retryAfter` (clamped to 1–60 s).
+ */
+export function useLinkPreview(url) {
+  const ctx = useWidgetContextOrThrow("useLinkPreview");
+  const client =
+    ctx.linkPreviews && typeof ctx.linkPreviews.get === "function"
+      ? ctx.linkPreviews
+      : null;
+  const available = client !== null;
+  const target = previewableUrl(url);
+
+  const clientRef = useRef(client);
+  clientRef.current = client;
+  const [settled, setSettled] = useState(() => {
+    const hit = target ? linkPreviewMemoPeek(target) : undefined;
+    return hit === undefined ? null : { url: target, preview: hit, error: null };
+  });
+  // URLs this mount already retried, so a rate limit is retried only once.
+  const retriedRef = useRef(null);
+  if (retriedRef.current === null) retriedRef.current = new Set();
+
+  useEffect(() => {
+    if (!target || !clientRef.current) return undefined;
+    const memoized = linkPreviewMemoTouch(target);
+    if (memoized !== undefined) {
+      // Held in state too, so a later LRU eviction cannot strand `loading`.
+      setSettled((prev) =>
+        prev && prev.url === target && prev.preview === memoized
+          ? prev
+          : { url: target, preview: memoized, error: null },
+      );
+      return undefined;
+    }
+    let live = true;
+    let retryTimer = null;
+    const load = () => {
+      const hit = linkPreviewMemoTouch(target);
+      const result =
+        hit !== undefined ? Promise.resolve(hit) : requestLinkPreview(clientRef.current, target);
+      result.then(
+        (preview) => {
+          if (live) setSettled({ url: target, preview, error: null });
+        },
+        (err) => {
+          if (!live) return;
+          const error = toLinkPreviewError(err);
+          setSettled({ url: target, preview: null, error });
+          const delayMs = linkPreviewRetryDelayMs(error);
+          if (delayMs === null || retriedRef.current.has(target) || !clientRef.current) return;
+          retriedRef.current.add(target);
+          retryTimer = setTimeout(() => {
+            retryTimer = null;
+            if (live && clientRef.current) load();
+          }, delayMs);
+        },
+      );
+    };
+    load();
+    return () => {
+      live = false;
+      if (retryTimer !== null) clearTimeout(retryTimer);
+    };
+  }, [target, available]);
+
+  if (!target || !available) {
+    return { preview: null, loading: false, error: null, available };
+  }
+  const memoized = linkPreviewMemoPeek(target);
+  if (memoized !== undefined) {
+    return { preview: memoized, loading: false, error: null, available };
+  }
+  const own = settled && settled.url === target ? settled : null;
+  return {
+    preview: own ? own.preview : null,
+    loading: own === null,
+    error: own ? own.error : null,
+    available,
+  };
+}
+
 /**
  * sc-5206 — keep a query-shaped argument at a STABLE reference across
  * renders so it can be handed straight to `useDatastoreQuery`'s second