@hedwigjs/broker 0.1.0

package/dist/index.cjs

@@ -0,0 +1,2238 @@
+'use strict';
+
+// src/core/utils/matchPattern.ts
+function matchPattern(topic, pattern) {
+  if (pattern === "*") return true;
+  if (topic === pattern) return true;
+  if (!pattern.includes("*")) return false;
+  const regexPattern = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${regexPattern}$`).test(topic);
+}
+function matchesAnyPattern(topic, patterns) {
+  return patterns.some((pattern) => matchPattern(topic, pattern));
+}
+
+// src/core/bridge/Bridge.ts
+var Bridge = class {
+  #inject;
+  #transport;
+  #patterns;
+  #unsubscribe = null;
+  #logger;
+  constructor(inject, config, logger) {
+    this.#inject = inject;
+    this.#transport = config.transport;
+    this.#patterns = config.forward;
+    this.#logger = logger;
+    this.#unsubscribe = this.#transport.onMessage((data) => {
+      this.#handleIncoming(data);
+    });
+  }
+  get forwardPatterns() {
+    return this.#patterns;
+  }
+  /**
+   * Human-friendly transport class name, derived from the constructor —
+   * `WebSocket` for `WebSocketTransport`, etc. Used by DevTools to label
+   * bridges. `undefined` for anonymous-class transports.
+   */
+  get transportKind() {
+    const raw = this.#transport.constructor?.name;
+    if (!raw) return void 0;
+    return raw.endsWith("Transport") ? raw.slice(0, -"Transport".length) : raw;
+  }
+  /**
+   * Check if topic matches forward patterns
+   */
+  shouldForward(topic) {
+    return matchesAnyPattern(topic, this.#patterns);
+  }
+  /**
+   * Send message to transport (OUTBOUND)
+   * Called by BrokerCore when message matches forward patterns
+   */
+  send(message) {
+    this.#transport.send(message);
+  }
+  /**
+   * Handle incoming message from transport (INBOUND)
+   * Parse and inject into broker
+   */
+  #handleIncoming(data) {
+    const message = this.#parseMessage(data);
+    if (!message) return;
+    if (!this.shouldForward(message.topic)) return;
+    this.#inject(
+      message.topic,
+      message.source,
+      message.target,
+      message.data
+    );
+  }
+  /**
+   * Parse raw data into Message object
+   */
+  #parseMessage(data) {
+    try {
+      const message = typeof data === "string" ? JSON.parse(data) : data;
+      if (!message || typeof message !== "object") return null;
+      if (!message.topic || typeof message.topic !== "string") return null;
+      return message;
+    } catch (error) {
+      this.#logger.error("bridge.message.parse_failed", { error });
+      return null;
+    }
+  }
+  /**
+   * Cleanup: stop listening and destroy transport
+   */
+  destroy() {
+    this.#unsubscribe?.();
+    this.#unsubscribe = null;
+    this.#transport.destroy();
+  }
+};
+
+// src/core/routing/RoutingResult.ts
+var RoutingReason = {
+  DELIVERED: "DELIVERED",
+  DISPATCHED: "DISPATCHED",
+  REPLAY_DELIVERED: "REPLAY_DELIVERED",
+  HOOK_REJECTED: "HOOK_REJECTED",
+  NO_SUBSCRIBERS: "NO_SUBSCRIBERS",
+  NOT_SUBSCRIBED: "NOT_SUBSCRIBED",
+  HANDLER_FAILED: "HANDLER_FAILED",
+  BROKER_DESTROYED: "BROKER_DESTROYED"
+};
+var RoutingResult = class _RoutingResult {
+  status;
+  reason;
+  message;
+  timestamp;
+  /** Recipient client ID — set for unicast, undefined for multicast. */
+  recipientId;
+  /** All recipient client IDs — set for multicast, undefined for unicast. */
+  recipientIds;
+  data;
+  constructor(status, reason, message, recipientId, data, recipientIds) {
+    this.status = status;
+    this.reason = reason;
+    this.message = message;
+    this.timestamp = Date.now();
+    this.recipientId = recipientId;
+    this.recipientIds = recipientIds;
+    this.data = data;
+    Object.freeze(this);
+  }
+  /**
+   * @param status - ACK for success, NACK for failure
+   * @param reason - Machine-readable reason code (use RoutingReason constants)
+   * @param message - Human-readable result description
+   * @param recipientId - Recipient client ID (unicast only)
+   * @param data - Response data from handler (Request-Reply pattern only)
+   * @param recipientIds - All recipient client IDs (multicast only)
+   */
+  static create(status, reason, message, recipientId, data, recipientIds) {
+    return new _RoutingResult(status, reason, message, recipientId, data, recipientIds);
+  }
+};
+
+// src/core/routing/Router.ts
+var Router = class {
+  #subscriptions;
+  #logger;
+  constructor(subscriptions, logger) {
+    this.#subscriptions = subscriptions;
+    this.#logger = logger;
+  }
+  /**
+   * Route unicast message to specific recipient.
+   *
+   * If the recipient registered multiple handlers on the topic, the FIRST
+   * one (in registration order) receives the message and its return value
+   * is captured. Multi-handler unicast is not a supported responder pattern
+   * — callers that expect a single response should keep unicast slots to
+   * one handler.
+   */
+  async unicast(message, recipient) {
+    if (!this.#subscriptions.isSubscribed(recipient, message.topic)) {
+      return RoutingResult.create(
+        "NACK",
+        RoutingReason.NOT_SUBSCRIBED,
+        `Client '${recipient}' not subscribed to '${message.topic}'`,
+        recipient
+      );
+    }
+    const entries = this.#subscriptions.getEntries(recipient, message.topic);
+    const first = entries[0]?.handler;
+    const { success, data: responseData } = await this.#executeHandler(message, first);
+    return RoutingResult.create(
+      success ? "ACK" : "NACK",
+      success ? RoutingReason.DELIVERED : RoutingReason.HANDLER_FAILED,
+      success ? `Message delivered and handled by '${recipient}'` : `Message not handled by '${recipient}'`,
+      recipient,
+      responseData
+    );
+  }
+  /**
+   * Route multicast message to all subscribers except sender.
+   *
+   * A subscriber may have registered multiple handlers on the topic — every
+   * one of them fires. The `dispatched` count reflects unique recipients
+   * (not handler invocations) to keep the ACK payload consistent with the
+   * subscriber-centric mental model.
+   *
+   * Handlers run fire-and-forget — ACK means dispatch completed, not that
+   * every subscriber finished processing the message.
+   */
+  async multicast(message, sender) {
+    const subscribers = this.#subscriptions.getSubscribers(message.topic);
+    const dispatched = [];
+    for (const clientId of subscribers) {
+      if (clientId === sender) continue;
+      const entries = this.#subscriptions.getEntries(clientId, message.topic);
+      if (entries.length === 0) continue;
+      for (const entry of entries) {
+        this.#executeHandlerFireAndForget(message, entry.handler, clientId);
+      }
+      dispatched.push(clientId);
+    }
+    if (dispatched.length === 0) {
+      return RoutingResult.create("NACK", RoutingReason.NO_SUBSCRIBERS, `No subscribers for message '${message.topic}'`);
+    }
+    return RoutingResult.create(
+      "ACK",
+      RoutingReason.DISPATCHED,
+      `Multicast dispatched to ${dispatched.length} subscriber${dispatched.length === 1 ? "" : "s"}`,
+      void 0,
+      void 0,
+      dispatched
+    );
+  }
+  // ========================================
+  // PRIVATE HELPER METHODS
+  // ========================================
+  /**
+   * Execute a handler with error handling and response capture
+   * @private
+   */
+  async #executeHandler(message, handler) {
+    if (!handler) return { success: false };
+    try {
+      const result = await handler(message);
+      return { success: true, data: result };
+    } catch (handlerError) {
+      this.#logger.error("handler.failed", { error: handlerError });
+      return { success: false };
+    }
+  }
+  /**
+   * Execute handler in fire-and-forget mode (for multicast)
+   * @private
+   */
+  #executeHandlerFireAndForget(message, handler, clientId) {
+    try {
+      Promise.resolve(handler(message)).catch((handlerError) => {
+        this.#logger.error("handler.failed", { clientId, error: handlerError });
+      });
+    } catch (handlerError) {
+      this.#logger.error("handler.failed", { clientId, error: handlerError });
+    }
+  }
+};
+
+// src/core/hooks/HooksRegistry.ts
+var HooksRegistry = class {
+  #onSubscribeHooks = [];
+  #beforeSendHooks = [];
+  #afterSendHooks = [];
+  #logger;
+  constructor(logger) {
+    this.#logger = logger;
+  }
+  // ========================================
+  // REGISTRATION
+  // ========================================
+  /**
+   * Register onSubscribe hook(s).
+   * Called whenever a client subscribes to a topic. Return `{ allowed: false }` to block.
+   *
+   * @returns Cleanup function to remove the hook(s).
+   */
+  addOnSubscribeHook(hook) {
+    return this.#addHook(this.#onSubscribeHooks, hook);
+  }
+  /**
+   * Register beforeSend hook(s).
+   *
+   * Called before routing for EVERY message, including those received from bridges.
+   * Return `{ allowed: false }` to block delivery.
+   *
+   * @returns Cleanup function to remove the hook(s).
+   */
+  addBeforeSendHook(hook) {
+    return this.#addHook(this.#beforeSendHooks, hook);
+  }
+  /**
+   * Register afterSend hook(s).
+   *
+   * Called after each message is processed. Receives the routing result.
+   * Called for ALL messages — both local and forwarded from bridges.
+   *
+   * @returns Cleanup function to remove the hook(s).
+   */
+  addAfterSendHook(hook) {
+    return this.#addHook(this.#afterSendHooks, hook);
+  }
+  // ========================================
+  // EXECUTION (called by BrokerCore)
+  // ========================================
+  /**
+   * Execute onSubscribe hooks. Stops at the first hook that denies.
+   */
+  onSubscribe(topic, clientId) {
+    return this.#runGuard(
+      this.#onSubscribeHooks,
+      "onSubscribe",
+      (hook) => hook(topic, clientId)
+    );
+  }
+  /**
+   * Execute beforeSend hooks. Stops at the first hook that denies.
+   * Executed for ALL messages, including those from bridges.
+   */
+  beforeSend(message) {
+    return this.#runGuard(this.#beforeSendHooks, "beforeSend", (hook) => hook(message));
+  }
+  /**
+   * Execute afterSend hooks. All hooks run; errors are isolated per-hook.
+   * Executed for ALL messages (local and external).
+   */
+  afterSend(message, messageResult) {
+    for (const hook of this.#afterSendHooks) {
+      try {
+        hook(message, messageResult);
+      } catch (error) {
+        this.#logger.error("hook.after_send.failed", { error });
+      }
+    }
+  }
+  // ========================================
+  // LIFECYCLE
+  // ========================================
+  /**
+   * Remove all registered hooks.
+   */
+  clear() {
+    this.#onSubscribeHooks = [];
+    this.#beforeSendHooks = [];
+    this.#afterSendHooks = [];
+  }
+  // ========================================
+  // PRIVATE HELPERS
+  // ========================================
+  /**
+   * Add one or more hooks to a list and return an unsubscribe function.
+   * Preserves insertion order for deterministic hook execution.
+   */
+  #addHook(list, hookOrHooks) {
+    const added = Array.isArray(hookOrHooks) ? [...hookOrHooks] : [hookOrHooks];
+    list.push(...added);
+    return () => {
+      for (const hook of added) {
+        const index = list.indexOf(hook);
+        if (index !== -1) list.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Run a list of guard-style hooks: each returns HookResult, execution stops
+   * at the first `{ allowed: false }`. Errors are caught and logged (fail-open):
+   * a throwing hook does not block the pipeline.
+   */
+  #runGuard(hooks, kind, invoke) {
+    for (const hook of hooks) {
+      try {
+        const result = invoke(hook);
+        if (!result.allowed) return result;
+      } catch (error) {
+        this.#logger.error("hook.failed", { kind, error });
+      }
+    }
+    return { allowed: true };
+  }
+};
+
+// src/core/client/ClientRegistry.ts
+var ClientRegistry = class {
+  #clients = /* @__PURE__ */ new Map();
+  #connectedAt = /* @__PURE__ */ new Map();
+  /**
+   * Register a client
+   */
+  register(client) {
+    this.#clients.set(client.id, client);
+    this.#connectedAt.set(client.id, Date.now());
+  }
+  /**
+   * Unregister a client
+   */
+  unregister(clientId) {
+    this.#clients.delete(clientId);
+    this.#connectedAt.delete(clientId);
+  }
+  /**
+   * Get the timestamp when a client registered (Unix ms)
+   */
+  getConnectedAt(clientId) {
+    return this.#connectedAt.get(clientId);
+  }
+  /**
+   * Get client by ID
+   */
+  get(clientId) {
+    return this.#clients.get(clientId);
+  }
+  /**
+   * Check if client is registered
+   */
+  has(clientId) {
+    return this.#clients.has(clientId);
+  }
+  /**
+   * Get all registered clients
+   */
+  getAll() {
+    return Array.from(this.#clients.values());
+  }
+  /**
+   * Get all client IDs
+   */
+  getAllIds() {
+    return Array.from(this.#clients.keys());
+  }
+  /**
+   * Clear all clients
+   */
+  clear() {
+    this.#clients.clear();
+    this.#connectedAt.clear();
+  }
+  /**
+   * Get number of registered clients
+   */
+  get size() {
+    return this.#clients.size;
+  }
+};
+
+// src/core/routing/Subscriptions.ts
+var Subscriptions = class {
+  // ========================================
+  // BIDIRECTIONAL INDEXES FOR O(1) OPERATIONS
+  // ========================================
+  /** Topic → Clients mapping for fast multicast recipient lookup */
+  #subscriptions = /* @__PURE__ */ new Map();
+  /** Client → Topics mapping for fast unsubscribe operations */
+  #clientSubscriptions = /* @__PURE__ */ new Map();
+  /** Composite key → ordered handler entries (many per pair). */
+  #entries = /* @__PURE__ */ new Map();
+  /** Subscription id → its location, for O(1) single-handler removal. */
+  #entryLocations = /* @__PURE__ */ new Map();
+  /** Monotonic subscription id counter. */
+  #nextId = 1;
+  /** Shared empty set to avoid allocations */
+  #emptySet = Object.freeze(/* @__PURE__ */ new Set());
+  #emptyEntries = Object.freeze([]);
+  // ========================================
+  // SUBSCRIPTION OPERATIONS
+  // ========================================
+  /**
+   * Reserve a subscription id ahead of {@link subscribe}.
+   *
+   * Callers that need the id BEFORE the handler is finalized (e.g. to key
+   * a backpressure strategy by that id) can pre-allocate here and then
+   * pass the reserved id to {@link subscribe}.
+   */
+  reserveId() {
+    return this.#nextId++;
+  }
+  /**
+   * Subscribe a handler to a (client, topic) pair.
+   *
+   * Appends a new entry — previously registered handlers on the same pair
+   * are preserved. Returns the subscription id so the caller can remove
+   * this specific handler later via {@link unsubscribeOne}.
+   *
+   * If `preReservedId` is provided (from {@link reserveId}), that id is
+   * used instead of generating a new one.
+   */
+  subscribe(clientId, topic, handler, options, preReservedId) {
+    if (!this.#subscriptions.has(topic)) {
+      this.#subscriptions.set(topic, /* @__PURE__ */ new Set());
+    }
+    this.#subscriptions.get(topic).add(clientId);
+    if (!this.#clientSubscriptions.has(clientId)) {
+      this.#clientSubscriptions.set(clientId, /* @__PURE__ */ new Set());
+    }
+    this.#clientSubscriptions.get(clientId).add(topic);
+    const id = preReservedId ?? this.#nextId++;
+    const entry = { id, handler, options };
+    const key = this.#getKey(clientId, topic);
+    let list = this.#entries.get(key);
+    if (!list) {
+      list = [];
+      this.#entries.set(key, list);
+    }
+    list.push(entry);
+    this.#entryLocations.set(id, { clientId, topic });
+    return id;
+  }
+  /**
+   * Remove a single handler by its subscription id.
+   *
+   * If this was the last handler for the pair, the pair is fully removed
+   * from the bidirectional indexes (mirroring `unsubscribe` semantics).
+   *
+   * @returns Removal outcome: the removed entry, the pair it belonged to,
+   *          and whether it was the last handler on that pair. `undefined`
+   *          when no such id existed.
+   */
+  unsubscribeOne(id) {
+    const location = this.#entryLocations.get(id);
+    if (!location) return void 0;
+    const { clientId, topic } = location;
+    const key = this.#getKey(clientId, topic);
+    const list = this.#entries.get(key);
+    if (!list) {
+      this.#entryLocations.delete(id);
+      return void 0;
+    }
+    const idx = list.findIndex((e) => e.id === id);
+    if (idx === -1) {
+      this.#entryLocations.delete(id);
+      return void 0;
+    }
+    const [removed] = list.splice(idx, 1);
+    this.#entryLocations.delete(id);
+    const wasLast = list.length === 0;
+    if (wasLast) {
+      this.#entries.delete(key);
+      this.#subscriptions.get(topic)?.delete(clientId);
+      this.#clientSubscriptions.get(clientId)?.delete(topic);
+      if (this.#subscriptions.get(topic)?.size === 0) {
+        this.#subscriptions.delete(topic);
+      }
+    }
+    return { entry: removed, clientId, topic, wasLast };
+  }
+  /**
+   * Unsubscribe every handler a client holds on a topic.
+   *
+   * @returns Entries that were actually removed. Empty when the client had
+   *          no handlers on the topic. Callers use this to release
+   *          per-handler resources (e.g. backpressure strategies).
+   */
+  unsubscribe(clientId, topic) {
+    const key = this.#getKey(clientId, topic);
+    const list = this.#entries.get(key);
+    if (!list || list.length === 0) return this.#emptyEntries;
+    for (const entry of list) {
+      this.#entryLocations.delete(entry.id);
+    }
+    this.#entries.delete(key);
+    this.#subscriptions.get(topic)?.delete(clientId);
+    this.#clientSubscriptions.get(clientId)?.delete(topic);
+    if (this.#subscriptions.get(topic)?.size === 0) {
+      this.#subscriptions.delete(topic);
+    }
+    return list;
+  }
+  /**
+   * Remove every subscription held by a given client.
+   *
+   * @returns Per-topic entry buckets that were removed, in iteration order.
+   *          Empty when the client had no active subscriptions. Callers use
+   *          this to release per-handler resources and emit per-topic
+   *          `subscription.removed` events.
+   */
+  unsubscribeAll(clientId) {
+    const clientTopics = this.#clientSubscriptions.get(clientId);
+    if (!clientTopics || clientTopics.size === 0) {
+      this.#clientSubscriptions.delete(clientId);
+      return [];
+    }
+    const removed = [];
+    for (const topic of clientTopics) {
+      const key = this.#getKey(clientId, topic);
+      const list = this.#entries.get(key);
+      if (list) {
+        for (const entry of list) {
+          this.#entryLocations.delete(entry.id);
+        }
+        this.#entries.delete(key);
+        removed.push({ topic, entries: list });
+      }
+      this.#subscriptions.get(topic)?.delete(clientId);
+      if (this.#subscriptions.get(topic)?.size === 0) {
+        this.#subscriptions.delete(topic);
+      }
+    }
+    this.#clientSubscriptions.delete(clientId);
+    return removed;
+  }
+  // ========================================
+  // QUERY OPERATIONS
+  // ========================================
+  /**
+   * Get all topics a client is subscribed to
+   */
+  getClientTopics(clientId) {
+    return this.#clientSubscriptions.get(clientId);
+  }
+  /**
+   * Check if a client has at least one handler on a topic.
+   */
+  isSubscribed(clientId, topic) {
+    return this.#clientSubscriptions.get(clientId)?.has(topic) ?? false;
+  }
+  /**
+   * All handler entries a client has on a topic, in registration order.
+   */
+  getEntries(clientId, topic) {
+    return this.#entries.get(this.#getKey(clientId, topic)) ?? this.#emptyEntries;
+  }
+  /**
+   * Options of the first handler registered on `(clientId, topic)`.
+   *
+   * Convenience for read-only observers (e.g. Inspector) that predate the
+   * multi-handler model and expect a single options blob per pair.
+   */
+  getFirstOptions(clientId, topic) {
+    return this.#entries.get(this.#getKey(clientId, topic))?.[0]?.options;
+  }
+  /**
+   * Number of handlers a client holds on a topic (0 = not subscribed).
+   */
+  getHandlerCount(clientId, topic) {
+    return this.#entries.get(this.#getKey(clientId, topic))?.length ?? 0;
+  }
+  /**
+   * Get all subscribers for a topic (read-only)
+   */
+  getSubscribers(topic) {
+    return this.#subscriptions.get(topic) ?? this.#emptySet;
+  }
+  /**
+   * Get list of all clients that have active subscriptions
+   */
+  getAllSubscribedClients() {
+    return Array.from(this.#clientSubscriptions.keys());
+  }
+  /**
+   * Get detailed subscription map for all clients
+   */
+  getAllSubscriptions() {
+    const result = {};
+    for (const [clientId, topics] of this.#clientSubscriptions) {
+      result[clientId] = Array.from(topics);
+    }
+    return result;
+  }
+  // ========================================
+  // LIFECYCLE
+  // ========================================
+  /**
+   * Clear all subscriptions and handlers.
+   *
+   * @returns All entries that were held, so the caller can release
+   *          per-handler resources (e.g. backpressure strategies).
+   */
+  clear() {
+    const all = [];
+    for (const list of this.#entries.values()) {
+      for (const entry of list) {
+        all.push(entry);
+      }
+    }
+    this.#subscriptions.clear();
+    this.#clientSubscriptions.clear();
+    this.#entries.clear();
+    this.#entryLocations.clear();
+    return all;
+  }
+  // ========================================
+  // PRIVATE HELPERS
+  // ========================================
+  #getKey(clientId, topic) {
+    return `${clientId}:${topic}`;
+  }
+};
+
+// src/core/backpressure/strategies/ThrottleStrategy.ts
+var ThrottleStrategy = class {
+  #throttleMs;
+  #lastExecutionTime = 0;
+  #timeoutId;
+  #pendingMessage;
+  #pendingHandler;
+  #logger;
+  constructor(throttleMs, logger) {
+    if (typeof throttleMs !== "number" || !Number.isFinite(throttleMs)) {
+      throw new Error("Throttle period must be a finite number");
+    }
+    if (throttleMs <= 0) {
+      throw new Error("Throttle period must be positive");
+    }
+    this.#throttleMs = throttleMs;
+    this.#logger = logger;
+  }
+  /**
+   * Process message through throttle
+   *
+   * @param message - Incoming message
+   * @param handler - Handler to call
+   * @returns true if executed immediately, false if delayed
+   */
+  process(message, handler) {
+    const now = Date.now();
+    const timeSinceLastExecution = now - this.#lastExecutionTime;
+    if (timeSinceLastExecution >= this.#throttleMs) {
+      this.#execute(message, handler);
+      return true;
+    }
+    this.#pendingMessage = message;
+    this.#pendingHandler = handler;
+    if (!this.#timeoutId) {
+      const delay = this.#throttleMs - timeSinceLastExecution;
+      this.#timeoutId = setTimeout(() => {
+        this.#flush();
+      }, delay);
+    }
+    return false;
+  }
+  /**
+   * Execute handler and update last execution time
+   */
+  #execute(message, handler) {
+    this.#lastExecutionTime = Date.now();
+    try {
+      handler(message);
+    } catch (error) {
+      this.#logger.error("backpressure.handler.failed", { strategy: "throttle", error });
+    }
+  }
+  /**
+   * Flush pending message
+   */
+  #flush() {
+    if (this.#pendingMessage && this.#pendingHandler) {
+      this.#execute(this.#pendingMessage, this.#pendingHandler);
+    }
+    this.#pendingMessage = void 0;
+    this.#pendingHandler = void 0;
+    this.#timeoutId = void 0;
+  }
+  /**
+   * Force flush pending messages
+   * Called on unsubscribe to ensure no messages are lost
+   */
+  flush() {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId);
+      this.#flush();
+    }
+  }
+  /**
+   * Cleanup resources
+   */
+  destroy() {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId);
+    }
+    this.#pendingMessage = void 0;
+    this.#pendingHandler = void 0;
+  }
+};
+
+// src/core/backpressure/strategies/DebounceStrategy.ts
+var DebounceStrategy = class {
+  #debounceMs;
+  #timeoutId;
+  #pendingMessage;
+  #pendingHandler;
+  #logger;
+  constructor(debounceMs, logger) {
+    if (typeof debounceMs !== "number" || !Number.isFinite(debounceMs)) {
+      throw new Error("Debounce period must be a finite number");
+    }
+    if (debounceMs <= 0) {
+      throw new Error("Debounce period must be positive");
+    }
+    this.#debounceMs = debounceMs;
+    this.#logger = logger;
+  }
+  /**
+   * Process message through debounce
+   *
+   * Resets timer on each call. Only executes after silence period.
+   *
+   * @param message - Incoming message
+   * @param handler - Handler to call
+   * @returns false (always delayed)
+   */
+  process(message, handler) {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId);
+    }
+    this.#pendingMessage = message;
+    this.#pendingHandler = handler;
+    this.#timeoutId = setTimeout(() => {
+      this.#flush();
+    }, this.#debounceMs);
+    return false;
+  }
+  /**
+   * Execute pending message
+   */
+  #flush() {
+    if (this.#pendingMessage && this.#pendingHandler) {
+      try {
+        this.#pendingHandler(this.#pendingMessage);
+      } catch (error) {
+        this.#logger.error("backpressure.handler.failed", { strategy: "debounce", error });
+      }
+    }
+    this.#pendingMessage = void 0;
+    this.#pendingHandler = void 0;
+    this.#timeoutId = void 0;
+  }
+  /**
+   * Force flush pending message
+   * Called on unsubscribe to ensure no messages are lost
+   */
+  flush() {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId);
+      this.#flush();
+    }
+  }
+  /**
+   * Cleanup resources
+   */
+  destroy() {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId);
+    }
+    this.#pendingMessage = void 0;
+    this.#pendingHandler = void 0;
+  }
+};
+
+// src/core/backpressure/strategies/RateLimitStrategy.ts
+var RateLimitStrategy = class {
+  #max;
+  #windowMs;
+  #onDrop;
+  #timestamps;
+  #head = 0;
+  #count = 0;
+  #droppedCount = 0;
+  #logger;
+  constructor(options, onDrop, logger) {
+    if (typeof options.max !== "number" || !Number.isFinite(options.max)) {
+      throw new Error("Rate limit max must be a finite number");
+    }
+    if (options.max <= 0) {
+      throw new Error("Rate limit max must be positive");
+    }
+    if (typeof options.window !== "number" || !Number.isFinite(options.window)) {
+      throw new Error("Rate limit window must be a finite number");
+    }
+    if (options.window <= 0) {
+      throw new Error("Rate limit window must be positive");
+    }
+    this.#max = options.max;
+    this.#windowMs = options.window;
+    this.#onDrop = onDrop;
+    this.#timestamps = new Array(options.max).fill(0);
+    this.#logger = logger;
+  }
+  /**
+   * Process message through rate limit
+   *
+   * Uses sliding window with circular buffer for O(1) amortized eviction.
+   *
+   * @param message - Incoming message
+   * @param handler - Handler to call
+   * @returns true if processed, false if dropped
+   */
+  process(message, handler) {
+    const now = Date.now();
+    this.#evict(now);
+    if (this.#count < this.#max) {
+      const tail = (this.#head + this.#count) % this.#max;
+      this.#timestamps[tail] = now;
+      this.#count++;
+      try {
+        handler(message);
+      } catch (error) {
+        this.#logger.error("backpressure.handler.failed", { strategy: "rateLimit", error });
+      }
+      return true;
+    }
+    this.#droppedCount++;
+    if (this.#onDrop) {
+      try {
+        this.#onDrop(this.#droppedCount);
+      } catch (error) {
+        this.#logger.error("backpressure.on_drop.failed", { error });
+      }
+    }
+    return false;
+  }
+  /**
+   * Flush is no-op for rate limiting
+   * Rate limit doesn't accumulate messages, so nothing to flush
+   */
+  flush() {
+  }
+  /**
+   * Cleanup resources
+   */
+  destroy() {
+    this.#head = 0;
+    this.#count = 0;
+    this.#timestamps.fill(0);
+  }
+  /**
+   * Get number of dropped messages (for debugging/metrics)
+   */
+  get droppedCount() {
+    return this.#droppedCount;
+  }
+  /**
+   * Get current count in window (for debugging/metrics)
+   */
+  get currentCount() {
+    this.#evict(Date.now());
+    return this.#count;
+  }
+  /** Advance head past expired timestamps */
+  #evict(now) {
+    while (this.#count > 0 && now - this.#timestamps[this.#head] >= this.#windowMs) {
+      this.#head = (this.#head + 1) % this.#max;
+      this.#count--;
+    }
+  }
+};
+
+// src/core/backpressure/BackpressureHandler.ts
+var BackpressureHandler = class {
+  /** subscriptionId → strategy. One entry per handler that opted into BP. */
+  #strategies = /* @__PURE__ */ new Map();
+  #logger;
+  constructor(logger) {
+    this.#logger = logger;
+  }
+  /**
+   * Wrap handler in backpressure strategy
+   *
+   * If options.backpressure is undefined/null, returns original handler (no backpressure).
+   * Otherwise creates appropriate strategy and returns wrapped handler.
+   *
+   * @param subscriptionId - Unique id of this handler subscription.
+   *   The id is emitted by {@link Subscriptions.subscribe} — the caller is
+   *   responsible for reserving it and passing the same value to both
+   *   `wrap()` and `subscribe()` so the strategy can be released via
+   *   {@link removeOne} when that specific handler unsubscribes.
+   * @param clientId - Unique client identifier (for logging context)
+   * @param topic - Topic being subscribed to (for logging context)
+   * @param handler - Original handler function
+   * @param options - Subscription options (optional)
+   * @returns Wrapped handler or original handler if no backpressure options
+   */
+  wrap(subscriptionId, clientId, topic, handler, options) {
+    const bpOptions = options?.backpressure;
+    if (!bpOptions) {
+      return handler;
+    }
+    const strategy = this.#createStrategy(bpOptions);
+    this.#strategies.set(subscriptionId, strategy);
+    return (message) => {
+      strategy.process(message, handler);
+    };
+  }
+  /**
+   * Create strategy instance based on backpressure options
+   *
+   * Only ONE strategy can be specified per subscription.
+   * Multiple strategies will throw an error.
+   *
+   * @throws Error if no strategy specified
+   * @throws Error if multiple strategies specified
+   */
+  #createStrategy(options) {
+    const specifiedStrategies = [
+      options.throttle !== void 0 && "throttle",
+      options.debounce !== void 0 && "debounce",
+      options.rateLimit !== void 0 && "rateLimit"
+    ].filter(Boolean);
+    if (specifiedStrategies.length === 0) {
+      throw new Error(
+        "No backpressure strategy specified. Provide one of: throttle, debounce, or rateLimit."
+      );
+    }
+    if (specifiedStrategies.length > 1) {
+      throw new Error(
+        `Multiple backpressure strategies specified: ${specifiedStrategies.join(", ")}. Only one strategy is allowed per subscription.`
+      );
+    }
+    if (options.throttle !== void 0) {
+      return new ThrottleStrategy(options.throttle, this.#logger);
+    }
+    if (options.debounce !== void 0) {
+      return new DebounceStrategy(options.debounce, this.#logger);
+    }
+    if (options.rateLimit) {
+      return new RateLimitStrategy(options.rateLimit, options.onDrop, this.#logger);
+    }
+    throw new Error("No backpressure strategy specified in BackpressureOptions");
+  }
+  /**
+   * Release the strategy attached to a single subscription id.
+   *
+   * Called when the corresponding handler unsubscribes. Flushes pending
+   * messages and destroys the strategy. No-op when the subscription had
+   * no backpressure.
+   */
+  removeOne(subscriptionId) {
+    const strategy = this.#strategies.get(subscriptionId);
+    if (!strategy) return;
+    strategy.flush();
+    strategy.destroy();
+    this.#strategies.delete(subscriptionId);
+  }
+  /**
+   * Bulk release for a set of subscription ids.
+   *
+   * Used when a client unsubscribes from a whole topic (or resets), which
+   * removes N handlers at once.
+   */
+  removeMany(subscriptionIds) {
+    for (const id of subscriptionIds) {
+      this.removeOne(id);
+    }
+  }
+  /**
+   * Cleanup all strategies
+   *
+   * Called when broker is destroyed.
+   */
+  destroy() {
+    for (const strategy of this.#strategies.values()) {
+      strategy.flush();
+      strategy.destroy();
+    }
+    this.#strategies.clear();
+  }
+  /**
+   * Get number of active strategies (for debugging/metrics)
+   */
+  get activeStrategies() {
+    return this.#strategies.size;
+  }
+};
+
+// src/core/utils/deepFreeze.ts
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  Object.getOwnPropertyNames(obj).forEach((prop) => {
+    const value = obj[prop];
+    if (value !== null && (typeof value === "object" || typeof value === "function") && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  });
+  return obj;
+}
+
+// src/core/history/MessageHistory.ts
+var MessageHistory = class {
+  #entries = [];
+  #sequence = 0;
+  #config;
+  #cleanupTimer;
+  constructor(config) {
+    this.#config = {
+      enabled: config.enabled,
+      maxSize: config.maxSize ?? 1e3,
+      ttl: config.ttl
+    };
+    if (this.#config.ttl !== void 0) {
+      this.#startCleanup();
+    }
+  }
+  /**
+   * Record a message to history
+   */
+  record(message) {
+    const entry = {
+      message: deepFreeze(message),
+      timestamp: message.timestamp,
+      sequence: this.#sequence++
+    };
+    this.#entries.push(entry);
+    if (this.#entries.length > this.#config.maxSize) {
+      this.#entries.shift();
+    }
+  }
+  /**
+   * Query messages from history
+   */
+  async query(filter) {
+    let results = [...this.#entries];
+    if (filter?.since !== void 0) {
+      results = results.filter((entry) => entry.timestamp >= filter.since);
+    }
+    if (filter?.until !== void 0) {
+      results = results.filter((entry) => entry.timestamp <= filter.until);
+    }
+    if (filter?.topics && filter.topics.length > 0) {
+      results = results.filter(
+        (entry) => filter.topics.some((pattern) => matchPattern(entry.message.topic, pattern))
+      );
+    }
+    if (filter?.sources && filter.sources.length > 0) {
+      results = results.filter((entry) => filter.sources.includes(entry.message.source));
+    }
+    if (filter?.limit !== void 0 && filter.limit > 0) {
+      results = results.slice(-filter.limit);
+    }
+    return results;
+  }
+  /**
+   * Clear messages from history
+   */
+  async clear(filter) {
+    if (!filter) {
+      this.#entries = [];
+      return;
+    }
+    const toKeep = await this.#getInverseFilter(filter);
+    this.#entries = toKeep;
+  }
+  /**
+   * Return a point-in-time snapshot of all entries (oldest → newest).
+   */
+  getSnapshot() {
+    return [...this.#entries];
+  }
+  /**
+   * Get history statistics
+   */
+  getStats() {
+    const count = this.#entries.length;
+    if (count === 0) {
+      return { count: 0 };
+    }
+    const oldestTimestamp = this.#entries[0]?.timestamp;
+    const newestTimestamp = this.#entries[count - 1]?.timestamp;
+    const memoryUsage = this.#estimateMemoryUsage();
+    return {
+      count,
+      oldestTimestamp,
+      newestTimestamp,
+      memoryUsage
+    };
+  }
+  /**
+   * Cleanup and destroy
+   */
+  destroy() {
+    if (this.#cleanupTimer) {
+      clearInterval(this.#cleanupTimer);
+      this.#cleanupTimer = void 0;
+    }
+    this.#entries = [];
+  }
+  // ========================================
+  // PRIVATE METHODS
+  // ========================================
+  /**
+   * Get entries that should be kept (inverse of filter)
+   */
+  async #getInverseFilter(filter) {
+    return this.#entries.filter((entry) => {
+      if (filter.since !== void 0 && entry.timestamp < filter.since) {
+        return true;
+      }
+      if (filter.until !== void 0 && entry.timestamp > filter.until) {
+        return true;
+      }
+      if (filter.topics && filter.topics.length > 0) {
+        const matches = filter.topics.some(
+          (pattern) => matchPattern(entry.message.topic, pattern)
+        );
+        if (!matches) {
+          return true;
+        }
+      }
+      if (filter.sources && filter.sources.length > 0) {
+        if (!filter.sources.includes(entry.message.source)) {
+          return true;
+        }
+      }
+      return false;
+    });
+  }
+  /**
+   * Start periodic TTL-based cleanup
+   */
+  #startCleanup() {
+    const ttl = this.#config.ttl;
+    if (!ttl) return;
+    const interval = Math.min(ttl / 2, 6e4);
+    this.#cleanupTimer = setInterval(() => {
+      const now = Date.now();
+      const cutoff = now - ttl;
+      this.#entries = this.#entries.filter((entry) => entry.timestamp > cutoff);
+    }, interval);
+  }
+  /**
+   * Estimate memory usage (rough approximation)
+   */
+  #estimateMemoryUsage() {
+    return this.#entries.length * 100;
+  }
+};
+
+// src/core/history/SubscriptionReplay.ts
+var SubscriptionReplay = class {
+  #history;
+  #hooks;
+  #logger;
+  constructor(history, hooks, logger) {
+    this.#history = history;
+    this.#hooks = hooks;
+    this.#logger = logger;
+  }
+  /**
+   * Asynchronously replay matching history entries to the given subscription.
+   *
+   * Does NOT await completion — returns immediately while the replay runs on
+   * the microtask queue. Callers should not assume replay is finished when
+   * this method returns.
+   *
+   * @param clientId - Target subscriber identifier.
+   * @param topic - Subscribed topic (supports glob; forwarded to history.query).
+   * @param handler - Handler to receive each replayed message.
+   * @param options - Replay window (`limit`, `since`, `until`).
+   */
+  start(clientId, topic, handler, options) {
+    queueMicrotask(async () => {
+      try {
+        const entries = await this.#history.query({
+          topics: [topic],
+          limit: options.limit,
+          since: options.since,
+          until: options.until
+        });
+        for (const entry of entries) {
+          try {
+            const recipient = entry.message.target;
+            if (recipient !== "*" && recipient !== clientId) continue;
+            const replayedMessage = {
+              ...entry.message,
+              replayed: true
+            };
+            await handler(replayedMessage);
+            this.#hooks.afterSend(
+              replayedMessage,
+              RoutingResult.create(
+                "ACK",
+                RoutingReason.REPLAY_DELIVERED,
+                `Replayed to '${clientId}'`,
+                clientId
+              )
+            );
+          } catch (error) {
+            this.#logger.error("replay.handler.failed", {
+              messageId: entry.message.id,
+              clientId,
+              error
+            });
+          }
+        }
+      } catch (error) {
+        this.#logger.error("replay.query.failed", { clientId, error });
+      }
+    });
+  }
+};
+
+// src/core/events/SystemEvents.ts
+var SystemEvents = class {
+  #listeners = /* @__PURE__ */ new Map();
+  #anyListeners = /* @__PURE__ */ new Set();
+  #logger;
+  constructor(logger) {
+    this.#logger = logger;
+  }
+  on(event, listener) {
+    let set = this.#listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.#listeners.set(event, set);
+    }
+    set.add(listener);
+    return () => {
+      const s = this.#listeners.get(event);
+      if (!s) return;
+      s.delete(listener);
+      if (s.size === 0) this.#listeners.delete(event);
+    };
+  }
+  once(event, listener) {
+    const wrapped = (payload) => {
+      unsubscribe();
+      listener(payload);
+    };
+    const unsubscribe = this.on(event, wrapped);
+    return unsubscribe;
+  }
+  off(event) {
+    if (event === void 0) {
+      this.#listeners.clear();
+      return;
+    }
+    this.#listeners.delete(event);
+  }
+  onAny(listener) {
+    this.#anyListeners.add(listener);
+    return () => this.#anyListeners.delete(listener);
+  }
+  listenerCount(event) {
+    if (event === void 0) {
+      let total = this.#anyListeners.size;
+      for (const set of this.#listeners.values()) total += set.size;
+      return total;
+    }
+    return (this.#listeners.get(event)?.size ?? 0) + this.#anyListeners.size;
+  }
+  /**
+   * Emit a system event to all subscribed listeners.
+   *
+   * Safe to call on the hot path: returns immediately when no listeners are
+   * registered (zero allocation). Listener errors are caught and logged;
+   * they never propagate back to the broker pipeline.
+   */
+  emit(event, payload) {
+    if (this.#anyListeners.size === 0) {
+      const direct2 = this.#listeners.get(event);
+      if (!direct2 || direct2.size === 0) return;
+      this.#dispatch(direct2, payload, event);
+      return;
+    }
+    const direct = this.#listeners.get(event);
+    if (direct && direct.size > 0) this.#dispatch(direct, payload, event);
+    for (const listener of this.#anyListeners) {
+      try {
+        listener(event, payload);
+      } catch (err) {
+        this.#logger.error("system_events.listener.failed", { event: String(event), error: err });
+      }
+    }
+  }
+  /**
+   * Remove all listeners. Called by `BrokerCore.destroy()`.
+   */
+  clear() {
+    this.#listeners.clear();
+    this.#anyListeners.clear();
+  }
+  #dispatch(listeners, payload, event) {
+    for (const listener of listeners) {
+      try {
+        listener(payload);
+      } catch (err) {
+        this.#logger.error("system_events.listener.failed", { event: String(event), error: err });
+      }
+    }
+  }
+};
+
+// src/core/observability/inspect/Inspector.ts
+var Inspector = class {
+  #clients;
+  #subscriptions;
+  #bridges;
+  #getHistory;
+  constructor(clients, subscriptions, bridges, getHistory) {
+    this.#clients = clients;
+    this.#subscriptions = subscriptions;
+    this.#bridges = bridges;
+    this.#getHistory = getHistory;
+  }
+  /**
+   * Snapshot of every registered client together with its active subscriptions.
+   *
+   * Use together with `$systemEvents.on('client.*' | 'subscription.*')` to
+   * build an accurate initial state without race conditions: read the snapshot
+   * first, then subscribe to events for incremental updates.
+   */
+  getClients() {
+    return this.#clients.getAllIds().map((id) => ({
+      id,
+      connectedAt: this.#clients.getConnectedAt(id) ?? Date.now(),
+      subscriptions: Array.from(this.#subscriptions.getClientTopics(id) ?? []).map((topic) => ({
+        topic,
+        // A pair may hold N handlers with different options — the Inspector
+        // surface predates the multi-handler model and exposes a single
+        // options blob. First handler wins; drill into `getEntries()` for
+        // full detail.
+        options: this.#subscriptions.getFirstOptions(id, topic),
+        handlerCount: this.#subscriptions.getHandlerCount(id, topic)
+      }))
+    }));
+  }
+  /**
+   * IDs of clients that have at least one active subscription.
+   */
+  getSubscribedClientIds() {
+    return this.#subscriptions.getAllSubscribedClients();
+  }
+  /**
+   * Lifecycle info for every registered bridge. Does NOT expose internal
+   * `Bridge` instances (see `BridgeInfo`).
+   */
+  getBridges() {
+    const result = [];
+    for (const [id, bridge] of this.#bridges) {
+      result.push({
+        id,
+        forwardPatterns: bridge.forwardPatterns,
+        transportKind: bridge.transportKind
+      });
+    }
+    return result;
+  }
+  /**
+   * All messages currently stored in the replay buffer (oldest → newest).
+   * Returns an empty array when history is not enabled.
+   */
+  getHistory() {
+    const history = this.#getHistory();
+    if (!history) return [];
+    return history.getSnapshot();
+  }
+  /**
+   * Replay buffer statistics. Always returns `{ enabled: false, count: 0 }`
+   * when history is not enabled.
+   */
+  getHistoryStats() {
+    const history = this.#getHistory();
+    if (!history) return { count: 0, enabled: false };
+    return { ...history.getStats(), enabled: true };
+  }
+};
+
+// src/core/logger/BrokerLogger.types.ts
+var defaultLogger = {
+  warn(event, meta) {
+    meta !== void 0 ? console.warn(`[broker] ${event}`, meta) : console.warn(`[broker] ${event}`);
+  },
+  error(event, meta) {
+    meta !== void 0 ? console.error(`[broker] ${event}`, meta) : console.error(`[broker] ${event}`);
+  }
+};
+
+// src/core/BrokerCore.ts
+var BrokerCore = class {
+  #isDestroyed = false;
+  #sessionId = crypto.randomUUID();
+  #eventCounter = 0;
+  #subscriptions = new Subscriptions();
+  #router;
+  #hooks;
+  #clientRegistry = new ClientRegistry();
+  #systemEvents;
+  #backpressure;
+  #history;
+  #replay;
+  #bridges = /* @__PURE__ */ new Map();
+  #inspect;
+  /**
+   * Infrastructure logger configured via {@link BrokerConfig.logger}.
+   *
+   * @internal Used by the facade layer.
+   */
+  logger;
+  constructor(config) {
+    this.logger = config?.logger ?? defaultLogger;
+    this.#hooks = new HooksRegistry(this.logger);
+    this.#systemEvents = new SystemEvents(this.logger);
+    this.#backpressure = new BackpressureHandler(this.logger);
+    this.#router = new Router(this.#subscriptions, this.logger);
+    if (config?.history?.enabled) {
+      this.#history = new MessageHistory(config.history);
+      this.#replay = new SubscriptionReplay(this.#history, this.#hooks, this.logger);
+    }
+    this.#inspect = new Inspector(
+      this.#clientRegistry,
+      this.#subscriptions,
+      this.#bridges,
+      () => this.#history
+    );
+  }
+  // ========================================
+  // SYSTEM EVENTS & INSPECT
+  // ========================================
+  /**
+   * Broker-internal system event channel (push model).
+   *
+   * The `$` prefix marks this as a broker-internal API. Intended for tooling:
+   * DevTools, tracing collectors, metrics integrations.
+   *
+   * This is NOT for extending broker behaviour — extension hooks are exposed
+   * via `useBeforeSendHook`, `useAfterSendHook`, `useOnSubscribeHook`.
+   *
+   * @example
+   * broker.$systemEvents.on('client.registered', ({ clientId }) => { ... });
+   * broker.$systemEvents.on('subscription.added', ({ clientId, topic }) => { ... });
+   */
+  get $systemEvents() {
+    return this.#systemEvents;
+  }
+  /**
+   * Point-in-time state snapshots (pull model).
+   *
+   * Read-only view over broker state for DevTools and debugging tools.
+   *
+   * @example
+   * const clients = broker.inspect.getClients();
+   * const history = broker.inspect.getHistory();
+   */
+  get inspect() {
+    return this.#inspect;
+  }
+  // ========================================
+  // SUBSCRIPTION MANAGEMENT
+  // ========================================
+  /**
+   * Subscribe a client to a topic.
+   *
+   * Multiple handlers may be attached to the same `(clientId, topic)` pair —
+   * each call returns a distinct subscription id that identifies THIS
+   * handler for later removal via {@link unsubscribeOne}.
+   *
+   * @returns Subscription id, or `0` when the call was a no-op (broker
+   *          destroyed). Zero is never a valid id.
+   *
+   * @throws Error if subscription is blocked on onSubscribe hook
+   *
+   * @internal Called by {@link BrokerClient.on}. Not part of the public
+   * `MessageBroker` contract.
+   */
+  subscribe(clientId, topic, handler, options) {
+    if (this.#isDestroyed) {
+      this.logger.warn("broker.subscribe.after_destroy", { clientId, topic });
+      return 0;
+    }
+    const hookResult = this.#hooks.onSubscribe(topic, clientId);
+    if (!hookResult.allowed) {
+      this.#systemEvents.emit("subscription.rejected", {
+        clientId,
+        topic,
+        reason: hookResult.message
+      });
+      throw new Error(hookResult.message);
+    }
+    const subscriptionId = this.#subscriptions.reserveId();
+    const wrappedHandler = this.#backpressure.wrap(
+      subscriptionId,
+      clientId,
+      topic,
+      handler,
+      options
+    );
+    this.#subscriptions.subscribe(clientId, topic, wrappedHandler, options, subscriptionId);
+    this.#systemEvents.emit("subscription.added", { clientId, topic, options });
+    if (options?.replay) {
+      if (!this.#replay) {
+        this.logger.warn("broker.replay.history_disabled", { clientId, topic });
+      } else {
+        this.#replay.start(clientId, topic, wrappedHandler, options.replay);
+      }
+    }
+    return subscriptionId;
+  }
+  /**
+   * Unsubscribe a client from a topic — removes every handler this client
+   * has attached to the topic.
+   *
+   * @internal Called by {@link BrokerClient.off}. Not part of the public
+   * `MessageBroker` contract.
+   */
+  unsubscribe(clientId, topic) {
+    const removed = this.#subscriptions.unsubscribe(clientId, topic);
+    if (removed.length === 0) return;
+    for (const entry of removed) {
+      this.#backpressure.removeOne(entry.id);
+    }
+    this.#systemEvents.emit("subscription.removed", { clientId, topic });
+  }
+  /**
+   * Unsubscribe a single handler by its subscription id.
+   *
+   * Fires `subscription.removed` only if this was the last handler that
+   * client had on the topic — otherwise the client is still subscribed.
+   *
+   * @internal Called by the unsubscribe closure returned from {@link BrokerClient.on}.
+   */
+  unsubscribeOne(subscriptionId) {
+    if (subscriptionId === 0) return;
+    const outcome = this.#subscriptions.unsubscribeOne(subscriptionId);
+    if (!outcome) return;
+    this.#backpressure.removeOne(outcome.entry.id);
+    if (outcome.wasLast) {
+      this.#systemEvents.emit("subscription.removed", {
+        clientId: outcome.clientId,
+        topic: outcome.topic
+      });
+    }
+  }
+  // ========================================
+  // MESSAGE DELIVERY
+  // ========================================
+  /**
+   * Process a message originating from a local client.
+   *
+   * Runs the full lifecycle pipeline: beforeSend → history → routing →
+   * afterSend → forward to bridges.
+   *
+   * @param topic - Type of message
+   * @param sender - Client ID of sender
+   * @param recipient - Target recipient: specific ClientID (unicast) or '*' (multicast)
+   * @param data - Message payload
+   * @param options - Message options (history)
+   * @returns Promise resolving to RoutingResult with delivery status
+   *
+   * @internal Called by {@link BrokerClient.emit} / {@link BrokerClient.request}.
+   * Not part of the public `MessageBroker` contract.
+   */
+  async processMessage(topic, sender, recipient, data, options) {
+    return this.#runPipeline(topic, sender, recipient, data, options, false, false);
+  }
+  /**
+   * Broker-internal debug channel.
+   *
+   * `send()` runs the full message pipeline exactly like a normal
+   * `Client.emit()` / `Client.request()` — routing, hooks, history and
+   * bridge forwarding all apply — but with two differences:
+   *
+   *  1. `source` is an arbitrary string, not tied to a registered client.
+   *     Nothing gets reset in the client registry: safe to «impersonate»
+   *     any client id for testing subscribers without breaking that
+   *     client's own subscriptions.
+   *  2. `message.synthetic === true` on the resulting Message, so
+   *     DevTools and integration tests can distinguish spoofed traffic
+   *     from production events (e.g. render a `SYNTHETIC` badge).
+   *
+   * Multicast vs unicast is picked by `target`: `'*'` fans out to all
+   * subscribers, a specific `ClientID` targets one recipient and captures
+   * that handler's return value in `RoutingResult.data`.
+   *
+   * The `$` prefix marks this as a broker-internal API — for DevTools
+   * and integration tests, not for business code.
+   */
+  get $debug() {
+    return {
+      send: (source, topic, target, data, options) => {
+        return this.#runPipeline(topic, source, target, data, options, false, true);
+      }
+    };
+  }
+  /**
+   * Shared pipeline body for local {@link processMessage} and external
+   * inject wired in {@link addBridge}.
+   *
+   * Pipeline stages:
+   *  1. Create Message (assign id, timestamp) and deep-freeze it.
+   *  2. Run `beforeSend` hooks. If any hook denies, short-circuit with
+   *     NACK(HOOK_REJECTED) — still fire `afterSend` so observers see the
+   *     rejection.
+   *  3. Record to history — ONLY for local-origin messages that explicitly
+   *     opt in via `options.history`. External (injected) messages are
+   *     skipped: the sender-side broker has already recorded them; recording
+   *     again here would duplicate on every bridge hop.
+   *  4. Route: unicast → one recipient, multicast (`*`) → all subscribers.
+   *  5. Run `afterSend` hooks with the delivery result.
+   *  6. Forward to bridges — ONLY for local-origin messages. External
+   *     messages are never bounced back to bridges; otherwise a bridge would
+   *     send what it just received right back to its transport.
+   *
+   * `fromExternal` gates stages 3 and 6 — the two places where local and
+   * external paths diverge. `synthetic` is metadata-only: routing, hooks,
+   * history and bridge forwarding all treat the message as real. Both
+   * flags are internal — never on the public API.
+   */
+  async #runPipeline(topic, sender, recipient, data, options, fromExternal, synthetic) {
+    if (this.#isDestroyed) {
+      return RoutingResult.create("NACK", RoutingReason.BROKER_DESTROYED, "Broker is destroyed");
+    }
+    const message = this.#createMessage(topic, sender, recipient, data);
+    if (fromExternal) {
+      message.fromExternal = true;
+    }
+    if (synthetic) {
+      message.synthetic = true;
+    }
+    const frozenMessage = deepFreeze(message);
+    const hookResult = this.#hooks.beforeSend(frozenMessage);
+    if (!hookResult.allowed) {
+      const result2 = RoutingResult.create(
+        "NACK",
+        RoutingReason.HOOK_REJECTED,
+        hookResult.message,
+        recipient !== "*" ? recipient : void 0
+      );
+      this.#systemEvents.emit("message.rejected", {
+        source: sender,
+        target: recipient,
+        topic,
+        reason: hookResult.message
+      });
+      this.#hooks.afterSend(frozenMessage, result2);
+      return result2;
+    }
+    if (this.#history && !fromExternal && options?.history === true) {
+      this.#history.record(frozenMessage);
+    }
+    const result = recipient === "*" ? await this.#router.multicast(frozenMessage, sender) : await this.#router.unicast(frozenMessage, recipient);
+    this.#hooks.afterSend(frozenMessage, result);
+    if (!fromExternal) {
+      this.#forwardToBridges(frozenMessage);
+    }
+    return result;
+  }
+  // ========================================
+  // BRIDGE MANAGEMENT
+  // ========================================
+  /**
+   * Add a bridge for cross-context communication (idempotent)
+   *
+   * If a bridge with the given ID already exists, the old bridge is destroyed
+   * and replaced with the new one. This prevents duplicate bridges during HMR.
+   *
+   * @param id - Unique identifier for the bridge (e.g. 'cross-tab', 'iframe-checkout')
+   * @param config - Bridge configuration (transport + forward patterns)
+   * @returns Function to remove the bridge
+   */
+  addBridge(id, config) {
+    if (this.#isDestroyed) {
+      this.logger.warn("broker.bridge.add.after_destroy", { bridgeId: id });
+      return () => {
+      };
+    }
+    const existing = this.#bridges.get(id);
+    if (existing) {
+      this.logger.warn("broker.bridge.replaced", { bridgeId: id });
+      existing.destroy();
+      this.#systemEvents.emit("bridge.removed", { bridgeId: id });
+    }
+    const inject = (topic, sender, recipient, data) => this.#runPipeline(topic, sender, recipient, data, void 0, true, false);
+    const bridge = new Bridge(inject, config, this.logger);
+    this.#bridges.set(id, bridge);
+    this.#systemEvents.emit("bridge.added", { bridgeId: id });
+    return () => {
+      if (this.#bridges.get(id) === bridge) {
+        this.#bridges.delete(id);
+        bridge.destroy();
+        this.#systemEvents.emit("bridge.removed", { bridgeId: id });
+      }
+    };
+  }
+  // ========================================
+  // CLIENT REGISTRY
+  // ========================================
+  /**
+   * Register a client instance.
+   *
+   * @internal Called by the `BrokerClient` constructor.
+   */
+  registerClient(client) {
+    if (this.#isDestroyed) {
+      this.logger.warn("broker.client.register.after_destroy", { clientId: client.id });
+      return;
+    }
+    this.#clientRegistry.register(client);
+    this.#systemEvents.emit("client.registered", {
+      clientId: client.id,
+      at: this.#clientRegistry.getConnectedAt(client.id) ?? Date.now()
+    });
+  }
+  /**
+   * Unregister a client and remove all its subscriptions.
+   *
+   * @internal Called by {@link BrokerClient.destroy}.
+   */
+  unregisterClient(clientId) {
+    const removed = this.#subscriptions.unsubscribeAll(clientId);
+    this.#clientRegistry.unregister(clientId);
+    for (const bucket of removed) {
+      for (const entry of bucket.entries) {
+        this.#backpressure.removeOne(entry.id);
+      }
+      this.#systemEvents.emit("subscription.removed", { clientId, topic: bucket.topic });
+    }
+    this.#systemEvents.emit("client.unregistered", { clientId, at: Date.now() });
+  }
+  /**
+   * Get a registered client by ID.
+   *
+   * @param clientId - Unique client identifier
+   * @returns Client instance or undefined if not found
+   *
+   * @internal Used by the `createClient` facade for idempotency checks.
+   */
+  getClient(clientId) {
+    return this.#clientRegistry.get(clientId);
+  }
+  /**
+   * Reset a client: clear all its subscriptions and backpressure strategies
+   * while keeping the client registered.
+   *
+   * Used for idempotent client creation (HMR, re-mounting).
+   * Iterates the client's subscriptions and calls unsubscribe() for each,
+   * which correctly flushes/destroys backpressure strategies.
+   *
+   * @param clientId - Unique client identifier
+   *
+   * @internal Called by {@link BrokerClient.reset} and by the
+   * `createClient` facade on idempotent re-creation.
+   */
+  resetClient(clientId) {
+    const topics = this.#subscriptions.getClientTopics(clientId);
+    if (topics) {
+      for (const topic of [...topics]) {
+        this.unsubscribe(clientId, topic);
+      }
+    }
+  }
+  // ========================================
+  // HOOKS & EXTENSIBILITY
+  // ========================================
+  /**
+   * Register a beforeSend hook
+   *
+   * Called before routing for ALL messages, including those from bridges.
+   * Use message.fromExternal to distinguish local vs external if needed.
+   */
+  useBeforeSendHook(hook) {
+    return this.#hooks.addBeforeSendHook(hook);
+  }
+  /**
+   * Register an afterSend hook
+   * Note: afterSend hooks are called for ALL messages (check message.fromExternal if needed)
+   */
+  useAfterSendHook(hook) {
+    return this.#hooks.addAfterSendHook(hook);
+  }
+  /**
+   * Register an onSubscribe hook
+   */
+  useOnSubscribeHook(hook) {
+    return this.#hooks.addOnSubscribeHook(hook);
+  }
+  // ========================================
+  // PRIVATE METHODS
+  // ========================================
+  /**
+   * Forward message to all bridges that match the topic
+   * @private
+   */
+  #forwardToBridges(message) {
+    for (const bridge of this.#bridges.values()) {
+      if (bridge.shouldForward(message.topic)) {
+        bridge.send(message);
+      }
+    }
+  }
+  /**
+   * Create a message with all required fields
+   *
+   * @private
+   */
+  #createMessage(topic, sender, recipient, data) {
+    return {
+      id: `${this.#sessionId}-${++this.#eventCounter}`,
+      topic,
+      source: sender,
+      target: recipient,
+      data,
+      timestamp: Date.now()
+    };
+  }
+  // ========================================
+  // LIFECYCLE & CLEANUP
+  // ========================================
+  /**
+   * Destroy the broker and clean up all resources
+   */
+  destroy() {
+    if (this.#isDestroyed) {
+      return;
+    }
+    this.#isDestroyed = true;
+    for (const bridge of this.#bridges.values()) {
+      bridge.destroy();
+    }
+    this.#bridges.clear();
+    this.#hooks.clear();
+    this.#history?.destroy();
+    const cleared = this.#subscriptions.clear();
+    for (const entry of cleared) {
+      this.#backpressure.removeOne(entry.id);
+    }
+    this.#backpressure.destroy();
+    this.#clientRegistry.clear();
+    this.#systemEvents.clear();
+  }
+};
+
+// src/core/client/BrokerClient.ts
+var BrokerClient = class {
+  id;
+  #core;
+  constructor(id, core2) {
+    this.id = id;
+    this.#core = core2;
+    this.#core.registerClient(this);
+  }
+  /**
+   * Subscribe to a topic with handler
+   *
+   * @param topic - Topic to subscribe to (e.g. 'user.login.v1')
+   * @param handler - Message handler function
+   * @param options - Subscription options (backpressure, replay)
+   * @returns Unsubscribe function
+   */
+  on(topic, handler, options) {
+    if (!handler) {
+      throw new Error("BrokerClient requires explicit handler function");
+    }
+    const subscriptionId = this.#core.subscribe(
+      this.id,
+      topic,
+      handler,
+      options
+    );
+    return () => {
+      this.#core.unsubscribeOne(subscriptionId);
+    };
+  }
+  /**
+   * Emit message to all subscribers (multicast)
+   */
+  async emit(topic, data, options) {
+    return this.#core.processMessage(topic, this.id, "*", data, options);
+  }
+  /**
+   * Send request to specific client (unicast).
+   *
+   * The recipient's handler return value (if any) is captured in
+   * `RoutingResult.data`. Caller specifies `R` to type that payload.
+   * The broker does not enforce that the handler actually returns `R` —
+   * the cast happens at the boundary, same trust level as `as R`.
+   */
+  async request(recipient, topic, data, options) {
+    return this.#core.processMessage(topic, this.id, recipient, data, options);
+  }
+  /**
+   * Unsubscribe from a topic
+   */
+  off(topic) {
+    this.#core.unsubscribe(this.id, topic);
+  }
+  /**
+   * Reset client: clear all subscriptions and backpressure strategies
+   * while keeping the client registered in the broker.
+   *
+   * After reset, the client can subscribe to messages again with fresh handlers.
+   * Existing backpressure strategies are flushed and destroyed.
+   */
+  reset() {
+    this.#core.resetClient(this.id);
+  }
+  /**
+   * Destroy client and cleanup resources
+   */
+  destroy() {
+    this.#core.unregisterClient(this.id);
+  }
+};
+
+// src/facade.ts
+var core = null;
+function initBroker(config) {
+  if (core) {
+    return core;
+  }
+  core = new BrokerCore(config);
+  return core;
+}
+function createClient(id) {
+  if (!core) {
+    throw new Error(
+      "MessageBroker not initialized. Call initBroker(config) first."
+    );
+  }
+  const existing = core.getClient(id);
+  if (existing) {
+    core.logger.warn("facade.createClient.reset", { clientId: id });
+    core.resetClient(id);
+    return existing;
+  }
+  return new BrokerClient(id, core);
+}
+function getBroker() {
+  if (!core) {
+    throw new Error(
+      "MessageBroker not initialized. Call initBroker(config) first."
+    );
+  }
+  return core;
+}
+function destroyBroker() {
+  core?.destroy();
+  core = null;
+}
+
+// src/transports/PostMessageTransport.ts
+var PostMessageTransport = class {
+  #target;
+  #origin;
+  #allowedOrigins;
+  #wildcardWarned = false;
+  #messageHandler = null;
+  #messageCallback = null;
+  constructor(config) {
+    this.#target = config.target;
+    this.#origin = config.origin ?? "*";
+    if (config.allowedOrigins !== void 0) {
+      this.#allowedOrigins = [...config.allowedOrigins];
+    } else if (this.#origin !== "*") {
+      this.#allowedOrigins = [this.#origin];
+    } else {
+      this.#allowedOrigins = null;
+    }
+  }
+  /**
+   * Send data to target window via postMessage
+   */
+  send(data) {
+    try {
+      this.#target.postMessage(data, this.#origin);
+    } catch (error) {
+      console.error("[PostMessageTransport] Failed to send:", error);
+    }
+  }
+  /**
+   * Subscribe to incoming messages from target window
+   */
+  onMessage(callback) {
+    this.#messageCallback = callback;
+    if (this.#allowedOrigins === null && !this.#wildcardWarned) {
+      this.#wildcardWarned = true;
+      console.warn(
+        "[PostMessageTransport] Listening with wildcard origin ('*') and no allowedOrigins \u2014 inbound messages from ANY origin will be accepted (source-window check still applies). Set `allowedOrigins` explicitly for cross-origin scenarios."
+      );
+    }
+    this.#messageHandler = (e) => {
+      if (e.source !== this.#target) {
+        return;
+      }
+      if (this.#allowedOrigins !== null && !this.#allowedOrigins.includes(e.origin)) {
+        console.warn(
+          `[PostMessageTransport] Message from unauthorized origin: ${e.origin} (allowed: ${this.#allowedOrigins.join(", ")})`
+        );
+        return;
+      }
+      this.#messageCallback?.(e.data);
+    };
+    window.addEventListener("message", this.#messageHandler);
+    return () => this.destroy();
+  }
+  /**
+   * Cleanup: remove event listener
+   */
+  destroy() {
+    if (this.#messageHandler) {
+      window.removeEventListener("message", this.#messageHandler);
+      this.#messageHandler = null;
+    }
+    this.#messageCallback = null;
+  }
+};
+
+// src/transports/BroadcastChannelTransport.ts
+var BroadcastChannelTransport = class {
+  #channel;
+  #messageCallback = null;
+  /**
+   * @param channelName - Unique channel name for this application
+   */
+  constructor(channelName) {
+    this.#channel = new BroadcastChannel(channelName);
+  }
+  /**
+   * Broadcast data to all other tabs
+   */
+  send(data) {
+    try {
+      this.#channel.postMessage(data);
+    } catch (error) {
+      console.error("[BroadcastChannelTransport] Failed to send:", error);
+    }
+  }
+  /**
+   * Subscribe to messages from other tabs
+   */
+  onMessage(callback) {
+    this.#messageCallback = callback;
+    this.#channel.onmessage = (e) => {
+      this.#messageCallback?.(e.data);
+    };
+    return () => this.destroy();
+  }
+  /**
+   * Cleanup: close the channel
+   */
+  destroy() {
+    this.#channel.onmessage = null;
+    this.#messageCallback = null;
+    this.#channel.close();
+  }
+};
+
+// src/transports/WebSocketTransport.ts
+var WebSocketTransport = class {
+  #socket;
+  #messageCallback = null;
+  #messageHandler = null;
+  /**
+   * @param socket - WebSocket instance (managed externally)
+   */
+  constructor(socket) {
+    this.#socket = socket;
+  }
+  /**
+   * Send data to server via WebSocket
+   */
+  send(data) {
+    if (this.#socket.readyState !== WebSocket.OPEN) {
+      console.warn("[WebSocketTransport] Cannot send: socket not open");
+      return;
+    }
+    try {
+      this.#socket.send(JSON.stringify(data));
+    } catch (error) {
+      console.error("[WebSocketTransport] Failed to send:", error);
+    }
+  }
+  /**
+   * Subscribe to messages from server
+   */
+  onMessage(callback) {
+    this.#messageCallback = callback;
+    this.#messageHandler = (e) => {
+      try {
+        const data = typeof e.data === "string" ? JSON.parse(e.data) : e.data;
+        this.#messageCallback?.(data);
+      } catch (error) {
+        console.error("[WebSocketTransport] Failed to parse message:", error);
+      }
+    };
+    this.#socket.addEventListener("message", this.#messageHandler);
+    return () => this.destroy();
+  }
+  /**
+   * Cleanup: remove listener (does NOT close socket)
+   */
+  destroy() {
+    if (this.#messageHandler) {
+      this.#socket.removeEventListener("message", this.#messageHandler);
+      this.#messageHandler = null;
+    }
+    this.#messageCallback = null;
+  }
+};
+
+// src/transports/SSETransport.ts
+var SSETransport = class {
+  #eventSource;
+  #eventName;
+  #messageHandler = null;
+  #messageCallback = null;
+  constructor(config) {
+    this.#eventName = config.eventName ?? "message";
+    this.#eventSource = new EventSource(config.url, {
+      withCredentials: config.withCredentials ?? false
+    });
+  }
+  /**
+   * SSE has no upstream channel from the browser. This method exists to
+   * satisfy the {@link BridgeTransport} contract but never actually
+   * transmits — it logs a warning so misconfigurations surface early.
+   *
+   * Practical guidance: keep the bridge's `forward` list to topics that
+   * are ONLY emitted by the server (never by local clients), so this
+   * warning never fires in normal operation.
+   */
+  send(_data) {
+    console.warn(
+      "[SSETransport] send() is a no-op \u2014 SSE is inbound-only. Ensure the bridge forward list contains topics emitted only by the server, or use WebSocketTransport for duplex traffic."
+    );
+  }
+  /**
+   * Subscribe to incoming SSE messages. Parses JSON payloads before
+   * forwarding to the bridge.
+   */
+  onMessage(callback) {
+    this.#messageCallback = callback;
+    this.#messageHandler = (e) => {
+      try {
+        const data = typeof e.data === "string" ? JSON.parse(e.data) : e.data;
+        this.#messageCallback?.(data);
+      } catch (error) {
+        console.error("[SSETransport] Failed to parse message:", error);
+      }
+    };
+    this.#eventSource.addEventListener(this.#eventName, this.#messageHandler);
+    return () => this.destroy();
+  }
+  /**
+   * Cleanup: remove listener and close the underlying EventSource.
+   */
+  destroy() {
+    if (this.#messageHandler) {
+      this.#eventSource.removeEventListener(this.#eventName, this.#messageHandler);
+      this.#messageHandler = null;
+    }
+    this.#messageCallback = null;
+    this.#eventSource.close();
+  }
+};
+
+exports.BroadcastChannelTransport = BroadcastChannelTransport;
+exports.PostMessageTransport = PostMessageTransport;
+exports.RoutingReason = RoutingReason;
+exports.SSETransport = SSETransport;
+exports.WebSocketTransport = WebSocketTransport;
+exports.createClient = createClient;
+exports.defaultLogger = defaultLogger;
+exports.destroyBroker = destroyBroker;
+exports.getBroker = getBroker;
+exports.initBroker = initBroker;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map