@oxvo/ai-live-assist 7.5.0 → 7.5.6

package/cjs/AiLiveAssist.d.ts

@@ -34,7 +34,7 @@ export declare const normalizeAiGuideOpenInput: (input?: AiGuideOpenInput) => Re
 export declare const resolveAiGuideProtocolVersion: (bootstrap: Pick<BootstrapConfig, "experienceMode" | "minimumProtocolVersion" | "protocol">) => 1 | 2;
 export default class AiLiveAssist {
     private readonly options;
-    readonly version = "7.5.0";
+    readonly version = "7.5.6";
     private readonly host;
     private readonly guideAdmission;
     private readonly standaloneAdmissionPending;
@@ -627,6 +627,7 @@ export default class AiLiveAssist {
     private submitFeedback;
     private retry;
     private scheduleReconnect;
+    private canRecoverControlTransport;
     private reconnectPendingHandoffControlInMemory;
     private reconnectMessengerTerminalControl;
     private clearReconnectTimer;

package/cjs/AiLiveAssist.js

@@ -7945,7 +7945,28 @@ class AiLiveAssist {
             ? this.navigationConsentResetReady
             : null;
         const resumeRecordAtConnect = this.readResume();
-        const channel = new control_js_1.ControlChannel(result, this.tabId, version_js_1.VERSION, () => this.scheduleReconnect(true), this.readResume()?.clientSequence ?? 0, (sequence) => this.updateResumeSequence(sequence), () => this.handleControlSequenceGap());
+        let recoveryPath = null;
+        const channel = new control_js_1.ControlChannel(result, this.tabId, version_js_1.VERSION, () => this.scheduleReconnect(true), this.readResume()?.clientSequence ?? 0, (sequence) => this.updateResumeSequence(sequence), () => this.handleControlSequenceGap(), {
+            canRecover: () => {
+                const currentPath = path();
+                if (!this.canRecoverControlTransport(channel, result, media) ||
+                    (recoveryPath !== null && recoveryPath !== currentPath))
+                    return false;
+                recoveryPath = currentPath;
+                return true;
+            },
+            onRecovered: async () => {
+                assertCurrent();
+                const fencingToken = channel.leaseToken;
+                channel.startHeartbeat(this.heartbeatSeconds);
+                await this.replayPreFenceAuthorityEnvelopes(channel, fencingToken, assertCurrent);
+                assertCurrent();
+                await this.context?.captureAndPublish();
+                assertCurrent();
+                this.flushPlaybackState();
+                this.reapplyConservativePreFencePresence(channel, fencingToken);
+            },
+        });
         const pauseHelloStateSignal = deferredSignal();
         (this.pauseHelloStateSignals ?? (this.pauseHelloStateSignals = new WeakMap())).set(channel, pauseHelloStateSignal);
         this.handoffContextPromptReceiptChannel = null;
@@ -8315,7 +8336,7 @@ class AiLiveAssist {
             this.context === context;
         context = new context_js_1.PageContextCollector({
             onSnapshot: (snapshot) => {
-                if (isCurrent() && this.channel?.leaseToken) {
+                if (isCurrent() && this.channel?.hasFencedAuthority) {
                     this.send("context.snapshot", snapshot);
                 }
             },
@@ -9674,7 +9695,15 @@ class AiLiveAssist {
             this.activePageAssistanceAuthorityEpoch === null &&
             this.activeActionAuthorityEpoch === null;
         if (!exactApplied || !localAuthorityInactive) {
-            this.invalidatePageAssistanceAuthority(false);
+            // A resumed document still owes the original action's terminal result.
+            // Preserve only its grantless outbox, never browser-control authority.
+            // Delivery remains fenced by the server's exact already_started receipt.
+            const preserveNavigationResult = source === "navigation_resume" &&
+                this.awaitingNavigationConsentReset &&
+                structurallyValid &&
+                localAuthorityInactive &&
+                this.pendingNavigationActionResult?.grant === null;
+            this.invalidatePageAssistanceAuthority(false, preserveNavigationResult);
         }
         if (!structurallyValid ||
             identity.authorityEpoch < this.minimumPageAssistanceAuthorityEpoch) {
@@ -11997,15 +12026,19 @@ class AiLiveAssist {
                 // intentionally result-less until navigation settles, preserving the
                 // cross-document recovery contract if this click unloads the page.
                 pendingExecution.result = deliveryResult;
+                let navigationReleased = false;
                 try {
-                    if (await this.navigateTo(deferredNavigation)) {
-                        return deliveryResult;
-                    }
-                    deliveryResult = this.markDeferredNavigationUnconfirmed(pendingExecution, context.currentRevision);
+                    navigationReleased = await this.navigateTo(deferredNavigation);
                 }
                 catch {
-                    deliveryResult = this.markDeferredNavigationUnconfirmed(pendingExecution, context.currentRevision);
+                    // A rejected router and an outgoing document both settle here.
                 }
+                // Pagehide stops the old collector and settles its pending router
+                // callback. It must not replace the destination document's grantless
+                // recovery record with an unconfirmed result from the outgoing page.
+                if (navigationReleased || !authorityIsCurrent())
+                    return deliveryResult;
+                deliveryResult = this.markDeferredNavigationUnconfirmed(pendingExecution, context.currentRevision);
             }
             else if (deferredNavigation) {
                 deliveryResult = this.markDeferredNavigationUnconfirmed(pendingExecution, context.currentRevision);
@@ -14669,6 +14702,21 @@ class AiLiveAssist {
         }, delay + Math.floor(Math.random() * 250));
         this.reconnectTimer = timer;
     }
+    canRecoverControlTransport(channel, result, media) {
+        return (this.channel === channel &&
+            this.result === result &&
+            this.media === media && media.isConnected && navigator.onLine &&
+            !this.ended && !this.destroyed && !this.terminalRequestPending &&
+            !this.reconnecting && !this.launchInFlight && !this.isVoicePresence() &&
+            (this.lifecyclePhase === "active_text" || this.lifecyclePhase === "active_voice") &&
+            !this.pendingAction && !this.pendingConfirmation && !this.pendingPageAssistance &&
+            !this.pendingNavigationActionResult && !this.legacyActionExecution &&
+            this.actionGrantInFlight.size === 0 &&
+            !this.pendingModeUpgrade && !this.pendingTextModeTransition &&
+            !this.messengerTransferPending && !this.messengerTransferred &&
+            !this.handoffRequestLifecycleOwner && !this.readResume()?.pauseCommand &&
+            this.modeUpgradePathIsCurrent(path()));
+    }
     async reconnectPendingHandoffControlInMemory(result, record, clientSequence, fencingToken, reconnectGeneration) {
         if (reconnectGeneration !== this.reconnectGeneration ||
             this.reconnecting ||

package/cjs/context.d.ts

@@ -23,6 +23,7 @@ export declare class PageContextCollector {
     private mutationObserver;
     private captureTimer;
     private mutationCaptureTimer;
+    private mutationCaptureStartedAt;
     private targetIds;
     private pageScrollIds;
     private navigationTargetBindings;
@@ -74,6 +75,7 @@ export declare class PageContextCollector {
     private waitForScrollSettlement;
     private actionApplied;
     private clippedGeometry;
+    private clearMutationCapture;
     private scheduleCapture;
     private scheduleMutationCapture;
     private scheduleViewportCapture;

package/cjs/context.js

@@ -10,6 +10,7 @@ const MAX_SELECTED_TEXT = 2000;
 const SELECTION_RETENTION_MS = 120000;
 const CAPTURE_SETTLE_MS = 250;
 const MUTATION_CAPTURE_DEBOUNCE_MS = 350;
+const MUTATION_CAPTURE_MAX_WAIT_MS = 1000;
 const SCROLL_SETTLEMENT_TIMEOUT_MS = 2000;
 const SCROLL_SETTLEMENT_FRAME_FALLBACK_MS = 50;
 const SCROLL_SETTLEMENT_POSITION_TOLERANCE_PX = 1;
@@ -78,6 +79,7 @@ const navigationTargetBinding = (target) => canonicalJson({
     inputType: target.inputType ?? null,
     autocomplete: target.autocomplete ?? null,
     semanticRegion: target.semanticRegion ?? null,
+    ...(target.navigationMenu === true ? { navigationMenu: true } : {}),
     destinationPath: target.destinationPath ?? null,
     sensitivity: target.sensitivity,
     protectedRegion: target.protectedRegion ?? null,
@@ -122,6 +124,7 @@ const actionTargetFingerprintBinding = (target) => canonicalJson({
     inputType: target.inputType ?? null,
     autocomplete: target.autocomplete ?? null,
     semanticRegion: target.semanticRegion ?? null,
+    ...(target.navigationMenu === true ? { navigationMenu: true } : {}),
     destinationPath: target.destinationPath ?? null,
     sensitivity: target.sensitivity,
     protectedRegion: target.protectedRegion ?? null,
@@ -145,47 +148,94 @@ const actionTargetFingerprint = async (target, subtle = globalThis.crypto?.subtl
 };
 exports.actionTargetFingerprint = actionTargetFingerprint;
 const isHTMLElement = (value) => value instanceof HTMLElement;
+// Clipping is checked in document geometry, not against the viewport: a
+// rendered footer link remains discoverable before it is scrolled into view.
+// No hidden descendant text is inspected to discover a navigation menu.
+const clippedRect = (element) => {
+    const rect = element.getBoundingClientRect();
+    let { left, top, right, bottom } = rect;
+    let depth = 0;
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        if (++depth > 64)
+            return null;
+        const style = window.getComputedStyle(parent);
+        if (Number.parseFloat(style.opacity) === 0 || style.visibility === 'hidden' || style.display === 'none' || style.contentVisibility === 'hidden')
+            return null;
+        if (parent === document.body || parent === document.documentElement)
+            continue;
+        const bounds = parent.getBoundingClientRect();
+        // Overflow scrolling can reveal an offscreen descendant. A collapsed or
+        // clipped disclosure cannot be revealed by scrolling the document to it.
+        if (['hidden', 'clip'].includes(style.overflowX)) {
+            left = Math.max(left, bounds.left);
+            right = Math.min(right, bounds.right);
+        }
+        if (['hidden', 'clip'].includes(style.overflowY)) {
+            top = Math.max(top, bounds.top);
+            bottom = Math.min(bottom, bounds.bottom);
+        }
+        if (right <= left || bottom <= top)
+            return null;
+    }
+    return right > left && bottom > top ? { left, top, right, bottom } : null;
+};
 const isRendered = (element) => {
-    if (!isHTMLElement(element) || !element.isConnected || element.closest(PRIVATE_SELECTOR)) {
+    if (!isHTMLElement(element) || !element.isConnected || element.closest(PRIVATE_SELECTOR))
         return false;
-    }
     const style = window.getComputedStyle(element);
-    const opacity = Number.parseFloat(style.opacity);
-    if (style.display === 'none' ||
-        style.visibility === 'hidden' ||
-        (Number.isFinite(opacity) && opacity === 0) ||
-        style.pointerEvents === 'none') {
+    if (style.display === 'none' || style.visibility === 'hidden' ||
+        Number.parseFloat(style.opacity) === 0 || style.pointerEvents === 'none')
         return false;
-    }
-    const rect = element.getBoundingClientRect();
-    return rect.width > 0 && rect.height > 0;
+    return clippedRect(element) !== null;
 };
-const isVisible = (element) => {
+const visibleRect = (element) => {
     if (!isRendered(element))
-        return false;
-    const rect = element.getBoundingClientRect();
-    return (rect.bottom >= 0 &&
-        rect.right >= 0 &&
-        rect.top <= window.innerHeight &&
-        rect.left <= window.innerWidth);
+        return null;
+    const rect = clippedRect(element);
+    if (!rect)
+        return null;
+    const left = Math.max(0, rect.left), top = Math.max(0, rect.top);
+    const right = Math.min(window.innerWidth, rect.right), bottom = Math.min(window.innerHeight, rect.bottom);
+    return right > left && bottom > top ? { left, top, right, bottom } : null;
 };
-const isCovered = (element, trustedGuideRoot = null) => {
-    const rect = element.getBoundingClientRect();
-    const x = Math.max(0, Math.min(window.innerWidth - 1, rect.left + rect.width / 2));
-    const y = Math.max(0, Math.min(window.innerHeight - 1, rect.top + rect.height / 2));
-    let top;
-    if (trustedGuideRoot?.isConnected &&
-        typeof document.elementsFromPoint === 'function') {
-        top =
-            document
-                .elementsFromPoint(x, y)
-                .find((candidate) => candidate !== trustedGuideRoot) ??
-                document.elementFromPoint(x, y);
-    }
-    else {
-        top = document.elementFromPoint(x, y);
-    }
-    return Boolean(top && top !== element && !element.contains(top) && !top.contains(element));
+const isVisible = (element) => visibleRect(element) !== null;
+const interactionPoint = (element, trustedGuideRoot = null) => {
+    const rect = visibleRect(element);
+    if (!rect)
+        return null;
+    // Five bounded hit tests permit an exposed part of a link without treating
+    // an ancestor, empty hit, or a covering sibling as an interactable target.
+    const insetX = Math.min(1, (rect.right - rect.left) / 4);
+    const insetY = Math.min(1, (rect.bottom - rect.top) / 4);
+    const points = [
+        [(rect.left + rect.right) / 2, (rect.top + rect.bottom) / 2],
+        [rect.left + insetX, rect.top + insetY], [rect.right - insetX, rect.top + insetY],
+        [rect.left + insetX, rect.bottom - insetY], [rect.right - insetX, rect.bottom - insetY],
+    ];
+    for (const [x, y] of points) {
+        const top = trustedGuideRoot?.isConnected && typeof document.elementsFromPoint === 'function'
+            ? document.elementsFromPoint(x, y).find(candidate => candidate !== trustedGuideRoot) ?? null
+            : document.elementFromPoint(x, y);
+        if (top !== null && (top === element || element.contains(top)))
+            return { x: x, y: y, hit: top };
+    }
+    return null;
+};
+const isCovered = (element, trustedGuideRoot = null) => interactionPoint(element, trustedGuideRoot) === null;
+const isNavigationMenu = (element, role) => {
+    if (role !== 'button' || literalBooleanAttribute(element, 'aria-expanded') === undefined ||
+        element.hasAttribute('aria-pressed') || element.hasAttribute('aria-checked') ||
+        element instanceof HTMLButtonElement && element.form !== null && element.type !== 'button')
+        return false;
+    if (element.closest('nav,[role="navigation"]'))
+        return true;
+    // aria-controls supplies identity only. Do not capture hidden menu labels,
+    // links, values or instructions before native expansion and recapture.
+    const controls = (element.getAttribute('aria-controls') ?? '').trim().split(/\s+/).slice(0, 4);
+    return controls.some(control => {
+        const menu = document.getElementById(control);
+        return menu !== null && menu.matches('nav,[role="navigation"],[role="menu"]');
+    });
 };
 const safePageUrl = () => `${window.location.origin}${window.location.pathname}`;
 const linkBrowsingTarget = (link) => (link.getAttribute('target') ?? document.querySelector('base[target]')?.getAttribute('target') ?? '').toLowerCase();
@@ -197,11 +247,13 @@ const sameNavigationDestination = (actual, expected) => {
     return left.origin === right.origin && left.pathname === right.pathname && left.search === right.search;
 };
 const safeDestinationPath = (element) => {
-    if (!(element instanceof HTMLAnchorElement))
+    // An empty href is a control, not authority to navigate to the current URL.
+    if (!(element instanceof HTMLAnchorElement) || !element.getAttribute('href')?.trim())
         return null;
     try {
         const destination = new URL(element.href, window.location.href);
         if (destination.origin !== window.location.origin ||
+            destination.username !== '' || destination.password !== '' ||
             destination.search ||
             destination.hash ||
             !destination.pathname.startsWith('/') ||
@@ -444,15 +496,17 @@ const checkedStateFor = (element) => {
     }
     return framerToggleDescriptor(element)?.checked;
 };
-const dispatchFramerPrimaryPointerSequence = (element) => {
+const dispatchFramerPrimaryPointerSequence = (element, trustedGuideRoot = null) => {
     if (typeof window.PointerEvent !== 'function') {
         throw new Error('Framer pointer interaction is unavailable.');
     }
-    const rect = element.getBoundingClientRect();
-    const clientX = rect.left + rect.width / 2;
-    const clientY = rect.top + rect.height / 2;
-    const hit = document.elementFromPoint(clientX, clientY);
-    const eventTarget = element instanceof HTMLAnchorElement && hit && element.contains(hit) ? hit : element;
+    // Capture and dispatch must agree on the exposed point and exact descendant,
+    // including when our own mobile surface covers a link's router-owned logo.
+    const point = interactionPoint(element, trustedGuideRoot);
+    if (!point)
+        throw new Error('The approved pointer target is covered.');
+    const { x: clientX, y: clientY } = point;
+    const eventTarget = element instanceof HTMLAnchorElement ? point.hit : element;
     const nestedLink = eventTarget.closest('a[href]');
     if (element instanceof HTMLAnchorElement && nestedLink instanceof HTMLAnchorElement && nestedLink !== element &&
         (!sameNavigationDestination(nestedLink.href, element.href) || nestedLink.hasAttribute('download') ||
@@ -524,11 +578,11 @@ const dispatchFramerPrimaryPointerSequence = (element) => {
         detail: 1,
     }));
 };
-const dispatchFramerTogglePrimaryPointer = (element) => {
+const dispatchFramerTogglePrimaryPointer = (element, trustedGuideRoot = null) => {
     if (!framerToggleDescriptor(element)) {
         throw new Error('Framer toggle pointer interaction is unavailable.');
     }
-    dispatchFramerPrimaryPointerSequence(element);
+    dispatchFramerPrimaryPointerSequence(element, trustedGuideRoot);
 };
 const semanticSourceSensitivity = (source) => {
     if (source.closest(PRIVATE_SELECTOR) || source.querySelector(PRIVATE_SELECTOR)) {
@@ -698,6 +752,7 @@ class PageContextCollector {
         this.mutationObserver = null;
         this.captureTimer = null;
         this.mutationCaptureTimer = null;
+        this.mutationCaptureStartedAt = null;
         this.targetIds = new WeakMap();
         this.pageScrollIds = new WeakMap();
         this.navigationTargetBindings = new WeakMap();
@@ -725,9 +780,7 @@ class PageContextCollector {
                 this.pendingCapture = true;
                 return;
             }
-            if (this.mutationCaptureTimer)
-                clearTimeout(this.mutationCaptureTimer);
-            this.mutationCaptureTimer = null;
+            this.clearMutationCapture();
             if (this.captureTimer)
                 return;
             this.captureTimer = setTimeout(() => {
@@ -744,12 +797,19 @@ class PageContextCollector {
             }
             if (this.captureTimer)
                 return;
+            // Decorative animation must not indefinitely hide newly available links.
+            // Retain trailing-edge batching, with at most one forced scan per second
+            // during continuous churn. Unchanged semantic snapshots are still deduped.
+            const now = performance.now();
+            this.mutationCaptureStartedAt ?? (this.mutationCaptureStartedAt = now);
+            const delay = Math.max(0, Math.min(MUTATION_CAPTURE_DEBOUNCE_MS, MUTATION_CAPTURE_MAX_WAIT_MS - (now - this.mutationCaptureStartedAt)));
             if (this.mutationCaptureTimer)
                 clearTimeout(this.mutationCaptureTimer);
             this.mutationCaptureTimer = setTimeout(() => {
                 this.mutationCaptureTimer = null;
+                this.mutationCaptureStartedAt = null;
                 void this.captureAndPublishIfChanged();
-            }, MUTATION_CAPTURE_DEBOUNCE_MS);
+            }, delay);
         };
         this.scheduleViewportCapture = () => {
             this.scheduleMutationCapture();
@@ -822,9 +882,7 @@ class PageContextCollector {
             if (this.captureTimer)
                 clearTimeout(this.captureTimer);
             this.captureTimer = null;
-            if (this.mutationCaptureTimer)
-                clearTimeout(this.mutationCaptureTimer);
-            this.mutationCaptureTimer = null;
+            this.clearMutationCapture();
             if (this.releasedNavigationSettlement &&
                 window.location.href !== this.releasedNavigationSettlement.fromUrl) {
                 this.finishReleasedNavigationSettlement(sameNavigationDestination(window.location.href, this.releasedNavigationSettlement.toUrl)
@@ -955,9 +1013,7 @@ class PageContextCollector {
         if (this.captureTimer)
             clearTimeout(this.captureTimer);
         this.captureTimer = null;
-        if (this.mutationCaptureTimer)
-            clearTimeout(this.mutationCaptureTimer);
-        this.mutationCaptureTimer = null;
+        this.clearMutationCapture();
         window.removeEventListener('resize', this.scheduleViewportCapture);
         document.removeEventListener('scroll', this.scheduleViewportCapture, true);
         window.visualViewport?.removeEventListener('resize', this.scheduleViewportCapture);
@@ -1061,6 +1117,7 @@ class PageContextCollector {
                     }
                     : {}),
                 ...(semanticRegion ? { semanticRegion } : {}),
+                ...(this.statefulButtonActionProof && isNavigationMenu(element, role) ? { navigationMenu: true } : {}),
                 ...(destinationPath ? { destinationPath } : {}),
                 sensitivity,
                 protectedRegion: sensitivity !== 'none' || regionAssessment.matchedRuleDigests.length > 0,
@@ -1172,6 +1229,7 @@ class PageContextCollector {
             pageId: this.pageId,
             revision,
             url: safePageUrl(),
+            locationHasQuery: window.location.search !== '',
             title: normalize(document.title, 512),
             locale: normalize(document.documentElement.lang || navigator.language || 'en', 16),
             viewport: {
@@ -1792,7 +1850,7 @@ class PageContextCollector {
                 };
                 window.addEventListener('click', preventNativeNavigation);
                 try {
-                    dispatchFramerPrimaryPointerSequence(navigation.source);
+                    dispatchFramerPrimaryPointerSequence(navigation.source, this.trustedGuideRoot);
                 }
                 finally {
                     window.removeEventListener('click', preventNativeNavigation);
@@ -1874,7 +1932,7 @@ class PageContextCollector {
         if (desiredStates.length > 0 && desiredStates.every(Boolean))
             return;
         if (desiredChecked !== undefined && framerToggleDescriptor(element)) {
-            dispatchFramerTogglePrimaryPointer(element);
+            dispatchFramerTogglePrimaryPointer(element, this.trustedGuideRoot);
             return;
         }
         if (element instanceof HTMLAnchorElement) {
@@ -2182,9 +2240,19 @@ class PageContextCollector {
             height,
         };
     }
+    clearMutationCapture() {
+        if (this.mutationCaptureTimer)
+            clearTimeout(this.mutationCaptureTimer);
+        this.mutationCaptureTimer = null;
+        this.mutationCaptureStartedAt = null;
+    }
     async captureAndPublishIfChanged() {
-        if (this.navigationSettlement)
+        if (!this.running || this.navigationSettlement)
+            return;
+        if (this.executingActionId) {
+            this.pendingCapture = true;
             return;
+        }
         const snapshot = this.captureSnapshot(false);
         if (snapshot && this.running)
             await this.callbacks.onSnapshot(snapshot);
@@ -2269,9 +2337,7 @@ class PageContextCollector {
         if (this.captureTimer)
             clearTimeout(this.captureTimer);
         this.captureTimer = null;
-        if (this.mutationCaptureTimer)
-            clearTimeout(this.mutationCaptureTimer);
-        this.mutationCaptureTimer = null;
+        this.clearMutationCapture();
         return settlement;
     }
     observeCausalNavigationAfterMutation(actionId, destinationPath, beforeActionUrl) {

package/cjs/control.d.ts

@@ -24,6 +24,10 @@ export type ControlOutboundOperation = {
     type: string;
 };
 export type ReservedControlOperation = Readonly<ControlOutboundOperation>;
+type TransportRecovery = {
+    canRecover: () => boolean;
+    onRecovered: () => Promise<void>;
+};
 export declare class ControlChannel {
     private readonly result;
     private readonly tabId;
@@ -31,6 +35,7 @@ export declare class ControlChannel {
     private readonly onDisconnect;
     private readonly onClientSequence;
     private readonly onUnsafeDisconnect;
+    private readonly transportRecovery?;
     private socket;
     private clientSequence;
     private serverSequence;
@@ -54,7 +59,9 @@ export declare class ControlChannel {
     private pendingConnection;
     private helloOperation;
     private fencedAuthorityConfirmed;
-    constructor(result: RuntimeAuthorization, tabId: string, clientVersion: string, onDisconnect: () => void, initialClientSequence?: number, onClientSequence?: (sequence: number) => void, onUnsafeDisconnect?: () => void);
+    private transportRecoveryAttempted;
+    private recoveringTransport;
+    constructor(result: RuntimeAuthorization, tabId: string, clientVersion: string, onDisconnect: () => void, initialClientSequence?: number, onClientSequence?: (sequence: number) => void, onUnsafeDisconnect?: () => void, transportRecovery?: TransportRecovery | undefined);
     get leaseToken(): number;
     get lastClientSequence(): number;
     get isOpen(): boolean;
@@ -78,6 +85,7 @@ export declare class ControlChannel {
     private handleMessage;
     private recoverFromSequenceGap;
     private notifyUnsafeDisconnect;
+    private recoverTransport;
     private enqueueHandlers;
     private dispatchHandlers;
     private handleHandlerFailure;

package/cjs/control.js

@@ -6,6 +6,7 @@ const PROTOCOL_VIOLATION_CLOSE_CODE = 4008;
 const SERVER_SEQUENCE_GAP_CLOSE_CODE = 4009;
 const HANDLER_FAILURE_CLOSE_CODE = 4010;
 const HANDLER_TIMEOUT_MS = 15000;
+const TRANSPORT_RECOVERY_TIMEOUT_MS = 5000;
 const MAX_PENDING_HANDLER_MESSAGES = 64;
 const MAX_PENDING_STATEFUL_OPERATIONS = 64;
 const MAX_SETTLED_OPERATION_HISTORY = 100;
@@ -38,13 +39,14 @@ const STATEFUL_CONTROL_TYPES = new Set([
 ]);
 const outcomeKey = (messageId, sequence) => `${messageId}\u0000${sequence}`;
 class ControlChannel {
-    constructor(result, tabId, clientVersion, onDisconnect, initialClientSequence = 0, onClientSequence = () => undefined, onUnsafeDisconnect = () => undefined) {
+    constructor(result, tabId, clientVersion, onDisconnect, initialClientSequence = 0, onClientSequence = () => undefined, onUnsafeDisconnect = () => undefined, transportRecovery) {
         this.result = result;
         this.tabId = tabId;
         this.clientVersion = clientVersion;
         this.onDisconnect = onDisconnect;
         this.onClientSequence = onClientSequence;
         this.onUnsafeDisconnect = onUnsafeDisconnect;
+        this.transportRecovery = transportRecovery;
         this.socket = null;
         this.serverSequence = 0;
         this.serverBaselineEstablished = false;
@@ -67,6 +69,8 @@ class ControlChannel {
         this.pendingConnection = null;
         this.helloOperation = null;
         this.fencedAuthorityConfirmed = false;
+        this.transportRecoveryAttempted = false;
+        this.recoveringTransport = false;
         this.clientSequence =
             Number.isSafeInteger(initialClientSequence) && initialClientSequence >= 0
                 ? initialClientSequence
@@ -79,7 +83,7 @@ class ControlChannel {
         return this.clientSequence;
     }
     get isOpen() {
-        return this.socket?.readyState === WebSocket.OPEN;
+        return (!this.recoveringTransport && this.socket?.readyState === WebSocket.OPEN);
     }
     get connectionHelloOperation() {
         return this.helloOperation ? { ...this.helloOperation } : null;
@@ -180,10 +184,19 @@ class ControlChannel {
                     this.rejectPendingConnection(socket, generation, new Error("The AI Guide control channel could not connect."));
                 }
             }, { once: true });
-            socket.addEventListener("close", () => {
+            socket.addEventListener("close", (event) => {
                 if (!this.isCurrentSocket(socket, generation))
                     return;
                 const wasIntentionallyClosed = this.intentionallyClosed;
+                // A settled transport loss is not a new session. Keep its provider
+                // connection alive for one bounded retry, but never carry ambiguous
+                // browser writes, an active handler, or a protocol failure across it.
+                const canRecover = event.code === 1006 &&
+                    this.fencedAuthorityConfirmed &&
+                    !this.transportRecoveryAttempted &&
+                    !this.sequenceGapDetected &&
+                    this.pendingHandlerMessages === 0 &&
+                    this.unsettledStatefulOperations.size === 0;
                 this.socket = null;
                 this.socketGeneration += 1;
                 this.stopHeartbeat();
@@ -197,12 +210,24 @@ class ControlChannel {
                 this.pendingHandlerMessages = 0;
                 this.rejectPendingConnection(socket, generation, new Error("The AI Guide control channel closed before connecting."));
                 if (!wasIntentionallyClosed && !signal.aborted) {
+                    try {
+                        if (canRecover && this.transportRecovery?.canRecover()) {
+                            void this.recoverTransport(signal);
+                            return;
+                        }
+                    }
+                    catch {
+                        /* A failed eligibility check uses full recovery. */
+                    }
                     this.notifyUnsafeDisconnect();
                 }
             });
         });
     }
     send(type, payload, stableMessageId) {
+        if (this.recoveringTransport && type !== "hello" && type !== "heartbeat") {
+            throw new Error("The AI Guide control channel is reconnecting.");
+        }
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
             throw new Error("The AI Guide control channel is not connected.");
         }
@@ -513,6 +538,59 @@ class ControlChannel {
             this.onDisconnect();
         }
     }
+    async recoverTransport(signal) {
+        this.transportRecoveryAttempted = true;
+        this.recoveringTransport = true;
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        signal.addEventListener("abort", abort, { once: true });
+        let timeout;
+        const deadline = new Promise((_resolve, reject) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                reject(new Error("The control reconnect timed out."));
+            }, TRANSPORT_RECOVERY_TIMEOUT_MS);
+        });
+        const fencingToken = this.fencingToken;
+        let recovered = false;
+        try {
+            await Promise.race([
+                deadline,
+                (async () => {
+                    if (signal.aborted)
+                        throw new Error("The control connection was retired.");
+                    await this.connect(controller.signal, true);
+                    const hello = await this.waitForHelloOutcome(2000);
+                    if (hello.status !== "ack" || controller.signal.aborted) {
+                        throw new Error("The control reconnect was not acknowledged.");
+                    }
+                    const authority = await this.proveFencedAuthority(2000);
+                    if (authority.status !== "ack" ||
+                        controller.signal.aborted ||
+                        this.fencingToken !== fencingToken ||
+                        !this.transportRecovery?.canRecover()) {
+                        throw new Error("The control reconnect no longer owns this session.");
+                    }
+                    this.recoveringTransport = false;
+                    await this.transportRecovery.onRecovered();
+                    recovered = !controller.signal.aborted && this.hasFencedAuthority;
+                })(),
+            ]);
+        }
+        catch {
+            // The existing full-resume path revokes local executable authority and
+            // handles expired credentials, changed ownership, and longer outages.
+        }
+        finally {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", abort);
+            this.recoveringTransport = false;
+            if (!recovered && !signal.aborted && !this.intentionallyClosed) {
+                this.retireSocket("control reconnect failed");
+                this.notifyUnsafeDisconnect();
+            }
+        }
+    }
     enqueueHandlers(message, socket, generation) {
         const isCurrent = () => this.isMessageSourceCurrent(socket, generation);
         if (!isCurrent())

package/cjs/liveControlChannel.d.ts

@@ -1,5 +1,5 @@
 import { type LiveDuplexMediaOptions, type LiveDuplexMediaDependencies } from './liveDuplexMedia.js';
-export declare const LIVE_CONTROL_CLIENT_VERSION = "7.5.0";
+export declare const LIVE_CONTROL_CLIENT_VERSION = "7.5.6";
 export declare const LIVE_CONTROL_CLIENT_CAPABILITIES: readonly ["live_duplex_v1", "live_local_wake_v1", "live_fragment_captions_v1"];
 declare const phases: readonly ["voice_off", "local_listening", "wake_buffering", "starting", "active", "tentative_idle", "closing", "uncertain", "muted", "suspended", "budget_blocked", "ended"];
 export type LiveControlState = {