@nanobpm/bojtos-react 0.1.0

package/dist/useBojtos.js

@@ -0,0 +1,177 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createBojtosSession, dispatchRound, dispatchWorkers, } from "@nanobpm/bojtos-kit";
+/**
+ * React binding over a headless {@link BojtosSession}: owns the engine's
+ * lifecycle and the reactive `snapshot` / `events` / `processIds` state, and
+ * exposes the engine commands. The consuming component owns its own form state
+ * (selected process, seed vars, per-job output) and drives the visual contract
+ * (`<BpmnRuntimeView>` + the variable payload) off `snapshot`.
+ *
+ * This is the reactive half of the Bojtos public API (ADR 0043 §2); the console
+ * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
+ * test).
+ */
+export function useBojtos({ bpmn, wasm }) {
+    const sessionRef = useRef(null);
+    const [phase, setPhase] = useState("loading");
+    const [error, setError] = useState(null);
+    const [processIds, setProcessIds] = useState([]);
+    const [snapshot, setSnapshot] = useState(null);
+    const [events, setEvents] = useState([]);
+    // The wasm source is an init-time concern (the first `ensureWasm` wins), so
+    // keep it in a ref rather than the mount effect's deps — a fresh URL/bytes
+    // identity each render must not re-create the session.
+    const wasmRef = useRef(wasm);
+    wasmRef.current = wasm;
+    const deployInto = useCallback((session) => {
+        const res = session.deploy(bpmn);
+        setProcessIds(res.processIds);
+        setSnapshot(null);
+        setEvents([]);
+        setError(null);
+    }, [bpmn]);
+    useEffect(() => {
+        let cancelled = false;
+        // A new diagram means a fresh engine: drop back to `loading` and clear the
+        // previous session's state — including `processIds` — so consumers never
+        // see `ready` (or a stale process list) against a freed session while the
+        // new one is still loading.
+        setPhase("loading");
+        setProcessIds([]);
+        setSnapshot(null);
+        setEvents([]);
+        setError(null);
+        createBojtosSession({ wasm: wasmRef.current })
+            .then((session) => {
+            if (cancelled) {
+                session.free();
+                return;
+            }
+            try {
+                deployInto(session);
+            }
+            catch (e) {
+                // A failed deploy (e.g. invalid BPMN) must free the just-created
+                // engine rather than leak it until unmount, and must not be stored
+                // as the active session.
+                session.free();
+                setError(String(e));
+                setPhase("error");
+                return;
+            }
+            sessionRef.current = session;
+            setPhase("ready");
+        })
+            .catch((e) => {
+            if (cancelled)
+                return;
+            setError(String(e));
+            setPhase("error");
+        });
+        return () => {
+            cancelled = true;
+            sessionRef.current?.free();
+            sessionRef.current = null;
+        };
+    }, [deployInto]);
+    const run = useCallback((fn) => {
+        const session = sessionRef.current;
+        if (!session)
+            return null;
+        try {
+            const snap = fn(session);
+            setSnapshot(snap);
+            setEvents(session.events());
+            setError(null);
+            return snap;
+        }
+        catch (e) {
+            setError(String(e));
+            return null;
+        }
+    }, []);
+    const createInstance = useCallback((processId, variablesJson) => run((s) => s.createInstance(processId, variablesJson)), [run]);
+    const completeJob = useCallback((jobKey, variablesJson) => run((s) => s.completeJob(jobKey, variablesJson)), [run]);
+    const 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 runWorkers = useCallback(async (workers, opts) => {
+        const session = sessionRef.current;
+        if (!session)
+            return null;
+        try {
+            const { snapshot: settled } = await dispatchWorkers(session, workers, opts);
+            // The session may have been torn down/replaced (bpmn change, unmount)
+            // while we awaited — don't publish stale state or read a freed session.
+            if (sessionRef.current !== session)
+                return null;
+            setSnapshot(settled);
+            setEvents(session.events());
+            setError(null);
+            return settled;
+        }
+        catch (e) {
+            if (sessionRef.current !== session)
+                return null;
+            // 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());
+            setError(String(e));
+            return null;
+        }
+    }, []);
+    const stepWorkers = useCallback(async (workers, opts) => {
+        const session = sessionRef.current;
+        if (!session)
+            return null;
+        try {
+            const round = await dispatchRound(session, workers, opts);
+            // Bail if the session was replaced/freed while we awaited the round.
+            if (sessionRef.current !== session)
+                return null;
+            setSnapshot(round.snapshot);
+            setEvents(session.events());
+            setError(null);
+            return round;
+        }
+        catch (e) {
+            if (sessionRef.current !== session)
+                return null;
+            setSnapshot(session.snapshot());
+            setEvents(session.events());
+            setError(String(e));
+            return null;
+        }
+    }, []);
+    const reset = useCallback(() => {
+        const session = sessionRef.current;
+        if (!session)
+            return;
+        try {
+            // Wipe the engine to its pristine state, then redeploy the diagram, so a
+            // re-run starts from zero instances/completions rather than accumulating
+            // across runs (a plain redeploy leaves prior instances resident).
+            session.reset();
+            deployInto(session);
+        }
+        catch (e) {
+            setError(String(e));
+        }
+    }, [deployInto]);
+    return {
+        phase,
+        error,
+        processIds,
+        snapshot,
+        events,
+        createInstance,
+        completeJob,
+        failJob,
+        advanceTime,
+        correlateMessage,
+        runWorkers,
+        stepWorkers,
+        reset,
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@nanobpm/bojtos-react",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Magikcraft/nano-bpm",
+    "directory": "bojtos-react"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./source": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@nanobpm/bojtos-kit": "^0.1.0"
+  },
+  "peerDependencies": {
+    "bpmn-js": ">=17",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.11",
+    "react": "^18.3.1",
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Bojtos.tsx

@@ -0,0 +1,263 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { JobHandler, WasmEvent } from "@nanobpm/bojtos-kit";
+import { BpmnRuntimeView } from "./BpmnRuntimeView.js";
+import { useBojtos } from "./useBojtos.js";
+
+/** 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;
+}
+
+const delay = (ms: number) => new Promise<void>((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,
+}: BojtosProps) {
+  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((): boolean => {
+    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 (
+    <div
+      className={className}
+      style={{ display: "flex", flexDirection: "column", gap: 8, minHeight: 320 }}
+    >
+      <style>{MARKER_CSS}</style>
+      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+        <button type="button" onClick={play} disabled={!ready || playing}>
+          ▶ Play
+        </button>
+        <button type="button" onClick={pause} disabled={!playing}>
+          ⏸ Pause
+        </button>
+        <button type="button" onClick={step} disabled={!ready || playing}>
+          ⏭ Step
+        </button>
+        <button type="button" onClick={restart} disabled={!ready}>
+          ↺ Reset
+        </button>
+        <span style={{ marginLeft: "auto", fontSize: 12, opacity: 0.7 }}>
+          {error
+            ? `error: ${error}`
+            : phase === "loading"
+              ? "loading engine…"
+              : instance
+                ? instance.completed
+                  ? "completed"
+                  : "running"
+                : "ready"}
+        </span>
+      </div>
+      <div style={{ display: "flex", gap: 8, flex: 1, minHeight: 280 }}>
+        <div
+          className="bojtos-diagram"
+          style={{ flex: 2, border: "1px solid #e5e7eb", borderRadius: 6 }}
+        >
+          <BpmnRuntimeView
+            xml={bpmn}
+            activeIds={snapshot?.activeElementIds ?? []}
+            incidentIds={snapshot?.incidentElementIds ?? []}
+          />
+        </div>
+        <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",
+          }}
+        >
+          <div style={{ fontWeight: 600, marginBottom: 4 }}>Variables</div>
+          <pre style={{ margin: 0, whiteSpace: "pre-wrap" }}>
+            {JSON.stringify(variables, null, 2)}
+          </pre>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/BpmnRuntimeView.tsx

@@ -0,0 +1,148 @@
+import { useEffect, useRef } from "react";
+import NavigatedViewer from "bpmn-js/lib/NavigatedViewer";
+
+interface Canvas {
+  zoom(mode: string): void;
+  addMarker(elementId: string, marker: string): void;
+  removeMarker(elementId: string, marker: string): void;
+}
+
+interface Overlays {
+  add(
+    elementId: string,
+    overlay: {
+      position: Record<string, number>;
+      html: string | HTMLElement;
+    },
+  ): string;
+  remove(id: string): void;
+}
+
+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 function BpmnRuntimeView({
+  xml,
+  activeIds,
+  incidentIds,
+  className,
+}: BpmnRuntimeViewProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const viewerRef = useRef<NavigatedViewer | null>(null);
+  const importedRef = useRef(false);
+  const markedRef = useRef<{ id: string; cls: string }[]>([]);
+  const tokenOverlaysRef = useRef<string[]>([]);
+  // 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>("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>("canvas");
+    for (const { id, cls } of markedRef.current) {
+      try {
+        canvas.removeMarker(id, cls);
+      } catch {
+        /* ignore */
+      }
+    }
+    const next: { id: string; cls: string }[] = [];
+    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>("overlays");
+    for (const id of tokenOverlaysRef.current) {
+      try {
+        overlays.remove(id);
+      } catch {
+        /* ignore */
+      }
+    }
+    const nextOverlays: string[] = [];
+    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 (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{ width: "100%", height: "100%" }}
+    />
+  );
+}

package/src/bpmn-js.d.ts

@@ -0,0 +1,18 @@
+// bpmn-js ships no types for the `NavigatedViewer` entry point; declare the
+// minimal surface `BpmnRuntimeView` uses. This ambient declaration is a build-
+// time input only — it is never emitted into `dist/`, so it cannot collide with
+// a consumer's own bpmn-js typings.
+declare module "bpmn-js/lib/NavigatedViewer" {
+  export interface ImportResult {
+    warnings: unknown[];
+  }
+  export default class NavigatedViewer {
+    constructor(options: { container: HTMLElement });
+    importXML(xml: string): Promise<ImportResult>;
+    get<T = unknown>(service: string): T;
+    destroy(): void;
+  }
+}
+
+declare module "bpmn-js/dist/assets/diagram-js.css";
+declare module "bpmn-js/dist/assets/bpmn-font/css/bpmn-embedded.css";