@nanobpm/bojtos-react 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @nanobpm/bojtos-react
+
+React binding for the **Bojtos** in-browser BPMN demo framework
+([ADR 0043](../docs/adr/0043-bojtos-demo-framework.md)), built on
+[`@nanobpm/bojtos-kit`](../bojtos-kit).
+
+- **`useBojtos({ bpmn })`** — owns the engine session and the reactive
+  `snapshot` / `events` / `processIds` state, and exposes the engine commands
+  (`createInstance`, `completeJob`, `failJob`, `advanceTime`, `reset`).
+- **`<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.
+
+## Install
+
+```bash
+npm install @nanobpm/bojtos-react react react-dom bpmn-js
+```
+
+`@nanobpm/bojtos-kit` and `@nanobpm/engine-wasm` (the wasm engine) are pulled in
+transitively — you only add the `react` / `bpmn-js` peers yourself. This is all
+you need to build your own Bojtos demo outside this repo; see the usage snippet
+below.
+
+## Usage
+
+```tsx
+import { useBojtos, BpmnRuntimeView } from "@nanobpm/bojtos-react";
+import "bpmn-js/dist/assets/diagram-js.css";
+import "bpmn-js/dist/assets/bpmn-font/css/bpmn-embedded.css";
+
+function Demo({ bpmn }: { bpmn: string }) {
+  const run = useBojtos({ bpmn });
+  const snap = run.snapshot;
+  return (
+    <BpmnRuntimeView
+      xml={bpmn}
+      activeIds={snap?.activeElementIds ?? []}
+      incidentIds={snap?.incidentElementIds ?? []}
+    />
+  );
+}
+```
+
+## Peer requirements
+
+`react` and `bpmn-js` are peer dependencies (the consumer already has them). The
+consumer must import bpmn-js's diagram CSS once and provide the `.nano-active` /
+`.nano-incident` marker styles.
+
+## 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
+`npm run build`.

package/dist/Bojtos.d.ts

@@ -0,0 +1,51 @@
+import type { JobHandler, WasmEvent } from "@nanobpm/bojtos-kit";
+/** A single engine event handed to `onTrace` as the simulation runs. */
+export type TraceEvent = WasmEvent;
+export interface BojtosProps {
+    /** The BPMN diagram XML to run. */
+    bpmn: string;
+    /**
+     * The in-browser workers, keyed by the model's job type (task definition
+     * type). Each handler receives the activated job (with the instance's live
+     * variables) and returns the variables to merge on completion — or throws to
+     * fail the job. This is the code a demo author edits to shape the run.
+     */
+    workers: Record<string, JobHandler>;
+    /** Initial instance variables (the starting payload). Defaults to `{}`. */
+    seed?: Record<string, unknown>;
+    /** Start the instance and run the workers automatically once ready. */
+    autoplay?: boolean;
+    /**
+     * Milliseconds between dispatch rounds while playing (default 700). The pause
+     * is what makes the token visibly hop task-to-task instead of settling
+     * instantly.
+     */
+    stepDelayMs?: number;
+    /**
+     * Which deployed process to start. Defaults to the first process in the
+     * diagram — set this only for a multi-process `.bpmn`.
+     */
+    processId?: string;
+    /**
+     * Optional engine wasm URL for bundlers where the default `import.meta.url`
+     * loader can't resolve the binary (ADR 0043 §3).
+     */
+    wasmUrl?: string;
+    /** Called for every engine event as the simulation advances. */
+    onTrace?: (event: TraceEvent) => void;
+    /** Optional class for the outer container. */
+    className?: string;
+}
+/**
+ * The turnkey Bojtos demo component (ADR 0043 §2): drop in a `bpmn` diagram and
+ * a map of in-browser `workers`, and it renders the live token/incident diagram
+ * beside the running variable payload, driving the "activate → handler →
+ * complete/fail" loop so you watch the token advance and the payload mutate as
+ * each worker runs.
+ *
+ * The consuming app must load bpmn-js's diagram CSS once
+ * (`bpmn-js/dist/assets/diagram-js.css` and
+ * `.../bpmn-font/css/bpmn-embedded.css`); the token/incident marker styles are
+ * injected here.
+ */
+export declare function Bojtos({ bpmn, workers, seed, autoplay, stepDelayMs, processId, wasmUrl, onTrace, className, }: BojtosProps): import("react").JSX.Element;

package/dist/Bojtos.js

@@ -0,0 +1,154 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { BpmnRuntimeView } from "./BpmnRuntimeView.js";
+import { useBojtos } from "./useBojtos.js";
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+const MARKER_CSS = `
+.bojtos-diagram .nano-active .djs-visual > :nth-child(1) {
+  stroke: #10b981 !important;
+  stroke-width: 3px !important;
+}
+.bojtos-diagram .nano-incident .djs-visual > :nth-child(1) {
+  stroke: #ef4444 !important;
+  stroke-width: 3px !important;
+  fill: #fee2e2 !important;
+}
+`;
+/**
+ * The turnkey Bojtos demo component (ADR 0043 §2): drop in a `bpmn` diagram and
+ * a map of in-browser `workers`, and it renders the live token/incident diagram
+ * beside the running variable payload, driving the "activate → handler →
+ * complete/fail" loop so you watch the token advance and the payload mutate as
+ * each worker runs.
+ *
+ * The consuming app must load bpmn-js's diagram CSS once
+ * (`bpmn-js/dist/assets/diagram-js.css` and
+ * `.../bpmn-font/css/bpmn-embedded.css`); the token/incident marker styles are
+ * injected here.
+ */
+export function Bojtos({ bpmn, workers, seed, autoplay, stepDelayMs = 700, processId, wasmUrl, onTrace, className, }) {
+    const { phase, error, processIds, snapshot, events, createInstance, stepWorkers, reset, } = useBojtos({ bpmn, wasm: wasmUrl });
+    const [playing, setPlaying] = useState(false);
+    const playingRef = useRef(false);
+    const startedRef = useRef(false);
+    // Tracks whether the component is still mounted, so the async play loop (which
+    // can outlive an unmount while awaiting `stepWorkers()` / `delay()`) neither
+    // sets state on an unmounted component nor keeps driving a freed session.
+    const mountedRef = useRef(true);
+    useEffect(() => () => {
+        mountedRef.current = false;
+        playingRef.current = false;
+    }, []);
+    // Keep the object/function props in refs so the play loop and the autoplay
+    // effect don't churn (or re-fire) when a parent re-renders with fresh
+    // identities for `workers` / `seed` / `onTrace`.
+    const workersRef = useRef(workers);
+    workersRef.current = workers;
+    const seedRef = useRef(seed);
+    seedRef.current = seed;
+    const onTraceRef = useRef(onTrace);
+    onTraceRef.current = onTrace;
+    // A fresh engine (bpmn change / reset drops back to `loading`) clears the
+    // "instance created" latch and stops any in-flight play loop.
+    useEffect(() => {
+        if (phase === "loading") {
+            startedRef.current = false;
+            playingRef.current = false;
+            setPlaying(false);
+        }
+    }, [phase]);
+    // Forward every newly-appended engine event to `onTrace`.
+    const emittedRef = useRef(0);
+    useEffect(() => {
+        const cb = onTraceRef.current;
+        if (cb) {
+            for (let i = emittedRef.current; i < events.length; i++)
+                cb(events[i]);
+        }
+        emittedRef.current = events.length;
+    }, [events]);
+    const ensureStarted = useCallback(() => {
+        if (startedRef.current)
+            return true;
+        const target = processId ?? processIds[0];
+        if (!target)
+            return false;
+        // Only latch once the instance actually started — a failed createInstance
+        // (returns null, e.g. an engine error) must stay retryable rather than
+        // wedging the demo in a non-started state.
+        if (!createInstance(target, JSON.stringify(seedRef.current ?? {}))) {
+            return false;
+        }
+        startedRef.current = true;
+        return true;
+    }, [createInstance, processId, processIds]);
+    const step = useCallback(async () => {
+        if (phase !== "ready")
+            return;
+        if (!ensureStarted())
+            return;
+        await stepWorkers(workersRef.current);
+    }, [phase, ensureStarted, stepWorkers]);
+    const play = useCallback(async () => {
+        if (phase !== "ready" || playingRef.current)
+            return;
+        if (!ensureStarted())
+            return;
+        playingRef.current = true;
+        setPlaying(true);
+        try {
+            while (playingRef.current) {
+                const round = await stepWorkers(workersRef.current);
+                if (!round || round.handled === 0)
+                    break;
+                await delay(stepDelayMs);
+            }
+        }
+        finally {
+            playingRef.current = false;
+            if (mountedRef.current)
+                setPlaying(false);
+        }
+    }, [phase, ensureStarted, stepWorkers, stepDelayMs]);
+    const pause = useCallback(() => {
+        playingRef.current = false;
+        setPlaying(false);
+    }, []);
+    const restart = useCallback(() => {
+        playingRef.current = false;
+        setPlaying(false);
+        startedRef.current = false;
+        reset();
+    }, [reset]);
+    // Autoplay once, when the engine first becomes ready.
+    const autoplayedRef = useRef(false);
+    useEffect(() => {
+        if (autoplay && phase === "ready" && !autoplayedRef.current) {
+            autoplayedRef.current = true;
+            void play();
+        }
+        if (phase === "loading")
+            autoplayedRef.current = false;
+    }, [autoplay, phase, play]);
+    const ready = phase === "ready";
+    const instance = snapshot?.instances[0];
+    const variables = instance?.variables ?? {};
+    return (_jsxs("div", { className: className, style: { display: "flex", flexDirection: "column", gap: 8, minHeight: 320 }, children: [_jsx("style", { children: MARKER_CSS }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: 8 }, children: [_jsx("button", { type: "button", onClick: play, disabled: !ready || playing, children: "\u25B6 Play" }), _jsx("button", { type: "button", onClick: pause, disabled: !playing, children: "\u23F8 Pause" }), _jsx("button", { type: "button", onClick: step, disabled: !ready || playing, children: "\u23ED Step" }), _jsx("button", { type: "button", onClick: restart, disabled: !ready, children: "\u21BA Reset" }), _jsx("span", { style: { marginLeft: "auto", fontSize: 12, opacity: 0.7 }, children: error
+                            ? `error: ${error}`
+                            : phase === "loading"
+                                ? "loading engine…"
+                                : instance
+                                    ? instance.completed
+                                        ? "completed"
+                                        : "running"
+                                    : "ready" })] }), _jsxs("div", { style: { display: "flex", gap: 8, flex: 1, minHeight: 280 }, children: [_jsx("div", { className: "bojtos-diagram", style: { flex: 2, border: "1px solid #e5e7eb", borderRadius: 6 }, children: _jsx(BpmnRuntimeView, { xml: bpmn, activeIds: snapshot?.activeElementIds ?? [], incidentIds: snapshot?.incidentElementIds ?? [] }) }), _jsxs("div", { style: {
+                            flex: 1,
+                            minWidth: 200,
+                            border: "1px solid #e5e7eb",
+                            borderRadius: 6,
+                            padding: 8,
+                            overflow: "auto",
+                            font: "12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace",
+                            background: "#f9fafb",
+                        }, children: [_jsx("div", { style: { fontWeight: 600, marginBottom: 4 }, children: "Variables" }), _jsx("pre", { style: { margin: 0, whiteSpace: "pre-wrap" }, children: JSON.stringify(variables, null, 2) })] })] })] }));
+}

package/dist/BpmnRuntimeView.d.ts

@@ -0,0 +1,23 @@
+export interface BpmnRuntimeViewProps {
+    /** The diagram XML to render. */
+    xml: string;
+    /** Element ids to highlight as active (token) — marker class `nano-active`. */
+    activeIds: string[];
+    /** Element ids to highlight as incidents — marker class `nano-incident`. */
+    incidentIds: string[];
+    /** Optional class for the container element (it always fills its parent). */
+    className?: string;
+}
+/**
+ * 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
+ * stepping through the simulation). This is the token-movement half of the
+ * Bojtos visual contract (ADR 0043 §4): drive `activeIds` / `incidentIds` from a
+ * session snapshot's `activeElementIds` / `incidentElementIds`.
+ *
+ * The consumer must load bpmn-js's diagram CSS (`bpmn-js/dist/assets/
+ * diagram-js.css` and `.../bpmn-font/css/bpmn-embedded.css`) once in the app,
+ * 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;

package/dist/BpmnRuntimeView.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import NavigatedViewer from "bpmn-js/lib/NavigatedViewer";
+/**
+ * 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
+ * stepping through the simulation). This is the token-movement half of the
+ * Bojtos visual contract (ADR 0043 §4): drive `activeIds` / `incidentIds` from a
+ * session snapshot's `activeElementIds` / `incidentElementIds`.
+ *
+ * The consumer must load bpmn-js's diagram CSS (`bpmn-js/dist/assets/
+ * diagram-js.css` and `.../bpmn-font/css/bpmn-embedded.css`) once in the app,
+ * 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, }) {
+    const containerRef = useRef(null);
+    const viewerRef = useRef(null);
+    const importedRef = useRef(false);
+    const markedRef = useRef([]);
+    const tokenOverlaysRef = useRef([]);
+    // Track the latest ids in a ref so the post-import `applyMarkers()` (fired from
+    // the `[xml]` effect's async `.then`) uses current values, not the ids that
+    // were current when the import started — otherwise ids changing mid-import
+    // would leave the diagram unmarked until the next change.
+    const idsRef = useRef({ activeIds, incidentIds });
+    idsRef.current = { activeIds, incidentIds };
+    useEffect(() => {
+        if (!containerRef.current)
+            return;
+        const viewer = new NavigatedViewer({ container: containerRef.current });
+        viewerRef.current = viewer;
+        importedRef.current = false;
+        viewer
+            .importXML(xml)
+            .then(() => {
+            viewer.get("canvas").zoom("fit-viewport");
+            importedRef.current = true;
+            applyMarkers();
+        })
+            .catch(() => {
+            /* malformed XML — leave blank */
+        });
+        return () => {
+            viewer.destroy();
+            viewerRef.current = null;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [xml]);
+    function applyMarkers() {
+        const viewer = viewerRef.current;
+        if (!viewer || !importedRef.current)
+            return;
+        const canvas = viewer.get("canvas");
+        for (const { id, cls } of markedRef.current) {
+            try {
+                canvas.removeMarker(id, cls);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const next = [];
+        for (const id of idsRef.current.activeIds)
+            next.push({ id, cls: "nano-active" });
+        for (const id of idsRef.current.incidentIds)
+            next.push({ id, cls: "nano-incident" });
+        for (const { id, cls } of next) {
+            try {
+                canvas.addMarker(id, cls);
+            }
+            catch {
+                /* element not in this diagram */
+            }
+        }
+        markedRef.current = next;
+        // A visible token badge on each active element: an explicit "token is here"
+        // marker so movement reads clearly even when a class-only highlight is too
+        // subtle. Overlays are removed/re-added each update so the token hops with
+        // the frontier.
+        const overlays = viewer.get("overlays");
+        for (const id of tokenOverlaysRef.current) {
+            try {
+                overlays.remove(id);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const nextOverlays = [];
+        for (const id of idsRef.current.activeIds) {
+            try {
+                nextOverlays.push(overlays.add(id, {
+                    position: { top: -12, left: -12 },
+                    html: '<div class="nano-token" aria-hidden="true"></div>',
+                }));
+            }
+            catch {
+                /* element not in this diagram */
+            }
+        }
+        tokenOverlaysRef.current = nextOverlays;
+    }
+    useEffect(() => {
+        applyMarkers();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeIds, incidentIds]);
+    return (_jsx("div", { ref: containerRef, className: className, style: { width: "100%", height: "100%" } }));
+}

package/dist/examples/orderFulfillment.d.ts

@@ -0,0 +1,17 @@
+import type { JobHandler } from "@nanobpm/bojtos-kit";
+/**
+ * A laid-out order-fulfillment diagram: start → reserve stock (inventory) →
+ * charge card (payment) → ship (shipping) → done. Unlike the headless engine
+ * fixtures, this carries `bpmndi` diagram-interchange so bpmn-js actually
+ * renders the shapes for the token to walk across.
+ */
+export declare const ORDER_FULFILLMENT_BPMN = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\" xmlns:bpmndi=\"http://www.omg.org/spec/BPMN/20100524/DI\" xmlns:dc=\"http://www.omg.org/spec/DD/20100524/DC\" xmlns:di=\"http://www.omg.org/spec/DD/20100524/DI\" xmlns:zeebe=\"http://camunda.org/schema/zeebe/1.0\" id=\"order-fulfillment-defs\" targetNamespace=\"http://bpmn.io/schema/bpmn\">\n  <bpmn:process id=\"order-fulfillment\" isExecutable=\"true\">\n    <bpmn:startEvent id=\"start\" name=\"Order placed\">\n      <bpmn:outgoing>f1</bpmn:outgoing>\n    </bpmn:startEvent>\n    <bpmn:serviceTask id=\"reserve\" name=\"Reserve stock\">\n      <bpmn:extensionElements><zeebe:taskDefinition type=\"inventory\" /></bpmn:extensionElements>\n      <bpmn:incoming>f1</bpmn:incoming>\n      <bpmn:outgoing>f2</bpmn:outgoing>\n    </bpmn:serviceTask>\n    <bpmn:serviceTask id=\"charge\" name=\"Charge card\">\n      <bpmn:extensionElements><zeebe:taskDefinition type=\"payment\" /></bpmn:extensionElements>\n      <bpmn:incoming>f2</bpmn:incoming>\n      <bpmn:outgoing>f3</bpmn:outgoing>\n    </bpmn:serviceTask>\n    <bpmn:serviceTask id=\"ship\" name=\"Ship\">\n      <bpmn:extensionElements><zeebe:taskDefinition type=\"shipping\" /></bpmn:extensionElements>\n      <bpmn:incoming>f3</bpmn:incoming>\n      <bpmn:outgoing>f4</bpmn:outgoing>\n    </bpmn:serviceTask>\n    <bpmn:endEvent id=\"done\" name=\"Fulfilled\">\n      <bpmn:incoming>f4</bpmn:incoming>\n    </bpmn:endEvent>\n    <bpmn:sequenceFlow id=\"f1\" sourceRef=\"start\" targetRef=\"reserve\" />\n    <bpmn:sequenceFlow id=\"f2\" sourceRef=\"reserve\" targetRef=\"charge\" />\n    <bpmn:sequenceFlow id=\"f3\" sourceRef=\"charge\" targetRef=\"ship\" />\n    <bpmn:sequenceFlow id=\"f4\" sourceRef=\"ship\" targetRef=\"done\" />\n  </bpmn:process>\n  <bpmndi:BPMNDiagram id=\"diagram\">\n    <bpmndi:BPMNPlane id=\"plane\" bpmnElement=\"order-fulfillment\">\n      <bpmndi:BPMNShape id=\"start_di\" bpmnElement=\"start\">\n        <dc:Bounds x=\"150\" y=\"102\" width=\"36\" height=\"36\" />\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"reserve_di\" bpmnElement=\"reserve\">\n        <dc:Bounds x=\"240\" y=\"80\" width=\"100\" height=\"80\" />\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"charge_di\" bpmnElement=\"charge\">\n        <dc:Bounds x=\"400\" y=\"80\" width=\"100\" height=\"80\" />\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"ship_di\" bpmnElement=\"ship\">\n        <dc:Bounds x=\"560\" y=\"80\" width=\"100\" height=\"80\" />\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"done_di\" bpmnElement=\"done\">\n        <dc:Bounds x=\"720\" y=\"102\" width=\"36\" height=\"36\" />\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNEdge id=\"f1_di\" bpmnElement=\"f1\">\n        <di:waypoint x=\"186\" y=\"120\" />\n        <di:waypoint x=\"240\" y=\"120\" />\n      </bpmndi:BPMNEdge>\n      <bpmndi:BPMNEdge id=\"f2_di\" bpmnElement=\"f2\">\n        <di:waypoint x=\"340\" y=\"120\" />\n        <di:waypoint x=\"400\" y=\"120\" />\n      </bpmndi:BPMNEdge>\n      <bpmndi:BPMNEdge id=\"f3_di\" bpmnElement=\"f3\">\n        <di:waypoint x=\"500\" y=\"120\" />\n        <di:waypoint x=\"560\" y=\"120\" />\n      </bpmndi:BPMNEdge>\n      <bpmndi:BPMNEdge id=\"f4_di\" bpmnElement=\"f4\">\n        <di:waypoint x=\"660\" y=\"120\" />\n        <di:waypoint x=\"720\" y=\"120\" />\n      </bpmndi:BPMNEdge>\n    </bpmndi:BPMNPlane>\n  </bpmndi:BPMNDiagram>\n</bpmn:definitions>";
+/**
+ * The in-browser workers for {@link ORDER_FULFILLMENT_BPMN}. Each reads the
+ * instance's live payload and returns the variables it adds — edit a handler and
+ * re-run to watch the payload change (ADR 0043 §8 step 4 makes these boxes
+ * editable in the browser).
+ */
+export declare const orderFulfillmentWorkers: Record<string, JobHandler>;
+/** A ready-to-drop-in Bojtos demo — the canonical first example (ADR 0043 §8). */
+export declare function OrderFulfillmentDemo(): import("react").JSX.Element;

package/dist/examples/orderFulfillment.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Bojtos } from "../Bojtos.js";
+/**
+ * A laid-out order-fulfillment diagram: start → reserve stock (inventory) →
+ * charge card (payment) → ship (shipping) → done. Unlike the headless engine
+ * fixtures, this carries `bpmndi` diagram-interchange so bpmn-js actually
+ * renders the shapes for the token to walk across.
+ */
+export const ORDER_FULFILLMENT_BPMN = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="order-fulfillment-defs" targetNamespace="http://bpmn.io/schema/bpmn">
+  <bpmn:process id="order-fulfillment" isExecutable="true">
+    <bpmn:startEvent id="start" name="Order placed">
+      <bpmn:outgoing>f1</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:serviceTask id="reserve" name="Reserve stock">
+      <bpmn:extensionElements><zeebe:taskDefinition type="inventory" /></bpmn:extensionElements>
+      <bpmn:incoming>f1</bpmn:incoming>
+      <bpmn:outgoing>f2</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="charge" name="Charge card">
+      <bpmn:extensionElements><zeebe:taskDefinition type="payment" /></bpmn:extensionElements>
+      <bpmn:incoming>f2</bpmn:incoming>
+      <bpmn:outgoing>f3</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="ship" name="Ship">
+      <bpmn:extensionElements><zeebe:taskDefinition type="shipping" /></bpmn:extensionElements>
+      <bpmn:incoming>f3</bpmn:incoming>
+      <bpmn:outgoing>f4</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:endEvent id="done" name="Fulfilled">
+      <bpmn:incoming>f4</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="f1" sourceRef="start" targetRef="reserve" />
+    <bpmn:sequenceFlow id="f2" sourceRef="reserve" targetRef="charge" />
+    <bpmn:sequenceFlow id="f3" sourceRef="charge" targetRef="ship" />
+    <bpmn:sequenceFlow id="f4" sourceRef="ship" targetRef="done" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="diagram">
+    <bpmndi:BPMNPlane id="plane" bpmnElement="order-fulfillment">
+      <bpmndi:BPMNShape id="start_di" bpmnElement="start">
+        <dc:Bounds x="150" y="102" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="reserve_di" bpmnElement="reserve">
+        <dc:Bounds x="240" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="charge_di" bpmnElement="charge">
+        <dc:Bounds x="400" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="ship_di" bpmnElement="ship">
+        <dc:Bounds x="560" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="done_di" bpmnElement="done">
+        <dc:Bounds x="720" y="102" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="f1_di" bpmnElement="f1">
+        <di:waypoint x="186" y="120" />
+        <di:waypoint x="240" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="f2_di" bpmnElement="f2">
+        <di:waypoint x="340" y="120" />
+        <di:waypoint x="400" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="f3_di" bpmnElement="f3">
+        <di:waypoint x="500" y="120" />
+        <di:waypoint x="560" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="f4_di" bpmnElement="f4">
+        <di:waypoint x="660" y="120" />
+        <di:waypoint x="720" y="120" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>`;
+/**
+ * The in-browser workers for {@link ORDER_FULFILLMENT_BPMN}. Each reads the
+ * instance's live payload and returns the variables it adds — edit a handler and
+ * re-run to watch the payload change (ADR 0043 §8 step 4 makes these boxes
+ * editable in the browser).
+ */
+export const orderFulfillmentWorkers = {
+    inventory: (job) => ({ reserved: true, sku: job.variables.sku }),
+    payment: (job) => ({ charged: job.variables.amount ?? 0 }),
+    shipping: () => ({ tracking: `1Z${Math.floor(Math.random() * 1e9)}` }),
+};
+/** A ready-to-drop-in Bojtos demo — the canonical first example (ADR 0043 §8). */
+export function OrderFulfillmentDemo() {
+    return (_jsx(Bojtos, { bpmn: ORDER_FULFILLMENT_BPMN, workers: orderFulfillmentWorkers, seed: { sku: "WIDGET-1", amount: 4200 }, autoplay: true }));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { useBojtos, type UseBojtosOptions, type BojtosControls, 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 { JobFailure, type JobHandler, type JobResult, type DispatchOptions, type DispatchResult, type RoundResult, } from "@nanobpm/bojtos-kit";
+export type { BojtosSession, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, WasmEvent, } from "@nanobpm/bojtos-kit";

package/dist/index.js

@@ -0,0 +1,10 @@
+// @nanobpm/bojtos-react — the React binding for the Bojtos in-browser BPMN demo
+// framework (ADR 0043). `useBojtos` owns the engine session and reactive state;
+// `<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 { 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";

package/dist/useBojtos.d.ts

@@ -0,0 +1,70 @@
+import { 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;
+    /**
+     * Optional engine wasm source. Pass a `URL` / bytes / `WebAssembly.Module`
+     * when the default `import.meta.url` loader can't resolve the binary (the
+     * external-`.wasm` "wasmUrl" mode, or a non-Vite bundler — ADR 0043 §3).
+     *
+     * Init-time only: the wasm module loads once per page (see `ensureWasm`), so
+     * changing `wasm` after the first successful init has no effect — it will not
+     * reload the module.
+     */
+    wasm?: WasmSource;
+}
+export interface BojtosControls {
+    phase: BojtosPhase;
+    error: string | null;
+    /** Deployable process ids from the current deployment. */
+    processIds: string[];
+    /** The latest snapshot, or `null` before the first command / after a reset. */
+    snapshot: Snapshot | null;
+    /** The engine's full event log after the latest command. */
+    events: WasmEvent[];
+    /** Start an instance; returns the post-run snapshot (with `created`) or null. */
+    createInstance(processId: string, variablesJson: string): Snapshot | null;
+    /** Complete a waiting job, merging output variables. */
+    completeJob(jobKey: string, variablesJson: string): Snapshot | null;
+    /** Fail a waiting job (raises an incident with no retries left). */
+    failJob(jobKey: string, retries: number, message: string): Snapshot | null;
+    /**
+     * Correlate a message to an instance parked at a message catch/receive:
+     * publishes `messageName` with `correlationKey` and merges `variablesJson`.
+     * The in-browser equivalent of an app publishing a message — used to unblock
+     * a waiting loop (e.g. urban-pr-review's `review-ready`).
+     */
+    correlateMessage(messageName: string, correlationKey: string, variablesJson: string): Snapshot | null;
+    /** Advance the virtual clock. */
+    advanceTime(byMs: number): Snapshot | null;
+    /**
+     * Run the registered worker handlers until the process settles (activate →
+     * handler → complete/fail), then reflect the resulting snapshot/events.
+     * Resolves to the settled snapshot, or null if there is no live session.
+     */
+    runWorkers(workers: Record<string, JobHandler>, opts?: DispatchOptions): Promise<Snapshot | null>;
+    /**
+     * Run a single activate-and-handle pass of the registered workers (one
+     * {@link dispatchRound}), reflecting the resulting snapshot/events. Returns
+     * how many jobs it handled (0 once the process is quiescent) plus the
+     * snapshot, or null if there is no live session — drive it on a timer to
+     * animate the token advancing one step at a time.
+     */
+    stepWorkers(workers: Record<string, JobHandler>, opts?: DispatchOptions): Promise<RoundResult | null>;
+    /** Re-deploy the diagram on the existing engine, clearing run state. */
+    reset(): void;
+}
+/**
+ * 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 declare function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls;