yrby-client 0.4.3 → 0.6.0

package/dist/cjs/y_protocol_session.js

@@ -40,10 +40,10 @@ exports.YProtocolSession = exports.MessageType = void 0;
 // 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.
+// Call resume() when the transport connects, pause() when it drops,
+// acknowledge(id) on an { ack } envelope, and receive(frame) for an inbound
+// frame (it returns a reply to send, or null). The session sends local doc and
+// awareness edits from their "update" events.
 const yjs_1 = require("yjs");
 const encoding = __importStar(require("lib0/encoding"));
 const decoding = __importStar(require("lib0/decoding"));
@@ -58,12 +58,12 @@ class YProtocolSession {
     awareness;
     #send;
     #onError;
-    #synced = false;
+    #state = { phase: "unsynced", cycle: {} };
     #delivery;
     #onDocUpdate;
     #onAwarenessUpdate;
     constructor(doc, opts) {
-        const { send, awareness = null, resendInterval, onError, setInterval: setIntervalFn, clearInterval: clearIntervalFn, } = opts ?? {};
+        const { send, awareness = null, resendInterval, onError, setInterval: setTimer, clearInterval: clearTimer } = opts ?? {};
         if (!doc)
             throw new TypeError("YProtocolSession requires a Y.Doc");
         if (typeof send !== "function")
@@ -76,8 +76,8 @@ class YProtocolSession {
             merge: yjs_1.mergeUpdates,
             send: (update, id) => this.#send(this.#frameUpdate(update), id),
             resendInterval,
-            setInterval: setIntervalFn,
-            clearInterval: clearIntervalFn,
+            setInterval: setTimer,
+            clearInterval: clearTimer,
         });
         this.#onDocUpdate = (update, origin) => {
             if (origin === this)
@@ -88,10 +88,10 @@ class YProtocolSession {
         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;
+                // and our own remote-cleanup in pause(), carry origin === this;
                 // re-sending those would echo presence and broadcast tombstones for
                 // other clients' cursors.
-                if (origin === this)
+                if (origin === this || this.#state.phase === "destroyed")
                     return;
                 const changed = added.concat(updated, removed);
                 this.#send(this.#frameAwareness(changed), undefined); // fire-and-forget
@@ -101,26 +101,35 @@ class YProtocolSession {
     }
     /** True once we've received the server's SyncStep2 (the document is caught up). */
     get synced() {
-        return this.#synced;
+        return this.#state.phase === "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() {
+    /** Call when the transport is up. Sends the opening handshake, re-announces presence, and replays the unacked tail. */
+    resume() {
+        if (this.#state.phase === "destroyed")
+            return;
+        const cycle = {};
+        this.#state = { phase: "unsynced", cycle };
         this.#send(this.#frameSyncStep1(), undefined);
+        if (!this.#current(cycle))
+            return;
         if (this.awareness && this.awareness.getLocalState() !== null) {
             this.#send(this.#frameAwareness([this.doc.clientID]), undefined);
         }
-        this.#delivery.onConnect();
+        if (this.#current(cycle))
+            this.#delivery.resume();
     }
-    /** Transport dropped: pause retransmits (queue kept) and clear remote presence. */
-    onDisconnect() {
-        this.#synced = false;
-        this.#delivery.onDisconnect();
+    /** Call when the transport is down. Keeps the queue, stops retransmits, and clears peers' presence. */
+    pause() {
+        if (this.#state.phase === "destroyed")
+            return;
+        this.#state = { phase: "unsynced", cycle: {} };
+        this.#delivery.pause();
         if (this.awareness) {
-            const remote = [...this.awareness.getStates().keys()].filter((c) => c !== this.doc.clientID);
+            const remote = [...this.awareness.getStates().keys()].filter(c => c !== this.doc.clientID);
             if (remote.length)
                 (0, awareness_1.removeAwarenessStates)(this.awareness, remote, this);
         }
@@ -132,23 +141,13 @@ class YProtocolSession {
      * waiting for the awareness timeout. A no-op when there's no local state.
      */
     removeLocalAwareness() {
-        if (this.awareness && this.awareness.getLocalState() !== null) {
+        if (this.#state.phase !== "destroyed" && this.awareness && this.awareness.getLocalState() !== null) {
             this.awareness.setLocalState(null); // fires "update" -> sends the removal frame
         }
     }
-    /**
-     * A reliable-delivery `{ ack: id }` envelope arrived. `dropped` is set when
-     * the server settled the update WITHOUT recording it (rejected as an
-     * unhealable causal gap after repeated resyncs). The queue is pruned either
-     * way — retransmitting an unhealable update would loop forever — but a
-     * dropped settle is surfaced via onError ("ack-dropped") so the app can warn
-     * or reload instead of silently reporting synced over lost data.
-     */
-    ack(id, dropped = false) {
-        this.#delivery.onAck(id);
-        if (dropped) {
-            this.#onError(new Error(`server dropped update ${id} as an unhealable causal gap; it was settled but NOT recorded`), "ack-dropped");
-        }
+    /** A reliable-delivery `{ ack: id }` envelope arrived. */
+    acknowledge(id) {
+        this.#delivery.acknowledge(id);
     }
     /**
      * Apply an update without treating it as a local edit, so it isn't queued for
@@ -160,11 +159,12 @@ class YProtocolSession {
      * 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
+     * filter skips. Safe to call before `resume()`: the state folds into the
      * SyncStep1 handshake instead of being re-sent.
      */
     applyRemoteUpdate(update) {
-        (0, yjs_1.applyUpdate)(this.doc, update, this);
+        if (this.#state.phase !== "destroyed")
+            (0, yjs_1.applyUpdate)(this.doc, update, this);
     }
     /**
      * Decode and apply one incoming binary protocol frame (document sync or
@@ -172,21 +172,27 @@ class YProtocolSession {
      * SyncStep1), or null if there's nothing to send.
      */
     receive(frame) {
+        if (this.#state.phase === "destroyed")
+            return null;
+        const { cycle } = this.#state;
         // 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;
+            if (!validateFrame(frame))
+                return null; // a y-protocols type yrby doesn't use
             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;
+                    // y-protocols catches a failing update itself and reports it through this handler.
+                    const report = (error) => { if (this.#current(cycle))
+                        this.#onError(error, "receive"); };
+                    const syncType = (0, sync_1.readSyncMessage)(decoder, encoder, this.doc, this, report);
+                    if (syncType === sync_1.messageYjsSyncStep2 && this.#current(cycle)) {
+                        this.#state = { phase: "synced", cycle };
+                    }
                     break;
                 }
                 case exports.MessageType.Awareness:
@@ -194,22 +200,29 @@ class YProtocolSession {
                         (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 null; // unreachable, since validateFrame accepts only the two types above
             }
-            return encoding.length(encoder) > 1 ? encoding.toUint8Array(encoder) : null;
+            return this.#current(cycle) && encoding.length(encoder) > 1 ? encoding.toUint8Array(encoder) : null;
         }
         catch (error) {
-            this.#onError(error, "receive");
+            if (this.#current(cycle))
+                this.#onError(error, "receive");
             return null;
         }
     }
     /** Detach doc/awareness listeners and stop retransmits. */
     destroy() {
+        if (this.#state.phase === "destroyed")
+            return;
+        this.#state = { phase: "destroyed" };
         this.doc.off("update", this.#onDocUpdate);
         if (this.awareness && this.#onAwarenessUpdate)
             this.awareness.off("update", this.#onAwarenessUpdate);
         this.#delivery.destroy();
     }
+    #current(cycle) {
+        return this.#state.phase !== "destroyed" && this.#state.cycle === cycle;
+    }
     #frameSyncStep1() {
         const e = encoding.createEncoder();
         encoding.writeVarUint(e, exports.MessageType.Sync);
@@ -228,53 +241,45 @@ class YProtocolSession {
         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:
-                // Validate the payload's CONTENTS, not just the envelope.
-                // applyAwarenessUpdate mutates state entry by entry and only notifies
-                // listeners at the end — a bad entry mid-payload would leave earlier
-                // entries applied with no event fired. Dry-running every entry here
-                // makes the real apply infallible (and catches trailing garbage
-                // inside the blob).
-                {
-                    const payload = decoding.readVarUint8Array(decoder);
-                    const inner = decoding.createDecoder(payload);
-                    const count = decoding.readVarUint(inner);
-                    for (let i = 0; i < count; i++) {
-                        decoding.readVarUint(inner); // clientID
-                        decoding.readVarUint(inner); // clock
-                        JSON.parse(decoding.readVarString(inner)); // state (null on removal)
-                    }
-                    if (decoding.hasContent(inner)) {
-                        throw new Error("awareness payload has trailing bytes");
-                    }
-                }
-                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;
+// Checks a frame's structure before anything is applied, so a truncated or
+// padded frame changes nothing. Returns false for a frame type yrby ignores
+// (auth, query-awareness) and throws for a malformed one. Yjs checks the
+// contents of an update itself when applying it.
+function validateFrame(frame) {
+    const decoder = decoding.createDecoder(frame);
+    const type = decoding.readVarUint(decoder);
+    if (type === exports.MessageType.Sync) {
+        // Every sync message is a subtype followed by one length-prefixed payload.
+        decoding.readVarUint(decoder);
+        decoding.readVarUint8Array(decoder);
+    }
+    else if (type === exports.MessageType.Awareness) {
+        validateAwareness(decoding.readVarUint8Array(decoder));
+    }
+    else {
+        return false;
+    }
+    // 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).
+    if (decoding.hasContent(decoder))
+        throw new Error("frame has trailing bytes after a complete message");
+    return true;
+}
+// applyAwarenessUpdate mutates state entry by entry and notifies listeners
+// only at the end, so a bad entry mid-payload would leave earlier entries
+// applied with no event fired. Reading every entry first makes the real apply
+// infallible and catches trailing bytes inside the payload.
+function validateAwareness(payload) {
+    const decoder = decoding.createDecoder(payload);
+    const count = decoding.readVarUint(decoder);
+    for (let i = 0; i < count; i++) {
+        decoding.readVarUint(decoder); // clientID
+        decoding.readVarUint(decoder); // clock
+        JSON.parse(decoding.readVarString(decoder)); // state (null on removal)
+    }
+    if (decoding.hasContent(decoder))
+        throw new Error("awareness payload has trailing bytes");
+}

package/dist/document_element.d.ts

@@ -0,0 +1,25 @@
+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 {};
+//# sourceMappingURL=document_element.d.ts.map

package/dist/document_element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document_element.d.ts","sourceRoot":"","sources":["../src/document_element.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAI/B,QAAA,MAAM,IAAI,EAAoE,OAAO,WAAW,CAAC;AAkDjG,qBAAa,mBAAoB,SAAQ,IAAI;;IAC3C,8EAA8E;IAC9E,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC;IAGpE,MAAM,CAAC,kBAAkB,WAAgC;IAazD,IAAI,OAAO,IAAI,eAAe,GAAG,SAAS,CAIzC;IACD,IAAI,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,GAAG,SAAS,CAA8B;IAC3E,IAAI,QAAQ,IAAI,eAAe,CAAC,UAAU,CAAC,GAAG,SAAS,CAAmC;IAC1F,gHAAgH;IAChH,IAAI,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAoC;IAEnE,iBAAiB,IAAI,IAAI;IAQzB,oBAAoB,IAAI,IAAI;IAC5B,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAO/F,iHAAiH;IACjH,QAAQ,IAAI,IAAI;IAKhB,kFAAkF;IAClF,UAAU,IAAI,IAAI;IAIlB,qEAAqE;IACrE,OAAO,IAAI,IAAI;CA6HhB"}

package/dist/document_element.js

@@ -0,0 +1,225 @@
+var _a;
+import { DocumentSessionStore, documentKey, } from "./document_session.js";
+import { registerDocumentMount } from "./turbo_adapter.js";
+// Lets tests and SSR import this module where HTMLElement is undefined.
+const Base = (typeof HTMLElement === "undefined" ? class {
+} : HTMLElement);
+// Holds the application's own inert value while the element forces inert on.
+const INERT_ATTRIBUTE = "data-yrby-inert";
+let sharedConsumer;
+// Loads once per page. A failed import is cleared so a later attempt can retry it.
+function defaultConsumer() {
+    sharedConsumer ??= import("@rails/actioncable")
+        .then(actioncable => actioncable.createConsumer())
+        .catch(error => { sharedConsumer = undefined; throw error; });
+    return sharedConsumer;
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise(r => { resolve = r; });
+    return { promise, resolve };
+}
+// Returns the yrby:error detail for a session that ended a lease. A block gets
+// a detail, and a discard gets undefined.
+function blockReport(session) {
+    return session.state === "blocked" ? { error: session.error, session } : undefined;
+}
+// The element binds when it is in the page, the Turbo adapter reports the page
+// as live, and it has a descriptor. It abandons an attempt synchronously,
+// because Turbo copies the page as soon as before-cache fires, and after a
+// retarget the editor has to stop writing to the old document before anything
+// else runs. Starting and advancing an attempt and handling every async result
+// all go through #settle, which runs after the current call stack and compares
+// what should be bound with what is.
+export class YrbyDocumentElement extends Base {
+    /** Set before adding elements to use another consumer, such as AnyCable's. */
+    static consumer;
+    // refresh is read when the session is acquired and isn't part of the
+    // document's identity, so changing it doesn't rebind the editor.
+    static observedAttributes = ["grant", "name", "channel"];
+    #live = false; // false while Turbo is showing a cached copy of the page
+    #attempt;
+    // Key of the document whose session blocked or failed. The element won't retry
+    // it until the page renders again, the attributes change, or the element is
+    // re-inserted.
+    #stalledKey;
+    #unregister;
+    #settleQueued = false;
+    // Resolves when the current attempt first syncs. Abandoning the attempt replaces it.
+    #firstSync = deferred();
+    get session() {
+        // Treat a lease its session aborted as gone, even before settle runs.
+        const lease = this.#attempt?.lease;
+        return lease && !lease.signal.aborted ? lease.session : undefined;
+    }
+    get doc() { return this.session?.doc; }
+    get provider() { return this.session?.provider; }
+    /** Resolves after the current attempt's first sync. If the attempt is abandoned, its promise never resolves. */
+    get whenSynced() { return this.#firstSync.promise; }
+    connectedCallback() {
+        this.#stalledKey = undefined;
+        // A same-turn move keeps its attempt, so don't make a live editor inert.
+        if (!this.#attempt)
+            this.#holdInert();
+        this.#unregister ??= registerDocumentMount(this);
+        this.#requestSettle();
+    }
+    // Same-turn moves keep their binding, because settle checks isConnected afterwards.
+    disconnectedCallback() { this.#requestSettle(); }
+    attributeChangedCallback(_name, oldValue, newValue) {
+        if (oldValue === newValue)
+            return;
+        this.#stalledKey = undefined;
+        this.#abandon();
+        this.#requestSettle();
+    }
+    /** @internal Called by the Turbo adapter when the page is live. A new render also retries a stalled document. */
+    activate() {
+        this.#live = true;
+        this.#stalledKey = undefined;
+        this.#requestSettle();
+    }
+    /** @internal Called by the Turbo adapter when the page is cached or previewed. */
+    deactivate() {
+        this.#live = false;
+        this.#abandon();
+    }
+    /** Releases the editor lease. The session keeps any unsaved work. */
+    destroy() {
+        // Reset the adapter's last report. The next connection registers again and gets a new one.
+        this.#live = false;
+        // Clear it before the call, since the call can re-enter through a replacement registration.
+        const unregister = this.#unregister;
+        this.#unregister = undefined;
+        unregister?.();
+        this.#abandon();
+    }
+    #requestSettle() {
+        if (this.#settleQueued)
+            return;
+        this.#settleQueued = true;
+        queueMicrotask(() => this.#settle());
+    }
+    #settle() {
+        this.#settleQueued = false;
+        if (!this.isConnected) {
+            this.destroy();
+            return;
+        }
+        const descriptor = this.#descriptor();
+        // key is undefined when nothing should be bound, because the page is cached
+        // or the attributes don't name a document yet.
+        const key = this.#live && descriptor.grant && descriptor.name ? documentKey(descriptor) : undefined;
+        const attempt = this.#attempt;
+        if (attempt && attempt.key !== key) {
+            // Should not happen, since every change to these facts already abandons the attempt.
+            this.#abandon();
+            this.#requestSettle();
+            return;
+        }
+        if (key === undefined || key === this.#stalledKey)
+            return;
+        // Take the next step. An attempt starts, acquires a lease once the consumer
+        // loads, and announces once synced. If the attempt has ended, stall.
+        if (!attempt)
+            this.#start(key, descriptor);
+        else if (attempt.ended)
+            this.#stall(attempt.ended.detail);
+        else if (attempt.consumer && !attempt.lease)
+            this.#acquire(attempt, attempt.consumer);
+        else if (attempt.synced && !attempt.announced)
+            this.#announce(attempt);
+    }
+    #start(key, descriptor) {
+        const attempt = { key, descriptor };
+        this.#attempt = attempt;
+        Promise.resolve(_a.consumer ?? defaultConsumer()).then(consumer => { attempt.consumer = consumer; }, error => { attempt.ended = { detail: { error } }; }).then(() => this.#requestSettle());
+    }
+    #acquire(attempt, consumer) {
+        let lease;
+        try {
+            lease = DocumentSessionStore.for(consumer).acquire(attempt.descriptor);
+        }
+        catch (error) {
+            this.#stall({ error });
+            return;
+        }
+        attempt.lease = lease;
+        const { session } = lease;
+        // A blocked session keeps new leases for retry(), and its first sync may
+        // be long past, so an editor must not bind to it.
+        const blocked = blockReport(session);
+        if (blocked) {
+            attempt.ended = { detail: blocked };
+            this.#requestSettle();
+            return;
+        }
+        // The lease aborts when its session blocks or is discarded. Read the
+        // reason now, before anything retries the session.
+        lease.signal.addEventListener("abort", () => {
+            attempt.ended ??= { detail: blockReport(session) };
+            this.#requestSettle();
+        }, { once: true });
+        void session.whenSynced.then(() => {
+            attempt.synced = true;
+            this.#requestSettle();
+        });
+    }
+    #announce(attempt) {
+        attempt.announced = true;
+        const lease = attempt.lease;
+        const { session } = lease;
+        this.#restoreInert();
+        this.#firstSync.resolve();
+        this.dispatchEvent(new CustomEvent("yrby:synced", {
+            bubbles: true,
+            detail: { session, doc: session.doc, provider: session.provider, lease, signal: lease.signal },
+        }));
+    }
+    #stall(detail) {
+        this.#stalledKey = this.#attempt?.key;
+        this.#abandon();
+        if (detail)
+            this.dispatchEvent(new CustomEvent("yrby:error", { bubbles: true, detail }));
+    }
+    // Ends the current attempt. Releasing the lease runs editor cleanup, which
+    // may change attributes or move the element, and those changes only request
+    // a settle.
+    #abandon() {
+        const attempt = this.#attempt;
+        if (!attempt)
+            return;
+        this.#attempt = undefined;
+        this.#firstSync = deferred();
+        this.#holdInert();
+        attempt.lease?.release();
+    }
+    #descriptor() {
+        return {
+            channel: this.getAttribute("channel") || undefined,
+            grant: this.getAttribute("grant") || "",
+            name: this.getAttribute("name") || "",
+            refresh: this.getAttribute("refresh") || undefined,
+        };
+    }
+    // Stay inert until synced so nobody types into a document that isn't live yet.
+    // The application's own inert value goes in an attribute, which survives a
+    // Turbo cache clone, and is restored when the element is ready.
+    #holdInert() {
+        if (!this.hasAttribute(INERT_ATTRIBUTE))
+            this.setAttribute(INERT_ATTRIBUTE, String(this.inert));
+        this.inert = true;
+    }
+    #restoreInert() {
+        const saved = this.getAttribute(INERT_ATTRIBUTE);
+        if (saved === null)
+            return;
+        this.inert = saved === "true";
+        this.removeAttribute(INERT_ATTRIBUTE);
+    }
+}
+_a = YrbyDocumentElement;
+if (typeof customElements !== "undefined" && !customElements.get("yrby-document")) {
+    customElements.define("yrby-document", YrbyDocumentElement);
+}
+//# sourceMappingURL=document_element.js.map

package/dist/document_element.js.map

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

package/dist/document_session.d.ts

@@ -0,0 +1,63 @@
+import * as Y from "yjs";
+import { ActionCableProvider, type CableConsumer } from "./actioncable_provider.js";
+export interface DocumentDescriptor {
+    channel?: string;
+    grant: string;
+    name: string;
+    /** A same-origin URL that returns `{ "grant": "..." }` for this document. The session fetches it at most once per rejection. */
+    refresh?: string;
+}
+export type ResolvedDescriptor = Readonly<{
+    channel: string;
+    grant: string;
+    name: string;
+    refresh?: string;
+}>;
+export type DocumentSessionState = "open" | "blocked" | "closed";
+/** The identity of the document a descriptor names. Matching keys share a session. */
+export declare function documentKey(descriptor: DocumentDescriptor): string;
+declare const attachLease: unique symbol;
+declare const notifyStoreChange: unique symbol;
+/** Holds one consumer's sessions and emits "change" with the session in `detail`. */
+export declare class DocumentSessionStore extends EventTarget {
+    #private;
+    readonly consumer: CableConsumer;
+    static for(consumer: CableConsumer): DocumentSessionStore;
+    private constructor();
+    get sessions(): readonly DocumentSession[];
+    /** Acquire a lease on this document session, creating it on first use. */
+    acquire(input: DocumentDescriptor): DocumentLease;
+    [notifyStoreChange](session: DocumentSession): void;
+}
+/** A caller's hold on a session. Release it when you're done with the session. */
+export declare class DocumentLease {
+    #private;
+    readonly session: DocumentSession;
+    constructor(session: DocumentSession, onRelease: () => void);
+    /** Aborts when the lease ends, including when the session blocks or is discarded. */
+    get signal(): AbortSignal;
+    setPresence(state: Record<string, unknown> | null): void;
+    /** Runs editor cleanup synchronously, before the final check for pending work. */
+    release(): void;
+}
+export declare class DocumentSession {
+    #private;
+    readonly store: DocumentSessionStore;
+    readonly descriptor: ResolvedDescriptor;
+    private readonly remove;
+    readonly doc: Y.Doc;
+    readonly provider: ActionCableProvider;
+    /** Create and hold sessions through DocumentSessionStore.acquire. */
+    constructor(store: DocumentSessionStore, descriptor: ResolvedDescriptor, remove: () => void);
+    get error(): unknown;
+    get hasPending(): boolean;
+    get whenSynced(): Promise<void>;
+    get state(): DocumentSessionState;
+    [attachLease](): DocumentLease;
+    /** Reconnects with this session's current grant, which is the original one or the last one a refresh returned. */
+    retry(): void;
+    /** Closes the session and drops pending work. The application calls this explicitly, because an ordinary detach keeps pending work. */
+    discard(): void;
+}
+export {};
+//# sourceMappingURL=document_session.d.ts.map

package/dist/document_session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document_session.d.ts","sourceRoot":"","sources":["../src/document_session.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAuB,MAAM,2BAA2B,CAAC;AAEzG,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gIAAgI;IAChI,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAG9G,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AA8BjE,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAElE;AAKD,QAAA,MAAM,WAAW,eAAwB,CAAC;AAE1C,QAAA,MAAM,iBAAiB,eAA8B,CAAC;AAEtD,qFAAqF;AACrF,qBAAa,oBAAqB,SAAQ,WAAW;;IAO/B,QAAQ,CAAC,QAAQ,EAAE,aAAa;IANpD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,GAAG,oBAAoB;IAMzD,OAAO;IAIP,IAAI,QAAQ,IAAI,SAAS,eAAe,EAAE,CAAyC;IAEnF,0EAA0E;IAC1E,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa;IAkBjD,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;CAGpD;AAED,kFAAkF;AAClF,qBAAa,aAAa;;IAGZ,QAAQ,CAAC,OAAO,EAAE,eAAe;gBAAxB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI;IAGpE,qFAAqF;IACrF,IAAI,MAAM,IAAI,WAAW,CAAoC;IAC7D,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI;IAGxD,kFAAkF;IAClF,OAAO,IAAI,IAAI;CAKhB;AAOD,qBAAa,eAAe;;IAcxB,QAAQ,CAAC,KAAK,EAAE,oBAAoB;IACpC,QAAQ,CAAC,UAAU,EAAE,kBAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAfzB,QAAQ,CAAC,GAAG,QAAe;IAC3B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAUvC,qEAAqE;gBAE1D,KAAK,EAAE,oBAAoB,EAC3B,UAAU,EAAE,kBAAkB,EACtB,MAAM,EAAE,MAAM,IAAI;IAwBrC,IAAI,KAAK,IAAI,OAAO,CAAwB;IAC5C,IAAI,UAAU,IAAI,OAAO,CAAqC;IAC9D,IAAI,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAqC;IACpE,IAAI,KAAK,IAAI,oBAAoB,CAAgD;IAEjF,CAAC,WAAW,CAAC,IAAI,aAAa;IAa9B,kHAAkH;IAClH,KAAK,IAAI,IAAI;IAGb,uIAAuI;IACvI,OAAO,IAAI,IAAI;CA+EhB"}