MessageChannel:
  A <---- private pipe ----> B

BroadcastChannel:
  A ----+
  B ----+---- same channel name ---- all listening contexts
  C ----+

const channel = new BroadcastChannel("app-session");

channel.postMessage({
  type: "logout",
  reason: "user-clicked-logout",
});

channel.onmessage = (event) => {
  console.log(event.data);
};

BroadcastChannel is a volatile signal bus.
It tells interested peers that something happened.
It should not be the only source of durable truth.

wrong:
  broadcast contains truth

better:
  durable store contains truth
  broadcast says: truth changed, go read it

BroadcastChannel reaches contexts that share the appropriate origin/storage partition boundary.
Do not assume every same-origin context in every embedding scenario can hear each other.

new BroadcastChannel("events");

function createChannelName(input: {
  appId: string;
  environment: "dev" | "staging" | "prod";
  protocol: string;
  version: number;
}): string {
  return `${input.appId}:${input.environment}:${input.protocol}:v${input.version}`;
}

const channel = new BroadcastChannel(createChannelName({
  appId: "regulatory-case-platform",
  environment: "prod",
  protocol: "session-events",
  version: 1,
}));

type BroadcastEnvelope<TType extends string, TPayload> = {
  protocol: "com.acme.browser-bus";
  version: 1;
  messageId: string;
  type: TType;
  senderId: string;
  tabId: string;
  epoch: number;
  createdAtMs: number;
  payload: TPayload;
};

type SessionLogout = BroadcastEnvelope<"session.logout", {
  reason: "user-action" | "server-revoked" | "token-expired";
}>;

type CacheInvalidated = BroadcastEnvelope<"cache.invalidated", {
  namespace: "case-list" | "case-detail" | "user-profile";
  key?: string;
}>;

type TabHeartbeat = BroadcastEnvelope<"tab.heartbeat", {
  visible: boolean;
  route: string;
}>;

type Handler<T> = (message: T) => void;

export class BrowserBroadcastBus<TMessage extends { type: string; messageId: string; senderId: string }> {
  private readonly channel: BroadcastChannel;
  private readonly handlers = new Map<string, Set<Handler<TMessage>>>();
  private readonly seen = new Set<string>();

  constructor(
    channelName: string,
    private readonly senderId: string,
    private readonly maxSeen = 1_000
  ) {
    this.channel = new BroadcastChannel(channelName);

    this.channel.addEventListener("message", (event) => {
      this.receive(event.data);
    });

    this.channel.addEventListener("messageerror", () => {
      console.error("BroadcastChannel messageerror", { channelName });
    });
  }

  publish(message: Omit<TMessage, "messageId" | "senderId">): void {
    const fullMessage = {
      ...message,
      messageId: crypto.randomUUID(),
      senderId: this.senderId,
    } as TMessage;

    this.remember(fullMessage.messageId);
    this.channel.postMessage(fullMessage);
  }

  subscribe(type: string, handler: Handler<TMessage>): () => void {
    let set = this.handlers.get(type);
    if (!set) {
      set = new Set();
      this.handlers.set(type, set);
    }

    set.add(handler);

    return () => {
      set?.delete(handler);
      if (set?.size === 0) this.handlers.delete(type);
    };
  }

  close(): void {
    this.handlers.clear();
    this.channel.close();
  }

  private receive(value: unknown): void {
    if (!isBusMessage(value)) return;

    const message = value as TMessage;

    if (message.senderId === this.senderId) {
      return;
    }

    if (this.seen.has(message.messageId)) {
      return;
    }

    this.remember(message.messageId);

    const handlers = this.handlers.get(message.type);
    if (!handlers) return;

    for (const handler of handlers) {
      handler(message);
    }
  }

  private remember(messageId: string): void {
    this.seen.add(messageId);

    if (this.seen.size <= this.maxSeen) return;

    const first = this.seen.values().next().value;
    if (first) this.seen.delete(first);
  }
}

function isBusMessage(value: unknown): value is {
  type: string;
  messageId: string;
  senderId: string;
} {
  if (!value || typeof value !== "object") return false;
  const record = value as Record<string, unknown>;
  return typeof record.type === "string" &&
    typeof record.messageId === "string" &&
    typeof record.senderId === "string";
}

type SessionBusMessage =
  | {
      type: "session.logout";
      messageId: string;
      senderId: string;
      reason: "user-action" | "server-revoked" | "token-expired";
      createdAtMs: number;
    }
  | {
      type: "session.changed";
      messageId: string;
      senderId: string;
      createdAtMs: number;
    };

const bus = new BrowserBroadcastBus<SessionBusMessage>(
  "case-platform:prod:session:v1",
  getOrCreateTabInstanceId()
);

function logout(reason: SessionBusMessage["reason"]): void {
  clearLocalSessionState();

  bus.publish({
    type: "session.logout",
    reason,
    createdAtMs: Date.now(),
  });

  redirectToLogin();
}

bus.subscribe("session.logout", (message) => {
  clearLocalSessionState();
  redirectToLogin({ reason: message.reason });
});

Logout must not depend only on receiving broadcast.

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    validateSessionOnResume();
  }
});

bus.publish({
  type: "case.updated",
  case: hugeCaseObject,
});

bus.publish({
  type: "cache.invalidated",
  namespace: "case-detail",
  key: caseId,
  revision,
  createdAtMs: Date.now(),
});

bus.subscribe("cache.invalidated", (message) => {
  if (message.namespace !== "case-detail") return;

  cache.markStale(message.key);

  if (isCurrentRouteCase(message.key)) {
    void refetchCase(message.key);
  }
});

Broadcast should carry invalidation metadata, not the source of truth.

type PresenceMessage =
  | {
      type: "tab.hello";
      messageId: string;
      senderId: string;
      tabId: string;
      route: string;
      visible: boolean;
      createdAtMs: number;
    }
  | {
      type: "tab.heartbeat";
      messageId: string;
      senderId: string;
      tabId: string;
      route: string;
      visible: boolean;
      createdAtMs: number;
    }
  | {
      type: "tab.goodbye";
      messageId: string;
      senderId: string;
      tabId: string;
      createdAtMs: number;
    };

type TabRecord = {
  tabId: string;
  route: string;
  visible: boolean;
  lastSeenAt: number;
};

class TabPresenceRegistry {
  private readonly tabs = new Map<string, TabRecord>();

  upsert(message: Extract<PresenceMessage, { type: "tab.hello" | "tab.heartbeat" }>): void {
    this.tabs.set(message.tabId, {
      tabId: message.tabId,
      route: message.route,
      visible: message.visible,
      lastSeenAt: Date.now(),
    });
  }

  remove(tabId: string): void {
    this.tabs.delete(tabId);
  }

  sweep(now = Date.now(), ttlMs = 30_000): void {
    for (const [tabId, record] of this.tabs) {
      if (now - record.lastSeenAt > ttlMs) {
        this.tabs.delete(tabId);
      }
    }
  }

  list(): TabRecord[] {
    return [...this.tabs.values()];
  }
}

const tabId = getOrCreateTabInstanceId();

function publishHeartbeat(): void {
  bus.publish({
    type: "tab.heartbeat",
    tabId,
    route: location.pathname,
    visible: document.visibilityState === "visible",
    createdAtMs: Date.now(),
  });
}

const heartbeatTimer = setInterval(publishHeartbeat, 10_000);

window.addEventListener("pagehide", () => {
  bus.publish({
    type: "tab.goodbye",
    tabId,
    createdAtMs: Date.now(),
  });

  clearInterval(heartbeatTimer);
});

Goodbye is best-effort. TTL sweep is mandatory.

bus.publish({
  type: "leader.heartbeat",
  leaderId,
  epoch,
  createdAtMs: Date.now(),
});

BroadcastChannel can announce leadership.
It should not be the only lock.

type SingleFlightMessage =
  | {
      type: "singleflight.started";
      messageId: string;
      senderId: string;
      key: string;
      ownerTabId: string;
      createdAtMs: number;
    }
  | {
      type: "singleflight.completed";
      messageId: string;
      senderId: string;
      key: string;
      ownerTabId: string;
      revision: string;
      createdAtMs: number;
    }
  | {
      type: "singleflight.failed";
      messageId: string;
      senderId: string;
      key: string;
      ownerTabId: string;
      retryable: boolean;
      createdAtMs: number;
    };

Broadcast request/reply means everyone hears every request.

type DiscoveryRequest = {
  type: "discovery.request";
  messageId: string;
  senderId: string;
  requestId: string;
};

type DiscoveryResponse = {
  type: "discovery.response";
  messageId: string;
  senderId: string;
  requestId: string;
  capabilities: string[];
};

BroadcastChannel for discovery
MessageChannel for private session
Web Locks for mutual exclusion
IndexedDB/Cache/OPFS for durable state/artifacts

bus.publish({
  type: "token.refreshed",
  accessToken,
  refreshToken,
});

bus.publish({
  type: "session.changed",
  createdAtMs: Date.now(),
});

Broadcast metadata and references, not bulk data.

bus.publish({
  type: "artifact.ready",
  artifactId,
  store: "indexeddb",
  revision,
});

bus.publish({
  type: "artifact.ready",
  hugeJsonDocument,
});

channel.close();

function mountFeature(): () => void {
  const channel = new BroadcastChannel("feature-x:v1");

  channel.addEventListener("message", onMessage);

  return () => {
    channel.removeEventListener("message", onMessage);
    channel.close();
  };
}

export const sessionBus = new BrowserBroadcastBus<SessionBusMessage>(
  "case-platform:prod:session:v1",
  getOrCreateTabInstanceId()
);

export function attachSessionLogoutHandler(onLogout: (reason: string) => void): () => void {
  return sessionBus.subscribe("session.logout", (message) => {
    onLogout(message.reason);
  });
}

On foreground/resume:
  re-read durable state.

On broadcast received:
  treat message as hint, not complete truth.

On startup:
  reconstruct local runtime from durable state, not past broadcasts.

async function reconcileOnResume(): Promise<void> {
  const session = await sessionStore.read();

  if (!session.valid) {
    redirectToLogin();
    return;
  }

  await cache.revalidateStaleEntries();
}

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    void reconcileOnResume();
  }
});

window.addEventListener("pageshow", (event) => {
  if (event.persisted) {
    void reconcileOnResume();
  }
});

type EntityChanged = {
  type: "entity.changed";
  messageId: string;
  senderId: string;
  entityType: "case";
  entityId: string;
  revision: string;
  createdAtMs: number;
};

bus.subscribe("entity.changed", (message) => {
  const current = revisionStore.get(message.entityId);

  if (current && compareRevision(current, message.revision) >= 0) {
    return;
  }

  revisionStore.set(message.entityId, message.revision);
  markEntityStale(message.entityId);
});

for (const progress of progressEvents) {
  bus.publish({ type: "import.progress", progress });
}

const publishProgress = throttle((progress: number) => {
  bus.publish({
    type: "import.progress",
    progress,
    createdAtMs: Date.now(),
  });
}, 500);

bus.publish({ type: "import.started", importId });
bus.publish({ type: "import.completed", importId, artifactId });

Need to announce? BroadcastChannel.
Need to talk privately? MessageChannel.
Need to coordinate ownership? Web Locks.
Need durable truth? IndexedDB/server/cache.
Need network mediation? Service Worker.

something changed

what is true now?

type BusOptions = {
  channelName: string;
  senderId: string;
  protocol: string;
  version: number;
  maxSeenMessages?: number;
  onProtocolError?: (error: unknown) => void;
};

export class ProductionBroadcastBus<TPayloadByType extends Record<string, unknown>> {
  private readonly channel: BroadcastChannel;
  private readonly handlers = new Map<
    keyof TPayloadByType & string,
    Set<(payload: unknown, envelope: BusEnvelope) => void>
  >();
  private readonly seen = new Set<string>();
  private readonly maxSeenMessages: number;

  constructor(private readonly options: BusOptions) {
    this.channel = new BroadcastChannel(options.channelName);
    this.maxSeenMessages = options.maxSeenMessages ?? 2_000;

    this.channel.addEventListener("message", (event) => {
      this.handleIncoming(event.data);
    });

    this.channel.addEventListener("messageerror", (event) => {
      options.onProtocolError?.(event);
    });
  }

  publish<TType extends keyof TPayloadByType & string>(
    type: TType,
    payload: TPayloadByType[TType]
  ): void {
    const envelope: BusEnvelope<TType, TPayloadByType[TType]> = {
      protocol: this.options.protocol,
      version: this.options.version,
      messageId: crypto.randomUUID(),
      senderId: this.options.senderId,
      type,
      createdAtMs: Date.now(),
      payload,
    };

    this.remember(envelope.messageId);
    this.channel.postMessage(envelope);
  }

  subscribe<TType extends keyof TPayloadByType & string>(
    type: TType,
    handler: (payload: TPayloadByType[TType], envelope: BusEnvelope<TType, TPayloadByType[TType]>) => void
  ): () => void {
    let handlers = this.handlers.get(type);
    if (!handlers) {
      handlers = new Set();
      this.handlers.set(type, handlers);
    }

    handlers.add(handler as (payload: unknown, envelope: BusEnvelope) => void);

    return () => {
      handlers?.delete(handler as (payload: unknown, envelope: BusEnvelope) => void);
      if (handlers?.size === 0) this.handlers.delete(type);
    };
  }

  close(): void {
    this.handlers.clear();
    this.channel.close();
  }

  private handleIncoming(value: unknown): void {
    if (!isBusEnvelope(value)) {
      this.options.onProtocolError?.(new Error("Invalid bus envelope"));
      return;
    }

    if (value.protocol !== this.options.protocol) return;
    if (value.version !== this.options.version) return;
    if (value.senderId === this.options.senderId) return;
    if (this.seen.has(value.messageId)) return;

    this.remember(value.messageId);

    const handlers = this.handlers.get(value.type);
    if (!handlers) return;

    for (const handler of handlers) {
      try {
        handler(value.payload, value);
      } catch (error) {
        this.options.onProtocolError?.(error);
      }
    }
  }

  private remember(messageId: string): void {
    this.seen.add(messageId);
    if (this.seen.size <= this.maxSeenMessages) return;

    const first = this.seen.values().next().value;
    if (first) this.seen.delete(first);
  }
}

type BusEnvelope<TType extends string = string, TPayload = unknown> = {
  protocol: string;
  version: number;
  messageId: string;
  senderId: string;
  type: TType;
  createdAtMs: number;
  payload: TPayload;
};

function isBusEnvelope(value: unknown): value is BusEnvelope {
  if (!value || typeof value !== "object") return false;

  const record = value as Record<string, unknown>;

  return typeof record.protocol === "string" &&
    typeof record.version === "number" &&
    typeof record.messageId === "string" &&
    typeof record.senderId === "string" &&
    typeof record.type === "string" &&
    typeof record.createdAtMs === "number" &&
    "payload" in record;
}

type Listener = (value: unknown) => void;

class FakeBroadcastChannel {
  private static channels = new Map<string, Set<FakeBroadcastChannel>>();
  private listeners = new Set<Listener>();

  constructor(private readonly name: string) {
    let peers = FakeBroadcastChannel.channels.get(name);
    if (!peers) {
      peers = new Set();
      FakeBroadcastChannel.channels.set(name, peers);
    }
    peers.add(this);
  }

  postMessage(value: unknown): void {
    const peers = FakeBroadcastChannel.channels.get(this.name);
    if (!peers) return;

    for (const peer of peers) {
      if (peer === this) continue;
      for (const listener of peer.listeners) {
        listener({ data: value });
      }
    }
  }

  addEventListener(type: "message", listener: Listener): void {
    if (type === "message") this.listeners.add(listener);
  }

  close(): void {
    FakeBroadcastChannel.channels.get(this.name)?.delete(this);
    this.listeners.clear();
  }
}

test("logout propagates across tabs", async ({ browser }) => {
  const context = await browser.newContext();
  const tab1 = await context.newPage();
  const tab2 = await context.newPage();

  await tab1.goto("/app");
  await tab2.goto("/app");

  await tab1.getByRole("button", { name: "Logout" }).click();

  await expect(tab2).toHaveURL(/\/login/);
});

type BroadcastMetrics = {
  channelName: string;
  sent: number;
  received: number;
  droppedSelf: number;
  droppedDuplicate: number;
  droppedInvalidProtocol: number;
  handlerErrors: number;
  messageErrors: number;
};

logger.debug("broadcast.received", {
  channelName,
  type: envelope.type,
  messageId: envelope.messageId,
  senderId: envelope.senderId,
  ageMs: Date.now() - envelope.createdAtMs,
});

BroadcastChannel is excellent for notification.
BroadcastChannel is dangerous as truth.

BroadcastChannel = signal
IndexedDB/Cache/Session Store = local truth
Backend = authoritative truth
Web Locks/Lease = ownership
MessageChannel = private session