@colixsystems/widget-sdk 0.159.0 → 0.161.0

package/README.md

@@ -43,12 +43,12 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `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, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
-| **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
+| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
+| **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **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. |
-| **AGENTS** | `useAgent(agentRef)` | `{ send, reset, messages, sending, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). 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. `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). **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
+| **AGENTS** | `useAgent(agentRef)` | `{ send, cancel, reset, messages, sending, resuming, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). Sending is IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. On mount the hook DOES reopen the caller's most recent thread with this agent, so a refresh or a navigation keeps the conversation instead of starting a blank one; that resume only READS and spends no credit. `resuming` is true while it runs — render a loading state, not an empty thread. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance), and the new thread is the one a later mount resumes. **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
 | **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `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) |
@@ -73,7 +73,35 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.157.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.160.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.161.0 (contract 1.124.0)
+
+**`useAgent()` resumes the conversation after a refresh or a navigation (sc-8867).** The backend has always persisted the thread, but the hook held the conversation id and the transcript in component state, so every remount opened a blank one. An app user who refreshed the page lost the conversation on screen — and re-explaining the context to the agent spent another paid turn.
+
+On mount the hook now reopens the caller's most recent thread with the bound agent and restores its transcript. Two things are worth knowing:
+
+- **It spends nothing.** The resume is two READ-ONLY GETs of the caller's own rows (`conversations.list` then `messages.list`). Sending stays imperative — no paid call is made on mount, so a widget nobody types into still costs the workspace nothing.
+- **New `resuming` flag** — true only while the transcript is being reopened. Render a loading state: an empty thread that is about to fill reads as a lost conversation. It is never true for a turn in flight; that is still `sending`.
+
+`reset()` is unchanged as a "new chat" affordance, and the new thread it starts is the one a later mount resumes. A transcript that fails to load renders no error — the widget is fully usable without it and the next send opens a fresh thread.
+
+Additive: a widget that ignores `resuming` behaves as before, except that it now shows the conversation the user actually left.
+
+### What's new in 0.160.0 (contract 1.123.0)
+
+**`useDatastoreQuery` and `useDatastoreRecord` keep their data on screen while they re-fetch (sc-8595).** `loading` used to turn true on every fetch, so a widget that showed a spinner on `loading` flashed its content away whenever its query changed — most visibly when a sort or filter waited on `useBoundColumns`, where the first rows arrived before the schema and were replaced by the spinner a moment later. `loading` is now true only until the first result for the bound table (or record) lands. A changed query on that table, `refetch()` and pull-to-refresh keep the rows already in `data` with `loading: false`; the new **`fetching`** flag is true while any request is in flight. Binding a different table, or a different record id, still resets to `loading`.
+
+Show a spinner on `loading` only. A query built from a bound column should pass `null` as the table until `useBoundColumns(...).loading` is false, so its first fetch already carries the column — and treat BOTH as loading, because the query reports `loading: false` while its table is still `null`:
+
+```js
+const { columns: bound, loading: columnsLoading } = useBoundColumns(tableId, shape, props);
+const query = useStableQuery(() => ({ sort: { field: bound.publishedAtField, dir: "desc" }, limit: 5 }));
+const { data, loading } = useDatastoreQuery(columnsLoading ? null : tableId, query);
+if (columnsLoading || loading) return <Spinner />;
+```
+
+Behaviour change: a widget that deliberately showed a spinner on every re-fetch now keeps its previous rows until the new ones arrive. `fetching` is there for an inline "updating" hint.
 
 ### What's new in 0.157.0 (contract 1.122.0 — unchanged)
 
@@ -186,7 +214,7 @@ It presents inside `<Overlay>`, so it escapes the widget's clipping box on both
 A workspace **agent** is a name plus a system prompt its author wrote in the Studio. This hook lets any widget hold a conversation with one, without touching HTTP and without ever holding an API key.
 
 ```js
-const { send, reset, messages, sending, error, available } = useAgent(props.agentId);
+const { send, reset, messages, sending, resuming, error, available } = useAgent(props.agentId);
 ```
 
 **What a widget deliberately cannot do.** You cannot set the system prompt, send your own transcript, or pick a model, and no API surface returns the prompt. The server assembles every turn from the stored prompt plus the stored history, and `content` is the only field that reaches the wire — not because the rest is filtered out, but because nothing else is ever sent. That guarantee is about the WIRE, not about secrecy: a model can be talked into repeating its own prompt, so an agent's prompt is not a secret store — never put credentials, or data the app's users may not see, in one. `messages` is the transcript this widget has seen; the real one is the server's.

package/dist/contract.cjs

@@ -913,9 +913,14 @@ const HOOKS = [
   {
     name: "useDatastoreRecord",
     signature: "useDatastoreRecord(tableId, recordId)",
+    description:
+      "Reads one row. Re-reading the same record (refetch, pull-to-refresh) " +
+      "keeps it in `data` with loading false while `fetching` is true; a " +
+      "different table or record id resets to loading.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
+      fetching: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
@@ -1205,9 +1210,16 @@ const HOOKS = [
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options)",
     optionalArgs: ["options"],
+    description:
+      "Reads a table's rows. Stale-while-revalidate: `loading` is true only " +
+      "until the first result for the bound table lands; a changed query on " +
+      "that table, refetch() and pull-to-refresh keep the rows already in " +
+      "`data` with loading false, while `fetching` is true. Binding a " +
+      "different table resets to loading. Show a spinner on `loading` only.",
     returnShape: {
       data: "Record[]",
       loading: "boolean",
+      fetching: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
@@ -1303,6 +1315,11 @@ const HOOKS = [
       "agents (an author-written name + system prompt). 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, or the transcript appears to pop in from nowhere. " +
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
       "An assistant message that used a tool also carries `activity`: what " +
@@ -1320,7 +1337,8 @@ const HOOKS = [
       "`agentRef` property — when it is missing, or the host brokers no " +
       "agents client, `available` is false and send() rejects UNAVAILABLE; " +
       "render a visible unbound state, NEVER a blank box. reset() drops the " +
-      "thread and clears the transcript (a 'new chat' affordance). " +
+      "thread and clears the transcript (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, so call it once per user action. " +
       "AgentError.code distinguishes the refusals that share a status: " +
@@ -1340,6 +1358,8 @@ const HOOKS = [
       reset: "() => void",
       messages: "Array<{ id, conversation_id, role, content, created_at }>",
       sending: "boolean",
+      resuming:
+        "boolean  // true only while the stored transcript is being reopened on mount; show a loading state, not an empty thread",
       error: "AgentError | null",
       available: "boolean  // false when no agent is bound, or the host brokers none",
     },
@@ -4334,7 +4354,10 @@ const CONTRACT = deepFreeze({
   //    layout it would use in a half-width cell. Additive: `isNarrowWidth` and
   //    `NARROW_WIDTH_PX` are unchanged, and `widthTier(w) === "narrow"` exactly
   //    when `isNarrowWidth(w)` is true.
-  version: "1.122.0",
+  // 1.123.0: behaviour (sc-8595) — useDatastoreQuery / useDatastoreRecord
+  //    keep their data while a changed query or refetch runs; `loading` only
+  //    until the first result for the table/record, new `fetching` flag.
+  version: "1.124.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -913,9 +913,14 @@ const HOOKS = [
   {
     name: "useDatastoreRecord",
     signature: "useDatastoreRecord(tableId, recordId)",
+    description:
+      "Reads one row. Re-reading the same record (refetch, pull-to-refresh) " +
+      "keeps it in `data` with loading false while `fetching` is true; a " +
+      "different table or record id resets to loading.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
+      fetching: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
@@ -1205,9 +1210,16 @@ const HOOKS = [
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options)",
     optionalArgs: ["options"],
+    description:
+      "Reads a table's rows. Stale-while-revalidate: `loading` is true only " +
+      "until the first result for the bound table lands; a changed query on " +
+      "that table, refetch() and pull-to-refresh keep the rows already in " +
+      "`data` with loading false, while `fetching` is true. Binding a " +
+      "different table resets to loading. Show a spinner on `loading` only.",
     returnShape: {
       data: "Record[]",
       loading: "boolean",
+      fetching: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
@@ -1303,6 +1315,11 @@ const HOOKS = [
       "agents (an author-written name + system prompt). 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, or the transcript appears to pop in from nowhere. " +
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
       "An assistant message that used a tool also carries `activity`: what " +
@@ -1320,7 +1337,8 @@ const HOOKS = [
       "`agentRef` property — when it is missing, or the host brokers no " +
       "agents client, `available` is false and send() rejects UNAVAILABLE; " +
       "render a visible unbound state, NEVER a blank box. reset() drops the " +
-      "thread and clears the transcript (a 'new chat' affordance). " +
+      "thread and clears the transcript (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, so call it once per user action. " +
       "AgentError.code distinguishes the refusals that share a status: " +
@@ -1340,6 +1358,8 @@ const HOOKS = [
       reset: "() => void",
       messages: "Array<{ id, conversation_id, role, content, created_at }>",
       sending: "boolean",
+      resuming:
+        "boolean  // true only while the stored transcript is being reopened on mount; show a loading state, not an empty thread",
       error: "AgentError | null",
       available: "boolean  // false when no agent is bound, or the host brokers none",
     },
@@ -4330,7 +4350,10 @@ const CONTRACT = deepFreeze({
   //    layout it would use in a half-width cell. Additive: `isNarrowWidth` and
   //    `NARROW_WIDTH_PX` are unchanged, and `widthTier(w) === "narrow"` exactly
   //    when `isNarrowWidth(w)` is true.
-  version: "1.122.0",
+  // 1.123.0: behaviour (sc-8595) — useDatastoreQuery / useDatastoreRecord
+  //    keep their data while a changed query or refetch runs; `loading` only
+  //    until the first result for the table/record, new `fetching` flag.
+  version: "1.124.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2173,8 +2173,23 @@ function toDatastoreError(err) {
 // on a genuine loop.
 const VOLATILE_QUERY_RENDER_LIMIT = 10;
 
+const NO_QUERY_RESULT = { key: null, table: null, data: null, error: null, loaded: false };
+const NO_RECORD_RESULT = { key: null, data: null, error: null, loaded: false };
+
+function serializeQuery(query) {
+  try {
+    return JSON.stringify(query);
+  } catch (_e) {
+    return null;
+  }
+}
+
+const queryResultKey = (table, queryKey) => JSON.stringify([table, queryKey]);
+const recordResultKey = (table, recordId) => JSON.stringify([table, recordId]);
+
 /**
- * Stateful datastore query hook. Returns { data, loading, error, refetch }.
+ * Stateful datastore query hook. Returns { data, loading, fetching, error,
+ * refetch }.
  *
  * The host injects a `@colixsystems/datastore-client` instance at
  * `ctx.datastore`. We call `ctx.datastore.records(table).list(query)`, which
@@ -2187,9 +2202,18 @@ const VOLATILE_QUERY_RENDER_LIMIT = 10;
  * re-fetch when [table, JSON.stringify(query)] changes. `refetch` re-runs the
  * same call on demand.
  *
+ * sc-8595 — stale-while-revalidate. `loading` is true only until the first
+ * result for the bound TABLE lands. A changed query on that table, `refetch()`
+ * and a page pull-to-refresh keep the rows already in `data` on screen with
+ * `loading: false`; `fetching` is true while any request is in flight. Binding
+ * a different table resets to `{ data: [], loading: true }`. So a widget shows
+ * its spinner on `loading` only, and never flashes back to it when its query
+ * settles (e.g. a sort that waits on `useBoundColumns`).
+ *
  * When `table` is falsy (e.g. the user hasn't bound a `tableRef` property
- * yet), the hook resolves to { data: [], loading: false, error: null,
- * refetch } so the widget can render its empty state without throwing.
+ * yet), the hook resolves to { data: [], loading: false, fetching: false,
+ * error: null, refetch } so the widget can render its empty state without
+ * throwing.
  */
 export function useDatastoreQuery(table, query) {
   const ctx = useWidgetContextOrThrow("useDatastoreQuery");
@@ -2198,9 +2222,12 @@ export function useDatastoreQuery(table, query) {
       "useDatastoreQuery: host did not inject a datastore client",
     );
   }
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(Boolean(table));
-  const [error, setError] = useState(null);
+  // sc-8595: the last settled request, stamped with the arguments it
+  // answered. What renders is DERIVED from it (see the return), so no
+  // committed frame shows another table's rows or a stale `loading`.
+  const [settled, setSettled] = useState(NO_QUERY_RESULT);
+  const [inFlight, setInFlight] = useState(false);
+  const emptyRows = useRef([]).current;
 
   // Capture the latest table + query in refs so refetch() — a stable
   // callback identity — always reads the current arguments without having
@@ -2230,13 +2257,12 @@ export function useDatastoreQuery(table, query) {
     if (!t) {
       // No table bound yet — collapse to a stable empty result without
       // a network round-trip.
-      setLoading(false);
-      setError(null);
-      setData([]);
+      setInFlight(false);
+      setSettled(NO_QUERY_RESULT);
       return;
     }
-    setLoading(true);
-    setError(null);
+    const key = queryResultKey(t, serializeQuery(queryRef.current));
+    setInFlight(true);
     try {
       const ns = recordsRef.current(t);
       const res = await ns.list(queryRef.current);
@@ -2245,23 +2271,23 @@ export function useDatastoreQuery(table, query) {
       const rows = res && Array.isArray(res.data) ? res.data : [];
       // Discard the result if a newer fetch has started since we kicked off.
       if (runRef.current !== myRun) return;
-      setData(rows);
-      setLoading(false);
+      setSettled({ key, table: t, data: rows, error: null, loaded: true });
+      setInFlight(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
-      setError(toDatastoreError(err));
-      setLoading(false);
+      const error = toDatastoreError(err);
+      // A failed re-fetch keeps the table's rows; a failed first load has none.
+      setSettled((prev) =>
+        prev.table === t && prev.loaded
+          ? { ...prev, key, error }
+          : { key, table: t, data: emptyRows, error, loaded: false },
+      );
+      setInFlight(false);
     }
   }, []);
 
   // Re-run on mount and whenever [table, JSON.stringify(query)] changes.
-  const queryKey = (() => {
-    try {
-      return JSON.stringify(query);
-    } catch (_e) {
-      return null;
-    }
-  })();
+  const queryKey = serializeQuery(query);
 
   // sc-1579 — a query argument built from a volatile value (`Date.now()`,
   // `new Date()`, `Math.random()`) serialises differently every render, so the
@@ -2304,12 +2330,21 @@ export function useDatastoreQuery(table, query) {
   // pull-to-refresh on mobile re-runs the query without per-widget code.
   useRefresh(refetch);
 
-  return { data, loading, error, refetch };
+  const currentKey = table ? queryResultKey(table, queryKey) : null;
+  const busy = Boolean(table) && (settled.key !== currentKey || inFlight);
+  const hasRows = Boolean(table) && settled.table === table && settled.loaded;
+  return {
+    data: hasRows ? settled.data : emptyRows,
+    loading: !hasRows && busy,
+    fetching: busy,
+    error: table && !busy && settled.table === table ? settled.error : null,
+    refetch,
+  };
 }
 
 /**
- * Stateful single-record query hook. Returns { data, loading, error, refetch }
- * where `data` is one row (`null` until loaded, never an array).
+ * Stateful single-record query hook. Returns { data, loading, fetching, error,
+ * refetch } where `data` is one row (`null` until loaded, never an array).
  *
  * The host injects a `@colixsystems/datastore-client` instance at
  * `ctx.datastore`. We call `ctx.datastore.records(table).get(id)`, which
@@ -2318,9 +2353,13 @@ export function useDatastoreQuery(table, query) {
  * named them. We hold the result in component state and re-fetch when
  * [table, id] changes. `refetch` re-runs the call on demand.
  *
+ * sc-8595 — same rule as useDatastoreQuery: re-reading the SAME record keeps
+ * it in `data` with `loading: false` while `fetching` is true; a different
+ * table or id resets to `{ data: null, loading: true }`.
+ *
  * When `table` OR `recordId` is falsy (e.g. the author hasn't bound the
  * record id yet), the hook resolves to { data: null, loading: false,
- * error: null, refetch } so the widget can render its empty state
+ * fetching: false, error: null, refetch } so the widget can render its empty state
  * without throwing. A 404 surfaces as a DatastoreError with
  * `code: "NOT_FOUND"`.
  */
@@ -2331,10 +2370,10 @@ export function useDatastoreRecord(table, recordId) {
       "useDatastoreRecord: host did not inject a datastore client",
     );
   }
-  const ready = Boolean(table && recordId);
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(ready);
-  const [error, setError] = useState(null);
+  // sc-8595: stamped with the record it answered; rendered values derive
+  // from it, like useDatastoreQuery's.
+  const [settled, setSettled] = useState(NO_RECORD_RESULT);
+  const [inFlight, setInFlight] = useState(false);
 
   // Same ref discipline as useDatastoreQuery — `ctx` is a fresh object
   // identity on every host render, so we hold the live inputs in refs
@@ -2353,23 +2392,27 @@ export function useDatastoreRecord(table, recordId) {
     const t = tableRef.current;
     const id = recordIdRef.current;
     if (!t || !id) {
-      setLoading(false);
-      setError(null);
-      setData(null);
+      setInFlight(false);
+      setSettled(NO_RECORD_RESULT);
       return;
     }
-    setLoading(true);
-    setError(null);
+    const key = recordResultKey(t, id);
+    setInFlight(true);
     try {
       const ns = recordsRef.current(t);
       const row = await ns.get(id);
       if (runRef.current !== myRun) return;
-      setData(row || null);
-      setLoading(false);
+      setSettled({ key, data: row || null, error: null, loaded: true });
+      setInFlight(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
-      setError(toDatastoreError(err));
-      setLoading(false);
+      const error = toDatastoreError(err);
+      setSettled((prev) =>
+        prev.key === key && prev.loaded
+          ? { ...prev, error }
+          : { key, data: null, error, loaded: false },
+      );
+      setInFlight(false);
     }
   }, []);
 
@@ -2385,7 +2428,16 @@ export function useDatastoreRecord(table, recordId) {
   // sc-1179 — auto-subscribe to the page-level refresh tick.
   useRefresh(refetch);
 
-  return { data, loading, error, refetch };
+  const currentKey = table && recordId ? recordResultKey(table, recordId) : null;
+  const busy = currentKey !== null && (settled.key !== currentKey || inFlight);
+  const hasRecord = currentKey !== null && settled.key === currentKey && settled.loaded;
+  return {
+    data: hasRecord ? settled.data : null,
+    loading: !hasRecord && busy,
+    fetching: busy,
+    error: currentKey !== null && !busy ? settled.error : null,
+    refetch,
+  };
 }
 
 /**
@@ -2761,17 +2813,23 @@ function toAgentError(err) {
 
 /**
  * sc-7991 — hold a conversation with a workspace-authored AI agent.
- * Returns `{ send, reset, messages, sending, error, available }`.
+ * Returns `{ send, cancel, reset, messages, sending, resuming, error, available }`.
  *
  *   send(text) → Promise<{ role, content }>   the agent's reply
  *
- * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls `send`
- * from an event handler. The first `send` opens the conversation, so an author
- * who places the widget and never types costs the workspace nothing.
+ * Sending is IMPERATIVE — no PAID call is ever made on mount; the widget calls
+ * `send` from an event handler, and the first `send` opens the conversation, so
+ * an author who places the widget and never types costs the workspace nothing.
+ *
+ * sc-8867 — 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 is two READ-ONLY GETs of the caller's own
+ * rows and spends no AI credit. `resuming` is true only while it runs; `reset()`
+ * starts a fresh thread and outdates any resume still in flight.
  *
  * `messages` is the running transcript this widget has seen, oldest first,
- * each `{ id, role, content, created_at }` with `role` of "user" | "assistant".
- * An assistant message that used a tool also carries `activity` — what the
+ * each `{ id, role, content, created_at }` with `role` of "user" | "assistant".
+ * An assistant message that used a tool also carries `activity` — what the
  * agent DID with the user's data. Render the writes: "done!" is not evidence.
  * The SERVER owns the real transcript and the system prompt: the widget sends
  * one message and can neither read nor set the prompt.
@@ -2808,12 +2866,25 @@ export function useAgent(agentRef) {
   const [messages, setMessages] = useState([]);
   const [sending, setSending] = useState(false);
   const [error, setError] = useState(null);
+  const [resuming, setResuming] = useState(available);
 
   // Set during render when the binding changes; consumed below. A setState in
   // the render body would be a cascading re-render, so the flag is applied to
   // the value this render returns instead.
   const pendingResetRef = useRef(false);
 
+  // sc-8867 — a `reset()` must SURVIVE the resume effect. Without it, "New
+  // conversation" on a mount whose list call is still in flight is overwritten
+  // by the transcript the user just asked to leave.
+  const resumeGenerationRef = useRef(0);
+
+  // "New conversation" is a decision about the THREAD, not about this mount.
+  // `reset()` drops only the client's handle — the server still lists the
+  // abandoned thread as the most recent one — so without this a remount
+  // resumes exactly what the user just dismissed. Cleared on a rebind, which
+  // is a different agent and therefore a different decision.
+  const suppressResumeRef = useRef(false);
+
   // A changed binding is a different agent, so neither the open thread nor the
   // transcript carries — leaving the messages would render agent A's
   // conversation underneath agent B.
@@ -2822,14 +2893,25 @@ export function useAgent(agentRef) {
     boundRef.current = agentRef;
     conversationRef.current = null;
     pendingResetRef.current = true;
+    // A resume for the PREVIOUS agent is now outdated, and the new binding's
+    // own resume has not run yet — without this the widget renders one frame
+    // of "no conversation" before the effect reports it is loading.
+    resumeGenerationRef.current += 1;
+    // A different agent is a different decision: leaving the old agent's
+    // "new conversation" set would stop this one from ever resuming.
+    suppressResumeRef.current = false;
   }
 
   const abortRef = useRef(null);
 
   const reset = useCallback(() => {
+    // Outdates any resume in flight, so its transcript is discarded on arrival.
+    resumeGenerationRef.current += 1;
+    suppressResumeRef.current = true;
     conversationRef.current = null;
     setMessages([]);
     setError(null);
+    setResuming(false);
   }, []);
 
   // Ends the WAIT, not the turn: the abort never reaches the server, which
@@ -2839,6 +2921,104 @@ export function useAgent(agentRef) {
     if (controller) controller.abort();
   }, []);
 
+  // sc-8867 — reopen the caller's most recent thread with this agent.
+  //
+  // The transcript lives on the SERVER; holding it only in component state
+  // meant a refresh or a navigation started a blank thread, losing the
+  // context and paying to rebuild it. Both calls here are READ-ONLY GETs of
+  // the caller's own rows: this spends no AI credit, so the hook's rule that
+  // it never makes a PAID call on mount is intact — `send` and
+  // `conversations.create` remain imperative and reachable only from an
+  // event handler.
+  //
+  // Nothing is resumed when the transcript is non-empty (a send already
+  // opened this thread) or after a `reset()`, whose generation bump outdates
+  // an in-flight resume.
+  useEffect(() => {
+    if (!available) {
+      setResuming(false);
+      return undefined;
+    }
+    const client = clientRef.current;
+    const agentId = agentIdRef.current;
+    if (!client || !agentId) {
+      setResuming(false);
+      return undefined;
+    }
+
+    let cancelled = false;
+    const generation = resumeGenerationRef.current;
+    // A remount with the thread already open would re-read what it holds, and
+    // a thread the user deliberately left must not come back on a remount.
+    if (conversationRef.current || suppressResumeRef.current) {
+      setResuming(false);
+      return undefined;
+    }
+
+    // An older host may broker a client with no `list`. Resuming is an
+    // ENHANCEMENT, so a client that cannot do it degrades to the previous
+    // behaviour — never to a widget wedged on a loading state it cannot leave.
+    let thread;
+    try {
+      thread = client.conversations(agentId);
+    } catch {
+      thread = null;
+    }
+    if (!thread || typeof thread.list !== "function") {
+      setResuming(false);
+      return undefined;
+    }
+    setResuming(true);
+
+    (async () => {
+      try {
+        const listed = await thread.list({ limit: 1 });
+        const latest =
+          listed && Array.isArray(listed.data) && listed.data.length > 0
+            ? listed.data[0]
+            : null;
+        const conversationId = latest && latest.id ? latest.id : null;
+        if (!conversationId) return;
+        const transcript = thread.messages(conversationId);
+        if (!transcript || typeof transcript.list !== "function") return;
+        const history = await transcript.list();
+        // Re-checked AFTER the awaits: a rebind, an unmount or a reset during
+        // the round trip must not adopt this agent's thread under another.
+        if (
+          cancelled ||
+          agentIdRef.current !== agentId ||
+          resumeGenerationRef.current !== generation ||
+          suppressResumeRef.current ||
+          // A `send` that started during the resume already latched a thread.
+          // Overwriting it would orphan that PAID turn in a conversation
+          // nothing reads again, and point the next send somewhere else.
+          conversationRef.current
+        ) {
+          return;
+        }
+        conversationRef.current = Promise.resolve(conversationId);
+        const rows =
+          history && Array.isArray(history.data) ? history.data : [];
+        // Never clobber a turn a concurrent send already appended.
+        if (rows.length > 0) setMessages((prior) => (prior.length > 0 ? prior : rows));
+      } catch {
+        // A transcript that will not load is not a failed turn, and the widget
+        // is fully usable without it: a visible error here would report a
+        // healthy agent as broken. The next send opens a fresh thread.
+      } finally {
+        if (!cancelled) setResuming(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      // A hung `list()` never settles, so the `finally` above may never run.
+      // Without this the next render stays latched on a spinner with the
+      // composer disabled — the wedge this whole path exists to avoid.
+      setResuming(false);
+    };
+  }, [available, agentRef]);
+
   const send = useCallback(async (text) => {
     const client = clientRef.current;
     const agentId = agentIdRef.current;
@@ -2910,6 +3090,7 @@ export function useAgent(agentRef) {
   // than one frame of the previous agent's conversation.
   let visibleMessages = messages;
   let visibleError = error;
+  let visibleResuming = resuming;
   if (pendingResetRef.current) {
     pendingResetRef.current = false;
     visibleMessages = [];
@@ -2918,6 +3099,10 @@ export function useAgent(agentRef) {
     // report a healthy agent as broken, and widgets gate on error.code.
     visibleError = null;
     if (error) setError(null);
+    // The new binding's resume starts in the effect below, so report it as
+    // loading now rather than showing an empty thread for one frame.
+    visibleResuming = available;
+    if (resuming !== available) setResuming(available);
   }
 
   return {
@@ -2926,6 +3111,10 @@ export function useAgent(agentRef) {
     reset,
     messages: visibleMessages,
     sending,
+    // sc-8867 — true only while the stored transcript is being reopened, so a
+    // widget shows a loading state instead of an empty thread that is about to
+    // fill. Never true for a turn in flight; that is `sending`.
+    resuming: visibleResuming,
     error: visibleError,
     available,
   };

package/dist/index.d.ts

@@ -825,7 +825,14 @@ export interface Query {
 
 export interface QueryResult<T> {
   data: T[];
+  /**
+   * True only until the first result for the bound table lands. A changed
+   * query on the same table, `refetch()` and pull-to-refresh keep the rows
+   * already in `data` with `loading: false`. Show a spinner on this only.
+   */
   loading: boolean;
+  /** True while any request is in flight, including a background re-fetch. */
+  fetching: boolean;
   error: Error | null;
   refetch(): Promise<void>;
 }
@@ -1042,8 +1049,10 @@ export function useTheme(): ThemeTokens;
 export function useWidgetStyle(): Record<string, unknown>;
 
 /**
- * Stateful single-record fetch hook. Returns `{ data, loading, error,
- * refetch }`. `data` is one row or `null` (never an array).
+ * Stateful single-record fetch hook. Returns `{ data, loading, fetching,
+ * error, refetch }`. `data` is one row or `null` (never an array). Re-reading
+ * the same record keeps it in `data` with `loading: false`; a different table
+ * or id resets to `loading: true`.
  */
 export function useDatastoreRecord(
   tableId: string | null | undefined,
@@ -1051,6 +1060,7 @@ export function useDatastoreRecord(
 ): {
   data: unknown | null;
   loading: boolean;
+  fetching: boolean;
   error: DatastoreError | null;
   refetch(): Promise<void>;
 };
@@ -1245,11 +1255,21 @@ export interface AgentApi {
    * "cancel", and show no error when the user presses it.
    */
   cancel(): void;
-  /** Drop the open thread and clear the transcript this widget has seen. */
+  /**
+   * Drop the open thread and clear the transcript this widget has seen. The
+   * NEW thread is the one a later mount resumes.
+   */
   reset(): void;
   /** Oldest first. The SERVER owns the real transcript. */
   messages: AgentMessage[];
   sending: boolean;
+  /**
+   * sc-8867 — true only while the caller's most recent thread is being
+   * reopened on mount. Render a loading state: an empty thread that is about
+   * to fill reads as a lost conversation. Never true for a turn in flight —
+   * that is `sending`.
+   */
+  resuming: boolean;
   error: AgentError | null;
   /** False when no agent is bound, or the host brokers no agents client. */
   available: boolean;
@@ -1257,9 +1277,13 @@ export interface AgentApi {
 
 /**
  * sc-7991 — hold a conversation with a workspace-authored AI agent.
- * IMPERATIVE: never fires on mount, so an unused widget costs nothing. The
- * widget sends ONE message; the system prompt and the real transcript stay
- * server-side and are never readable or settable from here.
+ * Sending is IMPERATIVE: no PAID call is made on mount, so an unused widget
+ * costs nothing. The widget sends ONE message; the system prompt and the real
+ * transcript stay server-side and are never readable or settable from here.
+ *
+ * sc-8867 — on mount it DOES reopen the caller's most recent thread with this
+ * agent (two read-only GETs, no credit spent), so a refresh or a navigation
+ * keeps the conversation rather than starting a blank one.
  */
 export function useAgent(agentRef: string | null | undefined): AgentApi;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.159.0",
+  "version": "0.161.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",