@n-dx/web 0.1.0

package/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;

package/dist/viewer/performance/dom-update-gate.js

@@ -0,0 +1,229 @@
+/**
+ * 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 { onVisibilityChange, isTabVisible, } from "../polling/index.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_RESUME_DEBOUNCE_MS = 100;
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * 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 function createDomUpdateGate(config) {
+    const batcher = config.batcher;
+    const onResume = config.onResume;
+    const resumeDebounceMs = config.resumeDebounceMs ?? DEFAULT_RESUME_DEBOUNCE_MS;
+    let open = true;
+    let deferredQueue = new Map();
+    let queuedCount = 0;
+    let totalDeferred = 0;
+    let suspensionCount = 0;
+    let resumeTimer = null;
+    let disposed = false;
+    // ─── Internal helpers ─────────────────────────────────────────────
+    function clearResumeTimer() {
+        if (resumeTimer !== null) {
+            clearTimeout(resumeTimer);
+            resumeTimer = null;
+        }
+    }
+    /**
+     * Compose all queued updaters for a single setter into one function call.
+     * Each updater receives the output of the previous — identical to
+     * sequential application, just like the update-batcher's composition.
+     */
+    function composeUpdaters(updaters) {
+        return (prev) => {
+            let current = prev;
+            for (const updater of updaters) {
+                current = updater(current);
+            }
+            return current;
+        };
+    }
+    /**
+     * Replay all queued updates through the batcher, then flush.
+     * This ensures all deferred updates are applied in a single synchronous
+     * block, producing exactly one re-render per setter.
+     */
+    function replayQueue() {
+        const entries = deferredQueue;
+        const hadDeferred = entries.size > 0;
+        deferredQueue = new Map();
+        queuedCount = 0;
+        // Replay each setter's accumulated updaters through the batcher.
+        for (const entry of entries.values()) {
+            batcher.schedule(entry.setter, composeUpdaters(entry.updaters));
+        }
+        // Flush immediately to apply in one synchronous block.
+        if (hadDeferred) {
+            batcher.flush();
+        }
+        // Notify consumer that deferred updates were applied.
+        if (hadDeferred && onResume) {
+            try {
+                onResume();
+            }
+            catch {
+                // Swallow errors from the resume callback.
+            }
+        }
+    }
+    /** Close the gate: flush the batcher and switch to queuing mode. */
+    function suspend() {
+        if (!open)
+            return;
+        open = false;
+        queuedCount = 0;
+        suspensionCount++;
+        // Flush the underlying batcher so any pending updates are applied
+        // before we go into suspension. This ensures state is consistent
+        // up to the point of the tab going hidden.
+        batcher.flush();
+    }
+    /** Re-open the gate and replay any deferred updates. */
+    function resume() {
+        if (open)
+            return;
+        open = true;
+        replayQueue();
+    }
+    function handleVisibilityChange(snapshot) {
+        if (disposed)
+            return;
+        if (snapshot.isVisible) {
+            // Tab became visible — resume with debounce to prevent thrash.
+            clearResumeTimer();
+            resumeTimer = setTimeout(() => {
+                resumeTimer = null;
+                resume();
+            }, resumeDebounceMs);
+        }
+        else {
+            // Tab became hidden — suspend immediately.
+            clearResumeTimer();
+            suspend();
+        }
+    }
+    // Subscribe to tab visibility changes.
+    const unsubVisibility = onVisibilityChange(handleVisibilityChange);
+    // If the tab is currently hidden, suspend immediately.
+    if (!isTabVisible()) {
+        suspend();
+    }
+    // ─── Public methods ─────────────────────────────────────────────────
+    function schedule(setter, updater) {
+        if (disposed)
+            return;
+        if (open) {
+            // Gate is open — delegate to the batcher (normal flow).
+            batcher.schedule(setter, updater);
+            return;
+        }
+        // Gate is closed — queue the updater for replay on resume.
+        const key = setter;
+        let entry = deferredQueue.get(key);
+        if (!entry) {
+            entry = { setter: key, updaters: [] };
+            deferredQueue.set(key, entry);
+        }
+        entry.updaters.push(updater);
+        queuedCount++;
+        totalDeferred++;
+    }
+    function flush() {
+        if (disposed)
+            return;
+        if (open) {
+            // Gate is open — just flush the batcher.
+            batcher.flush();
+            return;
+        }
+        // Gate is closed — compose queued updaters per-setter and apply
+        // them directly, bypassing the batcher (since we don't want to
+        // schedule RAF in a background tab).
+        const entries = deferredQueue;
+        deferredQueue = new Map();
+        queuedCount = 0;
+        for (const entry of entries.values()) {
+            entry.setter(composeUpdaters(entry.updaters));
+        }
+        // Also flush the batcher in case it has anything pending.
+        batcher.flush();
+    }
+    function hasPending() {
+        return deferredQueue.size > 0 || batcher.hasPending();
+    }
+    function isOpenFn() {
+        return open;
+    }
+    function getSnapshot() {
+        return {
+            isOpen: open,
+            queuedCount,
+            totalDeferred,
+            suspensionCount,
+        };
+    }
+    function dispose() {
+        disposed = true;
+        clearResumeTimer();
+        unsubVisibility();
+        deferredQueue = new Map();
+        queuedCount = 0;
+    }
+    return { schedule, flush, hasPending, isOpen: isOpenFn, getSnapshot, dispose };
+}
+//# sourceMappingURL=dom-update-gate.js.map

package/dist/viewer/performance/dom-update-gate.js.map

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

package/dist/viewer/performance/graceful-degradation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Graceful degradation manager for memory-constrained environments.
+ *
+ * Subscribes to the memory monitor and progressively disables non-essential
+ * features as memory usage rises through threshold levels. Features are
+ * re-enabled automatically when memory pressure subsides.
+ *
+ * Degradation tiers (cumulative — each tier includes all previous restrictions):
+ *
+ *   normal   → All features active.
+ *   elevated → Pause data polling, skip deferred module loading.
+ *   warning  → Disable graph rendering & CSS animations.
+ *   critical → Disable detail panel, reduce to minimal UI.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useGracefulDegradation`) is provided separately.
+ */
+import type { MemoryLevel } from "./memory-monitor.js";
+/**
+ * Features that can be individually degraded.
+ *
+ * Each feature maps to a user-facing capability that consumes significant
+ * memory or CPU. The degradation manager disables features from the bottom
+ * of the list upwards as memory pressure increases.
+ */
+export type DegradableFeature = "autoRefresh" | "deferredLoading" | "graphRendering" | "animations" | "detailPanel";
+/** Read-only snapshot of the current degradation state. */
+export interface DegradationState {
+    /** Current degradation tier, mirrors the memory level. */
+    readonly tier: MemoryLevel;
+    /** Set of features currently disabled due to memory pressure. */
+    readonly disabledFeatures: ReadonlySet<DegradableFeature>;
+    /** Whether *any* degradation is active (tier !== "normal"). */
+    readonly isDegraded: boolean;
+    /** Human-readable summary of what's disabled and why. */
+    readonly summary: string;
+}
+/** Callback invoked when the degradation state changes. */
+export type DegradationChangeHandler = (state: DegradationState, previousTier: MemoryLevel) => void;
+/** Configuration for the degradation manager. */
+export interface DegradationConfig {
+    /** Called when the degradation tier changes. */
+    onChange: DegradationChangeHandler | null;
+}
+/**
+ * Compute the disabled feature set for a given memory level.
+ * Exported for testing.
+ */
+export declare function featuresForTier(tier: MemoryLevel): Set<DegradableFeature>;
+/**
+ * Get the human-readable summary for a given memory level.
+ * Exported for testing.
+ */
+export declare function summaryForTier(tier: MemoryLevel): string;
+/**
+ * Start the degradation manager. Subscribes to the memory monitor and
+ * immediately evaluates the current memory level.
+ *
+ * Safe to call multiple times — restarts with new config.
+ */
+export declare function startDegradation(overrides?: Partial<DegradationConfig>): void;
+/** Stop the degradation manager and clean up subscriptions. */
+export declare function stopDegradation(): void;
+/** Subscribe to degradation state changes. Returns an unsubscribe function. */
+export declare function onDegradationChange(listener: (state: DegradationState) => void): () => void;
+/** Check whether a specific feature is currently disabled. */
+export declare function isFeatureDisabled(feature: DegradableFeature): boolean;
+/** Get the current degradation state. */
+export declare function getDegradationState(): DegradationState;
+/** Get the current degradation tier. */
+export declare function getCurrentTier(): MemoryLevel;
+/** Reset all module state (for testing). */
+export declare function resetDegradation(): void;

package/dist/viewer/performance/graceful-degradation.js

@@ -0,0 +1,152 @@
+/**
+ * Graceful degradation manager for memory-constrained environments.
+ *
+ * Subscribes to the memory monitor and progressively disables non-essential
+ * features as memory usage rises through threshold levels. Features are
+ * re-enabled automatically when memory pressure subsides.
+ *
+ * Degradation tiers (cumulative — each tier includes all previous restrictions):
+ *
+ *   normal   → All features active.
+ *   elevated → Pause data polling, skip deferred module loading.
+ *   warning  → Disable graph rendering & CSS animations.
+ *   critical → Disable detail panel, reduce to minimal UI.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useGracefulDegradation`) is provided separately.
+ */
+import { onSnapshot, getLatestSnapshot } from "./memory-monitor.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * Which features to disable at each memory level.
+ *
+ * Degradation is cumulative: "warning" includes everything from "elevated"
+ * plus its own additions.
+ */
+const TIER_FEATURES = {
+    normal: [],
+    elevated: ["autoRefresh", "deferredLoading"],
+    warning: ["autoRefresh", "deferredLoading", "graphRendering", "animations"],
+    critical: ["autoRefresh", "deferredLoading", "graphRendering", "animations", "detailPanel"],
+};
+const TIER_SUMMARIES = {
+    normal: "",
+    elevated: "Memory usage is elevated. Auto-refresh and background data loading have been paused to conserve memory.",
+    warning: "High memory usage detected. The graph view and animations have been disabled. Close unused tabs or refresh the page.",
+    critical: "Critical memory pressure. Most features are disabled to prevent a crash. Refresh the page to restore full functionality.",
+};
+const SEVERITY_ORDER = {
+    normal: 0,
+    elevated: 1,
+    warning: 2,
+    critical: 3,
+};
+// ─── Module state ────────────────────────────────────────────────────────────
+let currentTier = "normal";
+let disabledFeatures = new Set();
+let config = { onChange: null };
+let unsubscribeMonitor = null;
+let listeners = [];
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Build the DegradationState snapshot from current module state. */
+function buildState() {
+    return {
+        tier: currentTier,
+        disabledFeatures: new Set(disabledFeatures),
+        isDegraded: currentTier !== "normal",
+        summary: TIER_SUMMARIES[currentTier],
+    };
+}
+function notifyListeners(state) {
+    for (const listener of listeners) {
+        try {
+            listener(state);
+        }
+        catch (err) {
+            console.error("[graceful-degradation] listener error:", err);
+        }
+    }
+}
+/**
+ * Compute the disabled feature set for a given memory level.
+ * Exported for testing.
+ */
+export function featuresForTier(tier) {
+    return new Set(TIER_FEATURES[tier]);
+}
+/**
+ * Get the human-readable summary for a given memory level.
+ * Exported for testing.
+ */
+export function summaryForTier(tier) {
+    return TIER_SUMMARIES[tier];
+}
+// ─── Snapshot handler ────────────────────────────────────────────────────────
+function handleMemorySnapshot(snapshot) {
+    const newTier = snapshot.level;
+    if (newTier === currentTier)
+        return;
+    const previousTier = currentTier;
+    currentTier = newTier;
+    disabledFeatures = featuresForTier(newTier);
+    const state = buildState();
+    if (config.onChange) {
+        config.onChange(state, previousTier);
+    }
+    notifyListeners(state);
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Start the degradation manager. Subscribes to the memory monitor and
+ * immediately evaluates the current memory level.
+ *
+ * Safe to call multiple times — restarts with new config.
+ */
+export function startDegradation(overrides = {}) {
+    stopDegradation();
+    config = {
+        onChange: overrides.onChange ?? null,
+    };
+    // Subscribe to ongoing memory snapshots.
+    unsubscribeMonitor = onSnapshot(handleMemorySnapshot);
+    // Evaluate current state immediately from the latest snapshot.
+    const latest = getLatestSnapshot();
+    if (latest) {
+        handleMemorySnapshot(latest);
+    }
+}
+/** Stop the degradation manager and clean up subscriptions. */
+export function stopDegradation() {
+    if (unsubscribeMonitor) {
+        unsubscribeMonitor();
+        unsubscribeMonitor = null;
+    }
+}
+/** Subscribe to degradation state changes. Returns an unsubscribe function. */
+export function onDegradationChange(listener) {
+    listeners.push(listener);
+    return () => {
+        listeners = listeners.filter((l) => l !== listener);
+    };
+}
+/** Check whether a specific feature is currently disabled. */
+export function isFeatureDisabled(feature) {
+    return disabledFeatures.has(feature);
+}
+/** Get the current degradation state. */
+export function getDegradationState() {
+    return buildState();
+}
+/** Get the current degradation tier. */
+export function getCurrentTier() {
+    return currentTier;
+}
+/** Reset all module state (for testing). */
+export function resetDegradation() {
+    stopDegradation();
+    currentTier = "normal";
+    disabledFeatures = new Set();
+    config = { onChange: null };
+    listeners = [];
+}
+//# sourceMappingURL=graceful-degradation.js.map

package/dist/viewer/performance/graceful-degradation.js.map

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

package/dist/viewer/performance/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Performance zone public interface.
+ *
+ * All cross-zone consumers should import from this barrel rather than
+ * individual implementation files. Type-only imports are excluded per
+ * the gateway pattern (erased at compile time, stay at call-site).
+ */
+export { isFeatureDisabled, onDegradationChange, type DegradableFeature, type DegradationState, type DegradationChangeHandler, } from "./graceful-degradation.js";
+export { formatBytes, formatRatio, type MemorySnapshot, type MemoryLevel, } from "./memory-monitor.js";
+export { createDomUpdateGate, type DomUpdateGate, type DomUpdateGateConfig, } from "./dom-update-gate.js";
+export { createResponseBufferGate, type ResponseBufferGate, type ResponseBufferGateConfig, } from "./response-buffer-gate.js";
+export { createUpdateBatcher, type UpdateBatcher, type UpdateBatcherConfig, } from "./update-batcher.js";
+export { type RefreshQueueState, type RefreshPriority, } from "./refresh-throttle.js";
+export { countDOMNodes, readHeapUsage, formatDuration, formatNodeCount, formatDelta, recordRender, recordUpdate, measureOperation, takeDOMSnapshot, computeSummary, onDOMSnapshot, setObservedContainer, startDOMPerformanceMonitor, stopDOMPerformanceMonitor, getLatestDOMSnapshot, getDOMSnapshotHistory, getRenderTimings, getUpdateComparisons, getObservedContainer, resetDOMPerformanceMonitor, type DOMNodeSnapshot, type RenderTiming, type UpdateComparison, type PerformanceSummary, type DOMPerformanceConfig, type DOMSnapshotHandler, } from "./dom-performance-monitor.js";

package/dist/viewer/performance/index.js

@@ -0,0 +1,20 @@
+/**
+ * Performance zone public interface.
+ *
+ * All cross-zone consumers should import from this barrel rather than
+ * individual implementation files. Type-only imports are excluded per
+ * the gateway pattern (erased at compile time, stay at call-site).
+ */
+// ── Graceful degradation ──────────────────────────────────────────────────────
+export { isFeatureDisabled, onDegradationChange, } from "./graceful-degradation.js";
+// ── Memory monitor ────────────────────────────────────────────────────────────
+export { formatBytes, formatRatio, } from "./memory-monitor.js";
+// ── DOM update gate ───────────────────────────────────────────────────────────
+export { createDomUpdateGate, } from "./dom-update-gate.js";
+// ── Response buffer gate ──────────────────────────────────────────────────────
+export { createResponseBufferGate, } from "./response-buffer-gate.js";
+// ── Update batcher ────────────────────────────────────────────────────────────
+export { createUpdateBatcher, } from "./update-batcher.js";
+// ── DOM performance monitor ──────────────────────────────────────────────────
+export { countDOMNodes, readHeapUsage, formatDuration, formatNodeCount, formatDelta, recordRender, recordUpdate, measureOperation, takeDOMSnapshot, computeSummary, onDOMSnapshot, setObservedContainer, startDOMPerformanceMonitor, stopDOMPerformanceMonitor, getLatestDOMSnapshot, getDOMSnapshotHistory, getRenderTimings, getUpdateComparisons, getObservedContainer, resetDOMPerformanceMonitor, } from "./dom-performance-monitor.js";
+//# sourceMappingURL=index.js.map

package/dist/viewer/performance/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/viewer/performance/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iFAAiF;AAEjF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GAIpB,MAAM,2BAA2B,CAAC;AAEnC,iFAAiF;AAEjF,OAAO,EACL,WAAW,EACX,WAAW,GAGZ,MAAM,qBAAqB,CAAC;AAE7B,iFAAiF;AAEjF,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAE9B,iFAAiF;AAEjF,OAAO,EACL,wBAAwB,GAGzB,MAAM,2BAA2B,CAAC;AAEnC,iFAAiF;AAEjF,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAS7B,gFAAgF;AAEhF,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,GAO3B,MAAM,8BAA8B,CAAC"}