@n-dx/web 0.1.0

package/dist/viewer/polling/batched-tick-dispatcher.js

@@ -0,0 +1,183 @@
+/**
+ * Batched tick dispatcher for elapsed time state updates.
+ *
+ * Sits between the shared tick timer and individual `useTick` hook instances.
+ * Instead of N separate `onTick` listeners each calling `setState` independently,
+ * this dispatcher:
+ *
+ *   1. Subscribes to the tick timer **once** (regardless of how many components
+ *      display elapsed time).
+ *   2. On each tick, computes all new values synchronously (read-only phase).
+ *   3. Filters out unchanged values via equality check (skip phase).
+ *   4. Schedules a single `requestAnimationFrame` to apply all state updates
+ *      in one synchronous block (write phase).
+ *
+ * This two-phase (compute → RAF write) approach ensures:
+ *
+ *   - All `setState` calls occur within the same synchronous execution context
+ *     inside the RAF callback, allowing Preact to batch them into a single
+ *     reconciliation pass.
+ *   - State updates are aligned with the browser's paint cycle, eliminating
+ *     wasted intermediate renders.
+ *   - With 20+ visible task cards, the re-render count drops from N individual
+ *     renders to one batched reconciliation per tick.
+ *
+ * Auto-lifecycle: subscribes to the tick timer when the first component
+ * registers, unsubscribes when the last one unregisters. Zero overhead
+ * when no elapsed time displays are mounted.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact integration lives in the `useTick` hook.
+ */
+import { onTick } from "./tick-timer.js";
+// ─── Module state ────────────────────────────────────────────────────────────
+let registrations = [];
+let tickUnsub = null;
+let rafId = null;
+let pendingBatch = null;
+// ─── Internal helpers ────────────────────────────────────────────────────────
+/** Phase 1 (tick callback): compute values, filter unchanged, queue RAF. */
+function onTickFired() {
+    const batch = [];
+    // Snapshot registrations to protect against mid-iteration unregister.
+    const snapshot = registrations.slice();
+    for (const reg of snapshot) {
+        try {
+            const next = reg.compute();
+            if (next !== reg.lastValueRef.current) {
+                batch.push({ setDisplay: reg.setDisplay, value: next, reg });
+            }
+        }
+        catch {
+            // Swallow errors from individual computations to prevent one bad
+            // registration from breaking all others.
+        }
+    }
+    if (batch.length === 0)
+        return;
+    // Commit lastValueRef immediately so the next tick won't re-queue
+    // the same update if RAF hasn't fired yet.
+    for (const { reg, value } of batch) {
+        reg.lastValueRef.current = value;
+    }
+    // Queue state updates for the next animation frame.
+    // If a previous batch is still pending (unlikely at 1s intervals),
+    // merge into it.
+    if (pendingBatch) {
+        for (const { setDisplay, value } of batch) {
+            pendingBatch.push({ setDisplay, value });
+        }
+    }
+    else {
+        pendingBatch = batch.map(({ setDisplay, value }) => ({
+            setDisplay,
+            value,
+        }));
+    }
+    if (rafId === null) {
+        rafId = requestAnimationFrame(applyBatch);
+    }
+}
+/** Phase 2 (RAF callback): apply all state updates in one synchronous block. */
+function applyBatch() {
+    rafId = null;
+    const batch = pendingBatch;
+    pendingBatch = null;
+    if (!batch)
+        return;
+    // All setDisplay calls happen synchronously within this frame →
+    // Preact batches them into a single reconciliation pass.
+    for (const { setDisplay, value } of batch) {
+        try {
+            setDisplay(value);
+        }
+        catch {
+            // Swallow errors from individual setters.
+        }
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Register an elapsed time updater with the batched dispatcher.
+ *
+ * The dispatcher will call `compute()` on each tick, compare the result
+ * against `lastValueRef.current`, and — if changed — schedule a batched
+ * RAF update that calls `setDisplay(newValue)`.
+ *
+ * The `lastValueRef` is shared with the calling hook so that both the
+ * dispatcher and the hook's immediate-update effect (for `startedAt`
+ * prop changes) stay in sync.
+ *
+ * Returns an unregister function. When the last registration is removed,
+ * the dispatcher unsubscribes from the tick timer automatically.
+ *
+ * @param compute      - Pure function returning the current formatted string.
+ * @param setDisplay   - Preact state setter for the display value.
+ * @param lastValueRef - Mutable ref tracking the last emitted value.
+ * @returns Unregister function (safe to call multiple times).
+ */
+export function registerTickUpdater(compute, setDisplay, lastValueRef) {
+    const reg = { compute, setDisplay, lastValueRef };
+    registrations.push(reg);
+    // Auto-start: subscribe to the tick timer on first registration.
+    if (registrations.length === 1 && tickUnsub === null) {
+        tickUnsub = onTick(onTickFired);
+    }
+    let removed = false;
+    return () => {
+        if (removed)
+            return; // idempotent unregister
+        removed = true;
+        registrations = registrations.filter((r) => r !== reg);
+        // Auto-stop: unsubscribe from tick timer when no registrations remain.
+        if (registrations.length === 0) {
+            if (tickUnsub) {
+                tickUnsub();
+                tickUnsub = null;
+            }
+            if (rafId !== null) {
+                cancelAnimationFrame(rafId);
+                rafId = null;
+                pendingBatch = null;
+            }
+        }
+    };
+}
+/**
+ * Get the current state of the batched tick dispatcher (for testing/monitoring).
+ */
+export function getBatchedTickDispatcherState() {
+    return {
+        registrationCount: registrations.length,
+        hasPendingRAF: rafId !== null,
+        pendingUpdateCount: pendingBatch?.length ?? 0,
+    };
+}
+/**
+ * Force-flush all pending RAF updates synchronously.
+ * Cancels any pending RAF. No-op if nothing is pending.
+ */
+export function flushBatchedTicks() {
+    if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+        rafId = null;
+    }
+    applyBatch();
+}
+/**
+ * Reset all dispatcher state (for testing). Unsubscribes from the tick
+ * timer, cancels pending RAF, and clears all registrations.
+ */
+export function resetBatchedTickDispatcher() {
+    if (tickUnsub) {
+        tickUnsub();
+        tickUnsub = null;
+    }
+    if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+        rafId = null;
+    }
+    registrations = [];
+    pendingBatch = null;
+}
+//# sourceMappingURL=batched-tick-dispatcher.js.map

package/dist/viewer/polling/batched-tick-dispatcher.js.map

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

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

@@ -0,0 +1,13 @@
+/**
+ * Polling zone public interface.
+ *
+ * All cross-zone consumers should import from this barrel rather than
+ * individual implementation files.
+ */
+export { startPollingManager, stopPollingManager, registerPoller, unregisterPoller, suspendAll, resumeAll, isSuspended, isPollerActive, getRegisteredPollers, getPollerCount, resetPollingManager, } from "./polling-manager.js";
+export { startPollingRestart, stopPollingRestart, } from "./polling-restart.js";
+export { createTickVisibilityGate, } from "./tick-visibility-gate.js";
+export { onTick, suspendTickTimer, resumeTickTimer, getTickTimerState, resetTickTimer, } from "./tick-timer.js";
+export { registerTickUpdater, } from "./batched-tick-dispatcher.js";
+export { registerPollingSource, onPollingStateChange, getPollingState, resetPollingState, type PollingSourceCallbacks, type PollingSourceConfig, type PollingStateSnapshot, type PollingStateChangeHandler, } from "./polling-state.js";
+export { startTabVisibilityMonitor, stopTabVisibilityMonitor, onVisibilityChange, getTabVisibility, getTabVisibilitySnapshot, isTabVisible, getVisibilityCapabilities, getTransitionHistory, resetTabVisibility, detectVisibilityAPI, type TabVisibilityState, type TabVisibilitySnapshot, type VisibilityChangeHandler, type TabVisibilityConfig, type VisibilityDetectionMethod, type VisibilityAPICapabilities, type VisibilityTransition, } from "./tab-visibility.js";

package/dist/viewer/polling/index.js

@@ -0,0 +1,16 @@
+/**
+ * Polling zone public interface.
+ *
+ * All cross-zone consumers should import from this barrel rather than
+ * individual implementation files.
+ */
+export { startPollingManager, stopPollingManager, registerPoller, unregisterPoller, suspendAll, resumeAll, isSuspended, isPollerActive, getRegisteredPollers, getPollerCount, resetPollingManager, } from "./polling-manager.js";
+export { startPollingRestart, stopPollingRestart, } from "./polling-restart.js";
+export { createTickVisibilityGate, } from "./tick-visibility-gate.js";
+export { onTick, suspendTickTimer, resumeTickTimer, getTickTimerState, resetTickTimer, } from "./tick-timer.js";
+export { registerTickUpdater, } from "./batched-tick-dispatcher.js";
+// ── Polling state — cross-zone API ───────────────────────────────────────────
+export { registerPollingSource, onPollingStateChange, getPollingState, resetPollingState, } from "./polling-state.js";
+// ── Tab visibility ──────────────────────────────────────────────────────────
+export { startTabVisibilityMonitor, stopTabVisibilityMonitor, onVisibilityChange, getTabVisibility, getTabVisibilitySnapshot, isTabVisible, getVisibilityCapabilities, getTransitionHistory, resetTabVisibility, detectVisibilityAPI, } from "./tab-visibility.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/viewer/polling/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAEtC,gFAAgF;AAEhF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAKlB,MAAM,oBAAoB,CAAC;AAE5B,+EAA+E;AAE/E,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GAQpB,MAAM,qBAAqB,CAAC"}

package/dist/viewer/polling/polling-manager.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Centralized polling manager with tab visibility integration.
+ *
+ * Provides a registry for all polling intervals across the application.
+ * When the browser tab is backgrounded, all registered pollers are
+ * suspended to conserve resources. When the tab regains focus, pollers
+ * are resumed with their original intervals.
+ *
+ * Rapid visibility changes (e.g. quick alt-tab sequences) are debounced
+ * to avoid thrashing interval creation/destruction.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`usePolling`) is provided separately.
+ */
+/** Read-only view of a registered poller for external inspection. */
+export interface PollerInfo {
+    readonly key: string;
+    readonly intervalMs: number;
+    readonly active: boolean;
+}
+/**
+ * Start the polling manager. Subscribes to tab visibility changes
+ * and enables automatic suspend/resume of registered pollers.
+ *
+ * Safe to call multiple times — restarts cleanly.
+ */
+export declare function startPollingManager(): void;
+/**
+ * Stop the polling manager. Unsubscribes from visibility changes
+ * but does NOT clear registered pollers or their timers.
+ */
+export declare function stopPollingManager(): void;
+/**
+ * Register a polling interval. The callback will be called every
+ * `intervalMs` milliseconds while the tab is visible.
+ *
+ * If the tab is currently hidden and the manager is started,
+ * the poller is registered but not activated until the tab becomes visible.
+ *
+ * Returns an unregister function for cleanup.
+ *
+ * @param key - Unique identifier for this poller. Re-registering with the
+ *              same key replaces the previous entry.
+ * @param callback - Function to call on each tick.
+ * @param intervalMs - Polling interval in milliseconds.
+ */
+export declare function registerPoller(key: string, callback: () => void, intervalMs: number): () => void;
+/**
+ * Remove a poller from the registry and clear its interval.
+ */
+export declare function unregisterPoller(key: string): void;
+/**
+ * Suspend all registered pollers. Clears their interval timers
+ * but keeps them in the registry for later resumption.
+ */
+export declare function suspendAll(): void;
+/**
+ * Resume all registered pollers. Restarts their interval timers
+ * with their original intervals.
+ */
+export declare function resumeAll(): void;
+/**
+ * Check if the polling manager is currently in a suspended state.
+ */
+export declare function isSuspended(): boolean;
+/**
+ * Check if a specific poller is actively running (has a timer).
+ */
+export declare function isPollerActive(key: string): boolean;
+/**
+ * Get read-only information about all registered pollers.
+ */
+export declare function getRegisteredPollers(): readonly PollerInfo[];
+/**
+ * Get the number of registered pollers.
+ */
+export declare function getPollerCount(): number;
+/**
+ * Reset all module state (for testing). Clears all pollers, stops the
+ * manager, and resets the suspended flag.
+ */
+export declare function resetPollingManager(): void;

package/dist/viewer/polling/polling-manager.js

@@ -0,0 +1,254 @@
+/**
+ * Centralized polling manager with tab visibility integration.
+ *
+ * Provides a registry for all polling intervals across the application.
+ * When the browser tab is backgrounded, all registered pollers are
+ * suspended to conserve resources. When the tab regains focus, pollers
+ * are resumed with their original intervals.
+ *
+ * Rapid visibility changes (e.g. quick alt-tab sequences) are debounced
+ * to avoid thrashing interval creation/destruction.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`usePolling`) is provided separately.
+ */
+import { onVisibilityChange, isTabVisible, } from "./tab-visibility.js";
+import { registerPollingSource, } from "./polling-state.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * Debounce delay for visibility-triggered resume (ms).
+ * Prevents thrashing when the user rapidly switches between tabs.
+ * Suspension is immediate (no debounce) to stop work quickly.
+ */
+const RESUME_DEBOUNCE_MS = 100;
+// ─── Constants (polling-state integration) ───────────────────────────────────
+const POLLING_STATE_KEY = "polling-manager";
+// ─── Module state ────────────────────────────────────────────────────────────
+const pollers = new Map();
+let visibilityUnsub = null;
+let stateUnsub = null;
+let started = false;
+let suspended = false;
+let resumeDebounceTimer = null;
+// ─── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Clean up the polling manager's own resources (visibility subscription,
+ * debounce timer, poller intervals). Does NOT touch polling-state
+ * registration — callers are responsible for that coordination.
+ */
+function cleanupOwnResources() {
+    if (visibilityUnsub) {
+        visibilityUnsub();
+        visibilityUnsub = null;
+    }
+    if (resumeDebounceTimer !== null) {
+        clearTimeout(resumeDebounceTimer);
+        resumeDebounceTimer = null;
+    }
+}
+/** Start a poller's interval timer. */
+function activatePoller(entry) {
+    if (entry.timerId !== null)
+        return; // already active
+    entry.timerId = setInterval(entry.callback, entry.intervalMs);
+}
+/** Stop a poller's interval timer without removing it from the registry. */
+function deactivatePoller(entry) {
+    if (entry.timerId === null)
+        return; // already inactive
+    clearInterval(entry.timerId);
+    entry.timerId = null;
+}
+/** Handle visibility change events from the tab-visibility module. */
+function handleVisibilityChange(snapshot) {
+    if (snapshot.isVisible) {
+        // Tab became visible — resume with debounce to handle rapid toggling.
+        if (resumeDebounceTimer !== null) {
+            clearTimeout(resumeDebounceTimer);
+        }
+        resumeDebounceTimer = setTimeout(() => {
+            resumeDebounceTimer = null;
+            resumeAll();
+        }, RESUME_DEBOUNCE_MS);
+    }
+    else {
+        // Tab became hidden — suspend immediately.
+        // Cancel any pending resume first.
+        if (resumeDebounceTimer !== null) {
+            clearTimeout(resumeDebounceTimer);
+            resumeDebounceTimer = null;
+        }
+        suspendAll();
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Start the polling manager. Subscribes to tab visibility changes
+ * and enables automatic suspend/resume of registered pollers.
+ *
+ * Safe to call multiple times — restarts cleanly.
+ */
+export function startPollingManager() {
+    if (started)
+        stopPollingManager();
+    started = true;
+    suspended = false;
+    // Subscribe to tab visibility changes.
+    visibilityUnsub = onVisibilityChange(handleVisibilityChange);
+    // If the tab is currently hidden, start in suspended state.
+    if (!isTabVisible()) {
+        suspended = true;
+    }
+    // Register with centralized polling state for coordinated lifecycle.
+    // The dispose callback cleans up own resources without calling
+    // stopPollingManager (which would re-entrantly unregister from
+    // polling-state, causing a loop).
+    stateUnsub = registerPollingSource(POLLING_STATE_KEY, {
+        suspend: () => suspendAll(),
+        resume: () => resumeAll(),
+        dispose: () => {
+            for (const entry of pollers.values()) {
+                deactivatePoller(entry);
+            }
+            cleanupOwnResources();
+            started = false;
+            stateUnsub = null; // Already being disposed by polling-state.
+        },
+        getStatus: () => {
+            if (!started)
+                return "idle";
+            return suspended ? "suspended" : "active";
+        },
+    });
+}
+/**
+ * Stop the polling manager. Unsubscribes from visibility changes
+ * but does NOT clear registered pollers or their timers.
+ */
+export function stopPollingManager() {
+    cleanupOwnResources();
+    started = false;
+    // Deregister from centralized polling state. Nullify stateUnsub first
+    // to prevent re-entrant dispose (unregisterPollingSource calls dispose,
+    // which would otherwise try to call stateUnsub again).
+    if (stateUnsub) {
+        const unsub = stateUnsub;
+        stateUnsub = null;
+        unsub();
+    }
+}
+/**
+ * Register a polling interval. The callback will be called every
+ * `intervalMs` milliseconds while the tab is visible.
+ *
+ * If the tab is currently hidden and the manager is started,
+ * the poller is registered but not activated until the tab becomes visible.
+ *
+ * Returns an unregister function for cleanup.
+ *
+ * @param key - Unique identifier for this poller. Re-registering with the
+ *              same key replaces the previous entry.
+ * @param callback - Function to call on each tick.
+ * @param intervalMs - Polling interval in milliseconds.
+ */
+export function registerPoller(key, callback, intervalMs) {
+    // If a poller with this key already exists, clean it up first.
+    const existing = pollers.get(key);
+    if (existing) {
+        deactivatePoller(existing);
+    }
+    const entry = {
+        key,
+        callback,
+        intervalMs,
+        timerId: null,
+    };
+    pollers.set(key, entry);
+    // Only activate if the manager is started and not suspended.
+    if (started && !suspended) {
+        activatePoller(entry);
+    }
+    else if (!started) {
+        // Manager not started — activate immediately (unmanaged mode).
+        activatePoller(entry);
+    }
+    return () => unregisterPoller(key);
+}
+/**
+ * Remove a poller from the registry and clear its interval.
+ */
+export function unregisterPoller(key) {
+    const entry = pollers.get(key);
+    if (!entry)
+        return;
+    deactivatePoller(entry);
+    pollers.delete(key);
+}
+/**
+ * Suspend all registered pollers. Clears their interval timers
+ * but keeps them in the registry for later resumption.
+ */
+export function suspendAll() {
+    suspended = true;
+    for (const entry of pollers.values()) {
+        deactivatePoller(entry);
+    }
+}
+/**
+ * Resume all registered pollers. Restarts their interval timers
+ * with their original intervals.
+ */
+export function resumeAll() {
+    suspended = false;
+    for (const entry of pollers.values()) {
+        activatePoller(entry);
+    }
+}
+/**
+ * Check if the polling manager is currently in a suspended state.
+ */
+export function isSuspended() {
+    return suspended;
+}
+/**
+ * Check if a specific poller is actively running (has a timer).
+ */
+export function isPollerActive(key) {
+    const entry = pollers.get(key);
+    return entry !== null && entry !== undefined && entry.timerId !== null;
+}
+/**
+ * Get read-only information about all registered pollers.
+ */
+export function getRegisteredPollers() {
+    const result = [];
+    for (const entry of pollers.values()) {
+        result.push({
+            key: entry.key,
+            intervalMs: entry.intervalMs,
+            active: entry.timerId !== null,
+        });
+    }
+    return result;
+}
+/**
+ * Get the number of registered pollers.
+ */
+export function getPollerCount() {
+    return pollers.size;
+}
+/**
+ * Reset all module state (for testing). Clears all pollers, stops the
+ * manager, and resets the suspended flag.
+ */
+export function resetPollingManager() {
+    // Clear all pollers.
+    for (const entry of pollers.values()) {
+        deactivatePoller(entry);
+    }
+    pollers.clear();
+    // Stop the manager.
+    stopPollingManager();
+    suspended = false;
+}
+//# sourceMappingURL=polling-manager.js.map

package/dist/viewer/polling/polling-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling-manager.js","sourceRoot":"","sources":["../../../src/viewer/polling/polling-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,kBAAkB,EAClB,YAAY,GAEb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,qBAAqB,GAEtB,MAAM,oBAAoB,CAAC;AAuB5B,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,gFAAgF;AAEhF,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAE5C,gFAAgF;AAEhF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;AAC/C,IAAI,eAAe,GAAwB,IAAI,CAAC;AAChD,IAAI,UAAU,GAAwB,IAAI,CAAC;AAC3C,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,IAAI,SAAS,GAAG,KAAK,CAAC;AACtB,IAAI,mBAAmB,GAAyC,IAAI,CAAC;AAErE,gFAAgF;AAEhF;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,IAAI,eAAe,EAAE,CAAC;QACpB,eAAe,EAAE,CAAC;QAClB,eAAe,GAAG,IAAI,CAAC;IACzB,CAAC;IACD,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;QACjC,YAAY,CAAC,mBAAmB,CAAC,CAAC;QAClC,mBAAmB,GAAG,IAAI,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,uCAAuC;AACvC,SAAS,cAAc,CAAC,KAAkB;IACxC,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,CAAC,iBAAiB;IACrD,KAAK,CAAC,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;AAChE,CAAC;AAED,4EAA4E;AAC5E,SAAS,gBAAgB,CAAC,KAAkB;IAC1C,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,CAAC,mBAAmB;IACvD,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;AACvB,CAAC;AAED,sEAAsE;AACtE,SAAS,sBAAsB,CAAC,QAA+B;IAC7D,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QACvB,sEAAsE;QACtE,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACjC,YAAY,CAAC,mBAAmB,CAAC,CAAC;QACpC,CAAC;QACD,mBAAmB,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,mBAAmB,GAAG,IAAI,CAAC;YAC3B,SAAS,EAAE,CAAC;QACd,CAAC,EAAE,kBAAkB,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,2CAA2C;QAC3C,mCAAmC;QACnC,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACjC,YAAY,CAAC,mBAAmB,CAAC,CAAC;YAClC,mBAAmB,GAAG,IAAI,CAAC;QAC7B,CAAC;QACD,UAAU,EAAE,CAAC;IACf,CAAC;AACH,CAAC;AAED,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,OAAO;QAAE,kBAAkB,EAAE,CAAC;IAElC,OAAO,GAAG,IAAI,CAAC;IACf,SAAS,GAAG,KAAK,CAAC;IAElB,uCAAuC;IACvC,eAAe,GAAG,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;IAE7D,4DAA4D;IAC5D,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QACpB,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,qEAAqE;IACrE,+DAA+D;IAC/D,+DAA+D;IAC/D,kCAAkC;IAClC,UAAU,GAAG,qBAAqB,CAChC,iBAAiB,EACjB;QACE,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;QAC3B,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE;QACzB,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBACrC,gBAAgB,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;YACD,mBAAmB,EAAE,CAAC;YACtB,OAAO,GAAG,KAAK,CAAC;YAChB,UAAU,GAAG,IAAI,CAAC,CAAC,2CAA2C;QAChE,CAAC;QACD,SAAS,EAAE,GAAG,EAAE;YACd,IAAI,CAAC,OAAO;gBAAE,OAAO,MAAM,CAAC;YAC5B,OAAO,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5C,CAAC;KACF,CACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,mBAAmB,EAAE,CAAC;IACtB,OAAO,GAAG,KAAK,CAAC;IAEhB,sEAAsE;IACtE,wEAAwE;IACxE,uDAAuD;IACvD,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,UAAU,CAAC;QACzB,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,EAAE,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,QAAoB,EACpB,UAAkB;IAElB,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,EAAE,CAAC;QACb,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,KAAK,GAAgB;QACzB,GAAG;QACH,QAAQ;QACR,UAAU;QACV,OAAO,EAAE,IAAI;KACd,CAAC;IAEF,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAExB,6DAA6D;IAC7D,IAAI,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;QAC1B,cAAc,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;SAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,+DAA+D;QAC/D,cAAc,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,GAAG,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,SAAS,GAAG,IAAI,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,SAAS,GAAG,KAAK,CAAC;IAClB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC;YACV,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,IAAI;SAC/B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,qBAAqB;IACrB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB,oBAAoB;IACpB,kBAAkB,EAAE,CAAC;IAErB,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC"}

package/dist/viewer/polling/polling-restart.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Polling restart coordinator.
+ *
+ * Bridges the graceful-degradation system to the centralized polling-state
+ * manager. When memory pressure disables the `autoRefresh` feature, this
+ * module calls `suspendAllSources()` to halt all non-essential polling
+ * sources in one atomic operation. When pressure subsides and `autoRefresh`
+ * is re-enabled, it calls `resumeAllSources()` to restart everything at
+ * original intervals.
+ *
+ * This provides a safety net that ensures **all** polling loops stop and
+ * restart together, even if an individual component forgets to handle
+ * degradation on its own. Components that also track degradation individually
+ * (e.g. status-indicators, use-app-data) coexist harmlessly — suspending
+ * an already-suspended source or resuming an already-active one is a no-op
+ * in both polling-state and polling-manager.
+ *
+ * Flow:
+ *
+ *   memory-monitor  →  graceful-degradation  →  polling-restart
+ *                                                     ↓
+ *                                               polling-state
+ *                                                ↓         ↓
+ *                                          polling-manager  tick-timer
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ */
+/**
+ * Start the polling restart coordinator.
+ *
+ * Subscribes to degradation changes and evaluates the current state
+ * immediately. If `autoRefresh` is already disabled (e.g. the coordinator
+ * is started after memory pressure began), sources are suspended at once.
+ *
+ * Safe to call multiple times — restarts cleanly.
+ */
+export declare function startPollingRestart(): void;
+/**
+ * Stop the polling restart coordinator.
+ *
+ * Unsubscribes from degradation changes. If the coordinator had
+ * triggered a global suspension, sources are resumed to avoid
+ * leaving polling permanently frozen.
+ */
+export declare function stopPollingRestart(): void;