@nanobpm/bojtos-react 0.4.0 → 0.6.0

package/README.md

@@ -10,6 +10,15 @@ React binding for the **Bojtos** in-browser BPMN demo framework
 - **`<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.
+- **`<TraceTimeline rows />`** — the shared activity log: it renders the
+  framework-agnostic trace model from [`@nanobpm/bojtos-kit`](../bojtos-kit) as a
+  turn-by-turn story (consecutive same-`turn` rows fold into one card; rows with
+  no `turn` render as plain lines). Feed it a kit adapter —
+  `foldEngineEvents(run.events)` for a plain engine run, or
+  `traceEntriesToRows(entries)` for handler-emitted agent/tool/turn entries. It
+  imports **only** the kit and React, so a trace-only import tree-shakes `bpmn-js`
+  out (the package is `sideEffects: false`); a test walks the built module graph
+  to pin that.
 
 ## Install
 
@@ -42,6 +51,26 @@ function Demo({ bpmn }: { bpmn: string }) {
 }
 ```
 
+## Trace timeline
+
+```tsx
+import { useBojtos, TraceTimeline, foldEngineEvents } from "@nanobpm/bojtos-react";
+
+function RunLog({ bpmn }: { bpmn: string }) {
+  const run = useBojtos({ bpmn });
+  // Engine-event fold — the non-agentic / test-view case.
+  return <TraceTimeline rows={foldEngineEvents(run.events)} />;
+}
+```
+
+For an agentic run, emit `TraceEntry` lines from your handlers (with the additive
+`turn` / `elementId` / `args` / `result` fields) and pass
+`traceEntriesToRows(entries)` instead — same component, turn-grouped card view.
+`TraceTimeline` keeps the class names (`timeline`, `timeline-turn`,
+`log-line log-<kind>`, …) the demo stylesheet already targets, so your CSS applies
+unchanged. It never imports `bpmn-js`, so importing it alone won't pull the
+diagram bundle in.
+
 ## Peer requirements
 
 `react` and `bpmn-js` are peer dependencies (the consumer already has them). The
@@ -51,6 +80,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/TraceTimeline.d.ts

@@ -0,0 +1,50 @@
+import { type ElementStatDto, type IncidentDto, type TraceRow } from "@nanobpm/bojtos-kit";
+/**
+ * The shared activity log — the run told as a story rather than a flat stack of
+ * lines. It is the single component that retired the two drifted, forked
+ * `TraceTimeline` copies (nanobpm/bojtos#9): the web-demo framework's agent/tool/
+ * turn view and the console test-view's engine-event fold.
+ *
+ * It renders the framework-agnostic {@link TraceRow} model from
+ * `@nanobpm/bojtos-kit` — feed it whichever adapter matches your source:
+ *
+ * - `foldEngineEvents(useBojtos().events)` for the non-agentic / test-view case, or
+ * - `traceEntriesToRows(entries)` for handler-emitted agent/tool/turn entries.
+ *
+ * Consecutive rows sharing a `turn` fold into one card (the model's raw LLM reply,
+ * each tool it activated with its arguments, and — once it lands — what that tool
+ * returned); rows with no `turn` render as plain lines in order, so a non-agentic
+ * run looks exactly like the flat log it replaces.
+ *
+ * This module deliberately imports **only** the kit and React — never
+ * `./BpmnRuntimeView` or `bpmn-js` — so a trace-only import tree-shakes the
+ * diagram renderer out (the package is `sideEffects: false`). See
+ * `test/trace.timeline.test.ts`, which walks the built module graph to pin that.
+ *
+ * The markup keeps the class names the forked copies' CSS already targets
+ * (`timeline`, `timeline-turn`, `timeline-tool`, `log-line log-<kind>`, …) so a
+ * consumer's existing stylesheet applies unchanged; no design-system dependency
+ * is pulled in.
+ */
+export interface TraceTimelineProps {
+    /**
+     * The normalized rows to render. Produce them with a kit adapter
+     * (`foldEngineEvents` / `traceEntriesToRows`) or your own {@link TraceRow[]}.
+     */
+    rows: TraceRow[];
+    /** `snapshot.elementStats` — per-element completion/active counts, engine-side. */
+    elementStats?: ElementStatDto[];
+    /** Incidents on the current snapshot, with their reason. */
+    incidents?: IncidentDto[];
+    /** BPMN element id → human label, for both the timeline and the panels below. */
+    labelFor?: (elementId: string) => string;
+    /** Card heading. Defaults to "Activity". */
+    title?: string;
+    /** Sub-heading under the title. */
+    description?: string;
+    /** Shown when there are no rows yet. Defaults to "Press Run to start.". */
+    emptyText?: string;
+    /** Optional class for the outer container. */
+    className?: string;
+}
+export declare function TraceTimeline({ rows, elementStats, incidents, labelFor, title, description, emptyText, className, }: TraceTimelineProps): import("react").JSX.Element;

package/dist/TraceTimeline.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { buildTraceItems, isTraceTurnGroup, } from "@nanobpm/bojtos-kit";
+function safeStringify(value, space) {
+    // `JSON.stringify(undefined)` returns the JS value `undefined` (not a string),
+    // which would render as nothing. Emit the literal "undefined" so a handler/tool
+    // that actually returned `undefined` is shown explicitly rather than vanishing.
+    if (value === undefined)
+        return "undefined";
+    try {
+        // `JSON.stringify` throws on BigInt and circular structures; a replacer
+        // renders BigInt losslessly as its decimal string so trace payloads that
+        // carry engine-native BigInts don't crash serialization.
+        return JSON.stringify(value, (_key, val) => (typeof val === "bigint" ? val.toString() : val), space);
+    }
+    catch {
+        return "[unserializable value]";
+    }
+}
+function ToolStep({ activation, result, labelFor, }) {
+    const elementId = activation.elementId ?? "";
+    return (_jsxs("div", { className: "timeline-tool", children: [_jsxs("div", { className: "timeline-tool-head", children: [_jsx("span", { className: "timeline-badge timeline-badge-info", children: "tool" }), _jsx("strong", { children: labelFor(elementId) || elementId }), _jsx("code", { children: elementId })] }), activation.args !== undefined &&
+                Object.keys(activation.args).length > 0 && (_jsxs("div", { className: "timeline-kv", children: [_jsx("span", { className: "timeline-kv-label", children: "arguments" }), _jsx("code", { children: safeStringify(activation.args) })] })), _jsxs("div", { className: "timeline-kv", children: [_jsx("span", { className: "timeline-kv-label", children: "returned" }), _jsx("code", { children: result
+                            ? safeStringify(result.result)
+                            : "— waiting for the job to complete —" })] })] }));
+}
+function TurnCard({ group, labelFor, }) {
+    const reply = group.rows.find((e) => e.kind === "llm");
+    const activations = group.rows.filter((e) => e.kind === "agent" && e.elementId);
+    const results = group.rows.filter((e) => e.kind === "vars" && e.elementId);
+    const decisions = group.rows.filter((e) => e.kind === "agent" && !e.elementId);
+    const errors = group.rows.filter((e) => e.kind === "error");
+    // Entries a handler's own trace call emits (kind "tool") and any "vars" result
+    // that never paired with an activation above would otherwise vanish once
+    // stamped with a turn — render them as plain lines within the card, in order.
+    const activatedElementIds = new Set(activations.map((a) => a.elementId));
+    const loose = group.rows
+        .filter((e) => e.kind === "tool" ||
+        (e.kind === "vars" &&
+            e.elementId &&
+            !activatedElementIds.has(e.elementId)))
+        .sort((a, b) => a.id - b.id);
+    return (_jsxs("div", { className: "timeline-turn", children: [_jsxs("div", { className: "timeline-turn-head", children: [_jsxs("span", { className: `timeline-badge ${reply?.pending ? "timeline-badge-warning" : "timeline-badge-neutral"}`, children: ["Turn ", group.turn] }), reply?.pending && _jsx("span", { className: "timeline-pending", children: "thinking\u2026" })] }), reply && _jsx("blockquote", { className: "timeline-reply", children: reply.text }), decisions.map((d) => (_jsx("div", { className: "timeline-note", children: d.text }, d.key ?? d.id))), activations.map((a) => (_jsx(ToolStep, { activation: a, result: results.find((r) => r.elementId === a.elementId), labelFor: labelFor }, a.key ?? a.id))), loose.map((e) => (_jsxs("div", { className: `log-line log-${e.kind}`, children: [e.pending ? "⏳ " : "", e.text] }, e.key ?? e.id))), errors.map((e) => (_jsxs("div", { className: "timeline-error", children: ["\u26A0 ", e.text] }, e.id)))] }));
+}
+export function TraceTimeline({ rows, elementStats = [], incidents = [], labelFor = (id) => id, title = "Activity", description = "Agent turns, model replies, and tool calls — read top to bottom as a story.", emptyText = "Press Run to start.", className, }) {
+    const items = useMemo(() => buildTraceItems(rows), [rows]);
+    const [copied, setCopied] = useState(false);
+    const scrollRef = useRef(null);
+    // Keep the newest step in view as the run grows, same as the flat logs this
+    // replaces.
+    useEffect(() => {
+        const el = scrollRef.current;
+        if (el)
+            el.scrollTop = el.scrollHeight;
+    }, [items]);
+    const copyJson = () => {
+        const payload = {
+            log: rows.map(({ id: _id, ...rest }) => rest),
+            elementStats,
+            incidents,
+        };
+        const text = safeStringify(payload, 2);
+        if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+            navigator.clipboard
+                .writeText(text)
+                .then(() => {
+                setCopied(true);
+                setTimeout(() => setCopied(false), 1500);
+            })
+                .catch(() => {
+                // Clipboard access can be denied (permissions policy, insecure
+                // context, an embed iframe without a clipboard-write allowance) —
+                // fail quietly rather than surfacing an error for a convenience
+                // action, not a run-blocking one.
+            });
+        }
+    };
+    return (_jsxs("div", { className: className ? `timeline-panel ${className}` : "timeline-panel", children: [_jsxs("div", { className: "timeline-header", children: [_jsx("div", { className: "timeline-title", children: title }), description && (_jsx("div", { className: "timeline-description", children: description }))] }), _jsx("div", { className: "timeline-toolbar", children: _jsx("button", { type: "button", onClick: copyJson, children: copied ? "Copied!" : "Copy run as JSON" }) }), _jsx("div", { className: "timeline", ref: scrollRef, children: items.length === 0 ? (_jsx("div", { className: "log-empty", children: emptyText })) : (items.map((item) => isTraceTurnGroup(item) ? (_jsx(TurnCard, { group: item, labelFor: labelFor }, `turn-${item.turn}-${item.rows[0].key ?? item.rows[0].id}`)) : (_jsxs("div", { className: `log-line log-${item.kind}`, children: [item.pending ? "⏳ " : "", item.text] }, item.key ?? item.id)))) }), (elementStats.length > 0 || incidents.length > 0) && (_jsxs("div", { className: "timeline-engine-view", children: [elementStats.length > 0 && (_jsxs("div", { className: "timeline-stats", children: [_jsx("span", { className: "timeline-kv-label", children: "Element completion" }), _jsx("ul", { children: elementStats
+                                    .filter((s) => s.completed > 0 || (s.active ?? 0) > 0)
+                                    .map((s) => (_jsxs("li", { children: [_jsx("code", { children: labelFor(s.elementId) || s.elementId }), " ", "completed ", s.completed, s.active ? `, ${s.active} active` : ""] }, s.elementId))) })] })), incidents.length > 0 && (_jsxs("div", { className: "timeline-incidents", children: [_jsx("span", { className: "timeline-kv-label", children: "Incidents" }), _jsx("ul", { children: incidents.map((inc, i) => (_jsxs("li", { children: [_jsx("code", { children: labelFor(inc.elementId) || inc.elementId }), " \u2014", " ", inc.reason] }, `${inc.elementId}-${i}`))) })] }))] }))] }));
+}

package/dist/index.d.ts

@@ -2,5 +2,7 @@ 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 { TraceTimeline, type TraceTimelineProps } from "./TraceTimeline.js";
+export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, } 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";

package/dist/index.js

@@ -7,4 +7,8 @@ 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";
+// 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 { JobFailure, settleReason, unhandledJobTypes, buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } 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.6.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.6.0"
   },
   "peerDependencies": {
     "bpmn-js": ">=17",