@nanobpm/bojtos-react 0.5.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

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,6 +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 { TraceTimeline, type TraceTimelineProps } from "./TraceTimeline.js";
 export { describeRunState, markerKey, bpmnKey, resourceList, capEvents, } from "./runState.js";
-export { JobFailure, settleReason, unhandledJobTypes, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, type SettleReason, } from "@nanobpm/bojtos-kit";
-export type { BojtosSession, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, UserTaskDto, MessageSubscriptionDto, SignalSubscriptionDto, ElementStatDto, SequenceFlowDto, DecisionInstanceDto, ActiveEl, ActivateInstruction, AgentActivation, AgentResult, WasmEvent, } from "@nanobpm/bojtos-kit";
+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,5 +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";
+// 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, } from "@nanobpm/bojtos-kit";
+export { JobFailure, settleReason, unhandledJobTypes, buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } from "@nanobpm/bojtos-kit";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-react",
-  "version": "0.5.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",
@@ -32,7 +32,7 @@
     "test:ci": "node --experimental-strip-types --test test/*.test.ts"
   },
   "dependencies": {
-    "@nanobpm/bojtos-kit": "^0.5.0"
+    "@nanobpm/bojtos-kit": "^0.6.0"
   },
   "peerDependencies": {
     "bpmn-js": ">=17",

package/src/TraceTimeline.tsx

@@ -0,0 +1,303 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  buildTraceItems,
+  isTraceTurnGroup,
+  type ElementStatDto,
+  type IncidentDto,
+  type TraceItem,
+  type TraceRow,
+  type TraceTurnGroup,
+} 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;
+}
+
+function safeStringify(value: unknown, space?: number): string {
+  // `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,
+}: {
+  activation: TraceRow;
+  result: TraceRow | undefined;
+  labelFor: (elementId: string) => string;
+}) {
+  const elementId = activation.elementId ?? "";
+  return (
+    <div className="timeline-tool">
+      <div className="timeline-tool-head">
+        <span className="timeline-badge timeline-badge-info">tool</span>
+        <strong>{labelFor(elementId) || elementId}</strong>
+        <code>{elementId}</code>
+      </div>
+      {activation.args !== undefined &&
+        Object.keys(activation.args).length > 0 && (
+          <div className="timeline-kv">
+            <span className="timeline-kv-label">arguments</span>
+            <code>{safeStringify(activation.args)}</code>
+          </div>
+        )}
+      <div className="timeline-kv">
+        <span className="timeline-kv-label">returned</span>
+        <code>
+          {result
+            ? safeStringify(result.result)
+            : "— waiting for the job to complete —"}
+        </code>
+      </div>
+    </div>
+  );
+}
+
+function TurnCard({
+  group,
+  labelFor,
+}: {
+  group: TraceTurnGroup;
+  labelFor: (elementId: string) => string;
+}) {
+  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 (
+    <div className="timeline-turn">
+      <div className="timeline-turn-head">
+        <span
+          className={`timeline-badge ${
+            reply?.pending ? "timeline-badge-warning" : "timeline-badge-neutral"
+          }`}
+        >
+          Turn {group.turn}
+        </span>
+        {reply?.pending && <span className="timeline-pending">thinking…</span>}
+      </div>
+
+      {reply && <blockquote className="timeline-reply">{reply.text}</blockquote>}
+
+      {decisions.map((d) => (
+        <div key={d.key ?? d.id} className="timeline-note">
+          {d.text}
+        </div>
+      ))}
+
+      {activations.map((a) => (
+        <ToolStep
+          key={a.key ?? a.id}
+          activation={a}
+          result={results.find((r) => r.elementId === a.elementId)}
+          labelFor={labelFor}
+        />
+      ))}
+
+      {loose.map((e) => (
+        <div key={e.key ?? e.id} className={`log-line log-${e.kind}`}>
+          {e.pending ? "⏳ " : ""}
+          {e.text}
+        </div>
+      ))}
+
+      {errors.map((e) => (
+        <div key={e.id} className="timeline-error">
+          ⚠ {e.text}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+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,
+}: TraceTimelineProps) {
+  const items: TraceItem[] = useMemo(() => buildTraceItems(rows), [rows]);
+  const [copied, setCopied] = useState(false);
+  const scrollRef = useRef<HTMLDivElement>(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 (
+    <div className={className ? `timeline-panel ${className}` : "timeline-panel"}>
+      <div className="timeline-header">
+        <div className="timeline-title">{title}</div>
+        {description && (
+          <div className="timeline-description">{description}</div>
+        )}
+      </div>
+
+      <div className="timeline-toolbar">
+        <button type="button" onClick={copyJson}>
+          {copied ? "Copied!" : "Copy run as JSON"}
+        </button>
+      </div>
+
+      <div className="timeline" ref={scrollRef}>
+        {items.length === 0 ? (
+          <div className="log-empty">{emptyText}</div>
+        ) : (
+          items.map((item) =>
+            isTraceTurnGroup(item) ? (
+              <TurnCard
+                key={`turn-${item.turn}-${item.rows[0].key ?? item.rows[0].id}`}
+                group={item}
+                labelFor={labelFor}
+              />
+            ) : (
+              <div key={item.key ?? item.id} className={`log-line log-${item.kind}`}>
+                {item.pending ? "⏳ " : ""}
+                {item.text}
+              </div>
+            ),
+          )
+        )}
+      </div>
+
+      {(elementStats.length > 0 || incidents.length > 0) && (
+        <div className="timeline-engine-view">
+          {elementStats.length > 0 && (
+            <div className="timeline-stats">
+              <span className="timeline-kv-label">Element completion</span>
+              <ul>
+                {elementStats
+                  .filter((s) => s.completed > 0 || (s.active ?? 0) > 0)
+                  .map((s) => (
+                    <li key={s.elementId}>
+                      <code>{labelFor(s.elementId) || s.elementId}</code>{" "}
+                      completed {s.completed}
+                      {s.active ? `, ${s.active} active` : ""}
+                    </li>
+                  ))}
+              </ul>
+            </div>
+          )}
+          {incidents.length > 0 && (
+            <div className="timeline-incidents">
+              <span className="timeline-kv-label">Incidents</span>
+              <ul>
+                {incidents.map((inc, i) => (
+                  <li key={`${inc.elementId}-${i}`}>
+                    <code>{labelFor(inc.elementId) || inc.elementId}</code> —{" "}
+                    {inc.reason}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -20,6 +20,9 @@ export {
   BpmnRuntimeView,
   type BpmnRuntimeViewProps,
 } from "./BpmnRuntimeView.js";
+// The shared activity log (#9). Trace-only imports tree-shake bpmn-js out —
+// TraceTimeline imports only the kit + React, never BpmnRuntimeView.
+export { TraceTimeline, type TraceTimelineProps } from "./TraceTimeline.js";
 export {
   describeRunState,
   markerKey,
@@ -31,6 +34,10 @@ export {
   JobFailure,
   settleReason,
   unhandledJobTypes,
+  buildTraceItems,
+  isTraceTurnGroup,
+  foldEngineEvents,
+  traceEntriesToRows,
   type JobHandler,
   type JobResult,
   type AgentHandler,
@@ -58,4 +65,10 @@ export type {
   AgentActivation,
   AgentResult,
   WasmEvent,
+  TraceRowKind,
+  TraceEntry,
+  TraceRow,
+  TraceTurnGroup,
+  TraceItem,
+  TraceAdapter,
 } from "@nanobpm/bojtos-kit";