@geometra/mcp 1.19.20 → 1.19.23

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,
@@ -87,6 +91,7 @@ vi.mock('../session.js', () => ({
         lists: [],
     })),
     buildFormSchemas: vi.fn(() => mockState.formSchemas),
+    buildFormRequiredSnapshot: vi.fn(() => []),
     expandPageSection: vi.fn(() => null),
     buildUiDelta: vi.fn(() => ({})),
     hasUiDelta: vi.fn(() => false),
@@ -94,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');
@@ -107,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 },
@@ -171,6 +187,42 @@ describe('batch MCP result shaping', () => {
             readback: { role: 'textbox', value: 'taylor@example.com' },
         });
     });
+    it('resolves fieldId-only fill_fields entries from the current form schema', async () => {
+        const handler = getToolHandler('geometra_fill_fields');
+        mockState.formSchemas = [{
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 3,
+                requiredCount: 0,
+                invalidCount: 0,
+                fields: [
+                    { id: 'ff:0.0', kind: 'text', label: 'Full name' },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', choiceType: 'select' },
+                    { id: 'ff:0.2', kind: 'toggle', label: 'Share my profile for future roles', controlType: 'checkbox' },
+                ],
+            }];
+        const result = await handler({
+            fields: [
+                { kind: 'text', fieldId: 'ff:0.0', value: 'Taylor Applicant' },
+                { kind: 'choice', fieldId: 'ff:0.1', value: 'Berlin, Germany' },
+                { kind: 'toggle', fieldId: 'ff:0.2', checked: true },
+            ],
+            stopOnError: true,
+            failOnInvalid: false,
+            includeSteps: true,
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.sendFieldText).toHaveBeenCalledWith(mockState.session, 'Full name', 'Taylor Applicant', { exact: undefined, fieldId: 'ff:0.0' }, undefined);
+        expect(mockState.sendFieldChoice).toHaveBeenCalledWith(mockState.session, 'Preferred location', 'Berlin, Germany', { exact: undefined, query: undefined, choiceType: 'select', fieldId: 'ff:0.1' }, undefined);
+        expect(mockState.sendSetChecked).toHaveBeenCalledWith(mockState.session, 'Share my profile for future roles', { checked: true, exact: undefined, controlType: 'checkbox' }, undefined);
+        expect(payload).toMatchObject({
+            completed: true,
+            fieldCount: 3,
+            successCount: 3,
+            errorCount: 0,
+        });
+    });
     it('lets run_actions omit step listings while keeping capped final validation state', async () => {
         const handler = getToolHandler('geometra_run_actions');
         mockState.currentA11yRoot = node('group', undefined, {
@@ -232,6 +284,112 @@ describe('batch MCP result shaping', () => {
         expect(final.invalidFields.length).toBe(4);
         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({
@@ -247,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 = [
@@ -316,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 = [
@@ -633,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',
@@ -763,6 +1023,52 @@ describe('query and reveal tools', () => {
             },
         });
     });
+    it('auto-scales reveal steps for tall forms when maxSteps is omitted', async () => {
+        const handler = getToolHandler('geometra_reveal');
+        let scrollY = 0;
+        const setTree = () => {
+            mockState.currentA11yRoot = node('group', undefined, {
+                bounds: { x: 0, y: 0, width: 1280, height: 800 },
+                meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY },
+                children: [
+                    node('form', 'Application', {
+                        bounds: { x: 20, y: -200 - scrollY, width: 760, height: 6200 },
+                        path: [0],
+                        children: [
+                            node('button', 'Submit application', {
+                                bounds: { x: 60, y: 5200 - scrollY, width: 180, height: 40 },
+                                path: [0, 0],
+                            }),
+                        ],
+                    }),
+                ],
+            });
+        };
+        setTree();
+        mockState.sendWheel.mockImplementation(async () => {
+            scrollY += 650;
+            setTree();
+            bumpMockUiRevision();
+            return { status: 'updated', timeoutMs: 2500 };
+        });
+        const result = await handler({
+            role: 'button',
+            name: 'Submit application',
+            fullyVisible: true,
+            timeoutMs: 2500,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.sendWheel).toHaveBeenCalledTimes(7);
+        expect(payload).toMatchObject({
+            revealed: true,
+            attempts: 7,
+            target: {
+                role: 'button',
+                name: 'Submit application',
+                visibility: { fullyVisible: true },
+            },
+        });
+    });
     it('clicks an offscreen semantic target by revealing it first', async () => {
         const handler = getToolHandler('geometra_click');
         mockState.currentA11yRoot = node('group', undefined, {
@@ -855,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, {
@@ -915,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' },
@@ -974,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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { buildA11yTree, buildCompactUiIndex, buildFormSchemas, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+import { buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildFormSchemas, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
 function node(role, name, bounds, options) {
     return {
         role,
@@ -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: [
@@ -375,6 +423,78 @@ describe('buildFormSchemas', () => {
         });
     });
 });
+describe('buildFormRequiredSnapshot', () => {
+    it('keeps offscreen required fields with bounds, visibility, and scroll hints', () => {
+        const tree = node('group', undefined, { x: 0, y: 0, width: 900, height: 700 }, {
+            children: [
+                node('form', 'Application', { x: 20, y: -160, width: 760, height: 2200 }, {
+                    path: [0],
+                    children: [
+                        node('textbox', 'Full name', { x: 48, y: 120, width: 320, height: 36 }, {
+                            path: [0, 0],
+                            state: { required: true },
+                        }),
+                        node('combobox', 'Preferred location', { x: 48, y: 940, width: 320, height: 36 }, {
+                            path: [0, 1],
+                            state: { required: true },
+                            meta: { controlTag: 'select' },
+                        }),
+                        node('group', undefined, { x: 40, y: 1260, width: 520, height: 96 }, {
+                            path: [0, 2],
+                            children: [
+                                node('text', 'Will you require sponsorship?', { x: 48, y: 1260, width: 320, height: 24 }, {
+                                    path: [0, 2, 0],
+                                }),
+                                node('button', 'Yes', { x: 48, y: 1300, width: 88, height: 40 }, {
+                                    path: [0, 2, 1],
+                                    focusable: true,
+                                    state: { required: true },
+                                }),
+                                node('button', 'No', { x: 148, y: 1300, width: 88, height: 40 }, {
+                                    path: [0, 2, 2],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const snapshot = buildFormRequiredSnapshot(tree, { includeOptions: true });
+        expect(snapshot).toHaveLength(1);
+        expect(snapshot[0]).toMatchObject({
+            formId: 'fm:0',
+            name: 'Application',
+            requiredCount: 3,
+            fields: [
+                {
+                    id: 'ff:0.0',
+                    label: 'Full name',
+                    visibility: { intersectsViewport: true, fullyVisible: true },
+                    scrollHint: { status: 'visible' },
+                    bounds: { x: 48, y: 120, width: 320, height: 36 },
+                },
+                {
+                    id: 'ff:0.1',
+                    label: 'Preferred location',
+                    choiceType: 'select',
+                    visibility: { intersectsViewport: false, offscreenBelow: true },
+                    scrollHint: { status: 'offscreen' },
+                    bounds: { x: 48, y: 940, width: 320, height: 36 },
+                },
+                {
+                    id: 'ff:0.2',
+                    label: 'Will you require sponsorship?',
+                    choiceType: 'group',
+                    visibility: { intersectsViewport: false, offscreenBelow: true },
+                    scrollHint: { status: 'offscreen' },
+                    bounds: { x: 40, y: 1260, width: 520, height: 96 },
+                    options: ['Yes', 'No'],
+                },
+            ],
+        });
+    });
+});
 describe('buildUiDelta', () => {
     it('captures opened dialogs, state changes, and list count changes', () => {
         const before = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {

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;

package/dist/proxy-spawn.js

@@ -138,6 +138,7 @@ export async function startEmbeddedGeometraProxy(opts) {
         height: opts.height,
         headed: opts.headless !== true,
         slowMo: opts.slowMo,
+        eagerInitialExtract: opts.eagerInitialExtract,
     });
     return { runtime, wsUrl: runtime.wsUrl };
 }
@@ -189,6 +190,8 @@ export function spawnGeometraProxy(opts) {
         args.push('--headless');
     else if (opts.headless === false)
         args.push('--headed');
+    if (opts.eagerInitialExtract === false)
+        args.push('--lazy-initial-extract');
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, args, {
             stdio: ['ignore', 'pipe', 'pipe'],

package/dist/server.d.ts

@@ -7,6 +7,9 @@ interface NodeFilter {
     name?: string;
     text?: string;
     contextText?: string;
+    promptText?: string;
+    sectionText?: string;
+    itemText?: string;
     value?: string;
     checked?: NodeStateFilterValue;
     disabled?: boolean;