@colixsystems/widget-sdk 0.190.0 → 0.191.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,26 @@ 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.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**.
+
+### 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/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)",
@@ -2926,6 +2951,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. " +
@@ -4961,7 +4995,10 @@ 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).
+  version: "1.152.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)",
@@ -2922,6 +2947,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. " +
@@ -4957,7 +4991,10 @@ 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).
+  version: "1.152.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

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 };
@@ -1535,6 +1537,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;
@@ -2198,6 +2230,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,

package/dist/index.native.js

@@ -71,6 +71,8 @@ export {
   useI18n,
   useTranslate,
   TranslateError,
+  useLinkPreview,
+  LinkPreviewError,
   useUser,
   useUserPhoto,
   useFill,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.190.0",
+  "version": "0.191.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)",
@@ -2922,6 +2947,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. " +
@@ -4957,7 +4991,10 @@ 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).
+  version: "1.152.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,