live-traces 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+# live-traces
+
+> Real-time Effect span streaming to frontend UIs. Stream traces from any backend to React with zero overhead.
+
+[![npm version](https://img.shields.io/npm/v/live-traces.svg)](https://www.npmjs.com/package/live-traces)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![CI](https://github.com/necmttn/live-traces/actions/workflows/ci.yml/badge.svg)](https://github.com/necmttn/live-traces/actions/workflows/ci.yml)
+
+`live-traces` turns the [Effect](https://effect.website) tracer into a live UI feed. Wrap a workflow in `withTrace`, mount the React hooks, and the user sees every span - start, end, log event - as it happens.
+
+- **Drop-in Tracer decorator.** Composes with `@effect/opentelemetry`. Both OTel and live traces emit in parallel.
+- **Wire format is plain JSON.** Backends in Go, Python, Rust can produce events; React consumes them the same way.
+- **Pluggable transport.** SSE included. Console for dev. WebSocket / durable queues are 30 lines.
+- **Zero-Effect frontend.** `live-traces/react` is just `useSyncExternalStore` + a reducer. Works in any React 18+ app.
+
+→ Landing page & live demo: **[live-traces.necmttn.com](https://live-traces.necmttn.com)**
+
+---
+
+## Install
+
+```bash
+bun add live-traces effect
+# or
+npm install live-traces effect
+```
+
+React consumers also need `react@>=18`.
+
+## Quick start (Effect backend)
+
+```ts
+import { Effect, Layer } from "effect";
+import {
+    LiveTraceLayer,
+    TraceSinkLive,
+    SSETransportLayer,
+    withTrace,
+    step,
+    liveTraceLogger,
+} from "live-traces";
+import { SSETransportLayer as SSE } from "live-traces/transports/sse";
+
+// 1. Compose the layer
+const TraceLive = LiveTraceLayer.pipe(
+    Layer.provide(TraceSinkLive({ flushIntervalMs: 100 })),
+    Layer.provide(SSE),
+);
+
+// 2. Wrap a workflow
+const processDocument = (docId: string) =>
+    Effect.gen(function* () {
+        yield* Effect.logInfo(`Starting ${docId}`);
+        yield* step("Parse")(parsePdf(docId));
+        yield* step("Embed")(embedChunks(docId));
+        yield* step("Index")(indexVectors(docId));
+    }).pipe(
+        withTrace({
+            traceId: `doc:${docId}`,
+            label: "Document processing",
+            scope: { type: "user", id: "alice" },
+        }),
+    );
+
+// 3. Run with the trace layer + the live logger
+Effect.runPromise(processDocument("report.pdf").pipe(Effect.provide(TraceLive)));
+```
+
+## React frontend
+
+```tsx
+import { useActiveTraces, useTrace, useTraceSteps } from "live-traces/react";
+
+function ActivityPanel() {
+    const traces = useActiveTraces();
+    return (
+        <div>
+            {traces.map((t) => (
+                <TraceCard key={t.traceId} traceId={t.traceId} />
+            ))}
+        </div>
+    );
+}
+
+function TraceCard({ traceId }: { traceId: string }) {
+    const trace = useTrace(traceId);
+    const steps = useTraceSteps(traceId);
+    if (!trace) return null;
+
+    return (
+        <div>
+            <h3>
+                {trace.label} <span>{trace.status}</span>
+            </h3>
+            <ol>
+                {steps.map((s) => (
+                    <li key={s.spanId}>
+                        {s.name} · {s.status}
+                        {s.durationMs != null && ` · ${s.durationMs.toFixed(0)}ms`}
+                    </li>
+                ))}
+            </ol>
+        </div>
+    );
+}
+```
+
+Connect the store to a transport (SSE shown):
+
+```ts
+import { getTraceStore } from "live-traces/react";
+import type { TraceEvent } from "live-traces/types";
+
+const es = new EventSource(`/traces/user/${userId}`);
+es.onmessage = (msg) => {
+    const batch: TraceEvent[] = JSON.parse(msg.data);
+    getTraceStore().dispatchBatch(batch);
+};
+```
+
+## SSE server (Bun / Node)
+
+```ts
+import { getSseBroker } from "live-traces/transports/sse";
+
+// Bun's built-in server
+Bun.serve({
+    fetch(req) {
+        const url = new URL(req.url);
+        const match = url.pathname.match(/^\/traces\/(team|org|user)\/(.+)$/);
+        if (!match) return new Response("not found", { status: 404 });
+        const [, type, id] = match;
+
+        return new Response(
+            new ReadableStream({
+                start(controller) {
+                    const unsub = getSseBroker().subscribe(
+                        { type: type as "user", id: id! },
+                        (events) => {
+                            controller.enqueue(
+                                new TextEncoder().encode(`data: ${JSON.stringify(events)}\n\n`),
+                            );
+                        },
+                    );
+                    req.signal.addEventListener("abort", () => {
+                        unsub();
+                        controller.close();
+                    });
+                },
+            }),
+            {
+                headers: {
+                    "Content-Type": "text/event-stream",
+                    "Cache-Control": "no-cache",
+                    Connection: "keep-alive",
+                },
+            },
+        );
+    },
+});
+```
+
+## Composing with OpenTelemetry
+
+`LiveTraceLayer` wraps the current tracer instead of replacing it. Build OTel **outermost** (so it sets the tracer first), then live-traces wraps it.
+
+```ts
+const Env = ServerLive.pipe(
+    Layer.provideMerge(ServicesLive),
+    Layer.provideMerge(LiveTraceLayer),  // inner: wraps OTel
+    Layer.provideMerge(TelemetryLive),   // outer: sets OTel tracer first
+);
+```
+
+OTel still receives every span. Live-traces only annotates spans inside `withTrace` scopes and streams them out - there's no double-export.
+
+## Wire format
+
+Events are a discriminated union on `_tag`:
+
+```ts
+type TraceEvent = TraceStart | SpanStart | SpanEnd | SpanEvent | TraceEnd;
+```
+
+See [`src/types.ts`](./src/types.ts) for the full schema. The `live-traces/types` sub-export is **dependency-free** - any backend can emit these as JSON.
+
+## Why?
+
+OpenTelemetry is built for ops dashboards. `live-traces` is built for **user-facing** progress UIs - the difference between "show this user what their AI agent is doing right now" and "Datadog has my p99". Same span data, different rendering target.
+
+## License
+
+Apache-2.0 © Necmettin Karakaya

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * live-traces
+ *
+ * Real-time Effect span streaming to frontend UIs.
+ *
+ * Sub-exports:
+ * - "live-traces"        — Effect Tracer decorator (this file)
+ * - "live-traces/types"  — Plain TS types, zero deps
+ * - "live-traces/react"  — React store + hooks, no Effect dep
+ */
+export { LiveTraceLayer } from "./src/Tracer.js";
+export { withTrace, step, LiveSpanRef, type LiveTraceConfig } from "./src/LiveTrace.js";
+export { liveTraceLogger } from "./src/Logger.js";
+export { TraceSink, TraceSinkLive, TraceTransportTag, ConsoleTransportLayer, type TraceTransport, type TraceSinkHandle, type TraceSinkConfig, } from "./src/Sink.js";
+export { WrappedSpan, isWrappedSpan, LiveTraceSymbol } from "./src/WrappedSpan.js";
+export { TraceEventSchema, TraceStartSchema, SpanStartSchema, SpanEndSchema, SpanEventSchema, TraceEndSchema, TraceScopeSchema, } from "./src/Schema.js";
+export type { TraceEvent, TraceStart, SpanStart, SpanEnd, SpanEvent, TraceEnd, TraceScope } from "./src/types.js";
+export { UI_STEP, TRACE_INTERNAL, LIVE_TRACE, LIVE_TRACE_ID, LIVE_TRACE_LABEL, LIVE_TRACE_SCOPE_TYPE, LIVE_TRACE_SCOPE_ID, LIVE_TRACE_PROVIDER, } from "./src/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGxF,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,EACH,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGnF,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,EACd,gBAAgB,GACnB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAElH,OAAO,EACH,OAAO,EACP,cAAc,EACd,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * live-traces
+ *
+ * Real-time Effect span streaming to frontend UIs.
+ *
+ * Sub-exports:
+ * - "live-traces"        — Effect Tracer decorator (this file)
+ * - "live-traces/types"  — Plain TS types, zero deps
+ * - "live-traces/react"  — React store + hooks, no Effect dep
+ */
+// Core tracer
+export { LiveTraceLayer } from "./src/Tracer.js";
+// User-facing API
+export { withTrace, step, LiveSpanRef } from "./src/LiveTrace.js";
+// Logger (bridges Effect.log → SpanEvent inside traced scopes)
+export { liveTraceLogger } from "./src/Logger.js";
+// Sink + transport
+export { TraceSink, TraceSinkLive, TraceTransportTag, ConsoleTransportLayer, } from "./src/Sink.js";
+// WrappedSpan (for advanced use / testing)
+export { WrappedSpan, isWrappedSpan, LiveTraceSymbol } from "./src/WrappedSpan.js";
+// Effect Schemas
+export { TraceEventSchema, TraceStartSchema, SpanStartSchema, SpanEndSchema, SpanEventSchema, TraceEndSchema, TraceScopeSchema, } from "./src/Schema.js";
+export { UI_STEP, TRACE_INTERNAL, LIVE_TRACE, LIVE_TRACE_ID, LIVE_TRACE_LABEL, LIVE_TRACE_SCOPE_TYPE, LIVE_TRACE_SCOPE_ID, LIVE_TRACE_PROVIDER, } from "./src/types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc;AACd,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,kBAAkB;AAClB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAwB,MAAM,oBAAoB,CAAC;AAExF,+DAA+D;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,mBAAmB;AACnB,OAAO,EACH,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,qBAAqB,GAIxB,MAAM,eAAe,CAAC;AAEvB,2CAA2C;AAC3C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEnF,iBAAiB;AACjB,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,EACd,gBAAgB,GACnB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACH,OAAO,EACP,cAAc,EACd,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/react/hooks.d.ts

@@ -0,0 +1,22 @@
+import type { SpanNode, TraceState } from "./store.js";
+/**
+ * Subscribe to all active traces.
+ * Returns traces sorted by startedAt descending.
+ */
+export declare function useActiveTraces(): TraceState[];
+/**
+ * Subscribe to a single trace by ID.
+ * Returns undefined if the trace doesn't exist (yet).
+ */
+export declare function useTrace(traceId: string): TraceState | undefined;
+/**
+ * Get the step spans (ui.step=true) for a trace, in chronological order.
+ * These are the user-visible processing stages.
+ */
+export declare function useTraceSteps(traceId: string): SpanNode[];
+/**
+ * Get the root span tree for a trace.
+ * Returns the root SpanNode with nested children.
+ */
+export declare function useSpanTree(traceId: string): SpanNode | undefined;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/react/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../react/hooks.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiBvD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,UAAU,EAAE,CAG9C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAGhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CASzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAOjE"}

package/dist/react/hooks.js

@@ -0,0 +1,68 @@
+/**
+ * React hooks for consuming trace data.
+ *
+ * Uses useSyncExternalStore for tear-free reads from the TraceStore.
+ * All hooks return STABLE references — derived data is computed in
+ * useMemo to prevent infinite render loops.
+ *
+ * No Effect dependency — works with any React 18+ app.
+ */
+import { useMemo, useSyncExternalStore } from "react";
+import { getTraceStore } from "./store.js";
+/** Stable empty array to avoid creating new references */
+const EMPTY_STEPS = [];
+/**
+ * Get the stable Map snapshot from the store.
+ * This is the foundation for all hooks — the Map reference only changes
+ * when the store is actually updated via dispatch().
+ */
+function useSnapshot() {
+    const store = getTraceStore();
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+/**
+ * Subscribe to all active traces.
+ * Returns traces sorted by startedAt descending.
+ */
+export function useActiveTraces() {
+    const snapshot = useSnapshot();
+    return useMemo(() => Array.from(snapshot.values()).toSorted((a, b) => b.startedAt - a.startedAt), [snapshot]);
+}
+/**
+ * Subscribe to a single trace by ID.
+ * Returns undefined if the trace doesn't exist (yet).
+ */
+export function useTrace(traceId) {
+    const snapshot = useSnapshot();
+    return useMemo(() => snapshot.get(traceId), [snapshot, traceId]);
+}
+/**
+ * Get the step spans (ui.step=true) for a trace, in chronological order.
+ * These are the user-visible processing stages.
+ */
+export function useTraceSteps(traceId) {
+    const snapshot = useSnapshot();
+    return useMemo(() => {
+        const trace = snapshot.get(traceId);
+        if (!trace)
+            return EMPTY_STEPS;
+        const steps = Array.from(trace.spans.values()).filter((s) => s.isStep);
+        if (steps.length === 0)
+            return EMPTY_STEPS;
+        return steps.toSorted((a, b) => a.startedAt - b.startedAt);
+    }, [snapshot, traceId]);
+}
+/**
+ * Get the root span tree for a trace.
+ * Returns the root SpanNode with nested children.
+ */
+export function useSpanTree(traceId) {
+    const snapshot = useSnapshot();
+    return useMemo(() => {
+        const trace = snapshot.get(traceId);
+        if (!trace || !trace.rootSpanId)
+            return undefined;
+        return trace.spans.get(trace.rootSpanId);
+    }, [snapshot, traceId]);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/react/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../react/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAItD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,WAAW,GAAe,EAAE,CAAC;AAEnC;;;;GAIG;AACH,SAAS,WAAW;IAChB,MAAM,KAAK,GAAG,aAAa,EAAE,CAAC;IAC9B,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;AACvF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;AAClH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACpC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IACzC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,EAAE;QAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK;YAAE,OAAO,WAAW,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACvE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,WAAW,CAAC;QAC3C,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACvC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,EAAE;QAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU;YAAE,OAAO,SAAS,CAAC;QAClD,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5B,CAAC"}

package/dist/react/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * live-traces/react
+ *
+ * React store and hooks for consuming trace events.
+ * Zero Effect dependency — works with any React 18+ app.
+ *
+ * Usage:
+ * ```tsx
+ * import { useActiveTraces, useTrace, useTraceSteps } from "live-traces/react"
+ *
+ * function ActivityPanel() {
+ *   const traces = useActiveTraces()
+ *   return traces.map(t => <TraceCard key={t.traceId} trace={t} />)
+ * }
+ *
+ * function TraceCard({ trace }: { trace: TraceState }) {
+ *   const steps = useTraceSteps(trace.traceId)
+ *   return steps.map(s => <StepRow key={s.spanId} step={s} />)
+ * }
+ * ```
+ */
+export { TraceStore, getTraceStore } from "./store.js";
+export type { TraceState, SpanNode, SpanEventEntry, TraceStatus } from "./store.js";
+export { useActiveTraces, useTrace, useTraceSteps, useSpanTree } from "./hooks.js";
+export { LIVE_TRACE_PROVIDER, LIVE_TRACE_SCOPE_TYPE, LIVE_TRACE_SCOPE_ID } from "../src/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGpF,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,27 @@
+/**
+ * live-traces/react
+ *
+ * React store and hooks for consuming trace events.
+ * Zero Effect dependency — works with any React 18+ app.
+ *
+ * Usage:
+ * ```tsx
+ * import { useActiveTraces, useTrace, useTraceSteps } from "live-traces/react"
+ *
+ * function ActivityPanel() {
+ *   const traces = useActiveTraces()
+ *   return traces.map(t => <TraceCard key={t.traceId} trace={t} />)
+ * }
+ *
+ * function TraceCard({ trace }: { trace: TraceState }) {
+ *   const steps = useTraceSteps(trace.traceId)
+ *   return steps.map(s => <StepRow key={s.spanId} step={s} />)
+ * }
+ * ```
+ */
+// Store
+export { TraceStore, getTraceStore } from "./store.js";
+// Hooks
+export { useActiveTraces, useTrace, useTraceSteps, useSpanTree } from "./hooks.js";
+export { LIVE_TRACE_PROVIDER, LIVE_TRACE_SCOPE_TYPE, LIVE_TRACE_SCOPE_ID } from "../src/types.js";
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,QAAQ;AACR,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGvD,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/react/store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Trace Store — Reactive store for live trace events.
+ *
+ * Reduces a stream of TraceEvents into a tree of SpanNodes per trace.
+ * Framework-agnostic core — uses useSyncExternalStore for React binding.
+ *
+ * No Effect dependency. Consumes plain TraceEvent JSON from any source.
+ */
+import type { TraceEvent, TraceScope } from "../src/types.js";
+export type TraceStatus = "running" | "completed" | "failed";
+export interface SpanEventEntry {
+    readonly name: string;
+    readonly level?: string;
+    readonly attributes?: Record<string, unknown>;
+    readonly timestamp: number;
+}
+export interface SpanNode {
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly name: string;
+    readonly status: "running" | "ok" | "error";
+    readonly attributes: Record<string, unknown>;
+    readonly events: SpanEventEntry[];
+    readonly children: SpanNode[];
+    readonly startedAt: number;
+    readonly durationMs?: number;
+    /** True if this span has ui.step attribute */
+    readonly isStep: boolean;
+}
+export interface TraceState {
+    readonly traceId: string;
+    readonly label: string;
+    readonly scope: TraceScope;
+    readonly status: TraceStatus;
+    readonly rootSpanId?: string;
+    readonly spans: Map<string, SpanNode>;
+    readonly startedAt: number;
+    readonly completedAt?: number;
+    readonly durationMs?: number;
+    readonly error?: string;
+    readonly updatedAt: number;
+}
+type Listener = () => void;
+export declare class TraceStore {
+    private traces;
+    private listeners;
+    private cleanupTimer;
+    constructor();
+    /** Subscribe to store changes (for useSyncExternalStore) */
+    subscribe: (listener: Listener) => (() => void);
+    /** Get snapshot (for useSyncExternalStore) */
+    getSnapshot: () => Map<string, TraceState>;
+    /** Dispatch a single trace event */
+    dispatch(event: TraceEvent): void;
+    /** Dispatch a batch of events */
+    dispatchBatch(events: TraceEvent[]): void;
+    /** Get a single trace */
+    getTrace(traceId: string): TraceState | undefined;
+    /** Get all traces as array, sorted by startedAt descending */
+    getAllTraces(): TraceState[];
+    /** Get step spans (ui.step=true) for a trace, in order */
+    getSteps(traceId: string): SpanNode[];
+    /** Build the span tree for a trace */
+    getSpanTree(traceId: string): SpanNode | undefined;
+    /** Destroy the store (stop cleanup timer) */
+    destroy(): void;
+    private handleTraceStart;
+    private handleSpanStart;
+    private handleSpanEnd;
+    private handleSpanEvent;
+    private handleTraceEnd;
+    private cleanup;
+    private notify;
+}
+export declare function getTraceStore(): TraceStore;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/react/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../react/store.ts"],"names":[],"mappings":"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"}