yrby-client 0.4.0 → 0.4.1

package/dist/cjs/actioncable_provider.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionCableProvider = void 0;
+// 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.
+const y_protocol_session_js_1 = require("./y_protocol_session.js");
+const base64_js_1 = require("./base64.js");
+const awareness_1 = require("y-protocols/awareness");
+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_1.Awareness(doc);
+        this.#onError = opts.onError ?? ((error, context) => console.warn(`[yrby] ${context}:`, error));
+        this.session = new y_protocol_session_js_1.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 = (0, base64_js_1.fromBase64)(payload);
+                }
+                catch (error) {
+                    provider.#onError(error, "received");
+                    return;
+                }
+                if (awarenessPayload !== undefined && frame[0] !== y_protocol_session_js_1.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 = (0, base64_js_1.toBase64)(frame);
+        const isAwareness = frame[0] === y_protocol_session_js_1.MessageType.Awareness;
+        if (isAwareness && typeof sub.whisper === "function") {
+            sub.whisper({ awareness: update });
+            return;
+        }
+        const payload = id === undefined ? { update } : { update, id };
+        sub.send(payload);
+    }
+}
+exports.ActionCableProvider = ActionCableProvider;

package/dist/cjs/base64.js

@@ -0,0 +1,10 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromBase64 = exports.toBase64 = void 0;
+const toBase64 = (bytes) => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(""));
+exports.toBase64 = toBase64;
+const fromBase64 = (str) => Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
+exports.fromBase64 = fromBase64;

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromBase64 = exports.toBase64 = exports.ActionCableProvider = exports.MessageType = exports.YProtocolSession = exports.ReliableSync = void 0;
+// Zero-dependency reliable-delivery core. Safe to import on its own.
+var reliable_sync_js_1 = require("./reliable_sync.js");
+Object.defineProperty(exports, "ReliableSync", { enumerable: true, get: function () { return reliable_sync_js_1.ReliableSync; } });
+// Protocol session (sync steps + encode/decode + awareness).
+// Requires `yjs` and `y-protocols` as peers.
+var y_protocol_session_js_1 = require("./y_protocol_session.js");
+Object.defineProperty(exports, "YProtocolSession", { enumerable: true, get: function () { return y_protocol_session_js_1.YProtocolSession; } });
+Object.defineProperty(exports, "MessageType", { enumerable: true, get: function () { return y_protocol_session_js_1.MessageType; } });
+// ActionCable / AnyCable provider built on YProtocolSession.
+// Bring your own provider instead by composing YProtocolSession.
+var actioncable_provider_js_1 = require("./actioncable_provider.js");
+Object.defineProperty(exports, "ActionCableProvider", { enumerable: true, get: function () { return actioncable_provider_js_1.ActionCableProvider; } });
+// Optional base64 helpers for transports that carry frames as strings.
+var base64_js_1 = require("./base64.js");
+Object.defineProperty(exports, "toBase64", { enumerable: true, get: function () { return base64_js_1.toBase64; } });
+Object.defineProperty(exports, "fromBase64", { enumerable: true, get: function () { return base64_js_1.fromBase64; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/reliable_sync.js

@@ -0,0 +1,142 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReliableSync = void 0;
+const DEFAULTS = { resendInterval: 1000 };
+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;
+    }
+}
+exports.ReliableSync = ReliableSync;

package/dist/cjs/y_protocol_session.js

@@ -0,0 +1,252 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YProtocolSession = exports.MessageType = void 0;
+// 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.
+const yjs_1 = require("yjs");
+const encoding = __importStar(require("lib0/encoding"));
+const decoding = __importStar(require("lib0/decoding"));
+const sync_1 = require("y-protocols/sync");
+const awareness_1 = require("y-protocols/awareness");
+const reliable_sync_js_1 = require("./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.
+exports.MessageType = { Sync: 0, Awareness: 1 };
+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 reliable_sync_js_1.ReliableSync({
+            merge: yjs_1.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)
+                (0, awareness_1.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) {
+        (0, yjs_1.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 exports.MessageType.Sync: {
+                    encoding.writeVarUint(encoder, exports.MessageType.Sync);
+                    const syncType = (0, sync_1.readSyncMessage)(decoder, encoder, this.doc, this);
+                    if (!this.#synced && syncType === sync_1.messageYjsSyncStep2)
+                        this.#synced = true;
+                    break;
+                }
+                case exports.MessageType.Awareness:
+                    if (this.awareness)
+                        (0, awareness_1.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, exports.MessageType.Sync);
+        (0, sync_1.writeSyncStep1)(e, this.doc);
+        return encoding.toUint8Array(e);
+    }
+    #frameUpdate(update) {
+        const e = encoding.createEncoder();
+        encoding.writeVarUint(e, exports.MessageType.Sync);
+        (0, sync_1.writeUpdate)(e, update);
+        return encoding.toUint8Array(e);
+    }
+    #frameAwareness(clients) {
+        const e = encoding.createEncoder();
+        encoding.writeVarUint(e, exports.MessageType.Awareness);
+        encoding.writeVarUint8Array(e, (0, awareness_1.encodeAwarenessUpdate)(this.awareness, clients));
+        return encoding.toUint8Array(e);
+    }
+    #validateFrame(frame) {
+        const decoder = decoding.createDecoder(frame);
+        const type = decoding.readVarUint(decoder);
+        switch (type) {
+            case exports.MessageType.Sync: {
+                const scratchDoc = new yjs_1.Doc();
+                try {
+                    const scratchEncoder = encoding.createEncoder();
+                    encoding.writeVarUint(scratchEncoder, exports.MessageType.Sync);
+                    (0, sync_1.readSyncMessage)(decoder, scratchEncoder, scratchDoc, this);
+                }
+                finally {
+                    scratchDoc.destroy();
+                }
+                break;
+            }
+            case exports.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;
+    }
+}
+exports.YProtocolSession = YProtocolSession;

package/package.json

@@ -1,23 +1,26 @@
 {
   "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.",
+  "version": "0.4.1",
+  "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; ESM + CommonJS, usable from plain JS.",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
     },
     "./reliable": {
       "types": "./dist/reliable_sync.d.ts",
-      "default": "./dist/reliable_sync.js"
+      "import": "./dist/reliable_sync.js",
+      "require": "./dist/cjs/reliable_sync.js"
     },
     "./base64": {
       "types": "./dist/base64.d.ts",
-      "default": "./dist/base64.js"
+      "import": "./dist/base64.js",
+      "require": "./dist/cjs/base64.js"
     }
   },
   "files": [
@@ -26,7 +29,7 @@
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && tsc",
+    "build": "npm run clean && tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }) + '\\n')\"",
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build",
     "test": "npm run build && node --test"