yrby-client 0.5.0 → 0.6.0

package/dist/cjs/actioncable_provider.js

@@ -12,8 +12,8 @@ exports.ActionCableProvider = void 0;
 // 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. Editors that must not bind before the first sync
+// call `connect()`. Watch the connection with `onStatusChange(({ status, pending }) => ...)`
+// or the `status` and `hasPending` getters. Editors that must not bind before the first sync
 // can `await provider.whenSynced` after connect(). 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.
@@ -27,68 +27,58 @@ class ActionCableProvider {
     channelParams;
     awareness;
     session;
-    #subscription = null;
+    #state = { phase: "disconnected" };
     #onError;
-    #connected = false;
-    #status = "disconnected";
+    // The last event sent to listeners. A refresh notifies them only when a field differs.
+    #last = { status: "disconnected", pending: false };
     #statusListeners = new Set();
-    #whenSynced = null;
-    // `session.synced` resets on every transport drop (a reconnect
-    // re-handshakes). Whether the first catch-up has ever happened is tracked
-    // separately here, so `whenSynced` does not depend on when it is first
-    // read.
-    #everSynced = false;
-    #onUnload = null;
-    #onRestore = null;
-    #stashedPresence = null;
+    #resolveSynced;
+    #onDocUpdate = () => this.#refreshStatus(); // a local edit may have made the queue non-empty
+    #page = null;
+    /**
+     * Resolves once the document has first caught up with the server. Most
+     * editor bindings seed an empty document when they mount, so binding
+     * before the server's state arrives makes each client insert its own
+     * top-level node. Create the editor after this resolves:
+     *
+     *   provider.connect();
+     *   await provider.whenSynced;
+     *   // now hand the doc to the editor binding
+     *
+     * It resolves on the first catch-up and remains resolved across later
+     * reconnects, even while `synced` is false during a re-handshake. Use
+     * `onStatusChange` to track the live connection. If the provider is
+     * destroyed before the first sync, it never resolves.
+     */
+    whenSynced = new Promise((resolve) => { this.#resolveSynced = resolve; });
     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));
+        const onError = opts.onError ?? ((error, context) => console.warn(`[yrby] ${context}:`, error));
+        this.#onError = (error, context) => {
+            try {
+                onError(error, context);
+            }
+            catch (callbackError) {
+                console.warn("[yrby] onError callback failed:", callbackError, "while reporting:", error);
+            }
+        };
+        this.awareness = new ProviderAwareness(doc, this.#onError);
         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),
         });
+        // Registered after the session's listener, so the queue already has the edit.
+        this.doc.on("update", this.#onDocUpdate);
     }
     /** True once the document has caught up with the server (received a SyncStep2). */
     get synced() {
         return this.session.synced;
     }
-    /**
-     * Resolves once the document has first caught up with the server. Most
-     * editor bindings seed an empty document when they mount, so binding
-     * before the server's state arrives makes each client insert its own
-     * top-level node. Create the editor after this resolves:
-     *
-     *   provider.connect();
-     *   await provider.whenSynced;
-     *   // now hand the doc to the editor binding
-     *
-     * Resolves immediately if the first catch-up has already happened, even
-     * while the transport is down (`synced` is false during a reconnect;
-     * whether the doc has ever synced does not change). It stays resolved
-     * across later reconnects; use `onStatusChange` to track the live
-     * connection. If the provider is destroyed before the first sync, the
-     * promise never settles.
-     */
-    get whenSynced() {
-        this.#whenSynced ??= this.#everSynced
-            ? Promise.resolve()
-            : new Promise((resolve) => {
-                const off = this.onStatusChange(({ status }) => {
-                    if (status !== "synced")
-                        return;
-                    off();
-                    resolve();
-                });
-            });
-        return this.#whenSynced;
-    }
     /** True while there are unacknowledged local document updates in flight. */
     get hasPending() {
         return this.session.hasPending;
@@ -110,7 +100,7 @@ class ActionCableProvider {
     }
     /** Current connection status. See {@link ProviderStatus}. */
     get status() {
-        return this.#status;
+        return this.#computeStatus();
     }
     /** Subscribe to status changes. Returns an unsubscribe function. */
     onStatusChange(listener) {
@@ -118,171 +108,289 @@ class ActionCableProvider {
         return () => this.#statusListeners.delete(listener);
     }
     connect() {
-        if (this.#subscription)
+        if (this.#destroying())
+            throw new Error("provider is destroyed");
+        if (this.#state.phase !== "disconnected")
             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)
-            },
-            rejected() {
-                // The channel refused the subscription (auth, missing doc). Surface
-                // it and tear down — otherwise the provider sits at "connecting"
-                // forever, silently queueing edits. The app decides what's next.
-                provider.#onError(new Error("subscription rejected by the server"), "rejected");
-                provider.disconnect();
-            },
-        });
-        this.#installUnloadHandler();
-        this.#refreshStatus(); // -> "connecting"
-    }
-    disconnect() {
-        if (!this.#subscription)
+        const attempt = {};
+        this.#state = { phase: "subscribing", attempt };
+        // A consumer may invoke callbacks inside create(), before the subscription
+        // is installed, so on() defers those by one microtask.
+        const on = (callback) => (...args) => {
+            const run = () => { if (this.#active(attempt))
+                callback(...args); };
+            if (this.#state.phase === "subscribing")
+                queueMicrotask(run);
+            else
+                run();
+        };
+        let subscription;
+        try {
+            subscription = this.consumer.subscriptions.create({ channel: this.channelName, ...this.channelParams }, {
+                received: on((message) => this.#receive(message, attempt)),
+                connected: on(() => this.#connected()),
+                disconnected: on(() => this.#lost()),
+                rejected: on(() => this.#stop("reject")),
+            });
+        }
+        catch (error) {
+            if (!this.#subscribing(attempt))
+                return;
+            this.#state = { phase: "disconnected" };
+            this.#refreshStatus();
+            throw error;
+        }
+        // disconnect() or destroy() ran inside create().
+        if (!this.#subscribing(attempt)) {
+            this.#unsubscribe(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();
-        // Universal teardown: both @rails/actioncable and @anycable/web subscriptions
-        // expose unsubscribe() (Rails' just calls consumer.subscriptions.remove(this)
-        // internally). @anycable has NO consumer.subscriptions.remove, so calling that
-        // would throw there.
-        queueMicrotask(() => sub.unsubscribe?.());
-        this.#refreshStatus(); // -> "disconnected"
+        }
+        this.#state = { phase: "connecting", attempt, subscription };
+        this.#watchPage();
+        this.#refreshStatus();
     }
-    destroy() {
+    disconnect() { this.#stop("disconnect"); }
+    /**
+     * Resubscribes with updated channel params, such as a renewed grant. This
+     * replaces only the cable subscription and keeps the doc, the delivery
+     * queue, awareness, and this provider's ack route. Does nothing after
+     * destroy().
+     */
+    renew(params) {
+        if (this.#destroying())
+            return;
+        Object.assign(this.channelParams, params);
         this.disconnect();
-        this.session.destroy();
-        this.awareness.destroy(); // stops its reaper timer
-        this.#statusListeners.clear();
+        this.connect();
     }
-    #computeStatus() {
-        if (!this.#subscription)
-            return "disconnected";
-        if (!this.#connected)
-            return "connecting";
-        return this.session.synced ? "synced" : "connected";
+    destroy() { this.#stop("destroy"); }
+    #destroying() {
+        const state = this.#state;
+        return state.phase === "destroyed" || (state.phase === "stopping" && state.reason === "destroy");
     }
-    #refreshStatus() {
-        const next = this.#computeStatus();
-        if (next === this.#status)
+    #subscribing(attempt) {
+        return this.#state.phase === "subscribing" && this.#state.attempt === attempt;
+    }
+    // Cable callbacks run only for a connecting or connected subscription.
+    #active(attempt) {
+        const state = this.#state;
+        return (state.phase === "connecting" || state.phase === "connected") && state.attempt === attempt;
+    }
+    // The cable callbacks below run only for the active attempt, which on() in
+    // connect() checks.
+    #connected() {
+        const state = this.#state;
+        if (state.phase !== "connecting")
+            return;
+        this.#state = { ...state, phase: "connected" };
+        this.session.resume();
+        this.#refreshStatus();
+    }
+    #lost() {
+        const state = this.#state;
+        if (state.phase !== "connecting" && state.phase !== "connected")
             return;
-        this.#status = next;
-        if (next === "synced")
-            this.#everSynced = true;
-        for (const listener of this.#statusListeners)
-            listener({ status: next });
+        this.#state = { ...state, phase: "connecting" };
+        this.session.pause();
+        this.#refreshStatus();
     }
-    // Presence teardown/restore around page lifecycle:
-    // - `pagehide`: remove local presence while the socket is still live so peers
-    //   drop our cursor now (bfcache-safe; the awareness timeout is the backstop).
-    // - `pageshow` with `persisted`: the user came BACK (bfcache restore), so put
-    //   their presence back — editors set awareness once at setup, so without
-    //   this they'd rejoin as a ghost with no cursor.
-    #installUnloadHandler() {
-        if (typeof window === "undefined" || this.#onUnload)
+    #stop(reason) {
+        const state = this.#state;
+        if (state.phase === "destroyed")
+            return;
+        if (state.phase === "stopping") {
+            if (reason === "destroy")
+                state.reason = reason;
             return;
-        this.#onUnload = () => {
-            this.#stashedPresence = this.awareness.getLocalState();
+        }
+        if (state.phase === "disconnected" && reason === "disconnect")
+            return;
+        let finalReason = reason;
+        if ("subscription" in state) {
+            const stopping = { ...state, phase: "stopping", reason };
+            this.#state = stopping;
+            this.#unwatchPage();
+            // From here the provider ignores the old subscription's callbacks, but the
+            // subscription can still send our presence removal before its deferred
+            // unsubscribe.
             this.session.removeLocalAwareness();
-        };
-        this.#onRestore = (event) => {
-            if (!event.persisted || !this.#stashedPresence)
+            this.session.pause();
+            this.#unsubscribe(state.subscription);
+            if (this.#state !== stopping)
                 return;
-            if (this.awareness.getLocalState() === null) {
-                this.awareness.setLocalState(this.#stashedPresence);
+            finalReason = stopping.reason; // a destroy() during those calls upgrades it
+        }
+        const destroyed = finalReason === "destroy";
+        this.#state = { phase: destroyed ? "destroyed" : "disconnected" };
+        if (destroyed)
+            this.#destroyOwned();
+        else if (finalReason === "reject")
+            this.#onError(new Error("subscription rejected by the server"), "rejected");
+        this.#refreshStatus();
+        if (destroyed)
+            this.#statusListeners.clear();
+    }
+    #destroyOwned() {
+        this.session.destroy();
+        this.awareness.destroy();
+        this.doc.off("update", this.#onDocUpdate);
+    }
+    #unsubscribe(subscription) {
+        queueMicrotask(() => {
+            try {
+                subscription.unsubscribe?.();
             }
-            this.#stashedPresence = null;
-        };
-        window.addEventListener("pagehide", this.#onUnload);
-        window.addEventListener("pageshow", this.#onRestore);
+            catch (error) {
+                this.#onError(error, "unsubscribe");
+            }
+        });
     }
-    #removeUnloadHandler() {
-        if (typeof window === "undefined")
+    #receive(message, attempt) {
+        if (message && message.ack !== undefined) {
+            this.session.acknowledge(message.ack);
+            this.#refreshStatus();
+            return;
+        }
+        const awarenessPayload = message && message.awareness;
+        const payload = message && (awarenessPayload ?? message.update);
+        if (typeof payload !== "string")
+            return;
+        let frame;
+        try {
+            frame = (0, base64_js_1.fromBase64)(payload);
+        }
+        catch (error) {
+            this.#onError(error, "received");
             return;
-        if (this.#onUnload) {
-            window.removeEventListener("pagehide", this.#onUnload);
-            this.#onUnload = null;
         }
-        if (this.#onRestore) {
-            window.removeEventListener("pageshow", this.#onRestore);
-            this.#onRestore = null;
+        if (awarenessPayload !== undefined && frame[0] !== y_protocol_session_js_1.MessageType.Awareness) {
+            this.#onError(new Error("awareness envelope carried a non-awareness frame"), "received");
+            return;
+        }
+        const reply = this.session.receive(frame);
+        // Applying the frame runs doc observers, which may have replaced the connection.
+        if (reply && this.#active(attempt))
+            this.#send(reply, undefined);
+        this.#refreshStatus();
+    }
+    #computeStatus() {
+        switch (this.#state.phase) {
+            case "subscribing":
+            case "connecting": return "connecting";
+            case "connected": return this.session.synced ? "synced" : "connected";
+            default: return "disconnected";
+        }
+    }
+    #refreshStatus() {
+        const status = this.#computeStatus();
+        const pending = this.hasPending;
+        if (status === this.#last.status && pending === this.#last.pending)
+            return;
+        const event = this.#last = { status, pending };
+        if (status === "synced")
+            this.#resolveSynced();
+        // A throwing listener is an application bug. Report it and continue so one
+        // bad listener can't stop the others or break the cable callback that
+        // triggered this refresh.
+        for (const listener of this.#statusListeners) {
+            if (this.#last !== event)
+                break; // a listener caused a newer transition
+            try {
+                listener({ status, pending });
+            }
+            catch (error) {
+                this.#onError(error, "listener");
+            }
         }
     }
+    // Handles presence across the page lifecycle. `pagehide` removes our cursor
+    // while the socket is still live, so peers drop it without waiting for the
+    // awareness timeout. A `pageshow` with `persisted` means the user came back
+    // through the bfcache, so we restore the cursor. Editor bindings set
+    // awareness only once at setup, so without this the user would return with
+    // no cursor.
+    #watchPage() {
+        if (typeof window === "undefined" || this.#page)
+            return;
+        let stashed = null;
+        const page = this.#page = {
+            hide: () => {
+                if (this.#page !== page)
+                    return;
+                stashed = this.awareness.getLocalState();
+                this.session.removeLocalAwareness();
+            },
+            show: (event) => {
+                if (this.#page !== page || !event.persisted || !stashed)
+                    return;
+                if (this.awareness.getLocalState() === null)
+                    this.awareness.setLocalState(stashed);
+                stashed = null;
+            },
+        };
+        window.addEventListener("pagehide", this.#page.hide);
+        window.addEventListener("pageshow", this.#page.show);
+    }
+    #unwatchPage() {
+        if (!this.#page || typeof window === "undefined")
+            return;
+        const page = this.#page;
+        this.#page = null;
+        window.removeEventListener("pagehide", page.hide);
+        window.removeEventListener("pageshow", page.show);
+    }
     // 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)
+        const state = this.#state;
+        if (!("subscription" in state))
             return;
-        const update = (0, base64_js_1.toBase64)(frame);
         const isAwareness = frame[0] === y_protocol_session_js_1.MessageType.Awareness;
+        if (state.phase === "stopping" && !isAwareness)
+            return;
+        const { subscription } = state;
+        const update = (0, base64_js_1.toBase64)(frame);
         // Route transport failures (sync throws, or @anycable/web's rejected
         // promises) to onError instead of letting them escape into update
         // handlers. A failed send is recoverable: reliable frames stay queued
-        // until acked, and awareness is best-effort anyway.
+        // until acked, and awareness is best-effort anyway. Failures from a
+        // subscription that has since been replaced go unreported.
+        const report = (error) => {
+            const current = this.#state;
+            if ("subscription" in current && current.subscription === subscription)
+                this.#onError(error, "send");
+        };
         try {
-            if (isAwareness && typeof sub.whisper === "function") {
-                this.#observe(sub.whisper({ awareness: update }));
-                return;
-            }
-            const payload = id === undefined ? { update } : { update, id };
-            this.#observe(sub.send(payload));
+            const result = isAwareness && typeof subscription.whisper === "function"
+                ? subscription.whisper({ awareness: update })
+                : subscription.send(id === undefined ? { update } : { update, id });
+            if (result instanceof Promise)
+                result.catch(report);
         }
         catch (error) {
-            this.#onError(error, "send");
+            report(error);
         }
     }
-    // Attach a rejection handler when a transport returns a promise, so failures
-    // surface via onError instead of as unhandled rejections.
-    #observe(result) {
-        if (result instanceof Promise) {
-            result.catch((error) => this.#onError(error, "send"));
+}
+exports.ActionCableProvider = ActionCableProvider;
+// Awareness runs application listeners during presence removal and destruction.
+// A failing listener must not interrupt either one or leave the awareness timer
+// running.
+class ProviderAwareness extends awareness_1.Awareness {
+    onError;
+    constructor(doc, onError) {
+        super(doc);
+        this.onError = onError;
+    }
+    emit(...args) {
+        try {
+            super.emit(...args);
+        }
+        catch (error) {
+            this.onError(error, `awareness:${args[0]}`);
         }
     }
 }
-exports.ActionCableProvider = ActionCableProvider;

package/dist/cjs/document_element.d.ts

@@ -0,0 +1,24 @@
+import { type CableConsumer } from "./actioncable_provider.js";
+import { type DocumentSession } from "./document_session.js";
+declare const Base: typeof HTMLElement;
+export declare class YrbyDocumentElement extends Base {
+    #private;
+    /** Set before adding elements to use another consumer, such as AnyCable's. */
+    static consumer: CableConsumer | Promise<CableConsumer> | undefined;
+    static observedAttributes: string[];
+    get session(): DocumentSession | undefined;
+    get doc(): DocumentSession["doc"] | undefined;
+    get provider(): DocumentSession["provider"] | undefined;
+    /** Resolves after the current attempt's first sync. If the attempt is abandoned, its promise never resolves. */
+    get whenSynced(): Promise<void>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+    /** @internal Called by the Turbo adapter when the page is live. A new render also retries a stalled document. */
+    activate(): void;
+    /** @internal Called by the Turbo adapter when the page is cached or previewed. */
+    deactivate(): void;
+    /** Releases the editor lease. The session keeps any unsaved work. */
+    destroy(): void;
+}
+export {};