trellis 3.1.34 → 3.2.0

package/dist/realtime/relay-persistence.js

@@ -0,0 +1,107 @@
+// src/realtime/relay-persistence.ts
+var DEFAULT_MAX_CHAT = 200;
+var DEFAULT_MAX_TEXT_OPS = 2e3;
+function chatKey(msg) {
+  return msg.id ?? `${msg.from}:${msg.ts}`;
+}
+function tieKey(msg) {
+  if (msg.t === "msg") return chatKey(msg);
+  if (msg.t === "presence" || msg.t === "bye") return msg.from;
+  return "";
+}
+function messageTs(msg) {
+  if (msg.t === "presence" || msg.t === "bye" || msg.t === "msg") {
+    return msg.ts;
+  }
+  return 0;
+}
+var RelayPersistence = class {
+  maxChat;
+  maxTextOps;
+  presence = /* @__PURE__ */ new Map();
+  /** Chat is a grow-only set keyed by {@link chatKey} — dedup on record. */
+  chatLog = [];
+  chatKeys = /* @__PURE__ */ new Set();
+  textSnapshot = null;
+  textOps = [];
+  constructor(opts = {}) {
+    this.maxChat = opts.maxChat ?? DEFAULT_MAX_CHAT;
+    this.maxTextOps = opts.maxTextOps ?? DEFAULT_MAX_TEXT_OPS;
+  }
+  /** Record an inbound client message (skip `hello` / `replay`). */
+  record(message) {
+    if (message.v !== 1) return;
+    switch (message.t) {
+      case "hello":
+        return;
+      case "replay":
+        return;
+      case "presence":
+        this.presence.set(message.from, message);
+        return;
+      case "bye":
+        this.presence.delete(message.from);
+        return;
+      case "msg":
+        this.recordBroadcast(message);
+        return;
+    }
+  }
+  /** Ordered messages to replay to a peer that just connected. */
+  buildReplay() {
+    const out = [
+      ...this.presence.values(),
+      ...this.chatLog
+    ];
+    if (this.textSnapshot) {
+      out.push(this.textSnapshot);
+    } else {
+      out.push(...this.textOps);
+    }
+    out.sort((a, b) => {
+      const dt = messageTs(a) - messageTs(b);
+      if (dt !== 0) return dt;
+      return tieKey(a).localeCompare(tieKey(b));
+    });
+    return out;
+  }
+  getPresenceCount() {
+    return this.presence.size;
+  }
+  getChatCount() {
+    return this.chatLog.length;
+  }
+  hasTextSnapshot() {
+    return this.textSnapshot !== null;
+  }
+  recordBroadcast(message) {
+    if (message.channel === "chat" && message.event === "message") {
+      const key = chatKey(message);
+      if (this.chatKeys.has(key)) return;
+      this.chatKeys.add(key);
+      this.chatLog.push(message);
+      if (this.chatLog.length > this.maxChat) {
+        const evicted = this.chatLog.splice(0, this.chatLog.length - this.maxChat);
+        for (const m of evicted) this.chatKeys.delete(chatKey(m));
+      }
+      return;
+    }
+    if (message.channel === "text" && message.event === "state") {
+      this.textSnapshot = message;
+      this.textOps = [];
+      return;
+    }
+    if (message.channel === "text" && message.event === "op") {
+      if (this.textSnapshot) return;
+      this.textOps.push(message);
+      if (this.textOps.length > this.maxTextOps) {
+        this.textOps.splice(0, this.textOps.length - this.maxTextOps);
+      }
+    }
+  }
+};
+export {
+  DEFAULT_MAX_CHAT,
+  DEFAULT_MAX_TEXT_OPS,
+  RelayPersistence
+};

package/dist/realtime/relay-server.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Trellis Realtime — Relay Hub (server side)
+ *
+ * The server counterpart to {@link WebSocketRelayTransport}: a dumb broadcast
+ * mesh that fans every inbound frame out to all *other* connected peers, with
+ * optional in-memory replay ({@link RelayPersistence}) so a late joiner catches
+ * up on presence / chat tail / text state.
+ *
+ * This is intentionally NOT {@link RealtimeRoom}. `RealtimeRoom` is a *client*
+ * abstraction — one peer's view of a room (its own presence + observed peers).
+ * The relay holds no presence of its own; it only moves bytes between peers and
+ * remembers enough to replay. Keep the two roles distinct: clients run
+ * `RealtimeRoom`, the server runs a relay.
+ *
+ * Room-scoped: peers are fanned out (and replayed) only to others in the *same*
+ * room. The room is taken from the upgrade path — `${path}/{room}` — matching
+ * {@link DurableObjectRelayTransport}'s `${url}/{room}` convention (and the
+ * reference Durable Object worker, which maps one object per room). A bare
+ * connection to `path` lands in the `'default'` room. This makes the bundled
+ * relay a faithful local stand-in for the hosted DO: distinct rooms stay
+ * isolated, so `joinPresence({ relayUrl })` Just Works against it.
+ *
+ * Node-only (uses `node:http` + the optional `ws` package). Exposed through
+ * `trellis/server`, never `trellis/realtime` (which is browser-bundled).
+ *
+ *   import { createServer } from 'node:http';
+ *   import { attachRealtimeRelay } from 'trellis/server';
+ *
+ *   const server = createServer(handler);
+ *   await attachRealtimeRelay(server, { path: '/rt' });
+ *   server.listen(8231);
+ *   // client: joinPresence({ relayUrl: 'ws://localhost:8231/rt', room: 'doc:42' })
+ *   //   → connects to ws://localhost:8231/rt/doc:42
+ *
+ * @module trellis/server
+ */
+import type { Server as HttpServer } from 'node:http';
+import { RelayPersistence } from '../realtime/relay-persistence.js';
+export interface RealtimeRelayOptions {
+    /**
+     * Base WebSocket upgrade path this relay claims. Default `/rt`. The relay
+     * accepts `path` (→ room `'default'`) and `${path}/{room}` (→ that room);
+     * other upgrade paths are left untouched so it can coexist with path-scoped
+     * WebSocket handlers.
+     */
+    path?: string;
+    /**
+     * Per-room replay store factory for late joiners. A fresh store is created
+     * the first time a room is seen. Pass `false` to disable replay entirely
+     * (pure fan-out). Default: `() => new RelayPersistence()`.
+     */
+    persistence?: false | (() => RelayPersistence);
+    /**
+     * Grace window (ms) before replay is delivered to a new connection when no
+     * `hello` frame arrives first (UI mounting subscribers can race the socket).
+     * Default 250.
+     */
+    replayGraceMs?: number;
+    /** Injectable `ws` WebSocketServer ctor for tests. */
+    WebSocketServerImpl?: unknown;
+}
+export interface RealtimeRelay {
+    /** Connected peers — across all rooms, or in `room` when given. */
+    clientCount(room?: string): number;
+    /** Currently active room ids (rooms drop when their last peer leaves). */
+    rooms(): string[];
+    /** The replay store for `room`, or `null` when replay is disabled. */
+    persistenceFor(room: string): RelayPersistence | null;
+    /** Close every peer socket and tear down the WS server. */
+    close(): Promise<void>;
+}
+/**
+ * Mount a realtime relay on an existing HTTP server. Only handles upgrades on
+ * `opts.path`; other upgrade paths are left untouched, so this can coexist with
+ * other WebSocket handlers (e.g. the graph-subscription socket) **provided
+ * those handlers are themselves path-scoped**.
+ */
+export declare function attachRealtimeRelay(server: HttpServer, opts?: RealtimeRelayOptions): Promise<RealtimeRelay>;
+export interface StandaloneRealtimeRelayOptions extends RealtimeRelayOptions {
+    /** Port to bind. Default 8231. Use 0 for an OS-assigned ephemeral port. */
+    port?: number;
+    /** Host to bind. Default `0.0.0.0`. */
+    hostname?: string;
+}
+export interface StandaloneRealtimeRelay extends RealtimeRelay {
+    /** The bound port (resolved, so `port: 0` reports the real ephemeral port). */
+    port: number;
+    /** The underlying HTTP server (health check on `/`, 404 otherwise). */
+    server: HttpServer;
+}
+/**
+ * Spin up a standalone relay hub on its own HTTP server. The HTTP surface is a
+ * health endpoint only (`200` on `/`, `404` elsewhere); the relay lives on the
+ * WebSocket upgrade path. For embedding in an existing app server, use
+ * {@link attachRealtimeRelay} instead.
+ *
+ *   const relay = await createRealtimeRelay({ port: 8231 });
+ *   // ws://localhost:8231/rt        → room 'default'
+ *   // ws://localhost:8231/rt/doc:42 → room 'doc:42' (isolated fan-out)
+ *   await relay.close();
+ */
+export declare function createRealtimeRelay(opts?: StandaloneRealtimeRelayOptions): Promise<StandaloneRealtimeRelay>;
+//# sourceMappingURL=relay-server.d.ts.map

package/dist/realtime/relay-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-server.d.ts","sourceRoot":"","sources":["../../src/realtime/relay-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAmB,MAAM,WAAW,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAapE,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,CAAC,MAAM,gBAAgB,CAAC,CAAC;IAC/C;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,0EAA0E;IAC1E,KAAK,IAAI,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IACtD,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAmBD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA2IxB;AAED,MAAM,WAAW,8BAA+B,SAAQ,oBAAoB;IAC1E,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,GAAE,8BAAmC,GACxC,OAAO,CAAC,uBAAuB,CAAC,CA+BlC"}

package/dist/realtime/room.d.ts

@@ -0,0 +1,98 @@
+/**
+ * RealtimeRoom — presence + broadcast over a {@link RealtimeTransport}.
+ *
+ *   const room = RealtimeRoom.join({
+ *     transport: new BroadcastChannelTransport({ id, channel: 'demo' }),
+ *     initialPresence: { name: 'Ada', color: '#6d5bfa' },
+ *   });
+ *
+ *   room.onPresence((peers) => renderAvatars(peers));
+ *   room.setPresence({ cursor: { x, y } });
+ *   room.on('chat', (e) => appendMessage(e.payload));
+ *   room.broadcast('chat', 'message', { text: 'hi' });
+ *
+ * Presence is heartbeat-based: peers re-announce on an interval and are pruned
+ * after a timeout. Transports with explicit teardown (MemoryHub) also emit an
+ * immediate `bye` on {@link RealtimeRoom.leave}.
+ */
+import { Signal } from '../client/reactive.js';
+import type { BroadcastEvent, PresencePeer, PresenceState, RealtimeMessage, RealtimeTransport } from './types.js';
+export interface RealtimeRoomOptions<P extends PresenceState> {
+    transport: RealtimeTransport;
+    /** Initial presence for the local peer. */
+    initialPresence?: P;
+    /** Heartbeat interval (ms). Default 2000. Set 0 to disable timers. */
+    heartbeatMs?: number;
+    /** Peer expiry after no heartbeat (ms). Default 6000. */
+    timeoutMs?: number;
+    /** Injectable clock for tests. Default `Date.now`. */
+    now?: () => number;
+}
+type BroadcastHandler = (event: BroadcastEvent) => void;
+export declare class RealtimeRoom<P extends PresenceState = PresenceState> {
+    readonly id: string;
+    private transport;
+    private myState;
+    private peers;
+    /** Sender timestamps from presence messages (not local lastSeen). */
+    private presenceTsByPeer;
+    private channelHandlers;
+    private _presence;
+    private now;
+    private heartbeatMs;
+    private timeoutMs;
+    private heartbeatTimer?;
+    private unsubscribe;
+    private closed;
+    private pendingReplay;
+    /** Ids of broadcasts already delivered — keeps replay idempotent (G-Set). */
+    private seenMsgIds;
+    private constructor();
+    /** Join a room and announce presence. */
+    static join<P extends PresenceState = PresenceState>(opts: RealtimeRoomOptions<P>): RealtimeRoom<P>;
+    /** The local peer id. */
+    get selfId(): string;
+    /** Current local presence state. */
+    getSelfState(): P;
+    /** Merge a partial update into local presence and broadcast it. */
+    setPresence(partial: Partial<P>): void;
+    /** Replace local presence wholesale and broadcast it. */
+    replacePresence(state: P): void;
+    /** All peers including self (self first). */
+    getPresence(): PresencePeer<P>[];
+    /** Peers excluding self. */
+    getOthers(): PresencePeer<P>[];
+    /** Subscribe to presence changes. Called immediately with current peers. */
+    onPresence(cb: (peers: PresencePeer<P>[]) => void): () => void;
+    /** Reactive presence signal (for framework adapters). */
+    get presenceSignal(): Signal<PresencePeer<P>[]>;
+    /**
+     * Fire-and-forget broadcast to all other peers on a channel. Returns the
+     * stable message id assigned to this broadcast — persist it alongside an
+     * optimistic local render so an echoed copy (relay replay, reconnect) is
+     * deduplicated by id rather than re-rendered.
+     */
+    broadcast(channel: string, event: string, payload: unknown): string;
+    private newMsgId;
+    /** Subscribe to broadcasts on a channel. Returns an unsubscribe fn. */
+    on(channel: string, handler: BroadcastHandler): () => void;
+    /**
+     * Apply a relay replay batch (chat history, text snapshot, presence).
+     * Used when reconnecting to a hub with {@link RelayPersistence}.
+     */
+    replay(messages: RealtimeMessage[]): void;
+    /** Announce departure and tear down. */
+    leave(): void;
+    private handle;
+    private flushPendingReplay;
+    private hasActiveSubscribers;
+    private integrateRemote;
+    private upsertPeer;
+    private announceHello;
+    private announcePresence;
+    private startHeartbeat;
+    private pruneExpired;
+    private recomputePresence;
+}
+export {};
+//# sourceMappingURL=room.d.ts.map

package/dist/realtime/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../src/realtime/room.ts"],"names":[],"mappings":"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"}

package/dist/realtime/text.d.ts

@@ -0,0 +1,73 @@
+/**
+ * RealtimeText — a compact RGA-style sequence CRDT for collaborative text.
+ *
+ * Each character is a node with a globally-unique id (`<lamport>@<peerId>`) and
+ * an `after` pointer to the node it follows. Concurrent inserts sharing an
+ * anchor are ordered deterministically (higher lamport first, peer id as
+ * tiebreak), so all replicas converge regardless of delivery order. Deletes are
+ * tombstones, making them idempotent and commutative.
+ *
+ * This is intentionally minimal — enough for a genuine multiplayer editor demo
+ * without the weight of a full production CRDT (no block compaction, GC, or
+ * rich formatting).
+ */
+import type { RealtimeRoom } from './room.js';
+export interface TextNode {
+    id: string;
+    ch: string;
+    after: string | null;
+    deleted: boolean;
+}
+export type TextOp = {
+    op: 'ins';
+    id: string;
+    ch: string;
+    after: string | null;
+} | {
+    op: 'del';
+    id: string;
+};
+export interface RealtimeTextOptions {
+    peerId: string;
+    /** Optional room binding for automatic op + state sync. */
+    room?: RealtimeRoom;
+    /** Broadcast channel name when bound to a room. Default `text`. */
+    channel?: string;
+}
+export declare class RealtimeText {
+    private nodes;
+    private counter;
+    private peerId;
+    private listeners;
+    private room?;
+    private channel;
+    private unsubscribe?;
+    constructor(opts: RealtimeTextOptions);
+    /** Materialized visible text. */
+    toString(): string;
+    /** Current length of visible text. */
+    get length(): number;
+    /** Insert a string at a visible index. Broadcasts ops when room-bound. */
+    insert(index: number, str: string): TextOp[];
+    /** Delete `count` visible characters starting at `index`. */
+    delete(index: number, count?: number): TextOp[];
+    /** Apply a single remote op. Returns true if the document changed. */
+    applyOp(op: TextOp): boolean;
+    /** Apply a batch of remote ops, emitting once. */
+    applyOps(ops: TextOp[]): void;
+    /** Snapshot of all nodes (including tombstones) for state sync. */
+    getNodes(): TextNode[];
+    /** Merge a remote snapshot of nodes. */
+    mergeNodes(nodes: TextNode[]): void;
+    /** Subscribe to text changes. Returns an unsubscribe fn. */
+    onChange(cb: (text: string) => void): () => void;
+    /** Detach room bindings. */
+    dispose(): void;
+    private onRemote;
+    private publish;
+    private visibleNodes;
+    private nextId;
+    private bumpCounter;
+    private emit;
+}
+//# sourceMappingURL=text.d.ts.map

package/dist/realtime/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/realtime/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,MAAM,GACd;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAuBD,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAC,CAAa;gBAErB,IAAI,EAAE,mBAAmB;IAerC,iCAAiC;IACjC,QAAQ,IAAI,MAAM;IAMlB,sCAAsC;IACtC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,0EAA0E;IAC1E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAmB5C,6DAA6D;IAC7D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE;IAsB1C,sEAAsE;IACtE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAmB5B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ7B,mEAAmE;IACnE,QAAQ,IAAI,QAAQ,EAAE;IAItB,wCAAwC;IACxC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI;IAgBnC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOhD,4BAA4B;IAC5B,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,IAAI;CAUb"}

package/dist/realtime/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Trellis Realtime — Ephemeral Presence & Broadcast Types
+ *
+ * Distinct from the persisted VCS op log: realtime messages are ephemeral,
+ * mesh-broadcast, and never written to the causal history. This is the right
+ * home for high-frequency, disposable signals like cursors and presence, plus
+ * fire-and-forget broadcast (chat, live text edits).
+ *
+ * The transport is a broadcast mesh: `send` delivers a message to every other
+ * peer sharing the channel. Senders never receive their own messages.
+ */
+export declare const REALTIME_PROTOCOL: 1;
+/** Arbitrary per-peer presence state (name, avatar, color, cursor, …). */
+export type PresenceState = Record<string, unknown>;
+export interface PresencePeer<P extends PresenceState = PresenceState> {
+    /** Peer/client identity. */
+    id: string;
+    /** Latest published presence state. */
+    state: P;
+    /** Epoch ms of the last presence heartbeat we saw. */
+    lastSeen: number;
+    /** True for the local peer. */
+    self: boolean;
+}
+/** A received broadcast on a channel. */
+export interface BroadcastEvent {
+    from: string;
+    channel: string;
+    event: string;
+    payload: unknown;
+    ts: number;
+    /**
+     * Stable message identity. Assigned by the sender and carried unchanged to
+     * every replica, so dedup is order-independent (a grow-only set). Present on
+     * all broadcasts emitted by {@link RealtimeRoom.broadcast}; may be absent on
+     * legacy frames.
+     */
+    id?: string;
+}
+export type RealtimeMessage<P extends PresenceState = PresenceState> = {
+    v: 1;
+    t: 'hello';
+    from: string;
+} | {
+    v: 1;
+    t: 'presence';
+    from: string;
+    state: P;
+    ts: number;
+} | {
+    v: 1;
+    t: 'bye';
+    from: string;
+    ts: number;
+} | {
+    v: 1;
+    t: 'msg';
+    from: string;
+    channel: string;
+    event: string;
+    payload: unknown;
+    ts: number;
+    /** Stable per-message id (dedup key for grow-only replay). */
+    id?: string;
+}
+/** Relay welcome: re-deliver persisted session state to a new connection. */
+ | {
+    v: 1;
+    t: 'replay';
+    from: string;
+    messages: RealtimeMessage<P>[];
+};
+/**
+ * Broadcast mesh transport. Implementations: {@link MemoryHub} (in-process /
+ * tests / side-by-side panes), {@link BroadcastChannelTransport} (serverless
+ * cross-tab in one browser), and {@link WebSocketRelayTransport} (relay-backed
+ * cross-browser rooms).
+ */
+export interface RealtimeTransport {
+    /** Local peer identity on this transport. */
+    readonly id: string;
+    /** Broadcast a message to all other peers. Never echoes to the sender. */
+    send(message: RealtimeMessage): void;
+    /** Register an inbound message handler. Returns an unsubscribe fn. */
+    onMessage(handler: (message: RealtimeMessage) => void): () => void;
+    /** Tear down the transport. */
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/realtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/realtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,iBAAiB,EAAG,CAAU,CAAC;AAE5C,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACnE,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC;IACT,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,IAAI,EAAE,OAAO,CAAC;CACf;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAC/D;IAAE,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5C;IACE,CAAC,EAAE,CAAC,CAAC;IACL,CAAC,EAAE,KAAK,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AACH,6EAA6E;GAC3E;IACE,CAAC,EAAE,CAAC,CAAC;IACL,CAAC,EAAE,QAAQ,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;CAChC,CAAC;AAEN;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,sEAAsE;IACtE,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnE,+BAA+B;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/realtime/websocket-relay-transport.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Browser transport that relays {@link RealtimeMessage} frames through a
+ * shared WebSocket hub (demo server or custom relay). Unlike
+ * {@link BroadcastChannelTransport}, this works across different browsers on
+ * the same origin.
+ */
+import type { RealtimeMessage, RealtimeTransport } from './types.js';
+export interface WebSocketRelayTransportOptions {
+    /** Local peer identity. */
+    id: string;
+    /** Hub URL, e.g. `ws://localhost:8231/rt`. */
+    url: string;
+    /** Injectable WebSocket for tests. */
+    WebSocketImpl?: typeof WebSocket;
+}
+export declare class WebSocketRelayTransport implements RealtimeTransport {
+    readonly id: string;
+    private ws;
+    private handlers;
+    private closed;
+    private pending;
+    constructor(opts: WebSocketRelayTransportOptions);
+    send(message: RealtimeMessage): void;
+    onMessage(handler: (message: RealtimeMessage) => void): () => void;
+    close(): void;
+    private flushPending;
+}
+//# sourceMappingURL=websocket-relay-transport.d.ts.map

package/dist/realtime/websocket-relay-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-relay-transport.d.ts","sourceRoot":"","sources":["../../src/realtime/websocket-relay-transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,8BAA8B;IAC7C,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAClC;AAED,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAyB;gBAE5B,IAAI,EAAE,8BAA8B;IAgChD,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAUpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAOlE,KAAK,IAAI,IAAI;IAYb,OAAO,CAAC,YAAY;CAOrB"}