@nanobpm/bojtos-react 0.4.0 → 0.5.0

package/README.md

@@ -51,6 +51,7 @@ consumer must import bpmn-js's diagram CSS once and provide the `.nano-active` /
 ## Build
 
 `dist/` (the tsc-emitted JS + `.d.ts`, with JSX already compiled to
-`react/jsx-runtime` so consumers never re-transform node_modules) is committed
-so `file:` consumers and CI need no build-on-install step. Regenerate with
+`react/jsx-runtime` so consumers never re-transform node_modules) is what ships,
+built by `prepack` on publish. It is **not** committed — `.gitignore` covers it —
+so build before pointing a `file:` consumer at this workspace. Regenerate with
 `npm run build`.

package/dist/BpmnRuntimeView.d.ts

@@ -7,6 +7,17 @@ export interface BpmnRuntimeViewProps {
     incidentIds: string[];
     /** Optional class for the container element (it always fills its parent). */
     className?: string;
+    /**
+     * Accessible name for the diagram. The token and incident highlights are
+     * purely visual, so without this a screen-reader user is told nothing at all
+     * about what is running.
+     */
+    label?: string;
+    /**
+     * Map an element id to a human name for the live status announcement — pass
+     * the diagram's element names if you have them. Defaults to the raw id.
+     */
+    elementName?: (elementId: string) => string;
 }
 /**
  * Read-only diagram that imports the XML once and updates token/incident markers
@@ -20,4 +31,4 @@ export interface BpmnRuntimeViewProps {
  * and provide the `.nano-active` / `.nano-incident` marker styles plus a
  * `.nano-token` style for the token badge overlaid on each active element.
  */
-export declare function BpmnRuntimeView({ xml, activeIds, incidentIds, className, }: BpmnRuntimeViewProps): import("react").JSX.Element;
+export declare function BpmnRuntimeView({ xml, activeIds, incidentIds, className, label, elementName, }: BpmnRuntimeViewProps): import("react").JSX.Element;

package/dist/BpmnRuntimeView.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import NavigatedViewer from "bpmn-js/lib/NavigatedViewer";
+import { describeRunState, markerKey } from "./runState.js";
 /**
  * Read-only diagram that imports the XML once and updates token/incident markers
  * in place (no re-import, so the zoom/scroll position is preserved while
@@ -13,7 +14,7 @@ import NavigatedViewer from "bpmn-js/lib/NavigatedViewer";
  * and provide the `.nano-active` / `.nano-incident` marker styles plus a
  * `.nano-token` style for the token badge overlaid on each active element.
  */
-export function BpmnRuntimeView({ xml, activeIds, incidentIds, className, }) {
+export function BpmnRuntimeView({ xml, activeIds, incidentIds, className, label = "BPMN process diagram", elementName, }) {
     const containerRef = useRef(null);
     const viewerRef = useRef(null);
     const importedRef = useRef(false);
@@ -101,9 +102,24 @@ export function BpmnRuntimeView({ xml, activeIds, incidentIds, className, }) {
         }
         tokenOverlaysRef.current = nextOverlays;
     }
+    // `activeIds` / `incidentIds` are almost always fresh arrays (`snapshot?.x ??
+    // []`), so depending on their identity re-painted every marker and re-created
+    // every token overlay on every render of the parent — visible churn on a busy
+    // diagram. Depend on the ids themselves instead.
+    const key = markerKey(activeIds, incidentIds);
     useEffect(() => {
         applyMarkers();
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [activeIds, incidentIds]);
-    return (_jsx("div", { ref: containerRef, className: className, style: { width: "100%", height: "100%" } }));
+    }, [key]);
+    return (_jsxs("div", { className: className, style: { width: "100%", height: "100%", position: "relative" }, children: [_jsx("div", { ref: containerRef, role: "img", "aria-label": label, style: { width: "100%", height: "100%" } }), _jsx("div", { role: "status", "aria-live": "polite", style: {
+                    position: "absolute",
+                    width: 1,
+                    height: 1,
+                    margin: -1,
+                    padding: 0,
+                    overflow: "hidden",
+                    clip: "rect(0 0 0 0)",
+                    whiteSpace: "nowrap",
+                    border: 0,
+                }, children: describeRunState(activeIds, incidentIds, elementName) })] }));
 }

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export { useBojtos, type UseBojtosOptions, type BojtosControls, type BojtosPhase
 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 { JobFailure, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, } from "@nanobpm/bojtos-kit";
-export type { BojtosSession, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, AgentActivation, AgentResult, WasmEvent, } from "@nanobpm/bojtos-kit";
+export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, } from "./runState.js";
+export { JobFailure, settleReason, unhandledJobTypes, 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, } from "@nanobpm/bojtos-kit";

package/dist/index.js

@@ -7,4 +7,5 @@ export { useBojtos, } from "./useBojtos.js";
 export { Bojtos } from "./Bojtos.js";
 export { OrderFulfillmentDemo, ORDER_FULFILLMENT_BPMN, orderFulfillmentWorkers, } from "./examples/orderFulfillment.js";
 export { BpmnRuntimeView, } from "./BpmnRuntimeView.js";
-export { JobFailure, } from "@nanobpm/bojtos-kit";
+export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, } from "./runState.js";
+export { JobFailure, settleReason, unhandledJobTypes, } from "@nanobpm/bojtos-kit";

package/dist/runState.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure helpers behind the React binding's decisions.
+ *
+ * Kept out of the component and the hook — and out of any module that imports
+ * bpmn-js — so they can be tested without a DOM or the peer dependency. The
+ * component and hook hold rendering and lifecycle; what counts as a change, how
+ * a run reads aloud, which resources to deploy and how far to trim the log are
+ * decisions, and decisions are worth testing.
+ */
+/**
+ * Stable key for a marker set, so unchanged ids don't re-paint the diagram.
+ *
+ * Relies on BPMN element ids being XML NCNames (so they can't contain `,` or
+ * `|`) — that invariant is what keeps the two-field join collision-free. If ids
+ * could contain the delimiters, `["a,b"],[]` and `["a"],["b"]`-style pairs
+ * would key alike.
+ */
+export declare function markerKey(activeIds: string[], incidentIds: string[]): string;
+/**
+ * Content key for the `bpmn` prop, so a fresh array identity each render doesn't
+ * re-create the engine but a real content change still does. Only the array
+ * case is serialized (with a boundary-preserving `JSON.stringify`, not a
+ * `join` — a delimiter join lets two different resource arrays collapse to one
+ * key when a resource borders/contains the delimiter, silently missing a real
+ * change). A lone string can't have array-boundary collisions and React deps
+ * already compare strings by value, so it passes through untouched — no needless
+ * re-walk of potentially large BPMN XML each render.
+ */
+export declare function bpmnKey(bpmn: string | string[]): string;
+/**
+ * Normalize the `bpmn` prop to an ordered resource list for deployment. Deploy
+ * order is significant: a later resource can reference an earlier one (a call
+ * activity's child), so the array order is preserved verbatim.
+ */
+export declare function resourceList(bpmn: string | string[]): string[];
+/**
+ * Trim an event log to the consumer's cap, keeping the most recent events.
+ * `undefined` or a negative cap means "no cap"; `0` means "keep nothing". The
+ * input array is never mutated.
+ */
+export declare function capEvents<T>(all: T[], cap: number | undefined): T[];
+/**
+ * A one-line description of run state, for the diagram's live region. The token
+ * and incident highlights are purely visual; this is the same information as
+ * text.
+ */
+export declare function describeRunState(activeIds: string[], incidentIds: string[], name?: (id: string) => string): string;

package/dist/runState.js

@@ -0,0 +1,64 @@
+/**
+ * Pure helpers behind the React binding's decisions.
+ *
+ * Kept out of the component and the hook — and out of any module that imports
+ * bpmn-js — so they can be tested without a DOM or the peer dependency. The
+ * component and hook hold rendering and lifecycle; what counts as a change, how
+ * a run reads aloud, which resources to deploy and how far to trim the log are
+ * decisions, and decisions are worth testing.
+ */
+/**
+ * Stable key for a marker set, so unchanged ids don't re-paint the diagram.
+ *
+ * Relies on BPMN element ids being XML NCNames (so they can't contain `,` or
+ * `|`) — that invariant is what keeps the two-field join collision-free. If ids
+ * could contain the delimiters, `["a,b"],[]` and `["a"],["b"]`-style pairs
+ * would key alike.
+ */
+export function markerKey(activeIds, incidentIds) {
+    return `${activeIds.join(",")}|${incidentIds.join(",")}`;
+}
+/**
+ * Content key for the `bpmn` prop, so a fresh array identity each render doesn't
+ * re-create the engine but a real content change still does. Only the array
+ * case is serialized (with a boundary-preserving `JSON.stringify`, not a
+ * `join` — a delimiter join lets two different resource arrays collapse to one
+ * key when a resource borders/contains the delimiter, silently missing a real
+ * change). A lone string can't have array-boundary collisions and React deps
+ * already compare strings by value, so it passes through untouched — no needless
+ * re-walk of potentially large BPMN XML each render.
+ */
+export function bpmnKey(bpmn) {
+    return Array.isArray(bpmn) ? JSON.stringify(bpmn) : bpmn;
+}
+/**
+ * Normalize the `bpmn` prop to an ordered resource list for deployment. Deploy
+ * order is significant: a later resource can reference an earlier one (a call
+ * activity's child), so the array order is preserved verbatim.
+ */
+export function resourceList(bpmn) {
+    return Array.isArray(bpmn) ? bpmn : [bpmn];
+}
+/**
+ * Trim an event log to the consumer's cap, keeping the most recent events.
+ * `undefined` or a negative cap means "no cap"; `0` means "keep nothing". The
+ * input array is never mutated.
+ */
+export function capEvents(all, cap) {
+    return cap !== undefined && cap >= 0 && all.length > cap
+        ? all.slice(all.length - cap)
+        : all;
+}
+/**
+ * A one-line description of run state, for the diagram's live region. The token
+ * and incident highlights are purely visual; this is the same information as
+ * text.
+ */
+export function describeRunState(activeIds, incidentIds, name = (id) => id) {
+    const parts = [];
+    if (activeIds.length)
+        parts.push(`Running: ${activeIds.map(name).join(", ")}`);
+    if (incidentIds.length)
+        parts.push(`Incident: ${incidentIds.map(name).join(", ")}`);
+    return parts.length ? parts.join(". ") : "Nothing running";
+}

package/dist/useBojtos.d.ts

@@ -1,9 +1,15 @@
-import { 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 JobHandler, type RoundResult, type Snapshot, type WasmEvent, type WasmSource } from "@nanobpm/bojtos-kit";
 /** Lifecycle of the in-browser engine load. */
 export type BojtosPhase = "loading" | "ready" | "error";
 export interface UseBojtosOptions {
-    /** The BPMN diagram XML to deploy. Re-deploys on a fresh engine when it changes. */
-    bpmn: string;
+    /**
+     * The BPMN to deploy. Re-deploys on a fresh engine when it changes.
+     *
+     * Pass an array to deploy several resources into one engine — a called
+     * process alongside its parent, say. `processIds` then lists every deployable
+     * process across all of them, in deployment order.
+     */
+    bpmn: string | string[];
     /**
      * Optional engine wasm source. Pass a `URL` / bytes / `WebAssembly.Module`
      * when the default `import.meta.url` loader can't resolve the binary (the
@@ -14,6 +20,15 @@ export interface UseBojtosOptions {
      * reload the module.
      */
     wasm?: WasmSource;
+    /**
+     * Cap the reactive `events` log at the most recent N entries.
+     *
+     * Every command re-reads the engine's full event log into React state, so a
+     * long-running demo copies an ever-growing array on each step. Set this when
+     * a page runs for a while and only shows a tail; leave it unset to keep the
+     * whole log, which stays the default so existing consumers are unaffected.
+     */
+    maxEvents?: number;
 }
 export interface BojtosControls {
     phase: BojtosPhase;
@@ -46,6 +61,58 @@ export interface BojtosControls {
     correlateMessage(messageName: string, correlationKey: string, variablesJson: string): Snapshot | null;
     /** Advance the virtual clock. */
     advanceTime(byMs: number): Snapshot | null;
+    /**
+     * Throw a BPMN business error from a waiting job: interrupts the activity via
+     * a matching error boundary/event-subprocess catch, or raises an incident if
+     * uncaught. The job is consumed either way.
+     */
+    throwError(jobKey: string, errorCode: string, errorMessage: string): Snapshot | null;
+    /**
+     * Set a job's remaining retries. Used to recover a job parked on a no-retries
+     * incident before resolving that incident; does not itself unblock the job.
+     */
+    updateRetries(jobKey: string, retries: number): Snapshot | null;
+    /**
+     * Resolve an open incident by key, retrying the work that failed. Pair with
+     * {@link updateRetries} to make a failed job activatable again — the
+     * incident/retry loop a demo needs to show recovery.
+     */
+    resolveIncident(incidentKey: string): Snapshot | null;
+    /**
+     * Merge variables into a scope (a process-instance or element-instance key).
+     * With `local`, they are written strictly into that scope; otherwise they
+     * propagate up to the nearest ancestor defining each name.
+     */
+    setVariables(scopeKey: string, variablesJson: string, local: boolean): Snapshot | null;
+    /** Broadcast a signal by name to every matching open subscription. */
+    broadcastSignal(signalName: string, variablesJson: string): Snapshot | null;
+    /** Cancel (terminate) a running process instance. */
+    cancelInstance(instanceKey: string): Snapshot | null;
+    /**
+     * Modify a running instance: terminate element instances and/or activate new
+     * ones (Zeebe "modify process instance").
+     */
+    modify(instanceKey: string, activateInstructions: ActivateInstruction[], terminateElementInstanceKeys: string[]): Snapshot | null;
+    /**
+     * Complete a waiting user task, merging output variables.
+     *
+     * A `userTask` produces no job, so the dispatch loop cannot advance one: this
+     * is the only way a model with a human step reaches its end event. Drive it
+     * from `snapshot.userTasks`.
+     */
+    completeUserTask(userTaskKey: string, variablesJson: string): Snapshot | null;
+    /**
+     * Assign a user task. With `allowOverride` false the command is rejected if
+     * the task already has an assignee.
+     */
+    assignUserTask(userTaskKey: string, assignee: string, allowOverride: boolean): Snapshot | null;
+    /** Clear a user task's assignee. */
+    unassignUserTask(userTaskKey: string): Snapshot | null;
+    /**
+     * Update a user task's attributes from a JSON changeset (`candidateGroups`,
+     * `candidateUsers`, `dueDate`, `followUpDate`, `priority`).
+     */
+    updateUserTask(userTaskKey: string, changesetJson: string): Snapshot | null;
     /**
      * Run the registered worker handlers until the process settles (activate →
      * handler → complete/fail), then reflect the resulting snapshot/events.
@@ -76,4 +143,4 @@ export interface BojtosControls {
  * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
  * test).
  */
-export declare function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls;
+export declare function useBojtos({ bpmn, wasm, maxEvents, }: UseBojtosOptions): BojtosControls;

package/dist/useBojtos.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, 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
@@ -11,7 +12,7 @@ import { createBojtosSession, dispatchRound, dispatchWorkers, } from "@nanobpm/b
  * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
  * test).
  */
-export function useBojtos({ bpmn, wasm }) {
+export function useBojtos({ bpmn, wasm, maxEvents, }) {
     const sessionRef = useRef(null);
     const [phase, setPhase] = useState("loading");
     const [error, setError] = useState(null);
@@ -23,13 +24,32 @@ export function useBojtos({ bpmn, wasm }) {
     // identity each render must not re-create the session.
     const wasmRef = useRef(wasm);
     wasmRef.current = wasm;
+    // An array prop has a fresh identity every render, which would re-create the
+    // engine on each one. Key the deploy effect on the content instead — see
+    // `bpmnKey` for why this is a boundary-preserving serialization, not a join.
+    const deployKey = bpmnKey(bpmn);
+    const bpmnRef = useRef(bpmn);
+    bpmnRef.current = bpmn;
+    // Trim the reactive event log when the consumer asked for a cap.
+    const maxEventsRef = useRef(maxEvents);
+    maxEventsRef.current = maxEvents;
+    const readEvents = useCallback((session) => {
+        return capEvents(session.events(), maxEventsRef.current);
+    }, []);
     const deployInto = useCallback((session) => {
-        const res = session.deploy(bpmn);
-        setProcessIds(res.processIds);
+        const resources = resourceList(bpmnRef.current);
+        // Deploy in order, collecting every deployable process id. A later
+        // resource can reference an earlier one (a call activity's child).
+        const ids = [];
+        for (const xml of resources)
+            ids.push(...session.deploy(xml).processIds);
+        setProcessIds(ids);
         setSnapshot(null);
         setEvents([]);
         setError(null);
-    }, [bpmn]);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [deployKey]);
     useEffect(() => {
         let cancelled = false;
         // A new diagram means a fresh engine: drop back to `loading` and clear the
@@ -81,7 +101,7 @@ export function useBojtos({ bpmn, wasm }) {
         try {
             const snap = fn(session);
             setSnapshot(snap);
-            setEvents(session.events());
+            setEvents(readEvents(session));
             setError(null);
             return snap;
         }
@@ -96,6 +116,17 @@ export function useBojtos({ bpmn, wasm }) {
     const failJob = useCallback((jobKey, retries, message) => run((s) => s.failJob(jobKey, retries, message)), [run]);
     const advanceTime = useCallback((byMs) => run((s) => s.advanceTime(byMs)), [run]);
     const correlateMessage = useCallback((messageName, correlationKey, variablesJson) => run((s) => s.correlateMessage(messageName, correlationKey, variablesJson)), [run]);
+    const throwError = useCallback((jobKey, errorCode, errorMessage) => run((s) => s.throwError(jobKey, errorCode, errorMessage)), [run]);
+    const updateRetries = useCallback((jobKey, retries) => run((s) => s.updateRetries(jobKey, retries)), [run]);
+    const resolveIncident = useCallback((incidentKey) => run((s) => s.resolveIncident(incidentKey)), [run]);
+    const setVariables = useCallback((scopeKey, variablesJson, local) => run((s) => s.setVariables(scopeKey, variablesJson, local)), [run]);
+    const broadcastSignal = useCallback((signalName, variablesJson) => run((s) => s.broadcastSignal(signalName, variablesJson)), [run]);
+    const cancelInstance = useCallback((instanceKey) => run((s) => s.cancelInstance(instanceKey)), [run]);
+    const modify = useCallback((instanceKey, activateInstructions, terminateElementInstanceKeys) => run((s) => s.modify(instanceKey, activateInstructions, terminateElementInstanceKeys)), [run]);
+    const completeUserTask = useCallback((userTaskKey, variablesJson) => run((s) => s.completeUserTask(userTaskKey, variablesJson)), [run]);
+    const assignUserTask = useCallback((userTaskKey, assignee, allowOverride) => run((s) => s.assignUserTask(userTaskKey, assignee, allowOverride)), [run]);
+    const unassignUserTask = useCallback((userTaskKey) => run((s) => s.unassignUserTask(userTaskKey)), [run]);
+    const updateUserTask = useCallback((userTaskKey, changesetJson) => run((s) => s.updateUserTask(userTaskKey, changesetJson)), [run]);
     const runWorkers = useCallback(async (workers, opts) => {
         const session = sessionRef.current;
         if (!session)
@@ -107,7 +138,7 @@ export function useBojtos({ bpmn, wasm }) {
             if (sessionRef.current !== session)
                 return null;
             setSnapshot(settled);
-            setEvents(session.events());
+            setEvents(readEvents(session));
             setError(null);
             return settled;
         }
@@ -117,7 +148,7 @@ export function useBojtos({ bpmn, wasm }) {
             // Reflect whatever state the engine reached before the drain aborted
             // (e.g. the maxRounds guard) so the view isn't left stale.
             setSnapshot(session.snapshot());
-            setEvents(session.events());
+            setEvents(readEvents(session));
             setError(String(e));
             return null;
         }
@@ -132,7 +163,7 @@ export function useBojtos({ bpmn, wasm }) {
             if (sessionRef.current !== session)
                 return null;
             setSnapshot(round.snapshot);
-            setEvents(session.events());
+            setEvents(readEvents(session));
             setError(null);
             return round;
         }
@@ -140,7 +171,7 @@ export function useBojtos({ bpmn, wasm }) {
             if (sessionRef.current !== session)
                 return null;
             setSnapshot(session.snapshot());
-            setEvents(session.events());
+            setEvents(readEvents(session));
             setError(String(e));
             return null;
         }
@@ -172,6 +203,17 @@ export function useBojtos({ bpmn, wasm }) {
         failJob,
         advanceTime,
         correlateMessage,
+        throwError,
+        updateRetries,
+        resolveIncident,
+        setVariables,
+        broadcastSignal,
+        cancelInstance,
+        modify,
+        completeUserTask,
+        assignUserTask,
+        unassignUserTask,
+        updateUserTask,
         runWorkers,
         stepWorkers,
         reset,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-react",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -27,10 +27,12 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "test": "npm run build && npm run test:ci",
+    "test:ci": "node --experimental-strip-types --test test/*.test.ts"
   },
   "dependencies": {
-    "@nanobpm/bojtos-kit": "^0.4.0"
+    "@nanobpm/bojtos-kit": "^0.5.0"
   },
   "peerDependencies": {
     "bpmn-js": ">=17",

package/src/BpmnRuntimeView.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from "react";
 import NavigatedViewer from "bpmn-js/lib/NavigatedViewer";
+import { describeRunState, markerKey } from "./runState.js";
 
 interface Canvas {
   zoom(mode: string): void;
@@ -27,6 +28,17 @@ export interface BpmnRuntimeViewProps {
   incidentIds: string[];
   /** Optional class for the container element (it always fills its parent). */
   className?: string;
+  /**
+   * Accessible name for the diagram. The token and incident highlights are
+   * purely visual, so without this a screen-reader user is told nothing at all
+   * about what is running.
+   */
+  label?: string;
+  /**
+   * Map an element id to a human name for the live status announcement — pass
+   * the diagram's element names if you have them. Defaults to the raw id.
+   */
+  elementName?: (elementId: string) => string;
 }
 
 /**
@@ -46,6 +58,8 @@ export function BpmnRuntimeView({
   activeIds,
   incidentIds,
   className,
+  label = "BPMN process diagram",
+  elementName,
 }: BpmnRuntimeViewProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const viewerRef = useRef<NavigatedViewer | null>(null);
@@ -133,16 +147,49 @@ export function BpmnRuntimeView({
     tokenOverlaysRef.current = nextOverlays;
   }
 
+  // `activeIds` / `incidentIds` are almost always fresh arrays (`snapshot?.x ??
+  // []`), so depending on their identity re-painted every marker and re-created
+  // every token overlay on every render of the parent — visible churn on a busy
+  // diagram. Depend on the ids themselves instead.
+  const key = markerKey(activeIds, incidentIds);
   useEffect(() => {
     applyMarkers();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [activeIds, incidentIds]);
+  }, [key]);
 
   return (
     <div
-      ref={containerRef}
       className={className}
-      style={{ width: "100%", height: "100%" }}
-    />
+      style={{ width: "100%", height: "100%", position: "relative" }}
+    >
+      <div
+        ref={containerRef}
+        role="img"
+        aria-label={label}
+        style={{ width: "100%", height: "100%" }}
+      />
+      {/* The highlights are visual only. Mirror them as text, politely
+          announced, so the run is followable without seeing the diagram. No
+          `aria-label` here: on a live region it would override the changing
+          text in the accessible-name computation, so screen readers would
+          announce the static label instead of the run state. */}
+      <div
+        role="status"
+        aria-live="polite"
+        style={{
+          position: "absolute",
+          width: 1,
+          height: 1,
+          margin: -1,
+          padding: 0,
+          overflow: "hidden",
+          clip: "rect(0 0 0 0)",
+          whiteSpace: "nowrap",
+          border: 0,
+        }}
+      >
+        {describeRunState(activeIds, incidentIds, elementName)}
+      </div>
+    </div>
   );
 }

package/src/index.ts

@@ -20,14 +20,24 @@ export {
   BpmnRuntimeView,
   type BpmnRuntimeViewProps,
 } from "./BpmnRuntimeView.js";
+export {
+  describeRunState,
+  markerKey,
+  bpmnKey,
+  resourceList,
+  capEvents,
+} from "./runState.js";
 export {
   JobFailure,
+  settleReason,
+  unhandledJobTypes,
   type JobHandler,
   type JobResult,
   type AgentHandler,
   type DispatchOptions,
   type DispatchResult,
   type RoundResult,
+  type SettleReason,
 } from "@nanobpm/bojtos-kit";
 export type {
   BojtosSession,
@@ -37,7 +47,14 @@ export type {
   ActivatedJob,
   IncidentDto,
   TimerDto,
+  UserTaskDto,
+  MessageSubscriptionDto,
+  SignalSubscriptionDto,
+  ElementStatDto,
+  SequenceFlowDto,
+  DecisionInstanceDto,
   ActiveEl,
+  ActivateInstruction,
   AgentActivation,
   AgentResult,
   WasmEvent,

package/src/runState.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure helpers behind the React binding's decisions.
+ *
+ * Kept out of the component and the hook — and out of any module that imports
+ * bpmn-js — so they can be tested without a DOM or the peer dependency. The
+ * component and hook hold rendering and lifecycle; what counts as a change, how
+ * a run reads aloud, which resources to deploy and how far to trim the log are
+ * decisions, and decisions are worth testing.
+ */
+
+/**
+ * Stable key for a marker set, so unchanged ids don't re-paint the diagram.
+ *
+ * Relies on BPMN element ids being XML NCNames (so they can't contain `,` or
+ * `|`) — that invariant is what keeps the two-field join collision-free. If ids
+ * could contain the delimiters, `["a,b"],[]` and `["a"],["b"]`-style pairs
+ * would key alike.
+ */
+export function markerKey(activeIds: string[], incidentIds: string[]): string {
+  return `${activeIds.join(",")}|${incidentIds.join(",")}`;
+}
+
+/**
+ * Content key for the `bpmn` prop, so a fresh array identity each render doesn't
+ * re-create the engine but a real content change still does. Only the array
+ * case is serialized (with a boundary-preserving `JSON.stringify`, not a
+ * `join` — a delimiter join lets two different resource arrays collapse to one
+ * key when a resource borders/contains the delimiter, silently missing a real
+ * change). A lone string can't have array-boundary collisions and React deps
+ * already compare strings by value, so it passes through untouched — no needless
+ * re-walk of potentially large BPMN XML each render.
+ */
+export function bpmnKey(bpmn: string | string[]): string {
+  return Array.isArray(bpmn) ? JSON.stringify(bpmn) : bpmn;
+}
+
+/**
+ * Normalize the `bpmn` prop to an ordered resource list for deployment. Deploy
+ * order is significant: a later resource can reference an earlier one (a call
+ * activity's child), so the array order is preserved verbatim.
+ */
+export function resourceList(bpmn: string | string[]): string[] {
+  return Array.isArray(bpmn) ? bpmn : [bpmn];
+}
+
+/**
+ * Trim an event log to the consumer's cap, keeping the most recent events.
+ * `undefined` or a negative cap means "no cap"; `0` means "keep nothing". The
+ * input array is never mutated.
+ */
+export function capEvents<T>(all: T[], cap: number | undefined): T[] {
+  return cap !== undefined && cap >= 0 && all.length > cap
+    ? all.slice(all.length - cap)
+    : all;
+}
+
+/**
+ * A one-line description of run state, for the diagram's live region. The token
+ * and incident highlights are purely visual; this is the same information as
+ * text.
+ */
+export function describeRunState(
+  activeIds: string[],
+  incidentIds: string[],
+  name: (id: string) => string = (id) => id,
+): string {
+  const parts: string[] = [];
+  if (activeIds.length) parts.push(`Running: ${activeIds.map(name).join(", ")}`);
+  if (incidentIds.length)
+    parts.push(`Incident: ${incidentIds.map(name).join(", ")}`);
+  return parts.length ? parts.join(". ") : "Nothing running";
+}

package/src/useBojtos.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
+  type ActivateInstruction,
   type AgentResult,
   type BojtosSession,
   createBojtosSession,
@@ -12,13 +13,20 @@ import {
   type WasmEvent,
   type WasmSource,
 } from "@nanobpm/bojtos-kit";
+import { bpmnKey, capEvents, resourceList } from "./runState.js";
 
 /** Lifecycle of the in-browser engine load. */
 export type BojtosPhase = "loading" | "ready" | "error";
 
 export interface UseBojtosOptions {
-  /** The BPMN diagram XML to deploy. Re-deploys on a fresh engine when it changes. */
-  bpmn: string;
+  /**
+   * The BPMN to deploy. Re-deploys on a fresh engine when it changes.
+   *
+   * Pass an array to deploy several resources into one engine — a called
+   * process alongside its parent, say. `processIds` then lists every deployable
+   * process across all of them, in deployment order.
+   */
+  bpmn: string | string[];
   /**
    * Optional engine wasm source. Pass a `URL` / bytes / `WebAssembly.Module`
    * when the default `import.meta.url` loader can't resolve the binary (the
@@ -29,6 +37,15 @@ export interface UseBojtosOptions {
    * reload the module.
    */
   wasm?: WasmSource;
+  /**
+   * Cap the reactive `events` log at the most recent N entries.
+   *
+   * Every command re-reads the engine's full event log into React state, so a
+   * long-running demo copies an ever-growing array on each step. Set this when
+   * a page runs for a while and only shows a tail; leave it unset to keep the
+   * whole log, which stays the default so existing consumers are unaffected.
+   */
+  maxEvents?: number;
 }
 
 export interface BojtosControls {
@@ -66,6 +83,74 @@ export interface BojtosControls {
   ): Snapshot | null;
   /** Advance the virtual clock. */
   advanceTime(byMs: number): Snapshot | null;
+  /**
+   * Throw a BPMN business error from a waiting job: interrupts the activity via
+   * a matching error boundary/event-subprocess catch, or raises an incident if
+   * uncaught. The job is consumed either way.
+   */
+  throwError(
+    jobKey: string,
+    errorCode: string,
+    errorMessage: string,
+  ): Snapshot | null;
+  /**
+   * Set a job's remaining retries. Used to recover a job parked on a no-retries
+   * incident before resolving that incident; does not itself unblock the job.
+   */
+  updateRetries(jobKey: string, retries: number): Snapshot | null;
+  /**
+   * Resolve an open incident by key, retrying the work that failed. Pair with
+   * {@link updateRetries} to make a failed job activatable again — the
+   * incident/retry loop a demo needs to show recovery.
+   */
+  resolveIncident(incidentKey: string): Snapshot | null;
+  /**
+   * Merge variables into a scope (a process-instance or element-instance key).
+   * With `local`, they are written strictly into that scope; otherwise they
+   * propagate up to the nearest ancestor defining each name.
+   */
+  setVariables(
+    scopeKey: string,
+    variablesJson: string,
+    local: boolean,
+  ): Snapshot | null;
+  /** Broadcast a signal by name to every matching open subscription. */
+  broadcastSignal(signalName: string, variablesJson: string): Snapshot | null;
+  /** Cancel (terminate) a running process instance. */
+  cancelInstance(instanceKey: string): Snapshot | null;
+  /**
+   * Modify a running instance: terminate element instances and/or activate new
+   * ones (Zeebe "modify process instance").
+   */
+  modify(
+    instanceKey: string,
+    activateInstructions: ActivateInstruction[],
+    terminateElementInstanceKeys: string[],
+  ): Snapshot | null;
+  /**
+   * Complete a waiting user task, merging output variables.
+   *
+   * A `userTask` produces no job, so the dispatch loop cannot advance one: this
+   * is the only way a model with a human step reaches its end event. Drive it
+   * from `snapshot.userTasks`.
+   */
+  completeUserTask(userTaskKey: string, variablesJson: string): Snapshot | null;
+  /**
+   * Assign a user task. With `allowOverride` false the command is rejected if
+   * the task already has an assignee.
+   */
+  assignUserTask(
+    userTaskKey: string,
+    assignee: string,
+    allowOverride: boolean,
+  ): Snapshot | null;
+  /** Clear a user task's assignee. */
+  unassignUserTask(userTaskKey: string): Snapshot | null;
+  /**
+   * Update a user task's attributes from a JSON changeset (`candidateGroups`,
+   * `candidateUsers`, `dueDate`, `followUpDate`, `priority`).
+   */
+  updateUserTask(userTaskKey: string, changesetJson: string): Snapshot | null;
   /**
    * Run the registered worker handlers until the process settles (activate →
    * handler → complete/fail), then reflect the resulting snapshot/events.
@@ -92,6 +177,29 @@ export interface BojtosControls {
   reset(): void;
 }
 
+/**
+ * Session members the hook deliberately does not re-export: the deployment
+ * lifecycle it owns itself, and the low-level activate primitive the dispatch
+ * loop owns.
+ */
+type NotReExported = "deploy" | "free" | "activateJobs";
+
+/**
+ * Compile-time guard. `useBojtos` keeps its session private, so a command it
+ * doesn't re-export is *unreachable* for a consumer rather than merely
+ * inconvenient — which is how `completeUserTask` went missing and left any model
+ * with a user task unfinishable (#1).
+ *
+ * Adding a command to {@link BojtosSession} without a binding here now fails the
+ * build with the offending name, instead of shipping a hole.
+ */
+type UnboundCommands = Exclude<
+  keyof BojtosSession,
+  NotReExported | keyof BojtosControls
+>;
+type AssertNever<T extends never> = T;
+type _EverySessionCommandIsBound = AssertNever<UnboundCommands>;
+
 /**
  * React binding over a headless {@link BojtosSession}: owns the engine's
  * lifecycle and the reactive `snapshot` / `events` / `processIds` state, and
@@ -103,7 +211,11 @@ export interface BojtosControls {
  * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
  * test).
  */
-export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
+export function useBojtos({
+  bpmn,
+  wasm,
+  maxEvents,
+}: UseBojtosOptions): BojtosControls {
   const sessionRef = useRef<BojtosSession | null>(null);
   const [phase, setPhase] = useState<BojtosPhase>("loading");
   const [error, setError] = useState<string | null>(null);
@@ -117,15 +229,34 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
   const wasmRef = useRef(wasm);
   wasmRef.current = wasm;
 
+  // An array prop has a fresh identity every render, which would re-create the
+  // engine on each one. Key the deploy effect on the content instead — see
+  // `bpmnKey` for why this is a boundary-preserving serialization, not a join.
+  const deployKey = bpmnKey(bpmn);
+  const bpmnRef = useRef(bpmn);
+  bpmnRef.current = bpmn;
+
+  // Trim the reactive event log when the consumer asked for a cap.
+  const maxEventsRef = useRef(maxEvents);
+  maxEventsRef.current = maxEvents;
+  const readEvents = useCallback((session: BojtosSession): WasmEvent[] => {
+    return capEvents(session.events(), maxEventsRef.current);
+  }, []);
+
   const deployInto = useCallback(
     (session: BojtosSession) => {
-      const res = session.deploy(bpmn);
-      setProcessIds(res.processIds);
+      const resources = resourceList(bpmnRef.current);
+      // Deploy in order, collecting every deployable process id. A later
+      // resource can reference an earlier one (a call activity's child).
+      const ids: string[] = [];
+      for (const xml of resources) ids.push(...session.deploy(xml).processIds);
+      setProcessIds(ids);
       setSnapshot(null);
       setEvents([]);
       setError(null);
     },
-    [bpmn],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [deployKey],
   );
 
   useEffect(() => {
@@ -178,7 +309,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
       try {
         const snap = fn(session);
         setSnapshot(snap);
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(null);
         return snap;
       } catch (e) {
@@ -218,6 +349,68 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
       run((s) => s.correlateMessage(messageName, correlationKey, variablesJson)),
     [run],
   );
+  const throwError = useCallback(
+    (jobKey: string, errorCode: string, errorMessage: string) =>
+      run((s) => s.throwError(jobKey, errorCode, errorMessage)),
+    [run],
+  );
+  const updateRetries = useCallback(
+    (jobKey: string, retries: number) =>
+      run((s) => s.updateRetries(jobKey, retries)),
+    [run],
+  );
+  const resolveIncident = useCallback(
+    (incidentKey: string) => run((s) => s.resolveIncident(incidentKey)),
+    [run],
+  );
+  const setVariables = useCallback(
+    (scopeKey: string, variablesJson: string, local: boolean) =>
+      run((s) => s.setVariables(scopeKey, variablesJson, local)),
+    [run],
+  );
+  const broadcastSignal = useCallback(
+    (signalName: string, variablesJson: string) =>
+      run((s) => s.broadcastSignal(signalName, variablesJson)),
+    [run],
+  );
+  const cancelInstance = useCallback(
+    (instanceKey: string) => run((s) => s.cancelInstance(instanceKey)),
+    [run],
+  );
+  const modify = useCallback(
+    (
+      instanceKey: string,
+      activateInstructions: ActivateInstruction[],
+      terminateElementInstanceKeys: string[],
+    ) =>
+      run((s) =>
+        s.modify(
+          instanceKey,
+          activateInstructions,
+          terminateElementInstanceKeys,
+        ),
+      ),
+    [run],
+  );
+  const completeUserTask = useCallback(
+    (userTaskKey: string, variablesJson: string) =>
+      run((s) => s.completeUserTask(userTaskKey, variablesJson)),
+    [run],
+  );
+  const assignUserTask = useCallback(
+    (userTaskKey: string, assignee: string, allowOverride: boolean) =>
+      run((s) => s.assignUserTask(userTaskKey, assignee, allowOverride)),
+    [run],
+  );
+  const unassignUserTask = useCallback(
+    (userTaskKey: string) => run((s) => s.unassignUserTask(userTaskKey)),
+    [run],
+  );
+  const updateUserTask = useCallback(
+    (userTaskKey: string, changesetJson: string) =>
+      run((s) => s.updateUserTask(userTaskKey, changesetJson)),
+    [run],
+  );
 
   const runWorkers = useCallback(
     async (
@@ -236,7 +429,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
         // while we awaited — don't publish stale state or read a freed session.
         if (sessionRef.current !== session) return null;
         setSnapshot(settled);
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(null);
         return settled;
       } catch (e) {
@@ -244,7 +437,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
         // Reflect whatever state the engine reached before the drain aborted
         // (e.g. the maxRounds guard) so the view isn't left stale.
         setSnapshot(session.snapshot());
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(String(e));
         return null;
       }
@@ -264,13 +457,13 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
         // Bail if the session was replaced/freed while we awaited the round.
         if (sessionRef.current !== session) return null;
         setSnapshot(round.snapshot);
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(null);
         return round;
       } catch (e) {
         if (sessionRef.current !== session) return null;
         setSnapshot(session.snapshot());
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(String(e));
         return null;
       }
@@ -304,6 +497,17 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
     failJob,
     advanceTime,
     correlateMessage,
+    throwError,
+    updateRetries,
+    resolveIncident,
+    setVariables,
+    broadcastSignal,
+    cancelInstance,
+    modify,
+    completeUserTask,
+    assignUserTask,
+    unassignUserTask,
+    updateUserTask,
     runWorkers,
     stepWorkers,
     reset,