trellis 3.1.35 → 3.2.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,YAAY,EAAE,gCAAgC,EAAE,MAAM,kCAAkC,CAAC;AAEzF,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,YAAY,EACV,kCAAkC,EAClC,2BAA2B,GAC5B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,aAAa,EACb,YAAY,EACZ,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/realtime/index.js

@@ -0,0 +1,40 @@
+import {
+  BroadcastChannelTransport,
+  DEFAULT_MAX_RECORDS,
+  DurableObjectRelayTransport,
+  MemoryHub,
+  MemoryRealtimeTransport,
+  PersistentChannel,
+  REALTIME_PROTOCOL,
+  RealtimeRoom,
+  RealtimeText,
+  WebSocketRelayTransport,
+  createPresenceTransport,
+  joinPresence,
+  localStorageChannelStore
+} from "../chunk-KSU2GW22.js";
+import {
+  DEFAULT_MAX_CHAT,
+  DEFAULT_MAX_TEXT_OPS,
+  RelayPersistence
+} from "../chunk-GFZCJ4EH.js";
+import "../chunk-UBGUDMUV.js";
+import "../chunk-KFQGP6VL.js";
+export {
+  BroadcastChannelTransport,
+  DEFAULT_MAX_CHAT,
+  DEFAULT_MAX_RECORDS,
+  DEFAULT_MAX_TEXT_OPS,
+  DurableObjectRelayTransport,
+  MemoryHub,
+  MemoryRealtimeTransport,
+  PersistentChannel,
+  REALTIME_PROTOCOL,
+  RealtimeRoom,
+  RealtimeText,
+  RelayPersistence,
+  WebSocketRelayTransport,
+  createPresenceTransport,
+  joinPresence,
+  localStorageChannelStore
+};

package/dist/realtime/memory-hub.d.ts

@@ -0,0 +1,32 @@
+/**
+ * In-process broadcast mesh for realtime presence/broadcast.
+ *
+ * Useful for tests and for "side-by-side" demos where several simulated peers
+ * share one page. Each {@link MemoryRealtimeTransport} delivers messages to
+ * every other transport on the same hub (never to itself).
+ */
+import type { RealtimeMessage, RealtimeTransport } from './types.js';
+export declare class MemoryHub {
+    private transports;
+    /** Create a transport bound to this hub for the given peer id. */
+    connect(id: string): MemoryRealtimeTransport;
+    /** Number of currently connected transports. */
+    size(): number;
+    /** @internal */
+    _broadcast(from: MemoryRealtimeTransport, message: RealtimeMessage): void;
+    /** @internal */
+    _remove(transport: MemoryRealtimeTransport): void;
+}
+export declare class MemoryRealtimeTransport implements RealtimeTransport {
+    readonly id: string;
+    private hub;
+    private handlers;
+    private closed;
+    constructor(hub: MemoryHub, id: string);
+    send(message: RealtimeMessage): void;
+    onMessage(handler: (message: RealtimeMessage) => void): () => void;
+    close(): void;
+    /** @internal */
+    _deliver(message: RealtimeMessage): void;
+}
+//# sourceMappingURL=memory-hub.d.ts.map

package/dist/realtime/memory-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-hub.d.ts","sourceRoot":"","sources":["../../src/realtime/memory-hub.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAsC;IAExD,kEAAkE;IAClE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB;IAM5C,gDAAgD;IAChD,IAAI,IAAI,MAAM;IAId,gBAAgB;IAChB,UAAU,CAAC,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAOzE,gBAAgB;IAChB,OAAO,CAAC,SAAS,EAAE,uBAAuB,GAAG,IAAI;CAGlD;AAED,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,MAAM,CAAS;gBAEX,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM;IAKtC,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAKpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAOlE,KAAK,IAAI,IAAI;IAOb,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;CAUzC"}

package/dist/realtime/persistent-channel.d.ts

@@ -0,0 +1,105 @@
+/**
+ * PersistentChannel — a durable, convergent view over one broadcast channel.
+ *
+ * Wraps a {@link RealtimeRoom} channel as a **grow-only set** keyed by message
+ * id: every record is deduplicated by id and ordered by `(ts, id)`, so the same
+ * message arriving from any source (optimistic local send, live broadcast, or a
+ * relay replay on reconnect) lands exactly once and in a stable order.
+ *
+ * There is no single source of truth. Each peer holds its own replica (a
+ * pluggable {@link ChannelStore} — `localStorage`, IndexedDB, …) and the relay
+ * holds another. They converge on reconnect because union + id-dedup is
+ * commutative and idempotent. The store is an instant first-paint cache, not an
+ * authority: a refresh repaints from it immediately, then merges whatever the
+ * relay replays.
+ *
+ *   const chat = PersistentChannel.create(room, 'chat', {
+ *     store: localStorageChannelStore(`chat:${roomUrl}`),
+ *     resolveMeta: (e) => presenceById()[e.from],   // capture name/color
+ *   });
+ *
+ *   chat.messages.subscribe((msgs) => render(msgs)); // deduped + sorted
+ *   chat.send({ text });                             // optimistic + broadcast + persist
+ *
+ * Only the channel's "message" event (configurable) is persisted; transient
+ * events like typing indicators stay the caller's concern via `room.on`.
+ */
+import { Signal } from '../client/reactive.js';
+import type { RealtimeRoom } from './room.js';
+import type { BroadcastEvent } from './types.js';
+/** A persisted member of the grow-only set. */
+export interface ChannelRecord<T = unknown> {
+    /** Stable dedup key (sender-assigned message id). */
+    id: string;
+    /** Originating peer id. */
+    from: string;
+    /** Sender clock (epoch ms) — primary sort key. */
+    ts: number;
+    /** Application payload (e.g. `{ text }`). */
+    payload: T;
+    /** Optional sender metadata captured at send/receipt (name, color, …). */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Durable backing store for a peer's local replica. Implementations may be sync
+ * (`localStorage`) or async (IndexedDB/OPFS); `load` may return a promise.
+ */
+export interface ChannelStore<T = unknown> {
+    load(): ChannelRecord<T>[] | Promise<ChannelRecord<T>[]>;
+    save(records: ChannelRecord<T>[]): void | Promise<void>;
+}
+export interface PersistentChannelOptions<T = unknown> {
+    /** Broadcast event name treated as a persisted message. Default `'message'`. */
+    event?: string;
+    /** Durable replica for this peer. Omit for in-memory only. */
+    store?: ChannelStore<T>;
+    /** Keep at most the N most recent records. Default 200. */
+    max?: number;
+    /** Capture sender metadata for an inbound message (e.g. from presence). */
+    resolveMeta?: (event: BroadcastEvent) => Record<string, unknown> | undefined;
+    /** Injectable clock for local sends. Default `Date.now`. */
+    now?: () => number;
+}
+export declare const DEFAULT_MAX_RECORDS = 200;
+export declare class PersistentChannel<T = unknown> {
+    /** Reactive, deduped, `(ts, id)`-sorted message list. */
+    readonly messages: Signal<ChannelRecord<T>[]>;
+    private readonly room;
+    private readonly channel;
+    private readonly event;
+    private readonly store?;
+    private readonly max;
+    private readonly resolveMeta?;
+    private readonly now;
+    private records;
+    private byId;
+    private unsubscribe;
+    private disposed;
+    private constructor();
+    /** Create a persistent view over `room`'s `channel`. */
+    static create<T = unknown>(room: RealtimeRoom, channel: string, opts?: PersistentChannelOptions<T>): PersistentChannel<T>;
+    /**
+     * Optimistically record locally, broadcast to peers, and persist. Returns the
+     * stable message id. The room dedups its own id, so the broadcast never
+     * echoes back into this channel.
+     */
+    send(payload: T, meta?: Record<string, unknown>): string;
+    /** Current records (deduped + sorted). Read without subscribing. */
+    snapshot(): ChannelRecord<T>[];
+    /** Stop listening. Does not clear the durable store. */
+    dispose(): void;
+    private handleEvent;
+    private hydrate;
+    /** Insert one record and publish if it was new. */
+    private commitOne;
+    /** Pure insert with dedup + cap. Returns true when a new record was added. */
+    private add;
+    private commit;
+}
+/**
+ * A {@link ChannelStore} backed by Web Storage (`localStorage` by default).
+ * Degrades to in-memory if storage is unavailable or over quota — durability is
+ * best-effort, since the relay replica remains authoritative for catch-up.
+ */
+export declare function localStorageChannelStore<T = unknown>(key: string, storage?: Storage | undefined): ChannelStore<T>;
+//# sourceMappingURL=persistent-channel.d.ts.map

package/dist/realtime/persistent-channel.d.ts.map

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

package/dist/realtime/presence.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Transport-agnostic presence — the one place the local-first → cloud-optional
+ * gradient is encoded.
+ *
+ * Presence is ephemeral and self-healing; it is never written to the causal op
+ * log. That makes the *transport* a free choice, and this helper picks it by
+ * intent rather than hardcoding a hub:
+ *
+ *   - no `relayUrl`  → {@link BroadcastChannelTransport}: cross-tab, $0, no
+ *     socket, works with the network killed. This is the free / local tier and
+ *     the default. (Telos principle 7: kill the network, presence across tabs
+ *     still works — you just stop seeing remote peers.)
+ *   - `relayUrl` set → {@link DurableObjectRelayTransport}: a hosted relay room.
+ *     This opens a socket, so per the ecosystem economics it is a *paid* tier.
+ *   - `transport`    → bring your own (tests, or an Iroh gossip transport at
+ *     Boulder 2) — the escape hatch that keeps the seam honest.
+ *
+ * Frameworks consume this inside their room hooks, e.g. Svelte:
+ *
+ *   import { createRoom } from 'trellis/svelte';
+ *   import { joinPresence } from 'trellis/realtime';
+ *
+ *   const { presence, others, destroy } = createRoom(() =>
+ *     joinPresence({ peerId, room: 'doc:42', initialPresence: { name, color } }),
+ *   );
+ */
+import { BroadcastChannelTransport } from './broadcast-channel-transport.js';
+import { DurableObjectRelayTransport } from './durable-object-relay-transport.js';
+import { RealtimeRoom } from './room.js';
+import type { PresenceState, RealtimeTransport } from './types.js';
+export interface PresenceOptions<P extends PresenceState = PresenceState> {
+    /** Local peer identity (stable per tab/device). */
+    peerId: string;
+    /** Logical room — peers sharing it see each other. */
+    room: string;
+    /** Initial local presence (name, color, cursor, …). */
+    initialPresence?: P;
+    /**
+     * Hosted relay base URL. When set, presence syncs cross-device through the
+     * relay (paid tier). When omitted, presence stays local/cross-tab (free).
+     */
+    relayUrl?: string;
+    /** Auth token for the hosted relay. */
+    auth?: string;
+    /**
+     * Explicit transport — overrides the `relayUrl`/local selection entirely.
+     * Use for tests or an alternative transport (e.g. future Iroh gossip).
+     */
+    transport?: RealtimeTransport;
+    /** Heartbeat interval (ms). Default 2000 (see {@link RealtimeRoom}). */
+    heartbeatMs?: number;
+    /** Peer expiry after no heartbeat (ms). Default 6000. */
+    timeoutMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+    /** Injectable WebSocket (hosted relay) for tests / non-browser hosts. */
+    WebSocketImpl?: ConstructorParameters<typeof DurableObjectRelayTransport>[0]['WebSocketImpl'];
+    /** Injectable BroadcastChannel (local) for tests / non-browser hosts. */
+    BroadcastChannelImpl?: ConstructorParameters<typeof BroadcastChannelTransport>[0]['BroadcastChannelImpl'];
+}
+/**
+ * Select the presence transport for the given options without joining a room.
+ * Exposed so callers can inspect or wrap the choice; most code should use
+ * {@link joinPresence}.
+ */
+export declare function createPresenceTransport(opts: PresenceOptions): RealtimeTransport;
+/**
+ * Join a presence room with a transport chosen by intent (local vs hosted).
+ * Returns a {@link RealtimeRoom}; pair it with a framework room hook
+ * (`createRoom` / `useRoom`) for reactive presence + broadcast.
+ */
+export declare function joinPresence<P extends PresenceState = PresenceState>(opts: PresenceOptions<P>): RealtimeRoom<P>;
+//# sourceMappingURL=presence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/realtime/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACtE,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAAC,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,yEAAyE;IACzE,aAAa,CAAC,EAAE,qBAAqB,CACnC,OAAO,2BAA2B,CACnC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IACtB,yEAAyE;IACzE,oBAAoB,CAAC,EAAE,qBAAqB,CAC1C,OAAO,yBAAyB,CACjC,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,GACpB,iBAAiB,CAgBnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAClE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,YAAY,CAAC,CAAC,CAAC,CAQjB"}

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

@@ -0,0 +1,37 @@
+/**
+ * In-memory persistence for a WebSocket relay hub (demo / dev).
+ *
+ * Retains durable-enough session state: latest presence per peer, chat tail,
+ * and collaborative text (snapshot preferred, else op tail). Not the VCS op
+ * log — reset when the relay process stops.
+ */
+import type { RealtimeMessage } from './types.js';
+export declare const DEFAULT_MAX_CHAT = 200;
+export declare const DEFAULT_MAX_TEXT_OPS = 2000;
+export interface RelayPersistenceOptions {
+    maxChat?: number;
+    maxTextOps?: number;
+}
+/**
+ * Records relay traffic and builds ordered replay batches for newcomers.
+ */
+export declare class RelayPersistence {
+    private maxChat;
+    private maxTextOps;
+    private presence;
+    /** Chat is a grow-only set keyed by {@link chatKey} — dedup on record. */
+    private chatLog;
+    private chatKeys;
+    private textSnapshot;
+    private textOps;
+    constructor(opts?: RelayPersistenceOptions);
+    /** Record an inbound client message (skip `hello` / `replay`). */
+    record(message: RealtimeMessage): void;
+    /** Ordered messages to replay to a peer that just connected. */
+    buildReplay(): RealtimeMessage[];
+    getPresenceCount(): number;
+    getChatCount(): number;
+    hasTextSnapshot(): boolean;
+    private recordBroadcast;
+}
+//# sourceMappingURL=relay-persistence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relay-persistence.d.ts","sourceRoot":"","sources":["../../src/realtime/relay-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AA4BzC,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAkC;IAClD,0EAA0E;IAC1E,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,OAAO,CAAsB;gBAEzB,IAAI,GAAE,uBAA4B;IAK9C,kEAAkE;IAClE,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAoBtC,gEAAgE;IAChE,WAAW,IAAI,eAAe,EAAE;IAmBhC,gBAAgB,IAAI,MAAM;IAI1B,YAAY,IAAI,MAAM;IAItB,eAAe,IAAI,OAAO;IAI1B,OAAO,CAAC,eAAe;CA2BxB"}

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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"}