@colixsystems/widget-sdk 0.189.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. |
@@ -53,6 +54,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **AGENTS** | `useAgent(agentRef)` | `{ send, cancel, reset, messages, sending, resuming, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). Sending is IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. On mount the hook DOES reopen the caller's most recent thread with this agent, so a refresh or a navigation keeps the conversation instead of starting a blank one; that resume only READS and spends no credit. `resuming` is true while it runs — render a loading state, not an empty thread. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance), and the new thread is the one a later mount resumes. **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
 | **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
+| **DATASTORE** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
@@ -75,7 +77,40 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.189.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)
+
+**New `useTyping(tableId, recordId)` hook: a typing indicator for one record.** It returns `{ typingUserIds, setTyping, status }`. Call `setTyping(true)` on every keystroke in your composer and `setTyping(false)` when the message is sent, the field is cleared or it loses focus. The hook throttles for you: it sends at most one signal every 3 s, and sends `false` on its own after 5 s without a keystroke. `typingUserIds` lists the other users typing in that record (never yourself); each one drops out 6 s after their last signal, so a closed tab never leaves a stale indicator. Signals carry no message content and are never stored.
+
+Key it on the record the conversation lives in (a thread or channel row), which the user must be able to read. It rides the same realtime connection as `useDatastoreSubscription`, so a widget holds one socket for both. `status` is `"connecting"`, `"live"` or `"unavailable"`; it is `"unavailable"` for an anonymous visitor, a refused subscription, a preview with no backend, and a host whose datastore client predates typing. The hook never throws, so render the indicator only when `typingUserIds` is non-empty:
+
+```jsx
+const { typingUserIds, setTyping } = useTyping(threadsTableId, threadId);
+// <TextInput onChangeText={(t) => { setDraft(t); setTyping(t.length > 0); }} onBlur={() => setTyping(false)} />
+// {typingUserIds.length > 0 && <Text>{typingUserIds.length === 1 ? "Someone is typing…" : "Several people are typing…"}</Text>}
+```
+
+Declare `datastore.read` for the table. Additive; works identically in the web Player and the native export.
 
 ### What's new in 0.189.0 (contract 1.150.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)",
@@ -2043,6 +2068,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -2892,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. " +
@@ -4923,7 +4991,14 @@ const CONTRACT = deepFreeze({
   //    native-only file keeps every vetted subpath (Metro resolves them).
   //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
   //    linter export `subpathImportRootsFor(manifest)`.
-  version: "1.150.0",
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ 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"`.
+  // 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)",
@@ -2043,6 +2068,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -2888,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. " +
@@ -4919,7 +4987,14 @@ const CONTRACT = deepFreeze({
   //    native-only file keeps every vetted subpath (Metro resolves them).
   //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
   //    linter export `subpathImportRootsFor(manifest)`.
-  version: "1.150.0",
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ 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"`.
+  // 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
@@ -3834,6 +4064,71 @@ export function useDatastoreSubscription(table, handlers, options) {
   return { status };
 }
 
+const _NO_TYPERS = Object.freeze([]);
+
+/**
+ * Who else is typing in one record; call `setTyping` per keystroke.
+ * Never throws: a client without typing reports status "unavailable".
+ *
+ * @param {string} tableId
+ * @param {string} recordId
+ * @returns {{ typingUserIds: string[], setTyping: (active: boolean) => void, status: "connecting" | "live" | "unavailable" }}
+ */
+export function useTyping(tableId, recordId) {
+  const ctx = useWidgetContextOrThrow("useTyping");
+  const [typingUserIds, setTypingUserIds] = useState(_NO_TYPERS);
+  const [status, setStatus] = useState("connecting");
+  const handleRef = useRef(null);
+  // `ctx` is a fresh identity per host render; the effect keys on the ids.
+  const recordsRef = useRef(null);
+  recordsRef.current =
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null;
+
+  useEffect(() => {
+    setTypingUserIds(_NO_TYPERS);
+    setStatus("connecting");
+    const unavailable = () => {
+      setStatus("unavailable");
+      return undefined;
+    };
+    if (!tableId || !recordId || typeof recordsRef.current !== "function") {
+      return unavailable();
+    }
+    try {
+      const ns = recordsRef.current(tableId);
+      if (!ns || typeof ns.typing !== "function") return unavailable();
+      let current = true;
+      const handle = ns.typing(recordId, {
+        onChange: (ids) => {
+          if (current) setTypingUserIds(ids);
+        },
+        onStatus: (s) => {
+          if (current) setStatus(s);
+        },
+      });
+      handleRef.current = handle;
+      return () => {
+        current = false;
+        handleRef.current = null;
+        if (handle && typeof handle.stop === "function") handle.stop();
+      };
+    } catch (_) {
+      return unavailable();
+    }
+  }, [tableId, recordId]);
+
+  const setTyping = useCallback((active) => {
+    const handle = handleRef.current;
+    if (handle && typeof handle.setTyping === "function") {
+      handle.setTyping(active === true);
+    }
+  }, []);
+
+  return { typingUserIds, setTyping, status };
+}
+
 /* ============================================================================
  * ASSETS CLIENT — ctx.assets (@colixsystems/assets-client)
  *

package/dist/index.d.ts

@@ -496,6 +496,14 @@ export interface DatastoreClient {
       ): Promise<unknown>;
       revoke(permissionId: string): Promise<void>;
     };
+    /** REQ-RT-08 — backs `useTyping`; optional, the hook degrades without it. */
+    typing?(
+      recordId: string,
+      handlers: {
+        onChange?(typingUserIds: string[]): void;
+        onStatus?(status: TypingStatus): void;
+      },
+    ): { setTyping(active: boolean): void; stop(): void };
   };
 }
 
@@ -689,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 };
@@ -1410,6 +1420,27 @@ export function useDatastoreSubscription(
   options?: DatastoreSubscriptionOptions,
 ): { status: DatastoreSubscriptionStatus };
 
+export type TypingStatus = "connecting" | "live" | "unavailable";
+
+/**
+ * REQ-RT-08: who else is typing in one record, and announcing your own typing,
+ * via `ctx.datastore.records(tableId).typing(recordId, ...)`. Call
+ * `setTyping(true)` on every keystroke (throttled inside; `false` is sent
+ * after 5 s idle) and `setTyping(false)` on send, clear or blur.
+ * `typingUserIds` lists the other users typing; each drops out 6 s after
+ * their last signal. Needs a signed-in user who can read the record.
+ * Re-subscribes when `tableId` or `recordId` changes. Never throws — a host
+ * whose datastore client lacks typing reports `status: "unavailable"`.
+ */
+export function useTyping(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): {
+  typingUserIds: string[];
+  setTyping(active: boolean): void;
+  status: TypingStatus;
+};
+
 /**
  * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
  * refetch }`. The `url` is an absolute URL composed against the host's API
@@ -1506,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;
@@ -2169,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

@@ -60,6 +60,7 @@ export {
   IdentificationError,
   useRecordPermissions,
   useDatastoreSubscription,
+  useTyping,
   useWidgetEvent,
   useWidgetInput,
   usePayments,
@@ -70,6 +71,8 @@ export {
   useI18n,
   useTranslate,
   TranslateError,
+  useLinkPreview,
+  LinkPreviewError,
   useUser,
   useUserPhoto,
   useFill,

package/dist/index.native.js

@@ -60,6 +60,7 @@ export {
   IdentificationError,
   useRecordPermissions,
   useDatastoreSubscription,
+  useTyping,
   useWidgetEvent,
   useWidgetInput,
   usePayments,
@@ -70,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.189.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)",
@@ -2043,6 +2068,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -2888,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. " +
@@ -4919,7 +4987,14 @@ const CONTRACT = deepFreeze({
   //    native-only file keeps every vetted subpath (Metro resolves them).
   //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
   //    linter export `subpathImportRootsFor(manifest)`.
-  version: "1.150.0",
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ 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"`.
+  // 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,