@n-dx/core 0.1.0

package/packages/web/dist/viewer/messaging/message-coalescer.js

@@ -0,0 +1,121 @@
+/**
+ * WebSocket message coalescing for rapid sequential updates.
+ *
+ * When multiple WebSocket messages arrive in quick succession (e.g. a batch
+ * of rex:item-updated events during a bulk operation), this module batches
+ * them into a single flush to avoid redundant fetch calls.
+ *
+ * Two-callback design:
+ *
+ *   onMessage(msg)  — fires immediately for each message, enabling optimistic
+ *                     UI updates with no delay.
+ *   onFlush(batch)  — fires once per throttle window (trailing edge), after
+ *                     messages stop arriving. The batch includes all message
+ *                     types seen, counts per type, and the full ordered list.
+ *                     Consumers use this to trigger a single reconciliation
+ *                     (e.g. fetchPRDData + fetchTaskUsage) instead of N calls.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_WINDOW_MS = 150;
+const DEFAULT_MAX_BATCH_SIZE = 50;
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new message coalescer.
+ *
+ * Usage:
+ * ```ts
+ * const coalescer = createMessageCoalescer({
+ *   onMessage: (msg) => {
+ *     // Immediate optimistic update
+ *     if (msg.type === "rex:item-updated") applyItemUpdate(msg);
+ *   },
+ *   onFlush: (batch) => {
+ *     // Coalesced reconciliation — runs once per window
+ *     if (batch.types.has("rex:item-updated") || batch.types.has("rex:prd-changed")) {
+ *       fetchPRDData();
+ *       fetchTaskUsage();
+ *     }
+ *   },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   coalescer.push(msg);
+ * };
+ * ```
+ */
+export function createMessageCoalescer(config) {
+    const windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    const maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+    const onFlush = config.onFlush;
+    const onMessage = config.onMessage ?? null;
+    let messages = [];
+    let types = new Set();
+    let countByType = new Map();
+    let timer = null;
+    let disposed = false;
+    function clearTimer() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function buildBatch() {
+        return {
+            types,
+            countByType,
+            messages,
+            size: messages.length,
+        };
+    }
+    function resetBatch() {
+        messages = [];
+        types = new Set();
+        countByType = new Map();
+    }
+    function doFlush() {
+        clearTimer();
+        if (messages.length === 0)
+            return;
+        const batch = buildBatch();
+        resetBatch();
+        onFlush(batch);
+    }
+    function scheduleFlush() {
+        clearTimer();
+        timer = setTimeout(doFlush, windowMs);
+    }
+    function push(msg) {
+        if (disposed)
+            return;
+        // Immediate per-message callback (for optimistic updates)
+        if (onMessage)
+            onMessage(msg);
+        // Accumulate into the current batch
+        messages.push(msg);
+        types.add(msg.type);
+        countByType.set(msg.type, (countByType.get(msg.type) ?? 0) + 1);
+        // Force flush if batch size limit reached
+        if (messages.length >= maxBatchSize) {
+            doFlush();
+            return;
+        }
+        // Reset the trailing-edge debounce timer
+        scheduleFlush();
+    }
+    function flush() {
+        if (disposed)
+            return;
+        doFlush();
+    }
+    function dispose() {
+        disposed = true;
+        clearTimer();
+        resetBatch();
+    }
+    return { push, flush, dispose };
+}
+//# sourceMappingURL=message-coalescer.js.map

package/packages/web/dist/viewer/messaging/message-coalescer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-coalescer.js","sourceRoot":"","sources":["../../../src/viewer/messaging/message-coalescer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA6DH,gFAAgF;AAEhF,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAElC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA8B;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACtD,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC;IAE3C,IAAI,QAAQ,GAAsB,EAAE,CAAC;IACrC,IAAI,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,IAAI,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,SAAS,UAAU;QACjB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;IACH,CAAC;IAED,SAAS,UAAU;QACjB,OAAO;YACL,KAAK;YACL,WAAW;YACX,QAAQ;YACR,IAAI,EAAE,QAAQ,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC;IAED,SAAS,UAAU;QACjB,QAAQ,GAAG,EAAE,CAAC;QACd,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAC1B,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,CAAC;IAED,SAAS,OAAO;QACd,UAAU,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAElC,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,UAAU,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IAED,SAAS,aAAa;QACpB,UAAU,EAAE,CAAC;QACb,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,SAAS,IAAI,CAAC,GAAoB;QAChC,IAAI,QAAQ;YAAE,OAAO;QAErB,0DAA0D;QAC1D,IAAI,SAAS;YAAE,SAAS,CAAC,GAAG,CAAC,CAAC;QAE9B,oCAAoC;QACpC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAEhE,0CAA0C;QAC1C,IAAI,QAAQ,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC;YACpC,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QAED,yCAAyC;QACzC,aAAa,EAAE,CAAC;IAClB,CAAC;IAED,SAAS,KAAK;QACZ,IAAI,QAAQ;YAAE,OAAO;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,GAAG,IAAI,CAAC;QAChB,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,CAAC;IACf,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC"}

package/packages/web/dist/viewer/messaging/message-throttle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Per-type WebSocket message throttle with configurable debounce.
+ *
+ * Sits between the raw WebSocket and downstream handlers (e.g. the message
+ * coalescer) to provide per-message-type trailing-edge debouncing. Each
+ * configured type gets its own independent timer and delay, so different
+ * message types can be throttled at different rates.
+ *
+ * Design decisions:
+ *
+ *   - **Trailing-edge debounce** — messages accumulate during the delay
+ *     window and are forwarded once the timer fires. New messages of the
+ *     same type reset the timer (like the coalescer, but per-type).
+ *
+ *   - **Per-type isolation** — timers are fully independent. A burst of
+ *     rex:item-updated messages doesn't delay rex:prd-changed.
+ *
+ *   - **Bounded memory** — maxPendingPerType caps how many messages can
+ *     accumulate per type before a force-flush, preventing unbounded growth
+ *     during sustained bursts.
+ *
+ *   - **Pass-through** — message types not in the throttledTypes set are
+ *     forwarded immediately with zero delay, preserving low-latency for
+ *     types that don't need throttling.
+ *
+ * Standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+import type { ParsedWSMessage } from "./message-coalescer.js";
+/** Configuration for the throttled message handler. */
+export interface ThrottledHandlerConfig {
+    /**
+     * Called for each message after its type's debounce window expires.
+     * For unthrottled types, called immediately.
+     */
+    onMessage: (msg: ParsedWSMessage) => void;
+    /**
+     * Default debounce delay in milliseconds for throttled types
+     * that don't have an explicit entry in `delays`.
+     * Default: 250ms.
+     */
+    defaultDelayMs?: number | undefined;
+    /**
+     * Per-message-type delay overrides. Keys are message type strings,
+     * values are delay in milliseconds. Types not listed here fall back
+     * to `defaultDelayMs`.
+     */
+    delays?: Partial<Record<string, number>> | undefined;
+    /**
+     * Message types to throttle. Types not in this set pass through
+     * immediately to `onMessage`.
+     *
+     * If undefined (not provided), ALL types are throttled.
+     * If an empty array/set, NO types are throttled (all pass through).
+     */
+    throttledTypes?: ReadonlySet<string> | readonly string[] | undefined;
+    /**
+     * Maximum pending messages per type before force-flushing.
+     * Prevents unbounded memory growth during sustained bursts.
+     * Default: 20.
+     */
+    maxPendingPerType?: number | undefined;
+}
+/** A throttled message handler instance. */
+export interface MessageThrottle {
+    /** Push a message through the throttle. */
+    push(msg: ParsedWSMessage): void;
+    /** Force-flush all pending messages across all types immediately. */
+    flush(): void;
+    /** Dispose: cancel all timers, clear all pending, ignore future pushes. */
+    dispose(): void;
+}
+/**
+ * Create a new per-type message throttle.
+ *
+ * Usage:
+ * ```ts
+ * const throttle = createMessageThrottle({
+ *   onMessage: (msg) => coalescer.push(msg),
+ *   defaultDelayMs: 250,
+ *   delays: {
+ *     "rex:prd-changed": 500,    // slow — heavy reconciliation
+ *     "rex:item-updated": 150,   // fast — targeted updates
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated", "rex:item-deleted"],
+ *   maxPendingPerType: 20,
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   throttle.push(msg);
+ * };
+ * ```
+ */
+export declare function createMessageThrottle(config: ThrottledHandlerConfig): MessageThrottle;

package/packages/web/dist/viewer/messaging/message-throttle.js

@@ -0,0 +1,147 @@
+/**
+ * Per-type WebSocket message throttle with configurable debounce.
+ *
+ * Sits between the raw WebSocket and downstream handlers (e.g. the message
+ * coalescer) to provide per-message-type trailing-edge debouncing. Each
+ * configured type gets its own independent timer and delay, so different
+ * message types can be throttled at different rates.
+ *
+ * Design decisions:
+ *
+ *   - **Trailing-edge debounce** — messages accumulate during the delay
+ *     window and are forwarded once the timer fires. New messages of the
+ *     same type reset the timer (like the coalescer, but per-type).
+ *
+ *   - **Per-type isolation** — timers are fully independent. A burst of
+ *     rex:item-updated messages doesn't delay rex:prd-changed.
+ *
+ *   - **Bounded memory** — maxPendingPerType caps how many messages can
+ *     accumulate per type before a force-flush, preventing unbounded growth
+ *     during sustained bursts.
+ *
+ *   - **Pass-through** — message types not in the throttledTypes set are
+ *     forwarded immediately with zero delay, preserving low-latency for
+ *     types that don't need throttling.
+ *
+ * Standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_DELAY_MS = 250;
+const DEFAULT_MAX_PENDING_PER_TYPE = 20;
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new per-type message throttle.
+ *
+ * Usage:
+ * ```ts
+ * const throttle = createMessageThrottle({
+ *   onMessage: (msg) => coalescer.push(msg),
+ *   defaultDelayMs: 250,
+ *   delays: {
+ *     "rex:prd-changed": 500,    // slow — heavy reconciliation
+ *     "rex:item-updated": 150,   // fast — targeted updates
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated", "rex:item-deleted"],
+ *   maxPendingPerType: 20,
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   throttle.push(msg);
+ * };
+ * ```
+ */
+export function createMessageThrottle(config) {
+    const onMessage = config.onMessage;
+    const defaultDelayMs = config.defaultDelayMs ?? DEFAULT_DELAY_MS;
+    const delays = config.delays ?? {};
+    const maxPending = config.maxPendingPerType ?? DEFAULT_MAX_PENDING_PER_TYPE;
+    // Normalize throttledTypes into a Set, or null to mean "all types throttled"
+    const throttledTypes = config.throttledTypes === undefined
+        ? null // all types throttled
+        : config.throttledTypes instanceof Set
+            ? config.throttledTypes
+            : new Set(config.throttledTypes);
+    // Per-type state map
+    const stateByType = new Map();
+    let disposed = false;
+    function isThrottled(type) {
+        if (throttledTypes === null)
+            return true; // all throttled
+        return throttledTypes.has(type);
+    }
+    function getDelay(type) {
+        return delays[type] ?? defaultDelayMs;
+    }
+    function getOrCreateState(type) {
+        let state = stateByType.get(type);
+        if (!state) {
+            state = { pending: [], timer: null };
+            stateByType.set(type, state);
+        }
+        return state;
+    }
+    function clearTypeTimer(state) {
+        if (state.timer !== null) {
+            clearTimeout(state.timer);
+            state.timer = null;
+        }
+    }
+    function flushType(type) {
+        const state = stateByType.get(type);
+        if (!state || state.pending.length === 0)
+            return;
+        clearTypeTimer(state);
+        // Forward all pending messages for this type
+        const messages = state.pending;
+        state.pending = [];
+        for (const msg of messages) {
+            onMessage(msg);
+        }
+    }
+    function scheduleFlush(type, state) {
+        clearTypeTimer(state);
+        state.timer = setTimeout(() => {
+            state.timer = null;
+            flushType(type);
+        }, getDelay(type));
+    }
+    function push(msg) {
+        if (disposed)
+            return;
+        const type = msg.type;
+        // Pass-through for unthrottled types
+        if (!isThrottled(type)) {
+            onMessage(msg);
+            return;
+        }
+        // Accumulate into the type's pending queue
+        const state = getOrCreateState(type);
+        state.pending.push(msg);
+        // Force-flush if pending count exceeds the limit
+        if (state.pending.length >= maxPending) {
+            flushType(type);
+            return;
+        }
+        // Reset the trailing-edge debounce timer for this type
+        scheduleFlush(type, state);
+    }
+    function flush() {
+        if (disposed)
+            return;
+        for (const type of stateByType.keys()) {
+            flushType(type);
+        }
+    }
+    function dispose() {
+        disposed = true;
+        for (const state of stateByType.values()) {
+            clearTypeTimer(state);
+            state.pending = [];
+        }
+        stateByType.clear();
+    }
+    return { push, flush, dispose };
+}
+//# sourceMappingURL=message-throttle.js.map

package/packages/web/dist/viewer/messaging/message-throttle.js.map

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

package/packages/web/dist/viewer/messaging/request-dedup.d.ts

@@ -0,0 +1,43 @@
+/**
+ * In-flight request deduplication.
+ *
+ * Wraps an async function so that concurrent callers share a single in-flight
+ * promise instead of triggering duplicate API calls. When the underlying
+ * request completes (success or failure), tracking is cleared and the next
+ * call starts a fresh request.
+ *
+ * Typical use: prevent duplicate `fetchPRDData` calls when a WebSocket
+ * message arrives while a polling request is already in progress.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+/** A deduplicating wrapper around an async function. */
+export interface RequestDedup<T = void> {
+    /**
+     * Execute the wrapped function. If a request is already in-flight,
+     * returns the existing promise instead of starting a new one.
+     */
+    execute(): Promise<T>;
+    /** Whether a request is currently in-flight. */
+    isInFlight(): boolean;
+    /** Clear in-flight tracking state. Safe to call multiple times. */
+    dispose(): void;
+}
+/**
+ * Create a deduplicating wrapper for an async function.
+ *
+ * Usage:
+ * ```ts
+ * const dedupedFetch = createRequestDedup(() => fetch("/data/prd.json").then(r => r.json()));
+ *
+ * // These two calls share one underlying fetch:
+ * dedupedFetch.execute();  // starts the request
+ * dedupedFetch.execute();  // returns the same promise
+ *
+ * // After the request settles, the next call starts fresh:
+ * await dedupedFetch.execute();
+ * dedupedFetch.execute();  // new request
+ * ```
+ */
+export declare function createRequestDedup<T = void>(fn: () => Promise<T>): RequestDedup<T>;

package/packages/web/dist/viewer/messaging/request-dedup.js

@@ -0,0 +1,55 @@
+/**
+ * In-flight request deduplication.
+ *
+ * Wraps an async function so that concurrent callers share a single in-flight
+ * promise instead of triggering duplicate API calls. When the underlying
+ * request completes (success or failure), tracking is cleared and the next
+ * call starts a fresh request.
+ *
+ * Typical use: prevent duplicate `fetchPRDData` calls when a WebSocket
+ * message arrives while a polling request is already in progress.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a deduplicating wrapper for an async function.
+ *
+ * Usage:
+ * ```ts
+ * const dedupedFetch = createRequestDedup(() => fetch("/data/prd.json").then(r => r.json()));
+ *
+ * // These two calls share one underlying fetch:
+ * dedupedFetch.execute();  // starts the request
+ * dedupedFetch.execute();  // returns the same promise
+ *
+ * // After the request settles, the next call starts fresh:
+ * await dedupedFetch.execute();
+ * dedupedFetch.execute();  // new request
+ * ```
+ */
+export function createRequestDedup(fn) {
+    let inflight = null;
+    function execute() {
+        if (inflight !== null) {
+            return inflight;
+        }
+        inflight = fn().then((value) => {
+            inflight = null;
+            return value;
+        }, (err) => {
+            inflight = null;
+            throw err;
+        });
+        return inflight;
+    }
+    function isInFlight() {
+        return inflight !== null;
+    }
+    function dispose() {
+        inflight = null;
+    }
+    return { execute, isInFlight, dispose };
+}
+//# sourceMappingURL=request-dedup.js.map

package/packages/web/dist/viewer/messaging/request-dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-dedup.js","sourceRoot":"","sources":["../../../src/viewer/messaging/request-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmBH,gFAAgF;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAoB;IAEpB,IAAI,QAAQ,GAAsB,IAAI,CAAC;IAEvC,SAAS,OAAO;QACd,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,QAAQ,GAAG,EAAE,EAAE,CAAC,IAAI,CAClB,CAAC,KAAK,EAAE,EAAE;YACR,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,KAAK,CAAC;QACf,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;YACN,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,GAAG,CAAC;QACZ,CAAC,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,QAAQ,KAAK,IAAI,CAAC;IAC3B,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC"}

package/packages/web/dist/viewer/messaging/ws-pipeline.d.ts

@@ -0,0 +1,85 @@
+/**
+ * WebSocket message processing pipeline — composed throttle + coalescer.
+ *
+ * Both `usePRDWebSocket` and `useProjectStatus` build the same two-layer
+ * pipeline: per-type throttle → message coalescer. This module captures
+ * that pattern as a single factory, reducing the coupling surface from
+ * two individual messaging imports to one composed import.
+ *
+ * The pipeline handles:
+ *   1. **Throttle** — per-type trailing-edge debounce with independent timers.
+ *   2. **Coalescer** — batches throttled output into a single flush.
+ *
+ * Consumers configure which message types to throttle, their delays, and
+ * provide an `onMessage` (immediate/optimistic) and `onFlush` (batched
+ * reconciliation) callback.
+ *
+ * Standalone module with zero framework dependencies.
+ */
+import { type ParsedWSMessage, type CoalescedBatch } from "./message-coalescer.js";
+/** Configuration for the WebSocket message pipeline. */
+export interface WSPipelineConfig {
+    /**
+     * Called once per debounce window with the coalesced batch.
+     * Use this to trigger reconciliation fetches.
+     */
+    onFlush: (batch: CoalescedBatch) => void;
+    /**
+     * Called immediately for each incoming message (before throttling/batching).
+     * Use this for optimistic local state updates.
+     */
+    onMessage?: ((msg: ParsedWSMessage) => void) | undefined;
+    /**
+     * Default throttle debounce delay in milliseconds.
+     * Default: 250ms.
+     */
+    defaultDelayMs?: number | undefined;
+    /**
+     * Per-message-type delay overrides for the throttle layer.
+     */
+    delays?: Partial<Record<string, number>> | undefined;
+    /**
+     * Message types to throttle. Types not in this set pass through
+     * to the coalescer immediately (zero delay).
+     */
+    throttledTypes?: readonly string[] | undefined;
+    /**
+     * Maximum pending messages per type before force-flushing the throttle.
+     * Default: 20.
+     */
+    maxPendingPerType?: number | undefined;
+    /**
+     * Coalescer trailing-edge debounce window in milliseconds.
+     * Default: 150ms.
+     */
+    coalescerWindowMs?: number | undefined;
+}
+/** A composed WebSocket message pipeline (throttle → coalescer). */
+export interface WSPipeline {
+    /** Push a parsed WebSocket message into the pipeline. */
+    push(msg: ParsedWSMessage): void;
+    /** Force-flush both throttle and coalescer. */
+    flush(): void;
+    /** Dispose all timers and state. Safe to call multiple times. */
+    dispose(): void;
+}
+/**
+ * Create a WebSocket message processing pipeline.
+ *
+ * Usage:
+ * ```ts
+ * const pipeline = createWSPipeline({
+ *   onMessage: (msg) => applyOptimisticUpdate(msg),
+ *   onFlush: (batch) => {
+ *     if (batch.types.has("rex:prd-changed")) fetchPRDData();
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated"],
+ *   delays: { "rex:prd-changed": 300, "rex:item-updated": 200 },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   pipeline.push(JSON.parse(event.data));
+ * };
+ * ```
+ */
+export declare function createWSPipeline(config: WSPipelineConfig): WSPipeline;

package/packages/web/dist/viewer/messaging/ws-pipeline.js

@@ -0,0 +1,68 @@
+/**
+ * WebSocket message processing pipeline — composed throttle + coalescer.
+ *
+ * Both `usePRDWebSocket` and `useProjectStatus` build the same two-layer
+ * pipeline: per-type throttle → message coalescer. This module captures
+ * that pattern as a single factory, reducing the coupling surface from
+ * two individual messaging imports to one composed import.
+ *
+ * The pipeline handles:
+ *   1. **Throttle** — per-type trailing-edge debounce with independent timers.
+ *   2. **Coalescer** — batches throttled output into a single flush.
+ *
+ * Consumers configure which message types to throttle, their delays, and
+ * provide an `onMessage` (immediate/optimistic) and `onFlush` (batched
+ * reconciliation) callback.
+ *
+ * Standalone module with zero framework dependencies.
+ */
+import { createMessageThrottle } from "./message-throttle.js";
+import { createMessageCoalescer } from "./message-coalescer.js";
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a WebSocket message processing pipeline.
+ *
+ * Usage:
+ * ```ts
+ * const pipeline = createWSPipeline({
+ *   onMessage: (msg) => applyOptimisticUpdate(msg),
+ *   onFlush: (batch) => {
+ *     if (batch.types.has("rex:prd-changed")) fetchPRDData();
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated"],
+ *   delays: { "rex:prd-changed": 300, "rex:item-updated": 200 },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   pipeline.push(JSON.parse(event.data));
+ * };
+ * ```
+ */
+export function createWSPipeline(config) {
+    const coalescer = createMessageCoalescer({
+        onMessage: config.onMessage,
+        onFlush: config.onFlush,
+        windowMs: config.coalescerWindowMs,
+    });
+    const throttle = createMessageThrottle({
+        onMessage: (msg) => coalescer.push(msg),
+        defaultDelayMs: config.defaultDelayMs,
+        delays: config.delays,
+        throttledTypes: config.throttledTypes,
+        maxPendingPerType: config.maxPendingPerType,
+    });
+    return {
+        push(msg) {
+            throttle.push(msg);
+        },
+        flush() {
+            throttle.flush();
+            coalescer.flush();
+        },
+        dispose() {
+            throttle.dispose();
+            coalescer.dispose();
+        },
+    };
+}
+//# sourceMappingURL=ws-pipeline.js.map

package/packages/web/dist/viewer/messaging/ws-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-pipeline.js","sourceRoot":"","sources":["../../../src/viewer/messaging/ws-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,qBAAqB,EAAwB,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAoE,MAAM,wBAAwB,CAAC;AA0DlI,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,MAAM,SAAS,GAAqB,sBAAsB,CAAC;QACzD,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,iBAAiB;KACnC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAoB,qBAAqB,CAAC;QACtD,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;QACvC,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;KAC5C,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,CAAC,GAAoB;YACvB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,KAAK;YACH,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,SAAS,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;QAED,OAAO;YACL,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,SAAS,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/packages/web/dist/viewer/performance/crash-detector-test-support.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Test-only constants and helpers for crash-detector.ts.
+ *
+ * Separated from the production module to keep the public API surface
+ * clean and avoid bundling internal implementation details into production.
+ *
+ * @internal Only import this file from test code.
+ */
+export declare const HEARTBEAT_KEY = "ndx-crash-heartbeat";
+export declare const NAV_STATE_KEY = "ndx-crash-nav-state";
+export declare const CRASH_HISTORY_KEY = "ndx-crash-history";
+export declare const RECOVERY_SHOWN_KEY = "ndx-crash-recovery-shown";
+export declare const CRASH_LOOP_WINDOW_MS: number;
+export declare const CRASH_LOOP_THRESHOLD = 2;
+export declare const MAX_CRASH_HISTORY = 10;

package/packages/web/dist/viewer/performance/crash-detector-test-support.js

@@ -0,0 +1,19 @@
+/**
+ * Test-only constants and helpers for crash-detector.ts.
+ *
+ * Separated from the production module to keep the public API surface
+ * clean and avoid bundling internal implementation details into production.
+ *
+ * @internal Only import this file from test code.
+ */
+// Re-export the storage key constants so tests can verify storage behavior
+// without coupling to the production module's internal naming.
+export const HEARTBEAT_KEY = "ndx-crash-heartbeat";
+export const NAV_STATE_KEY = "ndx-crash-nav-state";
+export const CRASH_HISTORY_KEY = "ndx-crash-history";
+export const RECOVERY_SHOWN_KEY = "ndx-crash-recovery-shown";
+// Threshold constants for assertions
+export const CRASH_LOOP_WINDOW_MS = 5 * 60 * 1000;
+export const CRASH_LOOP_THRESHOLD = 2;
+export const MAX_CRASH_HISTORY = 10;
+//# sourceMappingURL=crash-detector-test-support.js.map