skills/plugins/library-navigator/skills/sp-events-transport/SKILL.md

name, description

name	description
sp-events-transport	Cross-context event bridges for @suaveplan/events — MessageChannel (at-least-once) and BroadcastChannel (at-most-once) transports with nonce dedup.

Architecture

Component	Responsibility
createMessageChannelTransport	Bidirectional at-least-once bridge over MessageChannel with ack/retry
createBroadcastChannelTransport	Fan-out at-most-once bridge over BroadcastChannel
buildEnvelope / parseEnvelope	Transport envelope builder and parser with versioning
NonceWindow	Sliding deduplication window for nonce tracking
EVENTS_TRANSPORT_CODES + EventsTransportError	Structured errors for transport failures
assertStructuredCloneable / isStructuredCloneable	Payload cloneability checks before transport

File Structure

packages/networking/events/events-transport/src/
  transports/message-channel/     createMessageChannelTransport with ack/retry
  transports/broadcast-channel/   createBroadcastChannelTransport (fan-out)
  core/envelope/                  buildEnvelope, parseEnvelope, envelope types
  core/nonce-window/              NonceWindow sliding dedup
  core/transport-interface/       Transport interface types
  error-codes/                    EVENTS_TRANSPORT_CODES and EventsTransportError
  constants/                      DEFAULT_ACK_TIMEOUT_MS, DEFAULT_MAX_RETRIES, etc.
  utils/                          structured-clone-check utilities

Sibling packages

• @suaveplan/events — EventBus that this package bridges across contexts
• @suaveplan/events-otel — W3C Trace Context propagation across transport boundaries
• @suaveplan/error — structured error registry via defineCodes
• @suaveplan/types — shared TypeScript primitives
• @suaveplan/testing — unit test infrastructure

Patterns

Quick Start

import { createMessageChannelTransport } from "@suaveplan/events-transport";
import { EventBus } from "@suaveplan/events";

const channel = new MessageChannel();
const bus = new EventBus<{ "data.sync": { id: string } }>();
const transport = createMessageChannelTransport({ channel, ackTimeoutMs: 3000 });
const handle = transport.connect(bus);

await bus.emitAsync("data.sync", { id: "x" });
console.log(handle.stats.sent); // 1
handle.disconnect();

BroadcastChannel fan-out

import { createBroadcastChannelTransport } from "@suaveplan/events-transport";

const transport = createBroadcastChannelTransport({ channelName: "app-events" });
const handle = transport.connect(bus);

Envelope inspection

import { buildEnvelope, parseEnvelope } from "@suaveplan/events-transport/core/envelope";

const envelope = buildEnvelope({ eventName: "user.created", payload: { id: "u-1" } });
const parsed = parseEnvelope(envelope);

Constraints

• Browser / Node.js worker contexts only (MessageChannel, BroadcastChannel APIs)
• MessageChannel transport requires ack within DEFAULT_ACK_TIMEOUT_MS (default 5000ms)
• NonceWindow prevents duplicate delivery; size configurable via DEFAULT_NONCE_WINDOW_SIZE
• Payloads must be structuredClone compatible; checked via assertStructuredCloneable
• W3C Trace Context can be propagated through envelope headers when paired with @suaveplan/events-otel

Checklist

• Verify createMessageChannelTransport retries on missing ack
• Confirm EVENTS_TRANSPORT_CODES registered via defineCodes("EVENTS_TRANSPORT", [...])
• Check subpath exports in package.json align with src/ modules
• Run bunx turbo lint typecheck test build --filter=@suaveplan/events-transport
• Confirm nonce deduplication prevents duplicate event delivery