@colixsystems/widget-sdk 0.269.1 → 0.270.0

package/README.md

@@ -50,7 +50,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities }`, applied on the server: see *Querying records*. |
+| **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:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities, live }`, applied on the server: see *Querying records*. `live: true` re-reads when anyone else changes the table: see *Live lists*. |
 | **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. |
 | **DATASTORE** | `useDatastoreRecord(table, id, options)` (optional: options) | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching`; `{ includeCapabilities: true }` adds `data._capabilities` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -59,7 +59,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 (with the `search` text and `filters` it read with), 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. |
 | **ACTIONS** | `useAction(actionRef)` | `{ available, run, running, result, error }` | `ctx.actions` — `actions.run:*`. Run one of the workspace's Actions from an event handler (never on mount) and read the value it passed to `respond()`. The Action needs the app trigger. `available` is false when nothing is bound or the host brokers no client. Errors are `ActionError` with a stable `code`. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. A successful write re-reads every query, record, figure and aggregate on that table in every widget on the screen (a run of writes at most once a second, always once more after the last), so never refetch after it, and never write from an effect that re-runs on the data it reads unless a ref or Set marks what it already wrote. **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 realtime 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"`). For a live list of the signed-in user's own rows pass `{ kind: "granted" }`: every row they read through a grant to them or one of their groups, plus `onAccessGained(record)` / `onAccessLost({ id })` as rows enter and leave that set. Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. To keep a list, record or figure current, pass `live: true` to its read hook instead (*Live lists*); this hook is for acting on each change. Live `onCreated` / `onUpdated` / `onDeleted` off the realtime 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"`). For a live list of the signed-in user's own rows pass `{ kind: "granted" }`: every row they read through a grant to them or one of their groups, plus `onAccessGained(record)` / `onAccessLost({ id })` as rows enter and leave that set. 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. |
@@ -86,7 +86,31 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.269.1` — 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.270.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.270.0 (contract 1.220.0)
+
+**Live lists.** Add `live: true` to the object you already pass `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreFigure` or `useDatastoreAggregate`, and the read stays current when anyone else changes the table: `useDatastoreQuery(tableId, { sort: "created_at:desc", limit: 50, live: true })`. See *Live lists* below. The publish checker refuses a `setInterval` that re-reads records (`widget.refetchPoll`).
+
+#### Live lists
+
+- **What it does.** The read rides the table's realtime stream on the widget's one datastore socket (the same subscription `useDatastoreSubscription` uses), and each pushed change re-reads it the way a write does: a burst folds into one read, a busy table re-reads at most once a second and always once more after the last change. Without `live`, a read behaves exactly as before.
+- **Permissions.** The server admits the whole-table stream only for a viewer who can read every row. Otherwise a signed-in viewer streams the rows granted to them, filtered per row, and a signed-out visitor gets no stream. The re-read is the ordinary permission-checked read, so a change to a row the viewer cannot read never changes what they see. Where nothing can stream (no socket, a refused visitor) the read re-checks every 30 seconds.
+- **Table ids.** Pass the table id a `tableRef` property binds. A table name still reads, but only re-checks every 30 seconds.
+- **No jumping.** A live re-read keeps `data` on screen with `loading: false`; render rows with `key={row.id}` so the ones already shown keep their place. For a newest-first list people scroll, hold new rows behind an "N new" button instead of pushing the list down:
+
+```jsx
+const { data, loading } = useDatastoreQuery(tableId, { sort: "created_at:desc", limit: 50, live: true });
+const [seen, setSeen] = useState(null);
+useEffect(() => {
+  if (!loading && seen === null) setSeen(new Set(data.map((r) => r.id)));
+}, [loading, data, seen]);
+const shown = seen ? data.filter((r) => seen.has(r.id)) : data;
+const fresh = seen ? data.length - shown.length : 0;
+// {fresh > 0 ? <Button title={`${fresh} new`} onPress={() => setSeen(new Set(data.map((r) => r.id)))} /> : null}
+```
+
+- **Never hand-poll.** Don't call `refetch()` from `setInterval`, and don't wire `useDatastoreSubscription` just to refresh a list. Keep that hook for acting on each change (a toast, a sound).
 
 ### What's new in 0.269.1 (contract 1.219.0)
 

package/dist/contract.cjs

@@ -1354,7 +1354,8 @@ const HOOKS = [
       "keeps it in `data` with loading false while `fetching` is true; a " +
       "different table or record id resets to loading. " +
       "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
-      "for useDatastoreQuery.",
+      "for useDatastoreQuery. `{ live: true }` re-reads it when anyone else " +
+      "changes the table.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1941,7 +1942,12 @@ const HOOKS = [
       "meta.total), not just the page in `data`; null until known. A " +
       "successful useDatastoreMutation write to the table, from this widget " +
       "or any other on the screen, re-reads it on its own: never refetch or " +
-      "subscribe for your own writes.",
+      "subscribe for your own writes. Add `live: true` to the options to also " +
+      "re-read when anyone else changes the table (a pushed change, paced like " +
+      "a write; the re-read is the same permission-checked read, and keeps the " +
+      "rows on screen with loading false). Use it for lists other people " +
+      "change: queues, bookings, chat, dashboards. Never poll with setInterval " +
+      "or wire useDatastoreSubscription for that.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -1955,8 +1961,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreFigure",
-    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
-    optionalArgs: ["aggregate", "column", "filter"],
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
+    optionalArgs: ["aggregate", "column", "filter", "live"],
     description:
       "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
       "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
@@ -1971,7 +1977,8 @@ const HOOKS = [
       "or average reads up to 1000 rows, skips blank cells rather than counting " +
       "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
       "Stat widget computes its figure through this hook, so use it rather than " +
-      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+      "reducing useDatastoreQuery rows by hand. Call it once per figure. " +
+      "`live: true` re-reads it when anyone else changes the table.",
     returnShape: {
       value: "number | null",
       text: "string | null  // the formatted figure for <Stat value>",
@@ -1989,8 +1996,8 @@ const HOOKS = [
   {
     name: "useDatastoreAggregate",
     signature:
-      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
-    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit, live })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit", "live"],
     description:
       "Counts rows on the server over EVERY row the viewer can read, so it is " +
       "exact past the 1000-row page a list read returns — never group " +
@@ -2009,7 +2016,8 @@ const HOOKS = [
       "them out with a `nempty:` filter. Encrypted, array, file and relation " +
       "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
       "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
-      "table until a bound table is known.",
+      "table until a bound table is known. `live: true` re-reads it when " +
+      "anyone else changes the table.",
     returnShape: {
       buckets:
         "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
@@ -2874,6 +2882,9 @@ const HOOKS = [
     signature: "useDatastoreSubscription(tableId, handlers, options)",
     optionalArgs: ["options"],
     description:
+      "To keep a list, record, figure or aggregate current, pass `live: true` " +
+      "to its read hook instead; this hook is for acting on each change " +
+      "(a toast, a sound, merging rows yourself). " +
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
       "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
@@ -6495,7 +6506,9 @@ const CONTRACT = deepFreeze({
   //    not reach the script.
   // 1.219.0: behaviour (sc-14407) — a useDatastoreMutation write re-reads
   //    every query, record, figure and aggregate on that table, app-wide.
-  version: "1.219.0",
+  // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
+  //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
+  version: "1.220.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1351,7 +1351,8 @@ const HOOKS = [
       "keeps it in `data` with loading false while `fetching` is true; a " +
       "different table or record id resets to loading. " +
       "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
-      "for useDatastoreQuery.",
+      "for useDatastoreQuery. `{ live: true }` re-reads it when anyone else " +
+      "changes the table.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1938,7 +1939,12 @@ const HOOKS = [
       "meta.total), not just the page in `data`; null until known. A " +
       "successful useDatastoreMutation write to the table, from this widget " +
       "or any other on the screen, re-reads it on its own: never refetch or " +
-      "subscribe for your own writes.",
+      "subscribe for your own writes. Add `live: true` to the options to also " +
+      "re-read when anyone else changes the table (a pushed change, paced like " +
+      "a write; the re-read is the same permission-checked read, and keeps the " +
+      "rows on screen with loading false). Use it for lists other people " +
+      "change: queues, bookings, chat, dashboards. Never poll with setInterval " +
+      "or wire useDatastoreSubscription for that.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -1952,8 +1958,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreFigure",
-    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
-    optionalArgs: ["aggregate", "column", "filter"],
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
+    optionalArgs: ["aggregate", "column", "filter", "live"],
     description:
       "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
       "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
@@ -1968,7 +1974,8 @@ const HOOKS = [
       "or average reads up to 1000 rows, skips blank cells rather than counting " +
       "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
       "Stat widget computes its figure through this hook, so use it rather than " +
-      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+      "reducing useDatastoreQuery rows by hand. Call it once per figure. " +
+      "`live: true` re-reads it when anyone else changes the table.",
     returnShape: {
       value: "number | null",
       text: "string | null  // the formatted figure for <Stat value>",
@@ -1986,8 +1993,8 @@ const HOOKS = [
   {
     name: "useDatastoreAggregate",
     signature:
-      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
-    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit, live })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit", "live"],
     description:
       "Counts rows on the server over EVERY row the viewer can read, so it is " +
       "exact past the 1000-row page a list read returns — never group " +
@@ -2006,7 +2013,8 @@ const HOOKS = [
       "them out with a `nempty:` filter. Encrypted, array, file and relation " +
       "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
       "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
-      "table until a bound table is known.",
+      "table until a bound table is known. `live: true` re-reads it when " +
+      "anyone else changes the table.",
     returnShape: {
       buckets:
         "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
@@ -2871,6 +2879,9 @@ const HOOKS = [
     signature: "useDatastoreSubscription(tableId, handlers, options)",
     optionalArgs: ["options"],
     description:
+      "To keep a list, record, figure or aggregate current, pass `live: true` " +
+      "to its read hook instead; this hook is for acting on each change " +
+      "(a toast, a sound, merging rows yourself). " +
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
       "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
@@ -6492,7 +6503,9 @@ const CONTRACT = deepFreeze({
   //    not reach the script.
   // 1.219.0: behaviour (sc-14407) — a useDatastoreMutation write re-reads
   //    every query, record, figure and aggregate on that table, app-wide.
-  version: "1.219.0",
+  // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
+  //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
+  version: "1.220.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datastore-figure.js

@@ -9,8 +9,9 @@ import { figureQuery, reduceFigure } from "./figure.js";
  * `filter` keeps the previous figure on screen while `fetching`.
  */
 export function useDatastoreFigure(table, options) {
-  const { aggregate, column, filter } = options || {};
-  const rows = useDatastoreQuery(table || null, figureQuery(filter, aggregate));
+  const { aggregate, column, filter, live } = options || {};
+  const query = figureQuery(filter, aggregate);
+  const rows = useDatastoreQuery(table || null, live === true ? { ...query, live } : query);
   const figure =
     table && !rows.loading && !rows.error
       ? reduceFigure(rows.data, { aggregate, column }, rows.total)

package/dist/hooks.js

@@ -28,6 +28,7 @@ import React, {
   useRef,
   useState,
 } from "react";
+import { watchTableChanges } from "./live-table.js";
 // REQ-L10N-WIDGET / REQ-L10N-SHARED: the translation key formats live in ONE
 // place (contract.js). useI18n (lookup) and the backend seeder (write) both
 // call them so the namespaced keys can never drift between the two sides.
@@ -2894,6 +2895,8 @@ const queryResultKey = (table, queryKey) => JSON.stringify([table, queryKey]);
 // write through any widget re-reads every other widget's rows on that table.
 // A burst of writes folds into one re-read; a long run of them re-reads each
 // widget at most once a second, and always once more after the last write.
+// sc-14423 — a change someone else made reaches only `live` readers, paced
+// the same way.
 const TABLE_WRITE_SETTLE_MS = 50;
 const TABLE_REREAD_INTERVAL_MS = 1000;
 const tableWrites = new Map();
@@ -2909,7 +2912,7 @@ export function stampFetchStart(ref) {
 function tableWritesOf(table) {
   let entry = tableWrites.get(table);
   if (!entry) {
-    entry = { listeners: new Set(), timer: null, lastRereadAt: -Infinity, wroteAt: 0 };
+    entry = { listeners: new Set(), timer: null, lastRereadAt: -Infinity, wroteAt: 0, changedAt: 0 };
     tableWrites.set(table, entry);
   }
   return entry;
@@ -2924,7 +2927,7 @@ function rereadTable(table, entry) {
   entry.lastRereadAt = Date.now();
   for (const listener of Array.from(entry.listeners)) {
     try {
-      listener(entry.wroteAt);
+      listener(entry);
     } catch (_e) {
       // A reader's failure must never reach the write that already succeeded.
     }
@@ -2932,10 +2935,11 @@ function rereadTable(table, entry) {
   forgetIfIdle(table, entry);
 }
 
-function announceTableWrite(table) {
+function announceTableChange(table, { local }) {
   const entry = tableWritesOf(table);
   readWriteOrder += 1;
-  entry.wroteAt = readWriteOrder;
+  entry.changedAt = readWriteOrder;
+  if (local) entry.wroteAt = readWriteOrder;
   if (entry.timer) return;
   const wait = Math.max(TABLE_WRITE_SETTLE_MS, entry.lastRereadAt + TABLE_REREAD_INTERVAL_MS - Date.now());
   entry.timer = setTimeout(() => rereadTable(table, entry), wait);
@@ -2947,15 +2951,22 @@ function announceTableWrite(table) {
  * widget, unless the reader began a fetch of its own (stamped into
  * `fetchStartRef` by stampFetchStart) after that write. Keyed by the table
  * reference exactly as the widgets pass it.
+ *
+ * sc-14423 — `live` also re-reads when anyone else changes the table, through
+ * the widget's datastore client's realtime subscription (see live-table.js).
  */
-export function useRereadOnWrite(table, reread, fetchStartRef) {
+export function useRereadOnWrite(table, reread, fetchStartRef, live = false) {
+  const ctx = useContext(HostWidgetContext);
   const rereadRef = useRef(reread);
   rereadRef.current = reread;
+  const liveRef = useRef(live);
+  liveRef.current = live;
   useEffect(() => {
     if (!table) return undefined;
     const entry = tableWritesOf(table);
-    const listener = (wroteAt) => {
-      if (fetchStartRef && fetchStartRef.current > wroteAt) return;
+    const listener = ({ wroteAt, changedAt }) => {
+      const since = liveRef.current ? changedAt : wroteAt;
+      if (!since || (fetchStartRef && fetchStartRef.current > since)) return;
       rereadRef.current();
     };
     entry.listeners.add(listener);
@@ -2965,6 +2976,24 @@ export function useRereadOnWrite(table, reread, fetchStartRef) {
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [table]);
+
+  const recordsRef = useRef(null);
+  recordsRef.current = ctx && ctx.datastore && typeof ctx.datastore.records === "function" ? ctx.datastore.records : null;
+  const signedIn = Boolean(ctx && ctx.user && ctx.user.id);
+  useEffect(() => {
+    if (!live || !table || !recordsRef.current) return undefined;
+    let ns;
+    try {
+      ns = recordsRef.current(table);
+    } catch (_e) {
+      return undefined;
+    }
+    return watchTableChanges(ns, {
+      tableId: table,
+      signedIn,
+      onChange: () => announceTableChange(table, { local: false }),
+    });
+  }, [table, live, signedIn]);
 }
 const recordResultKey = (table, recordId, includeCapabilities = false) =>
   JSON.stringify([table, recordId, includeCapabilities]);
@@ -3121,7 +3150,7 @@ export function useDatastoreQuery(table, query) {
   // sc-1179 — auto-subscribe to the page-level refresh tick so a
   // pull-to-refresh on mobile re-runs the query without per-widget code.
   useRefresh(refetch);
-  useRereadOnWrite(table, refetch, fetchStartRef);
+  useRereadOnWrite(table, refetch, fetchStartRef, Boolean(query && query.live === true));
 
   const currentKey = table ? queryResultKey(table, queryKey) : null;
   const busy = Boolean(table) && (settled.key !== currentKey || inFlight);
@@ -3232,7 +3261,7 @@ export function useDatastoreRecord(table, recordId, options) {
 
   // sc-1179 — auto-subscribe to the page-level refresh tick.
   useRefresh(refetch);
-  useRereadOnWrite(recordId ? table : null, refetch, fetchStartRef);
+  useRereadOnWrite(recordId ? table : null, refetch, fetchStartRef, options?.live === true);
 
   const currentKey =
     table && recordId ? recordResultKey(table, recordId, includeCapabilities) : null;
@@ -4146,7 +4175,7 @@ export function useDatastoreMutation(table) {
     } catch (err) {
       throw toDatastoreError(err);
     }
-    announceTableWrite(t);
+    announceTableChange(t, { local: true });
     return result;
   }, []);
 

package/dist/index.d.ts

@@ -1099,6 +1099,11 @@ export interface Query {
    * that row. Gate a row's Edit / Delete on it.
    */
   includeCapabilities?: boolean;
+  /**
+   * Re-read when anyone else changes the table, paced like a write and keeping
+   * the rows on screen. For lists other people change; never poll by hand.
+   */
+  live?: boolean;
 }
 
 /**
@@ -1148,6 +1153,11 @@ export interface FigureOptions {
   filter?:
     | Query["filter"]
     | Array<{ column: string; operator: string; value?: unknown; valueMode?: string }>;
+  /**
+   * Re-read when anyone else changes the table, paced like a write and keeping
+   * the figure on screen. Never poll by hand.
+   */
+  live?: boolean;
 }
 
 export interface FigureResult {
@@ -1180,6 +1190,8 @@ export interface AggregateBucketSpec {
   /** A plain number column to add up per bucket. */
   sumColumn?: string;
   filter?: FigureOptions["filter"];
+  /** Re-read when anyone else changes the table. */
+  live?: boolean;
 }
 
 export interface AggregateGroupSpec {
@@ -1192,6 +1204,8 @@ export interface AggregateGroupSpec {
   order?: "count:desc" | "count:asc" | "sum:desc" | "sum:asc" | "group:asc" | "group:desc";
   /** 1–1000. */
   limit?: number;
+  /** Re-read when anyone else changes the table. */
+  live?: boolean;
 }
 
 export interface AggregateBucket {
@@ -1626,7 +1640,7 @@ export function useWidgetStyle(): Record<string, unknown>;
 export function useDatastoreRecord(
   tableId: string | null | undefined,
   recordId: string | null | undefined,
-  options?: { includeCapabilities?: boolean },
+  options?: { includeCapabilities?: boolean; /** Re-read when anyone else changes the table. */ live?: boolean },
 ): {
   data: unknown | null;
   loading: boolean;

package/dist/live-table.js

@@ -0,0 +1,105 @@
+// sc-14423 — what keeps a `live: true` read current. No React, so the
+// backend's end-to-end test drives this same code.
+
+/** How often a live read re-reads while no realtime stream reaches it. */
+export const LIVE_POLL_MS = 30000;
+
+const GRANTED_SCOPE = Object.freeze({ kind: "granted" });
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Calls `onChange()` whenever someone may have changed the table behind `ns`
+ * (`records(tableId)`); it carries no row, the caller re-reads.
+ *
+ * Streams the whole table through the client's shared subscription. Until
+ * that goes live, a signed-in viewer also streams their granted rows (the
+ * server refuses the whole table to a viewer who cannot read every row).
+ * While nothing streams it polls; after any gap it reports one change.
+ *
+ * @param {object} ns
+ * @param {{ tableId: string, signedIn?: boolean, onChange: () => void }} options
+ * @returns {() => void} stop
+ */
+export function watchTableChanges(ns, { tableId, signedIn = false, onChange }) {
+  const streamable = Boolean(ns && typeof ns.subscribe === "function" && UUID_RE.test(tableId || ""));
+  const statuses = new Map();
+  const releases = new Map();
+  let stopped = false;
+  let pollTimer = null;
+  let live = false;
+  let missed = false;
+  let tableWasLive = false;
+
+  const changed = () => {
+    if (!stopped) onChange();
+  };
+
+  function settle() {
+    const all = [...statuses.values()];
+    const nowLive = all.includes("live");
+    if (nowLive && !live && missed) changed();
+    if (!nowLive && (live || all.includes("fallback"))) missed = true;
+    if (nowLive) missed = false;
+    live = nowLive;
+    if (!live && all.every((s) => s === "fallback")) {
+      if (!pollTimer) pollTimer = setInterval(changed, LIVE_POLL_MS);
+    } else if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+  }
+
+  function close(name) {
+    releases.get(name)?.();
+    releases.delete(name);
+    statuses.delete(name);
+  }
+
+  function update(name, status) {
+    if (stopped || !statuses.has(name)) return;
+    statuses.set(name, status);
+    if (name === "table" && status === "live") {
+      tableWasLive = true;
+      if (statuses.has("granted")) close("granted");
+    }
+    if (name === "table" && status === "fallback" && !tableWasLive && streamable && signedIn && !statuses.has("granted")) {
+      open("granted", GRANTED_SCOPE);
+    }
+    settle();
+  }
+
+  function open(name, scope) {
+    statuses.set(name, "connecting");
+    try {
+      const release = ns.subscribe(
+        {
+          onCreated: changed,
+          onUpdated: changed,
+          onDeleted: changed,
+          onAccessGained: changed,
+          onAccessLost: changed,
+          onStatus: (s) => update(name, s),
+        },
+        scope ? { scope } : undefined,
+      );
+      if (typeof release === "function" && statuses.has(name)) releases.set(name, release);
+      else if (typeof release === "function") release();
+    } catch (_e) {
+      update(name, "fallback");
+    }
+  }
+
+  if (streamable) open("table", null);
+  else {
+    statuses.set("table", "fallback");
+    settle();
+  }
+
+  return function stop() {
+    stopped = true;
+    if (pollTimer) clearInterval(pollTimer);
+    pollTimer = null;
+    for (const release of releases.values()) release();
+    releases.clear();
+  };
+}

package/dist/stats-hooks.js

@@ -117,7 +117,7 @@ export function useDatastoreAggregate(table, spec) {
     toDatastoreError,
     fetchStartRef,
   );
-  useRereadOnWrite(table, result.refetch, fetchStartRef);
+  useRereadOnWrite(table, result.refetch, fetchStartRef, Boolean(spec && spec.live === true));
 
   const { data, ...state } = result;
   const rows = data || [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.269.1",
+  "version": "0.270.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

@@ -1351,7 +1351,8 @@ const HOOKS = [
       "keeps it in `data` with loading false while `fetching` is true; a " +
       "different table or record id resets to loading. " +
       "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
-      "for useDatastoreQuery.",
+      "for useDatastoreQuery. `{ live: true }` re-reads it when anyone else " +
+      "changes the table.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1938,7 +1939,12 @@ const HOOKS = [
       "meta.total), not just the page in `data`; null until known. A " +
       "successful useDatastoreMutation write to the table, from this widget " +
       "or any other on the screen, re-reads it on its own: never refetch or " +
-      "subscribe for your own writes.",
+      "subscribe for your own writes. Add `live: true` to the options to also " +
+      "re-read when anyone else changes the table (a pushed change, paced like " +
+      "a write; the re-read is the same permission-checked read, and keeps the " +
+      "rows on screen with loading false). Use it for lists other people " +
+      "change: queues, bookings, chat, dashboards. Never poll with setInterval " +
+      "or wire useDatastoreSubscription for that.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -1952,8 +1958,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreFigure",
-    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
-    optionalArgs: ["aggregate", "column", "filter"],
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
+    optionalArgs: ["aggregate", "column", "filter", "live"],
     description:
       "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
       "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
@@ -1968,7 +1974,8 @@ const HOOKS = [
       "or average reads up to 1000 rows, skips blank cells rather than counting " +
       "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
       "Stat widget computes its figure through this hook, so use it rather than " +
-      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+      "reducing useDatastoreQuery rows by hand. Call it once per figure. " +
+      "`live: true` re-reads it when anyone else changes the table.",
     returnShape: {
       value: "number | null",
       text: "string | null  // the formatted figure for <Stat value>",
@@ -1986,8 +1993,8 @@ const HOOKS = [
   {
     name: "useDatastoreAggregate",
     signature:
-      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
-    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit, live })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit", "live"],
     description:
       "Counts rows on the server over EVERY row the viewer can read, so it is " +
       "exact past the 1000-row page a list read returns — never group " +
@@ -2006,7 +2013,8 @@ const HOOKS = [
       "them out with a `nempty:` filter. Encrypted, array, file and relation " +
       "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
       "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
-      "table until a bound table is known.",
+      "table until a bound table is known. `live: true` re-reads it when " +
+      "anyone else changes the table.",
     returnShape: {
       buckets:
         "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
@@ -2871,6 +2879,9 @@ const HOOKS = [
     signature: "useDatastoreSubscription(tableId, handlers, options)",
     optionalArgs: ["options"],
     description:
+      "To keep a list, record, figure or aggregate current, pass `live: true` " +
+      "to its read hook instead; this hook is for acting on each change " +
+      "(a toast, a sound, merging rows yourself). " +
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
       "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
@@ -6492,7 +6503,9 @@ const CONTRACT = deepFreeze({
   //    not reach the script.
   // 1.219.0: behaviour (sc-14407) — a useDatastoreMutation write re-reads
   //    every query, record, figure and aggregate on that table, app-wide.
-  version: "1.219.0",
+  // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
+  //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
+  version: "1.220.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,