@swirls/looms 0.0.1

package/dist/core/store.js

@@ -0,0 +1,229 @@
+import { Context, Data, Effect, Layer, Option, Queue, Ref, Stream } from 'effect';
+import { withAssignedSeq } from './envelope.js';
+export class EventStoreError extends Data.TaggedError('EventStoreError') {
+    conflict;
+    cause;
+    constructor(text, cause, options) {
+        super({ message: text, cause, conflict: options?.conflict });
+        this.name = 'EventStoreError';
+        this.cause = cause;
+        this.conflict = options?.conflict;
+    }
+}
+export class EventStoreConflictError extends Data.TaggedError('EventStoreConflictError') {
+    conflict = true;
+    constructor(runId, expectedTail, actualTail, cause) {
+        super({
+            runId,
+            expectedTail,
+            actualTail,
+            message: `Conflict appending to ${runId}: expected tail ${expectedTail}, got ${actualTail}`,
+            cause,
+        });
+        this.name = 'EventStoreConflictError';
+    }
+}
+export class EventStoreTruncationError extends Data.TaggedError('EventStoreTruncationError') {
+    constructor(runId, readCount, tail) {
+        super({
+            runId,
+            readCount,
+            tail,
+            message: `store.read returned ${readCount} events but tail is ${tail}; refusing to dispatch from a truncated log`,
+        });
+        this.name = 'EventStoreTruncationError';
+    }
+}
+export class EventStoreTrimmedError extends Data.TaggedError('EventStoreTrimmedError') {
+    constructor(runId, head, requestedSeq) {
+        super({
+            runId,
+            head,
+            requestedSeq,
+            message: `store head is ${head} but requested seq ${requestedSeq} for run "${runId}"; history was trimmed and no covering snapshot is available`,
+        });
+        this.name = 'EventStoreTrimmedError';
+    }
+}
+export class EventStoreFencedError extends Data.TaggedError('EventStoreFencedError') {
+    constructor(runId, token) {
+        super({
+            runId,
+            token,
+            message: `Fencing token mismatch for run "${runId}"; token "${token}" is no longer current`,
+        });
+        this.name = 'EventStoreFencedError';
+    }
+}
+export function isEventStoreError(err) {
+    return (err instanceof EventStoreError ||
+        err instanceof EventStoreConflictError ||
+        err instanceof EventStoreTruncationError ||
+        err instanceof EventStoreTrimmedError ||
+        err instanceof EventStoreFencedError);
+}
+/**
+ * Pure Effect-native stream pagination primitive.
+ *
+ * Lazily pulls pages using `fetchPage` until:
+ * 1. `fetchPage` returns null or an empty record list,
+ * 2. `nextCursor` is null/undefined (signaling stream exhaustion / tail reached),
+ * 3. Or the caller's optional `limit` is satisfied (avoiding subsequent page fetches).
+ */
+export function paginatePages(options, fetchPage) {
+    const baseStream = Stream.paginate(options.initialCursor, (cursor) => Effect.gen(function* () {
+        const page = yield* fetchPage(cursor);
+        if (!page || page.records.length === 0 || page.nextCursor == null) {
+            return [page?.records ?? [], Option.none()];
+        }
+        return [page.records, Option.some(page.nextCursor)];
+    }));
+    return options.limit !== undefined ? baseStream.pipe(Stream.take(options.limit)) : baseStream;
+}
+/**
+ * Utility to read an EventStore as a Stream.Stream, using `store.readStream` if implemented
+ * or falling back to `Stream.fromIterableEffect(store.read(...))`.
+ */
+export function readEventStream(store, runId, options) {
+    if (store.readStream) {
+        return store.readStream(runId, options);
+    }
+    return Stream.fromIterableEffect(store.read(runId, options));
+}
+export class EventStoreTag extends Context.Service()('looms/EventStore') {
+}
+export const makeMemoryEventStore = Effect.gen(function* () {
+    const logs = yield* Ref.make(new Map());
+    const getOrCreate = (map, runId) => {
+        const existing = map.get(runId);
+        if (existing) {
+            return existing;
+        }
+        const created = { events: [], waiters: [], head: 1, tail: 0 };
+        map.set(runId, created);
+        return created;
+    };
+    const service = {
+        append: (runId, events, options) => Effect.gen(function* () {
+            const sequences = [];
+            yield* Ref.update(logs, (map) => {
+                const next = new Map(map);
+                const log = getOrCreate(next, runId);
+                if (options?.expectedTail !== undefined && log.tail !== options.expectedTail) {
+                    throw new EventStoreConflictError(runId, options.expectedTail, log.tail);
+                }
+                if (options?.fencingToken !== undefined && log.fenceToken !== options.fencingToken) {
+                    throw new EventStoreFencedError(runId, options.fencingToken);
+                }
+                let nextTail = log.tail;
+                let fenceToken = log.fenceToken;
+                if (options?.fence !== undefined) {
+                    nextTail += 1;
+                    fenceToken = options.fence === '' ? undefined : options.fence;
+                }
+                const appended = [];
+                for (const partial of events) {
+                    const seq = nextTail + appended.length + 1;
+                    const event = withAssignedSeq(partial, runId, seq);
+                    appended.push(event);
+                    sequences.push(seq);
+                }
+                nextTail += appended.length;
+                const updated = {
+                    events: [...log.events, ...appended],
+                    waiters: log.waiters,
+                    head: log.head,
+                    tail: nextTail,
+                    fenceToken,
+                };
+                next.set(runId, updated);
+                for (const event of appended) {
+                    for (const waiter of log.waiters) {
+                        waiter(event);
+                    }
+                }
+                return next;
+            }).pipe(Effect.catchDefect((cause) => Effect.fail(cause instanceof EventStoreConflictError ||
+                cause instanceof EventStoreFencedError ||
+                cause instanceof EventStoreError
+                ? cause
+                : new EventStoreError('append failed', cause))));
+            const tail = yield* service.tail(runId);
+            return { sequences, tail };
+        }),
+        read: (runId, options) => Effect.gen(function* () {
+            const map = yield* Ref.get(logs);
+            const log = map.get(runId);
+            if (!log) {
+                return [];
+            }
+            const fromSeq = Math.max(options?.fromSeq ?? 1, log.head);
+            const sliced = log.events.filter((e) => e.seq >= fromSeq);
+            return options?.limit !== undefined ? sliced.slice(0, options.limit) : sliced;
+        }),
+        readStream: (runId, options) => Stream.fromIterableEffect(service.read(runId, options)),
+        tail: (runId) => Effect.gen(function* () {
+            const map = yield* Ref.get(logs);
+            return map.get(runId)?.tail ?? 0;
+        }),
+        bounds: (runId) => Effect.gen(function* () {
+            const map = yield* Ref.get(logs);
+            const log = map.get(runId);
+            if (!log) {
+                return { head: 1, tail: 0 };
+            }
+            return { head: log.head, tail: log.tail };
+        }),
+        trim: (runId, beforeSeq) => Effect.gen(function* () {
+            yield* Ref.update(logs, (map) => {
+                const log = map.get(runId);
+                if (!log) {
+                    return map;
+                }
+                const next = new Map(map);
+                const retained = log.events.filter((e) => e.seq >= beforeSeq);
+                next.set(runId, {
+                    ...log,
+                    events: retained,
+                    head: Math.max(log.head, beforeSeq),
+                });
+                return next;
+            });
+        }),
+        subscribe: (runId, options) => Stream.callback((queue) => Effect.gen(function* () {
+            const fromSeq = options?.fromSeq ?? 1;
+            const map = yield* Ref.get(logs);
+            const log = getOrCreate(map, runId);
+            yield* Ref.update(logs, (m) => {
+                const n = new Map(m);
+                if (!n.has(runId)) {
+                    n.set(runId, log);
+                }
+                return n;
+            });
+            for (const event of log.events) {
+                if (event.seq >= fromSeq) {
+                    Queue.offerUnsafe(queue, event);
+                }
+            }
+            const waiter = (event) => {
+                if (event.seq >= fromSeq) {
+                    Queue.offerUnsafe(queue, event);
+                }
+            };
+            log.waiters.push(waiter);
+            yield* Effect.addFinalizer(() => Effect.sync(() => {
+                const idx = log.waiters.indexOf(waiter);
+                if (idx >= 0) {
+                    log.waiters.splice(idx, 1);
+                }
+            }));
+        })),
+        listRuns: () => Effect.gen(function* () {
+            const map = yield* Ref.get(logs);
+            return [...map.keys()];
+        }),
+    };
+    return service;
+});
+export const MemoryEventStoreLive = Layer.effect(EventStoreTag, makeMemoryEventStore);

package/dist/core/thread.d.ts

@@ -0,0 +1,41 @@
+import type { RuntimeEffect } from './effects';
+import type { EventEnvelope } from './envelope';
+import type { InferDefinedSchema, InferSchemaOutput, SchemaInput } from './schema';
+import type { ThreadStatus, JsonValue } from './types';
+export interface StartContext<TInput = JsonValue> {
+    readonly runId: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+    readonly definitionName: string;
+    readonly input: TInput;
+}
+export interface ThreadContext {
+    readonly runId: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+}
+export interface ThreadDefinition<S = any> {
+    readonly kind: string;
+    readonly shape?: unknown;
+    readonly input?: SchemaInput;
+    initialState(ctx: StartContext): S;
+    step(state: S, event: EventEnvelope, ctx: ThreadContext): S;
+    effects(state: S, ctx: ThreadContext): RuntimeEffect[];
+}
+export declare function defineThread<TShape, TInputSchema extends SchemaInput | undefined = undefined>(def: {
+    readonly kind: string;
+    readonly shape: TShape;
+    readonly input?: TInputSchema;
+    initialState(ctx: StartContext<InferDefinedSchema<TInputSchema>>): InferSchemaOutput<TShape>;
+    step(state: InferSchemaOutput<TShape>, event: EventEnvelope, ctx: ThreadContext): InferSchemaOutput<TShape>;
+    effects?(state: InferSchemaOutput<TShape>, ctx: ThreadContext): RuntimeEffect[];
+}): ThreadDefinition<InferSchemaOutput<TShape>>;
+export declare function defineThread<S = JsonValue, TInputSchema extends SchemaInput | undefined = undefined>(def: {
+    readonly kind: string;
+    readonly shape?: unknown;
+    readonly input?: TInputSchema;
+    initialState(ctx: StartContext<InferDefinedSchema<TInputSchema>>): S;
+    step(state: S, event: EventEnvelope, ctx: ThreadContext): S;
+    effects?(state: S, ctx: ThreadContext): RuntimeEffect[];
+}): ThreadDefinition<S>;
+export declare function isTerminalStatus(status: ThreadStatus): boolean;

package/dist/core/thread.js

@@ -0,0 +1,13 @@
+export function defineThread(def) {
+    return {
+        kind: def.kind,
+        shape: def.shape,
+        input: def.input,
+        initialState: (ctx) => def.initialState(ctx),
+        step: (state, event, ctx) => def.step(state, event, ctx),
+        effects: def.effects ? (state, ctx) => def.effects(state, ctx) : () => [],
+    };
+}
+export function isTerminalStatus(status) {
+    return status === 'completed' || status === 'failed' || status === 'cancelled';
+}

package/dist/core/types.d.ts

@@ -0,0 +1,27 @@
+/** JSON-compatible values used in event payloads and effect I/O. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonValue[] | readonly JsonValue[];
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/** Structs that JSON-serialize to event payloads. */
+export interface JsonPayload {
+    readonly [key: string]: JsonValue | JsonPayload | readonly (JsonValue | JsonPayload)[] | undefined;
+}
+/**
+ * Recursively remove keys with `undefined` values from an object,
+ * matching wire JSON serialization behavior where undefined properties drop.
+ */
+export declare function cleanUndefined<T>(value: T): T;
+/** Mark a JSON-serializable struct as a log payload, stripping undefined fields. */
+export declare function asJson<T>(payload: T): JsonValue;
+/** Recover a typed struct previously written as JSON. */
+export declare function fromJsonStruct<T>(value: JsonValue): T;
+export declare function isJsonObject(value: unknown): value is {
+    [key: string]: JsonValue;
+};
+export declare function isJsonString(value: unknown): value is string;
+export declare function isJsonNumber(value: unknown): value is number;
+export type ThreadStatus = 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+export type RunStatus = 'running' | 'completed' | 'failed' | 'cancelled';

package/dist/core/types.js

@@ -0,0 +1,42 @@
+import { Predicate } from 'effect';
+/**
+ * Recursively remove keys with `undefined` values from an object,
+ * matching wire JSON serialization behavior where undefined properties drop.
+ */
+export function cleanUndefined(value) {
+    if (Array.isArray(value)) {
+        // SAFETY: Mapping recursively over an array preserves array structure.
+        return value.map(cleanUndefined);
+    }
+    if (value === null || !Predicate.isObject(value)) {
+        return value;
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (v !== undefined) {
+            // SAFETY: cleanUndefined produces JSON-compatible values from JSON-like inputs.
+            result[k] = cleanUndefined(v);
+        }
+    }
+    // SAFETY: Rebuilding an object without undefined keys preserves its record shape.
+    return result;
+}
+/** Mark a JSON-serializable struct as a log payload, stripping undefined fields. */
+export function asJson(payload) {
+    // SAFETY: cleanUndefined ensures undefined keys drop as they would across the wire.
+    return cleanUndefined(payload);
+}
+/** Recover a typed struct previously written as JSON. */
+export function fromJsonStruct(value) {
+    // SAFETY: value is a JSON struct previously produced as T.
+    return value;
+}
+export function isJsonObject(value) {
+    return Predicate.isObject(value) && !Array.isArray(value);
+}
+export function isJsonString(value) {
+    return Predicate.isString(value);
+}
+export function isJsonNumber(value) {
+    return Predicate.isNumber(value) && Number.isFinite(value);
+}

package/dist/core/validate-event.d.ts

@@ -0,0 +1,19 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Effect } from 'effect';
+import type { EventCatalog } from './catalog';
+import type { EventInput } from './envelope';
+declare const InvalidEventError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidEventError";
+} & Readonly<A>;
+export declare class InvalidEventError extends InvalidEventError_base<{
+    readonly type: string;
+    readonly message: string;
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+}> {
+    readonly type: string;
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(type: string, text: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+export declare function validateEventInput(catalogs: readonly EventCatalog[], input: EventInput): Effect.Effect<EventInput, InvalidEventError>;
+export declare function validateEventsEffect(catalogs: readonly EventCatalog[], events: readonly EventInput[]): Effect.Effect<EventInput[], InvalidEventError>;
+export {};

package/dist/core/validate-event.js

@@ -0,0 +1,42 @@
+import { Data, Effect } from 'effect';
+import { validateInputEffect } from './schema.js';
+import { cleanUndefined } from './types.js';
+export class InvalidEventError extends Data.TaggedError('InvalidEventError') {
+    type;
+    issues;
+    constructor(type, text, issues = []) {
+        super({ type, message: text, issues });
+        this.name = 'InvalidEventError';
+        this.type = type;
+        this.issues = issues;
+    }
+}
+function findCatalogAndEntry(catalogs, type) {
+    for (const catalog of catalogs) {
+        const prefix = `${catalog.namespace}.`;
+        if (type.startsWith(prefix)) {
+            const key = type.slice(prefix.length);
+            const entries = catalog.entries;
+            const entry = entries[key];
+            if (entry !== undefined) {
+                return { catalog, key, entry };
+            }
+        }
+    }
+    return undefined;
+}
+export function validateEventInput(catalogs, input) {
+    const match = findCatalogAndEntry(catalogs, input.type);
+    if (!match) {
+        return Effect.succeed(input);
+    }
+    const cleanedPayload = cleanUndefined(input.payload);
+    // SAFETY: match.entry is a catalog entry (Schema, StandardSchema, or payload marker).
+    return validateInputEffect(match.entry, cleanedPayload).pipe(Effect.map((validatedPayload) => ({
+        ...input,
+        payload: validatedPayload,
+    })), Effect.mapError((err) => new InvalidEventError(input.type, `Invalid payload for event "${input.type}": ${err.message}`, err.issues)));
+}
+export function validateEventsEffect(catalogs, events) {
+    return Effect.forEach(events, (event) => validateEventInput(catalogs, event));
+}

package/dist/debugger/components/debugger-split.d.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import type { ThreadTree } from '@swirls/looms/core';
+import type { DebuggerEvent, EventStreamCatalog, ReplayLoader } from '../contracts';
+export declare function DebuggerSplit<TEvent extends DebuggerEvent>({ runId, runStatus, tree, events, eventCounts, startedAt, selectedThread, onSelectThread, selectedSeq, onSelectSeq, catalog, loadReplayStep, renderInspector, orientation, showTreeHeading, className, treeClassName, streamClassName, }: {
+    runId: string;
+    runStatus: string;
+    tree: ThreadTree;
+    events: readonly TEvent[];
+    eventCounts: Map<string, number>;
+    startedAt?: number;
+    selectedThread?: string;
+    onSelectThread: (threadId: string | undefined) => void;
+    selectedSeq?: number;
+    onSelectSeq: (seq: number | undefined) => void;
+    catalog?: EventStreamCatalog<TEvent>;
+    loadReplayStep?: ReplayLoader;
+    renderInspector?: (selected: TEvent) => ReactNode;
+    orientation?: 'horizontal' | 'vertical';
+    showTreeHeading?: boolean;
+    className?: string;
+    treeClassName?: string;
+    streamClassName?: string;
+}): import("react").JSX.Element;

package/dist/debugger/components/debugger-split.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../lib/cn.js';
+import { EventStream } from './event-stream.js';
+import { RunTree } from './run-tree.js';
+function findThreadName(node, threadId) {
+    if (!node || !threadId) {
+        return undefined;
+    }
+    if (node.threadId === threadId) {
+        return node.definitionName;
+    }
+    for (const child of node.children) {
+        const name = findThreadName(child, threadId);
+        if (name) {
+            return name;
+        }
+    }
+    return undefined;
+}
+export function DebuggerSplit({ runId, runStatus, tree, events, eventCounts, startedAt, selectedThread, onSelectThread, selectedSeq, onSelectSeq, catalog, loadReplayStep, renderInspector, orientation = 'horizontal', showTreeHeading = true, className, treeClassName, streamClassName, }) {
+    const vertical = orientation === 'vertical';
+    return (_jsxs("div", { className: cn('grid h-full min-h-0', vertical
+            ? 'grid-rows-[minmax(0,38%)_minmax(0,1fr)]'
+            : 'grid-cols-1 min-[36rem]:grid-cols-[11rem_minmax(0,1fr)]', className), children: [_jsx("section", { "aria-label": "Run tree", className: cn('border-border min-h-0 overflow-auto border-b py-2', !vertical && 'min-[36rem]:border-r min-[36rem]:border-b-0', treeClassName), children: _jsx(RunTree, { showHeading: showTreeHeading, runId: runId, runStatus: runStatus, tree: tree, eventCounts: eventCounts, totalEventCount: events.length, selectedThread: selectedThread, onSelectThread: onSelectThread }) }), _jsx("section", { className: cn('min-h-0 overflow-hidden', streamClassName), children: _jsx(EventStream, { events: events, startedAt: startedAt, threadId: selectedThread, threadLabel: findThreadName(tree.root, selectedThread), selectedSeq: selectedSeq, onSelectSeq: onSelectSeq, catalog: catalog, loadReplayStep: loadReplayStep, renderInspector: renderInspector }) })] }));
+}

package/dist/debugger/components/event-inspector.d.ts

@@ -0,0 +1,5 @@
+import type { DebuggerEvent, ReplayLoader } from '../contracts';
+export declare function EventInspector({ event, loadReplayStep, }: {
+    event: DebuggerEvent;
+    loadReplayStep?: ReplayLoader;
+}): import("react").JSX.Element;

package/dist/debugger/components/event-inspector.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { asJson } from '@swirls/looms/core';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../ui/tabs.js';
+import { JsonView } from './json-view.js';
+export function EventInspector({ event, loadReplayStep, }) {
+    const [step, setStep] = useState(null);
+    const canReplay = loadReplayStep !== undefined;
+    useEffect(() => {
+        if (!loadReplayStep) {
+            setStep(null);
+            return () => undefined;
+        }
+        let cancelled = false;
+        void loadReplayStep({ runId: event.runId, seq: event.seq }).then((next) => {
+            if (!cancelled) {
+                setStep(next);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [event.runId, event.seq, loadReplayStep]);
+    return (_jsxs("div", { className: "border-border flex max-h-[45%] min-h-0 shrink-0 flex-col border-t", children: [_jsxs("div", { className: "text-muted-foreground flex items-center gap-2 px-3 py-1.5 text-[11px]", children: [_jsx("span", { className: "font-mono", children: event.seq }), _jsx("span", { className: "text-foreground truncate font-mono", children: event.type })] }), _jsxs(Tabs, { defaultValue: "payload", className: "min-h-0 flex-1 px-3 pb-2", children: [_jsxs(TabsList, { children: [_jsx(TabsTrigger, { value: "payload", children: "Payload" }), _jsx(TabsTrigger, { value: "envelope", children: "Envelope" }), canReplay ? _jsx(TabsTrigger, { value: "before", children: "Before" }) : null, canReplay ? _jsx(TabsTrigger, { value: "after", children: "After" }) : null, canReplay ? _jsx(TabsTrigger, { value: "effects", children: "Effects" }) : null] }), _jsx(TabsContent, { value: "payload", className: "overflow-auto", children: _jsx(JsonView, { value: event.payload }) }), _jsx(TabsContent, { value: "envelope", className: "overflow-auto", children: _jsx(JsonView, { value: asJson({
+                                id: event.id,
+                                runId: event.runId,
+                                seq: event.seq,
+                                ts: event.ts,
+                                type: event.type,
+                                threadId: event.threadId,
+                                parentThreadId: event.parentThreadId ?? null,
+                                causationId: event.causationId ?? null,
+                                correlationId: event.correlationId ?? null,
+                                effectId: event.effectId ?? null,
+                                origin: event.origin,
+                                ephemeral: event.ephemeral ?? false,
+                            }) }) }), canReplay ? (_jsx(TabsContent, { value: "before", className: "overflow-auto", children: step ? (_jsx(JsonView, { value: asJson(step.before) })) : (_jsx("p", { className: "text-muted-foreground text-xs", children: "Loading\u2026" })) })) : null, canReplay ? (_jsx(TabsContent, { value: "after", className: "overflow-auto", children: step ? (_jsx(JsonView, { value: asJson(step.after) })) : (_jsx("p", { className: "text-muted-foreground text-xs", children: "Loading\u2026" })) })) : null, canReplay ? (_jsx(TabsContent, { value: "effects", className: "overflow-auto", children: step ? (_jsx(JsonView, { value: asJson(step.effects) })) : (_jsx("p", { className: "text-muted-foreground text-xs", children: "Loading\u2026" })) })) : null] })] }));
+}

package/dist/debugger/components/event-stream.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import type { DebuggerEvent, EventStreamCatalog, ReplayLoader } from '../contracts';
+export declare function EventStream<TEvent extends DebuggerEvent>({ events, startedAt, threadId, threadLabel, selectedSeq, onSelectSeq, catalog, loadReplayStep, renderInspector, }: {
+    events: readonly TEvent[];
+    startedAt?: number;
+    threadId?: string;
+    threadLabel?: string;
+    selectedSeq?: number;
+    onSelectSeq: (seq: number | undefined) => void;
+    catalog?: EventStreamCatalog<TEvent>;
+    loadReplayStep?: ReplayLoader;
+    renderInspector?: (selected: TEvent) => ReactNode;
+}): import("react").JSX.Element;

package/dist/debugger/components/event-stream.js

@@ -0,0 +1,119 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { Check, Search, SlidersHorizontal } from 'lucide-react';
+import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { defaultEventCatalog } from '../events/catalog.js';
+import { cn, shortId } from '../lib/cn.js';
+import { getEventMeta } from '../lib/event-meta.js';
+import { useVisibleEvents } from '../lib/visible-events.js';
+import { Checkbox } from '../ui/checkbox.js';
+import { Input } from '../ui/input.js';
+import { ScrollArea } from '../ui/scroll-area.js';
+import { EventInspector } from './event-inspector.js';
+const ROW_ESTIMATE = 28;
+const FOLLOW_THRESHOLD = 24;
+export function EventStream({ events, startedAt, threadId, threadLabel, selectedSeq, onSelectSeq, catalog, loadReplayStep, renderInspector, }) {
+    const eventCatalog = catalog ?? defaultEventCatalog;
+    const [query, setQuery] = useState('');
+    const [follow, setFollow] = useState(true);
+    const [families, setFamilies] = useState(() => new Set(eventCatalog.families));
+    const parentRef = useRef(null);
+    const followLock = useRef(false);
+    const selected = useMemo(() => {
+        if (selectedSeq === undefined) {
+            return undefined;
+        }
+        const idx = selectedSeq - 1;
+        if (idx >= 0 && idx < events.length && events[idx]?.seq === selectedSeq) {
+            return events[idx];
+        }
+        return events.find((event) => event.seq === selectedSeq);
+    }, [events, selectedSeq]);
+    const visible = useVisibleEvents({
+        events,
+        query,
+        families,
+        threadId,
+        catalog: eventCatalog,
+    });
+    const virtualizer = useVirtualizer({
+        count: visible.length,
+        getScrollElement: () => parentRef.current,
+        estimateSize: () => ROW_ESTIMATE,
+        overscan: 16,
+        paddingStart: 4,
+        paddingEnd: 4,
+        getItemKey: (index) => visible[index]?.id ?? index,
+        // Avoid flushSync during ref measurement / follow-scroll under high event rates.
+        useFlushSync: false,
+    });
+    useEffect(() => {
+        if (!follow || visible.length === 0) {
+            return () => undefined;
+        }
+        followLock.current = true;
+        let timer;
+        const rafId = requestAnimationFrame(() => {
+            virtualizer.scrollToIndex(visible.length - 1, { align: 'end' });
+            timer = setTimeout(() => {
+                followLock.current = false;
+            }, 50);
+        });
+        return () => {
+            cancelAnimationFrame(rafId);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            followLock.current = false;
+        };
+    }, [follow, visible.length, virtualizer]);
+    const onScroll = useCallback(() => {
+        if (followLock.current) {
+            return;
+        }
+        const el = parentRef.current;
+        if (!el) {
+            return;
+        }
+        const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < FOLLOW_THRESHOLD;
+        if (follow && !atBottom) {
+            setFollow(false);
+        }
+        else if (!follow && atBottom) {
+            setFollow(true);
+        }
+    }, [follow]);
+    const toggleFamily = useCallback((family) => {
+        setFamilies((prev) => {
+            const next = new Set(prev);
+            if (next.has(family)) {
+                next.delete(family);
+            }
+            else {
+                next.add(family);
+            }
+            return next;
+        });
+    }, []);
+    const hiddenFamilyCount = eventCatalog.families.length - families.size;
+    return (_jsxs("div", { className: "debugger-event-stream flex h-full min-h-0 flex-col", children: [_jsxs("div", { className: "border-border flex min-h-10 items-center gap-1.5 border-b px-2 py-1.5", children: [_jsxs("div", { className: "relative min-w-0 flex-1", children: [_jsx(Search, { "aria-hidden": true, className: "text-muted-foreground pointer-events-none absolute top-1/2 left-2 size-3 -translate-y-1/2" }), _jsx(Input, { value: query, onChange: (event) => setQuery(event.target.value), placeholder: "Search events", "aria-label": "Search events", className: "h-7 w-full pl-7 text-xs" })] }), _jsxs(DropdownMenuPrimitive.Root, { children: [_jsx(DropdownMenuPrimitive.Trigger, { asChild: true, children: _jsxs("button", { type: "button", className: "border-input text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:ring-ring/50 relative inline-flex size-7 shrink-0 items-center justify-center rounded-md border outline-none focus-visible:ring-[3px]", "aria-label": "Filter event families", children: [_jsx(SlidersHorizontal, { className: "size-3.5" }), hiddenFamilyCount > 0 ? (_jsx("span", { className: "bg-foreground text-background absolute -top-1 -right-1 flex size-3.5 items-center justify-center rounded-full font-mono text-[8px]", children: hiddenFamilyCount })) : null] }) }), _jsx(DropdownMenuPrimitive.Portal, { children: _jsxs(DropdownMenuPrimitive.Content, { align: "end", sideOffset: 5, className: "bg-background text-foreground border-border z-50 min-w-36 rounded-md border p-1 shadow-lg", children: [_jsx(DropdownMenuPrimitive.Label, { className: "text-muted-foreground px-2 py-1 text-[10px] font-medium tracking-wide uppercase", children: "Event families" }), eventCatalog.families.map((family) => (_jsxs(DropdownMenuPrimitive.CheckboxItem, { checked: families.has(family), onCheckedChange: () => toggleFamily(family), onSelect: (event) => event.preventDefault(), className: "focus:bg-accent relative flex cursor-default items-center rounded-sm py-1.5 pr-2 pl-7 font-mono text-xs outline-none select-none", children: [_jsx("span", { className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(Check, { className: "size-3" }) }) }), family] }, family)))] }) })] }), _jsxs("label", { className: "text-muted-foreground hover:text-foreground flex shrink-0 cursor-pointer items-center gap-1.5 px-1 text-[10px]", children: [_jsx(Checkbox, { checked: follow, onCheckedChange: (checked) => setFollow(checked === true), "aria-label": "Follow newest events" }), _jsx("span", { className: "debugger-follow-label", children: "Follow" })] })] }), threadId ? (_jsxs("div", { className: "border-border text-muted-foreground flex items-center gap-1.5 border-b px-2 py-1 font-mono text-[10px]", children: [_jsx("span", { className: "text-[9px] tracking-wide uppercase", children: "Thread" }), _jsx("span", { className: "text-foreground truncate", title: threadId, children: threadLabel ?? shortId(threadId) })] })) : null, _jsx(ScrollArea, { viewportRef: parentRef, className: "min-h-32 flex-1", onViewportScroll: onScroll, children: _jsx("div", { className: "relative w-full px-1", style: { height: virtualizer.getTotalSize() }, children: virtualizer.getVirtualItems().map((row) => {
+                        const event = visible[row.index];
+                        if (!event) {
+                            return null;
+                        }
+                        return (_jsx("div", { "data-index": row.index, ref: virtualizer.measureElement, className: "absolute top-0 left-0 w-full", style: { transform: `translateY(${row.start}px)` }, children: _jsx(EventRow, { event: event, catalog: eventCatalog, startedAt: startedAt, selected: selectedSeq === event.seq, onSelectSeq: onSelectSeq }) }, event.id));
+                    }) }) }), selected
+                ? (renderInspector?.(selected) ?? (_jsx(EventInspector, { event: selected, loadReplayStep: loadReplayStep })))
+                : null] }));
+}
+// SAFETY: memoized EventRow preserves generic EventRowProps contract.
+const EventRow = memo(function EventRow({ event, catalog, startedAt, selected, onSelectSeq, }) {
+    const meta = getEventMeta(event, catalog);
+    const offset = startedAt !== undefined ? Math.max(0, event.ts - startedAt) : undefined;
+    const handleClick = useCallback(() => {
+        onSelectSeq(selected ? undefined : event.seq);
+    }, [onSelectSeq, selected, event.seq]);
+    return (_jsxs("button", { type: "button", onClick: handleClick, title: [meta.summary.title, meta.summary.detail].filter(Boolean).join(' — '), className: cn('flex w-full items-start gap-1.5 rounded-sm px-1.5 py-1 text-left font-mono text-[11px]', selected ? 'bg-accent' : 'hover:bg-accent/40', event.ephemeral && 'opacity-50'), children: [_jsx("span", { className: cn('mt-1.5 size-1.5 shrink-0 rounded-full', catalog.familyClass(meta.family)) }), _jsx("span", { className: "text-muted-foreground w-6 shrink-0 text-right tabular-nums", children: event.seq }), _jsx("span", { className: "debugger-event-offset text-muted-foreground w-10 shrink-0 text-right tabular-nums", children: offset !== undefined ? `+${offset}` : '' }), _jsxs("span", { className: "min-w-0 flex-1 truncate whitespace-nowrap", children: [_jsx("span", { className: "text-foreground", children: meta.summary.title }), meta.summary.detail ? (_jsx("span", { className: "text-muted-foreground ml-1", children: meta.summary.detail })) : null] }), event.causationId ? (_jsxs("span", { className: "debugger-event-causation text-muted-foreground shrink-0", children: ["\u2190 ", shortId(event.causationId)] })) : null, event.threadId ? (_jsx("span", { className: "debugger-event-thread text-muted-foreground shrink-0", children: shortId(event.threadId) })) : null] }));
+    // SAFETY: memoized EventRow preserves generic EventRowProps contract.
+});