@n-dx/core 0.1.0

package/packages/web/dist/viewer/hooks/use-prd-websocket.js

@@ -0,0 +1,139 @@
+/**
+ * PRD WebSocket real-time update hook.
+ *
+ * Sets up a five-layer message processing pipeline for real-time PRD
+ * updates via WebSocket:
+ *
+ *   raw WS → buffer gate → throttle → coalescer → DOM gate → batcher → RAF → render
+ *
+ * Each layer has a specific role:
+ *
+ * 0. **Response buffer gate** — drops messages when tab is hidden, flushes
+ *    downstream buffers to free memory, reconciles on resume.
+ * 1. **Throttle** — per-type trailing-edge debounce for high-frequency
+ *    rex message types (prd-changed, item-updated, item-deleted).
+ * 2. **Coalescer** — batches throttled output into a single reconciliation
+ *    flush instead of N separate fetches.
+ * 3. **DOM update gate** — queues state updates when tab is hidden,
+ *    replays them in a single batch when visible again.
+ * 4. **Update batcher** — collects setData calls into a single RAF
+ *    callback per animation frame.
+ *
+ * Extracted from PRDView to isolate WebSocket side effects from the
+ * component's render logic.
+ *
+ * @see ../messaging/message-coalescer.ts
+ * @see ../messaging/message-throttle.ts
+ * @see ../performance/dom-update-gate.ts
+ * @see ../performance/update-batcher.ts
+ * @see ../performance/response-buffer-gate.ts
+ */
+import { useEffect } from "preact/hooks";
+import { applyItemUpdate } from "../components/prd-tree/tree-differ.js";
+import { removeItemById } from "../components/prd-tree/tree-utils.js";
+import { createWSPipeline } from "../messaging/index.js";
+import { createUpdateBatcher, createDomUpdateGate, createResponseBufferGate } from "../performance/index.js";
+/**
+ * Hook that manages the WebSocket connection and message processing
+ * pipeline for real-time PRD updates.
+ *
+ * All parameters are expected to be stable references (wrapped in
+ * useCallback or similar). The effect re-runs when any dependency changes.
+ */
+export function usePRDWebSocket({ setData, fetchPRDData, fetchTaskUsage }) {
+    useEffect(() => {
+        let ws = null;
+        // RAF-based update batcher: ensures at most one setData call per
+        // animation frame during rapid WebSocket message bursts.
+        const batcher = createUpdateBatcher();
+        // DOM update gate: wraps the batcher to prevent state updates and
+        // re-renders when the tab is hidden.
+        const updateGate = createDomUpdateGate({ batcher });
+        // Composed throttle → coalescer pipeline for WebSocket messages.
+        const pipeline = createWSPipeline({
+            // Immediate per-message handler — optimistic UI updates are gated
+            // by tab visibility and batched into the next animation frame.
+            onMessage: (msg) => {
+                if (msg.type === "rex:item-updated" && msg.itemId && msg.updates) {
+                    updateGate.schedule(setData, (prev) => {
+                        if (!prev)
+                            return prev;
+                        const newItems = applyItemUpdate(prev.items, msg.itemId, msg.updates);
+                        return newItems === prev.items ? prev : { ...prev, items: newItems };
+                    });
+                    return;
+                }
+                if (msg.type === "rex:item-deleted" && msg.itemId) {
+                    updateGate.schedule(setData, (prev) => {
+                        if (!prev)
+                            return prev;
+                        const newItems = removeItemById(prev.items, msg.itemId);
+                        return newItems === prev.items ? prev : { ...prev, items: newItems };
+                    });
+                }
+            },
+            // Coalesced flush — fires once per debounce window for reconciliation.
+            onFlush: (batch) => {
+                updateGate.flush();
+                const needsReconciliation = batch.types.has("rex:item-updated") ||
+                    batch.types.has("rex:item-deleted") ||
+                    batch.types.has("rex:prd-changed");
+                if (needsReconciliation) {
+                    fetchPRDData();
+                    fetchTaskUsage();
+                }
+            },
+            defaultDelayMs: 250,
+            delays: {
+                "rex:prd-changed": 300, // heavier — full tree reconciliation
+                "rex:item-updated": 200, // lighter — targeted node patch
+                "rex:item-deleted": 200, // lighter — targeted node removal
+            },
+            throttledTypes: ["rex:prd-changed", "rex:item-updated", "rex:item-deleted"],
+            maxPendingPerType: 20,
+        });
+        // Response buffer gate: drops messages while tab is hidden,
+        // reconciles on resume.
+        const bufferGate = createResponseBufferGate({
+            flushDownstream: [
+                () => pipeline.flush(),
+                () => updateGate.flush(),
+            ],
+            onResume: () => {
+                fetchPRDData();
+                fetchTaskUsage();
+            },
+        });
+        try {
+            const proto = location.protocol === "https:" ? "wss:" : "ws:";
+            ws = new WebSocket(`${proto}//${location.host}`);
+            ws.onmessage = (event) => {
+                try {
+                    const msg = JSON.parse(event.data);
+                    if (!bufferGate.accept())
+                        return; // Tab hidden — drop message
+                    pipeline.push(msg);
+                }
+                catch {
+                    // Ignore malformed messages
+                }
+            };
+        }
+        catch {
+            // WebSocket not available — polling still works as fallback
+        }
+        return () => {
+            bufferGate.dispose();
+            pipeline.dispose();
+            updateGate.dispose();
+            batcher.dispose();
+            if (ws) {
+                try {
+                    ws.close();
+                }
+                catch { /* ignore */ }
+            }
+        };
+    }, [setData, fetchPRDData, fetchTaskUsage]);
+}
+//# sourceMappingURL=use-prd-websocket.js.map

package/packages/web/dist/viewer/hooks/use-prd-websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-prd-websocket.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-prd-websocket.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/viewer/hooks/use-project-metadata.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared hook + cache for project metadata from `/api/project`.
+ *
+ * Used by both the sidebar header (project name display) and the
+ * breadcrumb component.
+ */
+export interface GitInfo {
+    branch: string | null;
+    sha: string | null;
+    remoteUrl: string | null;
+    repoName: string | null;
+}
+export interface ProjectMetadata {
+    name: string;
+    description: string | null;
+    version: string | null;
+    git: GitInfo | null;
+    nameSource: "package.json" | "directory";
+}
+/** Fetch with dedup — concurrent calls share one in-flight request. */
+export declare function getProjectMetadata(): Promise<ProjectMetadata | null>;
+/** Return the cached value synchronously (may be null if not yet fetched). */
+export declare function getCachedProjectMetadata(): ProjectMetadata | null;
+/** Preact hook — returns project metadata (fetches once, shares cache). */
+export declare function useProjectMetadata(): ProjectMetadata | null;

package/packages/web/dist/viewer/hooks/use-project-metadata.js

@@ -0,0 +1,55 @@
+/**
+ * Shared hook + cache for project metadata from `/api/project`.
+ *
+ * Used by both the sidebar header (project name display) and the
+ * breadcrumb component.
+ */
+import { useState, useEffect } from "preact/hooks";
+// ---------------------------------------------------------------------------
+// Singleton fetch + cache
+// ---------------------------------------------------------------------------
+let cachedMeta = null;
+let fetchPromise = null;
+async function fetchProjectMetadata() {
+    try {
+        const res = await fetch("/api/project");
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/** Fetch with dedup — concurrent calls share one in-flight request. */
+export function getProjectMetadata() {
+    if (cachedMeta)
+        return Promise.resolve(cachedMeta);
+    if (!fetchPromise) {
+        fetchPromise = fetchProjectMetadata().then((m) => {
+            cachedMeta = m;
+            fetchPromise = null;
+            return m;
+        });
+    }
+    return fetchPromise;
+}
+/** Return the cached value synchronously (may be null if not yet fetched). */
+export function getCachedProjectMetadata() {
+    return cachedMeta;
+}
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+/** Preact hook — returns project metadata (fetches once, shares cache). */
+export function useProjectMetadata() {
+    const [project, setProject] = useState(cachedMeta);
+    useEffect(() => {
+        getProjectMetadata().then((m) => {
+            if (m)
+                setProject(m);
+        });
+    }, []);
+    return project;
+}
+//# sourceMappingURL=use-project-metadata.js.map

package/packages/web/dist/viewer/hooks/use-project-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-project-metadata.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-project-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAqBnD,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,IAAI,UAAU,GAA2B,IAAI,CAAC;AAC9C,IAAI,YAAY,GAA2C,IAAI,CAAC;AAEhE,KAAK,UAAU,oBAAoB;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,cAAc,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAoB,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,kBAAkB;IAChC,IAAI,UAAU;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,oBAAoB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YAC/C,UAAU,GAAG,CAAC,CAAC;YACf,YAAY,GAAG,IAAI,CAAC;YACpB,OAAO,CAAC,CAAC;QACX,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,wBAAwB;IACtC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB;IAChC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAyB,UAAU,CAAC,CAAC;IAE3E,SAAS,CAAC,GAAG,EAAE;QACb,kBAAkB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YAC9B,IAAI,CAAC;gBAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/packages/web/dist/viewer/hooks/use-project-status.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Hook for project-wide status polling + WebSocket instant updates.
+ *
+ * Fetches `/api/status` with dedup + visibility-aware polling, and listens
+ * for WebSocket events (hench:run-changed, rex:prd-changed) to refresh
+ * immediately when backend state changes.
+ *
+ * Polling is automatically suspended when memory pressure disables the
+ * `autoRefresh` feature (elevated tier and above). The last-known status
+ * is preserved and displayed without updates until pressure subsides.
+ *
+ * Follows the same hook-over-infrastructure pattern as use-prd-websocket,
+ * use-memory-monitor, etc. — all infrastructure coupling (WebSocket,
+ * ws-pipeline, graceful-degradation) lives here rather than in a
+ * presentation component.
+ */
+type AnalysisFreshness = "fresh" | "stale" | "unavailable";
+export interface SourceVisionStatus {
+    freshness: AnalysisFreshness;
+    analyzedAt: string | null;
+    minutesAgo: number | null;
+    modulesComplete: number;
+    modulesTotal: number;
+}
+export interface TreeStats {
+    total: number;
+    completed: number;
+    inProgress: number;
+    pending: number;
+    deferred: number;
+    blocked: number;
+}
+export interface RexStatus {
+    exists: boolean;
+    percentComplete: number;
+    stats: TreeStats | null;
+    hasInProgress: boolean;
+    hasPending: boolean;
+    nextTaskTitle: string | null;
+}
+export interface HenchStatus {
+    configured: boolean;
+    totalRuns: number;
+    activeRuns: number;
+    staleRuns: number;
+}
+export interface ProjectStatus {
+    sv: SourceVisionStatus;
+    rex: RexStatus;
+    hench: HenchStatus;
+}
+/** Hook that returns project status, polling at a regular interval.
+ *  Also listens for WebSocket events (hench:run-changed, rex:prd-changed)
+ *  to refresh immediately when runs or PRD data change on disk.
+ *
+ *  Polling is automatically suspended when memory pressure disables the
+ *  `autoRefresh` feature (elevated tier and above). The last-known status
+ *  is preserved and displayed without updates until pressure subsides. */
+export declare function useProjectStatus(): ProjectStatus | null;
+export {};

package/packages/web/dist/viewer/hooks/use-project-status.js

@@ -0,0 +1,133 @@
+/**
+ * Hook for project-wide status polling + WebSocket instant updates.
+ *
+ * Fetches `/api/status` with dedup + visibility-aware polling, and listens
+ * for WebSocket events (hench:run-changed, rex:prd-changed) to refresh
+ * immediately when backend state changes.
+ *
+ * Polling is automatically suspended when memory pressure disables the
+ * `autoRefresh` feature (elevated tier and above). The last-known status
+ * is preserved and displayed without updates until pressure subsides.
+ *
+ * Follows the same hook-over-infrastructure pattern as use-prd-websocket,
+ * use-memory-monitor, etc. — all infrastructure coupling (WebSocket,
+ * ws-pipeline, graceful-degradation) lives here rather than in a
+ * presentation component.
+ */
+import { useState, useEffect, useCallback, useRef } from "preact/hooks";
+import { usePolling } from "./use-polling.js";
+import { createWSPipeline } from "../messaging/index.js";
+import { isFeatureDisabled, onDegradationChange } from "../performance/index.js";
+// ---------------------------------------------------------------------------
+// Status fetcher with dedup + polling
+// ---------------------------------------------------------------------------
+const POLL_INTERVAL_MS = 10_000;
+let cachedStatus = null;
+let fetchPromise = null;
+async function fetchStatus() {
+    if (fetchPromise)
+        return fetchPromise;
+    fetchPromise = (async () => {
+        try {
+            const res = await fetch("/api/status");
+            if (!res.ok)
+                return null;
+            const data = await res.json();
+            cachedStatus = data;
+            return data;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            fetchPromise = null;
+        }
+    })();
+    return fetchPromise;
+}
+/** Hook that returns project status, polling at a regular interval.
+ *  Also listens for WebSocket events (hench:run-changed, rex:prd-changed)
+ *  to refresh immediately when runs or PRD data change on disk.
+ *
+ *  Polling is automatically suspended when memory pressure disables the
+ *  `autoRefresh` feature (elevated tier and above). The last-known status
+ *  is preserved and displayed without updates until pressure subsides. */
+export function useProjectStatus() {
+    const [status, setStatus] = useState(cachedStatus);
+    const mountedRef = useRef(true);
+    // Track memory-pressure state reactively so usePolling's `enabled`
+    // parameter updates when the degradation tier changes.
+    const [autoRefreshDisabled, setAutoRefreshDisabled] = useState(() => isFeatureDisabled("autoRefresh"));
+    useEffect(() => {
+        const unsubscribe = onDegradationChange((state) => {
+            setAutoRefreshDisabled(state.disabledFeatures.has("autoRefresh"));
+        });
+        return unsubscribe;
+    }, []);
+    const refresh = useCallback(async () => {
+        const data = await fetchStatus();
+        if (mountedRef.current)
+            setStatus(data);
+    }, []);
+    // Initial fetch + WebSocket for instant updates
+    useEffect(() => {
+        mountedRef.current = true;
+        refresh();
+        // Connect to WebSocket for instant status updates when runs/PRD change.
+        // Composed throttle → coalescer pipeline debounces high-frequency
+        // message types independently before batching into a single refresh.
+        let ws = null;
+        const pipeline = createWSPipeline({
+            onFlush: (batch) => {
+                if (!mountedRef.current)
+                    return;
+                const needsRefresh = batch.types.has("hench:run-changed") ||
+                    batch.types.has("hench:task-execution-progress") ||
+                    batch.types.has("rex:prd-changed");
+                if (needsRefresh) {
+                    refresh();
+                }
+            },
+            defaultDelayMs: 250,
+            delays: {
+                "rex:prd-changed": 300,
+                "hench:task-execution-progress": 200,
+            },
+            throttledTypes: ["rex:prd-changed", "hench:task-execution-progress"],
+            maxPendingPerType: 20,
+        });
+        try {
+            const proto = location.protocol === "https:" ? "wss:" : "ws:";
+            ws = new WebSocket(`${proto}//${location.host}`);
+            ws.onmessage = (event) => {
+                if (!mountedRef.current)
+                    return;
+                try {
+                    const msg = JSON.parse(event.data);
+                    pipeline.push(msg);
+                }
+                catch {
+                    // ignore malformed messages
+                }
+            };
+        }
+        catch {
+            // WebSocket not available — polling still works as fallback
+        }
+        return () => {
+            mountedRef.current = false;
+            pipeline.dispose();
+            if (ws) {
+                try {
+                    ws.close();
+                }
+                catch { /* ignore */ }
+            }
+        };
+    }, [refresh]);
+    // Visibility-aware polling via polling manager.
+    // Disabled during memory pressure (autoRefresh feature disabled).
+    usePolling("status-indicators", refresh, POLL_INTERVAL_MS, !autoRefreshDisabled);
+    return status;
+}
+//# sourceMappingURL=use-project-status.js.map

package/packages/web/dist/viewer/hooks/use-project-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-project-status.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-project-status.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/viewer/hooks/use-refresh-throttle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Preact hook for memory-aware refresh throttling.
+ *
+ * Provides reactive queue state to components so they can display
+ * queue progress, memory-adjusted intervals, and estimated completion
+ * times. Starts the refresh throttle on mount and cleans up on unmount.
+ */
+import type { MemoryLevel, RefreshQueueState, RefreshPriority } from "../performance/index.js";
+export interface UseRefreshThrottleOptions {
+    /** Base polling interval in milliseconds (default: 5000). */
+    baseIntervalMs?: number;
+    /** Average time a single refresh takes, for ETA estimation (default: 800ms). */
+    avgRefreshMs?: number;
+    /** Whether to start the throttle immediately (default: true). */
+    enabled?: boolean;
+}
+export interface UseRefreshThrottleResult {
+    /** Current queue state snapshot. */
+    state: RefreshQueueState;
+    /** Number of items waiting in the queue. */
+    queueLength: number;
+    /** Whether any refresh operations are active. */
+    isProcessing: boolean;
+    /** Whether the queue is paused due to memory pressure. */
+    paused: boolean;
+    /** Current memory level informing throttle decisions. */
+    memoryLevel: MemoryLevel;
+    /** Recommended polling interval for the current memory level. */
+    recommendedIntervalMs: number;
+    /** Estimated milliseconds until the queue is fully drained (-1 if unknown). */
+    estimatedCompletionMs: number;
+    /** Enqueue a refresh operation. Returns true if queued. */
+    enqueue: (key: string, execute: () => Promise<void>, priority?: RefreshPriority) => boolean;
+    /** Get the recommended interval for a given base interval. */
+    getInterval: (baseMs?: number) => number;
+}
+/**
+ * Hook that provides memory-aware refresh throttling state.
+ *
+ * Usage:
+ * ```tsx
+ * const { queueLength, paused, estimatedCompletionMs, enqueue } = useRefreshThrottle();
+ * ```
+ */
+export declare function useRefreshThrottle(options?: UseRefreshThrottleOptions): UseRefreshThrottleResult;

package/packages/web/dist/viewer/hooks/use-refresh-throttle.js

@@ -0,0 +1,52 @@
+/**
+ * Preact hook for memory-aware refresh throttling.
+ *
+ * Provides reactive queue state to components so they can display
+ * queue progress, memory-adjusted intervals, and estimated completion
+ * times. Starts the refresh throttle on mount and cleans up on unmount.
+ */
+import { useState, useEffect, useCallback } from "preact/hooks";
+import { startRefreshThrottle, stopRefreshThrottle, onQueueChange, getQueueState, enqueueRefresh, getRecommendedInterval, } from "../performance/refresh-throttle.js";
+/**
+ * Hook that provides memory-aware refresh throttling state.
+ *
+ * Usage:
+ * ```tsx
+ * const { queueLength, paused, estimatedCompletionMs, enqueue } = useRefreshThrottle();
+ * ```
+ */
+export function useRefreshThrottle(options = {}) {
+    const { baseIntervalMs = 5000, avgRefreshMs = 800, enabled = true } = options;
+    const [queueState, setQueueState] = useState(getQueueState);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        startRefreshThrottle({ baseIntervalMs, avgRefreshMs });
+        const unsubscribe = onQueueChange((newState) => {
+            setQueueState(newState);
+        });
+        // Sync in case state changed between render and effect.
+        setQueueState(getQueueState());
+        return () => {
+            unsubscribe();
+            stopRefreshThrottle();
+        };
+    }, [enabled, baseIntervalMs, avgRefreshMs]);
+    const enqueue = useCallback((key, execute, priority) => enqueueRefresh(key, execute, priority), []);
+    const getInterval = useCallback((baseMs) => getRecommendedInterval(baseMs), 
+    // Re-create when state changes so the closure captures fresh module state.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queueState]);
+    return {
+        state: queueState,
+        queueLength: queueState.queueLength,
+        isProcessing: queueState.activeCount > 0,
+        paused: queueState.paused,
+        memoryLevel: queueState.memoryLevel,
+        recommendedIntervalMs: queueState.recommendedIntervalMs,
+        estimatedCompletionMs: queueState.estimatedCompletionMs,
+        enqueue,
+        getInterval,
+    };
+}
+//# sourceMappingURL=use-refresh-throttle.js.map

package/packages/web/dist/viewer/hooks/use-refresh-throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-refresh-throttle.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-refresh-throttle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,cAAc,EACd,sBAAsB,GAEvB,MAAM,oCAAoC,CAAC;AAgC5C;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAqC,EAAE;IAEvC,MAAM,EAAE,cAAc,GAAG,IAAI,EAAE,YAAY,GAAG,GAAG,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAE9E,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAoB,aAAa,CAAC,CAAC;IAE/E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,oBAAoB,CAAC,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC;QAEvD,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,QAAQ,EAAE,EAAE;YAC7C,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,wDAAwD;QACxD,aAAa,CAAC,aAAa,EAAE,CAAC,CAAC;QAE/B,OAAO,GAAG,EAAE;YACV,WAAW,EAAE,CAAC;YACd,mBAAmB,EAAE,CAAC;QACxB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,GAAW,EAAE,OAA4B,EAAE,QAA0B,EAAE,EAAE,CACxE,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,EACxC,EAAE,CACH,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,MAAe,EAAE,EAAE,CAAC,sBAAsB,CAAC,MAAM,CAAC;IACnD,2EAA2E;IAC3E,uDAAuD;IACvD,CAAC,UAAU,CAAC,CACb,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,YAAY,EAAE,UAAU,CAAC,WAAW,GAAG,CAAC;QACxC,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,qBAAqB,EAAE,UAAU,CAAC,qBAAqB;QACvD,qBAAqB,EAAE,UAAU,CAAC,qBAAqB;QACvD,OAAO;QACP,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/packages/web/dist/viewer/hooks/use-route-state.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Route state management hook for the viewer app.
+ *
+ * Manages the active view, selected entity IDs (file, zone, run, task),
+ * URL history synchronisation, and backward-compat migration of legacy hash URLs.
+ */
+import type { ViewId, NavigateTo } from "../types.js";
+export interface RouteState {
+    view: ViewId;
+    selectedFile: string | null;
+    setSelectedFile: (file: string | null) => void;
+    selectedZone: string | null;
+    selectedRunId: string | null;
+    selectedTaskId: string | null;
+    navigateTo: NavigateTo;
+    handleSidebarNav: (id: ViewId) => void;
+}
+export declare function useRouteState(validViews: Set<ViewId>): RouteState;