causal-inspector 0.1.0

package/dist/components/JsonSyntax.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+function tokenizeJson(json) {
+    const tokens = [];
+    const re = /("(?:[^"\\]|\\.)*")\s*:|("(?:[^"\\]|\\.)*")|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|(\btrue\b|\bfalse\b)|(\bnull\b)|([{}[\]:,])/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = re.exec(json)) !== null) {
+        if (match.index > lastIndex) {
+            tokens.push({ text: json.slice(lastIndex, match.index), color: "" });
+        }
+        if (match[1] !== undefined) {
+            tokens.push({ text: match[1], color: "text-blue-400" });
+            tokens.push({ text: ":", color: "text-zinc-500" });
+        }
+        else if (match[2] !== undefined) {
+            tokens.push({ text: match[2], color: "text-green-400" });
+        }
+        else if (match[3] !== undefined) {
+            tokens.push({ text: match[3], color: "text-amber-400" });
+        }
+        else if (match[4] !== undefined) {
+            tokens.push({ text: match[4], color: "text-purple-400" });
+        }
+        else if (match[5] !== undefined) {
+            tokens.push({ text: match[5], color: "text-zinc-500" });
+        }
+        else if (match[6] !== undefined) {
+            tokens.push({ text: match[6], color: "text-zinc-500" });
+        }
+        lastIndex = re.lastIndex;
+    }
+    if (lastIndex < json.length) {
+        tokens.push({ text: json.slice(lastIndex), color: "" });
+    }
+    return tokens;
+}
+export function JsonSyntax({ json }) {
+    const tokens = tokenizeJson(json);
+    return (_jsx(_Fragment, { children: tokens.map((t, i) => (_jsx("span", { className: t.color, children: t.text }, i))) }));
+}

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import { type InspectorState } from "./state";
+import type { InspectorMachineEvent } from "./events";
+import type { EngineCreator } from "./machine";
+type CausalInspectorProviderProps = {
+    createEngine: EngineCreator<InspectorState, InspectorMachineEvent>;
+    /** Override slices of initial state (e.g. hydrated paneLayout). */
+    initialState?: Partial<InspectorState>;
+    children: ReactNode;
+};
+/**
+ * Provides the causal inspector machine to all child components.
+ *
+ * Usage:
+ * ```tsx
+ * <CausalInspectorProvider
+ *   createEngine={createInspectorEngine(transport, storage)}
+ *   initialState={{ paneLayout: savedLayout }}
+ * >
+ *   <TimelinePane />
+ *   <CausalFlowPane />
+ * </CausalInspectorProvider>
+ * ```
+ */
+export declare function CausalInspectorProvider({ createEngine, initialState: overrides, children, }: CausalInspectorProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/context.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo } from "react";
+import { Machine, MachineContext } from "./machine";
+import { reducer } from "./reducer";
+import { initialState } from "./state";
+/**
+ * Provides the causal inspector machine to all child components.
+ *
+ * Usage:
+ * ```tsx
+ * <CausalInspectorProvider
+ *   createEngine={createInspectorEngine(transport, storage)}
+ *   initialState={{ paneLayout: savedLayout }}
+ * >
+ *   <TimelinePane />
+ *   <CausalFlowPane />
+ * </CausalInspectorProvider>
+ * ```
+ */
+export function CausalInspectorProvider({ createEngine, initialState: overrides, children, }) {
+    const machine = useMemo(() => new Machine(reducer, createEngine, overrides ? { ...initialState, ...overrides } : initialState), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    useEffect(() => {
+        return () => machine.dispose();
+    }, [machine]);
+    return (_jsx(MachineContext.Provider, { value: machine, children: children }));
+}

package/dist/engines/index.d.ts

@@ -0,0 +1,22 @@
+import { type EngineCreator } from "../machine";
+import type { InspectorMachineEvent } from "../events";
+import type { InspectorState } from "../state";
+import { type SubscriptionTransport } from "./subscription";
+import { type QueryTransport } from "./query";
+import { type StorageTransport } from "./storage";
+export type { SubscriptionTransport } from "./subscription";
+export type { QueryTransport } from "./query";
+export type { StorageTransport } from "./storage";
+export { createSubscriptionEngine } from "./subscription";
+export { createQueryEngine } from "./query";
+export { createStorageEngine } from "./storage";
+export { createScrubberEngine } from "./scrubber";
+export { createUrlEngine } from "./url";
+export type InspectorTransport = SubscriptionTransport & QueryTransport;
+/**
+ * Create the default inspector engine combining subscription + query engines.
+ *
+ * Pass `storage` to persist pane layout changes. Load initial layout
+ * via `CausalInspectorProvider`'s `initialState` prop instead.
+ */
+export declare const createInspectorEngine: (transport: InspectorTransport, storage?: StorageTransport) => EngineCreator<InspectorState, InspectorMachineEvent>;

package/dist/engines/index.js

@@ -0,0 +1,29 @@
+import { combineEngineCreators } from "../machine";
+import { createSubscriptionEngine } from "./subscription";
+import { createQueryEngine } from "./query";
+import { createStorageEngine } from "./storage";
+import { createScrubberEngine } from "./scrubber";
+import { createUrlEngine } from "./url";
+export { createSubscriptionEngine } from "./subscription";
+export { createQueryEngine } from "./query";
+export { createStorageEngine } from "./storage";
+export { createScrubberEngine } from "./scrubber";
+export { createUrlEngine } from "./url";
+/**
+ * Create the default inspector engine combining subscription + query engines.
+ *
+ * Pass `storage` to persist pane layout changes. Load initial layout
+ * via `CausalInspectorProvider`'s `initialState` prop instead.
+ */
+export const createInspectorEngine = (transport, storage) => {
+    const engines = [
+        createUrlEngine,
+        createSubscriptionEngine(transport),
+        createQueryEngine(transport),
+        createScrubberEngine,
+    ];
+    if (storage) {
+        engines.push(createStorageEngine(storage));
+    }
+    return combineEngineCreators(...engines);
+};

package/dist/engines/query.d.ts

@@ -0,0 +1,14 @@
+import type { EngineCreator } from "../machine";
+import type { InspectorMachineEvent } from "../events";
+import type { InspectorState } from "../state";
+export type QueryTransport = {
+    /** Execute a GraphQL query. Returns the `data` object. */
+    query: <T = unknown>(query: string, variables?: Record<string, unknown>) => Promise<T>;
+};
+/**
+ * Query engine — fetches data in response to state transitions.
+ *
+ * State-reactive: watches (curr, prev) diffs for navigation state.
+ * Event-reactive: handles explicit requests (load_more, filter_changed, etc.).
+ */
+export declare const createQueryEngine: (transport: QueryTransport) => EngineCreator<InspectorState, InspectorMachineEvent>;

package/dist/engines/query.js

@@ -0,0 +1,241 @@
+import { INSPECTOR_EVENTS, INSPECTOR_CAUSAL_TREE, INSPECTOR_CAUSAL_FLOW, INSPECTOR_CORRELATIONS, INSPECTOR_REACTOR_DEPENDENCIES, INSPECTOR_AGGREGATE_KEYS, INSPECTOR_AGGREGATE_LIFECYCLE, INSPECTOR_REACTOR_LOGS_BY_CORRELATION, INSPECTOR_REACTOR_DESCRIPTIONS, INSPECTOR_REACTOR_DESCRIPTION_SNAPSHOTS, INSPECTOR_AGGREGATE_TIMELINE, INSPECTOR_REACTOR_OUTCOMES, } from "../queries";
+/**
+ * Query engine — fetches data in response to state transitions.
+ *
+ * State-reactive: watches (curr, prev) diffs for navigation state.
+ * Event-reactive: handles explicit requests (load_more, filter_changed, etc.).
+ */
+export const createQueryEngine = (transport) => {
+    return (dispatch, getState) => {
+        let flowPollTimer = null;
+        let correlationPollTimer = null;
+        // Stale-response guards
+        let activeCausalSeq = null;
+        let activeFlowCorrelationId = null;
+        const fetchEvents = async () => {
+            const state = getState();
+            const cursor = state.events.length > 0
+                ? state.events[state.events.length - 1].seq
+                : undefined;
+            try {
+                const data = await transport.query(INSPECTOR_EVENTS, {
+                    limit: 50,
+                    cursor,
+                    search: state.filters.search || undefined,
+                    from: state.filters.from || undefined,
+                    to: state.filters.to || undefined,
+                    correlationId: state.filters.correlationId || undefined,
+                    aggregateKey: state.filters.aggregateKey || undefined,
+                });
+                dispatch({
+                    type: "events/page_loaded",
+                    payload: {
+                        events: data.inspectorEvents.events,
+                        hasMore: data.inspectorEvents.nextCursor != null,
+                    },
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch events failed:", e);
+            }
+        };
+        const fetchCausalTree = async (seq) => {
+            activeCausalSeq = seq;
+            try {
+                const data = await transport.query(INSPECTOR_CAUSAL_TREE, { seq });
+                if (activeCausalSeq !== seq)
+                    return; // stale
+                dispatch({
+                    type: "events/causal_tree_loaded",
+                    payload: data.inspectorCausalTree,
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch causal tree failed:", e);
+            }
+        };
+        const fetchFlow = async (correlationId) => {
+            activeFlowCorrelationId = correlationId;
+            try {
+                const data = await transport.query(INSPECTOR_CAUSAL_FLOW, { correlationId });
+                if (activeFlowCorrelationId !== correlationId)
+                    return; // stale
+                dispatch({
+                    type: "events/flow_loaded",
+                    payload: data.inspectorCausalFlow.events,
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch flow failed:", e);
+            }
+        };
+        const fetchFlowMetadata = async (correlationId) => {
+            try {
+                const [descData, snapshotData, aggTimelineData, outcomeData] = await Promise.all([
+                    transport.query(INSPECTOR_REACTOR_DESCRIPTIONS, { correlationId }),
+                    transport.query(INSPECTOR_REACTOR_DESCRIPTION_SNAPSHOTS, { correlationId }),
+                    transport.query(INSPECTOR_AGGREGATE_TIMELINE, { correlationId }),
+                    transport.query(INSPECTOR_REACTOR_OUTCOMES, { correlationId }),
+                ]);
+                if (activeFlowCorrelationId !== correlationId)
+                    return; // stale
+                dispatch({
+                    type: "events/descriptions_loaded",
+                    payload: {
+                        correlationId,
+                        descriptions: descData.inspectorReactorDescriptions,
+                    },
+                });
+                dispatch({
+                    type: "events/description_snapshots_loaded",
+                    payload: {
+                        correlationId,
+                        snapshots: snapshotData.inspectorReactorDescriptionSnapshots,
+                    },
+                });
+                dispatch({
+                    type: "events/aggregate_timeline_loaded",
+                    payload: {
+                        correlationId,
+                        entries: aggTimelineData.inspectorAggregateTimeline,
+                    },
+                });
+                dispatch({
+                    type: "events/outcomes_loaded",
+                    payload: {
+                        correlationId,
+                        outcomes: outcomeData.inspectorReactorOutcomes,
+                    },
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch flow metadata failed:", e);
+            }
+        };
+        const fetchLogs = async (correlationId) => {
+            try {
+                const data = await transport.query(INSPECTOR_REACTOR_LOGS_BY_CORRELATION, { correlationId });
+                dispatch({ type: "events/logs_loaded", payload: data.inspectorReactorLogsByCorrelation });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch logs failed:", e);
+            }
+        };
+        const fetchCorrelations = async (search) => {
+            try {
+                const data = await transport.query(INSPECTOR_CORRELATIONS, { search: search || undefined, limit: 100 });
+                dispatch({
+                    type: "events/correlations_loaded",
+                    payload: data.inspectorCorrelations,
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch correlations failed:", e);
+            }
+        };
+        const fetchReactorDependencies = async () => {
+            try {
+                const data = await transport.query(INSPECTOR_REACTOR_DEPENDENCIES);
+                dispatch({
+                    type: "events/reactor_dependencies_loaded",
+                    payload: data.inspectorReactorDependencies,
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch reactor dependencies failed:", e);
+            }
+        };
+        const fetchAggregateKeys = async () => {
+            try {
+                const data = await transport.query(INSPECTOR_AGGREGATE_KEYS);
+                dispatch({
+                    type: "events/aggregate_keys_loaded",
+                    payload: data.inspectorAggregateKeys,
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch aggregate keys failed:", e);
+            }
+        };
+        const fetchAggregateLifecycle = async (aggregateKey) => {
+            try {
+                const data = await transport.query(INSPECTOR_AGGREGATE_LIFECYCLE, { aggregateKey, limit: 200 });
+                dispatch({
+                    type: "events/aggregate_lifecycle_loaded",
+                    payload: { key: aggregateKey, entries: data.inspectorAggregateLifecycle },
+                });
+            }
+            catch (e) {
+                console.error("[causal-inspector] fetch aggregate lifecycle failed:", e);
+            }
+        };
+        const startFlowPolling = (correlationId) => {
+            stopFlowPolling();
+            fetchFlowMetadata(correlationId);
+            flowPollTimer = setInterval(() => fetchFlowMetadata(correlationId), 5000);
+        };
+        const stopFlowPolling = () => {
+            if (flowPollTimer) {
+                clearInterval(flowPollTimer);
+                flowPollTimer = null;
+            }
+        };
+        const stopCorrelationPolling = () => {
+            if (correlationPollTimer) {
+                clearInterval(correlationPollTimer);
+                correlationPollTimer = null;
+            }
+        };
+        // Initial load
+        fetchEvents();
+        fetchCorrelations();
+        fetchReactorDependencies();
+        fetchAggregateKeys();
+        return {
+            handleEvent: (event, curr, prev) => {
+                // ── State-reactive: navigation transitions ──
+                if (curr.flowCorrelationId !== prev.flowCorrelationId) {
+                    if (curr.flowCorrelationId) {
+                        // Flow opened
+                        fetchFlow(curr.flowCorrelationId);
+                        startFlowPolling(curr.flowCorrelationId);
+                        fetchLogs(curr.flowCorrelationId);
+                        stopCorrelationPolling();
+                    }
+                    else {
+                        // Flow closed
+                        stopFlowPolling();
+                    }
+                }
+                // ── Event-reactive: explicit user requests ──
+                switch (event.type) {
+                    case "ui/load_more_requested":
+                        fetchEvents();
+                        break;
+                    case "ui/event_selected":
+                        fetchCausalTree(event.payload.seq);
+                        break;
+                    case "ui/filter_changed":
+                        dispatch({
+                            type: "events/page_loaded",
+                            payload: { events: [], hasMore: true },
+                        });
+                        fetchEvents();
+                        break;
+                    case "ui/correlations_requested":
+                        fetchCorrelations(event.payload.search);
+                        stopCorrelationPolling();
+                        correlationPollTimer = setInterval(() => fetchCorrelations(event.payload.search), 5000);
+                        break;
+                    case "ui/aggregate_lifecycle_requested":
+                        fetchAggregateLifecycle(event.payload.aggregateKey);
+                        break;
+                }
+            },
+            dispose: () => {
+                stopFlowPolling();
+                stopCorrelationPolling();
+            },
+        };
+    };
+};

package/dist/engines/scrubber.d.ts

@@ -0,0 +1,12 @@
+import type { EngineCreator } from "../machine";
+import type { InspectorMachineEvent } from "../events";
+import type { InspectorState } from "../state";
+/**
+ * Scrubber playback engine — advances scrubberEnd on a timer
+ * when scrubberPlaying is true.
+ *
+ * State-reactive: watches (curr, prev) diffs instead of specific events.
+ * Context-sensitive: derives the walkable sequence from current state
+ * (global events, flow events, or filtered subset).
+ */
+export declare const createScrubberEngine: EngineCreator<InspectorState, InspectorMachineEvent>;

package/dist/engines/scrubber.js

@@ -0,0 +1,69 @@
+import { getScrubberSequence } from "../utils";
+/**
+ * Scrubber playback engine — advances scrubberEnd on a timer
+ * when scrubberPlaying is true.
+ *
+ * State-reactive: watches (curr, prev) diffs instead of specific events.
+ * Context-sensitive: derives the walkable sequence from current state
+ * (global events, flow events, or filtered subset).
+ */
+export const createScrubberEngine = (dispatch, getState) => {
+    let timer = null;
+    function stop() {
+        if (timer != null) {
+            clearInterval(timer);
+            timer = null;
+        }
+    }
+    function start() {
+        stop();
+        const { scrubberSpeed } = getState();
+        timer = setInterval(() => {
+            const state = getState();
+            if (!state.scrubberPlaying) {
+                stop();
+                return;
+            }
+            const seqs = getScrubberSequence(state);
+            if (seqs.length === 0) {
+                stop();
+                return;
+            }
+            const currentEnd = state.scrubberEnd;
+            if (currentEnd == null) {
+                // At "show all" — set to first seq to begin replay
+                dispatch({ type: "ui/scrubber_end_changed", payload: { end: seqs[0] } });
+                return;
+            }
+            // Find next seq after current end position
+            const nextSeq = seqs.find((s) => s > currentEnd);
+            if (nextSeq != null) {
+                dispatch({ type: "ui/scrubber_end_changed", payload: { end: nextSeq } });
+            }
+            else {
+                // Reached the end — stop playing
+                dispatch({ type: "ui/scrubber_play_toggled" });
+            }
+        }, scrubberSpeed);
+    }
+    return {
+        handleEvent: (_event, curr, prev) => {
+            // Playing state changed
+            if (curr.scrubberPlaying !== prev.scrubberPlaying) {
+                if (curr.scrubberPlaying)
+                    start();
+                else
+                    stop();
+            }
+            // Speed changed while playing → restart with new interval
+            if (curr.scrubberSpeed !== prev.scrubberSpeed && curr.scrubberPlaying) {
+                start();
+            }
+            // Flow changed → stop playback
+            if (curr.flowCorrelationId !== prev.flowCorrelationId) {
+                stop();
+            }
+        },
+        dispose: () => stop(),
+    };
+};

package/dist/engines/storage.d.ts

@@ -0,0 +1,15 @@
+import type { EngineCreator } from "../machine";
+import type { InspectorMachineEvent } from "../events";
+import type { InspectorState } from "../state";
+import type { PaneLayout } from "../types";
+export type StorageTransport = {
+    /** Persist layout to storage. */
+    saveLayout: (layout: PaneLayout) => void;
+};
+/**
+ * Storage engine — persists pane layout changes as a side effect.
+ *
+ * Initial layout should be loaded by the consumer and passed via
+ * the provider's `initialState` — not dispatched from here.
+ */
+export declare const createStorageEngine: (transport: StorageTransport) => EngineCreator<InspectorState, InspectorMachineEvent>;

package/dist/engines/storage.js

@@ -0,0 +1,16 @@
+/**
+ * Storage engine — persists pane layout changes as a side effect.
+ *
+ * Initial layout should be loaded by the consumer and passed via
+ * the provider's `initialState` — not dispatched from here.
+ */
+export const createStorageEngine = (transport) => {
+    return () => ({
+        handleEvent: (event) => {
+            if (event.type === "ui/layout_changed") {
+                transport.saveLayout(event.payload);
+            }
+        },
+        dispose: () => { },
+    });
+};

package/dist/engines/subscription.d.ts

@@ -0,0 +1,17 @@
+import type { EngineCreator } from "../machine";
+import type { InspectorMachineEvent } from "../events";
+import type { InspectorState } from "../state";
+export type SubscriptionTransport = {
+    /** Subscribe to a GraphQL subscription. Returns an unsubscribe function. */
+    subscribe: (query: string, variables: Record<string, unknown>, onData: (data: unknown) => void, onError?: (error: unknown) => void) => () => void;
+};
+/**
+ * Subscription engine — connects to the live event stream via WebSocket.
+ *
+ * On creation, subscribes to `inspectorEventAdded`. Each event dispatches
+ * directly into the reducer as `events/received`.
+ *
+ * Transport is injected so consumers can use any GraphQL WS client
+ * (graphql-ws, Apollo, urql, etc).
+ */
+export declare const createSubscriptionEngine: (transport: SubscriptionTransport) => EngineCreator<InspectorState, InspectorMachineEvent>;

package/dist/engines/subscription.js

@@ -0,0 +1,44 @@
+import { EVENTS_SUBSCRIPTION } from "../queries";
+/**
+ * Subscription engine — connects to the live event stream via WebSocket.
+ *
+ * On creation, subscribes to `inspectorEventAdded`. Each event dispatches
+ * directly into the reducer as `events/received`.
+ *
+ * Transport is injected so consumers can use any GraphQL WS client
+ * (graphql-ws, Apollo, urql, etc).
+ */
+export const createSubscriptionEngine = (transport) => {
+    return (dispatch, getState) => {
+        let unsub = null;
+        const connect = () => {
+            const state = getState();
+            const lastSeq = state.events.length > 0 ? state.events[0].seq : undefined;
+            let connected = false;
+            unsub = transport.subscribe(EVENTS_SUBSCRIPTION, lastSeq != null ? { lastSeq } : {}, (data) => {
+                if (!connected) {
+                    connected = true;
+                    dispatch({ type: "events/subscription_connected" });
+                }
+                const event = data
+                    .inspectorEventAdded;
+                if (event) {
+                    dispatch({ type: "events/received", payload: [event] });
+                }
+            }, (error) => {
+                console.error("[causal-inspector] subscription error:", error);
+                dispatch({
+                    type: "events/subscription_error",
+                    payload: { message: String(error) },
+                });
+            });
+        };
+        // Connect immediately
+        connect();
+        return {
+            dispose: () => {
+                unsub?.();
+            },
+        };
+    };
+};

package/dist/engines/url.d.ts

@@ -0,0 +1,13 @@
+import type { EngineCreator } from "../machine";
+import type { InspectorMachineEvent } from "../events";
+import type { InspectorState } from "../state";
+/**
+ * URL engine — keeps the browser URL in sync with navigation state.
+ *
+ * For user-initiated actions (ui/flow_opened, etc.), the reducer updates
+ * state directly. This engine just writes the URL as a side effect.
+ *
+ * For browser-initiated navigation (back/forward), this engine dispatches
+ * location/changed so the reducer can update state from the URL.
+ */
+export declare const createUrlEngine: EngineCreator<InspectorState, InspectorMachineEvent>;

package/dist/engines/url.js

@@ -0,0 +1,64 @@
+function parseUrl() {
+    const params = new URLSearchParams(window.location.search);
+    return {
+        correlationId: params.get("correlation"),
+        handler: params.get("handler"),
+    };
+}
+function buildSearch(correlationId, handler) {
+    const params = new URLSearchParams(window.location.search);
+    if (correlationId)
+        params.set("correlation", correlationId);
+    else {
+        params.delete("correlation");
+        params.delete("handler");
+    }
+    if (handler && correlationId)
+        params.set("handler", handler);
+    else
+        params.delete("handler");
+    const search = params.toString();
+    return search ? `?${search}` : window.location.pathname;
+}
+/**
+ * URL engine — keeps the browser URL in sync with navigation state.
+ *
+ * For user-initiated actions (ui/flow_opened, etc.), the reducer updates
+ * state directly. This engine just writes the URL as a side effect.
+ *
+ * For browser-initiated navigation (back/forward), this engine dispatches
+ * location/changed so the reducer can update state from the URL.
+ */
+export const createUrlEngine = (dispatch, _getState) => {
+    // Popstate — browser back/forward
+    const onPopState = () => {
+        dispatch({ type: "location/changed", payload: parseUrl() });
+    };
+    window.addEventListener("popstate", onPopState);
+    // Seed from current URL on init — deferred so the Machine constructor finishes first.
+    queueMicrotask(() => {
+        const initial = parseUrl();
+        if (initial.correlationId || initial.handler) {
+            dispatch({ type: "location/changed", payload: initial });
+        }
+    });
+    return {
+        handleEvent: (event) => {
+            switch (event.type) {
+                case "ui/flow_opened":
+                    window.history.pushState(null, "", buildSearch(event.payload.correlationId, null));
+                    break;
+                case "ui/flow_closed":
+                    window.history.pushState(null, "", buildSearch(null, null));
+                    break;
+                case "ui/handler_selected":
+                    // Replace rather than push — handler changes within a flow are fine as one history entry
+                    window.history.replaceState(null, "", buildSearch(new URLSearchParams(window.location.search).get("correlation"), event.payload.reactorId));
+                    break;
+            }
+        },
+        dispose: () => {
+            window.removeEventListener("popstate", onPopState);
+        },
+    };
+};