@n-dx/web 0.1.0

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

@@ -0,0 +1,43 @@
+/**
+ * Messaging integration layer — stable public interface for flow control.
+ *
+ * ## Responsibility boundary
+ *
+ * This barrel is the **only sanctioned import path** for viewer-to-server
+ * messaging utilities. It isolates consumers (hooks, components) from the
+ * internal module structure of the messaging zone. If an internal file is
+ * renamed, split, or merged, consumers are unaffected as long as this
+ * barrel's exports remain stable.
+ *
+ * ## Import rules
+ *
+ * - **Consumers** (hooks, components, views) → import from this barrel.
+ * - **Messaging internals** (pipeline files) → may import siblings directly.
+ * - **Type-only imports** are exempt (erased at compile time).
+ *
+ * ## Exports
+ *
+ * **Composed pipelines (preferred for new consumers):**
+ *   - **WSPipeline** — throttle → coalescer chain for WebSocket messages.
+ *   - **FetchPipeline** — rate limiter → dedup chain for API fetch calls.
+ *
+ * **Primitives (for custom composition only):**
+ *   - **MessageCoalescer** — batches rapid sequential WebSocket messages
+ *     into a single flush to avoid redundant fetch calls.
+ *   - **MessageThrottle** — per-type trailing-edge debounce with independent
+ *     timers, so different message types throttle at different rates.
+ *   - **CallRateLimiter** — caps outbound API call frequency with automatic
+ *     queue draining.
+ *   - **RequestDedup** — deduplicates in-flight requests by key, returning
+ *     the same promise to all concurrent callers.
+ *
+ * New consumers should prefer the composed pipelines unless they need
+ * custom composition. All consumers should import from this barrel rather
+ * than individual implementation files.
+ */
+export { createWSPipeline, type WSPipeline, type WSPipelineConfig, } from "./ws-pipeline.js";
+export { createFetchPipeline, type FetchPipeline, type FetchPipelineConfig, } from "./fetch-pipeline.js";
+export { createCallRateLimiter, type CallRateLimiter, type CallRateLimiterConfig, } from "./call-rate-limiter.js";
+export { createMessageCoalescer, type MessageCoalescer, type MessageCoalescerConfig, type ParsedWSMessage, type CoalescedBatch, } from "./message-coalescer.js";
+export { createMessageThrottle, type MessageThrottle, type ThrottledHandlerConfig, } from "./message-throttle.js";
+export { createRequestDedup, type RequestDedup, } from "./request-dedup.js";

package/dist/viewer/messaging/index.js

@@ -0,0 +1,46 @@
+/**
+ * Messaging integration layer — stable public interface for flow control.
+ *
+ * ## Responsibility boundary
+ *
+ * This barrel is the **only sanctioned import path** for viewer-to-server
+ * messaging utilities. It isolates consumers (hooks, components) from the
+ * internal module structure of the messaging zone. If an internal file is
+ * renamed, split, or merged, consumers are unaffected as long as this
+ * barrel's exports remain stable.
+ *
+ * ## Import rules
+ *
+ * - **Consumers** (hooks, components, views) → import from this barrel.
+ * - **Messaging internals** (pipeline files) → may import siblings directly.
+ * - **Type-only imports** are exempt (erased at compile time).
+ *
+ * ## Exports
+ *
+ * **Composed pipelines (preferred for new consumers):**
+ *   - **WSPipeline** — throttle → coalescer chain for WebSocket messages.
+ *   - **FetchPipeline** — rate limiter → dedup chain for API fetch calls.
+ *
+ * **Primitives (for custom composition only):**
+ *   - **MessageCoalescer** — batches rapid sequential WebSocket messages
+ *     into a single flush to avoid redundant fetch calls.
+ *   - **MessageThrottle** — per-type trailing-edge debounce with independent
+ *     timers, so different message types throttle at different rates.
+ *   - **CallRateLimiter** — caps outbound API call frequency with automatic
+ *     queue draining.
+ *   - **RequestDedup** — deduplicates in-flight requests by key, returning
+ *     the same promise to all concurrent callers.
+ *
+ * New consumers should prefer the composed pipelines unless they need
+ * custom composition. All consumers should import from this barrel rather
+ * than individual implementation files.
+ */
+// ── Composed pipelines (prefer these for new consumers) ──────────
+export { createWSPipeline, } from "./ws-pipeline.js";
+export { createFetchPipeline, } from "./fetch-pipeline.js";
+// ── Primitives (for custom composition) ──────────────────────────
+export { createCallRateLimiter, } from "./call-rate-limiter.js";
+export { createMessageCoalescer, } from "./message-coalescer.js";
+export { createMessageThrottle, } from "./message-throttle.js";
+export { createRequestDedup, } from "./request-dedup.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/viewer/messaging/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,oEAAoE;AAEpE,OAAO,EACL,gBAAgB,GAGjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAE7B,oEAAoE;AAEpE,OAAO,EACL,qBAAqB,GAGtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,sBAAsB,GAKvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,qBAAqB,GAGtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC"}

package/dist/viewer/messaging/message-coalescer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.).
+ */
+/** A parsed WebSocket message. Minimum requirement: a `type` string. */
+export interface ParsedWSMessage {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+/** The coalesced batch delivered to onFlush. */
+export interface CoalescedBatch {
+    /** Deduplicated set of message types in this batch. */
+    readonly types: Set<string>;
+    /** Per-type count of messages in this batch. */
+    readonly countByType: Map<string, number>;
+    /** All messages in arrival order — no data loss. */
+    readonly messages: readonly ParsedWSMessage[];
+    /** Total number of messages. Convenience alias for messages.length. */
+    readonly size: number;
+}
+/** Configuration for the message coalescer. */
+export interface MessageCoalescerConfig {
+    /**
+     * Called once per throttle window with the coalesced batch.
+     * Use this to trigger reconciliation fetches.
+     */
+    onFlush: (batch: CoalescedBatch) => void;
+    /**
+     * Called immediately for each incoming message (before batching).
+     * Use this for optimistic local state updates that should not be delayed.
+     */
+    onMessage?: ((msg: ParsedWSMessage) => void) | undefined;
+    /**
+     * Trailing-edge debounce window in milliseconds.
+     * Messages arriving within this window are coalesced into one flush.
+     * Default: 150ms.
+     */
+    windowMs?: number | undefined;
+    /**
+     * Maximum number of messages to accumulate before forcing a flush.
+     * Prevents unbounded memory growth during sustained bursts.
+     * Default: 50.
+     */
+    maxBatchSize?: number | undefined;
+}
+/** A message coalescer instance. */
+export interface MessageCoalescer {
+    /** Push a new message into the coalescer. */
+    push(msg: ParsedWSMessage): void;
+    /** Force-flush the current batch immediately. No-op if empty. */
+    flush(): void;
+    /** Dispose: cancel timers, clear batch, ignore future pushes. */
+    dispose(): void;
+}
+/**
+ * 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 declare function createMessageCoalescer(config: MessageCoalescerConfig): MessageCoalescer;

package/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/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/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/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/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/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/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/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"}