@nanobpm/bojtos-react 0.7.0 → 0.8.0

package/README.md

@@ -6,7 +6,9 @@ React binding for the **Bojtos** in-browser BPMN demo framework
 
 - **`useBojtos({ bpmn })`** — owns the engine session and the reactive
   `snapshot` / `events` / `processIds` state, and exposes the engine commands
-  (`createInstance`, `completeJob`, `failJob`, `advanceTime`, `reset`).
+  (`createInstance`, `completeJob`, `failJob`, `advanceTime`, `reset`). Pass
+  `variant: "readmodel"` to also thread the gateway's read channel through the
+  hook — see [Read model](#read-model) below.
 - **`<BpmnRuntimeView xml activeIds incidentIds />`** — the live diagram: it
   imports the XML once and updates token (`nano-active`) / incident
   (`nano-incident`) markers in place, so zoom/scroll survive stepping.
@@ -71,6 +73,48 @@ For an agentic run, emit `TraceEntry` lines from your handlers (with the additiv
 unchanged. It never imports `bpmn-js`, so importing it alone won't pull the
 diagram bundle in.
 
+## Read model
+
+By default `useBojtos` loads the **lean** engine (primary state only). Pass
+`variant: "readmodel"` to load the read-model engine variant instead, which adds
+the gateway's Camunda-parity REST read channel. The returned controls then widen
+from `BojtosControls` to `ReadModelBojtosControls`, exposing five pull queries —
+`searchUserTasks`, `searchProcessInstances`, `searchVariables`, `getFormByKey`,
+`getResourceByKey` — plus a `readModelVersion` counter. The heavier read-model
+binary code-splits in only for `"readmodel"` hooks; a lean hook never downloads
+it.
+
+The read queries are **pull** projections of the read model, not part of the
+command→`snapshot` push loop, so they don't land in state on their own. Each read
+method returns `null` until the engine is ready (and on a lean hook), and
+`readModelVersion` bumps after every command / worker round / deploy / reset —
+i.e. whenever the read model may have moved. Make a query reactive with the
+ready-made `useReadModel` selector, which re-runs it keyed on `readModelVersion`:
+
+```tsx
+import { useBojtos, useReadModel } from "@nanobpm/bojtos-react";
+
+function ReviewInbox({ bpmn }: { bpmn: string }) {
+  const run = useBojtos({ bpmn, variant: "readmodel" });
+  // Re-runs after every command / round; `?? []` covers the not-ready null.
+  const openTasks = useReadModel(
+    run,
+    (rm) => rm.searchUserTasks('{"state":"CREATED"}')?.items ?? [],
+  );
+  return (
+    <ul>
+      {openTasks.map((t) => (
+        <li key={t.userTaskKey}>{t.elementId}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+You can also call the read methods imperatively (e.g. from an event handler)
+whenever you want a one-off answer — `useReadModel` is just the reactive wrapper
+over the same `readModelVersion` signal.
+
 ## Peer requirements
 
 `react` and `bpmn-js` are peer dependencies (the consumer already has them). The

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { useBojtos, type UseBojtosOptions, type BojtosControls, type BojtosPhase, } from "./useBojtos.js";
+export { useBojtos, useReadModel, type UseBojtosOptions, type BojtosControls, type ReadModelBojtosControls, type BojtosPhase, } from "./useBojtos.js";
 export { Bojtos, type BojtosProps, type TraceEvent } from "./Bojtos.js";
 export { OrderFulfillmentDemo, ORDER_FULFILLMENT_BPMN, orderFulfillmentWorkers, } from "./examples/orderFulfillment.js";
 export { BpmnRuntimeView, type BpmnRuntimeViewProps, } from "./BpmnRuntimeView.js";
 export { TraceTimeline, type TraceTimelineProps } from "./TraceTimeline.js";
-export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, } from "./runState.js";
+export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, resolveVariant, selectReadModel, } from "./runState.js";
 export { JobFailure, settleReason, unhandledJobTypes, buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, type SettleReason, } from "@nanobpm/bojtos-kit";
-export type { BojtosSession, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, UserTaskDto, MessageSubscriptionDto, SignalSubscriptionDto, ElementStatDto, SequenceFlowDto, DecisionInstanceDto, ActiveEl, ActivateInstruction, AgentActivation, AgentResult, WasmEvent, TraceRowKind, TraceEntry, TraceRow, TraceTurnGroup, TraceItem, TraceAdapter, } from "@nanobpm/bojtos-kit";
+export type { BojtosSession, ReadModelBojtosSession, EngineVariant, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, UserTaskDto, MessageSubscriptionDto, SignalSubscriptionDto, ElementStatDto, SequenceFlowDto, DecisionInstanceDto, ActiveEl, ActivateInstruction, AgentActivation, AgentResult, WasmEvent, TraceRowKind, TraceEntry, TraceRow, TraceTurnGroup, TraceItem, TraceAdapter, UserTaskSearchQueryResult, UserTaskResult, ProcessInstanceSearchQueryResult, ProcessInstanceResult, VariableSearchQueryResult, VariableResult, FormResult, ResourceResult, SearchQueryResponse, SearchQueryPageResponse, } from "@nanobpm/bojtos-kit";

package/dist/index.js

@@ -3,12 +3,12 @@
 // `<BpmnRuntimeView>` renders the live token/incident diagram. The engine's
 // snapshot/event contract types are re-exported from @nanobpm/bojtos-kit for
 // convenience.
-export { useBojtos, } from "./useBojtos.js";
+export { useBojtos, useReadModel, } from "./useBojtos.js";
 export { Bojtos } from "./Bojtos.js";
 export { OrderFulfillmentDemo, ORDER_FULFILLMENT_BPMN, orderFulfillmentWorkers, } from "./examples/orderFulfillment.js";
 export { BpmnRuntimeView, } from "./BpmnRuntimeView.js";
 // The shared activity log (#9). Trace-only imports tree-shake bpmn-js out —
 // TraceTimeline imports only the kit + React, never BpmnRuntimeView.
 export { TraceTimeline } from "./TraceTimeline.js";
-export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, } from "./runState.js";
+export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, resolveVariant, selectReadModel, } from "./runState.js";
 export { JobFailure, settleReason, unhandledJobTypes, buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } from "@nanobpm/bojtos-kit";

package/dist/runState.d.ts

@@ -7,6 +7,24 @@
  * a run reads aloud, which resources to deploy and how far to trim the log are
  * decisions, and decisions are worth testing.
  */
+import type { EngineVariant } from "@nanobpm/bojtos-kit";
+/**
+ * The engine variant a hook run should use, defaulting to `"lean"` when the
+ * consumer didn't pick one. Keeping the default here (rather than a parameter
+ * default) makes the "no `variant` means lean, so existing consumers are
+ * unaffected" decision a single testable fact instead of an inline `?? "lean"`
+ * scattered through the hook.
+ */
+export declare function resolveVariant(variant: EngineVariant | undefined): EngineVariant;
+/**
+ * Pull a value out of the read-model channel, or `null` when there is no live
+ * read-model session (loading, a lean-variant hook, or between a teardown and
+ * the next engine). This is the one place the "no session → null, otherwise run
+ * the query" decision lives, shared by every reactive read method so a
+ * lean-variant call or a mid-load call is a quiet `null` rather than a throw on
+ * a missing engine.
+ */
+export declare function selectReadModel<C, T>(channel: C | null, select: (channel: C) => T): T | null;
 /**
  * Stable key for a marker set, so unchanged ids don't re-paint the diagram.
  *

package/dist/runState.js

@@ -7,6 +7,27 @@
  * a run reads aloud, which resources to deploy and how far to trim the log are
  * decisions, and decisions are worth testing.
  */
+/**
+ * The engine variant a hook run should use, defaulting to `"lean"` when the
+ * consumer didn't pick one. Keeping the default here (rather than a parameter
+ * default) makes the "no `variant` means lean, so existing consumers are
+ * unaffected" decision a single testable fact instead of an inline `?? "lean"`
+ * scattered through the hook.
+ */
+export function resolveVariant(variant) {
+    return variant ?? "lean";
+}
+/**
+ * Pull a value out of the read-model channel, or `null` when there is no live
+ * read-model session (loading, a lean-variant hook, or between a teardown and
+ * the next engine). This is the one place the "no session → null, otherwise run
+ * the query" decision lives, shared by every reactive read method so a
+ * lean-variant call or a mid-load call is a quiet `null` rather than a throw on
+ * a missing engine.
+ */
+export function selectReadModel(channel, select) {
+    return channel === null ? null : select(channel);
+}
 /**
  * Stable key for a marker set, so unchanged ids don't re-paint the diagram.
  *

package/dist/useBojtos.d.ts

@@ -1,4 +1,4 @@
-import { type ActivateInstruction, type AgentResult, type DispatchOptions, type JobHandler, type RoundResult, type Snapshot, type WasmEvent, type WasmSource } from "@nanobpm/bojtos-kit";
+import { type ActivateInstruction, type AgentResult, type DispatchOptions, type EngineVariant, type FormResult, type JobHandler, type ProcessInstanceSearchQueryResult, type ResourceResult, type RoundResult, type Snapshot, type UserTaskSearchQueryResult, type VariableSearchQueryResult, type WasmEvent, type WasmSource } from "@nanobpm/bojtos-kit";
 /** Lifecycle of the in-browser engine load. */
 export type BojtosPhase = "loading" | "ready" | "error";
 export interface UseBojtosOptions {
@@ -29,6 +29,22 @@ export interface UseBojtosOptions {
      * whole log, which stays the default so existing consumers are unaffected.
      */
     maxEvents?: number;
+    /**
+     * Which engine variant to load, defaulting to `"lean"` — existing consumers
+     * are unaffected. Pass `"readmodel"` to also thread the gateway's
+     * Camunda-parity REST read channel through the hook: the returned controls
+     * then widen to {@link ReadModelBojtosControls}, exposing `searchUserTasks` /
+     * `searchProcessInstances` / `searchVariables` / `getFormByKey` /
+     * `getResourceByKey` plus the `readModelVersion` reactivity signal.
+     *
+     * Init-time only, like `wasm`: the variant is read when the session is first
+     * created for a given diagram, so changing it later has no effect until the
+     * next `bpmn` change re-creates the engine.
+     *
+     * The read-model binary is heavier and only code-splits in when this is
+     * `"readmodel"` (ADR 0043 §3); a lean hook never downloads it.
+     */
+    variant?: EngineVariant;
 }
 export interface BojtosControls {
     phase: BojtosPhase;
@@ -132,6 +148,69 @@ export interface BojtosControls {
     /** Re-deploy the diagram on the existing engine, clearing run state. */
     reset(): void;
 }
+/**
+ * The {@link BojtosControls} of a `readmodel`-variant hook: the full command
+ * surface **plus** reactive access to the gateway's Camunda-parity REST read
+ * channel. You get one by passing `variant: "readmodel"` to {@link useBojtos},
+ * which widens the return type from `BojtosControls` to this.
+ *
+ * ## Reactivity model
+ *
+ * The read queries are **pull** projections of the read model, not part of the
+ * command→`snapshot` push loop: `searchUserTasks` et al. answer "what does the
+ * read model say *right now*", and there is no single obvious cadence at which
+ * to re-run them (a consumer may care about tasks, another about variables, each
+ * with its own filter). So rather than eagerly re-running every query after
+ * every command and stuffing five results into state, the hook exposes:
+ *
+ * - the five read methods as **imperative pulls** — call one whenever you want a
+ *   fresh answer; each returns `null` before the engine is ready rather than
+ *   throwing, and
+ * - {@link readModelVersion}, a counter bumped after **every** command / worker
+ *   round (i.e. whenever the read model may have moved), so a consumer can make
+ *   a query reactive by keying a `useMemo`/`useEffect` on it — or just let
+ *   {@link useReadModel} do exactly that.
+ *
+ * This keeps the read channel opt-in and filter-agnostic while still landing its
+ * results in React state on the consumer's terms.
+ */
+export interface ReadModelBojtosControls extends BojtosControls {
+    /**
+     * Search user tasks through the read model (mirrors `POST
+     * /user-tasks/search`). Returns `null` until the engine is ready. Honours an
+     * optional `{ state? }` filter, e.g. `searchUserTasks('{"state":"CREATED"}')`.
+     */
+    searchUserTasks(filterJson?: string): UserTaskSearchQueryResult | null;
+    /**
+     * Search process instances through the read model (mirrors `POST
+     * /process-instances/search`). Returns `null` until the engine is ready.
+     */
+    searchProcessInstances(filterJson?: string): ProcessInstanceSearchQueryResult | null;
+    /**
+     * Search variables through the read model (mirrors `POST
+     * /variables/search`). Returns `null` until the engine is ready.
+     */
+    searchVariables(filterJson?: string): VariableSearchQueryResult | null;
+    /**
+     * The latest deployed form for `formKey` (mirrors `GET /forms/{formKey}`), or
+     * `null` if none exists — also `null` until the engine is ready.
+     */
+    getFormByKey(formKey: string): FormResult | null;
+    /**
+     * The generic resource for `resourceKey` (mirrors `GET
+     * /resources/{resourceKey}`), or `null` if none exists — also `null` until the
+     * engine is ready.
+     */
+    getResourceByKey(resourceKey: string): ResourceResult | null;
+    /**
+     * A monotonically increasing counter bumped after every command / worker round
+     * (and on deploy / reset). It is the reactivity signal for the pull read
+     * queries: key a `useMemo`/`useEffect` on it to re-run a query when the read
+     * model may have changed. {@link useReadModel} is the ready-made selector over
+     * it.
+     */
+    readModelVersion: number;
+}
 /**
  * React binding over a headless {@link BojtosSession}: owns the engine's
  * lifecycle and the reactive `snapshot` / `events` / `processIds` state, and
@@ -142,5 +221,38 @@ export interface BojtosControls {
  * This is the reactive half of the Bojtos public API (ADR 0043 §2); the console
  * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
  * test).
+ *
+ * With `variant: "readmodel"` the return type widens to
+ * {@link ReadModelBojtosControls}, adding the read channel + `readModelVersion`;
+ * the default `"lean"` variant returns the plain {@link BojtosControls} and never
+ * downloads the heavier read-model binary.
+ */
+export declare function useBojtos(options: UseBojtosOptions & {
+    variant: "readmodel";
+}): ReadModelBojtosControls;
+export declare function useBojtos(options: UseBojtosOptions & {
+    variant?: "lean";
+}): BojtosControls;
+export declare function useBojtos(options: UseBojtosOptions): BojtosControls | ReadModelBojtosControls;
+/**
+ * Reactively project a value out of a `readmodel` hook's read channel, re-run
+ * whenever the read model may have moved.
+ *
+ * The read queries are pull projections (see {@link ReadModelBojtosControls}),
+ * so this is the ready-made "selector" that lands their result in React state on
+ * your terms: pass the `readmodel` {@link useBojtos} controls and a `select`
+ * that calls whichever read methods you care about (with whatever filters), and
+ * the memoized result re-computes each time `readModelVersion` bumps — i.e.
+ * after every command / worker round / deploy / reset — or the load `phase`
+ * flips. Before the engine is ready the read methods return `null`, so a
+ * selector must tolerate nulls.
+ *
+ * ```tsx
+ * const run = useBojtos({ bpmn, variant: "readmodel" });
+ * const openTasks = useReadModel(
+ *   run,
+ *   (rm) => rm.searchUserTasks('{"state":"CREATED"}')?.items ?? [],
+ * );
+ * ```
  */
-export declare function useBojtos({ bpmn, wasm, maxEvents, }: UseBojtosOptions): BojtosControls;
+export declare function useReadModel<T>(controls: ReadModelBojtosControls, select: (controls: ReadModelBojtosControls) => T): T;

package/dist/useBojtos.js

@@ -1,24 +1,27 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { createBojtosSession, dispatchRound, dispatchWorkers, } from "@nanobpm/bojtos-kit";
-import { bpmnKey, capEvents, resourceList } from "./runState.js";
-/**
- * React binding over a headless {@link BojtosSession}: owns the engine's
- * lifecycle and the reactive `snapshot` / `events` / `processIds` state, and
- * exposes the engine commands. The consuming component owns its own form state
- * (selected process, seed vars, per-job output) and drives the visual contract
- * (`<BpmnRuntimeView>` + the variable payload) off `snapshot`.
- *
- * This is the reactive half of the Bojtos public API (ADR 0043 §2); the console
- * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
- * test).
- */
-export function useBojtos({ bpmn, wasm, maxEvents, }) {
+import { bpmnKey, capEvents, resolveVariant, resourceList, selectReadModel, } from "./runState.js";
+export function useBojtos({ bpmn, wasm, maxEvents, variant, }) {
     const sessionRef = useRef(null);
+    // The same session, narrowed to its read channel, but only when we actually
+    // asked for the `readmodel` variant. Kept as its own ref (rather than casting
+    // `sessionRef`) so the read methods reach the query surface without a cast — a
+    // lean session simply leaves this null and every read pull returns null.
+    const readModelRef = useRef(null);
     const [phase, setPhase] = useState("loading");
     const [error, setError] = useState(null);
     const [processIds, setProcessIds] = useState([]);
     const [snapshot, setSnapshot] = useState(null);
     const [events, setEvents] = useState([]);
+    // Bumped whenever the read model may have moved (any command / round / deploy /
+    // reset) so pull read queries can be made reactive by keying on it.
+    const [readModelVersion, setReadModelVersion] = useState(0);
+    const bumpReadModel = useCallback(() => setReadModelVersion((v) => v + 1), []);
+    // The variant is an init-time concern like `wasm` (read when a session is
+    // first created for a diagram), so keep it in a ref rather than the deploy
+    // effect's deps.
+    const variantRef = useRef(variant);
+    variantRef.current = variant;
     // The wasm source is an init-time concern (the first `ensureWasm` wins), so
     // keep it in a ref rather than the mount effect's deps — a fresh URL/bytes
     // identity each render must not re-create the session.
@@ -47,6 +50,9 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
         setSnapshot(null);
         setEvents([]);
         setError(null);
+        // The read model was just wiped and re-seeded by the redeploy, so any
+        // reactive read query must re-run.
+        bumpReadModel();
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [deployKey]);
@@ -61,7 +67,14 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
         setSnapshot(null);
         setEvents([]);
         setError(null);
-        createBojtosSession({ wasm: wasmRef.current })
+        // Resolve the session with the requested variant. The `readmodel` branch
+        // keeps the narrowed `ReadModelBojtosSession` so the read methods reach the
+        // query surface without a cast; the lean branch leaves `readModelRef` null.
+        const variant = resolveVariant(variantRef.current);
+        const pending = variant === "readmodel"
+            ? createBojtosSession({ wasm: wasmRef.current, variant: "readmodel" })
+            : createBojtosSession({ wasm: wasmRef.current });
+        pending
             .then((session) => {
             if (cancelled) {
                 session.free();
@@ -80,6 +93,8 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
                 return;
             }
             sessionRef.current = session;
+            readModelRef.current =
+                variant === "readmodel" ? session : null;
             setPhase("ready");
         })
             .catch((e) => {
@@ -92,6 +107,7 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             cancelled = true;
             sessionRef.current?.free();
             sessionRef.current = null;
+            readModelRef.current = null;
         };
     }, [deployInto]);
     const run = useCallback((fn) => {
@@ -103,13 +119,15 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             setSnapshot(snap);
             setEvents(readEvents(session));
             setError(null);
+            // A command may have moved the read model; signal reactive readers.
+            bumpReadModel();
             return snap;
         }
         catch (e) {
             setError(String(e));
             return null;
         }
-    }, []);
+    }, [bumpReadModel, readEvents]);
     const createInstance = useCallback((processId, variablesJson) => run((s) => s.createInstance(processId, variablesJson)), [run]);
     const completeJob = useCallback((jobKey, variablesJson) => run((s) => s.completeJob(jobKey, variablesJson)), [run]);
     const completeAgentJob = useCallback((jobKey, result) => run((s) => s.completeAgentJob(jobKey, result)), [run]);
@@ -140,6 +158,7 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             setSnapshot(settled);
             setEvents(readEvents(session));
             setError(null);
+            bumpReadModel();
             return settled;
         }
         catch (e) {
@@ -150,9 +169,10 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             setSnapshot(session.snapshot());
             setEvents(readEvents(session));
             setError(String(e));
+            bumpReadModel();
             return null;
         }
-    }, []);
+    }, [bumpReadModel, readEvents]);
     const stepWorkers = useCallback(async (workers, opts) => {
         const session = sessionRef.current;
         if (!session)
@@ -165,6 +185,7 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             setSnapshot(round.snapshot);
             setEvents(readEvents(session));
             setError(null);
+            bumpReadModel();
             return round;
         }
         catch (e) {
@@ -173,9 +194,10 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             setSnapshot(session.snapshot());
             setEvents(readEvents(session));
             setError(String(e));
+            bumpReadModel();
             return null;
         }
-    }, []);
+    }, [bumpReadModel, readEvents]);
     const reset = useCallback(() => {
         const session = sessionRef.current;
         if (!session)
@@ -191,6 +213,16 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
             setError(String(e));
         }
     }, [deployInto]);
+    // The read channel. Each pull returns null when there is no live read-model
+    // session (loading, or a lean-variant hook), via the shared `selectReadModel`
+    // guard, rather than throwing on a missing engine. They intentionally do not
+    // touch React state themselves — reactivity is opt-in through
+    // `readModelVersion` / `useReadModel` (see `ReadModelBojtosControls`).
+    const searchUserTasks = useCallback((filterJson) => selectReadModel(readModelRef.current, (rm) => rm.searchUserTasks(filterJson)), []);
+    const searchProcessInstances = useCallback((filterJson) => selectReadModel(readModelRef.current, (rm) => rm.searchProcessInstances(filterJson)), []);
+    const searchVariables = useCallback((filterJson) => selectReadModel(readModelRef.current, (rm) => rm.searchVariables(filterJson)), []);
+    const getFormByKey = useCallback((formKey) => selectReadModel(readModelRef.current, (rm) => rm.getFormByKey(formKey)), []);
+    const getResourceByKey = useCallback((resourceKey) => selectReadModel(readModelRef.current, (rm) => rm.getResourceByKey(resourceKey)), []);
     return {
         phase,
         error,
@@ -217,5 +249,44 @@ export function useBojtos({ bpmn, wasm, maxEvents, }) {
         runWorkers,
         stepWorkers,
         reset,
+        searchUserTasks,
+        searchProcessInstances,
+        searchVariables,
+        getFormByKey,
+        getResourceByKey,
+        readModelVersion,
     };
 }
+/**
+ * Reactively project a value out of a `readmodel` hook's read channel, re-run
+ * whenever the read model may have moved.
+ *
+ * The read queries are pull projections (see {@link ReadModelBojtosControls}),
+ * so this is the ready-made "selector" that lands their result in React state on
+ * your terms: pass the `readmodel` {@link useBojtos} controls and a `select`
+ * that calls whichever read methods you care about (with whatever filters), and
+ * the memoized result re-computes each time `readModelVersion` bumps — i.e.
+ * after every command / worker round / deploy / reset — or the load `phase`
+ * flips. Before the engine is ready the read methods return `null`, so a
+ * selector must tolerate nulls.
+ *
+ * ```tsx
+ * const run = useBojtos({ bpmn, variant: "readmodel" });
+ * const openTasks = useReadModel(
+ *   run,
+ *   (rm) => rm.searchUserTasks('{"state":"CREATED"}')?.items ?? [],
+ * );
+ * ```
+ */
+export function useReadModel(controls, select) {
+    // Keep the latest selector and controls without making them memo dependencies:
+    // re-running is driven by the read model moving (`readModelVersion`) / readiness
+    // (`phase`), not by a fresh inline selector or a fresh `controls` object literal
+    // (`useBojtos` returns a new object each render, so depending on it directly would
+    // re-run the selector on *every* parent re-render).
+    const selectRef = useRef(select);
+    selectRef.current = select;
+    const controlsRef = useRef(controls);
+    controlsRef.current = controls;
+    return useMemo(() => selectRef.current(controlsRef.current), [controls.readModelVersion, controls.phase]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "React binding for the Bojtos in-browser BPMN demo framework (ADR 0043): the useBojtos hook (owns the engine session + reactive snapshot/event state) and the <BpmnRuntimeView> live token/incident diagram. Built on @nanobpm/bojtos-kit; the console test-run panel is its first consumer.",
   "type": "module",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "test:ci": "node --experimental-strip-types --test test/*.test.ts"
   },
   "dependencies": {
-    "@nanobpm/bojtos-kit": "^0.7.0"
+    "@nanobpm/bojtos-kit": "^0.8.0"
   },
   "peerDependencies": {
     "bpmn-js": ">=17",

package/src/index.ts

@@ -6,8 +6,10 @@
 
 export {
   useBojtos,
+  useReadModel,
   type UseBojtosOptions,
   type BojtosControls,
+  type ReadModelBojtosControls,
   type BojtosPhase,
 } from "./useBojtos.js";
 export { Bojtos, type BojtosProps, type TraceEvent } from "./Bojtos.js";
@@ -29,6 +31,8 @@ export {
   bpmnKey,
   resourceList,
   capEvents,
+  resolveVariant,
+  selectReadModel,
 } from "./runState.js";
 export {
   JobFailure,
@@ -48,6 +52,8 @@ export {
 } from "@nanobpm/bojtos-kit";
 export type {
   BojtosSession,
+  ReadModelBojtosSession,
+  EngineVariant,
   Snapshot,
   InstanceDto,
   JobDto,
@@ -71,4 +77,14 @@ export type {
   TraceTurnGroup,
   TraceItem,
   TraceAdapter,
+  UserTaskSearchQueryResult,
+  UserTaskResult,
+  ProcessInstanceSearchQueryResult,
+  ProcessInstanceResult,
+  VariableSearchQueryResult,
+  VariableResult,
+  FormResult,
+  ResourceResult,
+  SearchQueryResponse,
+  SearchQueryPageResponse,
 } from "@nanobpm/bojtos-kit";

package/src/runState.ts

@@ -8,6 +8,36 @@
  * decisions, and decisions are worth testing.
  */
 
+import type { EngineVariant } from "@nanobpm/bojtos-kit";
+
+/**
+ * The engine variant a hook run should use, defaulting to `"lean"` when the
+ * consumer didn't pick one. Keeping the default here (rather than a parameter
+ * default) makes the "no `variant` means lean, so existing consumers are
+ * unaffected" decision a single testable fact instead of an inline `?? "lean"`
+ * scattered through the hook.
+ */
+export function resolveVariant(
+  variant: EngineVariant | undefined,
+): EngineVariant {
+  return variant ?? "lean";
+}
+
+/**
+ * Pull a value out of the read-model channel, or `null` when there is no live
+ * read-model session (loading, a lean-variant hook, or between a teardown and
+ * the next engine). This is the one place the "no session → null, otherwise run
+ * the query" decision lives, shared by every reactive read method so a
+ * lean-variant call or a mid-load call is a quiet `null` rather than a throw on
+ * a missing engine.
+ */
+export function selectReadModel<C, T>(
+  channel: C | null,
+  select: (channel: C) => T,
+): T | null {
+  return channel === null ? null : select(channel);
+}
+
 /**
  * Stable key for a marker set, so unchanged ids don't re-paint the diagram.
  *

package/src/useBojtos.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   type ActivateInstruction,
   type AgentResult,
@@ -7,13 +7,26 @@ import {
   type DispatchOptions,
   dispatchRound,
   dispatchWorkers,
+  type EngineVariant,
+  type FormResult,
   type JobHandler,
+  type ProcessInstanceSearchQueryResult,
+  type ReadModelBojtosSession,
+  type ResourceResult,
   type RoundResult,
   type Snapshot,
+  type UserTaskSearchQueryResult,
+  type VariableSearchQueryResult,
   type WasmEvent,
   type WasmSource,
 } from "@nanobpm/bojtos-kit";
-import { bpmnKey, capEvents, resourceList } from "./runState.js";
+import {
+  bpmnKey,
+  capEvents,
+  resolveVariant,
+  resourceList,
+  selectReadModel,
+} from "./runState.js";
 
 /** Lifecycle of the in-browser engine load. */
 export type BojtosPhase = "loading" | "ready" | "error";
@@ -46,6 +59,22 @@ export interface UseBojtosOptions {
    * whole log, which stays the default so existing consumers are unaffected.
    */
   maxEvents?: number;
+  /**
+   * Which engine variant to load, defaulting to `"lean"` — existing consumers
+   * are unaffected. Pass `"readmodel"` to also thread the gateway's
+   * Camunda-parity REST read channel through the hook: the returned controls
+   * then widen to {@link ReadModelBojtosControls}, exposing `searchUserTasks` /
+   * `searchProcessInstances` / `searchVariables` / `getFormByKey` /
+   * `getResourceByKey` plus the `readModelVersion` reactivity signal.
+   *
+   * Init-time only, like `wasm`: the variant is read when the session is first
+   * created for a given diagram, so changing it later has no effect until the
+   * next `bpmn` change re-creates the engine.
+   *
+   * The read-model binary is heavier and only code-splits in when this is
+   * `"readmodel"` (ADR 0043 §3); a lean hook never downloads it.
+   */
+  variant?: EngineVariant;
 }
 
 export interface BojtosControls {
@@ -177,6 +206,72 @@ export interface BojtosControls {
   reset(): void;
 }
 
+/**
+ * The {@link BojtosControls} of a `readmodel`-variant hook: the full command
+ * surface **plus** reactive access to the gateway's Camunda-parity REST read
+ * channel. You get one by passing `variant: "readmodel"` to {@link useBojtos},
+ * which widens the return type from `BojtosControls` to this.
+ *
+ * ## Reactivity model
+ *
+ * The read queries are **pull** projections of the read model, not part of the
+ * command→`snapshot` push loop: `searchUserTasks` et al. answer "what does the
+ * read model say *right now*", and there is no single obvious cadence at which
+ * to re-run them (a consumer may care about tasks, another about variables, each
+ * with its own filter). So rather than eagerly re-running every query after
+ * every command and stuffing five results into state, the hook exposes:
+ *
+ * - the five read methods as **imperative pulls** — call one whenever you want a
+ *   fresh answer; each returns `null` before the engine is ready rather than
+ *   throwing, and
+ * - {@link readModelVersion}, a counter bumped after **every** command / worker
+ *   round (i.e. whenever the read model may have moved), so a consumer can make
+ *   a query reactive by keying a `useMemo`/`useEffect` on it — or just let
+ *   {@link useReadModel} do exactly that.
+ *
+ * This keeps the read channel opt-in and filter-agnostic while still landing its
+ * results in React state on the consumer's terms.
+ */
+export interface ReadModelBojtosControls extends BojtosControls {
+  /**
+   * Search user tasks through the read model (mirrors `POST
+   * /user-tasks/search`). Returns `null` until the engine is ready. Honours an
+   * optional `{ state? }` filter, e.g. `searchUserTasks('{"state":"CREATED"}')`.
+   */
+  searchUserTasks(filterJson?: string): UserTaskSearchQueryResult | null;
+  /**
+   * Search process instances through the read model (mirrors `POST
+   * /process-instances/search`). Returns `null` until the engine is ready.
+   */
+  searchProcessInstances(
+    filterJson?: string,
+  ): ProcessInstanceSearchQueryResult | null;
+  /**
+   * Search variables through the read model (mirrors `POST
+   * /variables/search`). Returns `null` until the engine is ready.
+   */
+  searchVariables(filterJson?: string): VariableSearchQueryResult | null;
+  /**
+   * The latest deployed form for `formKey` (mirrors `GET /forms/{formKey}`), or
+   * `null` if none exists — also `null` until the engine is ready.
+   */
+  getFormByKey(formKey: string): FormResult | null;
+  /**
+   * The generic resource for `resourceKey` (mirrors `GET
+   * /resources/{resourceKey}`), or `null` if none exists — also `null` until the
+   * engine is ready.
+   */
+  getResourceByKey(resourceKey: string): ResourceResult | null;
+  /**
+   * A monotonically increasing counter bumped after every command / worker round
+   * (and on deploy / reset). It is the reactivity signal for the pull read
+   * queries: key a `useMemo`/`useEffect` on it to re-run a query when the read
+   * model may have changed. {@link useReadModel} is the ready-made selector over
+   * it.
+   */
+  readModelVersion: number;
+}
+
 /**
  * Session members the hook deliberately does not re-export: the deployment
  * lifecycle it owns itself, and the low-level activate primitive the dispatch
@@ -200,6 +295,20 @@ type UnboundCommands = Exclude<
 type AssertNever<T extends never> = T;
 type _EverySessionCommandIsBound = AssertNever<UnboundCommands>;
 
+/**
+ * The same guard for the widened `readmodel` surface: every method of a
+ * {@link ReadModelBojtosSession} — the lean commands **and** the five read
+ * queries — must be bound on {@link ReadModelBojtosControls}, or a `readmodel`
+ * hook would silently drop part of the read channel (the exact failure mode #1
+ * described, now covering the read methods too). Adding a read query to the
+ * session without binding it here fails the build with its name.
+ */
+type UnboundReadModelCommands = Exclude<
+  keyof ReadModelBojtosSession,
+  NotReExported | keyof ReadModelBojtosControls
+>;
+type _EveryReadModelCommandIsBound = AssertNever<UnboundReadModelCommands>;
+
 /**
  * React binding over a headless {@link BojtosSession}: owns the engine's
  * lifecycle and the reactive `snapshot` / `events` / `processIds` state, and
@@ -210,18 +319,51 @@ type _EverySessionCommandIsBound = AssertNever<UnboundCommands>;
  * This is the reactive half of the Bojtos public API (ADR 0043 §2); the console
  * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
  * test).
+ *
+ * With `variant: "readmodel"` the return type widens to
+ * {@link ReadModelBojtosControls}, adding the read channel + `readModelVersion`;
+ * the default `"lean"` variant returns the plain {@link BojtosControls} and never
+ * downloads the heavier read-model binary.
  */
+export function useBojtos(
+  options: UseBojtosOptions & { variant: "readmodel" },
+): ReadModelBojtosControls;
+export function useBojtos(
+  options: UseBojtosOptions & { variant?: "lean" },
+): BojtosControls;
+export function useBojtos(
+  options: UseBojtosOptions,
+): BojtosControls | ReadModelBojtosControls;
 export function useBojtos({
   bpmn,
   wasm,
   maxEvents,
-}: UseBojtosOptions): BojtosControls {
+  variant,
+}: UseBojtosOptions): ReadModelBojtosControls {
   const sessionRef = useRef<BojtosSession | null>(null);
+  // The same session, narrowed to its read channel, but only when we actually
+  // asked for the `readmodel` variant. Kept as its own ref (rather than casting
+  // `sessionRef`) so the read methods reach the query surface without a cast — a
+  // lean session simply leaves this null and every read pull returns null.
+  const readModelRef = useRef<ReadModelBojtosSession | null>(null);
   const [phase, setPhase] = useState<BojtosPhase>("loading");
   const [error, setError] = useState<string | null>(null);
   const [processIds, setProcessIds] = useState<string[]>([]);
   const [snapshot, setSnapshot] = useState<Snapshot | null>(null);
   const [events, setEvents] = useState<WasmEvent[]>([]);
+  // Bumped whenever the read model may have moved (any command / round / deploy /
+  // reset) so pull read queries can be made reactive by keying on it.
+  const [readModelVersion, setReadModelVersion] = useState(0);
+  const bumpReadModel = useCallback(
+    () => setReadModelVersion((v) => v + 1),
+    [],
+  );
+
+  // The variant is an init-time concern like `wasm` (read when a session is
+  // first created for a diagram), so keep it in a ref rather than the deploy
+  // effect's deps.
+  const variantRef = useRef(variant);
+  variantRef.current = variant;
 
   // The wasm source is an init-time concern (the first `ensureWasm` wins), so
   // keep it in a ref rather than the mount effect's deps — a fresh URL/bytes
@@ -254,6 +396,9 @@ export function useBojtos({
       setSnapshot(null);
       setEvents([]);
       setError(null);
+      // The read model was just wiped and re-seeded by the redeploy, so any
+      // reactive read query must re-run.
+      bumpReadModel();
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [deployKey],
@@ -270,7 +415,15 @@ export function useBojtos({
     setSnapshot(null);
     setEvents([]);
     setError(null);
-    createBojtosSession({ wasm: wasmRef.current })
+    // Resolve the session with the requested variant. The `readmodel` branch
+    // keeps the narrowed `ReadModelBojtosSession` so the read methods reach the
+    // query surface without a cast; the lean branch leaves `readModelRef` null.
+    const variant = resolveVariant(variantRef.current);
+    const pending =
+      variant === "readmodel"
+        ? createBojtosSession({ wasm: wasmRef.current, variant: "readmodel" })
+        : createBojtosSession({ wasm: wasmRef.current });
+    pending
       .then((session) => {
         if (cancelled) {
           session.free();
@@ -288,6 +441,8 @@ export function useBojtos({
           return;
         }
         sessionRef.current = session;
+        readModelRef.current =
+          variant === "readmodel" ? (session as ReadModelBojtosSession) : null;
         setPhase("ready");
       })
       .catch((e) => {
@@ -299,6 +454,7 @@ export function useBojtos({
       cancelled = true;
       sessionRef.current?.free();
       sessionRef.current = null;
+      readModelRef.current = null;
     };
   }, [deployInto]);
 
@@ -311,13 +467,15 @@ export function useBojtos({
         setSnapshot(snap);
         setEvents(readEvents(session));
         setError(null);
+        // A command may have moved the read model; signal reactive readers.
+        bumpReadModel();
         return snap;
       } catch (e) {
         setError(String(e));
         return null;
       }
     },
-    [],
+    [bumpReadModel, readEvents],
   );
 
   const createInstance = useCallback(
@@ -431,6 +589,7 @@ export function useBojtos({
         setSnapshot(settled);
         setEvents(readEvents(session));
         setError(null);
+        bumpReadModel();
         return settled;
       } catch (e) {
         if (sessionRef.current !== session) return null;
@@ -439,10 +598,11 @@ export function useBojtos({
         setSnapshot(session.snapshot());
         setEvents(readEvents(session));
         setError(String(e));
+        bumpReadModel();
         return null;
       }
     },
-    [],
+    [bumpReadModel, readEvents],
   );
 
   const stepWorkers = useCallback(
@@ -459,16 +619,18 @@ export function useBojtos({
         setSnapshot(round.snapshot);
         setEvents(readEvents(session));
         setError(null);
+        bumpReadModel();
         return round;
       } catch (e) {
         if (sessionRef.current !== session) return null;
         setSnapshot(session.snapshot());
         setEvents(readEvents(session));
         setError(String(e));
+        bumpReadModel();
         return null;
       }
     },
-    [],
+    [bumpReadModel, readEvents],
   );
 
   const reset = useCallback(() => {
@@ -485,6 +647,45 @@ export function useBojtos({
     }
   }, [deployInto]);
 
+  // The read channel. Each pull returns null when there is no live read-model
+  // session (loading, or a lean-variant hook), via the shared `selectReadModel`
+  // guard, rather than throwing on a missing engine. They intentionally do not
+  // touch React state themselves — reactivity is opt-in through
+  // `readModelVersion` / `useReadModel` (see `ReadModelBojtosControls`).
+  const searchUserTasks = useCallback(
+    (filterJson?: string) =>
+      selectReadModel(readModelRef.current, (rm) =>
+        rm.searchUserTasks(filterJson),
+      ),
+    [],
+  );
+  const searchProcessInstances = useCallback(
+    (filterJson?: string) =>
+      selectReadModel(readModelRef.current, (rm) =>
+        rm.searchProcessInstances(filterJson),
+      ),
+    [],
+  );
+  const searchVariables = useCallback(
+    (filterJson?: string) =>
+      selectReadModel(readModelRef.current, (rm) =>
+        rm.searchVariables(filterJson),
+      ),
+    [],
+  );
+  const getFormByKey = useCallback(
+    (formKey: string) =>
+      selectReadModel(readModelRef.current, (rm) => rm.getFormByKey(formKey)),
+    [],
+  );
+  const getResourceByKey = useCallback(
+    (resourceKey: string) =>
+      selectReadModel(readModelRef.current, (rm) =>
+        rm.getResourceByKey(resourceKey),
+      ),
+    [],
+  );
+
   return {
     phase,
     error,
@@ -511,5 +712,51 @@ export function useBojtos({
     runWorkers,
     stepWorkers,
     reset,
+    searchUserTasks,
+    searchProcessInstances,
+    searchVariables,
+    getFormByKey,
+    getResourceByKey,
+    readModelVersion,
   };
 }
+
+/**
+ * Reactively project a value out of a `readmodel` hook's read channel, re-run
+ * whenever the read model may have moved.
+ *
+ * The read queries are pull projections (see {@link ReadModelBojtosControls}),
+ * so this is the ready-made "selector" that lands their result in React state on
+ * your terms: pass the `readmodel` {@link useBojtos} controls and a `select`
+ * that calls whichever read methods you care about (with whatever filters), and
+ * the memoized result re-computes each time `readModelVersion` bumps — i.e.
+ * after every command / worker round / deploy / reset — or the load `phase`
+ * flips. Before the engine is ready the read methods return `null`, so a
+ * selector must tolerate nulls.
+ *
+ * ```tsx
+ * const run = useBojtos({ bpmn, variant: "readmodel" });
+ * const openTasks = useReadModel(
+ *   run,
+ *   (rm) => rm.searchUserTasks('{"state":"CREATED"}')?.items ?? [],
+ * );
+ * ```
+ */
+export function useReadModel<T>(
+  controls: ReadModelBojtosControls,
+  select: (controls: ReadModelBojtosControls) => T,
+): T {
+  // Keep the latest selector and controls without making them memo dependencies:
+  // re-running is driven by the read model moving (`readModelVersion`) / readiness
+  // (`phase`), not by a fresh inline selector or a fresh `controls` object literal
+  // (`useBojtos` returns a new object each render, so depending on it directly would
+  // re-run the selector on *every* parent re-render).
+  const selectRef = useRef(select);
+  selectRef.current = select;
+  const controlsRef = useRef(controls);
+  controlsRef.current = controls;
+  return useMemo(
+    () => selectRef.current(controlsRef.current),
+    [controls.readModelVersion, controls.phase],
+  );
+}