@n-dx/core 0.1.0

package/packages/web/dist/server/ws-health-tracker.js

@@ -0,0 +1,186 @@
+/**
+ * WebSocket connection health tracker — records connection lifecycle events,
+ * cleanup metrics, and resource usage for dashboard monitoring.
+ *
+ * Instruments the WebSocket manager to collect:
+ * - Active vs total (historical peak) connection counts
+ * - Cleanup events: successful removals, reasons, timing
+ * - Broadcast statistics: total broadcasts, failed writes
+ * - Connection duration tracking
+ *
+ * Designed as a singleton that accumulates metrics over the server lifetime.
+ * Provides a snapshot API consumed by the REST endpoint and WS broadcast.
+ */
+/** Maximum number of recent cleanup events to retain for rolling stats. */
+const MAX_CLEANUP_HISTORY = 500;
+/** Window (ms) for "recent cleanups" count. */
+const RECENT_WINDOW_MS = 60_000;
+/** Window (ms) for average connection duration calculation. */
+const DURATION_WINDOW_MS = 5 * 60_000;
+export class WsHealthTracker {
+    startedAt = Date.now();
+    // Connection tracking
+    activeConnectionCount = 0;
+    peakConnectionCount = 0;
+    totalAccepted = 0;
+    totalRemoved = 0;
+    // Per-connection timestamps for duration tracking
+    connectionStartTimes = new Map();
+    connectionIdCounter = 0;
+    // Cleanup history (ring buffer)
+    cleanupHistory = [];
+    cleanupsByReason = {
+        close: 0,
+        error: 0,
+        end: 0,
+        ping_timeout: 0,
+        prune: 0,
+        shutdown: 0,
+        write_fail: 0,
+    };
+    // Broadcast tracking
+    totalBroadcasts = 0;
+    totalWriteFailures = 0;
+    // Cleanup timing: track ms from connection start to cleanup
+    // for "cleanup latency" (how quickly we detect dead connections)
+    cleanupLatencySum = 0;
+    cleanupLatencyCount = 0;
+    /**
+     * Record a new connection being accepted.
+     * Returns a connection ID to pass to `recordDisconnect()`.
+     */
+    recordConnect() {
+        const id = String(++this.connectionIdCounter);
+        this.connectionStartTimes.set(id, Date.now());
+        this.activeConnectionCount++;
+        this.totalAccepted++;
+        if (this.activeConnectionCount > this.peakConnectionCount) {
+            this.peakConnectionCount = this.activeConnectionCount;
+        }
+        return id;
+    }
+    /**
+     * Record a connection being removed.
+     */
+    recordDisconnect(connectionId, reason) {
+        const startTime = this.connectionStartTimes.get(connectionId);
+        if (!startTime)
+            return; // Already recorded or unknown
+        this.connectionStartTimes.delete(connectionId);
+        const now = Date.now();
+        const durationMs = now - startTime;
+        this.activeConnectionCount = Math.max(0, this.activeConnectionCount - 1);
+        this.totalRemoved++;
+        this.cleanupsByReason[reason]++;
+        const event = {
+            reason,
+            timestamp: now,
+            connectionDurationMs: durationMs,
+        };
+        // Ring buffer for cleanup history
+        if (this.cleanupHistory.length >= MAX_CLEANUP_HISTORY) {
+            this.cleanupHistory.shift();
+        }
+        this.cleanupHistory.push(event);
+        // Accumulate cleanup latency for averaging
+        this.cleanupLatencySum += durationMs;
+        this.cleanupLatencyCount++;
+    }
+    /** Record a broadcast attempt. */
+    recordBroadcast() {
+        this.totalBroadcasts++;
+    }
+    /** Record a failed write during broadcast. */
+    recordBroadcastWriteFailure() {
+        this.totalWriteFailures++;
+    }
+    /**
+     * Sync the active connection count with the actual client set size.
+     * Called periodically to correct any drift from missed events.
+     */
+    syncActiveCount(actualCount) {
+        this.activeConnectionCount = actualCount;
+        if (actualCount > this.peakConnectionCount) {
+            this.peakConnectionCount = actualCount;
+        }
+    }
+    /** Get a snapshot of current health metrics. */
+    getSnapshot() {
+        const now = Date.now();
+        // Recent cleanups (last 60s)
+        const recentCutoff = now - RECENT_WINDOW_MS;
+        const recentCleanups = this.cleanupHistory.filter((e) => e.timestamp >= recentCutoff).length;
+        // Average connection duration for connections closed in last 5 min
+        const durationCutoff = now - DURATION_WINDOW_MS;
+        const recentDurations = this.cleanupHistory
+            .filter((e) => e.timestamp >= durationCutoff)
+            .map((e) => e.connectionDurationMs);
+        const avgConnectionDurationMs = recentDurations.length > 0
+            ? Math.round(recentDurations.reduce((a, b) => a + b, 0) / recentDurations.length)
+            : 0;
+        // Cleanup success rate: event-driven cleanups (close/error/end) vs
+        // safety-net cleanups (ping_timeout/prune/write_fail)
+        const totalCleanups = this.totalRemoved;
+        const eventDrivenCleanups = this.cleanupsByReason.close +
+            this.cleanupsByReason.error +
+            this.cleanupsByReason.end +
+            this.cleanupsByReason.shutdown;
+        const cleanupSuccessRate = totalCleanups > 0 ? eventDrivenCleanups / totalCleanups : 1;
+        // Average cleanup latency
+        const avgCleanupLatencyMs = this.cleanupLatencyCount > 0
+            ? Math.round(this.cleanupLatencySum / this.cleanupLatencyCount)
+            : 0;
+        // Health level
+        const health = this.computeHealth(cleanupSuccessRate, recentCleanups);
+        return {
+            activeConnections: this.activeConnectionCount,
+            peakConnections: this.peakConnectionCount,
+            totalConnectionsAccepted: this.totalAccepted,
+            totalConnectionsRemoved: this.totalRemoved,
+            cleanupsByReason: { ...this.cleanupsByReason },
+            recentCleanups,
+            avgConnectionDurationMs,
+            totalBroadcasts: this.totalBroadcasts,
+            totalBroadcastWriteFailures: this.totalWriteFailures,
+            cleanupSuccessRate: Math.round(cleanupSuccessRate * 1000) / 1000,
+            avgCleanupLatencyMs,
+            health,
+            uptimeMs: now - this.startedAt,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /** Reset all counters (for testing). */
+    reset() {
+        this.activeConnectionCount = 0;
+        this.peakConnectionCount = 0;
+        this.totalAccepted = 0;
+        this.totalRemoved = 0;
+        this.connectionStartTimes.clear();
+        this.connectionIdCounter = 0;
+        this.cleanupHistory.length = 0;
+        this.cleanupsByReason.close = 0;
+        this.cleanupsByReason.error = 0;
+        this.cleanupsByReason.end = 0;
+        this.cleanupsByReason.ping_timeout = 0;
+        this.cleanupsByReason.prune = 0;
+        this.cleanupsByReason.shutdown = 0;
+        this.cleanupsByReason.write_fail = 0;
+        this.totalBroadcasts = 0;
+        this.totalWriteFailures = 0;
+        this.cleanupLatencySum = 0;
+        this.cleanupLatencyCount = 0;
+    }
+    computeHealth(cleanupSuccessRate, recentCleanups) {
+        // Unhealthy: high rate of safety-net cleanups (>30% are prune/timeout/write_fail)
+        // or very high cleanup churn (>50 cleanups per minute)
+        if (cleanupSuccessRate < 0.7 || recentCleanups > 50) {
+            return "unhealthy";
+        }
+        // Degraded: moderate safety-net usage or moderate churn
+        if (cleanupSuccessRate < 0.9 || recentCleanups > 20) {
+            return "degraded";
+        }
+        return "healthy";
+    }
+}
+//# sourceMappingURL=ws-health-tracker.js.map

package/packages/web/dist/server/ws-health-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-health-tracker.js","sourceRoot":"","sources":["../../src/server/ws-health-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsDH,2EAA2E;AAC3E,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,+CAA+C;AAC/C,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC,+DAA+D;AAC/D,MAAM,kBAAkB,GAAG,CAAC,GAAG,MAAM,CAAC;AAEtC,MAAM,OAAO,eAAe;IACT,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAExC,sBAAsB;IACd,qBAAqB,GAAG,CAAC,CAAC;IAC1B,mBAAmB,GAAG,CAAC,CAAC;IACxB,aAAa,GAAG,CAAC,CAAC;IAClB,YAAY,GAAG,CAAC,CAAC;IAEzB,kDAAkD;IACjC,oBAAoB,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1D,mBAAmB,GAAG,CAAC,CAAC;IAEhC,gCAAgC;IACf,cAAc,GAAmB,EAAE,CAAC;IACpC,gBAAgB,GAAkC;QACjE,KAAK,EAAE,CAAC;QACR,KAAK,EAAE,CAAC;QACR,GAAG,EAAE,CAAC;QACN,YAAY,EAAE,CAAC;QACf,KAAK,EAAE,CAAC;QACR,QAAQ,EAAE,CAAC;QACX,UAAU,EAAE,CAAC;KACd,CAAC;IAEF,qBAAqB;IACb,eAAe,GAAG,CAAC,CAAC;IACpB,kBAAkB,GAAG,CAAC,CAAC;IAE/B,4DAA4D;IAC5D,iEAAiE;IACzD,iBAAiB,GAAG,CAAC,CAAC;IACtB,mBAAmB,GAAG,CAAC,CAAC;IAEhC;;;OAGG;IACH,aAAa;QACX,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC9C,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC7B,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC1D,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,qBAAqB,CAAC;QACxD,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,YAAoB,EAAE,MAAqB;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC9D,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,8BAA8B;QAEtD,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,GAAG,GAAG,SAAS,CAAC;QAEnC,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAAG,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;QAEhC,MAAM,KAAK,GAAiB;YAC1B,MAAM;YACN,SAAS,EAAE,GAAG;YACd,oBAAoB,EAAE,UAAU;SACjC,CAAC;QAEF,kCAAkC;QAClC,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;YACtD,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEhC,2CAA2C;QAC3C,IAAI,CAAC,iBAAiB,IAAI,UAAU,CAAC;QACrC,IAAI,CAAC,mBAAmB,EAAE,CAAC;IAC7B,CAAC;IAED,kCAAkC;IAClC,eAAe;QACb,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAED,8CAA8C;IAC9C,2BAA2B;QACzB,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,WAAmB;QACjC,IAAI,CAAC,qBAAqB,GAAG,WAAW,CAAC;QACzC,IAAI,WAAW,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC3C,IAAI,CAAC,mBAAmB,GAAG,WAAW,CAAC;QACzC,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,WAAW;QACT,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,6BAA6B;QAC7B,MAAM,YAAY,GAAG,GAAG,GAAG,gBAAgB,CAAC;QAC5C,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAC/C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,YAAY,CACnC,CAAC,MAAM,CAAC;QAET,mEAAmE;QACnE,MAAM,cAAc,GAAG,GAAG,GAAG,kBAAkB,CAAC;QAChD,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc;aACxC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,cAAc,CAAC;aAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;QACtC,MAAM,uBAAuB,GAC3B,eAAe,CAAC,MAAM,GAAG,CAAC;YACxB,CAAC,CAAC,IAAI,CAAC,KAAK,CACR,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,MAAM,CACpE;YACH,CAAC,CAAC,CAAC,CAAC;QAER,mEAAmE;QACnE,sDAAsD;QACtD,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC;QACxC,MAAM,mBAAmB,GACvB,IAAI,CAAC,gBAAgB,CAAC,KAAK;YAC3B,IAAI,CAAC,gBAAgB,CAAC,KAAK;YAC3B,IAAI,CAAC,gBAAgB,CAAC,GAAG;YACzB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC;QACjC,MAAM,kBAAkB,GACtB,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAE9D,0BAA0B;QAC1B,MAAM,mBAAmB,GACvB,IAAI,CAAC,mBAAmB,GAAG,CAAC;YAC1B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC/D,CAAC,CAAC,CAAC,CAAC;QAER,eAAe;QACf,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC;QAEtE,OAAO;YACL,iBAAiB,EAAE,IAAI,CAAC,qBAAqB;YAC7C,eAAe,EAAE,IAAI,CAAC,mBAAmB;YACzC,wBAAwB,EAAE,IAAI,CAAC,aAAa;YAC5C,uBAAuB,EAAE,IAAI,CAAC,YAAY;YAC1C,gBAAgB,EAAE,EAAE,GAAG,IAAI,CAAC,gBAAgB,EAAE;YAC9C,cAAc;YACd,uBAAuB;YACvB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,2BAA2B,EAAE,IAAI,CAAC,kBAAkB;YACpD,kBAAkB,EAAE,IAAI,CAAC,KAAK,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,IAAI;YAChE,mBAAmB;YACnB,MAAM;YACN,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC,SAAS;YAC9B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;IACJ,CAAC;IAED,wCAAwC;IACxC,KAAK;QACH,IAAI,CAAC,qBAAqB,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,GAAG,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,gBAAgB,CAAC,YAAY,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,gBAAgB,CAAC,UAAU,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;IAC/B,CAAC;IAEO,aAAa,CACnB,kBAA0B,EAC1B,cAAsB;QAEtB,kFAAkF;QAClF,uDAAuD;QACvD,IAAI,kBAAkB,GAAG,GAAG,IAAI,cAAc,GAAG,EAAE,EAAE,CAAC;YACpD,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,wDAAwD;QACxD,IAAI,kBAAkB,GAAG,GAAG,IAAI,cAAc,GAAG,EAAE,EAAE,CAAC;YACpD,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/packages/web/dist/shared/data-files.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Data file name constants for sourcevision output.
+ *
+ * Shared between the server layer (which serves these files) and the
+ * viewer layer (which fetches/validates them). Deliberately placed in
+ * a neutral `shared/` directory so neither layer owns the constants.
+ */
+export declare const DATA_FILES: {
+    readonly manifest: "manifest.json";
+    readonly inventory: "inventory.json";
+    readonly imports: "imports.json";
+    readonly zones: "zones.json";
+    readonly components: "components.json";
+    readonly callGraph: "callgraph.json";
+};
+export declare const ALL_DATA_FILES: ("manifest.json" | "inventory.json" | "imports.json" | "zones.json" | "components.json" | "callgraph.json")[];
+export declare const SUPPLEMENTARY_FILES: readonly ["llms.txt", "CONTEXT.md"];

package/packages/web/dist/shared/data-files.js

@@ -0,0 +1,18 @@
+/**
+ * Data file name constants for sourcevision output.
+ *
+ * Shared between the server layer (which serves these files) and the
+ * viewer layer (which fetches/validates them). Deliberately placed in
+ * a neutral `shared/` directory so neither layer owns the constants.
+ */
+export const DATA_FILES = {
+    manifest: "manifest.json",
+    inventory: "inventory.json",
+    imports: "imports.json",
+    zones: "zones.json",
+    components: "components.json",
+    callGraph: "callgraph.json",
+};
+export const ALL_DATA_FILES = Object.values(DATA_FILES);
+export const SUPPLEMENTARY_FILES = ["llms.txt", "CONTEXT.md"];
+//# sourceMappingURL=data-files.js.map

package/packages/web/dist/shared/data-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-files.js","sourceRoot":"","sources":["../../src/shared/data-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,QAAQ,EAAE,eAAe;IACzB,SAAS,EAAE,gBAAgB;IAC3B,OAAO,EAAE,cAAc;IACvB,KAAK,EAAE,YAAY;IACnB,UAAU,EAAE,iBAAiB;IAC7B,SAAS,EAAE,gBAAgB;CACnB,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AAExD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,YAAY,CAAU,CAAC"}

package/packages/web/dist/shared/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared utilities for the web package.
+ *
+ * Framework-agnostic modules used by both the viewer and server layers.
+ * Each module has zero external dependencies — integration with Preact
+ * or other frameworks is handled by the consumer.
+ */
+export { DATA_FILES, ALL_DATA_FILES, SUPPLEMENTARY_FILES } from "./data-files.js";
+export type { ViewId } from "./view-id.js";

package/packages/web/dist/shared/index.js

@@ -0,0 +1,9 @@
+/**
+ * Shared utilities for the web package.
+ *
+ * Framework-agnostic modules used by both the viewer and server layers.
+ * Each module has zero external dependencies — integration with Preact
+ * or other frameworks is handled by the consumer.
+ */
+export { DATA_FILES, ALL_DATA_FILES, SUPPLEMENTARY_FILES } from "./data-files.js";
+//# sourceMappingURL=index.js.map

package/packages/web/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/packages/web/dist/shared/node-culler.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Off-screen node culling engine using IntersectionObserver.
+ *
+ * Manages a single shared IntersectionObserver that tracks multiple tree
+ * node elements and invokes per-element callbacks when visibility changes.
+ * Nodes outside the viewport buffer are "culled" — their DOM children are
+ * removed and replaced with a height-preserving placeholder, freeing memory
+ * and preventing event listener accumulation.
+ *
+ * When culled nodes scroll back into view, the callback fires again and the
+ * component re-renders the full node content. The observer stores the last
+ * known height so placeholders can preserve scroll position.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * Preact integration is handled in the CulledNode component (prd-tree.ts).
+ */
+/** Configuration for creating a NodeCuller instance. */
+export interface NodeCullerOptions {
+    /** Buffer zone in pixels above/below viewport before culling (default: 200). */
+    bufferPx?: number;
+    /** Root element for IntersectionObserver (default: null = viewport). */
+    root?: Element | null;
+}
+/** Read-only diagnostic snapshot of culler state. */
+export interface NodeCullerState {
+    /** Number of elements currently being observed. */
+    trackedCount: number;
+    /** Whether the culler has been disposed. */
+    disposed: boolean;
+}
+/** Callback invoked when an element's visibility changes. */
+export type VisibilityCallback = (isVisible: boolean) => void;
+/**
+ * Shared IntersectionObserver-based node culler.
+ *
+ * Creates a single observer that efficiently tracks many elements.
+ * Each element gets a per-element callback that fires when its
+ * visibility (within the buffer zone) changes.
+ *
+ * Usage:
+ * ```ts
+ * const culler = new NodeCuller({ bufferPx: 200 });
+ *
+ * // Start observing an element
+ * const cleanup = culler.observe(element, (isVisible) => {
+ *   if (isVisible) renderFullContent();
+ *   else renderPlaceholder(culler.getLastHeight(element));
+ * });
+ *
+ * // Stop observing
+ * cleanup();
+ *
+ * // Tear down the entire culler
+ * culler.dispose();
+ * ```
+ */
+export declare class NodeCuller {
+    private observer;
+    private callbacks;
+    private heights;
+    private _disposed;
+    constructor(options?: NodeCullerOptions);
+    /**
+     * Start observing an element for visibility changes.
+     *
+     * The callback fires immediately when the observer first evaluates the
+     * element (typically within one frame) and again whenever it crosses
+     * the viewport buffer boundary.
+     *
+     * Returns a cleanup function that unobserves the element, removes
+     * the callback, and clears stored height data. Call this in your
+     * component's cleanup/unmount handler.
+     */
+    observe(element: Element, callback: VisibilityCallback): () => void;
+    /**
+     * Get the last known height of an observed element.
+     *
+     * Recorded from IntersectionObserverEntry.boundingClientRect when
+     * the element transitions to off-screen. Returns 0 if no height
+     * has been recorded yet.
+     */
+    getLastHeight(element: Element): number;
+    /**
+     * Dispose the observer and clear all tracked state.
+     *
+     * After disposal, observe() becomes a no-op. Safe to call multiple times.
+     */
+    dispose(): void;
+    /** Whether this culler has been disposed. */
+    get disposed(): boolean;
+    /** Get a diagnostic snapshot of current state. */
+    getState(): NodeCullerState;
+    private handleEntries;
+}

package/packages/web/dist/shared/node-culler.js

@@ -0,0 +1,133 @@
+/**
+ * Off-screen node culling engine using IntersectionObserver.
+ *
+ * Manages a single shared IntersectionObserver that tracks multiple tree
+ * node elements and invokes per-element callbacks when visibility changes.
+ * Nodes outside the viewport buffer are "culled" — their DOM children are
+ * removed and replaced with a height-preserving placeholder, freeing memory
+ * and preventing event listener accumulation.
+ *
+ * When culled nodes scroll back into view, the callback fires again and the
+ * component re-renders the full node content. The observer stores the last
+ * known height so placeholders can preserve scroll position.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * Preact integration is handled in the CulledNode component (prd-tree.ts).
+ */
+// ─── Default configuration ───────────────────────────────────────────────────
+const DEFAULT_BUFFER_PX = 200;
+// ─── NodeCuller ──────────────────────────────────────────────────────────────
+/**
+ * Shared IntersectionObserver-based node culler.
+ *
+ * Creates a single observer that efficiently tracks many elements.
+ * Each element gets a per-element callback that fires when its
+ * visibility (within the buffer zone) changes.
+ *
+ * Usage:
+ * ```ts
+ * const culler = new NodeCuller({ bufferPx: 200 });
+ *
+ * // Start observing an element
+ * const cleanup = culler.observe(element, (isVisible) => {
+ *   if (isVisible) renderFullContent();
+ *   else renderPlaceholder(culler.getLastHeight(element));
+ * });
+ *
+ * // Stop observing
+ * cleanup();
+ *
+ * // Tear down the entire culler
+ * culler.dispose();
+ * ```
+ */
+export class NodeCuller {
+    observer;
+    callbacks = new Map();
+    heights = new Map();
+    _disposed = false;
+    constructor(options = {}) {
+        const bufferPx = options.bufferPx ?? DEFAULT_BUFFER_PX;
+        this.observer = new IntersectionObserver((entries) => this.handleEntries(entries), {
+            root: options.root ?? null,
+            rootMargin: `${bufferPx}px 0px ${bufferPx}px 0px`,
+        });
+    }
+    /**
+     * Start observing an element for visibility changes.
+     *
+     * The callback fires immediately when the observer first evaluates the
+     * element (typically within one frame) and again whenever it crosses
+     * the viewport buffer boundary.
+     *
+     * Returns a cleanup function that unobserves the element, removes
+     * the callback, and clears stored height data. Call this in your
+     * component's cleanup/unmount handler.
+     */
+    observe(element, callback) {
+        if (this._disposed)
+            return () => { };
+        this.callbacks.set(element, callback);
+        this.observer.observe(element);
+        return () => {
+            this.callbacks.delete(element);
+            this.heights.delete(element);
+            if (!this._disposed) {
+                this.observer.unobserve(element);
+            }
+        };
+    }
+    /**
+     * Get the last known height of an observed element.
+     *
+     * Recorded from IntersectionObserverEntry.boundingClientRect when
+     * the element transitions to off-screen. Returns 0 if no height
+     * has been recorded yet.
+     */
+    getLastHeight(element) {
+        return this.heights.get(element) ?? 0;
+    }
+    /**
+     * Dispose the observer and clear all tracked state.
+     *
+     * After disposal, observe() becomes a no-op. Safe to call multiple times.
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this.observer.disconnect();
+        this.callbacks.clear();
+        this.heights.clear();
+    }
+    /** Whether this culler has been disposed. */
+    get disposed() {
+        return this._disposed;
+    }
+    /** Get a diagnostic snapshot of current state. */
+    getState() {
+        return {
+            trackedCount: this.callbacks.size,
+            disposed: this._disposed,
+        };
+    }
+    // ─── Private ─────────────────────────────────────────────────────────────
+    handleEntries(entries) {
+        for (const entry of entries) {
+            const callback = this.callbacks.get(entry.target);
+            if (!callback)
+                continue;
+            // Record height when transitioning to off-screen, so the placeholder
+            // can preserve scroll position. Use boundingClientRect which is
+            // already computed by the observer (no additional layout cost).
+            if (!entry.isIntersecting) {
+                const { height } = entry.boundingClientRect;
+                if (height > 0) {
+                    this.heights.set(entry.target, height);
+                }
+            }
+            callback(entry.isIntersecting);
+        }
+    }
+}
+//# sourceMappingURL=node-culler.js.map

package/packages/web/dist/shared/node-culler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-culler.js","sourceRoot":"","sources":["../../src/shared/node-culler.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/shared/request-dedup.d.ts

@@ -0,0 +1,43 @@
+/**
+ * In-flight request deduplication.
+ *
+ * Wraps an async function so that concurrent callers share a single in-flight
+ * promise instead of triggering duplicate API calls. When the underlying
+ * request completes (success or failure), tracking is cleared and the next
+ * call starts a fresh request.
+ *
+ * Typical use: prevent duplicate `fetchPRDData` calls when a WebSocket
+ * message arrives while a polling request is already in progress.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+/** A deduplicating wrapper around an async function. */
+export interface RequestDedup<T = void> {
+    /**
+     * Execute the wrapped function. If a request is already in-flight,
+     * returns the existing promise instead of starting a new one.
+     */
+    execute(): Promise<T>;
+    /** Whether a request is currently in-flight. */
+    isInFlight(): boolean;
+    /** Clear in-flight tracking state. Safe to call multiple times. */
+    dispose(): void;
+}
+/**
+ * Create a deduplicating wrapper for an async function.
+ *
+ * Usage:
+ * ```ts
+ * const dedupedFetch = createRequestDedup(() => fetch("/data/prd.json").then(r => r.json()));
+ *
+ * // These two calls share one underlying fetch:
+ * dedupedFetch.execute();  // starts the request
+ * dedupedFetch.execute();  // returns the same promise
+ *
+ * // After the request settles, the next call starts fresh:
+ * await dedupedFetch.execute();
+ * dedupedFetch.execute();  // new request
+ * ```
+ */
+export declare function createRequestDedup<T = void>(fn: () => Promise<T>): RequestDedup<T>;

package/packages/web/dist/shared/request-dedup.js

@@ -0,0 +1,55 @@
+/**
+ * In-flight request deduplication.
+ *
+ * Wraps an async function so that concurrent callers share a single in-flight
+ * promise instead of triggering duplicate API calls. When the underlying
+ * request completes (success or failure), tracking is cleared and the next
+ * call starts a fresh request.
+ *
+ * Typical use: prevent duplicate `fetchPRDData` calls when a WebSocket
+ * message arrives while a polling request is already in progress.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a deduplicating wrapper for an async function.
+ *
+ * Usage:
+ * ```ts
+ * const dedupedFetch = createRequestDedup(() => fetch("/data/prd.json").then(r => r.json()));
+ *
+ * // These two calls share one underlying fetch:
+ * dedupedFetch.execute();  // starts the request
+ * dedupedFetch.execute();  // returns the same promise
+ *
+ * // After the request settles, the next call starts fresh:
+ * await dedupedFetch.execute();
+ * dedupedFetch.execute();  // new request
+ * ```
+ */
+export function createRequestDedup(fn) {
+    let inflight = null;
+    function execute() {
+        if (inflight !== null) {
+            return inflight;
+        }
+        inflight = fn().then((value) => {
+            inflight = null;
+            return value;
+        }, (err) => {
+            inflight = null;
+            throw err;
+        });
+        return inflight;
+    }
+    function isInFlight() {
+        return inflight !== null;
+    }
+    function dispose() {
+        inflight = null;
+    }
+    return { execute, isInFlight, dispose };
+}
+//# sourceMappingURL=request-dedup.js.map

package/packages/web/dist/shared/request-dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-dedup.js","sourceRoot":"","sources":["../../src/shared/request-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmBH,gFAAgF;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAoB;IAEpB,IAAI,QAAQ,GAAsB,IAAI,CAAC;IAEvC,SAAS,OAAO;QACd,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,QAAQ,GAAG,EAAE,EAAE,CAAC,IAAI,CAClB,CAAC,KAAK,EAAE,EAAE;YACR,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,KAAK,CAAC;QACf,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;YACN,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,GAAG,CAAC;QACZ,CAAC,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,QAAQ,KAAK,IAAI,CAAC;IAC3B,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC"}

package/packages/web/dist/shared/view-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * View identifier type — framework-agnostic.
+ *
+ * Extracted to the shared layer so that modules with zero framework
+ * dependencies (e.g. crash-detector) can reference it without importing
+ * from the viewer layer.
+ */
+export type ViewId = "overview" | "graph" | "zones" | "files" | "routes" | "architecture" | "problems" | "suggestions" | "pr-markdown" | "rex-dashboard" | "prd" | "token-usage" | "validation" | "notion-config" | "integrations" | "hench-runs" | "hench-audit" | "hench-config" | "hench-templates" | "hench-optimization" | "feature-toggles";

package/packages/web/dist/shared/view-id.js

@@ -0,0 +1,9 @@
+/**
+ * View identifier type — framework-agnostic.
+ *
+ * Extracted to the shared layer so that modules with zero framework
+ * dependencies (e.g. crash-detector) can reference it without importing
+ * from the viewer layer.
+ */
+export {};
+//# sourceMappingURL=view-id.js.map

package/packages/web/dist/shared/view-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-id.js","sourceRoot":"","sources":["../../src/shared/view-id.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/packages/web/dist/viewer/api.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Viewer inbound API barrel — the sanctioned import surface for
+ * sibling zones (crash, route, performance, usage) that consume
+ * viewer-internal symbols.
+ *
+ * This is the inbound counterpart to external.ts (which concentrates
+ * viewer's outbound imports from schema/, shared/, and messaging/).
+ *
+ * Rules:
+ *   - Re-export only — no logic in this file
+ *   - Any symbol consumed by a file outside the web-viewer zone
+ *     should be re-exported here
+ *   - Sibling zones should import from "./api.js" rather than
+ *     reaching into types.js, route-state.js, or hooks/ directly
+ */
+export type { LoadedData, NavigateTo, FileDetail, ZoneDetail, GenericDetail, PRDDetail, DetailItem, } from "./types.js";
+export type { ViewId } from "./types.js";
+export type { ParsedRoute } from "./route-state.js";
+export { parseLegacyHashRoute, parsePathnameRoute, resolveLocationRoute, } from "./route-state.js";