@n-dx/core 0.1.0

package/packages/web/dist/viewer/performance/response-buffer-gate.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Response buffer gate — suspends message pipeline during tab inactivity.
+ *
+ * Sits at the front of the WebSocket message pipeline to prevent memory
+ * buildup from accumulating response data while the browser tab is hidden.
+ * When the tab becomes inactive:
+ *
+ *   1. Flushes all pending data from downstream buffers (throttle, coalescer,
+ *      batcher) so they release references immediately.
+ *   2. Drops all subsequent incoming messages silently — no accumulation.
+ *   3. Tracks that messages were dropped during suspension.
+ *
+ * When the tab becomes visible again:
+ *
+ *   1. Opens the gate to accept new messages normally.
+ *   2. If any messages were dropped, calls `onResume` so the consumer can
+ *      trigger a single full reconciliation (e.g. fetchPRDData + fetchTaskUsage)
+ *      to restore data integrity.
+ *
+ * This module complements the polling-manager (which suspends fetch intervals)
+ * by also stopping the *response processing* side. Without this, WebSocket
+ * messages arriving during a background tab would still accumulate in the
+ * message-throttle pending arrays, coalescer batch, and update-batcher queue.
+ *
+ * Pipeline position:
+ *
+ *   raw WebSocket → **response-buffer-gate** → throttle → coalescer → batcher → render
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+/** Flush callback for a downstream buffer (throttle, coalescer, or batcher). */
+export type BufferFlushFn = () => void;
+/** Configuration for the response buffer gate. */
+export interface ResponseBufferGateConfig {
+    /**
+     * Downstream buffer flush functions. Called in order when the gate
+     * closes (tab goes hidden) to release buffered data from memory.
+     *
+     * Typical order: throttle.flush → coalescer.flush → batcher.flush
+     */
+    flushDownstream: readonly BufferFlushFn[];
+    /**
+     * Called when the gate re-opens after suspension, but only if messages
+     * were dropped while the gate was closed. Use this to trigger a single
+     * reconciliation fetch that restores data integrity.
+     */
+    onResume: () => void;
+    /**
+     * 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's resume debounce).
+     */
+    resumeDebounceMs?: number | undefined;
+}
+/** Read-only snapshot of the gate's current state. */
+export interface BufferGateSnapshot {
+    /** Whether the gate is currently open (accepting messages). */
+    readonly isOpen: boolean;
+    /** Number of messages dropped during the current or most recent suspension. */
+    readonly droppedCount: number;
+    /** Total messages dropped across all suspensions since creation. */
+    readonly totalDropped: number;
+    /** Number of times the gate has been suspended. */
+    readonly suspensionCount: number;
+}
+/** A response buffer gate instance. */
+export interface ResponseBufferGate {
+    /**
+     * Check whether a message should be processed.
+     * Returns `true` if the gate is open (message should be forwarded).
+     * Returns `false` if the gate is closed (message is dropped).
+     *
+     * Increments the drop counter on each rejection.
+     */
+    accept(): boolean;
+    /** Whether the gate is currently open. */
+    isOpen(): boolean;
+    /** Get a snapshot of the gate's current state. */
+    getSnapshot(): BufferGateSnapshot;
+    /** Dispose: unsubscribe from visibility events, clear timers. */
+    dispose(): void;
+}
+/**
+ * Create a new response buffer gate.
+ *
+ * Usage:
+ * ```ts
+ * const gate = createResponseBufferGate({
+ *   flushDownstream: [
+ *     () => throttle.flush(),
+ *     () => coalescer.flush(),
+ *     () => batcher.flush(),
+ *   ],
+ *   onResume: () => {
+ *     fetchPRDData();
+ *     fetchTaskUsage();
+ *   },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   if (!gate.accept()) return; // Dropped — tab is hidden
+ *   throttle.push(msg);
+ * };
+ * ```
+ */
+export declare function createResponseBufferGate(config: ResponseBufferGateConfig): ResponseBufferGate;

package/packages/web/dist/viewer/performance/response-buffer-gate.js

@@ -0,0 +1,170 @@
+/**
+ * Response buffer gate — suspends message pipeline during tab inactivity.
+ *
+ * Sits at the front of the WebSocket message pipeline to prevent memory
+ * buildup from accumulating response data while the browser tab is hidden.
+ * When the tab becomes inactive:
+ *
+ *   1. Flushes all pending data from downstream buffers (throttle, coalescer,
+ *      batcher) so they release references immediately.
+ *   2. Drops all subsequent incoming messages silently — no accumulation.
+ *   3. Tracks that messages were dropped during suspension.
+ *
+ * When the tab becomes visible again:
+ *
+ *   1. Opens the gate to accept new messages normally.
+ *   2. If any messages were dropped, calls `onResume` so the consumer can
+ *      trigger a single full reconciliation (e.g. fetchPRDData + fetchTaskUsage)
+ *      to restore data integrity.
+ *
+ * This module complements the polling-manager (which suspends fetch intervals)
+ * by also stopping the *response processing* side. Without this, WebSocket
+ * messages arriving during a background tab would still accumulate in the
+ * message-throttle pending arrays, coalescer batch, and update-batcher queue.
+ *
+ * Pipeline position:
+ *
+ *   raw WebSocket → **response-buffer-gate** → throttle → coalescer → batcher → render
+ *
+ * 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 response buffer gate.
+ *
+ * Usage:
+ * ```ts
+ * const gate = createResponseBufferGate({
+ *   flushDownstream: [
+ *     () => throttle.flush(),
+ *     () => coalescer.flush(),
+ *     () => batcher.flush(),
+ *   ],
+ *   onResume: () => {
+ *     fetchPRDData();
+ *     fetchTaskUsage();
+ *   },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   if (!gate.accept()) return; // Dropped — tab is hidden
+ *   throttle.push(msg);
+ * };
+ * ```
+ */
+export function createResponseBufferGate(config) {
+    const flushDownstream = config.flushDownstream;
+    const onResume = config.onResume;
+    const resumeDebounceMs = config.resumeDebounceMs ?? DEFAULT_RESUME_DEBOUNCE_MS;
+    // Start as visible; the initial-state check below may immediately suspend.
+    let open = true;
+    let droppedCount = 0;
+    let totalDropped = 0;
+    let suspensionCount = 0;
+    let resumeTimer = null;
+    let disposed = false;
+    function clearResumeTimer() {
+        if (resumeTimer !== null) {
+            clearTimeout(resumeTimer);
+            resumeTimer = null;
+        }
+    }
+    /** Flush all downstream buffers to release buffered data from memory. */
+    function flushAllDownstream() {
+        for (const flush of flushDownstream) {
+            try {
+                flush();
+            }
+            catch {
+                // Swallow errors from individual flushes.
+            }
+        }
+    }
+    /** Close the gate: flush downstream buffers and start dropping. */
+    function suspend() {
+        if (!open)
+            return;
+        open = false;
+        droppedCount = 0;
+        suspensionCount++;
+        // Flush downstream buffers to release buffered data from memory.
+        // This ensures the throttle's pending arrays, the coalescer's batch,
+        // and the batcher's queue are all cleared immediately.
+        flushAllDownstream();
+    }
+    /** Re-open the gate and trigger reconciliation if data was dropped. */
+    function resume() {
+        if (open)
+            return;
+        const hadDrops = droppedCount > 0;
+        open = true;
+        // Trigger reconciliation if any messages were lost during suspension.
+        // This ensures the UI shows the latest state from the server.
+        if (hadDrops) {
+            try {
+                onResume();
+            }
+            catch {
+                // Swallow errors from the resume callback.
+            }
+        }
+    }
+    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. This runs the
+    // full suspend path (flush + mark closed) even on initial creation.
+    if (!isTabVisible()) {
+        suspend();
+    }
+    // ─── Public methods ─────────────────────────────────────────────────
+    function accept() {
+        if (disposed)
+            return false;
+        if (!open) {
+            droppedCount++;
+            totalDropped++;
+            return false;
+        }
+        return true;
+    }
+    function isOpenFn() {
+        return open;
+    }
+    function getSnapshot() {
+        return {
+            isOpen: open,
+            droppedCount,
+            totalDropped,
+            suspensionCount,
+        };
+    }
+    function dispose() {
+        disposed = true;
+        clearResumeTimer();
+        unsubVisibility();
+    }
+    return { accept, isOpen: isOpenFn, getSnapshot, dispose };
+}
+//# sourceMappingURL=response-buffer-gate.js.map

package/packages/web/dist/viewer/performance/response-buffer-gate.js.map

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

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

@@ -0,0 +1,79 @@
+/**
+ * requestAnimationFrame-based update batching for rapid UI state changes.
+ *
+ * When multiple WebSocket messages trigger state updates in quick succession,
+ * this module batches them into a single animation frame to prevent unnecessary
+ * intermediate renders. All queued updaters are composed per-setter and applied
+ * once within one RAF callback, preserving final state consistency.
+ *
+ * Two operating modes:
+ *
+ *   **Enabled (default)** — updaters are queued and applied in the next RAF.
+ *   Multiple `schedule()` calls for the same setter are composed in arrival
+ *   order so the setter is invoked exactly once per frame. Different setters
+ *   are invoked independently within the same frame.
+ *
+ *   **Disabled** — updaters are applied synchronously on each `schedule()`
+ *   call, bypassing RAF entirely. Useful for debugging and testing where
+ *   immediate state visibility is needed.
+ *
+ * Pipeline position:
+ *
+ *   ... → coalescer.onMessage → updateBatcher.schedule(setter, updater) → RAF → render
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+/** Configuration for the update batcher. */
+export interface UpdateBatcherConfig {
+    /**
+     * When true, bypasses RAF batching and applies updates synchronously.
+     * Useful for debugging and testing.
+     * Default: false.
+     */
+    disabled?: boolean | undefined;
+}
+/** An update batcher instance. */
+export interface UpdateBatcher {
+    /**
+     * Schedule a state update to be applied in the next animation frame.
+     *
+     * Multiple updates for the same setter are composed in order: each updater
+     * receives the result of the previous, and the setter is called once with
+     * the final composed value — identical to sequential application.
+     *
+     * When batching is disabled, the setter is called immediately.
+     */
+    schedule<T>(setter: (updater: (prev: T) => T) => void, updater: (prev: T) => T): void;
+    /**
+     * Force-flush all pending updates synchronously. Cancels any pending RAF.
+     * No-op if no updates are pending.
+     */
+    flush(): void;
+    /** Whether updates are currently pending in the batch queue. */
+    hasPending(): boolean;
+    /** Dispose: cancel pending RAF, clear queue, ignore future schedules. */
+    dispose(): void;
+}
+/**
+ * Create a new update batcher.
+ *
+ * Usage:
+ * ```ts
+ * const batcher = createUpdateBatcher();
+ *
+ * // In a WebSocket message handler:
+ * coalescer.onMessage = (msg) => {
+ *   if (msg.type === "rex:item-updated") {
+ *     batcher.schedule(setData, (prev) => {
+ *       const newItems = applyItemUpdate(prev.items, msg.itemId, msg.updates);
+ *       return newItems === prev.items ? prev : { ...prev, items: newItems };
+ *     });
+ *   }
+ * };
+ *
+ * // On component unmount:
+ * batcher.dispose();
+ * ```
+ */
+export declare function createUpdateBatcher(config?: UpdateBatcherConfig): UpdateBatcher;

package/packages/web/dist/viewer/performance/update-batcher.js

@@ -0,0 +1,119 @@
+/**
+ * requestAnimationFrame-based update batching for rapid UI state changes.
+ *
+ * When multiple WebSocket messages trigger state updates in quick succession,
+ * this module batches them into a single animation frame to prevent unnecessary
+ * intermediate renders. All queued updaters are composed per-setter and applied
+ * once within one RAF callback, preserving final state consistency.
+ *
+ * Two operating modes:
+ *
+ *   **Enabled (default)** — updaters are queued and applied in the next RAF.
+ *   Multiple `schedule()` calls for the same setter are composed in arrival
+ *   order so the setter is invoked exactly once per frame. Different setters
+ *   are invoked independently within the same frame.
+ *
+ *   **Disabled** — updaters are applied synchronously on each `schedule()`
+ *   call, bypassing RAF entirely. Useful for debugging and testing where
+ *   immediate state visibility is needed.
+ *
+ * Pipeline position:
+ *
+ *   ... → coalescer.onMessage → updateBatcher.schedule(setter, updater) → RAF → render
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new update batcher.
+ *
+ * Usage:
+ * ```ts
+ * const batcher = createUpdateBatcher();
+ *
+ * // In a WebSocket message handler:
+ * coalescer.onMessage = (msg) => {
+ *   if (msg.type === "rex:item-updated") {
+ *     batcher.schedule(setData, (prev) => {
+ *       const newItems = applyItemUpdate(prev.items, msg.itemId, msg.updates);
+ *       return newItems === prev.items ? prev : { ...prev, items: newItems };
+ *     });
+ *   }
+ * };
+ *
+ * // On component unmount:
+ * batcher.dispose();
+ * ```
+ */
+export function createUpdateBatcher(config) {
+    const disabled = config?.disabled ?? false;
+    // Map from setter reference → array of updater functions.
+    // Using a Map preserves insertion order for deterministic flush ordering.
+    let queue = new Map();
+    let rafId = null;
+    let disposed = false;
+    function applyAll() {
+        const entries = queue;
+        queue = new Map();
+        rafId = null;
+        for (const entry of entries.values()) {
+            // Compose all updaters into a single function call.
+            // Each updater receives the output of the previous one.
+            const composed = (prev) => {
+                let current = prev;
+                for (const updater of entry.updaters) {
+                    current = updater(current);
+                }
+                return current;
+            };
+            entry.setter(composed);
+        }
+    }
+    function scheduleRAF() {
+        if (rafId !== null)
+            return; // Already scheduled
+        rafId = requestAnimationFrame(applyAll);
+    }
+    function cancelRAF() {
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    }
+    function schedule(setter, updater) {
+        if (disposed)
+            return;
+        // Disabled mode: apply immediately, no batching.
+        if (disabled) {
+            setter(updater);
+            return;
+        }
+        const key = setter;
+        let entry = queue.get(key);
+        if (!entry) {
+            entry = { setter: key, updaters: [] };
+            queue.set(key, entry);
+        }
+        entry.updaters.push(updater);
+        scheduleRAF();
+    }
+    function flush() {
+        if (disposed)
+            return;
+        if (queue.size === 0)
+            return;
+        cancelRAF();
+        applyAll();
+    }
+    function hasPending() {
+        return queue.size > 0;
+    }
+    function dispose() {
+        disposed = true;
+        cancelRAF();
+        queue = new Map();
+    }
+    return { schedule, flush, hasPending, dispose };
+}
+//# sourceMappingURL=update-batcher.js.map

package/packages/web/dist/viewer/performance/update-batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-batcher.js","sourceRoot":"","sources":["../../../src/viewer/performance/update-batcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAwDH,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA4B;IAC9D,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,KAAK,CAAC;IAE3C,0DAA0D;IAC1D,0EAA0E;IAC1E,IAAI,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,SAAS,QAAQ;QACf,MAAM,OAAO,GAAG,KAAK,CAAC;QACtB,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QAClB,KAAK,GAAG,IAAI,CAAC;QAEb,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,oDAAoD;YACpD,wDAAwD;YACxD,MAAM,QAAQ,GAAe,CAAC,IAAI,EAAE,EAAE;gBACpC,IAAI,OAAO,GAAG,IAAI,CAAC;gBACnB,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;oBACrC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC7B,CAAC;gBACD,OAAO,OAAO,CAAC;YACjB,CAAC,CAAC;YAEF,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,SAAS,WAAW;QAClB,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,oBAAoB;QAChD,KAAK,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,SAAS,SAAS;QAChB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,oBAAoB,CAAC,KAAK,CAAC,CAAC;YAC5B,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;IACH,CAAC;IAED,SAAS,QAAQ,CACf,MAAyC,EACzC,OAAuB;QAEvB,IAAI,QAAQ;YAAE,OAAO;QAErB,iDAAiD;QACjD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,CAAC,OAAO,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,MAAmB,CAAC;QAChC,IAAI,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YACtC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAqB,CAAC,CAAC;QAE3C,WAAW,EAAE,CAAC;IAChB,CAAC;IAED,SAAS,KAAK;QACZ,IAAI,QAAQ;YAAE,OAAO;QACrB,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAE7B,SAAS,EAAE,CAAC;QACZ,QAAQ,EAAE,CAAC;IACb,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,EAAE,CAAC;QACZ,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/packages/web/dist/viewer/polling/batched-tick-dispatcher.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+/** Function that computes the current formatted elapsed time string. */
+type ComputeFn = () => string;
+/** Preact state setter for the display value. */
+type SetDisplayFn = (value: string) => void;
+/** Mutable ref object (matches Preact's useRef shape). */
+interface MutableRef<T> {
+    current: T;
+}
+/** Read-only snapshot of the dispatcher's current state (for testing/monitoring). */
+export interface BatchedTickDispatcherState {
+    /** Number of active registrations. */
+    readonly registrationCount: number;
+    /** Whether a RAF callback is currently pending. */
+    readonly hasPendingRAF: boolean;
+    /** Number of state updates queued for the next RAF. */
+    readonly pendingUpdateCount: number;
+}
+/**
+ * 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 declare function registerTickUpdater(compute: ComputeFn, setDisplay: SetDisplayFn, lastValueRef: MutableRef<string>): () => void;
+/**
+ * Get the current state of the batched tick dispatcher (for testing/monitoring).
+ */
+export declare function getBatchedTickDispatcherState(): BatchedTickDispatcherState;
+/**
+ * Force-flush all pending RAF updates synchronously.
+ * Cancels any pending RAF. No-op if nothing is pending.
+ */
+export declare function flushBatchedTicks(): void;
+/**
+ * Reset all dispatcher state (for testing). Unsubscribes from the tick
+ * timer, cancels pending RAF, and clears all registrations.
+ */
+export declare function resetBatchedTickDispatcher(): void;
+export {};