yrby-client 0.4.0

package/README.md

@@ -0,0 +1,160 @@
+# yrby-client
+
+The **client core** for the [`yrby`](https://github.com/jpcamara/yrby)
+y-websocket protocol — everything a Yjs provider needs *except the transport*.
+Bring your own socket (ActionCable, AnyCable, raw WebSocket); this owns the
+protocol.
+
+Three layers, use whichever you need:
+
+- **`ActionCableProvider`** — a ready-made Yjs provider for ActionCable /
+  AnyCable. Pass a `Y.Doc`, a cable consumer, and a channel; it wires the
+  subscription and you're collaborating. Awareness/presence rides AnyCable
+  `whisper` when available via an awareness-only envelope and falls back to
+  normal sends on plain ActionCable; document updates always go through the
+  server as reliable recorded/acked updates.
+- **`YProtocolSession`** — the transport-agnostic core. Binds to a `Y.Doc` (+ optional
+  `Awareness`) and owns the y-protocols **message encode/decode**, the
+  **sync-step handshake** (SyncStep1 / SyncStep2 / Update), **awareness**, and
+  reliable delivery. Speaks raw `Uint8Array` frames; you wire any socket.
+- **`ReliableSync`** — the zero-dependency reliable-delivery state machine on its
+  own: ack-tracked queue, **sync-since-last-ack** (the unacked tail merged into
+  one causally-complete delta), cumulative acks, retransmit, and reconnect
+  replay. Compose it yourself if you already have your own framing.
+
+## Install
+
+```bash
+npm install yrby-client
+```
+
+`ActionCableProvider` and `YProtocolSession` need `yjs` and `y-protocols` (peers — your
+app already has them), plus an ActionCable/AnyCable consumer. `ReliableSync` has
+**no dependencies**; import it on its own via `yrby-client/reliable` if
+that's all you want.
+
+Written in **TypeScript** and ships bundled type declarations, so TS projects get
+full types (typed options, methods, and errors) with no `@types` package — and
+plain-JS projects use the same compiled ESM with nothing extra to install.
+
+## ActionCableProvider (the easy path)
+
+```js
+import { ActionCableProvider } from "yrby-client";
+import * as Y from "yjs";
+import { createConsumer } from "@anycable/web"; // or @rails/actioncable
+
+const doc = new Y.Doc();
+const consumer = createConsumer();
+const provider = new ActionCableProvider(doc, consumer, "DocumentChannel", { id: docId });
+
+provider.connect(); // does not auto-connect — wire your editor binding first
+
+// Observe the connection (one signal, no separate "sync" event):
+provider.onStatusChange(({ status }) => render(status)); // returns an unsubscribe fn
+//   "connecting"  -> subscription created, transport not up yet
+//   "connected"   -> transport up, exchanging sync steps (show "syncing")
+//   "synced"      -> caught up with the server
+//   "disconnected"-> torn down via disconnect()/destroy()
+//                    (a dropped transport ActionCable will retry shows as "connecting")
+
+// provider.status     -> the current status (same union as above)
+// provider.awareness  -> the provider's Awareness instance (always a fresh one)
+// provider.synced     -> caught up with the server
+// provider.hasPending -> unacked local edits in flight
+// provider.destroy()  -> tear down
+```
+
+On `disconnect()` / `destroy()` — and on browser `pagehide` — the provider
+broadcasts a presence removal so peers drop your cursor immediately instead of
+waiting for the awareness timeout. `destroy()` is synchronous (the unsubscribe is
+deferred one microtask so that removal flushes first) and tears down the
+`Awareness` it created. (`ActionCableProvider` always creates its own; to bring
+your own `Awareness`, drop down to `YProtocolSession`, which leaves it for you to
+own.)
+
+On the server, include `Y::ActionCable::Sync` in a channel named
+`DocumentChannel` (the [`yrby-actioncable`](https://rubygems.org/gems/yrby-actioncable)
+gem). The server subscribes document broadcasts and AnyCable awareness whispers
+on separate streams, so the document stream is not whisper-enabled. Need a
+different transport or framing? Drop down to `YProtocolSession` and supply your
+own `send`.
+
+The provider uses one JSON envelope shape:
+
+```txt
+client -> server document frame      { update: "<base64 frame>", id: 42 }
+server -> client document frame      { update: "<base64 frame>" }
+server -> client acknowledgement     { ack: 42 }
+AnyCable awareness whisper           { awareness: "<base64 awareness frame>" }
+```
+
+## YProtocolSession
+
+```js
+import { YProtocolSession, toBase64, fromBase64 } from "yrby-client";
+import * as Y from "yjs";
+import { Awareness } from "y-protocols/awareness";
+
+const doc = new Y.Doc();
+const awareness = new Awareness(doc);
+
+const session = new YProtocolSession(doc, {
+  awareness,
+  // transmit one raw frame; `id` is set for reliable doc updates -> tag your envelope
+  send: (frame, id) => {
+    const payload = { update: toBase64(frame) };
+    if (id !== undefined) payload.id = id;
+    subscription.send(payload);
+  },
+});
+
+// wire your transport's callbacks:
+subscription.connected    = () => session.onConnect();      // handshake + replay
+subscription.disconnected = () => session.onDisconnect();   // pause + clear presence
+subscription.received = (msg) => {
+  if (msg.ack !== undefined) return session.ack(msg.ack);   // reliable ack envelope
+  const reply = session.receive(fromBase64(msg.update));     // decode + apply
+  if (reply) subscription.send({ update: toBase64(reply) });     // e.g. answer a SyncStep1
+};
+// session.synced -> caught up; session.hasPending -> unacked edits in flight
+// session.destroy() -> detach listeners + stop retransmits
+```
+
+Local document edits and awareness changes are picked up automatically from the
+doc's / awareness's `update` events — you never call anything for outbound edits.
+
+Pass `onError(error, context)` (on either `ActionCableProvider` or
+`YProtocolSession`) to observe dropped frames: a malformed or truncated message
+is decoded defensively, dropped, and reported here rather than thrown into your
+transport callback. Defaults to a `console.warn`.
+
+## ReliableSync (standalone)
+
+```js
+import { ReliableSync } from "yrby-client/reliable"; // zero-dep
+import * as Y from "yjs";
+
+const rs = new ReliableSync({
+  send: (update, id) => { /* frame + transmit */ },
+  merge: Y.mergeUpdates,
+});
+
+rs.enqueue(update);  // a local document update
+rs.onAck(id);        // an { ack: id } arrived
+rs.onConnect();      // (re)connected — replay the tail, resume retransmits
+rs.onDisconnect();   // dropped — keep the queue, pause
+```
+
+Pending updates are retained and replayed until the server acknowledges them.
+Document delivery stays queued and ack-tracked for the lifetime of the session.
+
+## How it fits
+
+The server counterpart — ack *generation*, gap detection, record-before-distribute
+— is the `yrby-actioncable` gem's `Y::ActionCable::Sync`. This package
+is the client half of the same protocol.
+
+## License
+
+MIT

package/dist/actioncable_provider.d.ts

@@ -0,0 +1,65 @@
+import { YProtocolSession, type YProtocolSessionOptions } from "./y_protocol_session.js";
+import { Awareness } from "y-protocols/awareness";
+import type { Doc } from "yjs";
+/**
+ * Connection lifecycle, folded into one signal (no separate "sync" event):
+ * connecting (subscription created, transport not up yet), connected (transport
+ * up, exchanging sync steps; UI: "syncing"), synced (caught up), and disconnected
+ * (torn down via disconnect()/destroy()). A dropped transport that ActionCable
+ * will retry shows as "connecting", not "disconnected".
+ */
+export type ProviderStatus = "connecting" | "connected" | "synced" | "disconnected";
+/** Payload passed to onStatusChange listeners. */
+export interface StatusEvent {
+    status: ProviderStatus;
+}
+/** The minimal slice of an ActionCable/AnyCable subscription this provider uses. */
+export interface CableSubscription {
+    send(data: unknown): unknown;
+    /** AnyCable client-to-client broadcast; absent on plain ActionCable. */
+    whisper?(data: unknown): unknown;
+    unsubscribe?(): void;
+}
+/** The minimal slice of an ActionCable/AnyCable consumer this provider uses. */
+export interface CableConsumer {
+    subscriptions: {
+        create(params: object, mixin: object): CableSubscription;
+        remove(subscription: CableSubscription): void;
+    };
+}
+export type ActionCableProviderOptions = Pick<YProtocolSessionOptions, "resendInterval" | "onError">;
+export declare class ActionCableProvider {
+    #private;
+    readonly doc: Doc;
+    readonly consumer: CableConsumer;
+    readonly channelName: string;
+    readonly channelParams: object;
+    readonly awareness: Awareness;
+    readonly session: YProtocolSession;
+    constructor(doc: Doc, consumer: CableConsumer, channelName: string, channelParams?: object, opts?: ActionCableProviderOptions);
+    /** True once the document has caught up with the server (received a SyncStep2). */
+    get synced(): boolean;
+    /** True while there are unacknowledged local document updates in flight. */
+    get hasPending(): boolean;
+    /**
+     * Apply a bootstrap/restore update (initial HTTP state, a server snapshot, an
+     * import) without re-sending it to the server as a local edit. Call it once per
+     * chunk of already-durable state when seeding the doc, before `connect()`:
+     *
+     *   provider.applyRemoteUpdate(fromBase64(initialState));
+     *   priorUpdates.forEach((u) => provider.applyRemoteUpdate(fromBase64(u)));
+     *   provider.connect();
+     *
+     * See {@link YProtocolSession.applyRemoteUpdate} for why a bare `Y.applyUpdate`
+     * would be re-broadcast as a pending change instead.
+     */
+    applyRemoteUpdate(update: Uint8Array): void;
+    /** Current connection status. See {@link ProviderStatus}. */
+    get status(): ProviderStatus;
+    /** Subscribe to status changes. Returns an unsubscribe function. */
+    onStatusChange(listener: (event: StatusEvent) => void): () => void;
+    connect(): void;
+    disconnect(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=actioncable_provider.d.ts.map

package/dist/actioncable_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actioncable_provider.d.ts","sourceRoot":"","sources":["../src/actioncable_provider.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,gBAAgB,EAAe,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEtG,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEpF,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7B,wEAAwE;IACxE,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjC,WAAW,CAAC,IAAI,IAAI,CAAC;CACtB;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE;QACb,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC;QACzD,MAAM,CAAC,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;KAC/C,CAAC;CACH;AAED,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,uBAAuB,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC;AAQrG,qBAAa,mBAAmB;;IAC9B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBASjC,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,MAAM,EACnB,aAAa,GAAE,MAAW,EAC1B,IAAI,GAAE,0BAA+B;IAiBvC,mFAAmF;IACnF,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,4EAA4E;IAC5E,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAI3C,6DAA6D;IAC7D,IAAI,MAAM,IAAI,cAAc,CAE3B;IAED,oEAAoE;IACpE,cAAc,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlE,OAAO,IAAI,IAAI;IAgDf,UAAU,IAAI,IAAI;IAelB,OAAO,IAAI,IAAI;CAqDhB"}

package/dist/actioncable_provider.js

@@ -0,0 +1,197 @@
+// Yjs provider for the yrby y-websocket protocol over ActionCable / AnyCable.
+// It owns the cable subscription and translates between the cable's JSON envelope
+// (`{ update, id }` / `{ ack }`, base64) and raw protocol frames. Everything else
+// (sync steps, encode/decode, awareness, reliable delivery) lives in
+// YProtocolSession; this is the transport glue.
+//
+// Awareness frames use AnyCable's `whisper` when available, under a separate
+// awareness-only envelope. Document frames always use `send` so they go through
+// the server's persistence/ack path.
+//
+// The constructor does not auto-connect: wire up your editor binding first, then
+// call `connect()`. Watch the connection with `onStatusChange(({ status }) => ...)`
+// or the `status` getter. On `disconnect()`/`destroy()`, and on browser
+// `pagehide`, the provider broadcasts a presence removal so peers drop our cursor
+// right away instead of waiting for the awareness timeout.
+import { YProtocolSession, MessageType } from "./y_protocol_session.js";
+import { toBase64, fromBase64 } from "./base64.js";
+import { Awareness } from "y-protocols/awareness";
+export class ActionCableProvider {
+    doc;
+    consumer;
+    channelName;
+    channelParams;
+    awareness;
+    session;
+    #subscription = null;
+    #onError;
+    #connected = false;
+    #status = "disconnected";
+    #statusListeners = new Set();
+    #onUnload = null;
+    constructor(doc, consumer, channelName, channelParams = {}, opts = {}) {
+        this.doc = doc;
+        this.consumer = consumer;
+        this.channelName = channelName;
+        this.channelParams = channelParams;
+        this.awareness = new Awareness(doc);
+        this.#onError = opts.onError ?? ((error, context) => console.warn(`[yrby] ${context}:`, error));
+        this.session = new YProtocolSession(doc, {
+            awareness: this.awareness,
+            resendInterval: opts.resendInterval,
+            onError: this.#onError,
+            send: (frame, id) => this.#send(frame, id),
+        });
+    }
+    /** True once the document has caught up with the server (received a SyncStep2). */
+    get synced() {
+        return this.session.synced;
+    }
+    /** True while there are unacknowledged local document updates in flight. */
+    get hasPending() {
+        return this.session.hasPending;
+    }
+    /**
+     * Apply a bootstrap/restore update (initial HTTP state, a server snapshot, an
+     * import) without re-sending it to the server as a local edit. Call it once per
+     * chunk of already-durable state when seeding the doc, before `connect()`:
+     *
+     *   provider.applyRemoteUpdate(fromBase64(initialState));
+     *   priorUpdates.forEach((u) => provider.applyRemoteUpdate(fromBase64(u)));
+     *   provider.connect();
+     *
+     * See {@link YProtocolSession.applyRemoteUpdate} for why a bare `Y.applyUpdate`
+     * would be re-broadcast as a pending change instead.
+     */
+    applyRemoteUpdate(update) {
+        this.session.applyRemoteUpdate(update);
+    }
+    /** Current connection status. See {@link ProviderStatus}. */
+    get status() {
+        return this.#status;
+    }
+    /** Subscribe to status changes. Returns an unsubscribe function. */
+    onStatusChange(listener) {
+        this.#statusListeners.add(listener);
+        return () => this.#statusListeners.delete(listener);
+    }
+    connect() {
+        if (this.#subscription)
+            return;
+        const provider = this;
+        this.#subscription = this.consumer.subscriptions.create({ channel: this.channelName, ...this.channelParams }, {
+            received(message) {
+                // Reliable-delivery ack: confirm + prune the local queue.
+                if (message && message.ack !== undefined) {
+                    provider.session.ack(message.ack);
+                    return;
+                }
+                const awarenessPayload = message && message.awareness;
+                const payload = message && (awarenessPayload ?? message.update);
+                if (typeof payload !== "string")
+                    return;
+                // Guard base64 decode too: a malformed envelope must not throw into
+                // the cable callback (session.receive is itself defensive).
+                let frame;
+                try {
+                    frame = fromBase64(payload);
+                }
+                catch (error) {
+                    provider.#onError(error, "received");
+                    return;
+                }
+                if (awarenessPayload !== undefined && frame[0] !== MessageType.Awareness) {
+                    provider.#onError(new Error("awareness envelope carried a non-awareness frame"), "received");
+                    return;
+                }
+                const reply = provider.session.receive(frame);
+                if (reply)
+                    provider.#send(reply, undefined); // e.g. SyncStep2 answering a SyncStep1
+                provider.#refreshStatus(); // a SyncStep2 may have just flipped us to "synced"
+            },
+            connected() {
+                provider.#connected = true;
+                provider.session.onConnect(); // handshake + replay the unacked tail
+                provider.#refreshStatus();
+            },
+            disconnected() {
+                provider.#connected = false;
+                provider.session.onDisconnect(); // pause retransmits, clear remote presence
+                provider.#refreshStatus(); // subscription still set -> "connecting" (retrying)
+            },
+        });
+        this.#installUnloadHandler();
+        this.#refreshStatus(); // -> "connecting"
+    }
+    disconnect() {
+        if (!this.#subscription)
+            return;
+        const sub = this.#subscription;
+        // Tell peers we're gone while the transport is still live, then pause and
+        // detach. Defer the unsubscribe one microtask so the removal frame flushes
+        // before the channel tears down.
+        this.session.removeLocalAwareness();
+        this.session.onDisconnect();
+        this.#connected = false;
+        this.#subscription = null;
+        this.#removeUnloadHandler();
+        queueMicrotask(() => this.consumer.subscriptions.remove(sub));
+        this.#refreshStatus(); // -> "disconnected"
+    }
+    destroy() {
+        this.disconnect();
+        this.session.destroy();
+        this.awareness.destroy(); // stops its reaper timer
+        this.#statusListeners.clear();
+    }
+    #computeStatus() {
+        if (!this.#subscription)
+            return "disconnected";
+        if (!this.#connected)
+            return "connecting";
+        return this.session.synced ? "synced" : "connected";
+    }
+    #refreshStatus() {
+        const next = this.#computeStatus();
+        if (next === this.#status)
+            return;
+        this.#status = next;
+        for (const listener of this.#statusListeners)
+            listener({ status: next });
+    }
+    // Best-effort presence removal when the tab/page goes away (close, navigation,
+    // bfcache). `pagehide` fires while the socket is still live and is bfcache-safe
+    // (unlike `beforeunload`, which can block it). Sends are not guaranteed to
+    // flush on unload, so the server-side awareness timeout remains the backstop.
+    #installUnloadHandler() {
+        if (typeof window === "undefined" || this.#onUnload)
+            return;
+        this.#onUnload = () => this.session.removeLocalAwareness();
+        window.addEventListener("pagehide", this.#onUnload);
+    }
+    #removeUnloadHandler() {
+        if (typeof window === "undefined" || !this.#onUnload)
+            return;
+        window.removeEventListener("pagehide", this.#onUnload);
+        this.#onUnload = null;
+    }
+    // Send one raw protocol frame over the cable. Awareness frames are whispered
+    // when AnyCable exposes `subscription.whisper`; otherwise they fall back to a
+    // normal send. `id` (reliable doc updates) is tagged onto the envelope so the
+    // server can ack. A no-op while disconnected: reliable frames stay queued in
+    // the session and flush on the next connect().
+    #send(frame, id) {
+        const sub = this.#subscription;
+        if (!sub)
+            return;
+        const update = toBase64(frame);
+        const isAwareness = frame[0] === MessageType.Awareness;
+        if (isAwareness && typeof sub.whisper === "function") {
+            sub.whisper({ awareness: update });
+            return;
+        }
+        const payload = id === undefined ? { update } : { update, id };
+        sub.send(payload);
+    }
+}
+//# sourceMappingURL=actioncable_provider.js.map

package/dist/actioncable_provider.js.map

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

package/dist/base64.d.ts

@@ -0,0 +1,3 @@
+export declare const toBase64: (bytes: Uint8Array) => string;
+export declare const fromBase64: (str: string) => Uint8Array;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,KAAG,MACoB,CAAC;AAElE,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,UAAgE,CAAC"}

package/dist/base64.js

@@ -0,0 +1,6 @@
+// base64 codecs for transports that carry binary frames as strings (e.g.
+// ActionCable's JSON envelope). Optional; a binary WebSocket transport sends the
+// raw frames directly and never needs these.
+export const toBase64 = (bytes) => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(""));
+export const fromBase64 = (str) => Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
+//# sourceMappingURL=base64.js.map

package/dist/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,iFAAiF;AACjF,6CAA6C;AAE7C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAiB,EAAU,EAAE,CACpD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAElE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAc,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { ReliableSync } from "./reliable_sync.js";
+export type { ReliableSyncOptions, TimerHandle } from "./reliable_sync.js";
+export { YProtocolSession, MessageType } from "./y_protocol_session.js";
+export type { YProtocolSessionOptions } from "./y_protocol_session.js";
+export { ActionCableProvider } from "./actioncable_provider.js";
+export type { ActionCableProviderOptions, ProviderStatus, StatusEvent, CableConsumer, CableSubscription, } from "./actioncable_provider.js";
+export { toBase64, fromBase64 } from "./base64.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAI3E,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACxE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAIvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EACV,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// Zero-dependency reliable-delivery core. Safe to import on its own.
+export { ReliableSync } from "./reliable_sync.js";
+// Protocol session (sync steps + encode/decode + awareness).
+// Requires `yjs` and `y-protocols` as peers.
+export { YProtocolSession, MessageType } from "./y_protocol_session.js";
+// ActionCable / AnyCable provider built on YProtocolSession.
+// Bring your own provider instead by composing YProtocolSession.
+export { ActionCableProvider } from "./actioncable_provider.js";
+// Optional base64 helpers for transports that carry frames as strings.
+export { toBase64, fromBase64 } from "./base64.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,6DAA6D;AAC7D,6CAA6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGxE,6DAA6D;AAC7D,iEAAiE;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAShE,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/reliable_sync.d.ts

@@ -0,0 +1,59 @@
+/** An opaque timer handle (number in browsers, Timeout in Node). */
+export type TimerHandle = unknown;
+export interface ReliableSyncOptions {
+    /**
+     * Transmit one update. `update` is the raw merged update bytes; `id` is the
+     * cumulative sequence to ack against.
+     */
+    send: (update: Uint8Array, id: number) => void;
+    /** Merge an array of update byte-arrays into one (typically Y.mergeUpdates). */
+    merge: (updates: Uint8Array[]) => Uint8Array;
+    /** Milliseconds between retransmits of the unacked tail (default 1000). */
+    resendInterval?: number;
+    /** Injectable timer hooks (default to globals); handy for tests. */
+    setInterval?: (handler: () => void, ms: number) => TimerHandle;
+    clearInterval?: (handle: TimerHandle) => void;
+}
+interface Pending {
+    seq: number;
+    update: Uint8Array;
+}
+export declare class ReliableSync {
+    #private;
+    /** Unacked local updates, in order. */
+    pending: Pending[];
+    constructor(opts: ReliableSyncOptions);
+    /** True while there are unacknowledged local updates. */
+    get hasPending(): boolean;
+    /**
+     * Record a local document update. It is queued and the unacked tail is
+     * flushed; the update remains retained until the server acknowledges it.
+     */
+    enqueue(update: Uint8Array): void;
+    /**
+     * Send the whole unacked tail as one merged delta. The id is the highest seq
+     * in the batch, so a single { ack } cumulatively confirms everything up to it.
+     * No-op while disconnected (the tail is replayed on the next onConnect).
+     */
+    flush(): void;
+    /**
+     * Confirm delivery up to `id`: prune every queued update with seq <= id.
+     * Acks arrive over the wire, so validate before pruning. A malformed value
+     * (NaN/string/negative) or an impossible future id must not silently drop the
+     * queue; invalid acks are ignored.
+     */
+    onAck(id: number): void;
+    /** Transport (re)connected: replay the unacked tail and resume retransmits. */
+    onConnect(): void;
+    /** Transport dropped: keep the queue (for reconnect replay), pause the timer. */
+    onDisconnect(): void;
+    /**
+     * One retransmit tick. Exposed for deterministic testing; normally driven by
+     * the internal timer.
+     */
+    onTick(): void;
+    /** Stop timers and drop references. Call when the provider is destroyed. */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=reliable_sync.d.ts.map

package/dist/reliable_sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliable_sync.d.ts","sourceRoot":"","sources":["../src/reliable_sync.ts"],"names":[],"mappings":"AAgBA,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,gFAAgF;IAChF,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,CAAC;IAC7C,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC;IAC/D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/C;AAID,UAAU,OAAO;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,qBAAa,YAAY;;IACvB,uCAAuC;IACvC,OAAO,EAAE,OAAO,EAAE,CAAM;gBAeZ,IAAI,EAAE,mBAAmB;IAiBrC,yDAAyD;IACzD,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOjC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQvB,+EAA+E;IAC/E,SAAS,IAAI,IAAI;IAMjB,iFAAiF;IACjF,YAAY,IAAI,IAAI;IAKpB;;;OAGG;IACH,MAAM,IAAI,IAAI;IAKd,4EAA4E;IAC5E,OAAO,IAAI,IAAI;CA2BhB"}

package/dist/reliable_sync.js

@@ -0,0 +1,139 @@
+// Transport-agnostic reliable-delivery core for the yrby y-websocket
+// protocol: an ack-tracked queue of unacknowledged local updates,
+// sync-since-last-ack (the unacked tail goes out as one merged, causally-complete
+// delta so the server never sees an internal gap), cumulative acks, periodic
+// retransmit, and reconnect replay.
+//
+// It doesn't touch the transport, the Yjs binding, or wire encoding. Inject two
+// functions:
+// send(update, id) transmits one update (raw merged bytes plus a cumulative
+// sequence id; you frame, base64, and put it on the socket), and merge(updates)
+// merges update byte-arrays into one (usually Y.mergeUpdates). Drive it from the
+// provider lifecycle: enqueue(update) on each local edit, onAck(id) when an
+// { ack: id } frame arrives, and onConnect()/onDisconnect() on transport changes.
+//
+// Awareness/presence stays out of scope; it's fire-and-forget in the provider.
+const DEFAULTS = { resendInterval: 1000 };
+export class ReliableSync {
+    /** Unacked local updates, in order. */
+    pending = [];
+    #send;
+    #merge;
+    #resendInterval;
+    #setInterval;
+    #clearInterval;
+    #nextSeq = 1;
+    #connected = false;
+    #timer = undefined;
+    // Memoized merge of the unacked tail. The tail only changes on enqueue/ack, so
+    // retransmit ticks reuse this instead of re-merging the whole queue each time.
+    #tailCache = undefined;
+    constructor(opts) {
+        const { send, merge, resendInterval } = opts ?? {};
+        if (typeof send !== "function")
+            throw new TypeError("ReliableSync requires a send(update, id) function");
+        if (typeof merge !== "function")
+            throw new TypeError("ReliableSync requires a merge(updates) function");
+        this.#send = send;
+        this.#merge = merge;
+        const interval = resendInterval ?? DEFAULTS.resendInterval;
+        if (!Number.isFinite(interval) || interval <= 0) {
+            throw new TypeError("ReliableSync resendInterval must be a positive number");
+        }
+        this.#resendInterval = interval;
+        // Injectable timer hooks make the resend loop testable; default to globals.
+        this.#setInterval = opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+        this.#clearInterval = opts.clearInterval ?? ((h) => clearInterval(h));
+    }
+    /** True while there are unacknowledged local updates. */
+    get hasPending() {
+        return this.pending.length > 0;
+    }
+    /**
+     * Record a local document update. It is queued and the unacked tail is
+     * flushed; the update remains retained until the server acknowledges it.
+     */
+    enqueue(update) {
+        this.pending.push({ seq: this.#nextSeq++, update });
+        this.#tailCache = undefined; // tail changed
+        if (this.#connected)
+            this.#startTimer();
+        this.flush();
+    }
+    /**
+     * Send the whole unacked tail as one merged delta. The id is the highest seq
+     * in the batch, so a single { ack } cumulatively confirms everything up to it.
+     * No-op while disconnected (the tail is replayed on the next onConnect).
+     */
+    flush() {
+        if (!this.#connected || this.pending.length === 0)
+            return;
+        this.#send(this.#mergedTail(), this.pending[this.pending.length - 1].seq);
+    }
+    /**
+     * Confirm delivery up to `id`: prune every queued update with seq <= id.
+     * Acks arrive over the wire, so validate before pruning. A malformed value
+     * (NaN/string/negative) or an impossible future id must not silently drop the
+     * queue; invalid acks are ignored.
+     */
+    onAck(id) {
+        if (!Number.isSafeInteger(id) || id < 0)
+            return; // malformed / impossible
+        if (this.pending.length > 0 && id > this.pending[this.pending.length - 1].seq)
+            return; // future ack
+        this.pending = this.pending.filter((p) => p.seq > id);
+        this.#tailCache = undefined; // tail changed
+        if (this.pending.length === 0)
+            this.#stopTimer();
+    }
+    /** Transport (re)connected: replay the unacked tail and resume retransmits. */
+    onConnect() {
+        this.#connected = true;
+        this.flush();
+        if (this.pending.length > 0)
+            this.#startTimer();
+    }
+    /** Transport dropped: keep the queue (for reconnect replay), pause the timer. */
+    onDisconnect() {
+        this.#connected = false;
+        this.#stopTimer();
+    }
+    /**
+     * One retransmit tick. Exposed for deterministic testing; normally driven by
+     * the internal timer.
+     */
+    onTick() {
+        if (!this.#connected || this.pending.length === 0)
+            return;
+        this.flush();
+    }
+    /** Stop timers and drop references. Call when the provider is destroyed. */
+    destroy() {
+        this.#connected = false;
+        this.#stopTimer();
+        this.pending = [];
+        this.#tailCache = undefined;
+    }
+    /** The unacked tail merged into one delta (memoized between tail changes). */
+    #mergedTail() {
+        if (this.#tailCache === undefined) {
+            const updates = this.pending.map((p) => p.update);
+            this.#tailCache = updates.length === 1 ? updates[0] : this.#merge(updates);
+        }
+        return this.#tailCache;
+    }
+    #startTimer() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = this.#setInterval(() => this.onTick(), this.#resendInterval);
+        const t = this.#timer;
+        if (t && typeof t.unref === "function")
+            t.unref();
+    }
+    #stopTimer() {
+        if (this.#timer !== undefined)
+            this.#clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+//# sourceMappingURL=reliable_sync.js.map

package/dist/reliable_sync.js.map

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

package/dist/y_protocol_session.d.ts

@@ -0,0 +1,76 @@
+import { Doc } from "yjs";
+import { type Awareness } from "y-protocols/awareness";
+import { type TimerHandle } from "./reliable_sync.js";
+export declare const MessageType: {
+    readonly Sync: 0;
+    readonly Awareness: 1;
+};
+export interface YProtocolSessionOptions {
+    /**
+     * Transmit one raw protocol frame. `id` is set only for reliable document
+     * updates (tag it onto your envelope so the server can ack). Awareness frames
+     * are identifiable by their first byte (`MessageType.Awareness`) if a transport
+     * needs to route them separately.
+     */
+    send: (frame: Uint8Array, id: number | undefined) => void;
+    /** Optional awareness/presence. When omitted, awareness frames are ignored. */
+    awareness?: Awareness | null;
+    /** Forwarded to ReliableSync. */
+    resendInterval?: number;
+    /**
+     * Called when an incoming frame can't be decoded/applied (malformed bytes,
+     * truncated message, unexpected structure). The frame is dropped and the
+     * session keeps running. `context` names where it happened (e.g. "receive").
+     * Defaults to a `console.warn`.
+     */
+    onError?: (error: unknown, context: string) => void;
+    /** Injectable timer hooks (forwarded to ReliableSync); handy for tests. */
+    setInterval?: (handler: () => void, ms: number) => TimerHandle;
+    clearInterval?: (handle: TimerHandle) => void;
+}
+export declare class YProtocolSession {
+    #private;
+    readonly doc: Doc;
+    readonly awareness: Awareness | null;
+    constructor(doc: Doc, opts: YProtocolSessionOptions);
+    /** True once we've received the server's SyncStep2 (the document is caught up). */
+    get synced(): boolean;
+    /** True while there are unacknowledged local document updates in flight. */
+    get hasPending(): boolean;
+    /** Transport connected: send the opening handshake and replay the unacked tail. */
+    onConnect(): void;
+    /** Transport dropped: pause retransmits (queue kept) and clear remote presence. */
+    onDisconnect(): void;
+    /**
+     * Broadcast that our local presence is gone (sets local state to null, which
+     * emits a removal awareness frame through `send`). Call this while the
+     * transport is still live so peers drop our cursor immediately instead of
+     * waiting for the awareness timeout. A no-op when there's no local state.
+     */
+    removeLocalAwareness(): void;
+    /** A reliable-delivery `{ ack: id }` envelope arrived. */
+    ack(id: number): void;
+    /**
+     * Apply an update without treating it as a local edit, so it isn't queued for
+     * re-delivery to the server. Use it for bootstrap/restore: initial state loaded
+     * over HTTP, a server snapshot, an import. These are bytes the server already
+     * has.
+     *
+     * The session re-sends any doc update whose origin isn't itself (that's how a
+     * keystroke becomes an outbound frame), so a bare `Y.applyUpdate(doc, update)`
+     * would look like a local edit and get echoed back on the next connect. Going
+     * through here applies under the session's own origin, which the outbound
+     * filter skips. Safe to call before `onConnect()`: the state folds into the
+     * SyncStep1 handshake instead of being re-sent.
+     */
+    applyRemoteUpdate(update: Uint8Array): void;
+    /**
+     * Decode and apply one incoming binary protocol frame (document sync or
+     * awareness). Returns a reply frame to transmit (e.g. SyncStep2 answering a
+     * SyncStep1), or null if there's nothing to send.
+     */
+    receive(frame: Uint8Array): Uint8Array | null;
+    /** Detach doc/awareness listeners and stop retransmits. */
+    destroy(): void;
+}
+//# sourceMappingURL=y_protocol_session.d.ts.map

package/dist/y_protocol_session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"y_protocol_session.d.ts","sourceRoot":"","sources":["../src/y_protocol_session.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,GAAG,EAA6B,MAAM,KAAK,CAAC;AAIrD,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIpE,eAAO,MAAM,WAAW;;;CAAqC,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAC1D,+EAA+E;IAC/E,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,2EAA2E;IAC3E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC;IAC/D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/C;AAID,qBAAa,gBAAgB;;IAC3B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;gBASzB,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,uBAAuB;IA6CnD,mFAAmF;IACnF,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,4EAA4E;IAC5E,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,mFAAmF;IACnF,SAAS,IAAI,IAAI;IAQjB,mFAAmF;IACnF,YAAY,IAAI,IAAI;IASpB;;;;;OAKG;IACH,oBAAoB,IAAI,IAAI;IAM5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIrB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAI3C;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI;IA8B7C,2DAA2D;IAC3D,OAAO,IAAI,IAAI;CAwDhB"}

package/dist/y_protocol_session.js

@@ -0,0 +1,216 @@
+// Transport-agnostic session for the yrby y-websocket protocol. Handles the
+// y-protocols framing, the sync handshake (SyncStep1/Step2/Update), and awareness
+// encode/apply on top of ReliableSync. Bind it to a Y.Doc (and an optional
+// Awareness); it works in raw Uint8Array frames and leaves the transport to the
+// caller: base64, the { update, id } / { ack } envelope, and a socket.
+//
+// Call onConnect() when the transport connects, onDisconnect() when it drops,
+// ack(id) on an { ack } envelope, and receive(frame) for an inbound frame (it
+// returns a reply to send, or null). Local doc and awareness edits send
+// themselves via the "update" events.
+import { Doc, mergeUpdates, applyUpdate } from "yjs";
+import * as encoding from "lib0/encoding";
+import * as decoding from "lib0/decoding";
+import { readSyncMessage, writeSyncStep1, writeUpdate, messageYjsSyncStep2 } from "y-protocols/sync";
+import { encodeAwarenessUpdate, applyAwarenessUpdate, removeAwarenessStates, } from "y-protocols/awareness";
+import { ReliableSync } from "./reliable_sync.js";
+// The y-protocols frame types yrby speaks, as the leading byte of a frame.
+// Other y-protocols types (auth = 2, query-awareness = 3) are not handled.
+export const MessageType = { Sync: 0, Awareness: 1 };
+export class YProtocolSession {
+    doc;
+    awareness;
+    #send;
+    #onError;
+    #synced = false;
+    #delivery;
+    #onDocUpdate;
+    #onAwarenessUpdate;
+    constructor(doc, opts) {
+        const { send, awareness = null, resendInterval, onError, setInterval: setIntervalFn, clearInterval: clearIntervalFn, } = opts ?? {};
+        if (!doc)
+            throw new TypeError("YProtocolSession requires a Y.Doc");
+        if (typeof send !== "function")
+            throw new TypeError("YProtocolSession requires a send(frame, id) function");
+        this.doc = doc;
+        this.awareness = awareness;
+        this.#send = send;
+        this.#onError = onError ?? ((error, context) => console.warn(`[yrby] ${context}:`, error));
+        this.#delivery = new ReliableSync({
+            merge: mergeUpdates,
+            send: (update, id) => this.#send(this.#frameUpdate(update), id),
+            resendInterval,
+            setInterval: setIntervalFn,
+            clearInterval: clearIntervalFn,
+        });
+        this.#onDocUpdate = (update, origin) => {
+            if (origin === this)
+                return; // applied from the server; don't echo it back
+            this.#delivery.enqueue(update);
+        };
+        this.doc.on("update", this.#onDocUpdate);
+        if (this.awareness) {
+            this.#onAwarenessUpdate = ({ added, updated, removed }, origin) => {
+                // Only broadcast our own presence changes. Updates applied from a peer,
+                // and our own remote-cleanup in onDisconnect, carry origin === this;
+                // re-sending those would echo presence and broadcast tombstones for
+                // other clients' cursors.
+                if (origin === this)
+                    return;
+                const changed = added.concat(updated, removed);
+                this.#send(this.#frameAwareness(changed), undefined); // fire-and-forget
+            };
+            this.awareness.on("update", this.#onAwarenessUpdate);
+        }
+    }
+    /** True once we've received the server's SyncStep2 (the document is caught up). */
+    get synced() {
+        return this.#synced;
+    }
+    /** True while there are unacknowledged local document updates in flight. */
+    get hasPending() {
+        return this.#delivery.hasPending;
+    }
+    /** Transport connected: send the opening handshake and replay the unacked tail. */
+    onConnect() {
+        this.#send(this.#frameSyncStep1(), undefined);
+        if (this.awareness && this.awareness.getLocalState() !== null) {
+            this.#send(this.#frameAwareness([this.doc.clientID]), undefined);
+        }
+        this.#delivery.onConnect();
+    }
+    /** Transport dropped: pause retransmits (queue kept) and clear remote presence. */
+    onDisconnect() {
+        this.#synced = false;
+        this.#delivery.onDisconnect();
+        if (this.awareness) {
+            const remote = [...this.awareness.getStates().keys()].filter((c) => c !== this.doc.clientID);
+            if (remote.length)
+                removeAwarenessStates(this.awareness, remote, this);
+        }
+    }
+    /**
+     * Broadcast that our local presence is gone (sets local state to null, which
+     * emits a removal awareness frame through `send`). Call this while the
+     * transport is still live so peers drop our cursor immediately instead of
+     * waiting for the awareness timeout. A no-op when there's no local state.
+     */
+    removeLocalAwareness() {
+        if (this.awareness && this.awareness.getLocalState() !== null) {
+            this.awareness.setLocalState(null); // fires "update" -> sends the removal frame
+        }
+    }
+    /** A reliable-delivery `{ ack: id }` envelope arrived. */
+    ack(id) {
+        this.#delivery.onAck(id);
+    }
+    /**
+     * Apply an update without treating it as a local edit, so it isn't queued for
+     * re-delivery to the server. Use it for bootstrap/restore: initial state loaded
+     * over HTTP, a server snapshot, an import. These are bytes the server already
+     * has.
+     *
+     * The session re-sends any doc update whose origin isn't itself (that's how a
+     * keystroke becomes an outbound frame), so a bare `Y.applyUpdate(doc, update)`
+     * would look like a local edit and get echoed back on the next connect. Going
+     * through here applies under the session's own origin, which the outbound
+     * filter skips. Safe to call before `onConnect()`: the state folds into the
+     * SyncStep1 handshake instead of being re-sent.
+     */
+    applyRemoteUpdate(update) {
+        applyUpdate(this.doc, update, this);
+    }
+    /**
+     * Decode and apply one incoming binary protocol frame (document sync or
+     * awareness). Returns a reply frame to transmit (e.g. SyncStep2 answering a
+     * SyncStep1), or null if there's nothing to send.
+     */
+    receive(frame) {
+        // A malformed/truncated frame must never take down the transport callback:
+        // decode + apply defensively, drop the frame on error, keep the session live.
+        try {
+            const validatedType = this.#validateFrame(frame);
+            if (validatedType === null)
+                return null;
+            const decoder = decoding.createDecoder(frame);
+            const encoder = encoding.createEncoder();
+            const type = decoding.readVarUint(decoder);
+            switch (type) {
+                case MessageType.Sync: {
+                    encoding.writeVarUint(encoder, MessageType.Sync);
+                    const syncType = readSyncMessage(decoder, encoder, this.doc, this);
+                    if (!this.#synced && syncType === messageYjsSyncStep2)
+                        this.#synced = true;
+                    break;
+                }
+                case MessageType.Awareness:
+                    if (this.awareness)
+                        applyAwarenessUpdate(this.awareness, decoding.readVarUint8Array(decoder), this);
+                    break;
+                default:
+                    return null; // a y-protocols type yrby doesn't speak (auth, query-awareness): ignore
+            }
+            return encoding.length(encoder) > 1 ? encoding.toUint8Array(encoder) : null;
+        }
+        catch (error) {
+            this.#onError(error, "receive");
+            return null;
+        }
+    }
+    /** Detach doc/awareness listeners and stop retransmits. */
+    destroy() {
+        this.doc.off("update", this.#onDocUpdate);
+        if (this.awareness && this.#onAwarenessUpdate)
+            this.awareness.off("update", this.#onAwarenessUpdate);
+        this.#delivery.destroy();
+    }
+    #frameSyncStep1() {
+        const e = encoding.createEncoder();
+        encoding.writeVarUint(e, MessageType.Sync);
+        writeSyncStep1(e, this.doc);
+        return encoding.toUint8Array(e);
+    }
+    #frameUpdate(update) {
+        const e = encoding.createEncoder();
+        encoding.writeVarUint(e, MessageType.Sync);
+        writeUpdate(e, update);
+        return encoding.toUint8Array(e);
+    }
+    #frameAwareness(clients) {
+        const e = encoding.createEncoder();
+        encoding.writeVarUint(e, MessageType.Awareness);
+        encoding.writeVarUint8Array(e, encodeAwarenessUpdate(this.awareness, clients));
+        return encoding.toUint8Array(e);
+    }
+    #validateFrame(frame) {
+        const decoder = decoding.createDecoder(frame);
+        const type = decoding.readVarUint(decoder);
+        switch (type) {
+            case MessageType.Sync: {
+                const scratchDoc = new Doc();
+                try {
+                    const scratchEncoder = encoding.createEncoder();
+                    encoding.writeVarUint(scratchEncoder, MessageType.Sync);
+                    readSyncMessage(decoder, scratchEncoder, scratchDoc, this);
+                }
+                finally {
+                    scratchDoc.destroy();
+                }
+                break;
+            }
+            case MessageType.Awareness:
+                decoding.readVarUint8Array(decoder);
+                break;
+            default:
+                return null; // a y-protocols type yrby doesn't speak: ignore
+        }
+        // This protocol is one message per frame. Anything left after a complete
+        // message is malformed (trailing garbage, or low-level packed messages whose
+        // tail we'd silently drop), so reject it before mutating local state.
+        if (decoding.hasContent(decoder)) {
+            throw new Error("frame has trailing bytes after a complete message");
+        }
+        return type;
+    }
+}
+//# sourceMappingURL=y_protocol_session.js.map

package/dist/y_protocol_session.js.map

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

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "yrby-client",
+  "version": "0.4.0",
+  "description": "JavaScript client for the yrby y-websocket protocol: a ready-made ActionCable/AnyCable provider, a transport-agnostic protocol session (sync steps, encode/decode, awareness), and a reliable-delivery core (ack-tracked queue, sync-since-last-ack, retransmit + reconnect replay). Written in TypeScript with bundled types; usable from plain JS.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./reliable": {
+      "types": "./dist/reliable_sync.d.ts",
+      "default": "./dist/reliable_sync.js"
+    },
+    "./base64": {
+      "types": "./dist/base64.d.ts",
+      "default": "./dist/base64.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test"
+  },
+  "license": "MIT",
+  "author": "JP Camara <jp@jpcamara.com>",
+  "homepage": "https://github.com/jpcamara/yrby/tree/main/packages/client#readme",
+  "bugs": {
+    "url": "https://github.com/jpcamara/yrby/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpcamara/yrby.git",
+    "directory": "packages/client"
+  },
+  "keywords": [
+    "yjs",
+    "crdt",
+    "yrby",
+    "reliable-delivery",
+    "actioncable",
+    "y-websocket",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "yjs": "^13.6.0",
+    "y-protocols": "^1.0.5"
+  },
+  "peerDependenciesMeta": {
+    "yjs": {
+      "optional": true
+    },
+    "y-protocols": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "lib0": "^0.2.117"
+  },
+  "devDependencies": {
+    "yjs": "^13.6.0",
+    "y-protocols": "^1.0.5",
+    "typescript": "^5.6.0"
+  }
+}