@colixsystems/widget-sdk 0.107.0 → 0.109.0

package/README.md

@@ -17,7 +17,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
-| **CORE** | `useTheme()` | `{ colors, elevation, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
+| **CORE** | `useTheme()` | `{ colors, elevation, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`) and `loader`, the spinner colour for your own loading state. `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
 | **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
@@ -46,6 +46,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options?)` | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `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?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "is this caller signed in AND permitted", reading the same table-ACL answer the write endpoint enforces. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
@@ -68,7 +69,20 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.107.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.108.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.108.0 (contract 1.82.0)
+
+**`themeTokens.colors` gains `loader` — the surface's spinner colour (sc-6095).** A widget that drew its own loading state had no token for it, so it reached for a literal grey. On a dark theme that grey vanished into the background and the widget looked frozen rather than busy — the same bug the host's own loading holds had.
+
+`loader` tracks `onSurfaceMuted`, which means it rides the existing REQ-THEME-SURFACE derivation: it flips light on a dark page background, and it re-derives for a container that paints its own dark fill, exactly like the text colours around it. So reading it is enough — there is nothing to branch on:
+
+```js
+const t = useTheme();
+if (loading) return <ActivityIndicator color={t.colors.loader} />;
+```
+
+The workspace's *Design → Loading Indicator* panel can override it app-wide; unset, it stays derived. Additive — the full `colors` shape is now `{ primary, onPrimary, primarySoft, onPrimarySoft, primaryStrong, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, loader, danger, success, warning, info }`.
 
 ### What's new in 0.107.0 (contract 1.81.0)
 
@@ -388,7 +402,7 @@ Additive — one new hook, one new optional device capability, one new error cla
 
 - **The workspace theme now reaches the elements an app is built from.** Three things that used to be unreachable are now themeable: an element inside YOUR widget, the structural card container a page is made of, and any style field whose name the platform does not know. For a widget author the practical change is that **your `styleSchema` is the contract**: every field you declare becomes a knob the workspace owner can set once for the whole app, so declare the fields that describe your widget's appearance and give them clear `label`s and `ui.group`s — those labels are what the owner reads.
 - **A field name you invented is as reachable as a canonical one.** A theme may carry values keyed by your widget's manifest id and then by your own field names, so `panelFill` is adjustable app-wide exactly like `cardBackground`. Separately, the unambiguous card names (`cardBackground`, `cardBorderColor`, `cardRadius`, `cardPadding`, `cardGradient`) bind by NAME to any widget that declares them, so naming a genuine card surface canonically opts it into the workspace's Cards controls for free.
-- **`useTheme().colors` describes the surface your widget SITS ON, not the page.** A layout container that paints its own background re-derives the surface roles for everything inside it, so reading `colors.onSurface` for your text is readable whether your widget lands on the page, in a dark hero, or in a light card nested inside that hero. Nothing to opt into.
+- **`useTheme().colors` describes the surface your widget SITS ON, not the page.** A layout container that paints its own background re-derives the surface roles for everything inside it, so reading `colors.onSurface` for your text is readable whether your widget lands on the page, in a dark hero, or in a light card nested inside that hero. `colors.loader` is that same surface's spinner colour — paint your loading state with it rather than a literal grey. Nothing to opt into.
 - **Precedence, unchanged in spirit.** Contract default → workspace palette → component scope → per-widget-type value → the app author's per-instance `props.style`. Most specific wins, and the Properties Panel is still the final word. Your widget reads `props.style` exactly as before and never learns which layer supplied a value.
 - **A colour may carry OPACITY.** `isHexColor` accepts the 8-digit `#RRGGBBAA` form alongside 3 and 6 digits, so a theme colour with an alpha reaches `useTheme()` with its transparency intact. It used to be rejected and the host dropped the key outright, which is why a translucent page background never reached the dark-surface derivation and every panel fell back to white.
 - **The colour maths ignores alpha, on purpose.** `hexChannels` reads the R/G/B pair and skips any alpha, so contrast, readable text and the derived accent tints reason about the opaque colour. None of them can composite without knowing the backdrop, which a token table does not have — so transparency lives in the VALUE your widget renders, not in the decision about whether that colour reads as light or dark.

package/dist/contract.cjs

@@ -64,6 +64,11 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     onSurface: "#111827",
     surfaceMuted: "#f8fafc",
     onSurfaceMuted: "#475569",
+    // sc-6095: the colour a loading spinner is painted with. A spinner is a
+    // muted foreground mark on the surface it sits on, so it tracks
+    // `onSurfaceMuted`, which deriveSurfaceTokens already flips for a dark
+    // background — so a dark theme gets a visible spinner with no new maths.
+    loader: "#475569",
     border: "#e2e8f0",
     danger: "#dc2626",
     success: "#059669",
@@ -457,12 +462,13 @@ const HOOKS = [
     signature: "useTheme()",
     returnShape: {
       colors:
-        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info } — " +
+        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, loader, danger, success, warning, info } — " +
         "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
-        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "onSurfaceMuted / border / loader) describes the surface your widget SITS ON, not the " +
         "page: a container painting its own background re-derives them for its " +
         "subtree. Read them and your text is readable wherever the widget lands; " +
-        "there is nothing to opt into.",
+        "there is nothing to opt into. `loader` is that surface's spinner colour " +
+        "(sc-6095) — paint your own loading state with it rather than a literal grey.",
       spacing: "{ xs, sm, md, lg, xl }",
       spacingScale:
         "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
@@ -1463,7 +1469,15 @@ const HOOKS = [
       "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
       "Reads the same datastore.read scope as useDatastoreQuery — declare " +
       "datastore.read for the table you subscribe to. Pair with " +
-      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+      "useDatastoreQuery for the initial load and merge the streamed " +
+      "envelopes. `options.scope` narrows the subscription: " +
+      "{ kind: 'record', record_id } streams one record, and " +
+      "{ kind: 'parent', relation_column, record_id } streams the rows whose " +
+      "RELATION column points at that parent — the only way to subscribe to a " +
+      "table governed by per-record grants, since a scope-less subscribe must " +
+      "prove read-every-row. A `parent` scope requires the column be an " +
+      "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }.",
     returnShape: {
       status:
         "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
@@ -3326,7 +3340,29 @@ const CONTRACT = deepFreeze({
   //    through the already-vetted react-native-svg and carries no native
   //    module of its own, so it is host-shimmed on web and pinned in the
   //    export like date-fns. No existing entry changed shape.
-  version: "1.81.0",
+  //
+  // 1.82.0: additive (sc-6095) — `themeTokens.colors` gains `loader`, the
+  //    colour a loading spinner is painted with, and `deriveSurfaceTokens`
+  //    returns it alongside the surface/text/border set. A spinner is a muted
+  //    foreground mark on the surface it sits on, so it tracks `onSurfaceMuted`
+  //    and inherits that set's dark-background flip — which is what makes a
+  //    dark theme's spinner visible instead of grey-on-grey.
+  //    `useTheme().colors.loader` is the value a widget reads for its own
+  //    loading state; both hosts paint their chrome spinners from the same key.
+  //
+  // 1.83.0: additive (sc-6270) — `useDatastoreSubscription` gains
+  //    `options.scope`, narrowing a subscription from the whole table to one
+  //    record (`{ kind: "record", record_id }`) or to a parent's inheriting
+  //    children (`{ kind: "parent", relation_column, record_id }`). Without it
+  //    a table whose rows are governed by PER-RECORD grants could not stream
+  //    at all: the plane fans one envelope to every subscriber, so a
+  //    scope-less subscribe must prove read-every-row (sc-4311) and a channel
+  //    member never can. A scoped subscribe is gated on the per-record read
+  //    check instead — the same predicate REST applies per row — and `parent`
+  //    additionally requires an `inheritAcl` RELATION column, which is what
+  //    makes the stream a strict subset of what `list()` already returns.
+  //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
+  version: "1.83.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3511,7 +3547,7 @@ const DARK_SURFACE_TEXT = Object.freeze({
  * page, which is in turn what lets a built app follow its theme instead of
  * carrying a baked-in hex for every heading.
  *
- * Returns all five keys together, never a subset: layering a dark card's text
+ * Returns all six keys together, never a subset: layering a dark card's text
  * colour over a light ancestor's surface is exactly how light-on-light happens.
  * `null` only when the colour is unusable, letting the caller keep what it had.
  */
@@ -3528,6 +3564,7 @@ function deriveSurfaceTokens(backgroundColor) {
       surfaceMuted: base.surfaceMuted,
       onSurface: base.onSurface,
       onSurfaceMuted: base.onSurfaceMuted,
+      loader: base.loader,
       border: base.border,
     };
   }
@@ -3536,6 +3573,7 @@ function deriveSurfaceTokens(backgroundColor) {
     surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
     onSurface: DARK_SURFACE_TEXT.onSurface,
     onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    loader: DARK_SURFACE_TEXT.onSurfaceMuted,
     border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
   };
 }

package/dist/contract.js

@@ -64,6 +64,11 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     onSurface: "#111827",
     surfaceMuted: "#f8fafc",
     onSurfaceMuted: "#475569",
+    // sc-6095: the colour a loading spinner is painted with. A spinner is a
+    // muted foreground mark on the surface it sits on, so it tracks
+    // `onSurfaceMuted`, which deriveSurfaceTokens already flips for a dark
+    // background — so a dark theme gets a visible spinner with no new maths.
+    loader: "#475569",
     border: "#e2e8f0",
     danger: "#dc2626",
     success: "#059669",
@@ -457,12 +462,13 @@ const HOOKS = [
     signature: "useTheme()",
     returnShape: {
       colors:
-        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info } — " +
+        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, loader, danger, success, warning, info } — " +
         "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
-        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "onSurfaceMuted / border / loader) describes the surface your widget SITS ON, not the " +
         "page: a container painting its own background re-derives them for its " +
         "subtree. Read them and your text is readable wherever the widget lands; " +
-        "there is nothing to opt into.",
+        "there is nothing to opt into. `loader` is that surface's spinner colour " +
+        "(sc-6095) — paint your own loading state with it rather than a literal grey.",
       spacing: "{ xs, sm, md, lg, xl }",
       spacingScale:
         "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
@@ -1463,7 +1469,15 @@ const HOOKS = [
       "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
       "Reads the same datastore.read scope as useDatastoreQuery — declare " +
       "datastore.read for the table you subscribe to. Pair with " +
-      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+      "useDatastoreQuery for the initial load and merge the streamed " +
+      "envelopes. `options.scope` narrows the subscription: " +
+      "{ kind: 'record', record_id } streams one record, and " +
+      "{ kind: 'parent', relation_column, record_id } streams the rows whose " +
+      "RELATION column points at that parent — the only way to subscribe to a " +
+      "table governed by per-record grants, since a scope-less subscribe must " +
+      "prove read-every-row. A `parent` scope requires the column be an " +
+      "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }.",
     returnShape: {
       status:
         "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
@@ -3326,7 +3340,29 @@ const CONTRACT = deepFreeze({
   //    through the already-vetted react-native-svg and carries no native
   //    module of its own, so it is host-shimmed on web and pinned in the
   //    export like date-fns. No existing entry changed shape.
-  version: "1.81.0",
+  //
+  // 1.82.0: additive (sc-6095) — `themeTokens.colors` gains `loader`, the
+  //    colour a loading spinner is painted with, and `deriveSurfaceTokens`
+  //    returns it alongside the surface/text/border set. A spinner is a muted
+  //    foreground mark on the surface it sits on, so it tracks `onSurfaceMuted`
+  //    and inherits that set's dark-background flip — which is what makes a
+  //    dark theme's spinner visible instead of grey-on-grey.
+  //    `useTheme().colors.loader` is the value a widget reads for its own
+  //    loading state; both hosts paint their chrome spinners from the same key.
+  //
+  // 1.83.0: additive (sc-6270) — `useDatastoreSubscription` gains
+  //    `options.scope`, narrowing a subscription from the whole table to one
+  //    record (`{ kind: "record", record_id }`) or to a parent's inheriting
+  //    children (`{ kind: "parent", relation_column, record_id }`). Without it
+  //    a table whose rows are governed by PER-RECORD grants could not stream
+  //    at all: the plane fans one envelope to every subscriber, so a
+  //    scope-less subscribe must prove read-every-row (sc-4311) and a channel
+  //    member never can. A scoped subscribe is gated on the per-record read
+  //    check instead — the same predicate REST applies per row — and `parent`
+  //    additionally requires an `inheritAcl` RELATION column, which is what
+  //    makes the stream a strict subset of what `list()` already returns.
+  //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
+  version: "1.83.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3511,7 +3547,7 @@ const DARK_SURFACE_TEXT = Object.freeze({
  * page, which is in turn what lets a built app follow its theme instead of
  * carrying a baked-in hex for every heading.
  *
- * Returns all five keys together, never a subset: layering a dark card's text
+ * Returns all six keys together, never a subset: layering a dark card's text
  * colour over a light ancestor's surface is exactly how light-on-light happens.
  * `null` only when the colour is unusable, letting the caller keep what it had.
  */
@@ -3528,6 +3564,7 @@ function deriveSurfaceTokens(backgroundColor) {
       surfaceMuted: base.surfaceMuted,
       onSurface: base.onSurface,
       onSurfaceMuted: base.onSurfaceMuted,
+      loader: base.loader,
       border: base.border,
     };
   }
@@ -3536,6 +3573,7 @@ function deriveSurfaceTokens(backgroundColor) {
     surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
     onSurface: DARK_SURFACE_TEXT.onSurface,
     onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    loader: DARK_SURFACE_TEXT.onSurfaceMuted,
     border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
   };
 }

package/dist/hooks.js

@@ -2482,7 +2482,9 @@ export function useCanWrite(tableId, options) {
  *
  * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
  * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
- * @param {{ fallbackAfterMs?: number }} [options]
+ * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent", relation_column?: string, record_id: string } }} [options]
+ *   `scope` narrows the stream below whole-table — required for a table
+ *   governed by per-record grants. Re-subscribes on its VALUES, not identity.
  * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
  */
 export function useDatastoreSubscription(table, handlers, options) {
@@ -2510,7 +2512,23 @@ export function useDatastoreSubscription(table, handlers, options) {
       ? options.fallbackAfterMs
       : undefined;
 
+  // sc-6270: a scope narrows the subscription to one record or to a parent's
+  // inheriting children. Authors pass a fresh object literal every render, so
+  // the effect keys on the scope's VALUES — depending on its identity would
+  // tear down and reopen the socket on each render.
+  const scope = options && options.scope ? options.scope : null;
+  const scopeKey = scope
+    ? [scope.kind, scope.relation_column, scope.record_id]
+        .map((part) => part || "")
+        .join("|")
+    : "";
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+
   useEffect(() => {
+    // Re-scoping starts a new connection, so a stale "live" from the previous
+    // scope must not mask the gap while it opens.
+    setStatus("connecting");
     if (!table || typeof recordsRef.current !== "function") {
       setStatus("fallback");
       return undefined;
@@ -2527,6 +2545,9 @@ export function useDatastoreSubscription(table, handlers, options) {
       setStatus("fallback");
       return undefined;
     }
+    const subscribeOptions = {};
+    if (fallbackAfterMs != null) subscribeOptions.fallbackAfterMs = fallbackAfterMs;
+    if (scopeRef.current) subscribeOptions.scope = scopeRef.current;
     const stop = ns.subscribe(
       {
         onCreated: (r) => handlersRef.current?.onCreated?.(r),
@@ -2534,13 +2555,13 @@ export function useDatastoreSubscription(table, handlers, options) {
         onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
         onStatus: (s) => setStatus(s),
       },
-      fallbackAfterMs != null ? { fallbackAfterMs } : undefined,
+      Object.keys(subscribeOptions).length > 0 ? subscribeOptions : undefined,
     );
     return () => {
       if (typeof stop === "function") stop();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [table, fallbackAfterMs]);
+  }, [table, fallbackAfterMs, scopeKey]);
 
   return { status };
 }

package/dist/index.d.ts

@@ -1137,8 +1137,16 @@ export interface DatastoreSubscriptionHandlers {
   onDeleted?: (record: Record<string, unknown>) => void;
 }
 
+// sc-6270: see SubscriptionScope in @colixsystems/datastore-client. A scoped
+// subscribe is gated on the per-record read check instead of read-every-row,
+// which is what lets a per-record-ACL table stream at all.
+export type DatastoreSubscriptionScope =
+  | { kind: "record"; record_id: string }
+  | { kind: "parent"; relation_column: string; record_id: string };
+
 export interface DatastoreSubscriptionOptions {
   fallbackAfterMs?: number;
+  scope?: DatastoreSubscriptionScope;
 }
 
 /**
@@ -1148,6 +1156,10 @@ export interface DatastoreSubscriptionOptions {
  * is `"fallback"` (no socket support, ACL-rejected, or connect timed out) run
  * REST polling instead. Never throws — degrades to `{ status: "fallback" }` on
  * a host whose datastore client predates realtime.
+ *
+ * `options.scope` narrows the stream to one record or to a parent's
+ * inheriting children; re-subscribes when the scope's values change, not on
+ * every render.
  */
 export function useDatastoreSubscription(
   tableId: string | null | undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.107.0",
+  "version": "0.109.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",