@geometra/proxy 1.64.0 → 1.65.1

package/dist/geometry-ws.js

@@ -1,48 +1,578 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import { WebSocketServer } from 'ws';
 import { attachFiles, clearFillLookupCache, createFillLookupCache, delay, fillFields, fillOtp, pickListboxOption, resolveExistingFiles, setFieldChoice, setFieldText, selectNativeOption, setCheckedControl, wheelAt, } from './dom-actions.js';
 import { createCdpAxSessionManager } from './a11y-enrich.js';
 import { coalescePatches, diffLayout } from './diff-layout.js';
 import { extractGeometry } from './extractor.js';
-import { clientMessageValidationError, isClickEventMessage, isCompositionMessage, isFillFieldsMessage, isFillOtpMessage, isFileMessage, isKeyMessage, isListboxPickMessage, isNavigateMessage, isResizeMessage, isPdfGenerateMessage, isScreenshotMessage, isSetFieldChoiceMessage, isSetFieldTextMessage, isSetCheckedMessage, isSelectOptionMessage, isWheelMessage, PROXY_PROTOCOL_VERSION, } from './types.js';
+import { clientMessageValidationError, isClickEventMessage, isCompositionMessage, isFillFieldsMessage, isFillOtpMessage, isFileMessage, isKeyMessage, isTypeTextMessage, isListboxPickMessage, isNavigateMessage, isResizeMessage, isPdfGenerateMessage, isScreenshotMessage, isSetFieldChoiceMessage, isSetFieldTextMessage, isSetCheckedMessage, isSelectOptionMessage, isWheelMessage, GEOMETRY_PROTOCOL_VERSION, PROXY_ACTION_PROTOCOL_VERSION, PROXY_PROTOCOL_VERSION, } from './types.js';
 const DOM_OBSERVER_BINDINGS = new WeakSet();
-async function bindDomObserverBridge(page, scheduleExtract) {
-    if (DOM_OBSERVER_BINDINGS.has(page))
+const DEFAULT_PROXY_HOST = '127.0.0.1';
+const DEFAULT_MAX_PAYLOAD_BYTES = 4 * 1024 * 1024;
+const DEFAULT_ACTION_REQUEST_LEDGER_ENTRIES = 65_536;
+/** A completed action must not be starved by a page that mutates forever. */
+const MAX_INPUT_ACK_LATENCY_MS = 250;
+// The page-side bridge lives in the untrusted main world. Even if application
+// code calls the exposed "settled" hook directly, it must not be able to turn
+// that hint into an unbounded extraction loop on the proxy host.
+const MIN_IMMEDIATE_EXTRACT_INTERVAL_MS = 250;
+const PROXY_PROTOCOL_CAPABILITIES = {
+    transport: 'proxy',
+    authenticatedController: true,
+    requestScopedAcks: true,
+    actionDeadlines: true,
+    idempotentRequestIds: true,
+    atomicTypeText: true,
+    proxyActions: true,
+    exactFieldIdentity: true,
+    verifiedFileUploads: true,
+};
+const PROXY_GEOMETRY_METADATA = {
+    protocolVersion: GEOMETRY_PROTOCOL_VERSION,
+    geometryProtocolVersion: GEOMETRY_PROTOCOL_VERSION,
+    proxyActionProtocolVersion: PROXY_ACTION_PROTOCOL_VERSION,
+    protocolCapabilities: PROXY_PROTOCOL_CAPABILITIES,
+};
+const PROXY_ACTION_METADATA = {
+    // Keep the legacy field at v2 so @geometra/mcp@1.64.x clients installed
+    // through their caret proxy dependency continue to accept exact-field acks.
+    protocolVersion: PROXY_PROTOCOL_VERSION,
+    geometryProtocolVersion: GEOMETRY_PROTOCOL_VERSION,
+    proxyActionProtocolVersion: PROXY_ACTION_PROTOCOL_VERSION,
+    protocolCapabilities: PROXY_PROTOCOL_CAPABILITIES,
+};
+/**
+ * Runs in every page/frame realm before application code.
+ *
+ * Keep this function closure-free: Playwright serializes it for addInitScript.
+ * Closed shadow roots are deliberately held in a WeakMap rather than exposed
+ * through DOM attributes. The extractor consumes the same Symbol.for key in
+ * its in-page evaluation.
+ */
+function installPageFreshnessInstrumentation(config) {
+    const { installToken, notifyBindingName } = config;
+    const CLOSED_ROOTS_KEY = Symbol.for('geometra.closedShadowRoots');
+    // This key is minted in the trusted host process and injected immediately
+    // before installation. A page can preseed a public Symbol.for name, but it
+    // cannot predict this per-binding capability before an init script runs.
+    const INSTALL_STATE_KEY = `__geometraProxyFreshnessInstalled_${installToken}`;
+    const global = globalThis;
+    const globalRecord = global;
+    if (globalRecord[INSTALL_STATE_KEY] === installToken)
         return;
-    await page.exposeFunction('__geometraProxyNotify', () => {
-        scheduleExtract();
-    });
-    await page.addInitScript(() => {
-        const w = window;
-        if (w.__geometraProxyObserverBootstrapped)
+    let existingRegistry;
+    try {
+        existingRegistry = global[CLOSED_ROOTS_KEY];
+    }
+    catch {
+        // A hostile getter must not disable the independent freshness signals.
+    }
+    let closedRoots = existingRegistry instanceof WeakMap
+        ? existingRegistry
+        : undefined;
+    if (!closedRoots) {
+        const candidate = new WeakMap();
+        try {
+            const existingDescriptor = Object.getOwnPropertyDescriptor(global, CLOSED_ROOTS_KEY);
+            if (existingDescriptor) {
+                // Supplying only value preserves the flags of a non-configurable but
+                // writable data property. Configurable collisions are replaced too.
+                Object.defineProperty(global, CLOSED_ROOTS_KEY, { value: candidate });
+            }
+            else {
+                Object.defineProperty(global, CLOSED_ROOTS_KEY, {
+                    value: candidate,
+                    configurable: false,
+                    enumerable: false,
+                    writable: false,
+                });
+            }
+            if (global[CLOSED_ROOTS_KEY] === candidate)
+                closedRoots = candidate;
+        }
+        catch {
+            // Fail closed for semantic access to closed roots. attachShadow remains
+            // usable and the mutation/resize/CSS freshness machinery still boots.
+        }
+    }
+    // Capture the Playwright bridge before application code can replace or
+    // delete its writable main-world property. All instrumentation signals use
+    // this private closure reference from here onward.
+    const bindingCandidate = globalRecord[notifyBindingName];
+    const notifyBridge = typeof bindingCandidate === 'function'
+        ? bindingCandidate.bind(global)
+        : undefined;
+    const NOTIFY_MIN_INTERVAL_MS = 25;
+    let notifyInFlight = false;
+    let notifyPending = false;
+    let settledNotifyPending = false;
+    let notifyTimer;
+    let lastNotifyStartedAt = Number.NEGATIVE_INFINITY;
+    const drainNotify = () => {
+        if (!notifyBridge || notifyInFlight || notifyTimer !== undefined || !notifyPending)
             return;
-        const install = () => {
-            if (w.__geometraProxyObserverInstalled)
-                return;
-            const root = document.documentElement;
-            if (!root)
-                return;
-            const observer = new MutationObserver(() => {
-                void w.__geometraProxyNotify?.();
+        const elapsed = global.performance.now() - lastNotifyStartedAt;
+        const remaining = Math.max(0, NOTIFY_MIN_INTERVAL_MS - elapsed);
+        if (remaining > 0) {
+            // Anchor the cadence to the prior dispatch instead of resetting this
+            // timer for every mutation. A page that changes forever therefore keeps
+            // making bounded progress and still emits its final trailing signal.
+            notifyTimer = global.setTimeout(() => {
+                notifyTimer = undefined;
+                drainNotify();
+            }, Math.ceil(remaining));
+            return;
+        }
+        const urgency = settledNotifyPending ? 'settled' : undefined;
+        notifyPending = false;
+        settledNotifyPending = false;
+        notifyInFlight = true;
+        lastNotifyStartedAt = global.performance.now();
+        let bridgeCall;
+        try {
+            bridgeCall = Promise.resolve(notifyBridge(urgency));
+        }
+        catch {
+            notifyInFlight = false;
+            drainNotify();
+            return;
+        }
+        void bridgeCall.catch(() => { }).finally(() => {
+            notifyInFlight = false;
+            drainNotify();
+        });
+    };
+    const notify = (urgency) => {
+        if (!notifyBridge)
+            return;
+        notifyPending = true;
+        // A final settle hint must survive coalescing with any number of ordinary
+        // mutation signals so the host can bypass its trailing debounce once.
+        if (urgency === 'settled')
+            settledNotifyPending = true;
+        drainNotify();
+    };
+    // A sampler is started only by a signal that can imply layout is actively
+    // changing. It has a hard per-signal horizon and never polls an idle page.
+    const MAX_SETTLE_MS = 500;
+    let settleUntil = 0;
+    let settleAnimationFrame;
+    const sampleUntilSettled = () => {
+        if (global.performance.now() < settleUntil) {
+            notify();
+            settleAnimationFrame = global.requestAnimationFrame(sampleUntilSettled);
+        }
+        else {
+            settleAnimationFrame = undefined;
+            // Bypass the trailing debounce for the final sample. This makes 500ms
+            // a hard scheduling bound for a finite layout activity window instead
+            // of silently turning it into 500ms + debounceMs.
+            notify('settled');
+        }
+    };
+    const markLayoutActivity = () => {
+        settleUntil = Math.max(settleUntil, global.performance.now() + MAX_SETTLE_MS);
+        notify();
+        if (settleAnimationFrame === undefined) {
+            settleAnimationFrame = global.requestAnimationFrame(sampleUntilSettled);
+        }
+    };
+    let resizeObserver;
+    const resizeTargets = new WeakSet();
+    // Bounding the target count avoids turning observation into an unbounded
+    // mirror of very large application DOMs. CSSOM/event sampling remains the
+    // fallback for nodes beyond this cap.
+    const MAX_RESIZE_TARGETS = 4_096;
+    let resizeTargetCount = 0;
+    const observeResizeTarget = (element) => {
+        if (!resizeObserver || resizeTargets.has(element) || resizeTargetCount >= MAX_RESIZE_TARGETS)
+            return;
+        resizeTargets.add(element);
+        resizeTargetCount += 1;
+        resizeObserver.observe(element);
+    };
+    const observeResizeCandidates = (root) => {
+        if (root instanceof Element)
+            observeResizeTarget(root);
+        for (const element of root.querySelectorAll('a,button,input,select,textarea,iframe,img,canvas,svg,video,[role],[contenteditable],[tabindex]')) {
+            observeResizeTarget(element);
+            if (resizeTargetCount >= MAX_RESIZE_TARGETS)
+                break;
+        }
+    };
+    if (typeof ResizeObserver === 'function') {
+        resizeObserver = new ResizeObserver(() => notify());
+    }
+    const mutationObserver = new MutationObserver(records => {
+        for (const record of records) {
+            for (const node of record.addedNodes) {
+                if (node instanceof Element || node instanceof ShadowRoot) {
+                    observeResizeCandidates(node);
+                }
+            }
+        }
+        notify();
+    });
+    const observeRoot = (root) => {
+        mutationObserver.observe(root, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            characterData: true,
+        });
+        observeResizeCandidates(root);
+    };
+    const attachShadowDescriptor = Object.getOwnPropertyDescriptor(Element.prototype, 'attachShadow');
+    const nativeAttachShadow = attachShadowDescriptor?.value;
+    if (nativeAttachShadow) {
+        const instrumentedAttachShadow = function attachShadow(init) {
+            const root = Reflect.apply(nativeAttachShadow, this, [init]);
+            if (init?.mode === 'closed')
+                closedRoots?.set(this, root);
+            observeRoot(root);
+            markLayoutActivity();
+            return root;
+        };
+        // Preserve the original method's own surface where the platform permits
+        // it. The wrapper already has the native one-argument call signature.
+        try {
+            Object.defineProperty(instrumentedAttachShadow, 'name', {
+                value: nativeAttachShadow.name,
+                configurable: true,
             });
-            observer.observe(root, {
-                subtree: true,
-                childList: true,
-                attributes: true,
-                characterData: true,
+            Object.defineProperty(instrumentedAttachShadow, 'toString', {
+                value: nativeAttachShadow.toString.bind(nativeAttachShadow),
+                configurable: true,
             });
-            w.__geometraProxyObserverInstalled = true;
+        }
+        catch {
+            // Function metadata is cosmetic; never make attachShadow unavailable.
+        }
+        try {
+            Object.defineProperty(Element.prototype, 'attachShadow', {
+                ...attachShadowDescriptor,
+                value: instrumentedAttachShadow,
+            });
+        }
+        catch {
+            // Hardened realms may lock platform prototypes. Keep the rest of the
+            // freshness instrumentation available even when closed-root capture is
+            // impossible in that realm.
+        }
+    }
+    const wrapLayoutMutator = (prototype, property) => {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, property);
+        const native = descriptor?.value;
+        if (!descriptor || typeof native !== 'function')
+            return;
+        const wrapped = function (...args) {
+            const result = Reflect.apply(native, this, args);
+            markLayoutActivity();
+            if (result && typeof result.then === 'function') {
+                void Promise.resolve(result).then(markLayoutActivity, markLayoutActivity);
+            }
+            return result;
         };
-        if (document.readyState === 'loading') {
-            document.addEventListener('DOMContentLoaded', install, { once: true });
+        try {
+            Object.defineProperty(wrapped, 'name', { value: native.name, configurable: true });
+            Object.defineProperty(wrapped, 'length', { value: native.length, configurable: true });
         }
-        else {
-            install();
+        catch {
+            // Function metadata is best-effort only.
+        }
+        try {
+            Object.defineProperty(prototype, property, { ...descriptor, value: wrapped });
+        }
+        catch {
+            // A locked CSSOM prototype still has ResizeObserver/event fallbacks.
+        }
+    };
+    const wrapLayoutSetter = (prototype, property) => {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, property);
+        const nativeSet = descriptor?.set;
+        if (!descriptor || !nativeSet)
+            return;
+        const wrappedSet = function (value) {
+            Reflect.apply(nativeSet, this, [value]);
+            markLayoutActivity();
+        };
+        try {
+            Object.defineProperty(prototype, property, { ...descriptor, set: wrappedSet });
+        }
+        catch {
+            // A locked CSSOM prototype still has ResizeObserver/event fallbacks.
+        }
+    };
+    const instrumentedDeclarations = new WeakSet();
+    const nativeGetPropertyValue = CSSStyleDeclaration.prototype.getPropertyValue;
+    const nativeSetProperty = CSSStyleDeclaration.prototype.setProperty;
+    // CSSStyleDeclaration exposes CSS properties as own WebIDL named
+    // properties. Assignments such as rule.style.transform = 'translateX(...)'
+    // do not call the JavaScript-visible setProperty method and do not produce a
+    // DOM mutation. Instrument geometry-bearing declarations when a CSS rule's
+    // style getter first exposes them so cached declarations remain observable.
+    const GEOMETRY_DECLARATION_PROPERTIES = [
+        'alignContent', 'alignItems', 'alignSelf', 'alignmentBaseline',
+        'animation', 'animationDelay', 'animationDuration', 'animationName', 'animationPlayState',
+        'aspectRatio',
+        'blockSize', 'inlineSize', 'minBlockSize', 'maxBlockSize', 'minInlineSize', 'maxInlineSize',
+        'border', 'borderBlock', 'borderInline', 'borderWidth', 'borderTopWidth', 'borderRightWidth',
+        'borderBottomWidth', 'borderLeftWidth', 'boxSizing',
+        'clear', 'clip', 'clipPath', 'columnCount', 'columnGap', 'columnWidth', 'columns',
+        'contain', 'content', 'contentVisibility',
+        'direction', 'display',
+        'flex', 'flexBasis', 'flexDirection', 'flexFlow', 'flexGrow', 'flexShrink', 'flexWrap',
+        'float', 'cssFloat',
+        'font', 'fontFamily', 'fontSize', 'fontStretch', 'fontStyle', 'fontWeight',
+        'gap', 'grid', 'gridArea', 'gridAutoColumns', 'gridAutoFlow', 'gridAutoRows',
+        'gridColumn', 'gridColumnEnd', 'gridColumnStart', 'gridRow', 'gridRowEnd', 'gridRowStart',
+        'gridTemplate', 'gridTemplateAreas', 'gridTemplateColumns', 'gridTemplateRows',
+        'height', 'minHeight', 'maxHeight',
+        'inset', 'insetBlock', 'insetBlockEnd', 'insetBlockStart', 'insetInline', 'insetInlineEnd',
+        'insetInlineStart', 'top', 'right', 'bottom', 'left',
+        'justifyContent', 'justifyItems', 'justifySelf',
+        'letterSpacing', 'lineHeight',
+        'margin', 'marginBlock', 'marginBlockEnd', 'marginBlockStart', 'marginInline', 'marginInlineEnd',
+        'marginInlineStart', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft',
+        'objectFit', 'objectPosition', 'opacity', 'order', 'overflow', 'overflowX', 'overflowY',
+        'padding', 'paddingBlock', 'paddingBlockEnd', 'paddingBlockStart', 'paddingInline',
+        'paddingInlineEnd', 'paddingInlineStart', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft',
+        'perspective', 'perspectiveOrigin', 'position',
+        'rotate', 'rowGap', 'scale',
+        'textIndent', 'transform', 'transformBox', 'transformOrigin', 'transition', 'translate',
+        'verticalAlign', 'visibility', 'whiteSpace',
+        'width', 'minWidth', 'maxWidth', 'wordSpacing', 'writingMode', 'zoom',
+    ];
+    const cssPropertyName = (property) => {
+        if (property === 'cssFloat')
+            return 'float';
+        const dashed = property.replace(/[A-Z]/g, character => `-${character.toLowerCase()}`);
+        return /^(webkit|moz|ms|o)-/.test(dashed) ? `-${dashed}` : dashed;
+    };
+    const instrumentDeclaration = (declaration) => {
+        if (instrumentedDeclarations.has(declaration))
+            return;
+        instrumentedDeclarations.add(declaration);
+        for (const property of GEOMETRY_DECLARATION_PROPERTIES) {
+            const descriptor = Object.getOwnPropertyDescriptor(declaration, property);
+            if (!descriptor?.configurable)
+                continue;
+            const cssName = cssPropertyName(property);
+            try {
+                Object.defineProperty(declaration, property, {
+                    configurable: true,
+                    enumerable: descriptor.enumerable,
+                    get() {
+                        return Reflect.apply(nativeGetPropertyValue, declaration, [cssName]);
+                    },
+                    set(value) {
+                        Reflect.apply(nativeSetProperty, declaration, [cssName, value == null ? '' : String(value), '']);
+                        markLayoutActivity();
+                    },
+                });
+            }
+            catch {
+                // The rule-style getter sampler below remains a bounded fallback.
+            }
+        }
+    };
+    const wrapRuleStyleGetter = (prototype) => {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, 'style');
+        const nativeGet = descriptor?.get;
+        if (!descriptor || !nativeGet)
+            return;
+        const wrappedGet = function () {
+            const declaration = Reflect.apply(nativeGet, this, []);
+            instrumentDeclaration(declaration);
+            // Also cover newly introduced CSS properties that are not yet in the
+            // explicit geometry list. Access starts one bounded settle window; it
+            // never creates persistent polling.
+            markLayoutActivity();
+            return declaration;
+        };
+        try {
+            Object.defineProperty(prototype, 'style', { ...descriptor, get: wrappedGet });
+        }
+        catch {
+            // Locked rule prototypes retain ResizeObserver/event fallbacks.
+        }
+    };
+    if (typeof CSSStyleSheet !== 'undefined') {
+        for (const method of ['insertRule', 'deleteRule', 'replace', 'replaceSync']) {
+            wrapLayoutMutator(CSSStyleSheet.prototype, method);
+        }
+    }
+    if (typeof CSSStyleDeclaration !== 'undefined') {
+        for (const method of ['setProperty', 'removeProperty']) {
+            wrapLayoutMutator(CSSStyleDeclaration.prototype, method);
         }
-        w.__geometraProxyObserverBootstrapped = true;
+        wrapLayoutSetter(CSSStyleDeclaration.prototype, 'cssText');
+    }
+    for (const constructorName of ['CSSStyleRule', 'CSSKeyframeRule', 'CSSFontFaceRule', 'CSSPageRule']) {
+        const constructor = global[constructorName];
+        if (constructor?.prototype)
+            wrapRuleStyleGetter(constructor.prototype);
+    }
+    const notifyEvent = () => notify();
+    const activityEvent = () => markLayoutActivity();
+    global.addEventListener('scroll', notifyEvent, { capture: true, passive: true });
+    global.addEventListener('resize', notifyEvent, { passive: true });
+    document.addEventListener('transitionrun', activityEvent, true);
+    document.addEventListener('transitionstart', activityEvent, true);
+    document.addEventListener('transitionend', activityEvent, true);
+    document.addEventListener('transitioncancel', activityEvent, true);
+    document.addEventListener('animationstart', activityEvent, true);
+    document.addEventListener('animationiteration', activityEvent, true);
+    document.addEventListener('animationend', activityEvent, true);
+    document.addEventListener('animationcancel', activityEvent, true);
+    document.addEventListener('load', event => {
+        const target = event.target;
+        if (target instanceof HTMLLinkElement && target.relList.contains('stylesheet')) {
+            markLayoutActivity();
+        }
+    }, true);
+    const fonts = document.fonts;
+    if (fonts) {
+        fonts.addEventListener('loading', activityEvent);
+        fonts.addEventListener('loadingdone', activityEvent);
+        fonts.addEventListener('loadingerror', activityEvent);
+        void fonts.ready.then(markLayoutActivity, notify);
+    }
+    // A Document can be observed before the parser creates documentElement, so
+    // install the mutation signal immediately and add resize targets once they
+    // exist.
+    observeRoot(document);
+    const installDocumentResizeTargets = () => {
+        if (document.documentElement)
+            observeResizeTarget(document.documentElement);
+        if (document.body)
+            observeResizeTarget(document.body);
+    };
+    if (document.documentElement) {
+        installDocumentResizeTargets();
+    }
+    else {
+        document.addEventListener('DOMContentLoaded', installDocumentResizeTargets, { once: true });
+    }
+    Object.defineProperty(global, INSTALL_STATE_KEY, {
+        value: installToken,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+async function bindDomObserverBridge(page, scheduleExtract) {
+    if (DOM_OBSERVER_BINDINGS.has(page))
+        return;
+    const installToken = randomBytes(32).toString('base64url');
+    const notifyBindingName = `__geometraProxyNotify_${installToken}`;
+    const installConfig = { installToken, notifyBindingName };
+    await page.exposeFunction(notifyBindingName, (urgency) => {
+        scheduleExtract(urgency === 'settled');
     });
+    // addInitScript is the critical path: it runs before application scripts in
+    // every subsequent main-frame and child-frame document.
+    await page.addInitScript(installPageFreshnessInstrumentation, installConfig);
+    // Also instrument a document that was already loaded before the bridge was
+    // bound. Closed roots created before this point cannot be recovered, which
+    // is why the runtime primes the bridge before its first navigation.
+    await Promise.all(page.frames().map(async (frame) => {
+        await frame.evaluate(installPageFreshnessInstrumentation, installConfig).catch(() => { });
+    }));
     DOM_OBSERVER_BINDINGS.add(page);
 }
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(',')}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+const ACTION_FINGERPRINT_TRANSPORT_KEYS = new Set([
+    'requestId',
+    'actionTimeoutMs',
+    'protocolVersion',
+    'geometryProtocolVersion',
+    'proxyActionProtocolVersion',
+]);
+function actionPayloadFingerprint(payload) {
+    const semanticPayload = Object.fromEntries(Object.entries(payload).filter(([key]) => !ACTION_FINGERPRINT_TRANSPORT_KEYS.has(key)));
+    return sha256(canonicalJson(semanticPayload));
+}
+export function createActionRequestLedger(maxEntries = DEFAULT_ACTION_REQUEST_LEDGER_ENTRIES) {
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new Error('Action request ledger size must be a positive safe integer');
+    }
+    const entries = new Map();
+    return {
+        remember(requestId, payload) {
+            // Hash request IDs as well as payloads so every retained entry has a
+            // fixed upper memory bound even when a peer sends an unusually long ID.
+            const requestKey = sha256(requestId);
+            const payloadFingerprint = actionPayloadFingerprint(payload);
+            const remembered = entries.get(requestKey);
+            if (remembered !== undefined) {
+                return remembered.fingerprint === payloadFingerprint ? 'duplicate' : 'conflict';
+            }
+            if (entries.size >= maxEntries) {
+                // Terminal means only that the handler returned; it does not prove
+                // the controller received the correlated ACK. Never evict a request
+                // ID within a runtime, or an ambiguous retry could mutate twice.
+                return 'capacity';
+            }
+            entries.set(requestKey, { fingerprint: payloadFingerprint, state: 'live' });
+            return 'accepted';
+        },
+        complete(requestId) {
+            const requestKey = sha256(requestId);
+            const remembered = entries.get(requestKey);
+            if (!remembered || remembered.state === 'terminal')
+                return;
+            entries.delete(requestKey);
+            entries.set(requestKey, { ...remembered, state: 'terminal' });
+        },
+    };
+}
+const MUTATING_CLIENT_MESSAGE_TYPES = new Set([
+    'event',
+    'key',
+    'typeText',
+    'resize',
+    'navigate',
+    'composition',
+    'file',
+    'setFieldText',
+    'setFieldChoice',
+    'fillFields',
+    'fillOtp',
+    'listboxPick',
+    'selectOption',
+    'setChecked',
+    'wheel',
+    'pdfGenerate',
+]);
+function isMutatingClientMessage(msg) {
+    return MUTATING_CLIENT_MESSAGE_TYPES.has(msg.type);
+}
+class ActionDeadlineExpiredError extends Error {
+}
+function assertActionDeadline(msg, receivedAt) {
+    if (!isMutatingClientMessage(msg))
+        return;
+    const actionTimeoutMs = msg.actionTimeoutMs;
+    if (actionTimeoutMs !== undefined && performance.now() - receivedAt >= actionTimeoutMs) {
+        throw new ActionDeadlineExpiredError('Action deadline expired; request was not executed');
+    }
+}
 function isProtocolCompatible(peerVersion) {
     if (peerVersion === undefined)
         return true;
@@ -50,6 +580,38 @@ function isProtocolCompatible(peerVersion) {
         return false;
     return peerVersion <= PROXY_PROTOCOL_VERSION;
 }
+function generatedAuthToken() {
+    return randomBytes(32).toString('base64url');
+}
+function normalizedAuthToken(value) {
+    const token = value?.trim() || generatedAuthToken();
+    if (token.length < 32) {
+        throw new Error('geometra-proxy authToken must contain at least 32 characters');
+    }
+    return token;
+}
+function bearerTokenMatches(header, expected) {
+    if (!header?.startsWith('Bearer '))
+        return false;
+    const received = header.slice('Bearer '.length);
+    const receivedBytes = Buffer.from(received);
+    const expectedBytes = Buffer.from(expected);
+    return receivedBytes.length === expectedBytes.length && timingSafeEqual(receivedBytes, expectedBytes);
+}
+function protocolCompatibilityError(msg) {
+    const record = msg;
+    const geometryVersion = record.geometryProtocolVersion;
+    if (geometryVersion !== undefined && (typeof geometryVersion !== 'number' ||
+        !Number.isFinite(geometryVersion) ||
+        geometryVersion > GEOMETRY_PROTOCOL_VERSION)) {
+        return `Client geometry protocol ${String(geometryVersion)} is newer than proxy geometry protocol ${GEOMETRY_PROTOCOL_VERSION}`;
+    }
+    const actionVersion = record.proxyActionProtocolVersion ?? record.protocolVersion;
+    if (!isProtocolCompatible(actionVersion)) {
+        return `Client proxy-action protocol ${String(actionVersion)} is newer than proxy action protocol ${PROXY_ACTION_PROTOCOL_VERSION}`;
+    }
+    return null;
+}
 function cloneLayout(layout) {
     return structuredClone(layout);
 }
@@ -105,13 +667,15 @@ async function applyKeyPhase(page, msg) {
     if (msg.shiftKey)
         await page.keyboard.up('Shift');
 }
-export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache, waitForBeforeInput, onViewportOrInput, onHandlerError) {
-    const sendWireError = (message, requestId) => {
+export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache, waitForBeforeInput, onViewportOrInput, onHandlerError, security) {
+    const receivedAt = security?.receivedAt ?? performance.now();
+    const sendWireError = (message, requestId, code) => {
         ws.send(JSON.stringify({
             type: 'error',
             message,
+            ...(code ? { code } : {}),
             ...(requestId ? { requestId } : {}),
-            protocolVersion: PROXY_PROTOCOL_VERSION,
+            ...PROXY_ACTION_METADATA,
         }));
     };
     let parsed;
@@ -131,9 +695,9 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
         return;
     }
     const msg = parsed;
-    const pv = 'protocolVersion' in msg ? msg.protocolVersion : undefined;
-    if (!isProtocolCompatible(pv)) {
-        sendWireError(`Client protocol ${String(pv)} is newer than proxy protocol ${PROXY_PROTOCOL_VERSION}`, requestId);
+    const compatibilityError = protocolCompatibilityError(msg);
+    if (compatibilityError) {
+        sendWireError(compatibilityError, requestId);
         return;
     }
     const validationError = clientMessageValidationError(msg);
@@ -141,18 +705,46 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
         sendWireError(validationError, requestId);
         return;
     }
+    // Reserve the request ID before consulting its deadline. An expired replay
+    // must be reported as a duplicate/conflict and must never become eligible
+    // to mutate merely because the original deadline elapsed.
+    let acceptedRequestId;
+    if (requestId && isMutatingClientMessage(msg) && security?.actionRequestLedger) {
+        const reservation = security.actionRequestLedger.remember(requestId, msg);
+        if (reservation === 'duplicate') {
+            sendWireError('Duplicate requestId; action was not repeated', requestId, 'DUPLICATE_REQUEST');
+            return;
+        }
+        if (reservation === 'conflict') {
+            sendWireError('requestId was already used with a different payload; action was not executed', requestId, 'REQUEST_ID_CONFLICT');
+            return;
+        }
+        if (reservation === 'capacity') {
+            sendWireError('Action request ledger is at capacity; action was not executed. Close and reconnect the proxy runtime before sending more actions.', requestId, 'REQUEST_LEDGER_CAPACITY');
+            return;
+        }
+        acceptedRequestId = requestId;
+    }
     try {
+        // These guards do not cancel an action that already started. They prevent
+        // queued work from beginning after the receipt-relative timeout.
+        assertActionDeadline(msg, receivedAt);
         const page = await waitForPage();
+        assertActionDeadline(msg, receivedAt);
         if (isResizeMessage(msg)) {
             const w = Math.max(1, Math.floor(msg.width));
             const h = Math.max(1, Math.floor(msg.height));
+            assertActionDeadline(msg, receivedAt);
             await page.setViewportSize({ width: w, height: h });
             onViewportOrInput('resize', requestId);
             return;
         }
+        assertActionDeadline(msg, receivedAt);
         await waitForBeforeInput();
+        assertActionDeadline(msg, receivedAt);
         if (isNavigateMessage(msg)) {
             clearFillLookupCache(fieldLookupCache);
+            assertActionDeadline(msg, receivedAt);
             await page.goto(msg.url, { waitUntil: 'domcontentloaded', timeout: 60_000 });
             onViewportOrInput('input', requestId, { pageUrl: page.url() });
             return;
@@ -169,6 +761,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
                 // "session crashed for unknown reason". Bug surfaced by JobForge
                 // round-2 marathon — Cloudflare FDE NYC #312 and Airtable PM AI #94.
                 const urlBefore = page.url();
+                assertActionDeadline(msg, receivedAt);
                 await page.mouse.click(x, y);
                 // Give the navigation a brief window to start. We don't await
                 // waitForNavigation here because most clicks DON'T navigate, and
@@ -199,26 +792,37 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isKeyMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             await applyKeyPhase(page, msg);
             onViewportOrInput('input', requestId);
             return;
         }
+        if (isTypeTextMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
+            await page.keyboard.type(msg.text);
+            onViewportOrInput('input', requestId);
+            return;
+        }
         if (isCompositionMessage(msg)) {
             const data = typeof msg.data === 'string' ? msg.data : '';
             if (msg.eventType === 'onCompositionUpdate' || msg.eventType === 'onCompositionEnd') {
+                assertActionDeadline(msg, receivedAt);
                 await page.keyboard.insertText(data);
                 onViewportOrInput('input', requestId);
             }
             return;
         }
         if (isFileMessage(msg)) {
-            const paths = resolveExistingFiles(msg.paths);
+            const paths = resolveExistingFiles(msg.paths, security?.allowedFileRoots);
+            assertActionDeadline(msg, receivedAt);
             await attachFiles(page, paths, {
                 clickX: msg.x,
                 clickY: msg.y,
                 fieldId: msg.fieldId,
                 fieldKey: msg.fieldKey,
                 fieldLabel: msg.fieldLabel,
+                contextText: msg.contextText,
+                sectionText: msg.sectionText,
                 exact: msg.exact,
                 strategy: msg.strategy,
                 dropX: msg.dropX,
@@ -228,6 +832,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isSetFieldTextMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             await setFieldText(page, msg.fieldLabel, msg.value, {
                 fieldId: msg.fieldId,
                 fieldKey: msg.fieldKey,
@@ -240,6 +845,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isSetFieldChoiceMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             await setFieldChoice(page, msg.fieldLabel, msg.value, {
                 fieldId: msg.fieldId,
                 fieldKey: msg.fieldKey,
@@ -253,12 +859,17 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isFillFieldsMessage(msg)) {
-            await fillFields(page, msg.fields, fieldLookupCache);
+            const authorizedFields = msg.fields.map(field => field.kind === 'file'
+                ? { ...field, paths: resolveExistingFiles(field.paths, security?.allowedFileRoots) }
+                : field);
+            assertActionDeadline(msg, receivedAt);
+            await fillFields(page, authorizedFields, fieldLookupCache);
             const result = await fillFieldsAckResult(page);
             onViewportOrInput('input', requestId, result);
             return;
         }
         if (isFillOtpMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             const result = await fillOtp(page, msg.value, {
                 fieldLabel: msg.fieldLabel,
                 perCharDelayMs: msg.perCharDelayMs,
@@ -271,6 +882,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isListboxPickMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             await pickListboxOption(page, msg.label, {
                 exact: msg.exact,
                 openX: msg.openX,
@@ -285,6 +897,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isSelectOptionMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             await selectNativeOption(page, msg.x, msg.y, {
                 value: msg.value,
                 label: msg.label,
@@ -294,6 +907,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             return;
         }
         if (isSetCheckedMessage(msg)) {
+            assertActionDeadline(msg, receivedAt);
             await setCheckedControl(page, msg.label, {
                 fieldKey: msg.fieldKey,
                 checked: msg.checked,
@@ -310,6 +924,7 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             const dy = typeof msg.deltaY === 'number' && Number.isFinite(msg.deltaY) ? msg.deltaY : 0;
             const x = typeof msg.x === 'number' && Number.isFinite(msg.x) ? msg.x : undefined;
             const y = typeof msg.y === 'number' && Number.isFinite(msg.y) ? msg.y : undefined;
+            assertActionDeadline(msg, receivedAt);
             await wheelAt(page, dx, dy, x, y);
             onViewportOrInput('input', requestId);
             return;
@@ -327,8 +942,10 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
             const marginValue = msg.margin ?? '1cm';
             const margin = { top: marginValue, right: marginValue, bottom: marginValue, left: marginValue };
             if (msg.html) {
+                assertActionDeadline(msg, receivedAt);
                 await page.setContent(msg.html, { waitUntil: 'networkidle', timeout: 30_000 });
             }
+            assertActionDeadline(msg, receivedAt);
             const buffer = await page.pdf({
                 format,
                 landscape,
@@ -342,8 +959,17 @@ export async function handleClientMessage(waitForPage, ws, raw, fieldLookupCache
         sendWireError(`Unsupported client message type "${msg.type}"`, requestId);
     }
     catch (err) {
-        onHandlerError(err);
-        sendWireError(err instanceof Error ? err.message : String(err), requestId);
+        if (!(err instanceof ActionDeadlineExpiredError))
+            onHandlerError(err);
+        sendWireError(err instanceof Error ? err.message : String(err), requestId, err instanceof ActionDeadlineExpiredError
+            ? 'ACTION_EXPIRED'
+            : acceptedRequestId
+                ? 'ACTION_OUTCOME_AMBIGUOUS'
+                : undefined);
+    }
+    finally {
+        if (acceptedRequestId)
+            security?.actionRequestLedger?.complete(acceptedRequestId);
     }
 }
 async function fillFieldsAckResult(page) {
@@ -355,9 +981,11 @@ async function fillFieldsAckResult(page) {
     // or similar. Counting both gives fill_form a reliable signal for whether
     // a custom dropdown commit actually landed, which is the authoritative
     // check used throughout the listbox pick pipeline (see readAriaInvalid in
-    // dom-actions.ts). The `:is()` selector de-duplicates the two passes so
-    // elements that match both just count once.
-    const invalidSelector = ':is(:invalid, [aria-invalid="true"]:is(input, textarea, select, [role="combobox"], [role="listbox"], [role="spinbutton"], [role="searchbox"], [role="textbox"]))';
+    // dom-actions.ts). Restrict native validity to actual controls because
+    // `:invalid` also matches ancestor <form> and <fieldset> elements whenever
+    // one descendant is invalid. The outer `:is()` de-duplicates controls that
+    // also advertise aria-invalid.
+    const invalidSelector = ':is(:is(input, textarea, select):invalid, [aria-invalid="true"]:is(input, textarea, select, [role="combobox"], [role="listbox"], [role="spinbutton"], [role="searchbox"], [role="textbox"]))';
     const [invalidCount, alertCount, dialogCount, busyCount] = await Promise.all([
         countAcrossFrames(frames, invalidSelector),
         countAcrossFrames(frames, '[role="alert"], [role="alertdialog"]'),
@@ -455,12 +1083,53 @@ async function countAcrossFrames(frames, selector) {
 }
 export function startGeometryWebSocket(options) {
     const debounceMs = options.debounceMs ?? 50;
+    const host = options.host?.trim() || DEFAULT_PROXY_HOST;
+    const authToken = normalizedAuthToken(options.authToken);
+    const allowedOrigins = new Set(options.allowedOrigins ?? []);
     const clients = new Set();
-    const wss = new WebSocketServer({ port: options.port });
-    const axSessionManager = createCdpAxSessionManager();
+    let controllerClaimed = false;
+    const wss = new WebSocketServer({
+        port: options.port,
+        host,
+        maxPayload: Math.max(1024, options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES),
+        verifyClient(info, done) {
+            const origin = typeof info.req.headers.origin === 'string' ? info.req.headers.origin : undefined;
+            if (origin !== undefined && !allowedOrigins.has(origin)) {
+                done(false, 403, 'WebSocket Origin is not allowed');
+                return;
+            }
+            const authorization = typeof info.req.headers.authorization === 'string'
+                ? info.req.headers.authorization
+                : undefined;
+            if (!bearerTokenMatches(authorization, authToken)) {
+                done(false, 401, 'Bearer capability required');
+                return;
+            }
+            const liveController = Array.from(clients).some(client => client.readyState === client.OPEN || client.readyState === client.CONNECTING);
+            // Permit a clean handover while the prior controller is already
+            // CLOSING; reject both a live controller and a concurrent handshake.
+            if (controllerClaimed && (clients.size === 0 || liveController)) {
+                done(false, 409, 'A Geometra controller is already connected');
+                return;
+            }
+            controllerClaimed = true;
+            done(true);
+        },
+    });
+    let closing = false;
+    const axSessionManager = createCdpAxSessionManager(() => {
+        if (!closing)
+            scheduleExtract(true);
+    });
     let prevLayout = null;
     let prevTreeJson = null;
     let debounceTimer = null;
+    let inputAckFlushTimer = null;
+    let immediateExtractTimer = null;
+    let axRetryTimer = null;
+    let axRetryDueAtMs = Number.POSITIVE_INFINITY;
+    let immediateExtractRequestedAfterActive = false;
+    let lastExtractCompletedAtMs = Number.NEGATIVE_INFINITY;
     let extracting = false;
     let pendingExtract = false;
     let extractSequence = 0;
@@ -468,6 +1137,7 @@ export function startGeometryWebSocket(options) {
     let actionQueue = Promise.resolve();
     let pendingInputAcks = [];
     const fieldLookupCache = createFillLookupCache();
+    const actionRequestLedger = createActionRequestLedger();
     const beforeInput = options.beforeInput?.then(() => undefined);
     const trace = { extractCount: 0 };
     const pagePromise = Promise.resolve(options.page);
@@ -500,14 +1170,20 @@ export function startGeometryWebSocket(options) {
                     type: 'ack',
                     ...(requestId ? { requestId } : {}),
                     ...(result !== undefined ? { result } : {}),
-                    protocolVersion: PROXY_PROTOCOL_VERSION,
+                    ...PROXY_ACTION_METADATA,
                 }));
             }
         }
+        if (pendingInputAcks.length === 0) {
+            clearInputAckFlushTimer();
+        }
+        else {
+            armInputAckFlushTimer();
+        }
     }
     function sendPendingInputErrors(message) {
         if (pendingInputAcks.length === 0) {
-            const errText = JSON.stringify({ type: 'error', message, protocolVersion: PROXY_PROTOCOL_VERSION });
+            const errText = JSON.stringify({ type: 'error', message, ...PROXY_ACTION_METADATA });
             for (const ws of clients) {
                 if (ws.readyState === ws.OPEN)
                     ws.send(errText);
@@ -516,13 +1192,15 @@ export function startGeometryWebSocket(options) {
         }
         const pending = pendingInputAcks;
         pendingInputAcks = [];
+        clearInputAckFlushTimer();
         for (const { ws, requestId } of pending) {
             if (ws.readyState === ws.OPEN) {
                 ws.send(JSON.stringify({
                     type: 'error',
                     message,
+                    code: 'ACTION_OUTCOME_AMBIGUOUS',
                     ...(requestId ? { requestId } : {}),
-                    protocolVersion: PROXY_PROTOCOL_VERSION,
+                    ...PROXY_ACTION_METADATA,
                 }));
             }
         }
@@ -535,7 +1213,7 @@ export function startGeometryWebSocket(options) {
                 type: 'frame',
                 layout: snap.layout,
                 tree: snap.tree,
-                protocolVersion: PROXY_PROTOCOL_VERSION,
+                ...PROXY_GEOMETRY_METADATA,
             };
             prevLayout = cloneLayout(snap.layout);
             prevTreeJson = snap.treeJson;
@@ -551,11 +1229,11 @@ export function startGeometryWebSocket(options) {
                     type: 'frame',
                     layout: snap.layout,
                     tree: snap.tree,
-                    protocolVersion: PROXY_PROTOCOL_VERSION,
+                    ...PROXY_GEOMETRY_METADATA,
                 };
             }
             else {
-                outbound = { type: 'patch', patches, protocolVersion: PROXY_PROTOCOL_VERSION };
+                outbound = { type: 'patch', patches, ...PROXY_GEOMETRY_METADATA };
             }
             prevLayout = cloneLayout(snap.layout);
             prevTreeJson = snap.treeJson;
@@ -583,7 +1261,7 @@ export function startGeometryWebSocket(options) {
             };
             const page = await waitForPage();
             const extractStartedAt = performance.now();
-            const snap = await extractGeometryWithRecovery(page, axSessionManager, extractorTrace, recoveryTrace);
+            const snap = await extractGeometryWithRecovery(page, axSessionManager, extractorTrace, recoveryTrace, () => scheduleExtract(true), delayMs => scheduleAxRetry(delayMs));
             const extractMs = performance.now() - extractStartedAt;
             const broadcastStartedAt = performance.now();
             const changed = broadcastSnapshot(snap);
@@ -631,20 +1309,113 @@ export function startGeometryWebSocket(options) {
         }
         finally {
             extracting = false;
+            lastExtractCompletedAtMs = performance.now();
+            if (immediateExtractRequestedAfterActive) {
+                immediateExtractRequestedAfterActive = false;
+                armImmediateExtract();
+            }
         }
         return changed;
     }
-    function scheduleExtract() {
-        if (debounceTimer !== null)
+    function clearDebounceTimer() {
+        if (debounceTimer !== null) {
             clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(() => {
             debounceTimer = null;
-            void runExtractQueued()
-                .then(() => {
-                sendPendingInputAcks();
-            })
-                .catch(err => options.onError?.(err));
-        }, debounceMs);
+        }
+    }
+    function clearInputAckFlushTimer() {
+        if (inputAckFlushTimer !== null) {
+            clearTimeout(inputAckFlushTimer);
+            inputAckFlushTimer = null;
+        }
+    }
+    function clearImmediateExtractTimer() {
+        if (immediateExtractTimer !== null) {
+            clearTimeout(immediateExtractTimer);
+            immediateExtractTimer = null;
+        }
+        immediateExtractRequestedAfterActive = false;
+    }
+    function clearAxRetryTimer() {
+        if (axRetryTimer !== null) {
+            clearTimeout(axRetryTimer);
+            axRetryTimer = null;
+        }
+        axRetryDueAtMs = Number.POSITIVE_INFINITY;
+    }
+    function scheduleAxRetry(delayMs) {
+        const boundedDelayMs = Math.max(1, Math.ceil(delayMs));
+        const dueAtMs = performance.now() + boundedDelayMs;
+        if (axRetryTimer !== null && dueAtMs >= axRetryDueAtMs)
+            return;
+        clearAxRetryTimer();
+        axRetryDueAtMs = dueAtMs;
+        axRetryTimer = setTimeout(() => {
+            axRetryTimer = null;
+            axRetryDueAtMs = Number.POSITIVE_INFINITY;
+            scheduleExtract(true);
+        }, boundedDelayMs);
+    }
+    function runScheduledExtract() {
+        void runExtractQueued()
+            .then(() => {
+            sendPendingInputAcks();
+        })
+            .catch(err => options.onError?.(err));
+    }
+    function flushDebouncedExtract() {
+        clearDebounceTimer();
+        runScheduledExtract();
+    }
+    function armInputAckFlushTimer() {
+        if (pendingInputAcks.length === 0 || inputAckFlushTimer !== null)
+            return;
+        // This timer is anchored to the first pending action ack and is never
+        // reset by page mutations. Mutation-only traffic does not arm it, so an
+        // animated page retains the normal trailing-edge debounce behavior.
+        inputAckFlushTimer = setTimeout(() => {
+            inputAckFlushTimer = null;
+            if (pendingInputAcks.length === 0)
+                return;
+            clearDebounceTimer();
+            runScheduledExtract();
+        }, MAX_INPUT_ACK_LATENCY_MS);
+    }
+    function armImmediateExtract() {
+        if (extracting) {
+            // Do not turn a page hint into runExtractQueued's pending loop. One
+            // coalesced refresh becomes eligible only after the active extraction
+            // completes and the host has had a cooldown window.
+            immediateExtractRequestedAfterActive = true;
+            return;
+        }
+        if (immediateExtractTimer !== null)
+            return;
+        const elapsed = performance.now() - lastExtractCompletedAtMs;
+        const remaining = Math.max(0, MIN_IMMEDIATE_EXTRACT_INTERVAL_MS - elapsed);
+        if (remaining === 0) {
+            runScheduledExtract();
+            return;
+        }
+        immediateExtractTimer = setTimeout(() => {
+            immediateExtractTimer = null;
+            if (extracting) {
+                immediateExtractRequestedAfterActive = true;
+            }
+            else {
+                runScheduledExtract();
+            }
+        }, remaining);
+    }
+    function scheduleExtract(immediate = false) {
+        if (immediate) {
+            clearDebounceTimer();
+            armImmediateExtract();
+            return;
+        }
+        if (debounceTimer !== null)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(flushDebouncedExtract, debounceMs);
     }
     wss.on('listening', () => {
         const addr = wss.address();
@@ -656,6 +1427,13 @@ export function startGeometryWebSocket(options) {
     });
     wss.on('connection', (ws) => {
         clients.add(ws);
+        // Authentication happens during the HTTP upgrade, but MCP still needs a
+        // protocol-level attestation before it can trust a spawned proxy. Send it
+        // immediately so lazy extraction can remain lazy without weakening the
+        // capability handshake.
+        if (ws.readyState === ws.OPEN) {
+            ws.send(JSON.stringify({ type: 'hello', ...PROXY_GEOMETRY_METADATA }));
+        }
         if (prevLayout && prevTreeJson !== null) {
             const snap = {
                 layout: prevLayout,
@@ -666,16 +1444,29 @@ export function startGeometryWebSocket(options) {
                 type: 'frame',
                 layout: snap.layout,
                 tree: snap.tree,
-                protocolVersion: PROXY_PROTOCOL_VERSION,
+                ...PROXY_GEOMETRY_METADATA,
             });
             if (ws.readyState === ws.OPEN)
                 ws.send(text);
         }
         ws.on('message', (raw) => {
+            // Capture receipt before queueing so actionTimeoutMs includes time spent
+            // waiting behind earlier Playwright work and uses this host's monotonic
+            // clock rather than trusting the controller's wall clock.
+            const receivedAt = performance.now();
             actionQueue = actionQueue
                 .then(() => handleClientMessage(waitForPage, ws, raw, fieldLookupCache, waitForBeforeInput, (kind, requestId, result) => {
                 if (kind === 'resize') {
-                    void runExtractQueued();
+                    if (requestId) {
+                        pendingInputAcks.push({
+                            ws,
+                            requestId,
+                            afterExtractSequence: extractSequence,
+                        });
+                    }
+                    void runExtractQueued()
+                        .then(() => sendPendingInputAcks())
+                        .catch(err => options.onError?.(err));
                 }
                 else {
                     pendingInputAcks.push({
@@ -685,36 +1476,48 @@ export function startGeometryWebSocket(options) {
                         ...(result !== undefined ? { result } : {}),
                     });
                     scheduleExtract();
+                    armInputAckFlushTimer();
                 }
-            }, err => options.onError?.(err)))
+            }, err => options.onError?.(err), { allowedFileRoots: options.allowedFileRoots, actionRequestLedger, receivedAt }))
                 .catch(err => options.onError?.(err));
         });
         ws.on('close', () => {
             clients.delete(ws);
+            controllerClaimed = clients.size > 0;
             pendingInputAcks = pendingInputAcks.filter(entry => entry.ws !== ws);
+            if (pendingInputAcks.length === 0)
+                clearInputAckFlushTimer();
         });
     });
     return {
+        authToken,
+        host,
         scheduleExtract,
         flushExtract: async () => {
             await actionQueue.catch(() => { });
-            if (debounceTimer !== null) {
-                clearTimeout(debounceTimer);
-                debounceTimer = null;
-            }
+            clearDebounceTimer();
+            clearInputAckFlushTimer();
+            clearImmediateExtractTimer();
             await runExtractQueued();
             sendPendingInputAcks();
         },
         getTrace: () => structuredClone(trace),
-        close: () => new Promise((resolve, reject) => {
-            void axSessionManager.close().finally(() => {
-                for (const ws of clients) {
-                    ws.close();
-                }
-                clients.clear();
-                wss.close(err => (err ? reject(err) : resolve()));
+        close: () => {
+            closing = true;
+            return new Promise((resolve, reject) => {
+                void axSessionManager.close().finally(() => {
+                    clearDebounceTimer();
+                    clearInputAckFlushTimer();
+                    clearImmediateExtractTimer();
+                    clearAxRetryTimer();
+                    for (const ws of clients) {
+                        ws.close();
+                    }
+                    clients.clear();
+                    wss.close(err => (err ? reject(err) : resolve()));
+                });
             });
-        }),
+        },
     };
 }
 export async function primeDomObserver(page, scheduleExtract) {
@@ -722,27 +1525,12 @@ export async function primeDomObserver(page, scheduleExtract) {
 }
 export async function installDomObserver(page, scheduleExtract) {
     await bindDomObserverBridge(page, scheduleExtract);
-    await page.evaluate(() => {
-        const w = window;
-        if (w.__geometraProxyObserverInstalled)
-            return;
-        const observer = new MutationObserver(() => {
-            void w.__geometraProxyNotify?.();
-        });
-        observer.observe(document.documentElement, {
-            subtree: true,
-            childList: true,
-            attributes: true,
-            characterData: true,
-        });
-        w.__geometraProxyObserverInstalled = true;
-    });
 }
 function isNavigationTransitionError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return /Execution context was destroyed|Cannot find context with specified id|Frame was detached|navigation/i.test(message);
 }
-async function extractGeometryWithRecovery(page, axSessionManager, extractTrace, recoveryTrace) {
+async function extractGeometryWithRecovery(page, axSessionManager, extractTrace, recoveryTrace, onAxReady, onAxRetryDue) {
     let lastNavigationError = null;
     let domContentLoadedWaitMs = 0;
     let loadWaitMs = 0;
@@ -751,7 +1539,12 @@ async function extractGeometryWithRecovery(page, axSessionManager, extractTrace,
             if (recoveryTrace) {
                 recoveryTrace.attemptCount = attempt + 1;
             }
-            return await extractGeometry(page, { axSessionManager, trace: extractTrace });
+            return await extractGeometry(page, {
+                axSessionManager,
+                trace: extractTrace,
+                onAxReady,
+                onAxRetryDue,
+            });
         }
         catch (err) {
             if (page.isClosed() || !isNavigationTransitionError(err))