@lotics/app-sdk 0.80.0 → 0.81.1

package/AGENTS.md

@@ -24,7 +24,7 @@ signature; open the file.**
 | [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; 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/comments.js

@@ -18,9 +18,15 @@
  * signed-in member: `available` is false, lists stay empty, and a mutation
  * rejects. Check `available` before rendering a composer.
  *
- * Freshness mirrors `useQuery`: SWR-cached, revalidate on focus / reconnect, and
- * an explicit refetch after every mutation. There is no realtime push to apps,
- * so a thread updated by another viewer appears on the next focus / refetch.
+ * Freshness: SWR-cached, revalidate on focus / reconnect, and an explicit
+ * refetch after every mutation — so another viewer's comment appears on the
+ * next focus or `refetch()`, not on its own.
+ *
+ * This is the one read hook that does NOT keep itself current, and the reason
+ * is worth knowing rather than guessing: the realtime channel carries **record**
+ * changes, and a comment is its own entity that emits no record event. Your
+ * QUERIES do get pushed (`docs/data_fetching.md`) — do not read this as "apps
+ * have no realtime" and go build a poll.
  */
 import { useCallback } from "react";
 import useSWR from "swr";

package/dist/src/hooks.js

@@ -21,10 +21,21 @@ import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 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

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/docs/data_fetching.md

@@ -119,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/members_and_options.md

@@ -297,8 +297,11 @@ updateComment, deleteComment, refetch }`.
   member source: the `useMembers` roster (requires the member-access declaration above) or member
   cells in your own data. An unresolvable id should render a fallback (`CommentList` has an
   `unknownMember` label for exactly this).
-- **Freshness:** SWR-cached, revalidates on focus/reconnect; there is **no realtime push** to apps,
-  so another viewer's comment appears on the next focus or explicit `refetch()`.
+- **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
+  the next focus or explicit `refetch()` — not on its own. Comments are the one read that does not
+  keep itself current, and not because apps lack realtime: the channel carries **record** changes,
+  and a comment is its own entity that emits no record event. Your queries DO get pushed
+  ([data_fetching.md](./data_fetching.md)) — don't read this line as "no push" and build a poll.
 
 ### Counts
 

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.80.0",
-  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
+  "version": "0.81.1",
+  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
     ".": {