@agent-native/core 0.221.0 → 0.221.1-nightly-20261028032829

package/dist/collab/client.js

@@ -113,10 +113,63 @@ const EMPTY_SNAPSHOT = Object.freeze({
     isLoading: false,
     isSynced: false,
     initialization: { status: "loading" },
+    durableUpdatesFailed: false,
+    updatesRefused: false,
     activeUsers: [],
     agentActive: false,
     agentPresent: false,
 });
+function readUpdateAck(body) {
+    if (!body || typeof body !== "object") {
+        throw new Error("The collab update response was not an object.");
+    }
+    const { liveCopy, liveCopyReason } = body;
+    if (liveCopy === undefined)
+        return { liveCopy: null };
+    if (liveCopy !== "derived" &&
+        liveCopy !== "not_derived" &&
+        liveCopy !== "unchanged") {
+        throw new Error(`Unknown live-copy outcome ${String(liveCopy)}.`);
+    }
+    return typeof liveCopyReason === "string"
+        ? { liveCopy, liveCopyReason }
+        : { liveCopy };
+}
+// Unacknowledged updates kept in localStorage, one entry per connection. Yjs
+// integrates an update once, so sending one the server already holds again
+// changes nothing.
+const OUTBOX_PREFIX = "agent-native-collab-outbox-v1:";
+const VERSIONED_OUTBOX_PREFIX = "agent-native-collab-outbox-v2:";
+const OUTBOX_ORIGIN = "collab-outbox";
+const OUTBOX_OWNER_LOCK_PREFIX = "agent-native-collab-outbox-owner:";
+function outboxPrefix(docKey, email, prefix = OUTBOX_PREFIX) {
+    return `${prefix}${encodeURIComponent(docKey)}:${encodeURIComponent(email)}:`;
+}
+function readStoredUpdates(entry, legacyRequireLiveCopyOutcome) {
+    if (entry.version === 1)
+        return [
+            {
+                update: base64ToUint8Array(entry.raw),
+                requireLiveCopyOutcome: legacyRequireLiveCopyOutcome,
+            },
+        ];
+    const body = JSON.parse(entry.raw);
+    if (body?.version !== 2 ||
+        !Array.isArray(body.updates) ||
+        body.updates.length === 0 ||
+        body.updates.length > 2)
+        throw new Error("The collab outbox has an unreadable update list.");
+    return body.updates.map((value) => {
+        const item = value;
+        if (typeof item?.update !== "string" ||
+            typeof item.requireLiveCopyOutcome !== "boolean")
+            throw new Error("The collab outbox has an unreadable update.");
+        return {
+            update: base64ToUint8Array(item.update),
+            requireLiveCopyOutcome: item.requireLiveCopyOutcome,
+        };
+    });
+}
 const requestSyncUnavailable = () => Promise.resolve({ status: "unavailable" });
 // Nothing is outstanding without a connection.
 const flushUpdatesUnavailable = () => Promise.resolve(true);
@@ -136,13 +189,27 @@ class CollabDocConnection {
     docMissing = false;
     requestSource;
     lastSetUser = null;
+    pageHidden = false;
+    presenceClear = null;
+    signedOut = false;
+    keepaliveSnapshots = new Set();
+    userGeneration = 0;
     pendingUpdates = [];
+    deliveredUpdates = new WeakSet();
+    strictDeliveryVersion = 0;
     flushTimer = null;
     updateInFlight = false;
-    keepaliveInFlight = false;
     updateErrors = 0;
+    updateBatchLimit = Infinity;
     updateAbortController = null;
     updateHandlerAttached = false;
+    keepsUnsentUpdates = false;
+    unsentUpdatesRestored = false;
+    onlineDuringUpdate = false;
+    releaseOutboxOwner = null;
+    outboxOwnerId = `${Date.now().toString(36)}-${Math.random()
+        .toString(36)
+        .slice(2)}`;
     syncActive = false;
     pollTimer = null;
     pollGeneration = 0;
@@ -176,6 +243,8 @@ class CollabDocConnection {
             isLoading: true,
             isSynced: false,
             initialization: { status: "loading" },
+            durableUpdatesFailed: false,
+            updatesRefused: false,
             activeUsers: [],
             agentActive: false,
             agentPresent: false,
@@ -188,7 +257,7 @@ class CollabDocConnection {
         return collabRegistryKey(this.docId, this.baseUrl, this.actorIdentity);
     }
     get retiredUpdatesKey() {
-        const email = this.lastSetUser?.email?.trim().toLowerCase();
+        const email = this.lastSetUser?.email.trim().toLowerCase();
         return email
             ? `${this.registryKey}\0${email}\0${this.requestSource ?? ""}`
             : null;
@@ -215,7 +284,7 @@ class CollabDocConnection {
             collabConnectionRegistry.set(nextKey, this);
         return true;
     }
-    add(id, sub) {
+    add(id, sub, user) {
         this.subscribers.set(id, sub);
         if (this.disposeTimer) {
             clearTimeout(this.disposeTimer);
@@ -225,6 +294,15 @@ class CollabDocConnection {
             this.requestSource = sub.requestSource;
             registerOwnCollabSource(sub.requestSource);
         }
+        if (user)
+            this.setUser(user);
+        // Once kept, updates stay kept until acknowledged, even if the caller
+        // stops asking.
+        if (sub.durableUpdates && !this.keepsUnsentUpdates) {
+            this.keepsUnsentUpdates = true;
+            this.storeUnsentUpdates();
+            this.restoreUnsentUpdates();
+        }
         if (!this.started) {
             this.started = true;
             this.start();
@@ -243,6 +321,10 @@ class CollabDocConnection {
     remove(id) {
         this.subscribers.delete(id);
         if (this.subscribers.size === 0) {
+            if (this.signedOut) {
+                this.dispose();
+                return;
+            }
             cancelAwarenessPush(this.baseUrl, this.docId, this.ydoc.clientID);
             // A lingering connection may outlive its document (a deleted Screen).
             this.stopSync();
@@ -287,14 +369,16 @@ class CollabDocConnection {
         }
         void this.flushPendingUpdates(true);
         this.detachUpdateHandler();
+        this.releaseOutboxOwner?.();
+        this.releaseOutboxOwner = null;
         if (this.agentTimer) {
             clearTimeout(this.agentTimer);
             this.agentTimer = null;
         }
         this.awareness.off("change", this.handleAwarenessChange);
-        cancelAwarenessPush(this.baseUrl, this.docId, this.ydoc.clientID);
-        if (this.awareness.getLocalState()) {
-            void postAwarenessState(this.baseUrl, this.docId, this.ydoc.clientID, null, true)
+        const clear = this.clearPresence();
+        if (clear) {
+            void clear
                 .catch(() => { })
                 .finally(() => {
                 forgetAwarenessClientSequence(this.baseUrl, this.docId, this.ydoc.clientID);
@@ -312,21 +396,35 @@ class CollabDocConnection {
     async clearPresenceBeforeSignOut() {
         if (this.disposed)
             return;
+        this.signedOut = true;
         this.stopSync();
-        cancelAwarenessPush(this.baseUrl, this.docId, this.ydoc.clientID);
-        if (!this.awareness.getLocalState())
-            return;
+        const clear = this.clearPresence();
         this.awareness.setLocalState(null);
-        try {
-            const response = await postAwarenessState(this.baseUrl, this.docId, this.ydoc.clientID, null, true);
-            if (!response.ok) {
-                throw new Error(`Awareness clear returned HTTP ${response.status}`);
-            }
+        if (collabConnectionRegistry.get(this.registryKey) === this) {
+            collabConnectionRegistry.delete(this.registryKey);
         }
-        finally {
-            forgetAwarenessClientSequence(this.baseUrl, this.docId, this.ydoc.clientID);
+        if (this.subscribers.size === 0)
+            this.dispose();
+        if (!clear)
+            return;
+        const response = await clear;
+        if (!response.ok) {
+            throw new Error(`Awareness clear returned HTTP ${response.status}`);
         }
     }
+    clearPresence() {
+        cancelAwarenessPush(this.baseUrl, this.docId, this.ydoc.clientID);
+        if (!this.presenceClear && this.awareness.getLocalState()) {
+            this.presenceClear = postAwarenessState(this.baseUrl, this.docId, this.ydoc.clientID, null, true);
+        }
+        return this.presenceClear;
+    }
+    get canPublishPresence() {
+        return (!this.disposed &&
+            !this.signedOut &&
+            !this.pageHidden &&
+            this.presenceClear === null);
+    }
     get effectivePollInterval() {
         let min = Infinity;
         for (const sub of this.subscribers.values()) {
@@ -356,6 +454,179 @@ class CollabDocConnection {
             sub.onSnapshot(this.snapshot);
         }
     }
+    get hasStrictSubscriber() {
+        return Array.from(this.subscribers.values()).some((sub) => sub.requireLiveCopyOutcome());
+    }
+    get outboxScope() {
+        const email = this.lastSetUser?.email.trim().toLowerCase();
+        if (!email || typeof window === "undefined")
+            return null;
+        const prefix = outboxPrefix(this.registryKey, email);
+        const versionedPrefix = outboxPrefix(this.registryKey, email, VERSIONED_OUTBOX_PREFIX);
+        return {
+            prefix,
+            key: prefix + this.outboxOwnerId,
+            versionedPrefix,
+            versionedKey: versionedPrefix + this.outboxOwnerId,
+        };
+    }
+    markDurableUpdatesFailed() {
+        if (!this.snapshot.durableUpdatesFailed) {
+            this.setSnapshot({ durableUpdatesFailed: true });
+        }
+    }
+    holdOutboxOwner(key) {
+        if (this.disposed || this.releaseOutboxOwner)
+            return;
+        const locks = typeof navigator === "undefined" ? undefined : navigator.locks;
+        if (typeof locks?.request !== "function") {
+            this.markDurableUpdatesFailed();
+            return;
+        }
+        // Queue the owner lock before publishing bytes an adopting tab can read.
+        const held = new Promise((release) => {
+            this.releaseOutboxOwner = release;
+        });
+        void locks
+            .request(OUTBOX_OWNER_LOCK_PREFIX + key, () => held)
+            .catch(() => {
+            if (!this.disposed)
+                this.markDurableUpdatesFailed();
+        });
+    }
+    storeUnsentUpdates() {
+        if (!this.keepsUnsentUpdates)
+            return;
+        const scope = this.outboxScope;
+        if (!scope)
+            return;
+        this.holdOutboxOwner(scope.key);
+        try {
+            if (this.pendingUpdates.length === 0) {
+                window.localStorage.removeItem(scope.key);
+                window.localStorage.removeItem(scope.versionedKey);
+            }
+            else {
+                const encode = (items) => uint8ArrayToBase64(Y.mergeUpdates(items.map((item) => item.update)));
+                const updates = [true, false].flatMap((requireLiveCopyOutcome) => {
+                    const items = this.pendingUpdates.filter((item) => item.requireLiveCopyOutcome === requireLiveCopyOutcome);
+                    return items.length
+                        ? [{ update: encode(items), requireLiveCopyOutcome }]
+                        : [];
+                });
+                // Older clients only understand v1's bare Yjs bytes and must not
+                // adopt or delete a versioned custody record.
+                window.localStorage.setItem(scope.versionedKey, JSON.stringify({ version: 2, updates }));
+                window.localStorage.removeItem(scope.key);
+            }
+        }
+        catch {
+            this.markDurableUpdatesFailed();
+        }
+    }
+    /**
+     * Sends what other connections for this doc and user kept: a tab that
+     * closed or reloaded before its updates were acknowledged. Applying them
+     * queues what the doc lacks as this connection's own unsent updates, which
+     * are kept before the other entry is removed. A live or frozen tab keeps
+     * its owner lock, so another connection leaves its entry untouched.
+     */
+    restoreUnsentUpdates() {
+        if (this.unsentUpdatesRestored ||
+            !this.keepsUnsentUpdates ||
+            !this.updateHandlerAttached ||
+            this.disposed) {
+            return;
+        }
+        const scope = this.outboxScope;
+        if (!scope)
+            return;
+        this.unsentUpdatesRestored = true;
+        const stored = [];
+        try {
+            const storage = window.localStorage;
+            for (let index = 0; index < storage.length; index += 1) {
+                const key = storage.key(index);
+                if (!key ||
+                    (!key.startsWith(scope.prefix) &&
+                        !key.startsWith(scope.versionedPrefix)) ||
+                    key === scope.key ||
+                    key === scope.versionedKey)
+                    continue;
+                const raw = storage.getItem(key);
+                if (raw !== null)
+                    stored.push({
+                        key,
+                        raw,
+                        version: key.startsWith(scope.versionedPrefix) ? 2 : 1,
+                    });
+            }
+        }
+        catch {
+            this.markDurableUpdatesFailed();
+            return;
+        }
+        const locks = typeof navigator === "undefined" ? undefined : navigator.locks;
+        if (typeof locks?.request !== "function") {
+            this.markDurableUpdatesFailed();
+            return;
+        }
+        for (const entry of stored) {
+            const ownerKey = entry.key.startsWith(scope.versionedPrefix)
+                ? scope.prefix + entry.key.slice(scope.versionedPrefix.length)
+                : entry.key;
+            void locks
+                .request(OUTBOX_OWNER_LOCK_PREFIX + ownerKey, { ifAvailable: true }, (lock) => {
+                if (!lock ||
+                    this.disposed ||
+                    this.outboxScope?.prefix !== scope.prefix)
+                    return;
+                try {
+                    const raw = window.localStorage.getItem(entry.key);
+                    if (raw !== null)
+                        this.adoptStoredOutbox({ ...entry, raw });
+                }
+                catch {
+                    this.markDurableUpdatesFailed();
+                }
+            })
+                .catch(() => {
+                if (!this.disposed)
+                    this.markDurableUpdatesFailed();
+            });
+        }
+    }
+    adoptStoredOutbox(entry) {
+        try {
+            for (const item of readStoredUpdates(entry, this.hasStrictSubscriber)) {
+                if (entry.version === 2 || item.requireLiveCopyOutcome) {
+                    Y.applyUpdate(this.ydoc, item.update, "remote");
+                    // Applying one custody group can integrate another's pending
+                    // dependencies without emitting a separate update event.
+                    this.enqueueUpdate(item.update, item.requireLiveCopyOutcome);
+                }
+                else {
+                    Y.applyUpdate(this.ydoc, item.update, OUTBOX_ORIGIN);
+                }
+            }
+            // Kept nowhere else while this connection cannot keep its own.
+            if (this.snapshot.durableUpdatesFailed)
+                return;
+        }
+        catch {
+            // An entry that cannot be applied never will be; it is reported,
+            // then removed so it is not reported on every open.
+            this.markDurableUpdatesFailed();
+        }
+        try {
+            if (window.localStorage.getItem(entry.key) === entry.raw) {
+                window.localStorage.removeItem(entry.key);
+            }
+        }
+        catch {
+            this.markDurableUpdatesFailed();
+        }
+    }
     markAgentActive() {
         this.setSnapshot({ agentActive: true });
         if (this.agentTimer)
@@ -371,6 +642,8 @@ class CollabDocConnection {
         if (!this.bindActorIdentity(user.email))
             return;
         const prev = this.lastSetUser;
+        if (prev?.email !== user.email)
+            this.userGeneration++;
         if (prev && prev.email !== user.email) {
             if (this.pendingUpdates.length && this.retiredUpdatesKey) {
                 retiredCollabUpdates.set(this.retiredUpdatesKey, this.pendingUpdates);
@@ -381,6 +654,12 @@ class CollabDocConnection {
                 clearTimeout(this.flushTimer);
             this.flushTimer = null;
             this.updateErrors = 0;
+            this.updateBatchLimit = Infinity;
+            if (this.snapshot.updatesRefused) {
+                this.setSnapshot({ updatesRefused: false });
+            }
+            // Kept updates are per account.
+            this.unsentUpdatesRestored = false;
         }
         if (prev &&
             prev.name === user.name &&
@@ -406,11 +685,13 @@ class CollabDocConnection {
             retiredCollabUpdates.delete(retiredKey);
             this.pendingUpdates.push(...retired);
             if (this.snapshot.initialization.status === "ready") {
-                for (const update of retired)
-                    Y.applyUpdate(this.ydoc, update, "remote");
+                for (const item of retired)
+                    Y.applyUpdate(this.ydoc, item.update, "remote");
                 void this.flushPendingUpdates();
             }
         }
+        this.storeUnsentUpdates();
+        this.restoreUnsentUpdates();
         this.awareness.setLocalStateField("user", {
             name: user.name,
             email: user.email,
@@ -449,7 +730,7 @@ class CollabDocConnection {
             this.snapshot.isSynced &&
             origin === "local" &&
             this.syncActive &&
-            !this.disposed) {
+            this.canPublishPresence) {
             scheduleAwarenessPush(this.baseUrl, this.docId, this.ydoc.clientID, () => this.awareness.getLocalState());
         }
     };
@@ -528,8 +809,8 @@ class CollabDocConnection {
                         validationDoc.destroy();
                     }
                     Y.applyUpdate(this.ydoc, binary, "remote");
-                    for (const update of this.pendingUpdates) {
-                        Y.applyUpdate(this.ydoc, update, "remote");
+                    for (const item of this.pendingUpdates) {
+                        Y.applyUpdate(this.ydoc, item.update, "remote");
                     }
                 }
                 catch {
@@ -543,6 +824,7 @@ class CollabDocConnection {
                 initialization: { status: "ready" },
             });
             this.startTransport();
+            this.restoreUnsentUpdates();
         }, () => {
             if (this.disposed)
                 return;
@@ -601,8 +883,13 @@ class CollabDocConnection {
                 clearTimeout(this.flushTimer);
                 this.flushTimer = null;
             }
+            const strictDeliveryVersion = this.strictDeliveryVersion;
             await this.flushPendingUpdates();
-            if (this.updateErrors > 0)
+            if (this.snapshot.updatesRefused)
+                return false;
+            if (this.updateErrors > 0 &&
+                (strictDeliveryVersion === this.strictDeliveryVersion ||
+                    !this.pendingUpdates.some((item) => !item.requireLiveCopyOutcome)))
                 return false;
         }
         return this.pendingUpdates.length === 0;
@@ -610,7 +897,11 @@ class CollabDocConnection {
     handleDocUpdate = (update, origin) => {
         if (origin === "remote")
             return;
-        this.pendingUpdates.push(update);
+        this.enqueueUpdate(update, this.hasStrictSubscriber);
+    };
+    enqueueUpdate(update, requireLiveCopyOutcome) {
+        this.pendingUpdates.push({ update, requireLiveCopyOutcome });
+        this.storeUnsentUpdates();
         if (this.updateErrors && this.flushTimer)
             return;
         if (this.flushTimer)
@@ -619,9 +910,35 @@ class CollabDocConnection {
             this.flushTimer = null;
             void this.flushPendingUpdates();
         }, UPDATE_DEBOUNCE_MS);
-    };
+    }
     handlePageHide = () => {
-        this.flushPendingUpdates(true);
+        void this.flushPendingUpdates(true);
+        this.pageHidden = true;
+        void this.clearPresence()?.catch(() => { });
+    };
+    handlePageShow = () => {
+        if (!this.pageHidden || this.disposed || this.signedOut)
+            return;
+        this.pageHidden = false;
+        // BFCache must retain the doc's sequence/token until it is retired.
+        this.presenceClear = null;
+        this.publishVisibility(!isDocumentHidden());
+        this.pollNow();
+    };
+    // A tab that comes back online sends what it kept without waiting out the
+    // retry backoff it built up while offline.
+    handleOnline = () => {
+        if (!this.keepsUnsentUpdates)
+            return;
+        if (this.updateInFlight) {
+            this.onlineDuringUpdate = true;
+            return;
+        }
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        void this.flushPendingUpdates();
     };
     attachUpdateHandler() {
         if (this.updateHandlerAttached || this.docMissing)
@@ -630,6 +947,8 @@ class CollabDocConnection {
         this.ydoc.on("update", this.handleDocUpdate);
         if (typeof window !== "undefined") {
             window.addEventListener("pagehide", this.handlePageHide);
+            window.addEventListener("online", this.handleOnline);
+            window.addEventListener("pageshow", this.handlePageShow);
         }
     }
     detachUpdateHandler() {
@@ -639,14 +958,16 @@ class CollabDocConnection {
         this.ydoc.off("update", this.handleDocUpdate);
         if (typeof window !== "undefined") {
             window.removeEventListener("pagehide", this.handlePageHide);
+            window.removeEventListener("online", this.handleOnline);
+            window.removeEventListener("pageshow", this.handlePageShow);
         }
     }
     async flushPendingUpdates(keepalive = false) {
-        if (keepalive
-            ? this.keepaliveInFlight
-            : this.disposed ||
-                this.updateInFlight ||
-                (this.updateErrors > 0 && this.flushTimer !== null))
+        if (this.snapshot.updatesRefused ||
+            (!keepalive &&
+                (this.disposed ||
+                    this.updateInFlight ||
+                    (this.updateErrors > 0 && this.flushTimer !== null))))
             return;
         if (this.flushTimer) {
             clearTimeout(this.flushTimer);
@@ -654,17 +975,35 @@ class CollabDocConnection {
         }
         if (this.pendingUpdates.length === 0)
             return;
-        const toSend = this.pendingUpdates.slice();
+        const ordinary = this.pendingUpdates.filter((item) => !item.requireLiveCopyOutcome);
+        // Ordinary successors may depend on retained strict bytes. Transport
+        // acceptance does not release those bytes' outcome custody.
+        const predecessors = ordinary.length
+            ? this.pendingUpdates.filter((item) => item.requireLiveCopyOutcome && !this.deliveredUpdates.has(item))
+            : [];
+        const toSend = (predecessors.length
+            ? predecessors
+            : ordinary.length
+                ? ordinary
+                : this.pendingUpdates).slice(0, this.updateBatchLimit);
+        if (keepalive &&
+            [...this.keepaliveSnapshots].some((snapshot) => toSend.every((item) => snapshot.includes(item))))
+            return;
+        if (keepalive)
+            this.keepaliveSnapshots.add(toSend);
         const retiredKey = this.retiredUpdatesKey;
-        const merged = toSend.length === 1 ? toSend[0] : Y.mergeUpdates(toSend);
+        const merged = Y.mergeUpdates(toSend.map((item) => item.update));
         const controller = new AbortController();
-        if (keepalive)
-            this.keepaliveInFlight = true;
-        else {
+        if (!keepalive) {
             this.updateInFlight = true;
             this.updateAbortController = controller;
         }
         const timeout = setTimeout(() => controller.abort(), STATE_VECTOR_FETCH_TIMEOUT_MS);
+        const userGeneration = this.userGeneration;
+        const requireLiveCopyOutcome = toSend.some((item) => item.requireLiveCopyOutcome);
+        const acknowledgedOwners = new Set();
+        const ordinaryReceiptOwners = Array.from(this.subscribers.values()).filter((sub) => !sub.requireLiveCopyOutcome());
+        let ack = null;
         try {
             const response = await fetch(`${this.baseUrl}/${this.docId}/update`, {
                 method: "POST",
@@ -676,8 +1015,56 @@ class CollabDocConnection {
                 signal: controller.signal,
                 ...(keepalive ? { keepalive: true } : {}),
             });
+            // The same bytes are refused again, so a refused batch is sent in
+            // halves, and a refused single update stops this tab's updates.
+            if (this.keepsUnsentUpdates && response.status === 413) {
+                if (userGeneration !== this.userGeneration)
+                    return;
+                if (!toSend.some((item) => this.pendingUpdates.includes(item) &&
+                    !this.deliveredUpdates.has(item)))
+                    return;
+                if (toSend.length > 1) {
+                    this.updateBatchLimit = Math.ceil(toSend.length / 2);
+                }
+                else {
+                    this.setSnapshot({ updatesRefused: true });
+                }
+                return;
+            }
             if (!response.ok)
                 throw new Error(`HTTP ${response.status}`);
+            if (userGeneration !== this.userGeneration)
+                return;
+            for (const item of toSend) {
+                if (!this.deliveredUpdates.has(item)) {
+                    this.deliveredUpdates.add(item);
+                    if (item.requireLiveCopyOutcome)
+                        this.strictDeliveryVersion++;
+                }
+            }
+            const parsedAck = requireLiveCopyOutcome ||
+                Array.from(this.subscribers.values()).some((sub) => sub.onUpdateAcknowledged !== undefined && sub.canAcknowledge())
+                ? readUpdateAck(await response.json())
+                : null;
+            if (userGeneration !== this.userGeneration)
+                return;
+            if (requireLiveCopyOutcome) {
+                if (!parsedAck?.liveCopy)
+                    throw new Error("The collab update response omitted its live-copy outcome.");
+                for (const sub of this.subscribers.values()) {
+                    if (this.disposed || userGeneration !== this.userGeneration)
+                        break;
+                    if (sub.requireLiveCopyOutcome() &&
+                        sub.canAcknowledge() &&
+                        sub.onUpdateAcknowledged) {
+                        sub.onUpdateAcknowledged(parsedAck);
+                        acknowledgedOwners.add(sub);
+                    }
+                }
+                if (acknowledgedOwners.size === 0)
+                    throw new Error("The live-copy acknowledgment has no current strict subscriber.");
+            }
+            ack = parsedAck;
             const previous = this.pendingUpdates;
             const acknowledged = new Set(toSend);
             this.pendingUpdates = previous.filter((update) => !acknowledged.has(update));
@@ -693,31 +1080,60 @@ class CollabDocConnection {
                     retiredCollabUpdates.delete(retiredKey);
                 }
             }
+            this.storeUnsentUpdates();
             this.updateErrors = 0;
+            if (this.pendingUpdates.length === 0)
+                this.updateBatchLimit = Infinity;
         }
         catch {
-            this.updateErrors++;
+            if (userGeneration === this.userGeneration)
+                this.updateErrors++;
         }
         finally {
-            clearTimeout(timeout);
             if (keepalive)
-                this.keepaliveInFlight = false;
-            else {
+                this.keepaliveSnapshots.delete(toSend);
+            clearTimeout(timeout);
+            let online = false;
+            if (!keepalive) {
                 this.updateInFlight = false;
                 this.updateAbortController = null;
+                online = this.onlineDuringUpdate;
+                this.onlineDuringUpdate = false;
             }
-            if (!this.disposed && this.pendingUpdates.length && !this.flushTimer) {
-                this.flushTimer = setTimeout(() => {
-                    this.flushTimer = null;
-                    void this.flushPendingUpdates();
-                }, this.updateErrors
-                    ? calcBackoff(this.updateErrors)
-                    : UPDATE_DEBOUNCE_MS);
+            this.schedulePendingFlush(online);
+        }
+        // Ordinary receipts keep nullable-ACK compatibility. Strict owners have
+        // already handled their outcome before its pending bytes were removed.
+        if (ack && !this.disposed && userGeneration === this.userGeneration) {
+            const receiptOwners = [
+                ...ordinaryReceiptOwners.filter((sub) => !sub.requireLiveCopyOutcome()),
+                ...Array.from(this.subscribers.values()).filter((sub) => sub.requireLiveCopyOutcome()),
+            ];
+            for (const sub of receiptOwners) {
+                if (userGeneration === this.userGeneration &&
+                    !acknowledgedOwners.has(sub) &&
+                    sub.canAcknowledge() &&
+                    (!sub.requireLiveCopyOutcome() || ack.liveCopy !== null))
+                    sub.onUpdateAcknowledged?.(ack);
             }
         }
     }
+    schedulePendingFlush(online) {
+        if (this.disposed ||
+            this.snapshot.updatesRefused ||
+            this.pendingUpdates.length === 0 ||
+            this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flushPendingUpdates();
+        }, this.updateErrors && !online
+            ? calcBackoff(this.updateErrors)
+            : UPDATE_DEBOUNCE_MS);
+    }
     startSync() {
         if (this.syncActive ||
+            this.signedOut ||
             this.docMissing ||
             this.disposed ||
             this.subscribers.size === 0) {
@@ -1008,7 +1424,9 @@ class CollabDocConnection {
             if (!this.isPollCurrent(generation))
                 return;
             const localState = this.awareness.getLocalState();
-            if (localState && this.isPollCurrent(generation)) {
+            if (localState &&
+                this.canPublishPresence &&
+                this.isPollCurrent(generation)) {
                 try {
                     const awarenessRes = await postAwarenessState(this.baseUrl, this.docId, this.ydoc.clientID, localState);
                     if (!this.isPollCurrent(generation))
@@ -1070,6 +1488,8 @@ class CollabDocConnection {
         void this.poll(this.pollGeneration);
     }
     publishVisibility(visible) {
+        if (!this.canPublishPresence || !this.awareness.getLocalState())
+            return;
         this.awareness.setLocalStateField("visible", visible);
         const localState = this.awareness.getLocalState();
         if (!localState)
@@ -1121,8 +1541,8 @@ class CollabDocConnection {
     }
 }
 const collabConnectionRegistry = new Map();
-// ponytail: in-memory retention survives component remounts; use a durable
-// outbox if offline reload recovery becomes supported. No retired retry loop.
+// In-memory retention survives component remounts; a connection with durable
+// updates also keeps them in localStorage. No retired retry loop.
 const retiredCollabUpdates = new Map();
 registerBeforeSignOutCleanup(async () => {
     const results = await Promise.allSettled(Array.from(new Set(collabConnectionRegistry.values()), (connection) => connection.clearPresenceBeforeSignOut()));
@@ -1167,7 +1587,12 @@ export function _collabDocRegistrySizeForTests() {
     return collabConnectionRegistry.size;
 }
 export function useCollaborativeDoc(options) {
-    const { docId, pollInterval = 2000, pollIntervalWithSse = 12000, pauseWhenHidden = true, baseUrl = agentNativePath("/_agent-native/collab"), requestSource, user, activityResource, onEvent, } = options;
+    const { docId, pollInterval = 2000, pollIntervalWithSse = 12000, pauseWhenHidden = true, baseUrl = agentNativePath("/_agent-native/collab"), requestSource, user, activityResource, durableUpdates = false, requireLiveCopyOutcome = false, onUpdateAcknowledged, onEvent, } = options;
+    const onUpdateAcknowledgedRef = useRef(onUpdateAcknowledged);
+    onUpdateAcknowledgedRef.current = onUpdateAcknowledged;
+    const requireLiveCopyOutcomeRef = useRef(requireLiveCopyOutcome);
+    requireLiveCopyOutcomeRef.current = requireLiveCopyOutcome;
+    const wantsAcks = onUpdateAcknowledged !== undefined;
     const onEventRef = useRef(onEvent);
     onEventRef.current = onEvent;
     useEffect(() => {
@@ -1199,6 +1624,9 @@ export function useCollaborativeDoc(options) {
         return getOrCreateCollabConnection(docId, baseUrl, actorIdentity);
     }, [docId, baseUrl, actorIdentity, generation, signedOutAfterAuthentication]);
     const previousActorConnection = useRef({ actorIdentity, conn });
+    const acknowledgementScope = useMemo(() => ({ conn, email: resolvedUser?.email }), [conn, resolvedUser?.email]);
+    const activeAcknowledgementScope = useRef(acknowledgementScope);
+    activeAcknowledgementScope.current = acknowledgementScope;
     const [snapshot, setSnapshot] = useState(() => conn ? conn.snapshot : EMPTY_SNAPSHOT);
     const [prevConn, setPrevConn] = useState(conn);
     if (prevConn !== conn) {
@@ -1217,15 +1645,38 @@ export function useCollaborativeDoc(options) {
             pollInterval,
             pollIntervalWithSse,
             pauseWhenHidden,
-            requestSource,
+            ...(requestSource !== undefined ? { requestSource } : {}),
+            durableUpdates,
+            requireLiveCopyOutcome: () => activeAcknowledgementScope.current === acknowledgementScope &&
+                requireLiveCopyOutcomeRef.current,
+            canAcknowledge: () => activeAcknowledgementScope.current === acknowledgementScope &&
+                onUpdateAcknowledgedRef.current !== undefined,
+            ...(wantsAcks
+                ? {
+                    onUpdateAcknowledged: (ack) => {
+                        if (activeAcknowledgementScope.current === acknowledgementScope)
+                            onUpdateAcknowledgedRef.current?.(ack);
+                    },
+                }
+                : {}),
             onSnapshot: setSnapshot,
             onEvent: (event) => onEventRef.current?.(event),
-        });
+        }, resolvedUser);
         setSnapshot(conn.snapshot);
         return () => {
             conn.remove(id);
         };
-    }, [conn, pollInterval, pollIntervalWithSse, pauseWhenHidden, requestSource]);
+    }, [
+        conn,
+        pollInterval,
+        pollIntervalWithSse,
+        pauseWhenHidden,
+        requestSource,
+        durableUpdates,
+        requireLiveCopyOutcome,
+        wantsAcks,
+        wantsAcks ? acknowledgementScope : null,
+    ]);
     useEffect(() => {
         if (!conn || conn.detached || !resolvedUser)
             return;
@@ -1259,6 +1710,8 @@ export function useCollaborativeDoc(options) {
             : () => { },
         requestSync: conn ? conn.requestSync : requestSyncUnavailable,
         flushUpdates: conn ? conn.flushUpdates : flushUpdatesUnavailable,
+        durableUpdatesFailed: snapshot.durableUpdatesFailed,
+        updatesRefused: snapshot.updatesRefused,
         activeUsers: snapshot.activeUsers,
         agentActive: snapshot.agentActive,
         agentPresent: snapshot.agentPresent,