@geometra/mcp 1.19.22 → 1.20.0

package/README.md

@@ -24,18 +24,20 @@ Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a sm
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; can inline `formSchema` and/or `pageModel` for lower-turn starts |
-| `geometra_query` | Find elements by stable id, role, name, text content, ancestor/prompt context, current value, or semantic state such as `invalid`, `required`, or `busy` |
+| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; can inline `formSchema` and/or `pageModel`, or defer the page model for a faster first connect response |
+| `geometra_prepare_browser` | Pre-launch and pre-navigate a reusable proxy/browser for `pageUrl` without creating an active session; best when the agent can prepare before the user-facing task starts |
+| `geometra_query` | Find elements by stable id, role, name, text content, prompt/section/item context, current value, or semantic state such as `invalid`, `required`, or `busy` |
 | `geometra_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.). **Strict parameters** — use `text` plus `present: false` to wait until a substring disappears (e.g. “Parsing your resume”); there is no `textGone` field |
 | `geometra_wait_for_resume_parse` | Convenience wait until a parsing banner is gone (defaults: `text`: `"Parsing"`, `present` implied false). Same engine as `geometra_wait_for` |
 | `geometra_form_schema` | Compact, fill-oriented form schema with stable field ids and collapsed radio/button groups; can auto-connect from `pageUrl` / `url` |
 | `geometra_fill_form` | Fill a form from `valuesById` / `valuesByLabel` in one MCP call; can auto-connect from `pageUrl` / `url` for the lowest-token known-form path |
-| `geometra_fill_fields` | Fill text/choice/toggle/file fields in one MCP call; text/choice/toggle entries can use `fieldId` from `geometra_form_schema` without repeating the label |
-| `geometra_run_actions` | Execute a batch of high-level actions in one MCP round trip and get one consolidated result, with optional final-only output |
-| `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
+| `geometra_fill_fields` | Fill text/choice/toggle/file fields in one MCP call; text-only batches now use the proxy fast path when step output is omitted, and text/choice/toggle entries can use `fieldId` from `geometra_form_schema` without repeating the label |
+| `geometra_run_actions` | Execute a batch of high-level actions in one MCP round trip; can auto-connect from `pageUrl` / `url` and return a final-only payload for the smallest multi-step responses |
+| `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, and primary actions with nearby section/item context when available |
+| `geometra_find_action` | Resolve a repeated button/link by action label plus optional `sectionText`, `promptText`, or `itemText` before clicking |
 | `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand, with paging/filtering for long sections |
 | `geometra_reveal` | Scroll until a matching node is visible instead of guessing wheel deltas; auto-scales reveal steps for tall forms when omitted |
-| `geometra_click` | Click by coordinates or semantic target, optionally waiting for a post-click semantic condition |
+| `geometra_click` | Click by coordinates or semantic target, including repeated-action disambiguation with `promptText`, `sectionText`, or `itemText`, optionally waiting for a post-click semantic condition |
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
 | `geometra_upload_files` | Attach files: labeled field / auto / hidden input / native chooser / synthetic drop (`@geometra/proxy` only) |
@@ -323,10 +325,11 @@ Agent:  geometra_query({ role: "button", name: "Save" })
 5. **`geometra_form_schema`** is the compact form-specific path: stable field ids, required/invalid state, current values, and collapsed choice groups without layout-heavy section detail. It can auto-connect when you pass `pageUrl` / `url`.
 6. **`geometra_fill_form`** turns a compact values object into semantic field operations server-side, so the model does not need to emit one tool call per field. It can also auto-connect, which collapses “open page + fill known values” into a single tool call.
 7. **`geometra_fill_fields`** is the lower-level field-intent path when you need direct control; text / choice / toggle entries can now resolve `fieldId` from `geometra_form_schema` without repeating labels.
-8. **`geometra_page_model`** is still the right summary-first path for non-form exploration: page archetypes, stable section ids, counts, top-level landmarks/forms/dialogs/lists, and a few primary actions.
-9. **`geometra_expand_section`** fetches richer details only for the section you care about (fields, actions, headings, nested lists, list items, text preview).
-10. After interactions, action tools return a **semantic delta** when possible (dialogs opened/closed, forms appeared/removed, list counts changed, named/focusable nodes added/removed/updated). If nothing meaningful changed, they fall back to a short current-UI overview.
-11. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
+8. **`geometra_page_model`** is still the right summary-first path for non-form exploration: page archetypes, stable section ids, counts, top-level landmarks/forms/dialogs/lists, and a few primary actions with nearby context.
+9. **`geometra_find_action`** is the narrow repeated-action resolver when the page has many identical buttons/links and you want one exact target by `itemText`, `sectionText`, or `promptText`.
+10. **`geometra_expand_section`** fetches richer details only for the section you care about (fields, actions, headings, nested lists, list items, text preview).
+11. After interactions, action tools return a **semantic delta** when possible (dialogs opened/closed, forms appeared/removed, list counts changed, named/focusable nodes added/removed/updated). If nothing meaningful changed, they fall back to a short current-UI overview.
+12. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
 
 ## Long Forms
 
@@ -338,9 +341,12 @@ For long application flows, prefer one of these patterns:
 4. `geometra_snapshot({ view: "form-required" })` when you need the remaining required fields including offscreen ones
 5. `geometra_reveal` for far-below-fold targets such as submit buttons (auto-scales reveal steps when you omit `maxSteps`)
 6. `geometra_click({ ..., waitFor: ... })` when one action should also wait for the next semantic state
-7. `geometra_run_actions` when you need mixed navigation + waits + field entry
-8. `geometra_connect({ pageUrl, returnPageModel: true })` when you want connect + summary-first exploration in one turn
-9. `geometra_page_model` + `geometra_expand_section` when you are still exploring the page rather than filling it
+7. `geometra_prepare_browser({ pageUrl, headless, width, height })` when you can hide browser startup before the real task and want the next proxy-backed flow to attach warm
+8. `geometra_run_actions` when you need mixed navigation + waits + field entry, especially with `pageUrl` / `url` for a one-call flow
+9. `geometra_connect({ pageUrl, returnPageModel: true })` when you want connect + summary-first exploration in one turn
+10. `geometra_connect({ pageUrl, returnPageModel: true, pageModelMode: "deferred" })` when first-response latency matters more than inlining the page model; follow with `geometra_page_model`
+11. `geometra_find_action` or `geometra_click({ name, itemText / sectionText / promptText, ... })` when the target action repeats across cards/rows
+12. `geometra_page_model` + `geometra_expand_section` when you are still exploring the page rather than filling it
 
 Typical batch:
 
@@ -355,12 +361,14 @@ Typical batch:
 }
 ```
 
-Single action tools now default to terse summaries. Pass `detail: "verbose"` when you need a fuller current-UI fallback for debugging.
+Single action tools default to short human-readable summaries (`detail: "minimal"`). Use `detail: "terse"` for the smallest machine-friendly JSON responses, or `detail: "verbose"` when you need a fuller current-UI fallback for debugging.
 
 For the smallest long-form responses, prefer:
 
-1. `detail: "minimal"` for structured step metadata instead of narrated deltas
+1. `detail: "terse"` for compact machine-friendly action responses
 2. `includeSteps: false` when you only need aggregate success/error counts plus the final validation/state payload
+3. `output: "final"` on `geometra_run_actions` when you only need completion state plus the final semantic signals
+4. `geometra_prepare_browser` before the flow when you can shift browser launch out of the user-visible task window
 
 Typical low-token form fill:
 

package/dist/__tests__/proxy-session-recovery.test.js

@@ -8,7 +8,7 @@ vi.mock('../proxy-spawn.js', () => ({
     startEmbeddedGeometraProxy: mockState.startEmbeddedGeometraProxy,
     spawnGeometraProxy: mockState.spawnGeometraProxy,
 }));
-const { connectThroughProxy, disconnect } = await import('../session.js');
+const { connectThroughProxy, disconnect, prewarmProxy } = await import('../session.js');
 function frame(pageUrl) {
     return {
         type: 'frame',
@@ -28,12 +28,17 @@ function frame(pageUrl) {
 async function createProxyPeer(options) {
     const wss = new WebSocketServer({ port: 0 });
     wss.on('connection', ws => {
-        ws.send(JSON.stringify(frame(options?.pageUrl ?? 'https://jobs.example.com/original')));
+        if (options?.sendInitialFrame !== false) {
+            ws.send(JSON.stringify(frame(options?.pageUrl ?? 'https://jobs.example.com/original')));
+        }
         ws.on('message', raw => {
             const msg = JSON.parse(String(raw));
             if (msg.type === 'navigate') {
                 options?.onNavigate?.(ws, msg);
             }
+            else if (msg.type === 'resize') {
+                options?.onResize?.(ws, msg);
+            }
         });
     });
     const port = await new Promise((resolve, reject) => {
@@ -78,6 +83,7 @@ describe('connectThroughProxy recovery', () => {
         });
         const staleRuntime = {
             wsUrl: stalePeer.wsUrl,
+            ready: Promise.resolve(),
             closed: false,
             close: vi.fn(async () => {
                 staleRuntime.closed = true;
@@ -85,6 +91,7 @@ describe('connectThroughProxy recovery', () => {
         };
         const freshRuntime = {
             wsUrl: freshPeer.wsUrl,
+            ready: Promise.resolve(),
             closed: false,
             close: vi.fn(async () => {
                 freshRuntime.closed = true;
@@ -124,6 +131,7 @@ describe('connectThroughProxy recovery', () => {
         });
         const headedRuntime = {
             wsUrl: headedPeer.wsUrl,
+            ready: Promise.resolve(),
             closed: false,
             close: vi.fn(async () => {
                 headedRuntime.closed = true;
@@ -131,6 +139,7 @@ describe('connectThroughProxy recovery', () => {
         };
         const headlessRuntime = {
             wsUrl: headlessPeer.wsUrl,
+            ready: Promise.resolve(),
             closed: false,
             close: vi.fn(async () => {
                 headlessRuntime.closed = true;
@@ -170,4 +179,84 @@ describe('connectThroughProxy recovery', () => {
             await closePeer(headlessPeer.wss);
         }
     });
+    it('can prewarm a reusable proxy before the first measured task', async () => {
+        const preparedPeer = await createProxyPeer({
+            pageUrl: 'https://jobs.example.com/prepared',
+        });
+        const preparedRuntime = {
+            wsUrl: preparedPeer.wsUrl,
+            ready: Promise.resolve(),
+            closed: false,
+            close: vi.fn(async () => {
+                preparedRuntime.closed = true;
+            }),
+        };
+        mockState.startEmbeddedGeometraProxy.mockResolvedValue({
+            runtime: preparedRuntime,
+            wsUrl: preparedPeer.wsUrl,
+        });
+        mockState.spawnGeometraProxy.mockRejectedValue(new Error('spawn fallback should not be used'));
+        try {
+            const prepared = await prewarmProxy({
+                pageUrl: 'https://jobs.example.com/prepared',
+                headless: true,
+            });
+            expect(prepared).toMatchObject({
+                prepared: true,
+                reused: false,
+                transport: 'embedded',
+                pageUrl: 'https://jobs.example.com/prepared',
+            });
+            const session = await connectThroughProxy({
+                pageUrl: 'https://jobs.example.com/prepared',
+                headless: true,
+            });
+            expect(session.proxyRuntime).toBe(preparedRuntime);
+            expect(mockState.startEmbeddedGeometraProxy).toHaveBeenCalledTimes(1);
+            expect(mockState.spawnGeometraProxy).not.toHaveBeenCalled();
+        }
+        finally {
+            disconnect({ closeProxy: true });
+            expect(preparedRuntime.close).toHaveBeenCalledTimes(1);
+            await closePeer(preparedPeer.wss);
+        }
+    });
+    it('starts without an eager initial extract when the caller defers the first frame', async () => {
+        const lazyPeer = await createProxyPeer({
+            pageUrl: 'https://jobs.example.com/lazy',
+            sendInitialFrame: false,
+        });
+        const lazyRuntime = {
+            wsUrl: lazyPeer.wsUrl,
+            ready: Promise.resolve(),
+            closed: false,
+            close: vi.fn(async () => {
+                lazyRuntime.closed = true;
+            }),
+        };
+        mockState.startEmbeddedGeometraProxy.mockResolvedValueOnce({
+            runtime: lazyRuntime,
+            wsUrl: lazyPeer.wsUrl,
+        });
+        mockState.spawnGeometraProxy.mockRejectedValue(new Error('spawn fallback should not be used'));
+        try {
+            const session = await connectThroughProxy({
+                pageUrl: 'https://jobs.example.com/lazy',
+                headless: true,
+                awaitInitialFrame: false,
+            });
+            expect(session.proxyRuntime).toBe(lazyRuntime);
+            expect(mockState.startEmbeddedGeometraProxy).toHaveBeenCalledWith(expect.objectContaining({
+                pageUrl: 'https://jobs.example.com/lazy',
+                headless: true,
+                eagerInitialExtract: false,
+            }));
+            expect(session.tree).toBeNull();
+        }
+        finally {
+            disconnect({ closeProxy: true });
+            expect(lazyRuntime.close).toHaveBeenCalledTimes(1);
+            await closePeer(lazyPeer.wss);
+        }
+    });
 });

package/dist/__tests__/server-batch-results.test.js

@@ -17,6 +17,7 @@ const mockState = vi.hoisted(() => ({
     currentA11yRoot: node('group', undefined, {
         meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
     }),
+    nodeContexts: new Map(),
     session: {
         tree: { kind: 'box' },
         layout: { x: 0, y: 0, width: 1280, height: 800, children: [] },
@@ -29,6 +30,7 @@ const mockState = vi.hoisted(() => ({
     formSchemas: [],
     connect: vi.fn(),
     connectThroughProxy: vi.fn(),
+    prewarmProxy: vi.fn(),
     sendClick: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     sendType: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     sendKey: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
@@ -44,13 +46,14 @@ const mockState = vi.hoisted(() => ({
     sendSelectOption: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     sendSetChecked: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     sendWheel: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
-    waitForUiCondition: vi.fn(async () => true),
+    waitForUiCondition: vi.fn(async (_session, _check, _timeoutMs) => true),
 }));
 function resetMockSessionCaches() {
     mockState.session.updateRevision = 1;
     mockState.session.cachedA11y = undefined;
     mockState.session.cachedA11yRevision = undefined;
     mockState.session.cachedFormSchemas = undefined;
+    mockState.nodeContexts.clear();
 }
 function bumpMockUiRevision() {
     mockState.session.updateRevision += 1;
@@ -61,6 +64,7 @@ function bumpMockUiRevision() {
 vi.mock('../session.js', () => ({
     connect: mockState.connect,
     connectThroughProxy: mockState.connectThroughProxy,
+    prewarmProxy: mockState.prewarmProxy,
     disconnect: vi.fn(),
     getSession: vi.fn(() => mockState.session),
     sendClick: mockState.sendClick,
@@ -95,6 +99,7 @@ vi.mock('../session.js', () => ({
     summarizeCompactIndex: vi.fn(() => ''),
     summarizePageModel: vi.fn(() => ''),
     summarizeUiDelta: vi.fn(() => ''),
+    nodeContextForNode: vi.fn((_, node) => mockState.nodeContexts.get((node.path ?? []).join('.'))),
     waitForUiCondition: mockState.waitForUiCondition,
 }));
 const { createServer } = await import('../server.js');
@@ -108,6 +113,16 @@ describe('batch MCP result shaping', () => {
         resetMockSessionCaches();
         mockState.connect.mockResolvedValue(mockState.session);
         mockState.connectThroughProxy.mockResolvedValue(mockState.session);
+        mockState.prewarmProxy.mockResolvedValue({
+            prepared: true,
+            reused: false,
+            transport: 'embedded',
+            pageUrl: 'https://jobs.example.com/application',
+            wsUrl: 'ws://127.0.0.1:3200',
+            headless: true,
+            width: 1280,
+            height: 720,
+        });
         mockState.formSchemas = [];
         mockState.currentA11yRoot = node('group', undefined, {
             meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 420 },
@@ -266,9 +281,115 @@ describe('batch MCP result shaping', () => {
             alertCount: 1,
             invalidCount: 5,
         });
-        expect(final.invalidFields.length).toBe(4);
+        expect(final.invalidFields.length).toBe(5);
         expect(final.alerts.length).toBe(1);
     });
+    it('uses the proxy batch path for fill_fields when step output is omitted', async () => {
+        const handler = getToolHandler('geometra_fill_fields');
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 420 },
+            children: [
+                node('textbox', 'Full name', { value: 'Taylor Applicant', path: [0] }),
+                node('textbox', 'Email', { value: 'taylor@example.com', path: [1] }),
+            ],
+        });
+        const result = await handler({
+            fields: [
+                { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+                { kind: 'text', fieldLabel: 'Email', value: 'taylor@example.com' },
+            ],
+            stopOnError: true,
+            failOnInvalid: false,
+            includeSteps: false,
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.sendFillFields).toHaveBeenCalledWith(mockState.session, [
+            { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+            { kind: 'text', fieldLabel: 'Email', value: 'taylor@example.com' },
+        ]);
+        expect(mockState.sendFieldText).not.toHaveBeenCalled();
+        expect(payload).toMatchObject({
+            completed: true,
+            execution: 'batched',
+            finalSource: 'session',
+            fieldCount: 2,
+            successCount: 2,
+            errorCount: 0,
+            final: { invalidCount: 0 },
+        });
+    });
+    it('auto-connects run_actions and supports final-only output', async () => {
+        const handler = getToolHandler('geometra_run_actions');
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://shop.example.com/login', scrollX: 0, scrollY: 0 },
+            children: [
+                node('textbox', 'Username', { value: 'standard_user', path: [0] }),
+                node('textbox', 'Password', { value: 'secret_sauce', path: [1] }),
+            ],
+        });
+        const result = await handler({
+            pageUrl: 'https://shop.example.com/login',
+            headless: true,
+            actions: [
+                {
+                    type: 'fill_fields',
+                    fields: [
+                        { kind: 'text', fieldLabel: 'Username', value: 'standard_user' },
+                        { kind: 'text', fieldLabel: 'Password', value: 'secret_sauce' },
+                    ],
+                },
+            ],
+            stopOnError: true,
+            includeSteps: false,
+            output: 'final',
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.connectThroughProxy).toHaveBeenCalledWith(expect.objectContaining({
+            pageUrl: 'https://shop.example.com/login',
+            headless: true,
+            awaitInitialFrame: false,
+        }));
+        expect(payload).toMatchObject({
+            autoConnected: true,
+            transport: 'proxy',
+            pageUrl: 'https://shop.example.com/login',
+            completed: true,
+            final: { invalidCount: 0 },
+        });
+        expect(payload).not.toHaveProperty('steps');
+        expect(payload).not.toHaveProperty('stepCount');
+    });
+    it('finds repeated actions by itemText in terse mode', async () => {
+        const handler = getToolHandler('geometra_find_action');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 720 },
+            meta: { pageUrl: 'https://shop.example.com/inventory', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Add to cart', { path: [0], bounds: { x: 40, y: 160, width: 120, height: 36 } }),
+                node('button', 'Add to cart', { path: [1], bounds: { x: 40, y: 260, width: 120, height: 36 } }),
+            ],
+        });
+        mockState.nodeContexts.set('0', { item: 'Sauce Labs Backpack', section: 'Inventory' });
+        mockState.nodeContexts.set('1', { item: 'Sauce Labs Bike Light', section: 'Inventory' });
+        const result = await handler({
+            name: 'Add to cart',
+            itemText: 'Backpack',
+            detail: 'terse',
+            maxResults: 4,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        const matches = payload.matches;
+        expect(payload.matchCount).toBe(1);
+        expect(matches[0]).toMatchObject({
+            id: 'n:0',
+            role: 'button',
+            name: 'Add to cart',
+            context: { item: 'Sauce Labs Backpack', section: 'Inventory' },
+            center: { x: 100, y: 178 },
+        });
+    });
     it('returns a compact structured connect payload by default', async () => {
         const handler = getToolHandler('geometra_connect');
         const result = await handler({
@@ -284,6 +405,34 @@ describe('batch MCP result shaping', () => {
         });
         expect(payload).not.toHaveProperty('currentUi');
     });
+    it('prepares a warm browser without creating an active session', async () => {
+        const handler = getToolHandler('geometra_prepare_browser');
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            width: 1280,
+            height: 720,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.prewarmProxy).toHaveBeenCalledWith({
+            pageUrl: 'https://jobs.example.com/application',
+            port: undefined,
+            headless: true,
+            width: 1280,
+            height: 720,
+            slowMo: undefined,
+        });
+        expect(payload).toMatchObject({
+            prepared: true,
+            reused: false,
+            transport: 'embedded',
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            width: 1280,
+            height: 720,
+        });
+        expect(mockState.connectThroughProxy).not.toHaveBeenCalled();
+    });
     it('can inline a packed form schema into connect for the low-turn form path', async () => {
         const handler = getToolHandler('geometra_connect');
         mockState.formSchemas = [
@@ -353,6 +502,72 @@ describe('batch MCP result shaping', () => {
         });
         expect(payload).not.toHaveProperty('formSchema');
     });
+    it('can defer the page model so connect returns before the first frame', async () => {
+        const handler = getToolHandler('geometra_connect');
+        mockState.session.tree = null;
+        mockState.session.layout = null;
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            returnPageModel: true,
+            pageModelMode: 'deferred',
+            maxPrimaryActions: 4,
+            maxSectionsPerKind: 3,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.connectThroughProxy).toHaveBeenCalledWith({
+            pageUrl: 'https://jobs.example.com/application',
+            port: undefined,
+            headless: true,
+            width: undefined,
+            height: undefined,
+            slowMo: undefined,
+            awaitInitialFrame: false,
+            eagerInitialExtract: true,
+        });
+        expect(payload).toMatchObject({
+            connected: true,
+            transport: 'proxy',
+            pageUrl: 'https://jobs.example.com/application',
+            pageModel: {
+                deferred: true,
+                ready: false,
+                tool: 'geometra_page_model',
+                options: {
+                    maxPrimaryActions: 4,
+                    maxSectionsPerKind: 3,
+                },
+            },
+        });
+    });
+    it('waits for the initial tree when page_model is requested after a deferred connect', async () => {
+        const handler = getToolHandler('geometra_page_model');
+        mockState.session.tree = null;
+        mockState.session.layout = null;
+        mockState.waitForUiCondition.mockImplementationOnce(async (_session, check) => {
+            mockState.session.tree = { kind: 'box' };
+            mockState.session.layout = {
+                x: 0,
+                y: 0,
+                width: 1280,
+                height: 800,
+                children: [],
+            };
+            bumpMockUiRevision();
+            return check();
+        });
+        const result = await handler({
+            maxPrimaryActions: 4,
+            maxSectionsPerKind: 3,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.waitForUiCondition).toHaveBeenCalledWith(mockState.session, expect.any(Function), 4000);
+        expect(payload).toMatchObject({
+            viewport: { width: 1280, height: 800 },
+            archetypes: ['form'],
+            summary: { formCount: 1 },
+        });
+    });
     it('returns compact form schemas without requiring section expansion', async () => {
         const handler = getToolHandler('geometra_form_schema');
         mockState.formSchemas = [
@@ -670,6 +885,14 @@ describe('query and reveal tools', () => {
                 }),
             ],
         });
+        mockState.nodeContexts.set('0.0.1', {
+            prompt: 'Are you legally authorized to work here?',
+            section: 'Application',
+        });
+        mockState.nodeContexts.set('0.1.1', {
+            prompt: 'Will you require sponsorship?',
+            section: 'Application',
+        });
         const result = await handler({
             role: 'button',
             name: 'Yes',
@@ -938,6 +1161,41 @@ describe('query and reveal tools', () => {
         expect(result.content[0].text).toContain('Post-click condition satisfied after');
         expect(result.content[0].text).toContain('1 matching node(s).');
     });
+    it('waits for the initial tree before a semantic click after deferred connect', async () => {
+        const handler = getToolHandler('geometra_click');
+        mockState.session.tree = null;
+        mockState.session.layout = null;
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Open incident', {
+                    bounds: { x: 40, y: 120, width: 140, height: 40 },
+                    path: [0],
+                }),
+            ],
+        });
+        mockState.waitForUiCondition.mockImplementationOnce(async (_session, check) => {
+            mockState.session.tree = { kind: 'box' };
+            mockState.session.layout = {
+                x: 0,
+                y: 0,
+                width: 1280,
+                height: 800,
+                children: [],
+            };
+            bumpMockUiRevision();
+            return check();
+        });
+        const result = await handler({
+            role: 'button',
+            name: 'Open incident',
+            detail: 'minimal',
+        });
+        expect(mockState.waitForUiCondition).toHaveBeenCalledWith(mockState.session, expect.any(Function), 4000);
+        expect(mockState.sendClick).toHaveBeenCalledWith(mockState.session, 110, 140, undefined);
+        expect(result.content[0].text).toContain('Clicked button "Open incident" (n:0) at (110, 140).');
+    });
     it('lets run_actions click a semantic target without manual coordinates', async () => {
         const handler = getToolHandler('geometra_run_actions');
         mockState.currentA11yRoot = node('group', undefined, {
@@ -998,6 +1256,7 @@ describe('query and reveal tools', () => {
             index: 0,
             type: 'click',
             ok: true,
+            elapsedMs: expect.any(Number),
             at: { x: 150, y: 340 },
             revealSteps: 1,
             target: { id: 'n:0.0', role: 'button', name: 'Submit application' },
@@ -1057,6 +1316,7 @@ describe('query and reveal tools', () => {
             index: 0,
             type: 'click',
             ok: true,
+            elapsedMs: expect.any(Number),
             postWait: {
                 present: true,
                 matchCount: 1,

package/dist/__tests__/session-model.test.js

@@ -75,6 +75,54 @@ describe('buildPageModel', () => {
             }),
         ]);
     });
+    it('adds nearby item context to repeated primary actions', () => {
+        const tree = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
+            children: [
+                node('main', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
+                    path: [0],
+                    children: [
+                        node('group', undefined, { x: 40, y: 80, width: 320, height: 140 }, {
+                            path: [0, 0],
+                            children: [
+                                node('link', 'Sauce Labs Backpack', { x: 56, y: 96, width: 180, height: 24 }, {
+                                    path: [0, 0, 0],
+                                    focusable: true,
+                                }),
+                                node('button', 'Add to cart', { x: 56, y: 156, width: 120, height: 36 }, {
+                                    path: [0, 0, 1],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                        node('group', undefined, { x: 40, y: 252, width: 320, height: 140 }, {
+                            path: [0, 1],
+                            children: [
+                                node('link', 'Sauce Labs Bike Light', { x: 56, y: 268, width: 180, height: 24 }, {
+                                    path: [0, 1, 0],
+                                    focusable: true,
+                                }),
+                                node('button', 'Add to cart', { x: 56, y: 328, width: 120, height: 36 }, {
+                                    path: [0, 1, 1],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const model = buildPageModel(tree, { maxPrimaryActions: 4 });
+        const addToCartActions = model.primaryActions.filter(action => action.name === 'Add to cart');
+        expect(addToCartActions).toHaveLength(2);
+        expect(addToCartActions[0]).toMatchObject({
+            id: 'n:0.0.1',
+            context: { item: 'Sauce Labs Backpack' },
+        });
+        expect(addToCartActions[1]).toMatchObject({
+            id: 'n:0.1.1',
+            context: { item: 'Sauce Labs Bike Light' },
+        });
+    });
     it('expands a section by id on demand', () => {
         const tree = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
             children: [

package/dist/proxy-spawn.d.ts

@@ -1,6 +1,8 @@
 import { type ChildProcess } from 'node:child_process';
 export interface EmbeddedProxyRuntime {
     wsUrl: string;
+    ready: Promise<void>;
+    getTrace?: () => Record<string, unknown>;
     closed: boolean;
     close: () => Promise<void>;
 }
@@ -16,6 +18,7 @@ export interface SpawnProxyParams {
     width?: number;
     height?: number;
     slowMo?: number;
+    eagerInitialExtract?: boolean;
 }
 export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
     runtime: EmbeddedProxyRuntime;