trellis 3.1.34 → 3.2.0

package/dist/react/realtime.js

@@ -0,0 +1,11 @@
+import {
+  usePresence,
+  useRoom,
+  useSignal
+} from "../chunk-O2AV5WMN.js";
+import "../chunk-KFQGP6VL.js";
+export {
+  usePresence,
+  useRoom,
+  useSignal
+};

package/dist/react/schema-hooks.js

@@ -0,0 +1,87 @@
+import {
+  liveEntities,
+  liveEntity
+} from "../chunk-J3WYZO3Q.js";
+import {
+  entityMutations
+} from "../chunk-USEINYUL.js";
+import "../chunk-JUEMDWLU.js";
+import {
+  useTrellis
+} from "../chunk-GWRIMRSX.js";
+import "../chunk-X762XWVC.js";
+import {
+  useSignal
+} from "../chunk-O2AV5WMN.js";
+import {
+  Signal
+} from "../chunk-UBGUDMUV.js";
+import "../chunk-KFQGP6VL.js";
+
+// src/react/schema-hooks.ts
+import { useEffect, useMemo } from "react";
+var IDLE = new Signal({
+  data: [],
+  loading: false,
+  error: null
+});
+var IDLE_SINGLE = new Signal({
+  data: null,
+  loading: false,
+  error: null
+});
+function parseReadOptions(opts) {
+  if (!opts) return {};
+  if ("resolve" in opts || "where" in opts) return opts;
+  return { where: opts };
+}
+function useLiveEntities(schema, opts) {
+  const client = useTrellis();
+  const parsed = parseReadOptions(opts);
+  const optsKey = JSON.stringify(parsed);
+  const res = useMemo(
+    () => schema ? liveEntities(client, schema, parsed) : null,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, schema, optsKey]
+  );
+  useEffect(() => res?.start(), [res]);
+  return useSignal(res?.signal ?? IDLE);
+}
+function useLiveEntity(schema, id, opts) {
+  const client = useTrellis();
+  const optsKey = JSON.stringify(opts ?? {});
+  const res = useMemo(
+    () => schema && id ? liveEntity(client, schema, id, opts) : null,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, schema, id, optsKey]
+  );
+  useEffect(() => res?.start(), [res]);
+  return useSignal(
+    res?.signal ?? IDLE_SINGLE
+  );
+}
+function useEntities(schema, opts) {
+  const state = useLiveEntities(schema, opts);
+  return {
+    data: state.data,
+    loading: state.loading,
+    error: state.error
+  };
+}
+function useEntity(schema, id, opts) {
+  const state = useLiveEntity(id ? schema : null, id, opts);
+  return {
+    data: state.data,
+    loading: state.loading,
+    error: state.error
+  };
+}
+function useMutation(schema) {
+  const client = useTrellis();
+  return useMemo(() => entityMutations(client, schema), [client, schema]);
+}
+export {
+  useEntities,
+  useEntity,
+  useMutation
+};

package/dist/realtime/broadcast-channel-transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Serverless cross-tab realtime transport using the browser BroadcastChannel
+ * API. All tabs/windows of the same origin that open a channel with the same
+ * name form a broadcast mesh — no server required.
+ *
+ * BroadcastChannel does not deliver a message back to the posting channel
+ * object, so the mesh semantics (no self-echo) hold naturally.
+ */
+import type { RealtimeMessage, RealtimeTransport } from './types.js';
+interface BroadcastChannelLike {
+    postMessage(message: unknown): void;
+    close(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    addEventListener?(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener?(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+type BroadcastChannelCtor = new (name: string) => BroadcastChannelLike;
+export interface BroadcastChannelTransportOptions {
+    /** Local peer identity. */
+    id: string;
+    /** Channel name — all peers in the room share this. */
+    channel: string;
+    /** Injectable implementation for tests / non-browser hosts. */
+    BroadcastChannelImpl?: BroadcastChannelCtor;
+}
+export declare class BroadcastChannelTransport implements RealtimeTransport {
+    readonly id: string;
+    private bc;
+    private handlers;
+    private closed;
+    constructor(opts: BroadcastChannelTransportOptions);
+    send(message: RealtimeMessage): void;
+    onMessage(handler: (message: RealtimeMessage) => void): () => void;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=broadcast-channel-transport.d.ts.map

package/dist/realtime/broadcast-channel-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast-channel-transport.d.ts","sourceRoot":"","sources":["../../src/realtime/broadcast-channel-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,UAAU,oBAAoB;IAC5B,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;IACd,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACvD,gBAAgB,CAAC,CACf,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC3C,IAAI,CAAC;IACR,mBAAmB,CAAC,CAClB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC3C,IAAI,CAAC;CACT;AAED,KAAK,oBAAoB,GAAG,KAAK,IAAI,EAAE,MAAM,KAAK,oBAAoB,CAAC;AAEvE,MAAM,WAAW,gCAAgC;IAC/C,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,CAAuB;IACjC,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,gCAAgC;IAgClD,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;CAUd"}

package/dist/realtime/durable-object-relay-transport.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Browser transport for a hosted relay room — the paid-tier accelerator.
+ *
+ * Functionally a {@link WebSocketRelayTransport} with three additions a hosted
+ * deployment needs: a room-aware URL convention, an auth token, and automatic
+ * reconnect with backoff. The server it talks to is the same dumb fan-out +
+ * disposable replay contract as {@link createRealtimeRelay} — whether that
+ * server is a Cloudflare Durable Object, a self-hosted relay, or PartyKit is
+ * irrelevant to this code. The name reflects the *recommended* hosted target
+ * (DO: single-writer-per-object matches Trellis's per-graph causality), not a
+ * hard dependency on it.
+ *
+ * Telos alignment: this is one swappable {@link RealtimeTransport} behind the
+ * stable seam. Local/free presence uses {@link BroadcastChannelTransport}; this
+ * is what you inject when "sync" is enabled. An Iroh gossip transport slots in
+ * the same way later with zero client change.
+ *
+ *   new DurableObjectRelayTransport({
+ *     id: peerId,
+ *     url: 'wss://relay.example.com',
+ *     room: 'doc:42',
+ *     auth: sessionToken,
+ *   });
+ *
+ * Reconnect self-heals presence for free: the room's heartbeat re-announces
+ * local presence after the socket comes back, and this transport re-sends a
+ * `hello` on every (re)open so the relay replays peers/chat tail immediately.
+ */
+import type { RealtimeMessage, RealtimeTransport } from './types.js';
+interface SocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+}
+type SocketCtor = new (url: string) => SocketLike;
+export interface DurableObjectRelayReconnect {
+    /** Max reconnect attempts after an unexpected close. 0 = unlimited. Default 0. */
+    maxAttempts?: number;
+    /** Initial backoff (ms). Default 500. */
+    baseDelayMs?: number;
+    /** Max backoff (ms). Default 10_000. */
+    maxDelayMs?: number;
+}
+export interface DurableObjectRelayTransportOptions {
+    /** Local peer identity. */
+    id: string;
+    /**
+     * Base relay URL, e.g. `wss://relay.example.com` or
+     * `wss://x.partykit.dev/parties/main`. The room segment and auth token are
+     * appended per {@link buildUrl} unless you pass a fully-formed URL and omit
+     * `room`/`auth`.
+     */
+    url: string;
+    /** Logical room id, appended as a path segment (`/{room}`) when set. */
+    room?: string;
+    /** Auth token, appended as `?token=` (or `&token=`) when set. */
+    auth?: string;
+    /**
+     * Override URL assembly entirely (e.g. a different DO routing convention).
+     * Receives the constructor options; returns the final `ws(s)://…` URL.
+     */
+    buildUrl?: (opts: {
+        url: string;
+        room?: string;
+        auth?: string;
+    }) => string;
+    /** Reconnect policy. Pass `false` to disable reconnect. */
+    reconnect?: DurableObjectRelayReconnect | false;
+    /** Cap on frames buffered while disconnected (oldest dropped). Default 128. */
+    maxPending?: number;
+    /** Injectable WebSocket for tests / non-browser hosts. */
+    WebSocketImpl?: SocketCtor;
+}
+export declare class DurableObjectRelayTransport implements RealtimeTransport {
+    readonly id: string;
+    private readonly url;
+    private readonly WS;
+    private readonly reconnect;
+    private readonly maxPending;
+    private ws;
+    private handlers;
+    private pending;
+    private closed;
+    private attempts;
+    private reconnectTimer;
+    constructor(opts: DurableObjectRelayTransportOptions);
+    send(message: RealtimeMessage): void;
+    onMessage(handler: (message: RealtimeMessage) => void): () => void;
+    close(): void;
+    private open;
+    private scheduleReconnect;
+    private flushPending;
+}
+export {};
+//# sourceMappingURL=durable-object-relay-transport.d.ts.map

package/dist/realtime/durable-object-relay-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-object-relay-transport.d.ts","sourceRoot":"","sources":["../../src/realtime/durable-object-relay-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1E;AAED,KAAK,UAAU,GAAG,KAAK,GAAG,EAAE,MAAM,KAAK,UAAU,CAAC;AAElD,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kCAAkC;IACjD,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;IAC3E,2DAA2D;IAC3D,SAAS,CAAC,EAAE,2BAA2B,GAAG,KAAK,CAAC;IAChD,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,UAAU,CAAC;CAC5B;AAmBD,qBAAa,2BAA4B,YAAW,iBAAiB;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+C;IACzE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,EAAE,CAA2B;IACrC,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,cAAc,CAA8C;gBAExD,IAAI,EAAE,kCAAkC;IAsBpD,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAYpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAOlE,KAAK,IAAI,IAAI;IAeb,OAAO,CAAC,IAAI;IA+CZ,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,YAAY;CAOrB"}

package/dist/realtime/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Trellis Realtime — Public Surface
+ *
+ * Ephemeral presence + broadcast primitives for multiplayer UI: active-user
+ * avatars, chat, live cursors, and collaborative text. Distinct from the
+ * persisted VCS op log — realtime data is mesh-broadcast and never written to
+ * the causal history.
+ *
+ * @module trellis/realtime
+ *
+ *   import {
+ *     RealtimeRoom,
+ *     BroadcastChannelTransport,
+ *     WebSocketRelayTransport,
+ *   } from 'trellis/realtime';
+ *
+ *   const room = RealtimeRoom.join({
+ *     transport: new BroadcastChannelTransport({ id, channel: 'room:42' }),
+ *     initialPresence: { name: 'Ada', color: '#6d5bfa' },
+ *   });
+ *
+ *   // Or relay across browsers:
+ *   new WebSocketRelayTransport({ id, url: 'ws://localhost:8231/rt' });
+ */
+export { RealtimeRoom } from './room.js';
+export type { RealtimeRoomOptions } from './room.js';
+export { MemoryHub, MemoryRealtimeTransport } from './memory-hub.js';
+export { BroadcastChannelTransport } from './broadcast-channel-transport.js';
+export type { BroadcastChannelTransportOptions } from './broadcast-channel-transport.js';
+export { WebSocketRelayTransport } from './websocket-relay-transport.js';
+export type { WebSocketRelayTransportOptions } from './websocket-relay-transport.js';
+export { DurableObjectRelayTransport } from './durable-object-relay-transport.js';
+export type { DurableObjectRelayTransportOptions, DurableObjectRelayReconnect, } from './durable-object-relay-transport.js';
+export { joinPresence, createPresenceTransport } from './presence.js';
+export type { PresenceOptions } from './presence.js';
+export { RelayPersistence, DEFAULT_MAX_CHAT, DEFAULT_MAX_TEXT_OPS, } from './relay-persistence.js';
+export type { RelayPersistenceOptions } from './relay-persistence.js';
+export { PersistentChannel, localStorageChannelStore, DEFAULT_MAX_RECORDS, } from './persistent-channel.js';
+export type { ChannelRecord, ChannelStore, PersistentChannelOptions, } from './persistent-channel.js';
+export { RealtimeText } from './text.js';
+export type { RealtimeTextOptions, TextNode, TextOp } from './text.js';
+export { REALTIME_PROTOCOL } from './types.js';
+export type { PresenceState, PresencePeer, BroadcastEvent, RealtimeMessage, RealtimeTransport, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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