skills/plugins/document-navigator/docs/networking/events/broadcast-channel/README.md

@suaveplan/broadcast-channel - Typed cross-tab messaging built on the BroadcastChannel API — leader election, tab presence, Zod-validated boundaries, OpenTelemetry-instrumented hot paths, StorageLike-backed fallback for Safari < 15.4. Browser-tier.

Typed cross-tab messaging built on the Web BroadcastChannel API. Browser-tier package — leader election, tab presence and heartbeats, message-type handler registry, Zod-validated boundaries, OpenTelemetry-instrumented hot paths, deterministic Clock / Rng / LoggerLike injection, and a StorageLike-backed fallback transport for Safari < 15.4 (and any sandbox where the native BroadcastChannel is unavailable).

Documentation tree

• ask — AskController is the request-side engine for the cross-tab request/response primitive layered on top of `TypedBroadca…
  • ask — AskController is the request-side engine for the cross-tab request/response primitive layered on top of `TypedBroadca…
  • responder — AskResponderRegistry is the response-side counterpart to AskController. It maps an inbound handlerKey to the sing…
• channel — TypedBroadcastChannel is the high-level cross-tab messaging object exported by @suaveplan/broadcast-channel. It wra…
  • channel — TypedBroadcastChannel is the high-level cross-tab messaging object exported by @suaveplan/broadcast-channel. It wra…
  • heartbeat — HeartbeatRunner is a tiny lifecycle helper that owns the pair of setInterval timers a TypedBroadcastChannel needs…
• errors — This module declares the stable error-code registry for @suaveplan/broadcast-channel. Every error the package throws…
  • codes — This module declares the stable error-code registry for @suaveplan/broadcast-channel. Every error the package throws…
• id — generateId is the shared 16-character lowercase-hex identifier generator used for tab IDs and per-message IDs through…
  • id — generateId is the shared 16-character lowercase-hex identifier generator used for tab IDs and per-message IDs through…
• logger — noopLogger is a shared zero-cost LoggerLike implementation used as the default by TypedBroadcastChannel and by `c…
  • noop — noopLogger is a shared zero-cost LoggerLike implementation used as the default by TypedBroadcastChannel and by `c…
• otel — This module declares the six OpenTelemetry counter instruments emitted by @suaveplan/broadcast-channel. Every counter…
  • metrics — This module declares the six OpenTelemetry counter instruments emitted by @suaveplan/broadcast-channel. Every counter…
• schemas — This module declares the Zod boundary schemas for @suaveplan/broadcast-channel. ChannelMessageSchema validates ever…
  • messages — This module declares the Zod boundary schemas for @suaveplan/broadcast-channel. ChannelMessageSchema validates ever…
• local-storage — createLocalStorageChannelFactory is the StorageLike-backed fallback transport. Use it whenever the host lacks a nat…
• native — nativeChannelFactory is a thin adapter that exposes the global BroadcastChannel constructor as a ChannelLike. Use…

Install

bun add @suaveplan/broadcast-channel

Quick start

import {
    nativeChannelFactory,
    TypedBroadcastChannel,
} from "@suaveplan/broadcast-channel";

const channel = new TypedBroadcastChannel({
    config: { name: "app-bus" },
    factory: nativeChannelFactory,
});

channel.open();
channel.on<{ userId: string }>("user:signed-in", (msg) => {
    console.log(`peer tab ${msg.senderId} signed in as ${msg.payload.userId}`);
});
channel.send("user:signed-in", { userId: "u_123" });

Fallback transport (Safari < 15.4)

import {
    createLocalStorageChannelFactory,
    isNativeBroadcastChannelAvailable,
    nativeChannelFactory,
    TypedBroadcastChannel,
} from "@suaveplan/broadcast-channel";
import { yourStorageLike } from "./storage";

const factory = isNativeBroadcastChannelAvailable()
    ? nativeChannelFactory
    : createLocalStorageChannelFactory(yourStorageLike, {
          pollIntervalMs: 50,
          retentionMs: 30_000,
      });

const channel = new TypedBroadcastChannel({
    config: { name: "app-bus" },
    factory,
});

Modules

• channel/channel — TypedBroadcastChannel core.
• channel/heartbeat — HeartbeatRunner interval pair.
• errors/codes — BROADCAST_CHANNEL_CODES registry + four typed error subclasses.
• id/id — generateId(rng) shared 16-hex id generator.
• logger/noop — shared no-op LoggerLike default.
• otel/metrics — six OpenTelemetry counters.
• schemas/messages — Zod boundary schemas.
• transport/native — native BroadcastChannel adapter.
• transport/local-storage — StorageLike-backed fallback.
• types/broadcast-channel — public shapes.

Error codes

Code	When
BROADCAST_CHANNEL.CHANNEL_CLOSED	send() called before open() or after close()
BROADCAST_CHANNEL.MESSAGE_MALFORMED	inbound frame fails ChannelMessageSchema
BROADCAST_CHANNEL.PAYLOAD_TOO_LARGE	outbound payload exceeds config.maxMessageBytes (default 1 MiB)
BROADCAST_CHANNEL.STORAGE_FAILED	fallback-transport StorageLike get/set/list/delete rejected

OpenTelemetry

Six counters under meter @suaveplan/broadcast-channel@0.1.0:

• channel.message.sent ({ type, channel })
• channel.message.received ({ type, channel })
• channel.message.dropped ({ reason, channel })
• channel.tab.joined ({ channel })
• channel.tab.left ({ channel })
• channel.leader.elected ({ channel })

License

MIT