@n-dx/core 0.1.0

package/packages/web/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/packages/web/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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"}

package/packages/web/dist/viewer/performance/dom-update-gate.d.ts

@@ -0,0 +1,122 @@
+/**
+ * DOM update gate — prevents state updates and re-renders during tab inactivity.
+ *
+ * Wraps an UpdateBatcher to intercept `schedule()` calls when the tab is hidden.
+ * Instead of creating RAF callbacks in background tabs (which still fire at
+ * reduced frequency, wasting CPU and triggering unnecessary re-renders), the
+ * gate queues all pending updaters per-setter and replays them in a single
+ * batch when the tab becomes visible again.
+ *
+ * Pipeline position:
+ *
+ *   ... → coalescer.onMessage → **dom-update-gate**.schedule() → batcher → RAF → render
+ *
+ * When visible:  schedule() → batcher.schedule() (normal flow)
+ * When hidden:   schedule() → internal queue (no RAF, no render)
+ * On resume:     internal queue → batcher → flush → single render
+ *
+ * Lifecycle:
+ *
+ *   Tab goes hidden:
+ *     1. Flush the underlying batcher (apply any pending updates immediately
+ *        so state is consistent up to the point of suspension).
+ *     2. Switch to queuing mode — all future schedule() calls are captured
+ *        in an internal per-setter queue.
+ *
+ *   Tab becomes visible (after resume debounce):
+ *     1. Replay all queued updaters through the batcher (preserving
+ *        per-setter composition order).
+ *     2. Immediately flush the batcher to apply them in one RAF frame.
+ *     3. Call onResume if any updates were deferred.
+ *
+ * This module complements the response-buffer-gate (which drops WebSocket
+ * messages during suspension) by also gating the DOM update pathway. Without
+ * this, polling callbacks, optimistic updates, or any late-arriving schedule()
+ * calls would still trigger RAF and re-renders in background tabs.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+import type { UpdateBatcher } from "./update-batcher.js";
+/** Configuration for the DOM update gate. */
+export interface DomUpdateGateConfig {
+    /**
+     * The underlying batcher to delegate to when the gate is open.
+     * The gate does NOT own this batcher — the caller is responsible
+     * for disposal of the batcher separately.
+     */
+    batcher: UpdateBatcher;
+    /**
+     * Called when the gate re-opens after suspension, but only if updates
+     * were deferred while the gate was closed. Use this to trigger any
+     * additional reconciliation work needed after deferred updates are applied.
+     *
+     * Optional — most consumers rely on the deferred updates themselves.
+     */
+    onResume?: (() => void) | undefined;
+    /**
+     * Debounce delay in milliseconds before re-opening the gate after the
+     * tab becomes visible. Prevents thrashing on rapid tab switches.
+     * Default: 100ms (matches polling-manager and buffer-gate debounce).
+     */
+    resumeDebounceMs?: number | undefined;
+}
+/** Read-only snapshot of the gate's current state. */
+export interface DomUpdateGateSnapshot {
+    /** Whether the gate is currently open (delegating to the batcher). */
+    readonly isOpen: boolean;
+    /** Number of updaters queued during the current or most recent suspension. */
+    readonly queuedCount: number;
+    /** Total updaters deferred across all suspensions since creation. */
+    readonly totalDeferred: number;
+    /** Number of times the gate has been suspended. */
+    readonly suspensionCount: number;
+}
+/** A DOM update gate instance. Extends UpdateBatcher with visibility gating. */
+export interface DomUpdateGate {
+    /**
+     * Schedule a state update.
+     *
+     * When the gate is open (tab visible): delegates to the underlying batcher.
+     * When the gate is closed (tab hidden): queues the updater internally.
+     * Multiple updates for the same setter are composed in order on replay.
+     */
+    schedule<T>(setter: (updater: (prev: T) => T) => void, updater: (prev: T) => T): void;
+    /**
+     * Force-flush all pending updates synchronously.
+     *
+     * When the gate is open: flushes the underlying batcher.
+     * When the gate is closed: composes queued updaters per-setter and applies
+     * them directly (bypassing the batcher), then flushes the batcher.
+     */
+    flush(): void;
+    /** Whether updates are pending (in the batcher or in the deferred queue). */
+    hasPending(): boolean;
+    /** Whether the gate is currently open (tab visible, accepting updates). */
+    isOpen(): boolean;
+    /** Get a snapshot of the gate's current state. */
+    getSnapshot(): DomUpdateGateSnapshot;
+    /** Dispose: unsubscribe from visibility events, clear queue, clear timers. */
+    dispose(): void;
+}
+/**
+ * Create a new DOM update gate.
+ *
+ * Usage:
+ * ```ts
+ * const batcher = createUpdateBatcher();
+ * const gate = createDomUpdateGate({ batcher });
+ *
+ * // Use gate.schedule() instead of batcher.schedule()
+ * coalescer.onMessage = (msg) => {
+ *   if (msg.type === "rex:item-updated") {
+ *     gate.schedule(setData, (prev) => applyItemUpdate(prev, msg));
+ *   }
+ * };
+ *
+ * // On component unmount:
+ * gate.dispose();
+ * batcher.dispose();
+ * ```
+ */
+export declare function createDomUpdateGate(config: DomUpdateGateConfig): DomUpdateGate;