@lotics/app-sdk 0.79.3 → 0.81.0

package/AGENTS.md

@@ -16,15 +16,15 @@ signature; open the file.**
 |---|---|
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
-| [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
-| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything), `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 
 ## Non-negotiables (each detailed in its doc)
 

package/dist/src/hooks.js

@@ -19,12 +19,23 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
-import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
+import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, } from "./rpc.js";
 import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
-import { getMockRows, hasMockFlag } from "./mock.js";
+import { getMockRows, getMockWorkflow, hasMockFlag } from "./mock.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 export function useWorkflow(alias) {
-    return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
+    return useCallback(async (inputs) => {
+        // Checked per CALL, not per render: a fixture registered after mount or
+        // swapped by HMR is picked up, and an app that never runs this workflow
+        // does no work here. Mock mode needs BOTH the `?__mock=1` flag and a
+        // registered fixture, so a bundle carrying demo data cannot answer real
+        // traffic with it.
+        const mock = getMockWorkflow(alias);
+        if (mock) {
+            return typeof mock === "function" ? await mock(inputs ?? {}) : mock;
+        }
+        return rpc("workflow", { alias, inputs: inputs ?? {} });
+    }, [alias]);
 }
 // Shared SWR config: surface a failed query immediately, keep the last good
 // rows (no retry loop that masks the error), and honor the focus/reconnect
@@ -52,17 +63,27 @@ function swrConfig(revalidateOnFocus) {
     };
 }
 /**
- * Re-run `refetch` when the host pushes `refetchQueries` — after an ambient
- * app-chat agent turn mutated records, every mounted query hook refreshes the
- * data it rendered. Inert in mock mode (no host, no listener) and for a mocked
- * alias (its rows come from the fixture). Shared by all three query hooks.
+ * Refetch this query when the host reports that ITS tables changed — whoever
+ * wrote them: another member, a workflow, the chat agent, or an external agent
+ * over the CLI or MCP.
+ *
+ * The host names the affected aliases rather than telling every hook to
+ * re-read: an app's queries usually span several tables, and a blanket refetch
+ * would re-run expensive aggregates on a change to a table they never touch.
+ *
+ * Inert in mock mode (no host, no listener), for a mocked alias (its rows come
+ * from the fixture), and for a standalone/public app (no host to push).
+ * Shared by all three query hooks.
  */
-function useHostRefetch(refetch, mockRows) {
+function useHostRefetch(alias, refetch, mockRows) {
     useEffect(() => {
         if (hasMockFlag() || mockRows)
             return;
-        return subscribeHostRefetch(refetch);
-    }, [refetch, mockRows]);
+        return subscribeQueriesChanged((aliases) => {
+            if (aliases.includes(alias))
+                refetch();
+        });
+    }, [alias, refetch, mockRows]);
 }
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
@@ -88,7 +109,7 @@ export function useQuery(alias, params, opts) {
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
-    useHostRefetch(refetch, mockRows);
+    useHostRefetch(alias, refetch, mockRows);
     return {
         rows: mockRows ?? swr.data?.rows ?? [],
         loading: mockRows ? false : swr.isLoading,
@@ -182,7 +203,7 @@ export function useInfiniteQuery(alias, params, opts) {
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
-    useHostRefetch(refetch, mockRows);
+    useHostRefetch(alias, refetch, mockRows);
     const loadMore = useCallback(() => {
         if (!hasMore || loadingMore)
             return;
@@ -251,7 +272,7 @@ export function usePaginatedQuery(alias, params, opts) {
         void rowsSwr.mutate();
         void countSwr.mutate();
     }, [rowsSwr, countSwr]);
-    useHostRefetch(refetch, mockRows);
+    useHostRefetch(alias, refetch, mockRows);
     return {
         rows,
         total,

package/dist/src/mock.d.ts

@@ -1,33 +1,53 @@
 /**
- * Demo / design-time fixture support for `useQuery`.
+ * Demo / design-time fixture support for `useQuery` and `useWorkflow`.
  *
  * Activation contract:
  *
  *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
- *      is a `{ queries: { alias: Row[] } }` map keyed by the same aliases the
- *      app declared in `package.json#lotics.queries`.
+ *      is a `{ queries: { alias: Row[] }, workflows: { alias: Result } }` map
+ *      keyed by the same aliases the app declared in
+ *      `package.json#lotics.queries` / `#lotics.workflows`.
  *   2. At runtime, the user (or a screenshot script) loads the app with the
  *      `?__mock=1` URL search param. Without that param the SDK ignores the
- *      fixture entirely and `useQuery` flows through the RPC bridge as usual.
+ *      fixture entirely and both hooks flow through the RPC bridge as usual.
  *
  * The two-step gate keeps demo data shipping in the bundle from leaking into
  * normal traffic — the param namespace (`__mock` prefix) is reserved and
  * unlikely to collide with app-side query state. Apps that don't pass a
- * fixture pay nothing: `getMockRows` returns `null` for every alias and the
- * hook path is unchanged.
+ * fixture pay nothing: `getMockRows` / `getMockWorkflow` return `null` for
+ * every alias and the hook path is unchanged.
  *
- * What's deliberately *not* mocked yet:
- *   - `useWorkflow` — mutations have side effects (notifications, audit
- *     trail). A workflow mock would have to also produce realistic followup
- *     state, which is more design than this iteration warrants.
- *   - `useFileUpload` — same reason.
+ * `workflows` exists because the side-effect argument runs the other way: a
+ * mocked workflow does not RUN, so it produces no notification and no audit
+ * trail — it PREVENTS them. What it cannot produce is the followup state a
+ * subsequent `useQuery` would read, which is the author's call and is already
+ * true of a mocked query. Without it, an app whose only AI surface is a
+ * workflow that reads and calls `agent(...)` — the standard shape — had no
+ * non-billing path to its own in-flight / done / error states at all, so those
+ * three screens could not be reviewed without spending on a live workspace.
  *
- * If those become needed, extend `AppFixture` with `workflows`/`uploads` and
- * route from each hook.
+ * A fixture entry may be the RESULT, or a FUNCTION of the inputs. The function
+ * form is what makes the in-flight state reachable: resolve on a timer and the
+ * app renders the pending branch it otherwise never shows. It also lets one
+ * alias answer differently per input, which is how an error branch is reviewed
+ * beside a success one.
+ *
+ * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
+ * different shape from a request/response pair, and nothing has needed it.
+ */
+import type { WorkflowResult } from "./hooks.js";
+/**
+ * What a mocked workflow answers with: a fixed result, or a function of the
+ * inputs it was called with. Return a promise from the function to hold the
+ * caller in its pending state for as long as the review needs.
  */
+export type MockWorkflow = WorkflowResult | ((inputs: Record<string, unknown>) => WorkflowResult | Promise<WorkflowResult>);
 export interface AppFixture {
     /** Map of query alias → rows the hook should return when mock mode is on. */
     queries?: Record<string, Array<Record<string, unknown>>>;
+    /** Map of workflow alias → the result it resolves with when mock mode is on.
+     *  The workflow never executes, so nothing it would have written is written. */
+    workflows?: Record<string, MockWorkflow>;
 }
 /**
  * Called by `mount({ fixture })`. Module-level state because the SDK has no
@@ -51,3 +71,13 @@ export declare function hasMockFlag(): boolean;
  * only some queries and let the rest flow through to real data.
  */
 export declare function getMockRows(alias: string): Array<Record<string, unknown>> | null;
+/**
+ * The fixture entry for a workflow alias when mock mode is active *and* the
+ * fixture has an entry for it. Otherwise null — the hook falls through to the
+ * real RPC path, so an app may mock one workflow and let the rest execute.
+ *
+ * Resolved when the workflow is CALLED rather than when the hook is created, so
+ * a fixture registered after mount (or replaced by HMR) is picked up, and an
+ * app that never calls the workflow pays nothing.
+ */
+export declare function getMockWorkflow(alias: string): MockWorkflow | null;

package/dist/src/mock.js

@@ -1,29 +1,39 @@
 /**
- * Demo / design-time fixture support for `useQuery`.
+ * Demo / design-time fixture support for `useQuery` and `useWorkflow`.
  *
  * Activation contract:
  *
  *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
- *      is a `{ queries: { alias: Row[] } }` map keyed by the same aliases the
- *      app declared in `package.json#lotics.queries`.
+ *      is a `{ queries: { alias: Row[] }, workflows: { alias: Result } }` map
+ *      keyed by the same aliases the app declared in
+ *      `package.json#lotics.queries` / `#lotics.workflows`.
  *   2. At runtime, the user (or a screenshot script) loads the app with the
  *      `?__mock=1` URL search param. Without that param the SDK ignores the
- *      fixture entirely and `useQuery` flows through the RPC bridge as usual.
+ *      fixture entirely and both hooks flow through the RPC bridge as usual.
  *
  * The two-step gate keeps demo data shipping in the bundle from leaking into
  * normal traffic — the param namespace (`__mock` prefix) is reserved and
  * unlikely to collide with app-side query state. Apps that don't pass a
- * fixture pay nothing: `getMockRows` returns `null` for every alias and the
- * hook path is unchanged.
+ * fixture pay nothing: `getMockRows` / `getMockWorkflow` return `null` for
+ * every alias and the hook path is unchanged.
  *
- * What's deliberately *not* mocked yet:
- *   - `useWorkflow` — mutations have side effects (notifications, audit
- *     trail). A workflow mock would have to also produce realistic followup
- *     state, which is more design than this iteration warrants.
- *   - `useFileUpload` — same reason.
+ * `workflows` exists because the side-effect argument runs the other way: a
+ * mocked workflow does not RUN, so it produces no notification and no audit
+ * trail — it PREVENTS them. What it cannot produce is the followup state a
+ * subsequent `useQuery` would read, which is the author's call and is already
+ * true of a mocked query. Without it, an app whose only AI surface is a
+ * workflow that reads and calls `agent(...)` — the standard shape — had no
+ * non-billing path to its own in-flight / done / error states at all, so those
+ * three screens could not be reviewed without spending on a live workspace.
  *
- * If those become needed, extend `AppFixture` with `workflows`/`uploads` and
- * route from each hook.
+ * A fixture entry may be the RESULT, or a FUNCTION of the inputs. The function
+ * form is what makes the in-flight state reachable: resolve on a timer and the
+ * app renders the pending branch it otherwise never shows. It also lets one
+ * alias answer differently per input, which is how an error branch is reviewed
+ * beside a success one.
+ *
+ * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
+ * different shape from a request/response pair, and nothing has needed it.
  */
 let registeredFixture;
 /**
@@ -70,3 +80,17 @@ export function getMockRows(alias) {
     const rows = registeredFixture?.queries?.[alias];
     return rows ?? null;
 }
+/**
+ * The fixture entry for a workflow alias when mock mode is active *and* the
+ * fixture has an entry for it. Otherwise null — the hook falls through to the
+ * real RPC path, so an app may mock one workflow and let the rest execute.
+ *
+ * Resolved when the workflow is CALLED rather than when the hook is created, so
+ * a fixture registered after mount (or replaced by HMR) is picked up, and an
+ * app that never calls the workflow pays nothing.
+ */
+export function getMockWorkflow(alias) {
+    if (!isMockMode())
+        return null;
+    return registeredFixture?.workflows?.[alias] ?? null;
+}

package/dist/src/rpc.d.ts

@@ -135,12 +135,20 @@ export declare function subscribeUrlParams(cb: (params: UrlParams) => void): ()
  */
 export declare function postHostNotification(message: HostNotification): void;
 /**
- * Subscribe to the host's `refetchQueries` push. Returns an unsubscribe fn.
- * Wired by every mounted query hook so an ambient-chat record mutation refreshes
- * exactly the data currently on screen. No host ever posts it standalone, so the
- * subscription is inert there.
+ * Subscribe to the host's `queriesChanged` push, which names the aliases whose
+ * underlying tables moved. Returns an unsubscribe fn.
+ *
+ * The host owns the realtime connection — one per tab, shared by every surface
+ * in it — because the app frame deliberately holds no platform credentials, and
+ * a second socket per app would only duplicate a subscription the host already
+ * has. The host resolves changed tables to aliases (it holds the query ASTs)
+ * and names them here, so a mounted hook refetches only when ITS query is
+ * affected rather than on every change anywhere in the workspace.
+ *
+ * A standalone (public) app has no host, so this is inert there — those apps
+ * stay on pull-based freshness.
  */
-export declare function subscribeHostRefetch(cb: () => void): () => void;
+export declare function subscribeQueriesChanged(cb: (aliases: string[]) => void): () => void;
 /**
  * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
  * (the caller parses it via `agent_stream`); `done` settles when the stream

package/dist/src/rpc.js

@@ -91,12 +91,20 @@ export function postHostNotification(message) {
     window.parent.postMessage(message, hostOrigin);
 }
 /**
- * Subscribe to the host's `refetchQueries` push. Returns an unsubscribe fn.
- * Wired by every mounted query hook so an ambient-chat record mutation refreshes
- * exactly the data currently on screen. No host ever posts it standalone, so the
- * subscription is inert there.
+ * Subscribe to the host's `queriesChanged` push, which names the aliases whose
+ * underlying tables moved. Returns an unsubscribe fn.
+ *
+ * The host owns the realtime connection — one per tab, shared by every surface
+ * in it — because the app frame deliberately holds no platform credentials, and
+ * a second socket per app would only duplicate a subscription the host already
+ * has. The host resolves changed tables to aliases (it holds the query ASTs)
+ * and names them here, so a mounted hook refetches only when ITS query is
+ * affected rather than on every change anywhere in the workspace.
+ *
+ * A standalone (public) app has no host, so this is inert there — those apps
+ * stay on pull-based freshness.
  */
-export function subscribeHostRefetch(cb) {
+export function subscribeQueriesChanged(cb) {
     ensureListener();
     refetchSubscribers.add(cb);
     return () => {
@@ -108,7 +116,7 @@ const streaming = new Map();
 /** `useUrlState` subscribers — notified when the host broadcasts new params
  *  after browser back/forward. */
 const urlStateSubscribers = new Set();
-/** Query hooks subscribed to the host's `refetchQueries` push — the host sends
+/** Query hooks subscribed to the host's `queriesChanged` push — the host sends
  *  it after an ambient app-chat agent turn mutated records. */
 const refetchSubscribers = new Set();
 let nextRpcId = 0;
@@ -131,13 +139,13 @@ function ensureListener() {
                 cb(msg.params);
             return;
         }
-        // Broadcast (no id): the host tells the app its rendered data may be stale
-        // after an ambient app-chat agent turn mutated records — every mounted query
-        // hook re-reads through its own declared queries. Push-only freshness; the
+        // Broadcast (no id): the host names the aliases whose tables changed, from
+        // the realtime channel it holds for the whole tab. Push-only freshness; the
         // host never reads app data through this path.
-        if (msg.type === "refetchQueries") {
+        if (msg.type === "queriesChanged" && Array.isArray(msg.aliases)) {
+            const aliases = msg.aliases.filter((a) => typeof a === "string");
             for (const cb of refetchSubscribers)
-                cb();
+                cb(aliases);
             return;
         }
         if (typeof msg.id !== "number")

package/docs/data_fetching.md

@@ -71,11 +71,19 @@ server validates system conditions by `type` and never reads `field_key` on them
   renders the cached rows instantly *and* revalidates them in the background, so a list reflects what
   another screen changed while you were away. Identical concurrent reads dedupe to one request.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on), the host's post-chat-turn poke, and explicit `refetch()`.
+  (`revalidateOnFocus`, default on), a **realtime push**, and explicit `refetch()`.
   **Still call `refetch()` after a write the user is watching for**: arrival covers navigation, not a
   mutation made on the screen you are already standing on.
+- **Realtime push keeps an already-open screen current.** When a table one of your queries reads
+  changes — another member, a workflow, the chat agent, or an external agent writing over the CLI or
+  MCP — that query refetches within about a second. Nothing to wire: it follows from the query's own
+  declaration. It refetches only the aliases whose tables actually moved, so an expensive aggregate
+  is not re-run by a change to a table it never reads. Two limits worth knowing: it carries RECORD
+  changes only (a schema edit does not push), and a **standalone/public app has no host**, so those
+  apps keep focus/reconnect freshness alone. Treat push as an improvement on pull, never a
+  replacement — it is absent whenever the channel cannot connect.
 - **`useInfiniteQuery` does not arrival-revalidate** — the one exception. A warm feed re-mounted
-  refetches nothing; a cold key still fetches, and focus / reconnect / the chat poke still refresh.
+  refetches nothing; a cold key still fetches, and focus / reconnect / a realtime push still refresh.
   Re-fetching page 1 on arrival would cost a request on every `loadMore()` and reshuffle the top of
   the feed under a reader scrolling further down it, and re-fetching every loaded page grows without
   bound. **A feed that must be fresh on arrival calls `refetch()`.**
@@ -111,8 +119,9 @@ server validates system conditions by `type` and never reads `field_key` on them
   queries currently on screen (mounted hooks only); it never reaches into app data, it only tells
   the app its rendered rows may be stale. Inert standalone and in mock mode.
 - A design-time fixture registered via `mount(<App />, { fixture })` plus the `?__mock=1` URL flag
-  short-circuits all three hooks (rows come from the fixture, no request, `loading` stays `false`)
-  — see [./runtime.md](./runtime.md).
+  short-circuits all three hooks (rows come from the fixture, no request, `loading` stays `false`).
+  The same fixture mocks `useWorkflow`, so a screen's in-flight / done / error states are
+  reviewable without running anything — see [./runtime.md](./runtime.md).
 
 ### Error messages you will actually see
 

package/docs/runtime.md

@@ -47,6 +47,16 @@ mount(<App />, {
       orders: MOCK_ORDERS,       // alias → rows, same aliases as package.json#lotics.queries
       customers: MOCK_CUSTOMERS,
     },
+    workflows: {
+      // A fixed result, for the settled state.
+      archive: { status: "success", message: "Archived 3 orders." },
+      // Or a FUNCTION of the inputs — the only way to reach the IN-FLIGHT state,
+      // and the way to put an error branch beside a success one.
+      publish: (inputs) =>
+        inputs.dryRun
+          ? { status: "error", message: "Row 2 has no customer." }
+          : new Promise((r) => setTimeout(() => r({ status: "success" }), 1200)),
+    },
   },
 });
 ```
@@ -55,7 +65,7 @@ Activation is a **two-step gate** — both must hold, so demo data shipping in t
 bundle never leaks into normal traffic:
 
 1. A fixture is registered via `mount({ fixture })` (`AppFixture` type:
-   `dist/src/mock.d.ts` — `{ queries?: Record<string, Array<Record<string, unknown>>> }`).
+   `dist/src/mock.d.ts` — `{ queries?, workflows? }`).
 2. The page URL carries `?__mock=1` (exactly `1`). Without the flag the fixture
    is completely inert.
 
@@ -68,9 +78,17 @@ transport. Calling `mount` again (HMR) replaces the registration last-write-wins
   as fetched rows, so shape them exactly like the query's real output — the same
   serialized cells your `row.*` / `readSelect` / `readFiles` readers decode —
   or the readers will decode nothing.
-- **Not mocked:** workflows (`useWorkflow`), uploads, `useFieldOptions`, members,
-  comments, agent runs. In mock mode those still hit the real transport;
-  mutations have side effects, so there is deliberately no workflow mock.
+- **A mocked workflow does not RUN.** `useWorkflow(alias)` resolves the fixture
+  entry and sends nothing, so there is no notification, no audit trail and no
+  spend — the side-effect argument is the reason to mock it, not a reason not
+  to. What a mock cannot produce is the followup state a later query would read;
+  that is yours to fixture too, exactly as it already is for queries.
+  **Reach the in-flight state with a function** that resolves on a timer: an app
+  whose only AI surface is a workflow calling `agent(...)` otherwise has no
+  non-billing path to its own thinking / done / error screens, which is how
+  those three ship unreviewed.
+- **Not mocked:** uploads, `useFieldOptions`, members, comments, agent runs. In
+  mock mode those still hit the real transport.
 - **Analytics is disabled** whenever `?__mock=1` is present, fixture or not — a
   screenshot/design-time load emits no events.
 - The `__mock` param-name prefix is reserved by the SDK; don't use it for

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.79.3",
-  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
+  "version": "0.81.0",
+  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
     ".": {