@n-dx/web 0.1.0

package/dist/viewer/messaging/ws-pipeline.d.ts

@@ -0,0 +1,85 @@
+/**
+ * WebSocket message processing pipeline — composed throttle + coalescer.
+ *
+ * Both `usePRDWebSocket` and `useProjectStatus` build the same two-layer
+ * pipeline: per-type throttle → message coalescer. This module captures
+ * that pattern as a single factory, reducing the coupling surface from
+ * two individual messaging imports to one composed import.
+ *
+ * The pipeline handles:
+ *   1. **Throttle** — per-type trailing-edge debounce with independent timers.
+ *   2. **Coalescer** — batches throttled output into a single flush.
+ *
+ * Consumers configure which message types to throttle, their delays, and
+ * provide an `onMessage` (immediate/optimistic) and `onFlush` (batched
+ * reconciliation) callback.
+ *
+ * Standalone module with zero framework dependencies.
+ */
+import { type ParsedWSMessage, type CoalescedBatch } from "./message-coalescer.js";
+/** Configuration for the WebSocket message pipeline. */
+export interface WSPipelineConfig {
+    /**
+     * Called once per debounce window with the coalesced batch.
+     * Use this to trigger reconciliation fetches.
+     */
+    onFlush: (batch: CoalescedBatch) => void;
+    /**
+     * Called immediately for each incoming message (before throttling/batching).
+     * Use this for optimistic local state updates.
+     */
+    onMessage?: ((msg: ParsedWSMessage) => void) | undefined;
+    /**
+     * Default throttle debounce delay in milliseconds.
+     * Default: 250ms.
+     */
+    defaultDelayMs?: number | undefined;
+    /**
+     * Per-message-type delay overrides for the throttle layer.
+     */
+    delays?: Partial<Record<string, number>> | undefined;
+    /**
+     * Message types to throttle. Types not in this set pass through
+     * to the coalescer immediately (zero delay).
+     */
+    throttledTypes?: readonly string[] | undefined;
+    /**
+     * Maximum pending messages per type before force-flushing the throttle.
+     * Default: 20.
+     */
+    maxPendingPerType?: number | undefined;
+    /**
+     * Coalescer trailing-edge debounce window in milliseconds.
+     * Default: 150ms.
+     */
+    coalescerWindowMs?: number | undefined;
+}
+/** A composed WebSocket message pipeline (throttle → coalescer). */
+export interface WSPipeline {
+    /** Push a parsed WebSocket message into the pipeline. */
+    push(msg: ParsedWSMessage): void;
+    /** Force-flush both throttle and coalescer. */
+    flush(): void;
+    /** Dispose all timers and state. Safe to call multiple times. */
+    dispose(): void;
+}
+/**
+ * Create a WebSocket message processing pipeline.
+ *
+ * Usage:
+ * ```ts
+ * const pipeline = createWSPipeline({
+ *   onMessage: (msg) => applyOptimisticUpdate(msg),
+ *   onFlush: (batch) => {
+ *     if (batch.types.has("rex:prd-changed")) fetchPRDData();
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated"],
+ *   delays: { "rex:prd-changed": 300, "rex:item-updated": 200 },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   pipeline.push(JSON.parse(event.data));
+ * };
+ * ```
+ */
+export declare function createWSPipeline(config: WSPipelineConfig): WSPipeline;

package/dist/viewer/messaging/ws-pipeline.js

@@ -0,0 +1,68 @@
+/**
+ * WebSocket message processing pipeline — composed throttle + coalescer.
+ *
+ * Both `usePRDWebSocket` and `useProjectStatus` build the same two-layer
+ * pipeline: per-type throttle → message coalescer. This module captures
+ * that pattern as a single factory, reducing the coupling surface from
+ * two individual messaging imports to one composed import.
+ *
+ * The pipeline handles:
+ *   1. **Throttle** — per-type trailing-edge debounce with independent timers.
+ *   2. **Coalescer** — batches throttled output into a single flush.
+ *
+ * Consumers configure which message types to throttle, their delays, and
+ * provide an `onMessage` (immediate/optimistic) and `onFlush` (batched
+ * reconciliation) callback.
+ *
+ * Standalone module with zero framework dependencies.
+ */
+import { createMessageThrottle } from "./message-throttle.js";
+import { createMessageCoalescer } from "./message-coalescer.js";
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a WebSocket message processing pipeline.
+ *
+ * Usage:
+ * ```ts
+ * const pipeline = createWSPipeline({
+ *   onMessage: (msg) => applyOptimisticUpdate(msg),
+ *   onFlush: (batch) => {
+ *     if (batch.types.has("rex:prd-changed")) fetchPRDData();
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated"],
+ *   delays: { "rex:prd-changed": 300, "rex:item-updated": 200 },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   pipeline.push(JSON.parse(event.data));
+ * };
+ * ```
+ */
+export function createWSPipeline(config) {
+    const coalescer = createMessageCoalescer({
+        onMessage: config.onMessage,
+        onFlush: config.onFlush,
+        windowMs: config.coalescerWindowMs,
+    });
+    const throttle = createMessageThrottle({
+        onMessage: (msg) => coalescer.push(msg),
+        defaultDelayMs: config.defaultDelayMs,
+        delays: config.delays,
+        throttledTypes: config.throttledTypes,
+        maxPendingPerType: config.maxPendingPerType,
+    });
+    return {
+        push(msg) {
+            throttle.push(msg);
+        },
+        flush() {
+            throttle.flush();
+            coalescer.flush();
+        },
+        dispose() {
+            throttle.dispose();
+            coalescer.dispose();
+        },
+    };
+}
+//# sourceMappingURL=ws-pipeline.js.map

package/dist/viewer/messaging/ws-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-pipeline.js","sourceRoot":"","sources":["../../../src/viewer/messaging/ws-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,qBAAqB,EAAwB,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAoE,MAAM,wBAAwB,CAAC;AA0DlI,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,MAAM,SAAS,GAAqB,sBAAsB,CAAC;QACzD,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,iBAAiB;KACnC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAoB,qBAAqB,CAAC;QACtD,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;QACvC,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;KAC5C,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,CAAC,GAAoB;YACvB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,KAAK;YACH,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,SAAS,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;QAED,OAAO;YACL,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,SAAS,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/viewer/performance/dom-performance-monitor.d.ts

@@ -0,0 +1,157 @@
+/**
+ * DOM performance monitoring for tree components.
+ *
+ * Tracks active DOM node counts, render/update timing, and memory usage
+ * for tree operations. Provides before/after comparison data for measuring
+ * the impact of DOM optimizations (progressive loading, node culling, etc.).
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useDOMPerformanceMonitor`) is provided separately.
+ *
+ * @see ./memory-monitor.ts — complementary heap-level memory monitoring
+ * @see ./components/progressive-loader.ts — progressive load integration
+ */
+/** DOM node count snapshot at a point in time. */
+export interface DOMNodeSnapshot {
+    /** Total DOM node count within the observed container. */
+    totalNodes: number;
+    /** Number of element nodes (excludes text, comment nodes). */
+    elementNodes: number;
+    /** Number of tree item elements (role="treeitem"). */
+    treeItemCount: number;
+    /** Maximum nesting depth within the container. */
+    maxDepth: number;
+    /** ISO timestamp of when this snapshot was taken. */
+    timestamp: string;
+}
+/** Timing data for a single render or update operation. */
+export interface RenderTiming {
+    /** Label identifying the operation (e.g. "initial-render", "filter-change"). */
+    label: string;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** DOM node count after the operation completed. */
+    nodeCountAfter: number;
+    /** ISO timestamp of when the operation was measured. */
+    timestamp: string;
+}
+/** Before/after comparison for a tree operation. */
+export interface UpdateComparison {
+    /** Label identifying the operation. */
+    label: string;
+    /** DOM node count before the operation. */
+    nodesBefore: number;
+    /** DOM node count after the operation. */
+    nodesAfter: number;
+    /** Change in DOM node count (positive = growth, negative = reduction). */
+    nodeDelta: number;
+    /** Duration of the operation in milliseconds. */
+    durationMs: number;
+    /** Memory usage before (bytes, -1 if unavailable). */
+    memoryBefore: number;
+    /** Memory usage after (bytes, -1 if unavailable). */
+    memoryAfter: number;
+    /** Change in memory usage (bytes, -1 if unavailable). */
+    memoryDelta: number;
+    /** ISO timestamp of the operation. */
+    timestamp: string;
+}
+/** Aggregate performance summary computed from collected metrics. */
+export interface PerformanceSummary {
+    /** Average render time across all recorded timings. */
+    avgRenderMs: number;
+    /** Peak render time across all recorded timings. */
+    peakRenderMs: number;
+    /** Average DOM node count across snapshots. */
+    avgNodeCount: number;
+    /** Peak DOM node count across snapshots. */
+    peakNodeCount: number;
+    /** Total number of recorded render timings. */
+    renderCount: number;
+    /** Total number of recorded update comparisons. */
+    updateCount: number;
+    /** Total number of DOM snapshots taken. */
+    snapshotCount: number;
+}
+/** Configuration for the DOM performance monitor. */
+export interface DOMPerformanceConfig {
+    /** Polling interval in milliseconds for automatic snapshots (default: 2000). */
+    intervalMs: number;
+    /** Maximum number of snapshots to retain in history (default: 120). */
+    maxSnapshots: number;
+    /** Maximum number of render timings to retain (default: 200). */
+    maxTimings: number;
+    /** Maximum number of update comparisons to retain (default: 100). */
+    maxComparisons: number;
+}
+/** Callback invoked when a new DOM snapshot is taken. */
+export type DOMSnapshotHandler = (snapshot: DOMNodeSnapshot) => void;
+/**
+ * Count all DOM nodes within a container element.
+ *
+ * Walks the subtree using a non-recursive stack to avoid
+ * stack overflow on very deep trees. Returns counts for
+ * total nodes, element-only nodes, and tree items.
+ */
+export declare function countDOMNodes(container: Element): DOMNodeSnapshot;
+/** Read current JS heap usage in bytes, or -1 if unavailable. */
+export declare function readHeapUsage(): number;
+/** Format a duration in milliseconds (e.g. "12.3 ms"). */
+export declare function formatDuration(ms: number): string;
+/** Format a node count with thousands separator. */
+export declare function formatNodeCount(count: number): string;
+/** Format a delta with sign prefix (e.g. "+42" or "−18"). */
+export declare function formatDelta(delta: number): string;
+/**
+ * Record a render timing measurement.
+ *
+ * Call this after a render completes with the operation label,
+ * elapsed time, and current DOM node count.
+ */
+export declare function recordRender(label: string, durationMs: number, nodeCountAfter: number): void;
+/**
+ * Record a before/after update comparison.
+ *
+ * Call this after a tree operation completes to capture the
+ * DOM node delta, timing, and memory change.
+ */
+export declare function recordUpdate(label: string, durationMs: number, nodesBefore: number, nodesAfter: number, memoryBefore?: number, memoryAfter?: number): void;
+/**
+ * Measure a tree operation end-to-end.
+ *
+ * Captures DOM node count and memory before/after executing `fn`,
+ * records the comparison, and returns the function's result.
+ *
+ * The container must be set via `startDOMPerformanceMonitor` or
+ * `setObservedContainer` before calling this function.
+ */
+export declare function measureOperation<T>(label: string, fn: () => T): T;
+/** Take a DOM performance snapshot of the observed container. */
+export declare function takeDOMSnapshot(): DOMNodeSnapshot | null;
+/** Compute an aggregate performance summary from collected metrics. */
+export declare function computeSummary(): PerformanceSummary;
+/** Subscribe to every new DOM snapshot. Returns an unsubscribe function. */
+export declare function onDOMSnapshot(listener: DOMSnapshotHandler): () => void;
+/** Set the container element to observe for DOM metrics. */
+export declare function setObservedContainer(container: Element | null): void;
+/**
+ * Start the DOM performance monitor.
+ *
+ * Begins periodic DOM node counting on the specified container.
+ * Safe to call multiple times — restarts with new config if already running.
+ */
+export declare function startDOMPerformanceMonitor(container: Element, overrides?: Partial<DOMPerformanceConfig>): void;
+/** Stop the DOM performance monitor and clean up polling. */
+export declare function stopDOMPerformanceMonitor(): void;
+/** Get the most recent DOM snapshot, or null if not yet taken. */
+export declare function getLatestDOMSnapshot(): DOMNodeSnapshot | null;
+/** Get the DOM snapshot history (bounded ring buffer). */
+export declare function getDOMSnapshotHistory(): readonly DOMNodeSnapshot[];
+/** Get all recorded render timings (bounded ring buffer). */
+export declare function getRenderTimings(): readonly RenderTiming[];
+/** Get all recorded update comparisons (bounded ring buffer). */
+export declare function getUpdateComparisons(): readonly UpdateComparison[];
+/** Get the currently observed container element, or null. */
+export declare function getObservedContainer(): Element | null;
+/** Reset all module state (for testing). */
+export declare function resetDOMPerformanceMonitor(): void;

package/dist/viewer/performance/dom-performance-monitor.js

@@ -0,0 +1,341 @@
+/**
+ * DOM performance monitoring for tree components.
+ *
+ * Tracks active DOM node counts, render/update timing, and memory usage
+ * for tree operations. Provides before/after comparison data for measuring
+ * the impact of DOM optimizations (progressive loading, node culling, etc.).
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useDOMPerformanceMonitor`) is provided separately.
+ *
+ * @see ./memory-monitor.ts — complementary heap-level memory monitoring
+ * @see ./components/progressive-loader.ts — progressive load integration
+ */
+import { registerPollingSource, } from "../polling/index.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_INTERVAL_MS = 2000;
+const DEFAULT_MAX_SNAPSHOTS = 120;
+const DEFAULT_MAX_TIMINGS = 200;
+const DEFAULT_MAX_COMPARISONS = 100;
+/** Key used to register with the centralized polling state manager. */
+const POLLING_STATE_KEY = "dom-performance-monitor";
+// ─── Module state ────────────────────────────────────────────────────────────
+let config = {
+    intervalMs: DEFAULT_INTERVAL_MS,
+    maxSnapshots: DEFAULT_MAX_SNAPSHOTS,
+    maxTimings: DEFAULT_MAX_TIMINGS,
+    maxComparisons: DEFAULT_MAX_COMPARISONS,
+};
+let pollTimer = null;
+let stateUnsub = null;
+let observedContainer = null;
+let latestSnapshot = null;
+let snapshotHistory = [];
+let renderTimings = [];
+let updateComparisons = [];
+let snapshotListeners = [];
+// ─── DOM counting ────────────────────────────────────────────────────────────
+/**
+ * Count all DOM nodes within a container element.
+ *
+ * Walks the subtree using a non-recursive stack to avoid
+ * stack overflow on very deep trees. Returns counts for
+ * total nodes, element-only nodes, and tree items.
+ */
+export function countDOMNodes(container) {
+    let totalNodes = 0;
+    let elementNodes = 0;
+    let treeItemCount = 0;
+    let maxDepth = 0;
+    // Non-recursive DFS using an explicit stack: [node, depth]
+    const stack = [[container, 0]];
+    while (stack.length > 0) {
+        const [node, depth] = stack.pop();
+        totalNodes++;
+        if (depth > maxDepth) {
+            maxDepth = depth;
+        }
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            elementNodes++;
+            const el = node;
+            if (el.getAttribute("role") === "treeitem") {
+                treeItemCount++;
+            }
+        }
+        // Push children in reverse so the first child is processed first
+        const children = node.childNodes;
+        for (let i = children.length - 1; i >= 0; i--) {
+            stack.push([children[i], depth + 1]);
+        }
+    }
+    return {
+        totalNodes,
+        elementNodes,
+        treeItemCount,
+        maxDepth,
+        timestamp: new Date().toISOString(),
+    };
+}
+// ─── Memory reading ──────────────────────────────────────────────────────────
+/** Read current JS heap usage in bytes, or -1 if unavailable. */
+export function readHeapUsage() {
+    const perf = performance;
+    if (perf.memory && typeof perf.memory.usedJSHeapSize === "number") {
+        return perf.memory.usedJSHeapSize;
+    }
+    return -1;
+}
+// ─── Formatting ──────────────────────────────────────────────────────────────
+/** Format a duration in milliseconds (e.g. "12.3 ms"). */
+export function formatDuration(ms) {
+    if (ms < 0)
+        return "N/A";
+    if (ms < 1)
+        return `${(ms * 1000).toFixed(0)} µs`;
+    if (ms < 1000)
+        return `${ms.toFixed(1)} ms`;
+    return `${(ms / 1000).toFixed(2)} s`;
+}
+/** Format a node count with thousands separator. */
+export function formatNodeCount(count) {
+    if (count < 0)
+        return "N/A";
+    return count.toLocaleString("en-US");
+}
+/** Format a delta with sign prefix (e.g. "+42" or "−18"). */
+export function formatDelta(delta) {
+    if (delta > 0)
+        return `+${delta.toLocaleString("en-US")}`;
+    if (delta < 0)
+        return `−${Math.abs(delta).toLocaleString("en-US")}`;
+    return "0";
+}
+// ─── Recording operations ────────────────────────────────────────────────────
+/**
+ * Record a render timing measurement.
+ *
+ * Call this after a render completes with the operation label,
+ * elapsed time, and current DOM node count.
+ */
+export function recordRender(label, durationMs, nodeCountAfter) {
+    const timing = {
+        label,
+        durationMs,
+        nodeCountAfter,
+        timestamp: new Date().toISOString(),
+    };
+    renderTimings.push(timing);
+    if (renderTimings.length > config.maxTimings) {
+        renderTimings = renderTimings.slice(-config.maxTimings);
+    }
+}
+/**
+ * Record a before/after update comparison.
+ *
+ * Call this after a tree operation completes to capture the
+ * DOM node delta, timing, and memory change.
+ */
+export function recordUpdate(label, durationMs, nodesBefore, nodesAfter, memoryBefore = -1, memoryAfter = -1) {
+    const comparison = {
+        label,
+        nodesBefore,
+        nodesAfter,
+        nodeDelta: nodesAfter - nodesBefore,
+        durationMs,
+        memoryBefore,
+        memoryAfter,
+        memoryDelta: memoryBefore >= 0 && memoryAfter >= 0
+            ? memoryAfter - memoryBefore
+            : -1,
+        timestamp: new Date().toISOString(),
+    };
+    updateComparisons.push(comparison);
+    if (updateComparisons.length > config.maxComparisons) {
+        updateComparisons = updateComparisons.slice(-config.maxComparisons);
+    }
+}
+/**
+ * Measure a tree operation end-to-end.
+ *
+ * Captures DOM node count and memory before/after executing `fn`,
+ * records the comparison, and returns the function's result.
+ *
+ * The container must be set via `startDOMPerformanceMonitor` or
+ * `setObservedContainer` before calling this function.
+ */
+export function measureOperation(label, fn) {
+    const container = observedContainer;
+    const memBefore = readHeapUsage();
+    const nodesBefore = container ? countDOMNodes(container).totalNodes : -1;
+    const start = performance.now();
+    const result = fn();
+    const elapsed = performance.now() - start;
+    const nodesAfter = container ? countDOMNodes(container).totalNodes : -1;
+    const memAfter = readHeapUsage();
+    if (nodesBefore >= 0 && nodesAfter >= 0) {
+        recordUpdate(label, elapsed, nodesBefore, nodesAfter, memBefore, memAfter);
+    }
+    recordRender(label, elapsed, nodesAfter >= 0 ? nodesAfter : 0);
+    return result;
+}
+// ─── Snapshot ────────────────────────────────────────────────────────────────
+/** Take a DOM performance snapshot of the observed container. */
+export function takeDOMSnapshot() {
+    if (!observedContainer)
+        return null;
+    return countDOMNodes(observedContainer);
+}
+// ─── Summary ─────────────────────────────────────────────────────────────────
+/** Compute an aggregate performance summary from collected metrics. */
+export function computeSummary() {
+    const timings = renderTimings;
+    const snapshots = snapshotHistory;
+    let avgRenderMs = 0;
+    let peakRenderMs = 0;
+    if (timings.length > 0) {
+        let sum = 0;
+        for (const t of timings) {
+            sum += t.durationMs;
+            if (t.durationMs > peakRenderMs)
+                peakRenderMs = t.durationMs;
+        }
+        avgRenderMs = sum / timings.length;
+    }
+    let avgNodeCount = 0;
+    let peakNodeCount = 0;
+    if (snapshots.length > 0) {
+        let sum = 0;
+        for (const s of snapshots) {
+            sum += s.totalNodes;
+            if (s.totalNodes > peakNodeCount)
+                peakNodeCount = s.totalNodes;
+        }
+        avgNodeCount = sum / snapshots.length;
+    }
+    return {
+        avgRenderMs,
+        peakRenderMs,
+        avgNodeCount,
+        peakNodeCount,
+        renderCount: timings.length,
+        updateCount: updateComparisons.length,
+        snapshotCount: snapshots.length,
+    };
+}
+// ─── Monitor lifecycle ───────────────────────────────────────────────────────
+/** Subscribe to every new DOM snapshot. Returns an unsubscribe function. */
+export function onDOMSnapshot(listener) {
+    snapshotListeners.push(listener);
+    return () => {
+        snapshotListeners = snapshotListeners.filter((l) => l !== listener);
+    };
+}
+function notifyListeners(snapshot) {
+    for (const listener of snapshotListeners) {
+        listener(snapshot);
+    }
+}
+function poll() {
+    const snapshot = takeDOMSnapshot();
+    if (!snapshot)
+        return;
+    latestSnapshot = snapshot;
+    snapshotHistory.push(snapshot);
+    if (snapshotHistory.length > config.maxSnapshots) {
+        snapshotHistory = snapshotHistory.slice(-config.maxSnapshots);
+    }
+    notifyListeners(snapshot);
+}
+/** Set the container element to observe for DOM metrics. */
+export function setObservedContainer(container) {
+    observedContainer = container;
+}
+/**
+ * Start the DOM performance monitor.
+ *
+ * Begins periodic DOM node counting on the specified container.
+ * Safe to call multiple times — restarts with new config if already running.
+ */
+export function startDOMPerformanceMonitor(container, overrides = {}) {
+    stopDOMPerformanceMonitor();
+    observedContainer = container;
+    config = {
+        intervalMs: overrides.intervalMs ?? DEFAULT_INTERVAL_MS,
+        maxSnapshots: overrides.maxSnapshots ?? DEFAULT_MAX_SNAPSHOTS,
+        maxTimings: overrides.maxTimings ?? DEFAULT_MAX_TIMINGS,
+        maxComparisons: overrides.maxComparisons ?? DEFAULT_MAX_COMPARISONS,
+    };
+    // Take an immediate snapshot on start.
+    poll();
+    pollTimer = setInterval(poll, config.intervalMs);
+    // Register with centralized polling state for coordinated lifecycle.
+    stateUnsub = registerPollingSource(POLLING_STATE_KEY, {
+        suspend: () => stopPollTimer(),
+        resume: () => {
+            if (pollTimer === null && observedContainer) {
+                pollTimer = setInterval(poll, config.intervalMs);
+            }
+        },
+        dispose: () => {
+            stopPollTimer();
+            stateUnsub = null;
+        },
+        getStatus: () => (pollTimer !== null ? "active" : "idle"),
+    });
+}
+/** Stop the poll interval timer without touching polling-state registration. */
+function stopPollTimer() {
+    if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+}
+/** Stop the DOM performance monitor and clean up polling. */
+export function stopDOMPerformanceMonitor() {
+    stopPollTimer();
+    // Deregister from centralized polling state. Nullify first to
+    // prevent re-entrant dispose.
+    if (stateUnsub) {
+        const unsub = stateUnsub;
+        stateUnsub = null;
+        unsub();
+    }
+}
+/** Get the most recent DOM snapshot, or null if not yet taken. */
+export function getLatestDOMSnapshot() {
+    return latestSnapshot;
+}
+/** Get the DOM snapshot history (bounded ring buffer). */
+export function getDOMSnapshotHistory() {
+    return snapshotHistory;
+}
+/** Get all recorded render timings (bounded ring buffer). */
+export function getRenderTimings() {
+    return renderTimings;
+}
+/** Get all recorded update comparisons (bounded ring buffer). */
+export function getUpdateComparisons() {
+    return updateComparisons;
+}
+/** Get the currently observed container element, or null. */
+export function getObservedContainer() {
+    return observedContainer;
+}
+/** Reset all module state (for testing). */
+export function resetDOMPerformanceMonitor() {
+    stopDOMPerformanceMonitor();
+    observedContainer = null;
+    stateUnsub = null;
+    latestSnapshot = null;
+    snapshotHistory = [];
+    renderTimings = [];
+    updateComparisons = [];
+    snapshotListeners = [];
+    config = {
+        intervalMs: DEFAULT_INTERVAL_MS,
+        maxSnapshots: DEFAULT_MAX_SNAPSHOTS,
+        maxTimings: DEFAULT_MAX_TIMINGS,
+        maxComparisons: DEFAULT_MAX_COMPARISONS,
+    };
+}
+//# sourceMappingURL=dom-performance-monitor.js.map

package/dist/viewer/performance/dom-performance-monitor.js.map

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