@colixsystems/widget-sdk 0.269.1 → 0.271.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,35 @@ 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.271.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.271.0 (contract 1.221.0)
+
+**Basic styling in one call.** Spread `BASIC_STYLE_SCHEMA` into `manifest.styleSchema` and call `basicStyle(style)` in the component: the five basic style fields (`background`, `textColor`, `align`, `padding`, `margin`) are declared and applied without wiring each by hand. See *Basic styling* under *Design & visual polish*.
+
+### 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)
 
@@ -3321,6 +3349,22 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 **Decide before you build:** the widget's shape (card, list, form, control), its hierarchy (the one thing the eye lands on first), its single accent moment, and its empty/loading/error look — then compose. Specific decisions make a distinctive widget; leaving them to default makes a generic one.
 
+- **Basic styling: one schema, one call.** Every generated widget offers five whole-widget style fields: `background`, `textColor`, `align`, `padding` and `margin`. Spread `BASIC_STYLE_SCHEMA` into your manifest's `styleSchema`, then apply them with `basicStyle(style)`. It returns `{ root, text }`: spread `root` on the outermost `View` (background, align as `alignItems`, per-side padding and margin) and `text` on each `Text` in a theme text colour. A field the author left unset emits nothing, so your theme-based styles show through. `appstudio-widget lint` counts the call as reading all five. When `submit_widget_source` or the Studio's widget builder publishes a widget that calls `basicStyle()`, any of the five its manifest leaves out is declared for it.
+
+  ```jsx
+  import { View, Text, basicStyle, BASIC_STYLE_SCHEMA } from "@colixsystems/widget-sdk";
+
+  export const manifest = { /* … */ styleSchema: { ...BASIC_STYLE_SCHEMA, titleColor: { type: "color", label: "Title", ui: { group: "Title" } } } };
+
+  export default function Hero({ title, style = {} }) {
+    const basic = basicStyle(style);
+    return (
+      <View style={[styles.root, basic.root]}>
+        <Text style={[styles.title, basic.text, style.titleColor && { color: style.titleColor }]}>{title}</Text>
+      </View>
+    );
+  }
+  ```
 - **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
 - **Style text by its ROLE, not by inventing a size and weight.** `theme.typography.roles` carries the workspace's type scale as six semantic tiers — `display`, `title`, `subtitle`, `body`, `caption`, `overline` — each already resolved to a `fontSize`, `fontWeight`, `fontStyle`, `lineHeight` (a MULTIPLE of the size), `letterSpacing`, `textTransform` and a `colorToken`. Pick the tier the text IS, rather than choosing `fontSize: 16, fontWeight: "600"` yourself: your widget's section title is `title`, each card or row title is `subtitle`, running text is `body`, timestamps and helper text are `caption`, a small kicker or column label is `overline`, and a headline stat is `display`. This is what stops one widget rendering a subtitle bold while the widget beside it renders one italic, and it lets the workspace re-tune every subtitle in the app from Theme Settings in one edit. **Two tokens need converting rather than copying** — `lineHeight` is a multiple (React Native wants absolute pixels, so the raw `1.15` gives you a one-pixel line box) and `colorToken` names a colour rather than being one:

package/dist/basic-style.js

@@ -0,0 +1,37 @@
+// The five style fields every generated widget declares, in one call: spread
+// BASIC_STYLE_SCHEMA into `manifest.styleSchema`, apply `basicStyle(style)`.
+// Platform-free, so the web and native entries export this one module.
+
+import { CONTRACT } from "./contract.js";
+import { spacingOverlay } from "./card-style.js";
+
+export const BASIC_STYLE_SCHEMA = CONTRACT.basicStyleSchema;
+
+const ALIGN_ITEMS = Object.freeze({
+  left: "flex-start",
+  center: "center",
+  right: "flex-end",
+});
+
+/**
+ * The basic style fields as React Native styles. Each is emitted only when the
+ * author set it, so the widget's own theme-based styles show through.
+ *
+ * @param {object} [style] the widget's `props.style`
+ * @returns {{ root: object, text: object|null }} `root` for the outermost
+ *   View (backgroundColor, alignItems, padding, margin); `text` (`{ color }`)
+ *   for each Text coloured by a theme text token.
+ */
+export function basicStyle(style) {
+  const s = style || {};
+  const alignItems = ALIGN_ITEMS[s.align];
+  return {
+    root: {
+      ...(s.background ? { backgroundColor: s.background } : null),
+      ...(alignItems ? { alignItems } : null),
+      ...spacingOverlay(s.padding, "padding"),
+      ...spacingOverlay(s.margin, "margin"),
+    },
+    text: s.textColor ? { color: s.textColor } : null,
+  };
+}

package/dist/contract.cjs

@@ -389,6 +389,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1354,7 +1386,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 +1974,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 +1993,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 +2009,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 +2028,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 +2048,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 +2914,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 +6538,11 @@ 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.
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  version: "1.221.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6520,6 +6567,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/contract.js

@@ -386,6 +386,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1351,7 +1383,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 +1971,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 +1990,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 +2006,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 +2025,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 +2045,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 +2911,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 +6535,11 @@ 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.
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  version: "1.221.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6517,6 +6564,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

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;
@@ -5562,6 +5576,27 @@ export function roleColor(tokens: any, colors: any): string | undefined;
  */
 export function textRoleStyle(role: TextRole | string, typography: any, colors?: any): Record<string, any>;
 
+/**
+ * The five style fields every generated widget declares — `background`,
+ * `textColor`, `align`, `padding` and `margin` — as styleSchema entries.
+ * Spread it into `manifest.styleSchema`; `basicStyle()` applies it.
+ */
+export const BASIC_STYLE_SCHEMA: Readonly<WidgetPropertySchema>;
+/**
+ * The basic style fields as React Native styles, each only when set. Spread
+ * `root` on the outermost View and `text` on each Text in a theme text colour.
+ *
+ * @example
+ *   const basic = basicStyle(style);
+ *   <View style={[styles.root, basic.root]}>
+ *     <Text style={[styles.title, basic.text]}>{title}</Text>
+ *   </View>
+ */
+export function basicStyle(style?: Record<string, any> | null): {
+  root: Record<string, any>;
+  text: { color: string } | null;
+};
+
 // ----------------------------------------------------- formatted content
 // sc-6970 — widgets have no HTML path: they render through React Native
 // primitives, which have no `dangerouslySetInnerHTML` on either host. Content

package/dist/index.js

@@ -268,6 +268,8 @@ export {
   gradientProps,
   cardGradientProps,
 } from "./card-style.js";
+// The five style fields every generated widget declares, in one call.
+export { BASIC_STYLE_SCHEMA, basicStyle } from "./basic-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
 export { Button, IconButton, BUTTON_VARIANTS } from "./button.js";
 export {

package/dist/index.native.js

@@ -261,6 +261,8 @@ export {
   gradientProps,
   cardGradientProps,
 } from "./card-style.js";
+// The five style fields every generated widget declares, in one call.
+export { BASIC_STYLE_SCHEMA, basicStyle } from "./basic-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
 export { Button, IconButton, BUTTON_VARIANTS } from "./button.native.js";
 export {

package/dist/linter.cjs

@@ -1946,11 +1946,15 @@ function lintStyleWiring(manifest, files) {
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
     .join("\n");
+  const appliedByHelper = callsBasicStyle(sources)
+    ? _WHOLE_WIDGET_STYLE_FIELDS
+    : new Set();
   const findings = [];
   for (const field of Object.keys(schema)) {
     // A key that is not a bare identifier cannot be scanned by name; the
     // manifest validator rejects those anyway.
     if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) continue;
+    if (appliedByHelper.has(field)) continue;
     if (new RegExp(`\\b${field}\\b`).test(code)) continue;
     findings.push({
       rule: "style-field-unread",
@@ -1961,7 +1965,8 @@ function lintStyleWiring(manifest, files) {
         `— per instance, and app-wide under Design -> Widget appearance — ` +
         `moves nothing. Read it from props.style and apply it ONLY when ` +
         `set, so the theme still shows through while the author has chosen ` +
-        `none. If it is not styleable, drop it from styleSchema instead.`,
+        `none. If it is not styleable, drop it from styleSchema instead.` +
+        (_WHOLE_WIDGET_STYLE_FIELDS.has(field) ? _BASIC_STYLE_FIX : ""),
       line: 0,
       snippet: field,
     });
@@ -1970,6 +1975,26 @@ function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+const _BASIC_STYLE_CALL = /\bbasicStyle\s*\(/;
+
+const _BASIC_STYLE_FIX =
+  ` The one-line fix for every basic field: basicStyle(props.style) from ` +
+  `@colixsystems/widget-sdk — spread its .root on the outermost View and ` +
+  `its .text on each Text in a theme text colour.`;
+
+/**
+ * Whether the bundle calls `basicStyle()`, which applies every basic style
+ * field (`CONTRACT.basicStyleSchema`) in one call.
+ *
+ * @param {object|string[]|string} files bundle sources, as `lintStyleWiring` takes them
+ * @returns {boolean}
+ */
+function callsBasicStyle(files) {
+  return _bundleSources(files).some((s) =>
+    _BASIC_STYLE_CALL.test(_stripNonCode(s)),
+  );
+}
+
 // sc-7799 — a group name that groups everything defeats the rule: one
 // catch-all fieldset reads exactly like the flat list it replaced.
 const _GENERIC_STYLE_GROUPS = new Set([
@@ -1982,16 +2007,9 @@ const _GENERIC_STYLE_GROUPS = new Set([
 ]);
 
 // The five the basic-style gate mandates; they restyle the widget as a whole.
-// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
-// — a mandated field missing here reads as per-element coverage the widget does
-// not have, which silently retires this rule for EVERY generated widget.
-const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
-  "background",
-  "textColor",
-  "align",
-  "padding",
-  "margin",
-]);
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set(
+  Object.keys(CONTRACT.basicStyleSchema),
+);
 
 // A second element an author would style apart from the text. Pressable and
 // Button are deliberately absent: a touch target wrapping the only label is
@@ -2385,6 +2403,7 @@ function lintSource(source, options) {
 module.exports = {
   lintSource,
   lintStyleWiring,
+  callsBasicStyle,
   lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,

package/dist/linter.js

@@ -2009,11 +2009,15 @@ export function lintStyleWiring(manifest, files) {
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
     .join("\n");
+  const appliedByHelper = callsBasicStyle(sources)
+    ? _WHOLE_WIDGET_STYLE_FIELDS
+    : new Set();
   const findings = [];
   for (const field of Object.keys(schema)) {
     // A key that is not a bare identifier cannot be scanned by name; the
     // manifest validator rejects those anyway.
     if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) continue;
+    if (appliedByHelper.has(field)) continue;
     if (new RegExp(`\\b${field}\\b`).test(code)) continue;
     findings.push({
       rule: "style-field-unread",
@@ -2024,7 +2028,8 @@ export function lintStyleWiring(manifest, files) {
         `— per instance, and app-wide under Design -> Widget appearance — ` +
         `moves nothing. Read it from props.style and apply it ONLY when ` +
         `set, so the theme still shows through while the author has chosen ` +
-        `none. If it is not styleable, drop it from styleSchema instead.`,
+        `none. If it is not styleable, drop it from styleSchema instead.` +
+        (_WHOLE_WIDGET_STYLE_FIELDS.has(field) ? _BASIC_STYLE_FIX : ""),
       line: 0,
       snippet: field,
     });
@@ -2033,6 +2038,26 @@ export function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+const _BASIC_STYLE_CALL = /\bbasicStyle\s*\(/;
+
+const _BASIC_STYLE_FIX =
+  ` The one-line fix for every basic field: basicStyle(props.style) from ` +
+  `@colixsystems/widget-sdk — spread its .root on the outermost View and ` +
+  `its .text on each Text in a theme text colour.`;
+
+/**
+ * Whether the bundle calls `basicStyle()`, which applies every basic style
+ * field (`CONTRACT.basicStyleSchema`) in one call.
+ *
+ * @param {object|string[]|string} files bundle sources, as `lintStyleWiring` takes them
+ * @returns {boolean}
+ */
+export function callsBasicStyle(files) {
+  return _bundleSources(files).some((s) =>
+    _BASIC_STYLE_CALL.test(_stripNonCode(s)),
+  );
+}
+
 // sc-7799 — a group name that groups everything defeats the rule: one
 // catch-all fieldset reads exactly like the flat list it replaced.
 const _GENERIC_STYLE_GROUPS = new Set([
@@ -2045,16 +2070,9 @@ const _GENERIC_STYLE_GROUPS = new Set([
 ]);
 
 // The five the basic-style gate mandates; they restyle the widget as a whole.
-// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
-// — a mandated field missing here reads as per-element coverage the widget does
-// not have, which silently retires this rule for EVERY generated widget.
-const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
-  "background",
-  "textColor",
-  "align",
-  "padding",
-  "margin",
-]);
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set(
+  Object.keys(CONTRACT.basicStyleSchema),
+);
 
 // A second element an author would style apart from the text. Pressable and
 // Button are deliberately absent: a touch target wrapping the only label is

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.271.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

@@ -386,6 +386,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1351,7 +1383,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 +1971,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 +1990,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 +2006,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 +2025,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 +2045,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 +2911,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 +6535,11 @@ 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.
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  version: "1.221.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6517,6 +6564,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.