@oxvo/ai-live-assist 7.3.4 → 7.4.23

package/lib/context.js

@@ -26,12 +26,63 @@ const SENSITIVE_PATTERNS = [
     ['authentication_secret', /auth.*secret|private.?key|access.?token/i],
     ['api_secret', /api.?key|client.?secret|secret.?key/i],
 ];
+const EXPLICIT_SENSITIVITIES = new Set([
+    'private',
+    'password',
+    'otp',
+    'payment',
+    'banking',
+    'recovery',
+    'authentication_secret',
+    'api_secret',
+]);
 const id = (prefix) => `${prefix}_${crypto.randomUUID()}`;
 const normalize = (value, maximum) => value
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
     .replace(/\s+/g, ' ')
     .trim()
     .slice(0, maximum);
+const canonicalJson = (value) => {
+    const sort = (item) => {
+        if (Array.isArray(item))
+            return item.map(sort);
+        if (item !== null && typeof item === 'object') {
+            return Object.fromEntries(Object.entries(item)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, nested]) => [key, sort(nested)]));
+        }
+        return item;
+    };
+    return JSON.stringify(sort(value));
+};
+export const actionTargetFingerprint = async (target, subtle = globalThis.crypto?.subtle) => {
+    if (!subtle)
+        return null;
+    try {
+        const canonical = canonicalJson({
+            targetId: target.targetId,
+            role: target.role,
+            name: target.name,
+            inputType: target.inputType ?? null,
+            autocomplete: target.autocomplete ?? null,
+            semanticRegion: target.semanticRegion ?? null,
+            destinationPath: target.destinationPath ?? null,
+            sensitivity: target.sensitivity,
+            protectedRegion: target.protectedRegion ?? null,
+            frameOrigin: target.frameOrigin ?? null,
+            consequence: target.consequence ?? null,
+            regionAssessment: target.regionAssessment ?? null,
+            options: target.options ?? null,
+        });
+        const digest = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(canonical)));
+        if (digest.byteLength !== 32)
+            return null;
+        return Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+    }
+    catch {
+        return null;
+    }
+};
 const isHTMLElement = (value) => value instanceof HTMLElement;
 const isRendered = (element) => {
     if (!isHTMLElement(element) || !element.isConnected || element.closest(PRIVATE_SELECTOR)) {
@@ -57,11 +108,22 @@ const isVisible = (element) => {
         rect.top <= window.innerHeight &&
         rect.left <= window.innerWidth);
 };
-const isCovered = (element) => {
+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));
-    const top = document.elementFromPoint(x, y);
+    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 safePageUrl = () => `${window.location.origin}${window.location.pathname}`;
@@ -94,17 +156,22 @@ const sensitivityFor = (element, name) => {
         return 'otp';
     if (/^cc-/.test(autocomplete))
         return 'payment';
+    const explicitSensitivity = normalize(element.closest('[data-oxvo-sensitivity]')?.getAttribute('data-oxvo-sensitivity') ?? '', 64);
+    if (EXPLICIT_SENSITIVITIES.has(explicitSensitivity))
+        return explicitSensitivity;
     const descriptors = [
         name,
         element.getAttribute('name') ?? '',
         element.id,
         element.getAttribute('autocomplete') ?? '',
-        element.getAttribute('data-oxvo-sensitivity') ?? '',
+        element.closest('[data-oxvo-sensitivity]')?.getAttribute('data-oxvo-sensitivity') ?? '',
     ].join(' ');
     for (const [sensitivity, pattern] of SENSITIVE_PATTERNS) {
         if (pattern.test(descriptors))
             return sensitivity;
     }
+    if (element.closest('[data-oxvo-sensitivity]'))
+        return 'private';
     if (element.closest('[data-oxvo-private]'))
         return 'private';
     return 'none';
@@ -138,11 +205,6 @@ const roleFor = (element) => {
     return tag.slice(0, 64);
 };
 const nameFor = (element) => {
-    const labelledBy = element.getAttribute('aria-labelledby');
-    const labelledText = labelledBy
-        ?.split(/\s+/)
-        .map((value) => document.getElementById(value)?.textContent ?? '')
-        .join(' ');
     const input = element instanceof HTMLInputElement ? element : null;
     const formControl = element instanceof HTMLInputElement ||
         element instanceof HTMLSelectElement ||
@@ -151,49 +213,208 @@ const nameFor = (element) => {
         : null;
     const associatedLabel = formControl
         ? Array.from(formControl.labels ?? [])
-            .flatMap((label) => {
-            const walker = document.createTreeWalker(label, NodeFilter.SHOW_TEXT);
-            const text = [];
-            let node = walker.nextNode();
-            while (node) {
-                if (!node.parentElement?.closest('input,select,textarea,option,button')) {
-                    text.push(node.textContent ?? '');
-                }
-                node = walker.nextNode();
-            }
-            return text;
-        })
+            .map((label) => safeAccessibleNameText(label, 300))
+            .filter(Boolean)
             .join(' ')
         : '';
-    const explicitName = element.getAttribute('aria-label') ??
-        labelledText ??
-        element.getAttribute('alt') ??
-        element.getAttribute('title') ??
-        element.getAttribute('placeholder');
+    const safeAttribute = (attribute, maximum) => {
+        const value = normalize(element.getAttribute(attribute) ?? '', maximum);
+        return value && sensitivityFor(element, value) === 'none' ? value : '';
+    };
+    const semanticName = safeAccessibleNameText(element, 300);
+    const attributeName = safeAttribute('alt', 300) ||
+        safeAttribute('title', 300) ||
+        safeAttribute('placeholder', 300);
     if (element instanceof HTMLFormElement) {
-        return normalize(explicitName ??
-            element.getAttribute('data-oxvo-ai-region') ??
-            element.getAttribute('name') ??
+        const explicitSemanticName = element.hasAttribute('aria-label') || element.hasAttribute('aria-labelledby')
+            ? semanticName
+            : '';
+        return normalize(explicitSemanticName ||
+            attributeName ||
+            safeAttribute('data-oxvo-ai-region', 120) ||
+            safeAttribute('name', 120) ||
             'Form', 120);
     }
-    return normalize(explicitName ??
-        (associatedLabel || null) ??
-        (input && ['button', 'submit', 'reset'].includes(input.type) ? input.value : null) ??
-        element.textContent ??
-        '', 300);
+    const buttonValue = input && ['button', 'submit', 'reset'].includes(input.type)
+        ? normalize(input.value, 300)
+        : '';
+    return normalize(semanticName ||
+        associatedLabel ||
+        attributeName ||
+        (buttonValue && sensitivityFor(element, buttonValue) === 'none' ? buttonValue : ''), 300);
+};
+const safeDescendantText = (element, maximum, renderedOnly = false) => {
+    const parts = [];
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+    let node = walker.nextNode();
+    while (node) {
+        const parent = node.parentElement;
+        const text = normalize(node.textContent ?? '', maximum);
+        if (parent &&
+            text &&
+            !parent.closest(PRIVATE_SELECTOR) &&
+            !parent.closest('script,style,noscript,template,svg,input,select,textarea,option') &&
+            (renderedOnly ? isRendered(parent) : isVisible(parent)) &&
+            sensitivityFor(parent, text) === 'none') {
+            parts.push(text);
+        }
+        node = walker.nextNode();
+    }
+    return normalize(parts.join(' '), maximum);
+};
+const safeSemanticText = (element, maximum) => {
+    if (!isVisible(element) || element.closest(PRIVATE_SELECTOR))
+        return '';
+    const explicit = normalize(element.getAttribute('aria-label') ?? '', maximum);
+    if (explicit) {
+        return sensitivityFor(element, explicit) === 'none' ? explicit : '';
+    }
+    const labelledBy = element.getAttribute('aria-labelledby');
+    const labelledParts = labelledBy
+        ? labelledBy
+            .split(/\s+/)
+            .map((idValue) => document.getElementById(idValue))
+            .filter((label) => Boolean(label))
+            .flatMap((label) => {
+            if (!isVisible(label) || label.closest(PRIVATE_SELECTOR))
+                return [];
+            const text = safeDescendantText(label, maximum);
+            return text && sensitivityFor(label, text) === 'none' ? [text] : [];
+        })
+        : [];
+    if (labelledParts.length > 0) {
+        const text = normalize(labelledParts.join(' '), maximum);
+        return sensitivityFor(element, text) === 'none' ? text : '';
+    }
+    const text = safeDescendantText(element, maximum);
+    return text && sensitivityFor(element, text) === 'none' ? text : '';
+};
+const safeAccessibleNameText = (element, maximum) => {
+    if (!isRendered(element) || element.closest(PRIVATE_SELECTOR))
+        return '';
+    const explicit = normalize(element.getAttribute('aria-label') ?? '', maximum);
+    if (explicit) {
+        return sensitivityFor(element, explicit) === 'none' ? explicit : '';
+    }
+    const labelledBy = element.getAttribute('aria-labelledby');
+    const labelledParts = labelledBy
+        ? labelledBy
+            .split(/\s+/)
+            .map((idValue) => document.getElementById(idValue))
+            .filter((label) => Boolean(label))
+            .flatMap((label) => {
+            if (!isRendered(label) || label.closest(PRIVATE_SELECTOR))
+                return [];
+            const text = safeDescendantText(label, maximum, true);
+            return text && sensitivityFor(label, text) === 'none' ? [text] : [];
+        })
+        : [];
+    if (labelledParts.length > 0) {
+        const text = normalize(labelledParts.join(' '), maximum);
+        return sensitivityFor(element, text) === 'none' ? text : '';
+    }
+    const text = safeDescendantText(element, maximum, true);
+    return text && sensitivityFor(element, text) === 'none' ? text : '';
+};
+const semanticSourceSensitivity = (source) => {
+    if (source.closest(PRIVATE_SELECTOR) || source.querySelector(PRIVATE_SELECTOR)) {
+        return 'private';
+    }
+    const markedSources = [
+        ...(source.matches('[data-oxvo-sensitivity]') ? [source] : []),
+        ...Array.from(source.querySelectorAll('[data-oxvo-sensitivity]')),
+    ];
+    for (const marked of markedSources) {
+        const marker = normalize(marked.getAttribute('data-oxvo-sensitivity') ?? '', 64);
+        if (EXPLICIT_SENSITIVITIES.has(marker))
+            return marker;
+        const descriptor = normalize(`${marker} ${marked.textContent ?? ''}`, 500);
+        for (const [sensitivity, pattern] of SENSITIVE_PATTERNS) {
+            if (pattern.test(descriptor))
+                return sensitivity;
+        }
+        return 'private';
+    }
+    const text = normalize(`${source.getAttribute('label') ?? ''} ${source.textContent ?? ''}`, 500);
+    return sensitivityFor(source, text);
+};
+const accessibleNameSourceSensitivity = (element) => {
+    const labelledBy = element.getAttribute('aria-labelledby');
+    const referencedLabels = labelledBy
+        ? labelledBy
+            .split(/\s+/)
+            .map((idValue) => document.getElementById(idValue))
+            .filter((label) => Boolean(label))
+        : [];
+    const formControl = element instanceof HTMLInputElement ||
+        element instanceof HTMLSelectElement ||
+        element instanceof HTMLTextAreaElement
+        ? element
+        : null;
+    const sources = [
+        ...referencedLabels,
+        ...Array.from(formControl?.labels ?? []),
+    ];
+    for (const source of sources) {
+        const sensitivity = semanticSourceSensitivity(source);
+        if (sensitivity !== 'none')
+            return sensitivity;
+    }
+    return 'none';
+};
+const safeOptionLabel = (option) => {
+    const label = normalize(option.label || option.textContent || '', 300);
+    if (!label || semanticSourceSensitivity(option) !== 'none')
+        return '';
+    const group = option.closest('optgroup');
+    if (group && semanticSourceSensitivity(group) !== 'none')
+        return '';
+    return sensitivityFor(option, label) === 'none' ? label : '';
 };
 const isActionTarget = (element) => element.matches('a[href],button,input,select,textarea,summary,form,[contenteditable="true"],[role="button"],[role="link"],[role="checkbox"],[role="radio"],[role="combobox"],[role="textbox"],[tabindex]');
+const READONLY_INPUT_TYPES = new Set([
+    'date',
+    'datetime-local',
+    'email',
+    'month',
+    'number',
+    'password',
+    'search',
+    'tel',
+    'text',
+    'time',
+    'url',
+    'week',
+]);
+const isReadOnlyTextControl = (element) => (element instanceof HTMLInputElement &&
+    READONLY_INPUT_TYPES.has(element.type) &&
+    element.readOnly) ||
+    (element instanceof HTMLTextAreaElement && element.readOnly);
 const enabled = (element) => {
-    if (element.getAttribute('aria-disabled') === 'true')
+    if (element.getAttribute('aria-disabled') === 'true' ||
+        element.getAttribute('aria-readonly') === 'true' ||
+        isReadOnlyTextControl(element)) {
         return false;
+    }
     if (element instanceof HTMLButtonElement ||
         element instanceof HTMLInputElement ||
         element instanceof HTMLSelectElement ||
         element instanceof HTMLTextAreaElement) {
-        return !element.disabled;
+        return !element.matches(':disabled');
     }
     return true;
 };
+const optionDisabled = (option) => option.disabled ||
+    option.closest('optgroup')?.disabled === true ||
+    option.matches(':disabled');
+const literalBooleanAttribute = (element, attribute) => {
+    const value = element.getAttribute(attribute);
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return undefined;
+};
 const consequenceFor = (element, role, name) => {
     const form = element instanceof HTMLFormElement ? element : element.closest('form');
     const explicit = element
@@ -244,10 +465,12 @@ const consequenceFor = (element, role, name) => {
     return role === 'button' || role === 'checkbox' || role === 'radio' ? 'state_change' : 'none';
 };
 export class PageContextCollector {
-    constructor(callbacks, selectorRegionRules = [], policyVersion = 1) {
+    constructor(callbacks, selectorRegionRules = [], policyVersion = 1, trustedGuideRoot = null, statefulButtonActionProof = false) {
         this.callbacks = callbacks;
         this.selectorRegionRules = selectorRegionRules;
         this.policyVersion = policyVersion;
+        this.trustedGuideRoot = trustedGuideRoot;
+        this.statefulButtonActionProof = statefulButtonActionProof;
         this.pageId = id('page');
         this.revision = 0;
         this.running = false;
@@ -264,10 +487,12 @@ export class PageContextCollector {
         this.pendingNavigation = null;
         this.pendingCapture = false;
         this.deferredNavigation = null;
+        this.navigationSettlementGeneration = 0;
+        this.navigationSettlement = null;
         this.recentSelection = null;
         this.latestSemanticSignature = null;
         this.scheduleCapture = () => {
-            if (!this.running)
+            if (!this.running || this.navigationSettlement)
                 return;
             if (this.executingActionId) {
                 this.pendingCapture = true;
@@ -284,7 +509,7 @@ export class PageContextCollector {
             }, CAPTURE_SETTLE_MS);
         };
         this.scheduleMutationCapture = () => {
-            if (!this.running)
+            if (!this.running || this.navigationSettlement)
                 return;
             if (this.executingActionId) {
                 this.pendingCapture = true;
@@ -325,6 +550,14 @@ export class PageContextCollector {
         this.handleNavigation = () => {
             if (!this.running)
                 return;
+            const currentUrl = safePageUrl();
+            if (this.executingActionId &&
+                this.pendingNavigation?.causalActionId === this.executingActionId &&
+                this.pendingNavigation.url === currentUrl) {
+                this.pendingCapture = true;
+                this.reportCausalNavigationObservation();
+                return;
+            }
             this.pageId = id('page');
             this.revision += 1;
             this.targets.clear();
@@ -333,12 +566,27 @@ export class PageContextCollector {
                 this.pendingNavigation = {
                     pageId: this.pageId,
                     revision: this.revision,
-                    url: safePageUrl(),
+                    url: currentUrl,
+                    causalActionId: this.executingActionId,
+                    causalObservationReported: false,
                 };
                 this.pendingCapture = true;
+                this.reportCausalNavigationObservation();
                 return;
             }
-            void Promise.resolve(this.callbacks.onNavigation(this.pageId, this.revision, safePageUrl())).then(() => this.captureAndPublish());
+            const settlement = this.beginNavigationSettlement(this.pageId, this.revision, currentUrl);
+            void Promise.resolve()
+                .then(() => this.callbacks.onNavigation(settlement.pageId, settlement.revision, settlement.url))
+                .then((navigationAcknowledged) => {
+                if (navigationAcknowledged === false ||
+                    !this.running ||
+                    this.navigationSettlement !== settlement) {
+                    return undefined;
+                }
+                this.navigationSettlement = null;
+                return this.captureAndPublish();
+            })
+                .catch(() => undefined);
         };
     }
     get currentRevision() {
@@ -385,6 +633,7 @@ export class PageContextCollector {
                     'aria-label',
                     'aria-disabled',
                     'aria-expanded',
+                    'aria-pressed',
                     'aria-live',
                     'class',
                     'disabled',
@@ -439,14 +688,19 @@ export class PageContextCollector {
         this.pendingNavigation = null;
         this.pendingCapture = false;
         this.deferredNavigation = null;
+        this.navigationSettlementGeneration += 1;
+        this.navigationSettlement = null;
         this.recentSelection = null;
         this.latestSemanticSignature = null;
         this.callbacks.onHighlight(null, 'focus');
     }
     async captureAndPublish() {
+        if (this.navigationSettlement)
+            return null;
         const snapshot = this.capture();
-        if (this.running)
+        if (this.running) {
             await this.callbacks.onSnapshot(snapshot);
+        }
         return snapshot;
     }
     capture() {
@@ -465,8 +719,17 @@ export class PageContextCollector {
             }
             if (!isActionTarget(element) || !isRendered(element))
                 continue;
+            const role = roleFor(element);
+            const hasStatefulButtonAttribute = role === 'button' &&
+                (element.hasAttribute('aria-expanded') || element.hasAttribute('aria-pressed'));
+            const hasUnsupportedMixedPressedState = role === 'button' &&
+                element.getAttribute('aria-pressed')?.trim().toLowerCase() === 'mixed';
+            if (hasUnsupportedMixedPressedState ||
+                (!this.statefulButtonActionProof && hasStatefulButtonAttribute)) {
+                continue;
+            }
             const name = nameFor(element);
-            if (!name && !['form', 'textbox'].includes(roleFor(element)))
+            if (!name && !['form', 'textbox'].includes(role))
                 continue;
             const targetId = this.targetIds.get(element) ?? id('target');
             this.targetIds.set(element, targetId);
@@ -475,15 +738,18 @@ export class PageContextCollector {
             if (element instanceof HTMLSelectElement) {
                 options = Array.from(element.options)
                     .slice(0, MAX_OPTIONS)
-                    .map((option) => {
+                    .flatMap((option) => {
+                    const label = safeOptionLabel(option);
+                    if (!label)
+                        return [];
                     const optionId = this.optionIds.get(option) ?? id('option');
                     this.optionIds.set(option, optionId);
                     optionMap.set(optionId, option);
-                    return {
-                        id: optionId,
-                        label: normalize(option.label || option.textContent || '', 300),
-                        disabled: option.disabled,
-                    };
+                    return [{
+                            id: optionId,
+                            label,
+                            disabled: optionDisabled(option),
+                        }];
                 });
             }
             const semanticRegion = normalize(element.closest('[data-oxvo-ai-region]')?.getAttribute('data-oxvo-ai-region') ?? '', 128);
@@ -503,10 +769,14 @@ export class PageContextCollector {
                     // Invalid tenant selectors remain unevaluated so server policy fails closed.
                 }
             }
-            const role = roleFor(element);
-            const sensitivity = sensitivityFor(element, name);
+            const directSensitivity = sensitivityFor(element, name);
+            const sensitivity = directSensitivity !== 'none'
+                ? directSensitivity
+                : accessibleNameSourceSensitivity(element);
             const visible = isVisible(element);
             const destinationPath = safeDestinationPath(element);
+            const expanded = literalBooleanAttribute(element, 'aria-expanded');
+            const pressed = literalBooleanAttribute(element, 'aria-pressed');
             const target = {
                 targetId,
                 revision,
@@ -532,10 +802,12 @@ export class PageContextCollector {
                 state: {
                     visible,
                     enabled: enabled(element),
-                    covered: visible ? isCovered(element) : false,
+                    covered: visible ? isCovered(element, this.trustedGuideRoot) : false,
                     ...(element instanceof HTMLInputElement && ['checkbox', 'radio'].includes(element.type)
                         ? { checked: element.checked }
                         : {}),
+                    ...(this.statefulButtonActionProof && expanded !== undefined ? { expanded } : {}),
+                    ...(this.statefulButtonActionProof && pressed !== undefined ? { pressed } : {}),
                 },
                 ...(options ? { options } : {}),
             };
@@ -568,11 +840,12 @@ export class PageContextCollector {
         const landmarks = Array.from(document.querySelectorAll('main,nav,header,footer,aside,[role="main"],[role="navigation"]'))
             .filter(isVisible)
             .slice(0, 32)
-            .map((element) => ({ role: roleFor(element), label: nameFor(element) }));
+            .map((element) => ({ role: roleFor(element), label: safeSemanticText(element, 300) }))
+            .filter(({ label }) => Boolean(label));
         const alerts = Array.from(document.querySelectorAll('[role="alert"],[aria-live]'))
             .filter(isVisible)
             .slice(0, 16)
-            .map((element) => normalize(element.textContent ?? '', 500))
+            .map((element) => safeSemanticText(element, 500))
             .filter(Boolean);
         const activeSelection = this.readSafeSelection();
         if (activeSelection)
@@ -609,6 +882,8 @@ export class PageContextCollector {
         return snapshot;
     }
     captureVisualContext() {
+        if (this.navigationSettlement)
+            return null;
         if (this.revision < 1 || this.targets.size === 0)
             return null;
         const viewportWidth = Math.max(1, Math.round(window.innerWidth));
@@ -647,14 +922,81 @@ export class PageContextCollector {
             regions,
         });
     }
-    async execute(grant) {
-        const handle = this.targets.get(grant.targetId);
+    async execute(grant, authorityIsCurrent = () => true) {
         const base = {
             grant: grant.grant,
             actionId: grant.actionId,
         };
-        if (Date.parse(grant.expiresAt) <= Date.now() ||
-            grant.domRevision !== this.revision ||
+        const authorityStale = () => ({
+            ...base,
+            status: 'stale',
+            observed: {
+                url: safePageUrl(),
+                revision: this.revision,
+                targetState: 'unchanged',
+                safeSummary: 'Page assistance permission changed before execution.',
+            },
+        });
+        const expiresAt = Date.parse(grant.expiresAt);
+        const approvalExpired = () => ({
+            ...base,
+            status: 'stale',
+            observed: {
+                url: safePageUrl(),
+                revision: this.revision,
+                targetState: 'unchanged',
+                safeSummary: 'The approved page action expired before execution.',
+            },
+        });
+        const executionStale = () => {
+            if (!authorityIsCurrent())
+                return authorityStale();
+            return expiresAt <= Date.now() ? approvalExpired() : null;
+        };
+        const initialStale = executionStale();
+        if (initialStale)
+            return initialStale;
+        this.captureSnapshot(false);
+        let handle = this.targets.get(grant.targetId);
+        const revisionMatchesOrStableNavigation = grant.domRevision === this.revision ||
+            (grant.domRevision < this.revision &&
+                grant.action === 'click' &&
+                handle?.element instanceof HTMLAnchorElement &&
+                handle.target.consequence === 'navigation' &&
+                typeof handle.target.destinationPath === 'string');
+        if (expiresAt <= Date.now() ||
+            grant.pageId !== this.pageId ||
+            grant.pageUrl !== safePageUrl() ||
+            grant.policyVersion !== this.policyVersion ||
+            !revisionMatchesOrStableNavigation ||
+            !handle ||
+            handle.revision !== this.revision ||
+            !handle.element.isConnected) {
+            return {
+                ...base,
+                status: 'stale',
+                observed: {
+                    url: safePageUrl(),
+                    revision: this.revision,
+                    targetState: 'detached',
+                    safeSummary: 'The requested target changed before execution.',
+                },
+            };
+        }
+        const fingerprintedHandle = handle;
+        const fingerprint = await actionTargetFingerprint(handle.target);
+        const postFingerprintStale = executionStale();
+        if (postFingerprintStale)
+            return postFingerprintStale;
+        this.captureSnapshot(false);
+        handle = this.targets.get(grant.targetId);
+        if (!fingerprint ||
+            fingerprint !== grant.targetFingerprint ||
+            grant.pageId !== this.pageId ||
+            grant.pageUrl !== safePageUrl() ||
+            grant.policyVersion !== this.policyVersion ||
+            !revisionMatchesOrStableNavigation ||
+            handle !== fingerprintedHandle ||
             !handle ||
             handle.revision !== this.revision ||
             !handle.element.isConnected) {
@@ -680,7 +1022,9 @@ export class PageContextCollector {
             !isRendered(element) ||
             (grant.action !== 'scroll' && !isVisible(element) && !canRevealDesiredStateTarget) ||
             !enabled(element) ||
-            (grant.action !== 'scroll' && isVisible(element) && isCovered(element))) {
+            (grant.action !== 'scroll' &&
+                isVisible(element) &&
+                isCovered(element, this.trustedGuideRoot))) {
             return {
                 ...base,
                 status: 'blocked',
@@ -693,9 +1037,17 @@ export class PageContextCollector {
             };
         }
         if (!isVisible(element) && canRevealDesiredStateTarget) {
+            const preRevealStale = executionStale();
+            if (preRevealStale)
+                return preRevealStale;
             element.scrollIntoView({ behavior: 'auto', block: 'center' });
             await new Promise((resolve) => setTimeout(resolve, 80));
-            if (!isRendered(element) || !isVisible(element) || isCovered(element)) {
+            const postRevealStale = executionStale();
+            if (postRevealStale)
+                return postRevealStale;
+            if (!isRendered(element) ||
+                !isVisible(element) ||
+                isCovered(element, this.trustedGuideRoot)) {
                 return {
                     ...base,
                     status: 'blocked',
@@ -708,11 +1060,18 @@ export class PageContextCollector {
                 };
             }
         }
+        const preHighlightStale = executionStale();
+        if (preHighlightStale)
+            return preHighlightStale;
         const before = this.safeState(element);
+        const beforeActionUrl = safePageUrl();
+        this.callbacks.onHighlight(element, 'focus');
+        const preMutationStale = executionStale();
+        if (preMutationStale)
+            return preMutationStale;
         this.executingActionId = grant.actionId;
         this.pendingCapture = false;
         this.deferredNavigation = null;
-        this.callbacks.onHighlight(element, 'focus');
         try {
             switch (grant.action) {
                 case 'scroll':
@@ -729,7 +1088,7 @@ export class PageContextCollector {
                     element.focus({ preventScroll: false });
                     break;
                 case 'click':
-                    this.click(element, grant.actionId, grant.desiredChecked, handle.target.destinationPath);
+                    this.click(element, grant.actionId, grant.desiredChecked, grant.desiredExpanded, grant.desiredPressed, grant.destinationPath);
                     break;
                 case 'type':
                     this.type(element, grant.value ?? '');
@@ -741,13 +1100,29 @@ export class PageContextCollector {
                     this.submit(element);
                     break;
             }
+            if (['click', 'type', 'select', 'submit'].includes(grant.action)) {
+                this.callbacks.onActionMutationApplied?.(grant.actionId, this.revision, safePageUrl());
+            }
+            if (grant.action === 'click' &&
+                typeof grant.destinationPath === 'string') {
+                this.observeCausalNavigationAfterMutation(grant.actionId, grant.destinationPath, beforeActionUrl);
+            }
             await new Promise((resolve) => setTimeout(resolve, 80));
+            const postActionStale = executionStale();
+            if (postActionStale)
+                return postActionStale;
             if (!this.actionApplied(grant, element, handle)) {
                 throw new Error('The approved value was not applied.');
             }
             const snapshot = this.capture();
             const attached = element.isConnected;
             const after = attached ? this.safeState(element) : '';
+            const expanded = attached
+                ? literalBooleanAttribute(element, 'aria-expanded')
+                : undefined;
+            const pressed = attached
+                ? literalBooleanAttribute(element, 'aria-pressed')
+                : undefined;
             this.callbacks.onHighlight(attached ? element : null, 'success');
             return {
                 ...base,
@@ -766,10 +1141,14 @@ export class PageContextCollector {
                             ? 'The requested option was applied to the approved field.'
                             : grant.desiredChecked !== undefined
                                 ? 'The requested checkbox state was applied.'
-                                : `${grant.action} executed on the approved ${roleFor(element)} target.`,
+                                : grant.desiredExpanded !== undefined || grant.desiredPressed !== undefined
+                                    ? 'The requested button state was applied.'
+                                    : `${grant.action} executed on the approved ${roleFor(element)} target.`,
                     ...(element instanceof HTMLInputElement && ['checkbox', 'radio'].includes(element.type)
                         ? { checked: element.checked }
                         : {}),
+                    ...(this.statefulButtonActionProof && expanded !== undefined ? { expanded } : {}),
+                    ...(this.statefulButtonActionProof && pressed !== undefined ? { pressed } : {}),
                 },
             };
         }
@@ -795,10 +1174,25 @@ export class PageContextCollector {
         this.pendingNavigation = null;
         const shouldCapture = this.pendingCapture || Boolean(navigation);
         this.pendingCapture = false;
+        let navigationAcknowledged = true;
+        const settlement = navigation && this.running
+            ? this.beginNavigationSettlement(navigation.pageId, Math.max(navigation.revision, this.revision), navigation.url)
+            : null;
         if (navigation && this.running) {
-            await this.callbacks.onNavigation(navigation.pageId, Math.max(navigation.revision, this.revision), navigation.url);
+            try {
+                navigationAcknowledged =
+                    (await this.callbacks.onNavigation(navigation.pageId, Math.max(navigation.revision, this.revision), navigation.url, navigation.causalActionId)) !== false;
+            }
+            catch {
+                navigationAcknowledged = false;
+            }
         }
-        if (this.running && (shouldCapture || !navigation)) {
+        if (this.running &&
+            navigationAcknowledged &&
+            (!settlement || this.navigationSettlement === settlement) &&
+            (shouldCapture || !navigation)) {
+            if (settlement)
+                this.navigationSettlement = null;
             await this.captureAndPublish();
         }
         const deferred = this.deferredNavigation;
@@ -807,19 +1201,39 @@ export class PageContextCollector {
             ? deferred.toUrl
             : null;
     }
-    click(element, actionId, desiredChecked, expectedDestinationPath) {
+    click(element, actionId, desiredChecked, desiredExpanded, desiredPressed, expectedDestinationPath) {
         if (!(element instanceof HTMLElement))
             throw new Error('Target is not clickable.');
+        if (desiredChecked !== undefined &&
+            (desiredExpanded !== undefined || desiredPressed !== undefined)) {
+            throw new Error('Conflicting desired-state contracts are not allowed.');
+        }
+        const desiredStates = [];
         if (desiredChecked !== undefined) {
             if (!(element instanceof HTMLInputElement) || !['checkbox', 'radio'].includes(element.type)) {
                 throw new Error('Desired checked state requires a checkbox or radio target.');
             }
-            if (element.checked === desiredChecked)
-                return;
-            if (element.type === 'radio' && !desiredChecked) {
+            desiredStates.push(element.checked === desiredChecked);
+            if (element.type === 'radio' && !desiredChecked && element.checked !== desiredChecked) {
                 throw new Error('A radio target cannot be cleared by clicking it.');
             }
         }
+        if (desiredExpanded !== undefined) {
+            const expanded = literalBooleanAttribute(element, 'aria-expanded');
+            if (roleFor(element) !== 'button' || expanded === undefined) {
+                throw new Error('Desired expanded state requires an expandable button target.');
+            }
+            desiredStates.push(expanded === desiredExpanded);
+        }
+        if (desiredPressed !== undefined) {
+            const pressed = literalBooleanAttribute(element, 'aria-pressed');
+            if (roleFor(element) !== 'button' || pressed === undefined) {
+                throw new Error('Desired pressed state requires a pressed button target.');
+            }
+            desiredStates.push(pressed === desiredPressed);
+        }
+        if (desiredStates.length > 0 && desiredStates.every(Boolean))
+            return;
         if (element instanceof HTMLAnchorElement) {
             const target = new URL(element.href, window.location.href);
             if (expectedDestinationPath !== undefined &&
@@ -859,6 +1273,8 @@ export class PageContextCollector {
     type(element, value) {
         if (value.length > 2000)
             throw new Error('Value is too long.');
+        if (!enabled(element))
+            throw new Error('Text target is not editable.');
         if (element instanceof HTMLInputElement) {
             if (!['text', 'search', 'email', 'tel', 'url', 'number'].includes(element.type)) {
                 throw new Error('Input type is not supported.');
@@ -896,14 +1312,24 @@ export class PageContextCollector {
         element.dispatchEvent(new Event('change', { bubbles: true }));
     }
     select(element, handle, optionValueId) {
-        if (!(element instanceof HTMLSelectElement) || !optionValueId) {
+        if (!(element instanceof HTMLSelectElement) || !optionValueId || !enabled(element)) {
             throw new Error('Select target is invalid.');
         }
         const option = handle.options.get(optionValueId);
-        if (!option || option.disabled || !option.isConnected) {
+        if (!option ||
+            optionDisabled(option) ||
+            !option.isConnected ||
+            option.closest('select') !== element) {
             throw new Error('Select option is unavailable.');
         }
-        element.value = option.value;
+        const selectedIndexSetter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'selectedIndex')?.set;
+        if (!selectedIndexSetter) {
+            throw new Error('Select option cannot be updated safely.');
+        }
+        selectedIndexSetter.call(element, option.index);
+        if (element.options[element.selectedIndex] !== option || !option.selected) {
+            throw new Error('Select option could not be applied.');
+        }
         element.dispatchEvent(new Event('input', { bubbles: true }));
         element.dispatchEvent(new Event('change', { bubbles: true }));
     }
@@ -925,6 +1351,7 @@ export class PageContextCollector {
             connected: element.isConnected,
             disabled: !enabled(element),
             expanded: element.getAttribute('aria-expanded'),
+            pressed: element.getAttribute('aria-pressed'),
             checked: element instanceof HTMLInputElement && ['checkbox', 'radio'].includes(element.type)
                 ? element.checked
                 : undefined,
@@ -938,6 +1365,17 @@ export class PageContextCollector {
                 ['checkbox', 'radio'].includes(element.type) &&
                 element.checked === grant.desiredChecked);
         }
+        if (grant.desiredExpanded !== undefined &&
+            literalBooleanAttribute(element, 'aria-expanded') !== grant.desiredExpanded) {
+            return false;
+        }
+        if (grant.desiredPressed !== undefined &&
+            literalBooleanAttribute(element, 'aria-pressed') !== grant.desiredPressed) {
+            return false;
+        }
+        if (grant.desiredExpanded !== undefined || grant.desiredPressed !== undefined) {
+            return true;
+        }
         if (grant.action === 'type') {
             if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
                 return element.value === (grant.value ?? '');
@@ -949,7 +1387,13 @@ export class PageContextCollector {
         }
         if (grant.action === 'select') {
             const option = grant.optionValueId ? handle.options.get(grant.optionValueId) : undefined;
-            return (element instanceof HTMLSelectElement && Boolean(option) && element.value === option?.value);
+            if (!(element instanceof HTMLSelectElement) || !option)
+                return false;
+            return (option.isConnected &&
+                option.closest('select') === element &&
+                !optionDisabled(option) &&
+                element.options[element.selectedIndex] === option &&
+                option.selected);
         }
         return true;
     }
@@ -970,6 +1414,8 @@ export class PageContextCollector {
         };
     }
     async captureAndPublishIfChanged() {
+        if (this.navigationSettlement)
+            return;
         const snapshot = this.captureSnapshot(false);
         if (snapshot && this.running)
             await this.callbacks.onSnapshot(snapshot);
@@ -1043,6 +1489,54 @@ export class PageContextCollector {
             capturedAt: new Date().toISOString(),
         };
     }
+    beginNavigationSettlement(pageId, revision, url) {
+        const settlement = {
+            generation: ++this.navigationSettlementGeneration,
+            pageId,
+            revision,
+            url,
+        };
+        this.navigationSettlement = settlement;
+        if (this.captureTimer)
+            clearTimeout(this.captureTimer);
+        this.captureTimer = null;
+        if (this.mutationCaptureTimer)
+            clearTimeout(this.mutationCaptureTimer);
+        this.mutationCaptureTimer = null;
+        return settlement;
+    }
+    observeCausalNavigationAfterMutation(actionId, destinationPath, beforeActionUrl) {
+        const currentUrl = safePageUrl();
+        if (currentUrl === beforeActionUrl ||
+            window.location.search !== '' ||
+            window.location.hash !== '' ||
+            window.location.pathname !== destinationPath) {
+            return;
+        }
+        if (this.pendingNavigation?.causalActionId !== actionId ||
+            this.pendingNavigation.url !== currentUrl) {
+            this.pageId = id('page');
+            this.revision += 1;
+            this.targets.clear();
+            this.recentSelection = null;
+            this.pendingNavigation = {
+                pageId: this.pageId,
+                revision: this.revision,
+                url: currentUrl,
+                causalActionId: actionId,
+                causalObservationReported: false,
+            };
+        }
+        this.pendingCapture = true;
+        this.reportCausalNavigationObservation();
+    }
+    reportCausalNavigationObservation() {
+        const navigation = this.pendingNavigation;
+        if (!navigation || navigation.causalObservationReported)
+            return;
+        navigation.causalObservationReported = true;
+        this.callbacks.onCausalNavigationObserved?.(navigation.pageId, navigation.revision, navigation.url, navigation.causalActionId);
+    }
     installNavigationHooks() {
         this.originalPushState = history.pushState;
         this.originalReplaceState = history.replaceState;