@hedwigjs/broker 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1507 @@
+/**
+ * Backpressure strategies to control message processing rate
+ *
+ * Control how messages are processed to prevent UI freezing and optimize performance.
+ * All strategies are mutually exclusive - only one can be used per subscription.
+ */
+interface BackpressureOptions {
+    /**
+     * Throttle: Limit handler calls to once per `throttle` milliseconds
+     *
+     * First call executes immediately, subsequent calls are delayed.
+     * Guarantees maximum call rate without losing the last message.
+     *
+     * Use case: Real-time charts, high-frequency updates
+     */
+    throttle?: number;
+    /**
+     * Debounce: Delay handler execution until `debounce` milliseconds of silence
+     *
+     * Resets timer on each new message. Only the last message is processed.
+     *
+     * Use case: Search autocomplete, input validation
+     */
+    debounce?: number;
+    /**
+     * Rate limiting: Drop messages exceeding rate limit
+     *
+     * Allows maximum `max` messages per `window` milliseconds.
+     * Messages exceeding the limit are dropped (lost permanently).
+     *
+     * Use case: Prevent flooding, protect from bursts, spam protection
+     */
+    rateLimit?: {
+        /** Maximum number of messages allowed */
+        max: number;
+        /** Time window in milliseconds */
+        window: number;
+    };
+    /**
+     * Callback when messages are dropped (rate limiting only)
+     *
+     * @param droppedCount - Number of messages dropped so far
+     */
+    onDrop?: (droppedCount: number) => void;
+}
+
+/**
+ * All structured log events emitted by the broker infrastructure.
+ *
+ * These are machine-readable codes — stable across versions.
+ * Use them as filter keys in Sentry / Datadog / Grafana.
+ */
+type BrokerLogEvent = 'broker.subscribe.after_destroy' | 'broker.bridge.add.after_destroy' | 'broker.bridge.replaced' | 'broker.client.register.after_destroy' | 'broker.replay.history_disabled' | 'facade.createClient.reset' | 'handler.failed' | 'hook.after_send.failed' | 'hook.failed' | 'bridge.message.parse_failed' | 'backpressure.handler.failed' | 'backpressure.on_drop.failed' | 'replay.handler.failed' | 'replay.query.failed' | 'system_events.listener.failed';
+/**
+ * Pluggable logger interface for broker infrastructure events.
+ *
+ * Implement this to redirect broker warnings and errors to your
+ * observability stack (Sentry, Datadog, pino, etc.).
+ *
+ * @example
+ * initBroker({
+ *   logger: {
+ *     warn: (event, meta) => myLogger.warn(event, meta),
+ *     error: (event, meta) => Sentry.captureMessage(event, { extra: meta }),
+ *   }
+ * });
+ */
+interface BrokerLogger {
+    warn(event: BrokerLogEvent, meta?: Record<string, unknown>): void;
+    error(event: BrokerLogEvent, meta?: Record<string, unknown>): void;
+}
+/**
+ * Default logger — forwards to console.
+ * Used when no logger is provided in BrokerConfig.
+ */
+declare const defaultLogger: BrokerLogger;
+
+/** Unique client identifier in the system */
+type ClientID = string;
+/**
+ * Internal message format for inter-module communication
+ */
+interface Message<T extends string = string, P = any> {
+    /** Unique message identifier (e.g. "abc-42") for debugging and DevTools */
+    id: string;
+    /** Message topic (e.g. 'user.login.v1') */
+    topic: T;
+    /** Message source - client ID that emitted the message */
+    source: string;
+    /** Target client ID or '*' for broadcast */
+    target: string;
+    /** Message payload data */
+    data: P;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Indicates if this is a replayed historical message */
+    replayed?: boolean;
+    /** Indicates if this message was received from external source (bridge) */
+    fromExternal?: boolean;
+    /**
+     * Marks a debug/test message injected via `broker.$debug.send(...)`.
+     * Routing, hooks, history and bridge forwarding all treat it as a
+     * real message — the flag is purely metadata so DevTools and integration
+     * tests can distinguish spoofed traffic from production events.
+     */
+    synthetic?: boolean;
+}
+/**
+ * Message handler function
+ * Can return data for Request-Reply pattern
+ */
+type HandlerFn<T extends string, P = unknown> = (message: Message<T, P>) => void | any | Promise<void | any>;
+/**
+ * Type-erased message handler for internal core usage
+ *
+ * Same contract as HandlerFn but without generic type parameters.
+ * Used in Broker, Subscriptions, Router, BackpressureHandler
+ * where specific message/payload types are already erased.
+ */
+type MessageHandler = (message: Message) => void | any | Promise<void | any>;
+/**
+ * Options for message emission and requests
+ */
+interface MessageOptions {
+    /**
+     * Record this message to history for replay
+     *
+     * Important: History has limited capacity (default 1000 messages).
+     * Only mark truly important messages that late subscribers need to replay.
+     *
+     * @default false
+     */
+    history?: boolean;
+}
+/**
+ * Options for replaying historical messages
+ */
+interface ReplayOptions {
+    /**
+     * Maximum number of historical messages to replay
+     * If not specified, replays all matching messages
+     */
+    limit?: number;
+    /**
+     * Replay messages starting from this timestamp (Unix ms)
+     */
+    since?: number;
+    /**
+     * Replay messages until this timestamp (Unix ms)
+     */
+    until?: number;
+}
+/**
+ * Options for message subscription
+ *
+ * Controls how messages are processed and delivered to handlers.
+ * All options are opt-in and can be combined.
+ */
+interface SubscriptionOptions {
+    /**
+     * Backpressure control strategies for incoming messages
+     *
+     * Controls the rate and manner of message processing to prevent
+     * UI freezing and optimize performance.
+     */
+    backpressure?: BackpressureOptions;
+    /**
+     * Replay historical messages when subscribing
+     *
+     * Allows late subscribers to catch up on missed messages.
+     * Messages are replayed asynchronously after subscription is established.
+     */
+    replay?: ReplayOptions;
+}
+interface ClientSubscriptionInfo {
+    topic: string;
+    /**
+     * Options of the first handler registered on this (client, topic) pair.
+     * A pair may hold multiple handlers, each with distinct options — this
+     * field surfaces one representative set for observability tools that
+     * predate the multi-handler model.
+     */
+    options?: SubscriptionOptions;
+    /** Total number of handlers this client has attached to the topic. */
+    handlerCount: number;
+}
+/** Point-in-time snapshot of a single registered client. */
+interface ClientInfo {
+    id: ClientID;
+    /** Unix timestamp (ms) when the client registered. */
+    connectedAt: number;
+    subscriptions: ClientSubscriptionInfo[];
+}
+/**
+ * Configuration for Broker
+ */
+interface BrokerConfig {
+    /** Message history configuration */
+    history?: {
+        /** Enable message history */
+        enabled: boolean;
+        /** Maximum number of messages to keep in memory (default: 1000) */
+        maxSize?: number;
+        /** Time to live for messages (ms). undefined = no expiration */
+        ttl?: number;
+    };
+    /**
+     * Pluggable logger for broker infrastructure events.
+     *
+     * Receives structured event codes (e.g. `'handler.failed'`) and a metadata
+     * object. Use this to redirect broker warnings and errors to your
+     * observability stack (Sentry, Datadog, pino, etc.).
+     *
+     * Defaults to `console.warn` / `console.error` when not provided.
+     */
+    logger?: BrokerLogger;
+}
+
+declare const RoutingReason: {
+    readonly DELIVERED: "DELIVERED";
+    readonly DISPATCHED: "DISPATCHED";
+    readonly REPLAY_DELIVERED: "REPLAY_DELIVERED";
+    readonly HOOK_REJECTED: "HOOK_REJECTED";
+    readonly NO_SUBSCRIBERS: "NO_SUBSCRIBERS";
+    readonly NOT_SUBSCRIBED: "NOT_SUBSCRIBED";
+    readonly HANDLER_FAILED: "HANDLER_FAILED";
+    readonly BROKER_DESTROYED: "BROKER_DESTROYED";
+};
+type RoutingReasonType = (typeof RoutingReason)[keyof typeof RoutingReason];
+/**
+ * RoutingResult - Message delivery result (Value Object)
+ *
+ * Immutable object representing the result of a message dispatch operation.
+ * Can only be created through the static factory method create().
+ */
+declare class RoutingResult<TResponse = unknown> {
+    readonly status: 'ACK' | 'NACK';
+    readonly reason: RoutingReasonType;
+    readonly message: string;
+    readonly timestamp: number;
+    /** Recipient client ID — set for unicast, undefined for multicast. */
+    readonly recipientId?: ClientID;
+    /** All recipient client IDs — set for multicast, undefined for unicast. */
+    readonly recipientIds?: ClientID[];
+    readonly data?: TResponse;
+    private constructor();
+    /**
+     * @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<T = unknown>(status: 'ACK' | 'NACK', reason: RoutingReasonType, message: string, recipientId?: ClientID, data?: T, recipientIds?: ClientID[]): RoutingResult<T>;
+}
+
+/**
+ * Pluggable wire used by {@link BridgeConfig} / {@link MessageBroker.addBridge}.
+ *
+ * This is the extension point for cross-context transports. Built-in
+ * implementations (`PostMessageTransport`, `BroadcastChannelTransport`,
+ * `WebSocketTransport`, `SSETransport`) are exported from `@hedwigjs/broker`;
+ * custom transports (WebRTC, Service Worker, Electron IPC, etc.) plug in by
+ * implementing this interface — no other broker internals need to be touched.
+ *
+ * ## Contract
+ *
+ * ### Outbound — `send(data)`
+ * Called by the {@link Bridge} whenever a local broker message matches the
+ * bridge's forward patterns. Implementation must serialize (if needed) and
+ * hand the payload to the underlying wire. Errors should be caught and
+ * logged, not thrown — a failing wire must not crash the broker pipeline.
+ *
+ * ### Inbound — `onMessage(callback)`
+ * Called once by the {@link Bridge} at construction time to subscribe to
+ * incoming messages. Implementation must invoke `callback` for every valid
+ * inbound payload after any transport-level validation (e.g. origin checks
+ * for postMessage, channel filtering for BroadcastChannel). Returns an
+ * unsubscribe function; the {@link Bridge} calls it in `destroy()`.
+ *
+ * ### Cleanup — `destroy()`
+ * Called when the bridge is removed or the broker is destroyed. Must release
+ * all resources (event listeners, sockets, channels). Must be idempotent.
+ *
+ * ## Security note
+ *
+ * Transports are the trust boundary between the broker and the outside
+ * world. If your wire crosses origins (postMessage, WebSocket, SSE),
+ * validate the source before invoking the inbound callback — the broker
+ * will otherwise route whatever it receives.
+ *
+ * @example Custom transport skeleton
+ * ```ts
+ * class MyTransport implements BridgeTransport {
+ *   #cb: ((data: unknown) => void) | null = null;
+ *
+ *   send(data: unknown): void {
+ *     try { myWire.publish(data); }
+ *     catch (e) { console.error('[MyTransport] send failed:', e); }
+ *   }
+ *
+ *   onMessage(cb: (data: unknown) => void): () => void {
+ *     this.#cb = cb;
+ *     const off = myWire.subscribe((payload) => {
+ *       if (!isTrusted(payload)) return;
+ *       this.#cb?.(payload);
+ *     });
+ *     return () => { off(); this.#cb = null; };
+ *   }
+ *
+ *   destroy(): void { this.#cb = null; myWire.close(); }
+ * }
+ * ```
+ */
+interface BridgeTransport {
+    /** Outbound: send a payload to the wire. See interface docs for contract. */
+    send(data: unknown): void;
+    /** Inbound: subscribe to payloads from the wire. Returns unsubscribe. */
+    onMessage(callback: (data: unknown) => void): () => void;
+    /** Release resources. Must be idempotent. */
+    destroy(): void;
+}
+/**
+ * Bridge configuration
+ */
+interface BridgeConfig {
+    /** Low-level duplex link (see {@link BridgeTransport}) */
+    transport: BridgeTransport;
+    /** Message patterns to forward (e.g. ['user.*', 'theme.*']) */
+    forward: string[];
+}
+/**
+ * Bridge interface - transport layer for cross-context communication
+ *
+ * Bridge forwards messages
+ * between broker and external contexts (iframes, tabs, servers).
+ */
+interface Bridge {
+    /** Topic patterns this bridge forwards to its transport. */
+    readonly forwardPatterns: ReadonlyArray<string>;
+    /**
+     * Transport class name with the `Transport` suffix stripped
+     * (e.g. `WebSocket`, `SSE`). Used only by the Inspector to label
+     * bridges in DevTools. `undefined` for transports whose constructor
+     * is an anonymous class.
+     */
+    readonly transportKind?: string;
+    /**
+     * Check if topic should be forwarded to transport
+     */
+    shouldForward(topic: string): boolean;
+    /**
+     * Send message to transport
+     */
+    send(message: Message): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+
+/**
+ * System events - internal signals about broker state transitions.
+ *
+ * These are NOT user messages. System events expose infrastructure-level
+ * state changes (client/subscription/bridge lifecycle) that are not
+ * observable through the hook pipeline.
+ *
+ * Intended consumers:
+ * - DevTools (message-broker-devtools)
+ * - Tracing / metrics integrations
+ *
+ * These events are FIRE-AND-FORGET. Listeners cannot influence the pipeline;
+ * exceptions thrown from a listener are caught and logged, not propagated.
+ *
+ * Exposed on the broker under `$systemEvents` (the `$` prefix signals that
+ * this is a broker-internal channel, distinct from user message pub/sub).
+ */
+interface SystemEventMap<T extends string, P extends Record<T, any>> {
+    'client.registered': {
+        clientId: ClientID;
+        /** Unix ms when the client was registered. */
+        at: number;
+    };
+    'client.unregistered': {
+        clientId: ClientID;
+        /** Unix ms when the client was unregistered. */
+        at: number;
+    };
+    'subscription.added': {
+        clientId: ClientID;
+        topic: T;
+        options?: SubscriptionOptions;
+    };
+    'subscription.removed': {
+        clientId: ClientID;
+        topic: T;
+    };
+    /**
+     * Fired when an `onSubscribe` hook denied a subscription attempt. The
+     * broker still throws on the caller so the subscription is NOT registered;
+     * this event exists so observability tools (DevTools, ACL audit) can pick
+     * up the denial without racing the exception.
+     */
+    'subscription.rejected': {
+        clientId: ClientID;
+        topic: T;
+        reason: string;
+    };
+    /**
+     * Fired when a `beforeSend` hook denied an outgoing message. The message
+     * also surfaces in the delivery result as `NACK HOOK_REJECTED`, but this
+     * event lets pure-observability consumers listen for security signals on a
+     * dedicated channel without inspecting every RoutingResult.
+     */
+    'message.rejected': {
+        source: ClientID;
+        target: ClientID | '*';
+        topic: T;
+        reason: string;
+    };
+    'bridge.added': {
+        bridgeId: string;
+    };
+    'bridge.removed': {
+        bridgeId: string;
+    };
+}
+type SystemEventName<T extends string, P extends Record<T, any>> = keyof SystemEventMap<T, P>;
+type SystemEventPayload<T extends string, P extends Record<T, any>, K extends SystemEventName<T, P>> = SystemEventMap<T, P>[K];
+/**
+ * Listener for a specific system event. Receives the event payload.
+ * Exceptions are caught by the dispatcher.
+ */
+type SystemEventListener<T extends string, P extends Record<T, any>, K extends SystemEventName<T, P>> = (payload: SystemEventPayload<T, P, K>) => void;
+/**
+ * Listener that receives every system event with its name.
+ * Useful for universal recorders (e.g. DevTools event log).
+ */
+type SystemAnyEventListener<T extends string, P extends Record<T, any>> = <K extends SystemEventName<T, P>>(event: K, payload: SystemEventPayload<T, P, K>) => void;
+/**
+ * Subscriber contract for the system event channel.
+ *
+ * Consumers (DevTools, tracing, metrics) use this to subscribe. Listeners
+ * are fire-and-forget — they cannot influence the pipeline, and exceptions
+ * they throw are caught and logged, never propagated.
+ *
+ * `emit()` and `clear()` are intentionally absent: only `BrokerCore`
+ * (which holds the concrete `SystemEvents` instance) can publish events
+ * or tear down listeners.
+ */
+interface SystemEventsEmitter<T extends string, P extends Record<T, any>> {
+    /**
+     * Subscribe to a specific system event.
+     * @returns Unsubscribe function.
+     */
+    on<K extends SystemEventName<T, P>>(event: K, listener: SystemEventListener<T, P, K>): () => void;
+    /**
+     * Subscribe once — listener is automatically removed after first invocation.
+     * @returns Unsubscribe function.
+     */
+    once<K extends SystemEventName<T, P>>(event: K, listener: SystemEventListener<T, P, K>): () => void;
+    /**
+     * Remove all listeners for a given event. Omit `event` to clear everything.
+     */
+    off<K extends SystemEventName<T, P>>(event?: K): void;
+    /**
+     * Subscribe to every system event with one listener.
+     * Useful for DevTools panels that need a unified event feed.
+     * @returns Unsubscribe function.
+     */
+    onAny(listener: SystemAnyEventListener<T, P>): () => void;
+    /**
+     * Number of registered listeners for a given event, or total across all
+     * events when called without arguments. Useful for tests and fast-path checks.
+     */
+    listenerCount<K extends SystemEventName<T, P>>(event?: K): number;
+}
+
+/**
+ * Result of hook execution
+ */
+type HookResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    message: string;
+};
+/**
+ * Hook function types
+ */
+type OnSubscribeHook<T> = (topic: T, clientId: ClientID) => HookResult;
+/** Called before each message is sent. Return { allowed: false } to block. */
+type BeforeSendHook<T extends string, P extends Record<T, any>> = (message: Readonly<Message<T, P[T]>>) => HookResult;
+/** Called after each message is sent. Receives delivery result. */
+type AfterSendHook<T extends string, P extends Record<T, any>> = (message: Readonly<Message<T, P[T]>>, messageResult: RoutingResult) => void;
+
+/**
+ * BrokerCore — low-level message broker engine, internal implementation
+ * of the public {@link MessageBroker} interface.
+ *
+ * Responsibilities:
+ * - Message routing and delivery pipeline (hooks → routing → history → bridges)
+ * - Subscription management (delegates to Subscriptions)
+ * - Coordinate Router, HooksRegistry, ClientRegistry
+ * - Bridge management for cross-context communication
+ * - Message history & replay
+ * - Emit system events on the internal system events channel
+ * - Expose state snapshots via the inspect facade
+ * - Lifecycle management
+ *
+ * The class is exported within the package for unit tests. Consumers
+ * receive only the `MessageBroker<T, P>` contract from `initBroker()` /
+ * `getBroker()`. Methods tagged `@internal` (subscribe, unsubscribe,
+ * processMessage, registerClient, unregisterClient, resetClient,
+ * getClient) form the internal protocol between
+ * BrokerClient, Bridge and the facade — they are stable only inside the
+ * package and may change without notice.
+ */
+declare class BrokerCore<T extends string, P extends Record<T, any>> implements MessageBroker<T, P> {
+    #private;
+    /**
+     * Infrastructure logger configured via {@link BrokerConfig.logger}.
+     *
+     * @internal Used by the facade layer.
+     */
+    readonly logger: BrokerLogger;
+    constructor(config?: BrokerConfig);
+    /**
+     * 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(): SystemEventsEmitter<T, P>;
+    /**
+     * 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(): Inspector<T, P>;
+    /**
+     * 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: ClientID, topic: T, handler: MessageHandler, options?: SubscriptionOptions): number;
+    /**
+     * 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: ClientID, topic: T): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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.
+     */
+    processMessage<K extends T, R = unknown>(topic: K, sender: ClientID, recipient: ClientID | '*', data: P[K], options?: MessageOptions): Promise<RoutingResult<R>>;
+    /**
+     * 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(): {
+        send<K extends T, R = unknown>(source: ClientID, topic: K, target: ClientID | '*', data: P[K], options?: MessageOptions): Promise<RoutingResult<R>>;
+    };
+    /**
+     * 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: string, config: BridgeConfig): () => void;
+    /**
+     * Register a client instance.
+     *
+     * @internal Called by the `BrokerClient` constructor.
+     */
+    registerClient(client: BrokerClient<T, P>): void;
+    /**
+     * Unregister a client and remove all its subscriptions.
+     *
+     * @internal Called by {@link BrokerClient.destroy}.
+     */
+    unregisterClient(clientId: ClientID): void;
+    /**
+     * 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: ClientID): BrokerClient<T, P> | undefined;
+    /**
+     * 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: ClientID): void;
+    /**
+     * 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: BeforeSendHook<T, P>): () => void;
+    /**
+     * Register an afterSend hook
+     * Note: afterSend hooks are called for ALL messages (check message.fromExternal if needed)
+     */
+    useAfterSendHook(hook: AfterSendHook<T, P>): () => void;
+    /**
+     * Register an onSubscribe hook
+     */
+    useOnSubscribeHook(hook: OnSubscribeHook<T>): () => void;
+    /**
+     * Destroy the broker and clean up all resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Client — the public contract of a broker-connected client.
+ *
+ * Instances are obtained via `createClient(id)`. Consumers should treat
+ * this as the stable surface — the underlying class is an internal
+ * implementation detail and may change in minor releases.
+ *
+ * A client provides three things:
+ *  - subscription (`on` / `off`) to a topic,
+ *  - message emission: broadcast (`emit`) or targeted (`request`),
+ *  - lifecycle control (`reset`, `destroy`).
+ */
+interface Client<T extends string, P extends Record<T, any>> {
+    /** Unique client identifier passed to `createClient(id)`. */
+    readonly id: ClientID;
+    /**
+     * Subscribe to a topic.
+     *
+     * @param topic - Topic name (e.g. `'user.login.v1'`).
+     * @param handler - Handler invoked for every matching message.
+     * @param options - Subscription options (backpressure strategy, replay).
+     * @returns Unsubscribe function. Equivalent to `client.off(topic)`.
+     * @throws If an `onSubscribe` hook rejects the subscription.
+     */
+    on<K extends T>(topic: K, handler: HandlerFn<K, P[K]>, options?: SubscriptionOptions): () => void;
+    /**
+     * Unsubscribe from a topic. No-op if the client was not subscribed.
+     */
+    off<K extends T>(topic: K): void;
+    /**
+     * Broadcast a message to every subscriber of `topic` (multicast).
+     *
+     * @returns Promise resolving to the aggregated {@link RoutingResult}.
+     */
+    emit<K extends T>(topic: K, data: P[K], options?: MessageOptions): Promise<RoutingResult>;
+    /**
+     * Send a targeted message to a specific recipient (unicast).
+     *
+     * @typeParam R - Expected shape of the handler's return value, surfaced
+     *   on `RoutingResult.data`. Defaults to `unknown` — caller must specify
+     *   to get a typed response (e.g. `client.request<'user.fetch', User>(…)`).
+     *   Not enforced against the handler signature; treated as a boundary cast.
+     * @returns Promise resolving to the {@link RoutingResult} for that one
+     *   recipient.
+     */
+    request<K extends T, R = unknown>(recipient: ClientID, topic: K, data: P[K], options?: MessageOptions): Promise<RoutingResult<R>>;
+    /**
+     * Reset the client: flush and drop every subscription and its
+     * backpressure strategy while keeping the client registered.
+     *
+     * Used by `createClient(id)` for idempotent creation (HMR, re-mount).
+     */
+    reset(): void;
+    /**
+     * Destroy the client: unregister it and remove all its subscriptions.
+     * After `destroy()` the client instance becomes inert.
+     */
+    destroy(): void;
+}
+
+/**
+ * BrokerClient — concrete implementation of the {@link Client} contract.
+ *
+ * Created by the facade function `createClient(id)`. Use cases:
+ * - Communication between microfrontends in the same browser context
+ * - Fastest possible message delivery (no serialization)
+ * - Default choice for most applications
+ *
+ * Consumers should treat `Client<T, P>` as the stable surface — this
+ * class is an internal implementation detail. It is exported within the
+ * package so unit tests can construct instances directly with a
+ * `BrokerCore` stub, but it is NOT part of the public API: transport of
+ * `BrokerClient` through the package exports map is disabled.
+ */
+declare class BrokerClient<T extends string, P extends Record<T, any>> implements Client<T, P> {
+    #private;
+    readonly id: ClientID;
+    constructor(id: ClientID, core: BrokerCore<T, P>);
+    /**
+     * 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<K extends T>(topic: K, handler: HandlerFn<K, P[K]>, options?: SubscriptionOptions): () => void;
+    /**
+     * Emit message to all subscribers (multicast)
+     */
+    emit<K extends T>(topic: K, data: P[K], options?: MessageOptions): Promise<RoutingResult>;
+    /**
+     * 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`.
+     */
+    request<K extends T, R = unknown>(recipient: ClientID, topic: K, data: P[K], options?: MessageOptions): Promise<RoutingResult<R>>;
+    /**
+     * Unsubscribe from a topic
+     */
+    off<K extends T>(topic: K): void;
+    /**
+     * 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(): void;
+    /**
+     * Destroy client and cleanup resources
+     */
+    destroy(): void;
+}
+
+/**
+ * ClientRegistry - Manages registered clients
+ *
+ * Responsibilities:
+ * - Register/unregister clients
+ * - Track active clients
+ * - Provide client lookup
+ *
+ * Used for observability and DevTools integration
+ */
+declare class ClientRegistry<T extends string, P extends Record<T, any>> {
+    #private;
+    /**
+     * Register a client
+     */
+    register(client: BrokerClient<T, P>): void;
+    /**
+     * Unregister a client
+     */
+    unregister(clientId: ClientID): void;
+    /**
+     * Get the timestamp when a client registered (Unix ms)
+     */
+    getConnectedAt(clientId: ClientID): number | undefined;
+    /**
+     * Get client by ID
+     */
+    get(clientId: ClientID): BrokerClient<T, P> | undefined;
+    /**
+     * Check if client is registered
+     */
+    has(clientId: ClientID): boolean;
+    /**
+     * Get all registered clients
+     */
+    getAll(): BrokerClient<T, P>[];
+    /**
+     * Get all client IDs
+     */
+    getAllIds(): ClientID[];
+    /**
+     * Clear all clients
+     */
+    clear(): void;
+    /**
+     * Get number of registered clients
+     */
+    get size(): number;
+}
+
+/**
+ * Subscriptions - Efficient subscription and handler management
+ *
+ * A single `(clientId, topic)` pair may hold MANY handlers. Each individual
+ * subscription is identified by a monotonic numeric id returned from
+ * {@link subscribe}, so callers can remove one handler without touching the
+ * others. Bulk operations (`unsubscribe(clientId, topic)`,
+ * `unsubscribeAll(clientId)`) still nuke every handler in scope.
+ *
+ * Bidirectional indexes for O(1) lookups:
+ * - Topic → Clients mapping (multicast recipient lookup — a client appears
+ *   once no matter how many handlers it registered)
+ * - Client → Topics mapping (unsubscribe fan-out)
+ * - Composite key → ordered handler entries
+ * - Subscription id → location (for O(1) per-handler removal)
+ *
+ * @internal This class is used internally by BrokerCore and Router
+ */
+/** Opaque handle returned by {@link Subscriptions.subscribe}. */
+type SubscriptionId = number;
+type SubscriptionEntry = {
+    readonly id: SubscriptionId;
+    readonly handler: MessageHandler;
+    readonly options?: SubscriptionOptions;
+};
+declare class Subscriptions<T extends string> {
+    #private;
+    /**
+     * 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(): SubscriptionId;
+    /**
+     * 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: ClientID, topic: T, handler: MessageHandler, options?: SubscriptionOptions, preReservedId?: SubscriptionId): SubscriptionId;
+    /**
+     * 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: SubscriptionId): {
+        entry: SubscriptionEntry;
+        clientId: ClientID;
+        topic: T;
+        wasLast: boolean;
+    } | undefined;
+    /**
+     * 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: ClientID, topic: T): readonly SubscriptionEntry[];
+    /**
+     * 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: ClientID): ReadonlyArray<{
+        topic: T;
+        entries: readonly SubscriptionEntry[];
+    }>;
+    /**
+     * Get all topics a client is subscribed to
+     */
+    getClientTopics(clientId: ClientID): ReadonlySet<T> | undefined;
+    /**
+     * Check if a client has at least one handler on a topic.
+     */
+    isSubscribed(clientId: ClientID, topic: T): boolean;
+    /**
+     * All handler entries a client has on a topic, in registration order.
+     */
+    getEntries(clientId: ClientID, topic: T): readonly SubscriptionEntry[];
+    /**
+     * 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: ClientID, topic: T): SubscriptionOptions | undefined;
+    /**
+     * Number of handlers a client holds on a topic (0 = not subscribed).
+     */
+    getHandlerCount(clientId: ClientID, topic: T): number;
+    /**
+     * Get all subscribers for a topic (read-only)
+     */
+    getSubscribers(topic: T): ReadonlySet<ClientID>;
+    /**
+     * Get list of all clients that have active subscriptions
+     */
+    getAllSubscribedClients(): ClientID[];
+    /**
+     * Get detailed subscription map for all clients
+     */
+    getAllSubscriptions(): Record<string, string[]>;
+    /**
+     * Clear all subscriptions and handlers.
+     *
+     * @returns All entries that were held, so the caller can release
+     *          per-handler resources (e.g. backpressure strategies).
+     */
+    clear(): readonly SubscriptionEntry[];
+}
+
+/**
+ * Entry in message history with metadata
+ */
+interface HistoryEntry<T extends string = string, P = any> {
+    /** The message itself (immutable) */
+    message: Readonly<Message<T, P>>;
+    /** Unix timestamp (ms) when message was recorded */
+    timestamp: number;
+    /** Sequence number for guaranteed ordering */
+    sequence: number;
+}
+/**
+ * Filter for querying message history
+ */
+interface HistoryFilter<T extends string = string> {
+    /** Topics to filter (supports glob patterns like 'user.*') */
+    topics?: T[];
+    /** Filter by event sources */
+    sources?: ClientID[];
+    /** Start timestamp (inclusive) */
+    since?: number;
+    /** End timestamp (inclusive) */
+    until?: number;
+    /** Maximum number of messages to return */
+    limit?: number;
+}
+/**
+ * Configuration for message history
+ */
+interface HistoryConfig {
+    /** Enable message history */
+    enabled: boolean;
+    /** Maximum number of messages to keep in memory (default: 1000) */
+    maxSize?: number;
+    /** Time to live for messages (ms). undefined = no expiration */
+    ttl?: number;
+}
+/**
+ * Statistics about message history
+ */
+interface HistoryStats {
+    /** Total number of messages in history */
+    count: number;
+    /** Unix timestamp (ms) of oldest message */
+    oldestTimestamp?: number;
+    /** Unix timestamp (ms) of newest message */
+    newestTimestamp?: number;
+    /** Memory usage estimate (bytes) */
+    memoryUsage?: number;
+}
+
+/**
+ * MessageHistory - In-memory message history
+ *
+ * Features:
+ * - FIFO eviction when maxSize is reached
+ * - TTL-based automatic cleanup
+ * - Glob pattern matching for topics
+ * - Immutable messages (deepFreeze)
+ * - Efficient filtering
+ */
+declare class MessageHistory<T extends string, P extends Record<T, any>> {
+    #private;
+    constructor(config: HistoryConfig);
+    /**
+     * Record a message to history
+     */
+    record(message: Message<T, P[T]>): void;
+    /**
+     * Query messages from history
+     */
+    query(filter?: HistoryFilter<T>): Promise<HistoryEntry<T, P[T]>[]>;
+    /**
+     * Clear messages from history
+     */
+    clear(filter?: HistoryFilter<T>): Promise<void>;
+    /**
+     * Return a point-in-time snapshot of all entries (oldest → newest).
+     */
+    getSnapshot(): ReadonlyArray<HistoryEntry<T, P[T]>>;
+    /**
+     * Get history statistics
+     */
+    getStats(): HistoryStats;
+    /**
+     * Cleanup and destroy
+     */
+    destroy(): void;
+}
+
+/**
+ * Read-only view of a registered bridge.
+ *
+ * Produced by `broker.inspect.getBridges()`. Does NOT leak the internal
+ * `Bridge` instance (`transport`, lifecycle methods, etc.) — only the
+ * information useful for DevTools / debugging.
+ */
+interface BridgeInfo {
+    /** Unique bridge identifier passed to `addBridge(id, ...)`. */
+    id: string;
+    /** Topic patterns this bridge forwards to its transport. */
+    forwardPatterns: ReadonlyArray<string>;
+    /**
+     * Transport class name with the `Transport` suffix stripped —
+     * e.g. `WebSocket`, `PostMessage`, `SSE`, `BroadcastChannel`, or the
+     * bare constructor name for custom implementations. `undefined` when
+     * the transport was created from an anonymous class expression.
+     */
+    transportKind?: string;
+}
+
+/**
+ * Inspector - read-only view over broker state.
+ *
+ * Exposed via `broker.inspect`. Intended for DevTools, debugging tools, and
+ * diagnostic integrations that need point-in-time state snapshots (pull model).
+ * Pair with `broker.$systemEvents` (push model) for incremental updates.
+ *
+ * This class is a pure facade over internal registries — it does NOT own data,
+ * it only aggregates and projects it. Dependencies are injected as references,
+ * so adding new snapshot methods does not require changing the constructor
+ * shape or threading callbacks through `BrokerCore`.
+ *
+ * All collection-returning methods return `ReadonlyArray<T>` to prevent
+ * accidental mutation of broker state by external callers.
+ */
+declare class Inspector<T extends string, P extends Record<T, any>> {
+    #private;
+    constructor(clients: ClientRegistry<T, P>, subscriptions: Subscriptions<T>, bridges: ReadonlyMap<string, Bridge>, getHistory: () => MessageHistory<T, P> | undefined);
+    /**
+     * 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(): ReadonlyArray<ClientInfo>;
+    /**
+     * IDs of clients that have at least one active subscription.
+     */
+    getSubscribedClientIds(): ReadonlyArray<ClientID>;
+    /**
+     * Lifecycle info for every registered bridge. Does NOT expose internal
+     * `Bridge` instances (see `BridgeInfo`).
+     */
+    getBridges(): ReadonlyArray<BridgeInfo>;
+    /**
+     * All messages currently stored in the replay buffer (oldest → newest).
+     * Returns an empty array when history is not enabled.
+     */
+    getHistory(): ReadonlyArray<HistoryEntry>;
+    /**
+     * Replay buffer statistics. Always returns `{ enabled: false, count: 0 }`
+     * when history is not enabled.
+     */
+    getHistoryStats(): HistoryStats & {
+        enabled: boolean;
+    };
+}
+
+/**
+ * Broker-internal debug channel — see {@link MessageBroker.$debug}.
+ */
+interface DebugChannel<T extends string, P extends Record<T, any>> {
+    /**
+     * Inject a message into the pipeline with an arbitrary `source`.
+     *
+     * Runs full routing/hooks/history/bridge-forward like a normal emit;
+     * only difference is `message.synthetic === true` and `source` is not
+     * validated against the client registry. Multicast when `target === '*'`,
+     * unicast otherwise (return value from the handler is captured in
+     * `RoutingResult.data`).
+     */
+    send<K extends T, R = unknown>(source: ClientID, topic: K, target: ClientID | '*', data: P[K], options?: MessageOptions): Promise<RoutingResult<R>>;
+}
+/**
+ * MessageBroker — the public contract of the broker instance.
+ *
+ * This is the type returned by `initBroker()` / `getBroker()`. It exposes
+ * the stable, user-facing surface of the broker and intentionally HIDES
+ * low-level internals (message pipeline, subscription management, client
+ * registry plumbing) which are accessed via the {@link Client} instances
+ * returned by `createClient()`.
+ *
+ * The broker surface is organized in three groups:
+ *
+ * 1. **Tooling APIs** — stable channels for DevTools / observers.
+ *    - `$systemEvents` (push) for lifecycle events.
+ *    - `inspect` (pull) for point-in-time state snapshots.
+ *
+ * 2. **Extensibility** — hooks that let adapters and plugins alter or
+ *    observe broker behaviour without reaching into internals.
+ *    - `useBeforeSendHook`, `useAfterSendHook`, `useOnSubscribeHook`.
+ *
+ * 3. **Infrastructure wiring** — bridges for cross-context delivery.
+ *    - `addBridge(id, { transport, forward })`. Pass a {@link BridgeTransport}
+ *      instance; built-in implementations are used internally by framework
+ *      adapters and are not part of the public surface.
+ *
+ * 4. **Lifecycle**
+ *    - `destroy()` for clean shutdown.
+ */
+interface MessageBroker<T extends string, P extends Record<T, any>> {
+    /**
+     * Broker-internal system event channel (push model).
+     *
+     * The `$` prefix marks this as a broker-internal API. Intended for
+     * tooling: DevTools, tracing collectors, metrics integrations.
+     *
+     * Not for extending broker behaviour — use the `use*Hook` methods
+     * for that.
+     *
+     * @example
+     * broker.$systemEvents.on('client.registered', ({ clientId }) => { ... });
+     * broker.$systemEvents.on('subscription.added', ({ clientId, topic }) => { ... });
+     */
+    readonly $systemEvents: SystemEventsEmitter<T, P>;
+    /**
+     * 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();
+     */
+    readonly inspect: Inspector<T, P>;
+    /**
+     * Broker-internal debug channel (test / DevTools).
+     *
+     * `$debug.send(source, topic, target, data)` runs the full pipeline
+     * with an arbitrary source id and no client-registry side effects.
+     * Messages are tagged `synthetic: true` so tools can distinguish
+     * spoofed traffic from production events. See {@link DebugChannel}.
+     *
+     * The `$` prefix marks this as broker-internal — for DevTools and
+     * integration tests, not for business code.
+     */
+    readonly $debug: DebugChannel<T, P>;
+    /**
+     * Register a bridge for cross-context communication (idempotent).
+     *
+     * A bridge forwards messages whose topic matches `forward` patterns to
+     * the given {@link BridgeTransport}, and injects messages coming back from
+     * the transport into this broker. Framework adapters supply the transport;
+     * this package does not export concrete transport classes.
+     *
+     * If a bridge with the given `id` already exists, the old one is
+     * destroyed and replaced. This keeps the operation HMR-safe.
+     *
+     * @param id - Unique bridge identifier (e.g. `'cross-tab'`, `'iframe-checkout'`).
+     * @param config - Bridge configuration: `transport` + `forward` patterns.
+     * @returns Function that removes the bridge and tears down its listeners.
+     */
+    addBridge(id: string, config: BridgeConfig): () => void;
+    /**
+     * Register a `beforeSend` hook.
+     *
+     * Invoked synchronously before every message enters the routing stage,
+     * for both locally-emitted AND externally-injected (bridge) messages.
+     * Use `message.fromExternal` to distinguish.
+     *
+     * A hook returning `{ allowed: false, message }` short-circuits the
+     * pipeline with a `NACK(HOOK_REJECTED)`.
+     */
+    useBeforeSendHook(hook: BeforeSendHook<T, P>): () => void;
+    /**
+     * Register an `afterSend` hook.
+     *
+     * Invoked after routing completes, regardless of success. Receives the
+     * frozen message and the final {@link RoutingResult}. Runs for both
+     * local and external messages.
+     */
+    useAfterSendHook(hook: AfterSendHook<T, P>): () => void;
+    /**
+     * Register an `onSubscribe` hook.
+     *
+     * Invoked synchronously when a client subscribes to a topic. A hook
+     * returning `{ allowed: false, message }` prevents the subscription —
+     * `BrokerClient.on()` will throw with `message`.
+     */
+    useOnSubscribeHook(hook: OnSubscribeHook<T>): () => void;
+    /**
+     * Shut the broker down and release all resources.
+     *
+     * Destroys every bridge, clears subscriptions, history, hooks and the
+     * client registry. After `destroy()` the broker becomes inert: further
+     * calls are no-ops with console warnings.
+     */
+    destroy(): void;
+}
+
+/**
+ * Initialize the message broker (idempotent).
+ *
+ * Called once by the host application (e.g. the shell / app bootstrap).
+ * If the broker is already initialized, the existing instance is returned
+ * without changes. To reinitialize, call {@link destroyBroker} first.
+ *
+ * @param config - Broker configuration (history, etc.).
+ * @returns The broker instance typed against the caller's Topics/Payloads.
+ */
+declare function initBroker<T extends string = string, P extends Record<T, any> = any>(config?: BrokerConfig): MessageBroker<T, P>;
+/**
+ * Create or retrieve a client for message communication (idempotent).
+ *
+ * If a client with the given ID already exists, its subscriptions and
+ * backpressure strategies are reset and the existing instance is returned.
+ * Safe for HMR and component re-mounting scenarios.
+ *
+ * Pass explicit type parameters to get a fully typed client without a cast:
+ *
+ * @example
+ * import type { Topic, TopicPayloads } from '@hedwigjs/registry';
+ * const client = createClient<Topic, TopicPayloads>('cart');
+ *
+ * @param id - Unique identifier for the client.
+ * @throws Error if the broker has not been initialized.
+ */
+declare function createClient<T extends string = string, P extends Record<T, any> = any>(id: string): Client<T, P>;
+/**
+ * Get the current broker instance.
+ *
+ * Use when you need access to broker methods (hooks, `$systemEvents`,
+ * `inspect`, `addBridge`) without holding the reference returned by
+ * {@link initBroker}.
+ *
+ * Types can be passed explicitly: `getBroker<MyTopics, MyPayloads>()`.
+ *
+ * @throws Error if the broker has not been initialized.
+ */
+declare function getBroker<T extends string = string, P extends Record<T, any> = any>(): MessageBroker<T, P>;
+/**
+ * Destroy the broker and release all resources.
+ *
+ * Destroys bridges, clears subscriptions, history, and the client registry.
+ */
+declare function destroyBroker(): void;
+
+/**
+ * Configuration for PostMessageTransport
+ */
+interface PostMessageTransportConfig {
+    /** Target window to communicate with (iframe.contentWindow, window.parent, etc.) */
+    target: Window;
+    /**
+     * Target origin for outbound `postMessage` calls.
+     * Use `'*'` only for trusted contexts — the browser will otherwise refuse
+     * to deliver the message if the target's origin doesn't match.
+     * @default '*'
+     */
+    origin?: string;
+    /**
+     * Explicit allowlist for **inbound** message origins.
+     *
+     * When set, only messages whose `e.origin` is included in this list are
+     * forwarded to the broker; others are dropped with a `console.warn`. This
+     * is the trust boundary between the broker and cross-origin iframes.
+     *
+     * When omitted, inbound validation falls back to `origin`:
+     *  - If `origin` is an explicit URL, it acts as a single-item allowlist.
+     *  - If `origin` is `'*'`, all origins are accepted (a `console.warn` is
+     *    emitted at construction time — this mode is intended only for
+     *    trusted contexts and should not be used in production against
+     *    untrusted iframes).
+     *
+     * Prefer setting `allowedOrigins` explicitly for cross-origin scenarios.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * PostMessageTransport - Transport for cross-window communication
+ *
+ * Uses `window.postMessage` for iframe/popup communication.
+ *
+ * Security:
+ * - Validates message source window (must match configured `target`).
+ * - Validates message origin against `allowedOrigins` (explicit allowlist)
+ *   or `origin` (fallback single-item allowlist).
+ */
+declare class PostMessageTransport implements BridgeTransport {
+    #private;
+    constructor(config: PostMessageTransportConfig);
+    /**
+     * Send data to target window via postMessage
+     */
+    send(data: unknown): void;
+    /**
+     * Subscribe to incoming messages from target window
+     */
+    onMessage(callback: (data: unknown) => void): () => void;
+    /**
+     * Cleanup: remove event listener
+     */
+    destroy(): void;
+}
+
+/**
+ * BroadcastChannelTransport - Transport for cross-tab communication
+ *
+ * Uses BroadcastChannel API for communication between browser tabs
+ * of the same origin.
+ *
+ * Use cases:
+ * - Sync user session across tabs
+ * - Sync theme/locale preferences
+ * - Broadcast notifications to all tabs
+ */
+declare class BroadcastChannelTransport implements BridgeTransport {
+    #private;
+    /**
+     * @param channelName - Unique channel name for this application
+     */
+    constructor(channelName: string);
+    /**
+     * Broadcast data to all other tabs
+     */
+    send(data: unknown): void;
+    /**
+     * Subscribe to messages from other tabs
+     */
+    onMessage(callback: (data: unknown) => void): () => void;
+    /**
+     * Cleanup: close the channel
+     */
+    destroy(): void;
+}
+
+/**
+ * WebSocketTransport - Transport wrapper for WebSocket
+ *
+ * Simple wrapper that forwards messages to/from an existing WebSocket.
+ * All connection management (connect, reconnect, etc.) is handled externally.
+ */
+declare class WebSocketTransport implements BridgeTransport {
+    #private;
+    /**
+     * @param socket - WebSocket instance (managed externally)
+     */
+    constructor(socket: WebSocket);
+    /**
+     * Send data to server via WebSocket
+     */
+    send(data: unknown): void;
+    /**
+     * Subscribe to messages from server
+     */
+    onMessage(callback: (data: unknown) => void): () => void;
+    /**
+     * Cleanup: remove listener (does NOT close socket)
+     */
+    destroy(): void;
+}
+
+/**
+ * Configuration for {@link SSETransport}.
+ */
+interface SSETransportConfig {
+    /**
+     * URL of the Server-Sent Events endpoint. `EventSource` is created
+     * internally and the browser handles reconnection.
+     */
+    url: string;
+    /**
+     * If set, subscribes to a named SSE event (`event: <name>`) instead of
+     * the default unnamed `message` stream. Broker Messages already carry
+     * their own `topic` field, so most integrations leave this unset and
+     * multiplex on the topic.
+     */
+    eventName?: string;
+    /**
+     * Passed to `new EventSource(url, { withCredentials })`. Enables sending
+     * cookies for same-origin auth on cross-origin SSE endpoints.
+     */
+    withCredentials?: boolean;
+}
+/**
+ * SSETransport — inbound-only transport backed by `EventSource`.
+ *
+ * SSE is server → client by design. `send()` is a no-op with a warning;
+ * bridges built on top of this transport are effectively receive-only.
+ * If your integration needs client → server frames, use
+ * {@link WebSocketTransport} or pair SSE with a separate POST endpoint.
+ *
+ * Reconnect handling is delegated to the browser's built-in EventSource
+ * behavior — no external backoff required, unlike WebSocket where the
+ * transport wraps an already-connected socket.
+ *
+ * Expects incoming payloads to be JSON-encoded broker Messages
+ * (`{id, topic, source, target, data, timestamp}`) — the same wire
+ * format all the other bridges use.
+ */
+declare class SSETransport implements BridgeTransport {
+    #private;
+    constructor(config: SSETransportConfig);
+    /**
+     * 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: unknown): void;
+    /**
+     * Subscribe to incoming SSE messages. Parses JSON payloads before
+     * forwarding to the bridge.
+     */
+    onMessage(callback: (data: unknown) => void): () => void;
+    /**
+     * Cleanup: remove listener and close the underlying EventSource.
+     */
+    destroy(): void;
+}
+
+export { type AfterSendHook, type BackpressureOptions, type BeforeSendHook, type BridgeConfig, type BridgeInfo, type BridgeTransport, BroadcastChannelTransport, type BrokerConfig, type BrokerLogEvent, type BrokerLogger, type Client, type ClientID, type ClientInfo, type ClientSubscriptionInfo, type HandlerFn, type HistoryEntry, type HistoryStats, type HookResult, Inspector, type Message, type MessageBroker, type MessageHandler, type MessageOptions, type OnSubscribeHook, PostMessageTransport, type PostMessageTransportConfig, type ReplayOptions, RoutingReason, type RoutingReasonType, RoutingResult, SSETransport, type SSETransportConfig, type SubscriptionOptions, type SystemAnyEventListener, type SystemEventListener, type SystemEventMap, type SystemEventName, type SystemEventPayload, type SystemEventsEmitter, WebSocketTransport, createClient, defaultLogger, destroyBroker, getBroker, initBroker };