@n-dx/core 0.1.0

package/packages/web/dist/viewer/tab-visibility.js

@@ -0,0 +1,276 @@
+/**
+ * Centralized tab visibility state manager.
+ *
+ * Wraps the Page Visibility API to provide a single source of truth for
+ * browser tab visibility state. All polling components subscribe to this
+ * module instead of independently listening for visibility changes.
+ *
+ * Browser compatibility:
+ *
+ *   1. Standard API    — `document.visibilityState` + `visibilitychange`
+ *   2. Webkit prefix   — `document.webkitVisibilityState` + `webkitvisibilitychange`
+ *   3. MS prefix       — `document.msVisibilityState` + `msvisibilitychange`
+ *   4. Focus/blur      — `window.focus` / `window.blur` (fallback when no API)
+ *
+ * State transitions:
+ *
+ *   visible -> hidden   Tab is backgrounded, minimized, or screen-locked.
+ *   hidden  -> visible  Tab regains focus or is foregrounded.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useTabVisibility`) is provided separately.
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Maximum number of transitions kept in history for debugging. */
+const MAX_TRANSITION_HISTORY = 50;
+// ─── Module state ────────────────────────────────────────────────────────────
+let currentState = "visible";
+let stateChangedAt = Date.now();
+let config = { onChange: null };
+let listeners = [];
+let boundHandler = null;
+let boundFocusHandler = null;
+let boundBlurHandler = null;
+let transitionHistory = [];
+let detectedMethod = "none";
+let detectedEventName = null;
+// ─── Browser API detection ──────────────────────────────────────────────────
+/**
+ * Probe the runtime environment for the best available Page Visibility API
+ * variant. Called once on first use, result is cached.
+ *
+ * Priority:
+ *   1. Standard API (`document.visibilityState`)
+ *   2. Webkit prefix (`document.webkitVisibilityState`)
+ *   3. MS prefix (`document.msVisibilityState`)
+ *   4. Focus/blur fallback (window events)
+ *   5. None (SSR or non-browser environment)
+ */
+export function detectVisibilityAPI() {
+    if (typeof document === "undefined") {
+        return { method: "none", eventName: null };
+    }
+    // Standard API
+    if ("visibilityState" in document) {
+        return { method: "standard", eventName: "visibilitychange" };
+    }
+    const doc = document;
+    // Webkit prefix (Safari < 14, older Chrome)
+    if ("webkitVisibilityState" in doc) {
+        return { method: "webkit", eventName: "webkitvisibilitychange" };
+    }
+    // MS prefix (IE 10)
+    if ("msVisibilityState" in doc) {
+        return { method: "ms", eventName: "msvisibilitychange" };
+    }
+    // Focus/blur fallback — available in all window-bearing environments
+    if (typeof window !== "undefined") {
+        return { method: "focus-blur", eventName: null };
+    }
+    return { method: "none", eventName: null };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Build a snapshot from current module state. */
+function buildSnapshot() {
+    const now = Date.now();
+    return {
+        state: currentState,
+        isVisible: currentState === "visible",
+        since: new Date(stateChangedAt).toISOString(),
+        durationMs: now - stateChangedAt,
+        timestamp: new Date(now).toISOString(),
+    };
+}
+function notifyListeners(snapshot) {
+    for (const listener of listeners) {
+        listener(snapshot);
+    }
+}
+/** Record a state transition in the bounded history ring. */
+function recordTransition(from, to) {
+    transitionHistory.push({
+        state: to,
+        from,
+        timestamp: new Date().toISOString(),
+    });
+    if (transitionHistory.length > MAX_TRANSITION_HISTORY) {
+        transitionHistory = transitionHistory.slice(-MAX_TRANSITION_HISTORY);
+    }
+}
+/**
+ * Read the current visibility state from the best available API.
+ * Handles standard, vendor-prefixed, and fallback scenarios.
+ */
+function readDocumentVisibility() {
+    if (typeof document === "undefined")
+        return "visible";
+    switch (detectedMethod) {
+        case "standard":
+            return document.visibilityState === "visible" ? "visible" : "hidden";
+        case "webkit": {
+            const doc = document;
+            return doc.webkitVisibilityState === "visible" ? "visible" : "hidden";
+        }
+        case "ms": {
+            const doc = document;
+            return doc.msVisibilityState === "visible" ? "visible" : "hidden";
+        }
+        // Focus/blur and none: return current tracked state (updated by focus/blur handlers)
+        default:
+            return currentState;
+    }
+}
+// ─── Event handlers ─────────────────────────────────────────────────────────
+function handleVisibilityChange() {
+    const newState = readDocumentVisibility();
+    if (newState === currentState)
+        return;
+    const previousState = currentState;
+    currentState = newState;
+    stateChangedAt = Date.now();
+    recordTransition(previousState, newState);
+    const snapshot = buildSnapshot();
+    if (config.onChange) {
+        config.onChange(snapshot, previousState);
+    }
+    notifyListeners(snapshot);
+}
+/** Focus handler for the fallback detection path. */
+function handleWindowFocus() {
+    if (currentState === "visible")
+        return;
+    const previousState = currentState;
+    currentState = "visible";
+    stateChangedAt = Date.now();
+    recordTransition(previousState, "visible");
+    const snapshot = buildSnapshot();
+    if (config.onChange) {
+        config.onChange(snapshot, previousState);
+    }
+    notifyListeners(snapshot);
+}
+/** Blur handler for the fallback detection path. */
+function handleWindowBlur() {
+    if (currentState === "hidden")
+        return;
+    const previousState = currentState;
+    currentState = "hidden";
+    stateChangedAt = Date.now();
+    recordTransition(previousState, "hidden");
+    const snapshot = buildSnapshot();
+    if (config.onChange) {
+        config.onChange(snapshot, previousState);
+    }
+    notifyListeners(snapshot);
+}
+// ─── Cleanup helpers ────────────────────────────────────────────────────────
+/** Remove all event listeners regardless of detection method. */
+function removeAllListeners() {
+    // Remove visibilitychange listener (standard or prefixed)
+    if (boundHandler && detectedEventName && typeof document !== "undefined") {
+        document.removeEventListener(detectedEventName, boundHandler);
+        boundHandler = null;
+    }
+    // Remove focus/blur listeners
+    if (typeof window !== "undefined") {
+        if (boundFocusHandler) {
+            window.removeEventListener("focus", boundFocusHandler);
+            boundFocusHandler = null;
+        }
+        if (boundBlurHandler) {
+            window.removeEventListener("blur", boundBlurHandler);
+            boundBlurHandler = null;
+        }
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Start the tab visibility monitor. Detects the best available browser API
+ * and begins listening for state changes.
+ *
+ * Safe to call multiple times — restarts with new config.
+ */
+export function startTabVisibilityMonitor(overrides = {}) {
+    stopTabVisibilityMonitor();
+    config = {
+        onChange: overrides.onChange ?? null,
+    };
+    // Detect the best available API on first start.
+    const detection = detectVisibilityAPI();
+    detectedMethod = detection.method;
+    detectedEventName = detection.eventName;
+    // Capture the current state immediately.
+    currentState = readDocumentVisibility();
+    stateChangedAt = Date.now();
+    // Bind and register event listeners based on detected method.
+    if (detectedEventName && typeof document !== "undefined") {
+        // Standard or vendor-prefixed Page Visibility API.
+        boundHandler = handleVisibilityChange;
+        document.addEventListener(detectedEventName, boundHandler);
+    }
+    else if (detectedMethod === "focus-blur" && typeof window !== "undefined") {
+        // Focus/blur fallback — less precise but universally supported.
+        boundFocusHandler = handleWindowFocus;
+        boundBlurHandler = handleWindowBlur;
+        window.addEventListener("focus", boundFocusHandler);
+        window.addEventListener("blur", boundBlurHandler);
+    }
+    // "none" method: SSR — no events to listen to.
+}
+/** Stop the tab visibility monitor and remove all event listeners. */
+export function stopTabVisibilityMonitor() {
+    removeAllListeners();
+}
+/** Subscribe to visibility change events. Returns an unsubscribe function. */
+export function onVisibilityChange(listener) {
+    listeners.push(listener);
+    return () => {
+        listeners = listeners.filter((l) => l !== listener);
+    };
+}
+/** Get the current tab visibility state. */
+export function getTabVisibility() {
+    return currentState;
+}
+/** Get a full snapshot of the current tab visibility state. */
+export function getTabVisibilitySnapshot() {
+    return buildSnapshot();
+}
+/** Convenience check: is the tab currently visible? */
+export function isTabVisible() {
+    return currentState === "visible";
+}
+/**
+ * Get the browser's Page Visibility API capabilities.
+ * Reports which detection method is in use and whether fallbacks are active.
+ */
+export function getVisibilityCapabilities() {
+    return {
+        supported: detectedMethod !== "none",
+        method: detectedMethod,
+        nativeAPI: detectedMethod === "standard" ||
+            detectedMethod === "webkit" ||
+            detectedMethod === "ms",
+        usingFallback: detectedMethod === "focus-blur",
+        eventName: detectedEventName,
+    };
+}
+/**
+ * Get the recent transition history (up to 50 entries).
+ * Useful for debugging visibility state patterns.
+ */
+export function getTransitionHistory() {
+    return transitionHistory;
+}
+/** Reset all module state (for testing). */
+export function resetTabVisibility() {
+    stopTabVisibilityMonitor();
+    currentState = "visible";
+    stateChangedAt = Date.now();
+    config = { onChange: null };
+    listeners = [];
+    transitionHistory = [];
+    detectedMethod = "none";
+    detectedEventName = null;
+}
+//# sourceMappingURL=tab-visibility.js.map

package/packages/web/dist/viewer/tab-visibility.js.map

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

package/packages/web/dist/viewer/tick-timer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared tick timer service for elapsed time updates.
+ *
+ * Manages a single setInterval that fires every second and distributes
+ * tick events to all subscribed components. This eliminates the need for
+ * individual per-component timers, reducing CPU overhead when many task
+ * cards are visible simultaneously.
+ *
+ * The timer automatically starts when the first subscriber joins and
+ * stops when the last subscriber leaves, ensuring zero overhead when
+ * no components need elapsed time updates.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useTick`) is provided separately.
+ */
+/** Callback invoked on each tick with the current timestamp (Date.now()). */
+export type TickListener = (now: number) => void;
+/** Read-only view of the tick timer's current state. */
+export interface TickTimerState {
+    /** Number of active subscribers. */
+    readonly subscriberCount: number;
+    /** Whether the shared interval is currently running. */
+    readonly running: boolean;
+}
+/**
+ * Subscribe to 1-second tick events.
+ *
+ * The listener receives the current `Date.now()` timestamp on each tick.
+ * The shared interval starts automatically when the first subscriber joins.
+ *
+ * Returns an unsubscribe function. When the last subscriber unsubscribes,
+ * the shared interval is stopped.
+ *
+ * @param listener - Callback invoked on each tick.
+ * @returns Unsubscribe function (safe to call multiple times).
+ */
+export declare function onTick(listener: TickListener): () => void;
+/**
+ * Suspend the tick timer.
+ *
+ * Clears the shared interval but keeps all listeners registered. The timer
+ * can be resumed later with `resumeTickTimer()`. Used by the tick visibility
+ * gate to pause elapsed time updates when the browser tab is hidden.
+ *
+ * No-op if the timer is already stopped.
+ */
+export declare function suspendTickTimer(): void;
+/**
+ * Resume a suspended tick timer.
+ *
+ * Restarts the shared interval if listeners exist. Fires an **immediate tick**
+ * before restarting the interval so that elapsed time displays catch up to
+ * the current wall-clock time without waiting up to 1 second for the next
+ * regular tick.
+ *
+ * Used by the tick visibility gate to resume elapsed time updates when the
+ * browser tab becomes visible again.
+ *
+ * No-op if the timer is already running or no listeners are registered.
+ */
+export declare function resumeTickTimer(): void;
+/**
+ * Get the current state of the tick timer.
+ */
+export declare function getTickTimerState(): TickTimerState;
+/**
+ * Reset all module state (for testing). Clears all listeners and
+ * stops the interval.
+ */
+export declare function resetTickTimer(): void;

package/packages/web/dist/viewer/tick-timer.js

@@ -0,0 +1,168 @@
+/**
+ * Shared tick timer service for elapsed time updates.
+ *
+ * Manages a single setInterval that fires every second and distributes
+ * tick events to all subscribed components. This eliminates the need for
+ * individual per-component timers, reducing CPU overhead when many task
+ * cards are visible simultaneously.
+ *
+ * The timer automatically starts when the first subscriber joins and
+ * stops when the last subscriber leaves, ensuring zero overhead when
+ * no components need elapsed time updates.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useTick`) is provided separately.
+ */
+import { registerPollingSource, } from "./polling-state.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Tick interval in milliseconds. */
+const TICK_INTERVAL_MS = 1000;
+/** Key used to register with the centralized polling state manager. */
+const POLLING_STATE_KEY = "tick-timer";
+// ─── Module state ────────────────────────────────────────────────────────────
+let listeners = [];
+let timerId = null;
+let stateUnsub = null;
+// ─── Internal helpers ────────────────────────────────────────────────────────
+/** Start the shared interval if not already running. */
+function startTimer() {
+    if (timerId !== null)
+        return;
+    timerId = setInterval(tick, TICK_INTERVAL_MS);
+    // Register with centralized polling state when the timer starts.
+    if (stateUnsub === null) {
+        stateUnsub = registerPollingSource(POLLING_STATE_KEY, {
+            suspend: () => clearTimer(),
+            resume: () => {
+                if (timerId === null && listeners.length > 0) {
+                    timerId = setInterval(tick, TICK_INTERVAL_MS);
+                }
+            },
+            dispose: () => {
+                clearTimer();
+                stateUnsub = null;
+            },
+            getStatus: () => (timerId !== null ? "active" : "idle"),
+        });
+    }
+}
+/** Clear the interval timer without touching polling-state registration. */
+function clearTimer() {
+    if (timerId === null)
+        return;
+    clearInterval(timerId);
+    timerId = null;
+}
+/** Stop the shared interval and deregister from polling-state. */
+function stopTimer() {
+    clearTimer();
+    // Deregister from centralized polling state when no subscribers remain.
+    if (stateUnsub) {
+        const unsub = stateUnsub;
+        stateUnsub = null;
+        unsub();
+    }
+}
+/** Fire a tick event to all current listeners. */
+function tick() {
+    const now = Date.now();
+    // Snapshot the listener array so that subscribe/unsubscribe during
+    // iteration doesn't cause skips or double-fires within a single tick.
+    const snapshot = listeners.slice();
+    for (const listener of snapshot) {
+        try {
+            listener(now);
+        }
+        catch {
+            // Swallow errors from individual listeners to prevent one bad
+            // subscriber from breaking all others.
+        }
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Subscribe to 1-second tick events.
+ *
+ * The listener receives the current `Date.now()` timestamp on each tick.
+ * The shared interval starts automatically when the first subscriber joins.
+ *
+ * Returns an unsubscribe function. When the last subscriber unsubscribes,
+ * the shared interval is stopped.
+ *
+ * @param listener - Callback invoked on each tick.
+ * @returns Unsubscribe function (safe to call multiple times).
+ */
+export function onTick(listener) {
+    listeners.push(listener);
+    // Start the timer if this is the first subscriber.
+    if (listeners.length === 1) {
+        startTimer();
+    }
+    let removed = false;
+    return () => {
+        if (removed)
+            return; // idempotent unsubscribe
+        removed = true;
+        listeners = listeners.filter((l) => l !== listener);
+        // Stop the timer if no subscribers remain.
+        if (listeners.length === 0) {
+            stopTimer();
+        }
+    };
+}
+/**
+ * Suspend the tick timer.
+ *
+ * Clears the shared interval but keeps all listeners registered. The timer
+ * can be resumed later with `resumeTickTimer()`. Used by the tick visibility
+ * gate to pause elapsed time updates when the browser tab is hidden.
+ *
+ * No-op if the timer is already stopped.
+ */
+export function suspendTickTimer() {
+    clearTimer();
+}
+/**
+ * Resume a suspended tick timer.
+ *
+ * Restarts the shared interval if listeners exist. Fires an **immediate tick**
+ * before restarting the interval so that elapsed time displays catch up to
+ * the current wall-clock time without waiting up to 1 second for the next
+ * regular tick.
+ *
+ * Used by the tick visibility gate to resume elapsed time updates when the
+ * browser tab becomes visible again.
+ *
+ * No-op if the timer is already running or no listeners are registered.
+ */
+export function resumeTickTimer() {
+    if (timerId !== null)
+        return; // already running
+    if (listeners.length === 0)
+        return; // no subscribers
+    // Fire an immediate tick for catch-up. Elapsed time formatters compute
+    // from an absolute start timestamp, so a single tick is enough for all
+    // displays to jump to the correct current value.
+    tick();
+    // Restart the periodic interval.
+    timerId = setInterval(tick, TICK_INTERVAL_MS);
+}
+/**
+ * Get the current state of the tick timer.
+ */
+export function getTickTimerState() {
+    return {
+        subscriberCount: listeners.length,
+        running: timerId !== null,
+    };
+}
+/**
+ * Reset all module state (for testing). Clears all listeners and
+ * stops the interval.
+ */
+export function resetTickTimer() {
+    stopTimer();
+    listeners = [];
+    stateUnsub = null;
+}
+//# sourceMappingURL=tick-timer.js.map

package/packages/web/dist/viewer/tick-timer.js.map

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

package/packages/web/dist/viewer/tick-visibility-gate.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Tick visibility gate — pauses elapsed time timer updates during tab inactivity.
+ *
+ * Bridges the Page Visibility API (via tab-visibility) to the tick timer's
+ * suspend/resume lifecycle. When the browser tab is backgrounded, the tick
+ * timer's shared setInterval is cleared to conserve CPU and battery. When the
+ * tab returns to the foreground, the timer is resumed with an immediate
+ * catch-up tick so elapsed time displays jump to the correct current value.
+ *
+ * Pipeline position:
+ *
+ *   tab-visibility → **tick-visibility-gate** → tick-timer → batched-tick-dispatcher → useTick → render
+ *
+ * When visible:  tick timer runs normally (1s interval)
+ * When hidden:   tick timer is suspended (no interval, no ticks, zero CPU)
+ * On resume:     immediate catch-up tick → restart interval
+ *
+ * Lifecycle:
+ *
+ *   Tab goes hidden:
+ *     1. Immediately suspend the tick timer (clearInterval).
+ *     2. No ticks fire while the tab is hidden — zero overhead.
+ *
+ *   Tab becomes visible (after resume debounce):
+ *     1. Resume the tick timer — fires an immediate tick for catch-up,
+ *        then restarts the 1-second interval.
+ *     2. The immediate tick causes all elapsed time displays to recompute
+ *        from their absolute startedAt timestamps, jumping to the correct
+ *        current value without waiting up to 1 second.
+ *
+ * The resume is debounced (100ms default) to prevent thrashing during rapid
+ * tab switching (e.g. quick alt-tab sequences). Suspension is always immediate
+ * to stop unnecessary work as fast as possible.
+ *
+ * This module complements the polling-manager (which manages its own set of
+ * registered pollers) and the DOM update gate (which gates state updates).
+ * Together they form a complete tab-inactivity optimization pipeline.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ */
+/** Configuration for the tick visibility gate. */
+export interface TickVisibilityGateConfig {
+    /**
+     * Debounce delay in milliseconds before resuming the tick timer after
+     * the tab becomes visible. Prevents thrashing on rapid tab switches.
+     * Default: 100ms (matches polling-manager and DOM update gate debounce).
+     */
+    resumeDebounceMs?: number | undefined;
+    /**
+     * Called when the tick timer is suspended (tab went hidden).
+     * Optional — useful for monitoring and debugging.
+     */
+    onSuspend?: (() => void) | undefined;
+    /**
+     * Called when the tick timer is resumed (tab became visible, after debounce).
+     * Optional — useful for monitoring and debugging.
+     */
+    onResume?: (() => void) | undefined;
+}
+/** Read-only snapshot of the gate's current state. */
+export interface TickVisibilityGateSnapshot {
+    /** Whether the tick timer is currently running (gate is open). */
+    readonly isRunning: boolean;
+    /** Number of times the timer has been suspended. */
+    readonly suspensionCount: number;
+    /** Number of times the timer has been resumed (after debounce). */
+    readonly resumeCount: number;
+    /** Whether the gate has been disposed. */
+    readonly disposed: boolean;
+}
+/** A tick visibility gate instance. */
+export interface TickVisibilityGate {
+    /** Whether the tick timer is currently running. */
+    isRunning(): boolean;
+    /** Get a snapshot of the gate's current state. */
+    getSnapshot(): TickVisibilityGateSnapshot;
+    /** Dispose: unsubscribe from visibility events, clear debounce timer. */
+    dispose(): void;
+}
+/**
+ * Create a new tick visibility gate.
+ *
+ * Usage:
+ * ```ts
+ * // During app initialization (after startTabVisibilityMonitor):
+ * const gate = createTickVisibilityGate();
+ *
+ * // On app shutdown:
+ * gate.dispose();
+ * ```
+ */
+export declare function createTickVisibilityGate(config?: TickVisibilityGateConfig): TickVisibilityGate;