@colixsystems/widget-sdk 0.268.0 → 0.269.1

package/README.md

@@ -58,7 +58,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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. |
 | **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:*`. **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** | `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** | `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) |
@@ -86,7 +86,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.268.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.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**.
+
+### What's new in 0.269.1 (contract 1.219.0)
+
+**Re-reads after a write are paced, and a write loop is refused.** A run of writes re-reads each widget at most once a second, and always once more after the last write; a reader that fetched on its own after the write is not re-read again. So a bulk loop of 500 saves costs each reader about one read a second, not 500, and the list still ends on the last save. An effect that saves and re-runs on the data it reads (or has no dependency list) would now save forever, because every save re-reads that data: keep the rows it already saved in a ref or a Set and return early, or save from the user's action. The publish checker refuses such an effect (`widget.writeLoopEffect`).
+
+### What's new in 0.269.0 (contract 1.219.0)
+
+**A write refreshes every widget that shows the table.** After a successful `create`, `update` or `delete` through `useDatastoreMutation`, every `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreFigure` and `useDatastoreAggregate` on the same table re-reads itself, in the widget that wrote and in every other widget on the screen, on the web Player and in the native app alike. Drop the `refetch()` you called after your own writes and any subscription you wired for them; `useDatastoreSubscription` stays for changes other people make. Widgets must address the table the same way (its id, as a `tableRef` property binds it) for the refresh to reach them.
+
+### What's new in 0.268.1 (contract 1.218.0)
+
+**The web `DateTimePicker`'s hour and minute columns no longer look broken.** The browser drew its scrollbar inside each narrow column, which cut the chosen hour and minute off on one side. The columns now hide the scrollbar and fade their top and bottom edges to show they scroll. The keyboard focus ring is drawn in full, and a row reached with the arrow keys stops clear of the fade. No API change; native keeps the operating system's picker.
 
 ### What's new in 0.268.0 (contract 1.218.0)
 

package/dist/contract.cjs

@@ -1938,7 +1938,10 @@ const HOOKS = [
       "enforce, computed for the whole page in one lookup. Gate a row's " +
       "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
       "`total` is how many rows the query matches in all (the envelope's " +
-      "meta.total), not just the page in `data`; null until known.",
+      "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.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -2212,6 +2215,15 @@ const HOOKS = [
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
+    description:
+      "Creates, updates (partial) and deletes rows. A successful write re-reads " +
+      "every useDatastoreQuery, useDatastoreRecord, useDatastoreFigure and " +
+      "useDatastoreAggregate on the same table reference, in every widget on " +
+      "the screen, so no widget calls refetch() or subscribes for it. Readers " +
+      "must name the table the same way (its id, as a tableRef property binds it). " +
+      "A run of writes re-reads each reader at most once a second, always once " +
+      "more after the last. Never write from a useEffect that re-runs on the data " +
+      "it reads unless a ref or Set marks each row as already written: it loops.",
     returnShape: {
       create:
         "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
@@ -6481,7 +6493,9 @@ const CONTRACT = deepFreeze({
   // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
   //    `useAction().available` turns false when the server says a run would
   //    not reach the script.
-  version: "1.218.0",
+  // 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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1935,7 +1935,10 @@ const HOOKS = [
       "enforce, computed for the whole page in one lookup. Gate a row's " +
       "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
       "`total` is how many rows the query matches in all (the envelope's " +
-      "meta.total), not just the page in `data`; null until known.",
+      "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.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -2209,6 +2212,15 @@ const HOOKS = [
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
+    description:
+      "Creates, updates (partial) and deletes rows. A successful write re-reads " +
+      "every useDatastoreQuery, useDatastoreRecord, useDatastoreFigure and " +
+      "useDatastoreAggregate on the same table reference, in every widget on " +
+      "the screen, so no widget calls refetch() or subscribes for it. Readers " +
+      "must name the table the same way (its id, as a tableRef property binds it). " +
+      "A run of writes re-reads each reader at most once a second, always once " +
+      "more after the last. Never write from a useEffect that re-runs on the data " +
+      "it reads unless a ref or Set marks each row as already written: it loops.",
     returnShape: {
       create:
         "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
@@ -6478,7 +6490,9 @@ const CONTRACT = deepFreeze({
   // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
   //    `useAction().available` turns false when the server says a run would
   //    not reach the script.
-  version: "1.218.0",
+  // 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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datetimepicker-time-columns.js

@@ -14,6 +14,9 @@ const COLUMN_WIDTH = 64;
 const HOURS = Array.from({ length: 24 }, (_, i) => i);
 const MINUTES = Array.from({ length: 60 }, (_, i) => i);
 const LIST_KEYS = ["ArrowDown", "ArrowUp", "Home", "End"];
+// Fades the edges in place of a scrollbar, which would clip cells.
+const FADE = 24;
+const EDGE_FADE = `linear-gradient(to bottom, transparent, #000 ${FADE}px, #000 calc(100% - ${FADE}px), transparent)`;
 
 /** @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any}} rn */
 export function makeTimeColumns(rn) {
@@ -27,7 +30,7 @@ export function makeTimeColumns(rn) {
     React.useEffect(() => {
       if (!mounted.current) {
         mounted.current = true;
-        const top = values.indexOf(chosen) * (ITEM_HEIGHT + ITEM_GAP) - (height - ITEM_HEIGHT) / 2;
+        const top = FADE + values.indexOf(chosen) * (ITEM_HEIGHT + ITEM_GAP) - (height - ITEM_HEIGHT) / 2;
         if (scroller.current && typeof scroller.current.scrollTo === "function") {
           scroller.current.scrollTo({ y: Math.max(0, top), animated: false });
         }
@@ -76,7 +79,7 @@ export function makeTimeColumns(rn) {
           "aria-selected": selected,
           disabled: option.disabled,
           testID: testID ? `${testID}-${field}-${twoDigits(option.value)}` : undefined,
-          style: cellStyle(t, { selected, current: false, disabled: option.disabled, width: COLUMN_WIDTH, height: ITEM_HEIGHT, round: true }),
+          style: cellStyle(t, { selected, current: false, disabled: option.disabled, width: COLUMN_WIDTH - 2 * ITEM_GAP, height: ITEM_HEIGHT, round: true }),
         },
         h(Text, { style: cellText(t, { selected }) }, twoDigits(option.value)),
       );
@@ -87,7 +90,15 @@ export function makeTimeColumns(rn) {
       h(Text, { "aria-hidden": true, style: { textAlign: "center", fontFamily: t.fontFamily, fontSize: t.helperSize, fontWeight: "500", color: t.helperColor } }, name),
       h(
         ScrollView,
-        { ref: scroller, role: "listbox", accessibilityLabel: name, style: { height }, contentContainerStyle: { gap: ITEM_GAP, paddingVertical: ITEM_GAP } },
+        {
+          ref: scroller,
+          role: "listbox",
+          accessibilityLabel: name,
+          showsVerticalScrollIndicator: false,
+          style: { height, maskImage: EDGE_FADE, WebkitMaskImage: EDGE_FADE, scrollPaddingBlock: FADE },
+          // The first and last rows can scroll clear of the fade.
+          contentContainerStyle: { gap: ITEM_GAP, paddingVertical: FADE, paddingHorizontal: ITEM_GAP },
+        },
         ...options.map(item),
       ),
     );

package/dist/hooks.js

@@ -2888,6 +2888,84 @@ function serializeQuery(query) {
 }
 
 const queryResultKey = (table, queryKey) => JSON.stringify([table, queryKey]);
+
+// sc-14407 — every widget of a running app shares this module (the web host
+// hands custom widgets its own SDK; the native bundle has one copy), so a
+// 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.
+const TABLE_WRITE_SETTLE_MS = 50;
+const TABLE_REREAD_INTERVAL_MS = 1000;
+const tableWrites = new Map();
+// Orders writes and fetch starts: a fetch begun after a write already has its rows.
+let readWriteOrder = 0;
+
+/** Internal: stamps the start of a reader's fetch, for useRereadOnWrite. */
+export function stampFetchStart(ref) {
+  readWriteOrder += 1;
+  ref.current = readWriteOrder;
+}
+
+function tableWritesOf(table) {
+  let entry = tableWrites.get(table);
+  if (!entry) {
+    entry = { listeners: new Set(), timer: null, lastRereadAt: -Infinity, wroteAt: 0 };
+    tableWrites.set(table, entry);
+  }
+  return entry;
+}
+
+function forgetIfIdle(table, entry) {
+  if (entry.listeners.size === 0 && !entry.timer && tableWrites.get(table) === entry) tableWrites.delete(table);
+}
+
+function rereadTable(table, entry) {
+  entry.timer = null;
+  entry.lastRereadAt = Date.now();
+  for (const listener of Array.from(entry.listeners)) {
+    try {
+      listener(entry.wroteAt);
+    } catch (_e) {
+      // A reader's failure must never reach the write that already succeeded.
+    }
+  }
+  forgetIfIdle(table, entry);
+}
+
+function announceTableWrite(table) {
+  const entry = tableWritesOf(table);
+  readWriteOrder += 1;
+  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);
+}
+
+/**
+ * Internal: shared with stats-hooks.js, not re-exported by the index. Runs
+ * `reread` after a successful useDatastoreMutation write to `table`, from any
+ * 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.
+ */
+export function useRereadOnWrite(table, reread, fetchStartRef) {
+  const rereadRef = useRef(reread);
+  rereadRef.current = reread;
+  useEffect(() => {
+    if (!table) return undefined;
+    const entry = tableWritesOf(table);
+    const listener = (wroteAt) => {
+      if (fetchStartRef && fetchStartRef.current > wroteAt) return;
+      rereadRef.current();
+    };
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+      forgetIfIdle(table, entry);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table]);
+}
 const recordResultKey = (table, recordId, includeCapabilities = false) =>
   JSON.stringify([table, recordId, includeCapabilities]);
 
@@ -2961,6 +3039,7 @@ export function useDatastoreQuery(table, query) {
   recordsRef.current = ctx.datastore.records;
 
   const runRef = useRef(0);
+  const fetchStartRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     const myRun = ++runRef.current;
@@ -2972,6 +3051,7 @@ export function useDatastoreQuery(table, query) {
       setSettled(NO_QUERY_RESULT);
       return;
     }
+    stampFetchStart(fetchStartRef);
     const key = queryResultKey(t, serializeQuery(queryRef.current));
     setInFlight(true);
     try {
@@ -3041,6 +3121,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);
 
   const currentKey = table ? queryResultKey(table, queryKey) : null;
   const busy = Boolean(table) && (settled.key !== currentKey || inFlight);
@@ -3106,6 +3187,7 @@ export function useDatastoreRecord(table, recordId, options) {
   recordsRef.current = ctx.datastore.records;
 
   const runRef = useRef(0);
+  const fetchStartRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     const myRun = ++runRef.current;
@@ -3116,6 +3198,7 @@ export function useDatastoreRecord(table, recordId, options) {
       setSettled(NO_RECORD_RESULT);
       return;
     }
+    stampFetchStart(fetchStartRef);
     const key = recordResultKey(t, id, includeCapabilitiesRef.current);
     setInFlight(true);
     try {
@@ -3149,6 +3232,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);
 
   const currentKey =
     table && recordId ? recordResultKey(table, recordId, includeCapabilities) : null;
@@ -4044,68 +4128,31 @@ export function useDatastoreMutation(table) {
   tableRef.current = table;
   recordsRef.current = ctx.datastore.records;
 
-  // Resolve records(table) lazily. Returns null when no table is bound so
-  // the callbacks reject with a clear VALIDATION error rather than letting
-  // the client's raw TypeError surface (or crashing at render).
-  const resolveNs = useCallback(() => {
+  // Resolve records(table) lazily, so an unbound widget rejects with a clear
+  // VALIDATION error instead of crashing at render. A successful write
+  // re-reads every widget showing this table (sc-14407).
+  const write = useCallback(async (verb, run) => {
     const t = tableRef.current;
-    if (!t) return null;
-    return recordsRef.current(t);
+    if (!t) {
+      throw new DatastoreError(
+        "VALIDATION",
+        `useDatastoreMutation: no table bound — set a source table before ${verb} a record.`,
+      );
+    }
+    const ns = recordsRef.current(t);
+    let result;
+    try {
+      result = await run(ns);
+    } catch (err) {
+      throw toDatastoreError(err);
+    }
+    announceTableWrite(t);
+    return result;
   }, []);
 
-  const create = useCallback(
-    async (values) => {
-      const ns = resolveNs();
-      if (!ns) {
-        throw new DatastoreError(
-          "VALIDATION",
-          "useDatastoreMutation: no table bound — set a source table before creating a record.",
-        );
-      }
-      try {
-        return await ns.create(values);
-      } catch (err) {
-        throw toDatastoreError(err);
-      }
-    },
-    [resolveNs],
-  );
-
-  const update = useCallback(
-    async (id, values) => {
-      const ns = resolveNs();
-      if (!ns) {
-        throw new DatastoreError(
-          "VALIDATION",
-          "useDatastoreMutation: no table bound — set a source table before updating a record.",
-        );
-      }
-      try {
-        return await ns.update(id, values);
-      } catch (err) {
-        throw toDatastoreError(err);
-      }
-    },
-    [resolveNs],
-  );
-
-  const del = useCallback(
-    async (id) => {
-      const ns = resolveNs();
-      if (!ns) {
-        throw new DatastoreError(
-          "VALIDATION",
-          "useDatastoreMutation: no table bound — set a source table before deleting a record.",
-        );
-      }
-      try {
-        return await ns.delete(id);
-      } catch (err) {
-        throw toDatastoreError(err);
-      }
-    },
-    [resolveNs],
-  );
+  const create = useCallback((values) => write("creating", (ns) => ns.create(values)), [write]);
+  const update = useCallback((id, values) => write("updating", (ns) => ns.update(id, values)), [write]);
+  const del = useCallback((id) => write("deleting", (ns) => ns.delete(id)), [write]);
 
   // sc-10268: one object while the methods are unchanged, so a widget can list
   // the mutation in a dependency array without re-running every render.

package/dist/stats-hooks.js

@@ -6,6 +6,8 @@ import {
   toDatastoreError,
   toDirectoryError,
   useRefresh,
+  stampFetchStart,
+  useRereadOnWrite,
   useWidgetContextOrThrow,
 } from "./hooks.js";
 
@@ -27,7 +29,7 @@ function serialize(value) {
  * keeps the previous data on screen (`fetching`); a new identity starts over
  * (`loading`). A null key is "nothing to read" and settles empty.
  */
-function useKeyedRead(read, identity, key, mapError) {
+function useKeyedRead(read, identity, key, mapError, fetchStartRef) {
   const readRef = useRef(read);
   readRef.current = read;
   const runRef = useRef(0);
@@ -42,6 +44,7 @@ function useKeyedRead(read, identity, key, mapError) {
       return;
     }
     setFetching(true);
+    if (fetchStartRef) stampFetchStart(fetchStartRef);
     try {
       const data = await readRef.current();
       if (runRef.current === myRun) setSettled({ identity, key, data, error: null });
@@ -97,6 +100,7 @@ export function useDatastoreAggregate(table, spec) {
     ? serialize(byDate ? [groupBy, bucket, from, to, sumColumn, filter] : [groupBy, sumColumn, filter, order, limit])
     : null;
   const records = ctx.datastore.records;
+  const fetchStartRef = useRef(0);
 
   const result = useKeyedRead(
     async () => {
@@ -111,7 +115,9 @@ export function useDatastoreAggregate(table, spec) {
     table ? `${table}|${byDate ? "date" : "column"}` : null,
     key,
     toDatastoreError,
+    fetchStartRef,
   );
+  useRereadOnWrite(table, result.refetch, fetchStartRef);
 
   const { data, ...state } = result;
   const rows = data || [];

package/package.json

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

@@ -1935,7 +1935,10 @@ const HOOKS = [
       "enforce, computed for the whole page in one lookup. Gate a row's " +
       "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
       "`total` is how many rows the query matches in all (the envelope's " +
-      "meta.total), not just the page in `data`; null until known.",
+      "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.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -2209,6 +2212,15 @@ const HOOKS = [
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
+    description:
+      "Creates, updates (partial) and deletes rows. A successful write re-reads " +
+      "every useDatastoreQuery, useDatastoreRecord, useDatastoreFigure and " +
+      "useDatastoreAggregate on the same table reference, in every widget on " +
+      "the screen, so no widget calls refetch() or subscribes for it. Readers " +
+      "must name the table the same way (its id, as a tableRef property binds it). " +
+      "A run of writes re-reads each reader at most once a second, always once " +
+      "more after the last. Never write from a useEffect that re-runs on the data " +
+      "it reads unless a ref or Set marks each row as already written: it loops.",
     returnShape: {
       create:
         "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
@@ -6478,7 +6490,9 @@ const CONTRACT = deepFreeze({
   // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
   //    `useAction().available` turns false when the server says a run would
   //    not reach the script.
-  version: "1.218.0",
+  // 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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,