causal-inspector 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,77 @@
+import type { BaseEvent } from "./machine";
+import type { InspectorEvent, CorrelationSummary, ReactorDependency, AggregateLifecycleEntry, FilterState, FlowSelection, ReactorDescription, ReactorDescriptionSnapshot, AggregateTimelineEntry, ReactorLog, ReactorOutcome, PaneLayout } from "./types";
+type EventsReceived = BaseEvent<"events/received", InspectorEvent[]>;
+type SubscriptionConnected = BaseEvent<"events/subscription_connected">;
+type SubscriptionError = BaseEvent<"events/subscription_error", {
+    message: string;
+}>;
+type PageLoaded = BaseEvent<"events/page_loaded", {
+    events: InspectorEvent[];
+    hasMore: boolean;
+}>;
+type CausalTreeLoaded = BaseEvent<"events/causal_tree_loaded", {
+    events: InspectorEvent[];
+    rootSeq: number;
+}>;
+type FlowLoaded = BaseEvent<"events/flow_loaded", InspectorEvent[]>;
+type LogsLoaded = BaseEvent<"events/logs_loaded", ReactorLog[]>;
+type DescriptionsLoaded = BaseEvent<"events/descriptions_loaded", {
+    correlationId: string;
+    descriptions: ReactorDescription[];
+}>;
+type DescriptionSnapshotsLoaded = BaseEvent<"events/description_snapshots_loaded", {
+    correlationId: string;
+    snapshots: ReactorDescriptionSnapshot[];
+}>;
+type AggregateTimelineLoaded = BaseEvent<"events/aggregate_timeline_loaded", {
+    correlationId: string;
+    entries: AggregateTimelineEntry[];
+}>;
+type OutcomesLoaded = BaseEvent<"events/outcomes_loaded", {
+    correlationId: string;
+    outcomes: ReactorOutcome[];
+}>;
+type CorrelationsLoaded = BaseEvent<"events/correlations_loaded", CorrelationSummary[]>;
+type ReactorDependenciesLoaded = BaseEvent<"events/reactor_dependencies_loaded", ReactorDependency[]>;
+type AggregateKeysLoaded = BaseEvent<"events/aggregate_keys_loaded", string[]>;
+type AggregateLifecycleLoaded = BaseEvent<"events/aggregate_lifecycle_loaded", {
+    key: string;
+    entries: AggregateLifecycleEntry[];
+}>;
+type EventSelected = BaseEvent<"ui/event_selected", {
+    seq: number;
+}>;
+type EventDeselected = BaseEvent<"ui/event_deselected">;
+type FlowOpened = BaseEvent<"ui/flow_opened", {
+    correlationId: string;
+}>;
+type FlowClosed = BaseEvent<"ui/flow_closed">;
+type FlowNodeSelected = BaseEvent<"ui/flow_node_selected", FlowSelection>;
+type FilterChanged = BaseEvent<"ui/filter_changed", Partial<FilterState>>;
+type LoadMoreRequested = BaseEvent<"ui/load_more_requested">;
+type LayoutChanged = BaseEvent<"ui/layout_changed", PaneLayout>;
+type ScrubberStartChanged = BaseEvent<"ui/scrubber_start_changed", {
+    start: number | null;
+}>;
+type ScrubberEndChanged = BaseEvent<"ui/scrubber_end_changed", {
+    end: number | null;
+}>;
+type ScrubberPlayToggled = BaseEvent<"ui/scrubber_play_toggled">;
+type ScrubberSpeedChanged = BaseEvent<"ui/scrubber_speed_changed", {
+    speed: number;
+}>;
+type CorrelationsRequested = BaseEvent<"ui/correlations_requested", {
+    search?: string;
+}>;
+type HandlerSelected = BaseEvent<"ui/handler_selected", {
+    reactorId: string;
+}>;
+type AggregateLifecycleRequested = BaseEvent<"ui/aggregate_lifecycle_requested", {
+    aggregateKey: string;
+}>;
+type LocationChanged = BaseEvent<"location/changed", {
+    correlationId: string | null;
+    handler: string | null;
+}>;
+export type InspectorMachineEvent = EventsReceived | SubscriptionConnected | SubscriptionError | PageLoaded | CausalTreeLoaded | FlowLoaded | LogsLoaded | DescriptionsLoaded | DescriptionSnapshotsLoaded | AggregateTimelineLoaded | OutcomesLoaded | CorrelationsLoaded | EventSelected | EventDeselected | FlowOpened | FlowClosed | FlowNodeSelected | FilterChanged | LoadMoreRequested | LayoutChanged | ScrubberStartChanged | ScrubberEndChanged | ScrubberPlayToggled | ScrubberSpeedChanged | CorrelationsRequested | ReactorDependenciesLoaded | AggregateKeysLoaded | HandlerSelected | LocationChanged | AggregateLifecycleLoaded | AggregateLifecycleRequested;
+export {};

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { Machine, Store, combineEngineCreators, MachineContext, useSelector, useDispatch, useInlineMachine, } from "./machine";
+export type { Reducer, Engine, EngineCreator, BaseEvent, Dispatch, } from "./machine";
+export { CausalInspectorProvider } from "./context";
+export { reducer } from "./reducer";
+export { initialState } from "./state";
+export type { InspectorState } from "./state";
+export type { InspectorMachineEvent } from "./events";
+export type { InspectorEvent, InspectorEventsPage, InspectorCausalTree, InspectorCausalFlow, CorrelationSummary, ReactorDependency, AggregateLifecycleEntry, Block, ReactorLog, ReactorDescription, ReactorDescriptionSnapshot, AggregateStateEntry, AggregateTimelineEntry, ReactorOutcome, FilterState, LogsFilter, FlowSelection, PaneLayout, } from "./types";
+export { createInspectorEngine, createSubscriptionEngine, createQueryEngine, createStorageEngine, } from "./engines";
+export type { InspectorTransport, SubscriptionTransport, QueryTransport, StorageTransport, } from "./engines";
+export { EVENTS_SUBSCRIPTION, INSPECTOR_EVENTS, INSPECTOR_CAUSAL_TREE, INSPECTOR_CAUSAL_FLOW, INSPECTOR_CORRELATIONS, INSPECTOR_REACTOR_LOGS, INSPECTOR_REACTOR_LOGS_BY_CORRELATION, INSPECTOR_REACTOR_DESCRIPTIONS, INSPECTOR_REACTOR_DESCRIPTION_SNAPSHOTS, INSPECTOR_AGGREGATE_TIMELINE, INSPECTOR_REACTOR_OUTCOMES, INSPECTOR_REACTOR_DEPENDENCIES, INSPECTOR_AGGREGATE_KEYS, INSPECTOR_AGGREGATE_LIFECYCLE, } from "./queries";
+export { eventHue, eventBg, eventBorder, eventTextColor, LOG_LEVEL_COLORS, } from "./theme";
+export { formatTs, compactPayload, copyToClipboard } from "./utils";
+export { CausalInspector } from "./CausalInspector";
+export type { CausalInspectorProps } from "./CausalInspector";
+export { FilterBar } from "./components/FilterBar";
+export { CopyablePayload } from "./components/CopyablePayload";
+export { JsonSyntax } from "./components/JsonSyntax";
+export { GlobalScrubber } from "./components/GlobalScrubber";
+export { TimelinePane } from "./panes/TimelinePane";
+export type { TimelinePaneProps } from "./panes/TimelinePane";
+export { CausalTreePane } from "./panes/CausalTreePane";
+export type { CausalTreePaneProps } from "./panes/CausalTreePane";
+export { LogsPane } from "./panes/LogsPane";
+export type { LogsPaneProps } from "./panes/LogsPane";
+export { CausalFlowPane } from "./panes/CausalFlowPane";
+export type { CausalFlowPaneProps } from "./panes/CausalFlowPane";
+export { AggregateTimelinePane } from "./panes/AggregateTimelinePane";
+export { WaterfallPane } from "./panes/WaterfallPane";
+export { CorrelationExplorerPane } from "./panes/CorrelationExplorerPane";

package/dist/index.js

@@ -0,0 +1,29 @@
+// ── Machine infra (generic, reusable) ──
+export { Machine, Store, combineEngineCreators, MachineContext, useSelector, useDispatch, useInlineMachine, } from "./machine";
+// ── Causal Inspector domain ──
+export { CausalInspectorProvider } from "./context";
+export { reducer } from "./reducer";
+export { initialState } from "./state";
+// ── Engines ──
+export { createInspectorEngine, createSubscriptionEngine, createQueryEngine, createStorageEngine, } from "./engines";
+// ── Queries ──
+export { EVENTS_SUBSCRIPTION, INSPECTOR_EVENTS, INSPECTOR_CAUSAL_TREE, INSPECTOR_CAUSAL_FLOW, INSPECTOR_CORRELATIONS, INSPECTOR_REACTOR_LOGS, INSPECTOR_REACTOR_LOGS_BY_CORRELATION, INSPECTOR_REACTOR_DESCRIPTIONS, INSPECTOR_REACTOR_DESCRIPTION_SNAPSHOTS, INSPECTOR_AGGREGATE_TIMELINE, INSPECTOR_REACTOR_OUTCOMES, INSPECTOR_REACTOR_DEPENDENCIES, INSPECTOR_AGGREGATE_KEYS, INSPECTOR_AGGREGATE_LIFECYCLE, } from "./queries";
+// ── Theme ──
+export { eventHue, eventBg, eventBorder, eventTextColor, LOG_LEVEL_COLORS, } from "./theme";
+// ── Utilities ──
+export { formatTs, compactPayload, copyToClipboard } from "./utils";
+// ── Drop-in component ──
+export { CausalInspector } from "./CausalInspector";
+// ── Components ──
+export { FilterBar } from "./components/FilterBar";
+export { CopyablePayload } from "./components/CopyablePayload";
+export { JsonSyntax } from "./components/JsonSyntax";
+export { GlobalScrubber } from "./components/GlobalScrubber";
+// ── Panes ──
+export { TimelinePane } from "./panes/TimelinePane";
+export { CausalTreePane } from "./panes/CausalTreePane";
+export { LogsPane } from "./panes/LogsPane";
+export { CausalFlowPane } from "./panes/CausalFlowPane";
+export { AggregateTimelinePane } from "./panes/AggregateTimelinePane";
+export { WaterfallPane } from "./panes/WaterfallPane";
+export { CorrelationExplorerPane } from "./panes/CorrelationExplorerPane";

package/dist/machine/core.d.ts

@@ -0,0 +1,22 @@
+import { EngineCreator } from "./engine";
+import { Reducer } from "./store";
+/**
+ * Machine = Store (pure state) + Engine (side effects).
+ *
+ * Dispatch flow:
+ *   UI dispatches event
+ *   → Store reduces (sync, via Immer)
+ *   → Engine handles event with (curr, prev) state
+ *   → Engine may dispatch new events (async reactions)
+ */
+export declare class Machine<TState, TEvent extends {
+    type: string;
+}> {
+    private _engine;
+    private _store;
+    constructor(reducer: Reducer<TState, TEvent>, createEngine: EngineCreator<TState, TEvent>, initialState: TState);
+    getState: () => TState;
+    dispatch: (event: TEvent) => void;
+    onStateChange(listener: (newState: TState, oldState: TState) => void): () => void;
+    dispose(): void;
+}

package/dist/machine/core.js

@@ -0,0 +1,34 @@
+import { Store } from "./store";
+/**
+ * Machine = Store (pure state) + Engine (side effects).
+ *
+ * Dispatch flow:
+ *   UI dispatches event
+ *   → Store reduces (sync, via Immer)
+ *   → Engine handles event with (curr, prev) state
+ *   → Engine may dispatch new events (async reactions)
+ */
+export class Machine {
+    _engine;
+    _store;
+    constructor(reducer, createEngine, initialState) {
+        this._store = new Store(reducer, initialState);
+        this._engine = createEngine(this.dispatch, this.getState);
+    }
+    getState = () => {
+        return this._store.getState();
+    };
+    dispatch = (event) => {
+        const prevState = this._store.getState();
+        this._store.dispatch(event);
+        const currState = this._store.getState();
+        this._engine.handleEvent?.(event, currState, prevState);
+    };
+    onStateChange(listener) {
+        return this._store.onStateChange(listener);
+    }
+    dispose() {
+        this._engine.dispose();
+        this._store.dispose();
+    }
+}

package/dist/machine/engine.d.ts

@@ -0,0 +1,17 @@
+import { Dispatch } from "./events";
+export type Engine<TState, TEvent extends {
+    type: string;
+}> = {
+    handleEvent?: (event: TEvent, currState: TState, prevState: TState) => void;
+    dispose: () => void;
+};
+export type EngineCreator<TState, TEvent extends {
+    type: string;
+}> = (dispatch: Dispatch<TEvent>, getState: () => TState) => Engine<TState, TEvent>;
+/**
+ * Compose multiple engine creators into one.
+ * Each engine receives every event — fan-out pattern.
+ */
+export declare const combineEngineCreators: <TState, TEvent extends {
+    type: string;
+}>(...creators: EngineCreator<TState, TEvent>[]) => EngineCreator<TState, TEvent>;

package/dist/machine/engine.js

@@ -0,0 +1,21 @@
+/**
+ * Compose multiple engine creators into one.
+ * Each engine receives every event — fan-out pattern.
+ */
+export const combineEngineCreators = (...creators) => {
+    return (dispatch, getState) => {
+        const engines = creators.map((create) => create(dispatch, getState));
+        return {
+            handleEvent: (event, currState, prevState) => {
+                for (const engine of engines) {
+                    engine.handleEvent?.(event, currState, prevState);
+                }
+            },
+            dispose: () => {
+                for (const engine of engines) {
+                    engine.dispose();
+                }
+            },
+        };
+    };
+};

package/dist/machine/events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base event type — discriminated union foundation.
+ *
+ * When no payload type is given, the event has no `payload` property.
+ * When a payload type IS given, `payload` is required.
+ * This prevents accidentally omitting required payloads at dispatch sites.
+ */
+export type BaseEvent<TType extends string, TPayload = void> = [
+    TPayload
+] extends [void] ? {
+    type: TType;
+} : {
+    type: TType;
+    payload: TPayload;
+};
+export type Dispatch<TEvent extends {
+    type: string;
+}> = (event: TEvent) => void;

package/dist/machine/events.js

@@ -0,0 +1 @@
+export {};

package/dist/machine/hooks.d.ts

@@ -0,0 +1,23 @@
+import { Machine } from "./core";
+import { Dispatch } from "./events";
+import { EngineCreator } from "./engine";
+import { Reducer } from "./store";
+export declare const MachineContext: import("react").Context<Machine<any, any> | null>;
+/**
+ * Select a slice of state. Only re-renders when the selected value changes
+ * (reference equality).
+ */
+export declare const useSelector: <TState, TSelected>(selector: (state: TState) => TSelected) => TSelected;
+/**
+ * Get the dispatch function. Stable reference — never causes re-renders.
+ */
+export declare const useDispatch: <TEvent extends {
+    type: string;
+}>() => Dispatch<TEvent>;
+/**
+ * Create and manage a machine inline within a component.
+ * Useful for self-contained widgets.
+ */
+export declare const useInlineMachine: <TState, TEvent extends {
+    type: string;
+}>(reducer: Reducer<TState, TEvent>, createEngine: EngineCreator<TState, TEvent>, initialState: TState) => [TState, Dispatch<TEvent>];

package/dist/machine/hooks.js

@@ -0,0 +1,52 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Machine } from "./core";
+export const MachineContext = createContext(null);
+const useMachine = () => {
+    const machine = useContext(MachineContext);
+    if (!machine) {
+        throw new Error("useMachine must be used within a MachineContext.Provider");
+    }
+    return machine;
+};
+/**
+ * Select a slice of state. Only re-renders when the selected value changes
+ * (reference equality).
+ */
+export const useSelector = (selector) => {
+    const machine = useMachine();
+    const [value, setValue] = useState(() => selector(machine.getState()));
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    useEffect(() => {
+        // Sync in case state changed between render and effect
+        setValue(selectorRef.current(machine.getState()));
+        return machine.onStateChange((newState) => {
+            setValue(selectorRef.current(newState));
+        });
+    }, [machine]);
+    return value;
+};
+/**
+ * Get the dispatch function. Stable reference — never causes re-renders.
+ */
+export const useDispatch = () => {
+    return useMachine().dispatch;
+};
+/**
+ * Create and manage a machine inline within a component.
+ * Useful for self-contained widgets.
+ */
+export const useInlineMachine = (reducer, createEngine, initialState) => {
+    const machine = useMemo(() => new Machine(reducer, createEngine, initialState), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const [state, setState] = useState(machine.getState());
+    useEffect(() => {
+        const unsub = machine.onStateChange((newState) => setState(newState));
+        return () => {
+            unsub();
+            machine.dispose();
+        };
+    }, [machine]);
+    return [state, machine.dispatch];
+};

package/dist/machine/index.d.ts

@@ -0,0 +1,5 @@
+export { Machine } from "./core";
+export { Store, type Reducer } from "./store";
+export { type Engine, type EngineCreator, combineEngineCreators } from "./engine";
+export { type BaseEvent, type Dispatch } from "./events";
+export { MachineContext, useSelector, useDispatch, useInlineMachine } from "./hooks";

package/dist/machine/index.js

@@ -0,0 +1,4 @@
+export { Machine } from "./core";
+export { Store } from "./store";
+export { combineEngineCreators } from "./engine";
+export { MachineContext, useSelector, useDispatch, useInlineMachine } from "./hooks";

package/dist/machine/store.d.ts

@@ -0,0 +1,27 @@
+import { type Draft } from "immer";
+type ChangeListener<TState> = (newState: TState, oldState: TState) => void;
+export type Reducer<TState, TEvent extends {
+    type: string;
+}> = (draft: Draft<TState>, event: TEvent) => void;
+/**
+ * Immutable state store powered by Immer.
+ *
+ * Reducer receives a mutable draft (Immer proxy) — mutations are
+ * automatically converted to structural sharing under the hood.
+ */
+export declare class Store<TState, TEvent extends {
+    type: string;
+}> {
+    private _reduce;
+    private _state;
+    private _listeners;
+    constructor(_reduce: Reducer<TState, TEvent>, initialState: TState);
+    getState(): TState;
+    dispatch(event: TEvent): void;
+    /**
+     * Subscribe to state changes. Returns an unsubscribe function.
+     */
+    onStateChange(listener: ChangeListener<TState>): () => void;
+    dispose(): void;
+}
+export {};

package/dist/machine/store.js

@@ -0,0 +1,42 @@
+import { produce } from "immer";
+/**
+ * Immutable state store powered by Immer.
+ *
+ * Reducer receives a mutable draft (Immer proxy) — mutations are
+ * automatically converted to structural sharing under the hood.
+ */
+export class Store {
+    _reduce;
+    _state;
+    _listeners = new Set();
+    constructor(_reduce, initialState) {
+        this._reduce = _reduce;
+        this._state = initialState;
+    }
+    getState() {
+        return this._state;
+    }
+    dispatch(event) {
+        const oldState = this._state;
+        this._state = produce(oldState, (draft) => {
+            this._reduce(draft, event);
+        });
+        if (this._state !== oldState) {
+            for (const listener of this._listeners) {
+                listener(this._state, oldState);
+            }
+        }
+    }
+    /**
+     * Subscribe to state changes. Returns an unsubscribe function.
+     */
+    onStateChange(listener) {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+    dispose() {
+        this._listeners.clear();
+    }
+}

package/dist/panes/AggregateTimelinePane.d.ts

@@ -0,0 +1,2 @@
+export type AggregateTimelinePaneProps = Record<string, never>;
+export declare function AggregateTimelinePane(): import("react/jsx-runtime").JSX.Element;