@geometra/mcp 1.19.15 → 1.19.17

package/README.md

@@ -21,8 +21,8 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 | `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; `url: "https://…"` is auto-coerced onto the proxy path |
 | `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_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.) |
-| `geometra_form_schema` | Compact, fill-oriented form schema with stable field ids and collapsed radio/button groups |
-| `geometra_fill_form` | Fill a form from `valuesById` / `valuesByLabel` in one MCP call; preferred low-token happy path for standard forms |
+| `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 labeled text/choice/toggle/file fields in one MCP call; can return final-only status for the smallest responses |
 | `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 |
@@ -297,8 +297,8 @@ Agent:  geometra_query({ role: "button", name: "Save" })
 2. It receives the computed layout (`{ x, y, width, height }` for every node) and the UI tree (`kind`, `semantic`, `props`, `handlers`, `children`).
 3. It builds an accessibility tree from that data — roles, names, focusable state, bounds.
 4. **`geometra_snapshot`** defaults to a **compact** flat list of viewport-visible actionable nodes (minified JSON) to reduce LLM tokens; use `view: "full"` for the complete nested tree.
-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.
-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.
+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_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.
 8. **`geometra_expand_section`** fetches richer details only for the section you care about (fields, actions, headings, nested lists, list items, text preview).
 9. 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.
@@ -308,8 +308,9 @@ Agent:  geometra_query({ role: "button", name: "Save" })
 
 For long application flows, prefer one of these patterns:
 
-1. `geometra_form_schema`
-2. `geometra_fill_form`
+1. `geometra_fill_form({ pageUrl, valuesByLabel })` when you already know the fields you want to set
+2. otherwise `geometra_form_schema`
+3. then `geometra_fill_form`
 3. `geometra_reveal` for far-below-fold targets such as submit buttons
 4. `geometra_run_actions` when you need mixed navigation + waits + field entry
 5. `geometra_page_model` + `geometra_expand_section` when you are still exploring the page rather than filling it

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

@@ -1,6 +1,6 @@
 import { afterAll, describe, expect, it } from 'vitest';
 import { WebSocketServer } from 'ws';
-import { connect, disconnect, sendClick, sendFillFields, sendListboxPick } from '../session.js';
+import { connect, disconnect, sendClick, sendFillFields, sendListboxPick, sendNavigate } from '../session.js';
 describe('proxy-backed MCP actions', () => {
     afterAll(() => {
         disconnect();
@@ -150,8 +150,8 @@ describe('proxy-backed MCP actions', () => {
         try {
             const session = await connect(`ws://127.0.0.1:${port}`);
             await expect(sendFillFields(session, [
-                { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
-                { kind: 'choice', fieldLabel: 'Country', value: 'Germany' },
+                { kind: 'text', fieldId: 'ff:0.0', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+                { kind: 'choice', fieldId: 'ff:0.1', fieldLabel: 'Country', value: 'Germany' },
             ], 80)).resolves.toMatchObject({
                 status: 'updated',
                 timeoutMs: 80,
@@ -164,8 +164,8 @@ describe('proxy-backed MCP actions', () => {
             expect(seenMessage).toMatchObject({
                 type: 'fillFields',
                 fields: [
-                    { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
-                    { kind: 'choice', fieldLabel: 'Country', value: 'Germany' },
+                    { kind: 'text', fieldId: 'ff:0.0', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+                    { kind: 'choice', fieldId: 'ff:0.1', fieldLabel: 'Country', value: 'Germany' },
                 ],
             });
         }
@@ -229,4 +229,62 @@ describe('proxy-backed MCP actions', () => {
             await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
         }
     });
+    it('supports in-session navigation and waits for the resulting frame', async () => {
+        const wss = new WebSocketServer({ port: 0 });
+        const received = [];
+        wss.on('connection', ws => {
+            ws.on('message', raw => {
+                const msg = JSON.parse(String(raw));
+                received.push(msg);
+                if (msg.type === 'resize') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: { kind: 'box', props: {}, semantic: { tag: 'body', role: 'group' }, children: [] },
+                    }));
+                    return;
+                }
+                if (msg.type === 'navigate') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: {
+                            kind: 'box',
+                            props: {},
+                            semantic: { tag: 'body', role: 'group' },
+                            children: [],
+                        },
+                    }));
+                    ws.send(JSON.stringify({
+                        type: 'ack',
+                        requestId: msg.requestId,
+                        result: { pageUrl: msg.url },
+                    }));
+                }
+            });
+        });
+        const port = await new Promise((resolve, reject) => {
+            wss.once('listening', () => {
+                const address = wss.address();
+                if (typeof address === 'object' && address)
+                    resolve(address.port);
+                else
+                    reject(new Error('Failed to resolve ephemeral WebSocket port'));
+            });
+            wss.once('error', reject);
+        });
+        try {
+            const session = await connect(`ws://127.0.0.1:${port}`);
+            await expect(sendNavigate(session, 'https://jobs.example.com/application', 80)).resolves.toMatchObject({
+                status: 'updated',
+                timeoutMs: 80,
+                result: { pageUrl: 'https://jobs.example.com/application' },
+            });
+            expect(received.some(message => message.type === 'navigate' && message.url === 'https://jobs.example.com/application')).toBe(true);
+        }
+        finally {
+            disconnect();
+            await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
+        }
+    });
 });

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

@@ -22,6 +22,9 @@ const mockState = vi.hoisted(() => ({
         layout: { x: 0, y: 0, width: 1280, height: 800, children: [] },
         url: 'ws://127.0.0.1:3200',
         updateRevision: 1,
+        cachedA11y: undefined,
+        cachedA11yRevision: undefined,
+        cachedFormSchemas: undefined,
     },
     formSchemas: [],
     connect: vi.fn(),
@@ -43,6 +46,18 @@ const mockState = vi.hoisted(() => ({
     sendWheel: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     waitForUiCondition: vi.fn(async () => true),
 }));
+function resetMockSessionCaches() {
+    mockState.session.updateRevision = 1;
+    mockState.session.cachedA11y = undefined;
+    mockState.session.cachedA11yRevision = undefined;
+    mockState.session.cachedFormSchemas = undefined;
+}
+function bumpMockUiRevision() {
+    mockState.session.updateRevision += 1;
+    mockState.session.cachedA11y = undefined;
+    mockState.session.cachedA11yRevision = undefined;
+    mockState.session.cachedFormSchemas = undefined;
+}
 vi.mock('../session.js', () => ({
     connect: mockState.connect,
     connectThroughProxy: mockState.connectThroughProxy,
@@ -89,6 +104,7 @@ function getToolHandler(name) {
 describe('batch MCP result shaping', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        resetMockSessionCaches();
         mockState.connect.mockResolvedValue(mockState.session);
         mockState.connectThroughProxy.mockResolvedValue(mockState.session);
         mockState.formSchemas = [];
@@ -231,6 +247,53 @@ describe('batch MCP result shaping', () => {
         });
         expect(payload).not.toHaveProperty('currentUi');
     });
+    it('can inline a packed form schema into connect for the low-turn form path', async () => {
+        const handler = getToolHandler('geometra_connect');
+        mockState.formSchemas = [
+            {
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 2,
+                requiredCount: 1,
+                invalidCount: 0,
+                fields: [
+                    { id: 'ff:0.0', kind: 'text', label: 'Full name', required: true },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Work authorization', choiceType: 'group', booleanChoice: true, optionCount: 2 },
+                ],
+            },
+        ];
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            returnForms: true,
+            includeContext: 'none',
+            schemaFormat: 'packed',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            connected: true,
+            transport: 'proxy',
+            pageUrl: 'https://jobs.example.com/application',
+            formSchema: {
+                changed: true,
+                formCount: 1,
+                format: 'packed',
+                schemaId: expect.any(String),
+                forms: [
+                    {
+                        i: 'fm:0',
+                        fc: 2,
+                        rc: 1,
+                        ic: 0,
+                        f: [
+                            { i: 'ff:0.0', k: 'text', l: 'Full name', r: 1 },
+                            { i: 'ff:0.1', k: 'choice', l: 'Work authorization', ch: 'group', b: 1, oc: 2 },
+                        ],
+                    },
+                ],
+            },
+        });
+    });
     it('returns compact form schemas without requiring section expansion', async () => {
         const handler = getToolHandler('geometra_form_schema');
         mockState.formSchemas = [
@@ -242,22 +305,73 @@ describe('batch MCP result shaping', () => {
                 invalidCount: 0,
                 fields: [
                     { id: 'ff:0.0', kind: 'text', label: 'Full name', required: true },
-                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', required: true },
-                    { id: 'ff:0.2', kind: 'choice', label: 'Are you legally authorized to work in Germany?', options: ['Yes', 'No'], optionCount: 2 },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', required: true, choiceType: 'select' },
+                    { id: 'ff:0.2', kind: 'choice', label: 'Are you legally authorized to work in Germany?', choiceType: 'group', booleanChoice: true, optionCount: 2 },
                     { id: 'ff:0.3', kind: 'toggle', label: 'Share my profile for future roles', controlType: 'checkbox' },
                 ],
             },
         ];
         const result = await handler({ maxFields: 20 });
         const payload = JSON.parse(result.content[0].text);
-        expect(payload.forms).toEqual([
-            expect.objectContaining({
+        expect(payload).toMatchObject({
+            changed: true,
+            formCount: 1,
+            format: 'compact',
+            schemaId: expect.any(String),
+            forms: [
+                expect.objectContaining({
+                    formId: 'fm:0',
+                    fieldCount: 4,
+                    requiredCount: 3,
+                    invalidCount: 0,
+                }),
+            ],
+        });
+        const forms = payload.forms;
+        const fields = forms[0]?.fields;
+        expect(fields[2]).toMatchObject({
+            id: 'ff:0.2',
+            kind: 'choice',
+            label: 'Are you legally authorized to work in Germany?',
+            choiceType: 'group',
+            booleanChoice: true,
+            optionCount: 2,
+        });
+        expect(fields[2]).not.toHaveProperty('options');
+    });
+    it('can auto-connect inside form_schema when given a pageUrl', async () => {
+        const handler = getToolHandler('geometra_form_schema');
+        mockState.formSchemas = [
+            {
                 formId: 'fm:0',
-                fieldCount: 4,
-                requiredCount: 3,
+                name: 'Application',
+                fieldCount: 1,
+                requiredCount: 1,
                 invalidCount: 0,
-            }),
-        ]);
+                fields: [{ id: 'ff:0.0', kind: 'text', label: 'Full name', required: true }],
+            },
+        ];
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+        });
+        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: undefined,
+        });
+        expect(payload).toMatchObject({
+            autoConnected: true,
+            transport: 'proxy',
+            pageUrl: 'https://jobs.example.com/application',
+            changed: true,
+            formCount: 1,
+        });
     });
     it('fills a form from ids and labels without echoing long essay content', async () => {
         const longAnswer = 'B'.repeat(220);
@@ -271,7 +385,7 @@ describe('batch MCP result shaping', () => {
                 invalidCount: 0,
                 fields: [
                     { id: 'ff:0.0', kind: 'text', label: 'Full name', required: true },
-                    { id: 'ff:0.1', kind: 'choice', label: 'Are you legally authorized to work in Germany?', options: ['Yes', 'No'], optionCount: 2 },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Are you legally authorized to work in Germany?', choiceType: 'group', booleanChoice: true, optionCount: 2 },
                     { id: 'ff:0.2', kind: 'toggle', label: 'Share my profile for future roles', controlType: 'checkbox' },
                     { id: 'ff:0.3', kind: 'text', label: 'Why Geometra?' },
                 ],
@@ -304,7 +418,7 @@ describe('batch MCP result shaping', () => {
         const payload = JSON.parse(text);
         const steps = payload.steps;
         expect(text).not.toContain(longAnswer);
-        expect(mockState.sendFieldChoice).toHaveBeenCalledWith(mockState.session, 'Are you legally authorized to work in Germany?', 'Yes', { exact: undefined, query: undefined }, undefined);
+        expect(mockState.sendFieldChoice).toHaveBeenCalledWith(mockState.session, 'Are you legally authorized to work in Germany?', 'Yes', { exact: undefined, query: undefined, choiceType: 'group', fieldId: 'ff:0.1' }, undefined);
         expect(payload).toMatchObject({
             completed: true,
             formId: 'fm:0',
@@ -342,7 +456,7 @@ describe('batch MCP result shaping', () => {
                 invalidCount: 0,
                 fields: [
                     { id: 'ff:0.0', kind: 'text', label: 'Full name', required: true },
-                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', required: true },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', required: true, choiceType: 'select' },
                     { id: 'ff:0.2', kind: 'toggle', label: 'Share my profile for future roles', controlType: 'checkbox' },
                 ],
             },
@@ -369,10 +483,11 @@ describe('batch MCP result shaping', () => {
         });
         const payload = JSON.parse(result.content[0].text);
         expect(mockState.sendFillFields).toHaveBeenCalledWith(mockState.session, [
-            { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
-            { kind: 'choice', fieldLabel: 'Preferred location', value: 'Berlin, Germany' },
+            { kind: 'text', fieldId: 'ff:0.0', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+            { kind: 'choice', fieldId: 'ff:0.1', fieldLabel: 'Preferred location', value: 'Berlin, Germany', choiceType: 'select' },
             {
                 kind: 'toggle',
+                fieldId: 'ff:0.2',
                 label: 'Share my profile for future roles',
                 checked: true,
                 controlType: 'checkbox',
@@ -396,10 +511,77 @@ describe('batch MCP result shaping', () => {
         });
         expect(payload).not.toHaveProperty('steps');
     });
+    it('can auto-connect inside fill_form for known-label one-turn flows', async () => {
+        const handler = getToolHandler('geometra_fill_form');
+        mockState.sendFillFields.mockResolvedValueOnce({
+            status: 'acknowledged',
+            timeoutMs: 6000,
+            result: {
+                pageUrl: 'https://jobs.example.com/application',
+                invalidCount: 0,
+                alertCount: 0,
+                dialogCount: 0,
+                busyCount: 0,
+            },
+        });
+        mockState.formSchemas = [
+            {
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 2,
+                requiredCount: 2,
+                invalidCount: 0,
+                fields: [
+                    { id: 'ff:0.0', kind: 'text', label: 'Full name', required: true },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Are you legally authorized to work in Germany?', choiceType: 'group', booleanChoice: true, optionCount: 2 },
+                ],
+            },
+        ];
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            valuesByLabel: {
+                'Full name': 'Taylor Applicant',
+                'Are you legally authorized to work in Germany?': true,
+            },
+            includeSteps: false,
+            detail: 'minimal',
+        });
+        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,
+        });
+        expect(mockState.sendFillFields).toHaveBeenCalledWith(mockState.session, [
+            { kind: 'auto', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+            { kind: 'auto', fieldLabel: 'Are you legally authorized to work in Germany?', value: true },
+        ]);
+        expect(payload).toMatchObject({
+            autoConnected: true,
+            transport: 'proxy',
+            pageUrl: 'https://jobs.example.com/application',
+            completed: true,
+            execution: 'batched-direct',
+            finalSource: 'proxy',
+            fieldCount: 2,
+            successCount: 2,
+            errorCount: 0,
+            final: {
+                invalidCount: 0,
+                alertCount: 0,
+            },
+        });
+    });
 });
 describe('query and reveal tools', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        resetMockSessionCaches();
     });
     it('lets query disambiguate repeated controls by context text', async () => {
         const handler = getToolHandler('geometra_query');
@@ -461,7 +643,7 @@ describe('query and reveal tools', () => {
                 invalidCount: 2,
                 fields: [
                     { id: 'ff:0.0', kind: 'text', label: 'Full name', required: true, invalid: true },
-                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', required: true, invalid: true },
+                    { id: 'ff:0.1', kind: 'choice', label: 'Preferred location', required: true, invalid: true, choiceType: 'select' },
                 ],
             },
         ];
@@ -490,8 +672,8 @@ describe('query and reveal tools', () => {
         });
         const payload = JSON.parse(result.content[0].text);
         expect(mockState.sendFillFields).toHaveBeenCalledTimes(1);
-        expect(mockState.sendFieldText).toHaveBeenCalledWith(mockState.session, 'Full name', 'Taylor Applicant', { exact: undefined }, undefined);
-        expect(mockState.sendFieldChoice).toHaveBeenCalledWith(mockState.session, 'Preferred location', 'Berlin, Germany', { exact: undefined, query: undefined }, undefined);
+        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(payload).toMatchObject({
             completed: true,
             execution: 'sequential',
@@ -537,6 +719,7 @@ describe('query and reveal tools', () => {
                     }),
                 ],
             });
+            bumpMockUiRevision();
             return { status: 'updated', timeoutMs: 2500 };
         });
         const result = await handler({

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

@@ -253,6 +253,7 @@ describe('buildFormSchemas', () => {
                             path: [0, 1],
                             state: { required: true },
                             value: 'Berlin, Germany',
+                            meta: { controlTag: 'select' },
                         }),
                         node('group', undefined, { x: 40, y: 260, width: 520, height: 96 }, {
                             path: [0, 2],
@@ -304,15 +305,17 @@ describe('buildFormSchemas', () => {
             expect.objectContaining({
                 kind: 'choice',
                 label: 'Preferred location',
+                choiceType: 'select',
                 required: true,
                 value: 'Berlin, Germany',
             }),
             expect.objectContaining({
                 kind: 'choice',
                 label: 'Are you legally authorized to work in Germany?',
+                choiceType: 'group',
                 required: true,
                 optionCount: 2,
-                options: ['Yes', 'No'],
+                booleanChoice: true,
             }),
             expect.objectContaining({
                 kind: 'toggle',
@@ -328,8 +331,9 @@ describe('buildFormSchemas', () => {
                 valueLength: longEssay.length,
             }),
         ]);
+        expect(schemas[0]?.fields[2]).not.toHaveProperty('options');
     });
-    it('prefers question prompts over nearby explanatory copy for grouped choices', () => {
+    it('includes explicit options when requested and prefers question prompts over nearby explanatory copy', () => {
         const tree = node('group', undefined, { x: 0, y: 0, width: 900, height: 700 }, {
             children: [
                 node('form', 'Application', { x: 20, y: 20, width: 760, height: 480 }, {
@@ -358,11 +362,16 @@ describe('buildFormSchemas', () => {
                 }),
             ],
         });
-        const schema = buildFormSchemas(tree)[0];
+        const schema = buildFormSchemas(tree, { includeOptions: true, includeContext: 'always' })[0];
         expect(schema?.fields[0]).toMatchObject({
             kind: 'choice',
+            choiceType: 'group',
             label: 'Will you now or in the future require sponsorship?',
             options: ['Yes', 'No'],
+            booleanChoice: true,
+            context: {
+                section: 'Application',
+            },
         });
     });
 });

package/dist/proxy-spawn.d.ts

@@ -1,7 +1,14 @@
 import { type ChildProcess } from 'node:child_process';
+export interface EmbeddedProxyRuntime {
+    wsUrl: string;
+    closed: boolean;
+    close: () => Promise<void>;
+}
 /** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
 export declare function resolveProxyScriptPath(): string;
 export declare function resolveProxyScriptPathWith(customRequire: NodeRequire, moduleDir?: string): string;
+export declare function resolveProxyRuntimePath(): string;
+export declare function resolveProxyRuntimePathWith(customRequire: NodeRequire, moduleDir?: string): string;
 export interface SpawnProxyParams {
     pageUrl: string;
     port: number;
@@ -10,6 +17,10 @@ export interface SpawnProxyParams {
     height?: number;
     slowMo?: number;
 }
+export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
+    runtime: EmbeddedProxyRuntime;
+    wsUrl: string;
+}>;
 export declare function parseProxyReadySignalLine(line: string): string | undefined;
 export declare function formatProxyStartupFailure(message: string, opts: SpawnProxyParams): string;
 /**

package/dist/proxy-spawn.js

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, realpathSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 const require = createRequire(import.meta.url);
 const READY_SIGNAL_TYPE = 'geometra-proxy-ready';
 const READY_TIMEOUT_MS = 45_000;
@@ -12,21 +12,30 @@ export function resolveProxyScriptPath() {
     return resolveProxyScriptPathWith(require);
 }
 export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR) {
+    return resolveProxyDistPathWith(customRequire, moduleDir, 'index.js');
+}
+export function resolveProxyRuntimePath() {
+    return resolveProxyRuntimePathWith(require);
+}
+export function resolveProxyRuntimePathWith(customRequire, moduleDir = MODULE_DIR) {
+    return resolveProxyDistPathWith(customRequire, moduleDir, 'runtime.js');
+}
+function resolveProxyDistPathWith(customRequire, moduleDir, entryFile) {
     const errors = [];
-    const workspaceDist = path.resolve(moduleDir, '../../packages/proxy/dist/index.js');
+    const workspaceDist = path.resolve(moduleDir, `../../packages/proxy/dist/${entryFile}`);
     const bundledDependencyDir = path.resolve(moduleDir, '../node_modules/@geometra/proxy');
     const packageDir = resolveProxyPackageDir(customRequire);
     if (packageDir) {
         if (shouldPreferWorkspaceDist(packageDir, bundledDependencyDir) && existsSync(workspaceDist)) {
             return workspaceDist;
         }
-        const packagedDist = path.join(packageDir, 'dist/index.js');
+        const packagedDist = path.join(packageDir, 'dist', entryFile);
         if (existsSync(packagedDist))
             return packagedDist;
-        const builtLocalDist = buildLocalProxyDistIfPossible(packageDir, errors);
+        const builtLocalDist = buildLocalProxyDistIfPossible(packageDir, entryFile, errors);
         if (builtLocalDist)
             return builtLocalDist;
-        errors.push(`Resolved @geometra/proxy package at ${packageDir}, but dist/index.js was missing`);
+        errors.push(`Resolved @geometra/proxy package at ${packageDir}, but dist/${entryFile} was missing`);
     }
     else {
         errors.push('Could not find @geometra/proxy/package.json via Node module search paths');
@@ -34,24 +43,26 @@ export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR
     try {
         const pkgJson = customRequire.resolve('@geometra/proxy/package.json');
         const exportPackageDir = path.dirname(pkgJson);
-        const packagedDist = path.join(exportPackageDir, 'dist/index.js');
+        const packagedDist = path.join(exportPackageDir, 'dist', entryFile);
         if (existsSync(packagedDist))
             return packagedDist;
-        const builtLocalDist = buildLocalProxyDistIfPossible(exportPackageDir, errors);
+        const builtLocalDist = buildLocalProxyDistIfPossible(exportPackageDir, entryFile, errors);
         if (builtLocalDist)
             return builtLocalDist;
-        errors.push(`Resolved @geometra/proxy/package.json at ${pkgJson}, but dist/index.js was missing`);
+        errors.push(`Resolved @geometra/proxy/package.json at ${pkgJson}, but dist/${entryFile} was missing`);
     }
     catch (err) {
         errors.push(err instanceof Error ? err.message : String(err));
     }
-    try {
-        return customRequire.resolve('@geometra/proxy');
-    }
-    catch (err) {
-        errors.push(err instanceof Error ? err.message : String(err));
+    if (entryFile === 'index.js') {
+        try {
+            return customRequire.resolve('@geometra/proxy');
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+        }
     }
-    const packagedSiblingDist = path.resolve(moduleDir, '../../proxy/dist/index.js');
+    const packagedSiblingDist = path.resolve(moduleDir, `../../proxy/dist/${entryFile}`);
     if (existsSync(packagedSiblingDist)) {
         return packagedSiblingDist;
     }
@@ -60,7 +71,7 @@ export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR
         return workspaceDist;
     }
     errors.push(`Workspace fallback not found at ${workspaceDist}`);
-    throw new Error(`Could not resolve @geometra/proxy. Install it with the MCP package: npm install @geometra/proxy. Resolution errors: ${errors.join(' | ')}`);
+    throw new Error(`Could not resolve @geometra/proxy dist/${entryFile}. Install it with the MCP package: npm install @geometra/proxy. Resolution errors: ${errors.join(' | ')}`);
 }
 function resolveProxyPackageDir(customRequire) {
     const searchRoots = customRequire.resolve.paths('@geometra/proxy') ?? [];
@@ -79,8 +90,8 @@ function shouldPreferWorkspaceDist(packageDir, bundledDependencyDir) {
         return false;
     }
 }
-function buildLocalProxyDistIfPossible(packageDir, errors) {
-    const distEntry = path.join(packageDir, 'dist/index.js');
+function buildLocalProxyDistIfPossible(packageDir, entryFile, errors) {
+    const distEntry = path.join(packageDir, 'dist', entryFile);
     const sourceEntry = path.join(packageDir, 'src/index.ts');
     const tsconfigPath = path.join(packageDir, 'tsconfig.build.json');
     if (!existsSync(sourceEntry) || !existsSync(tsconfigPath)) {
@@ -104,16 +115,32 @@ function buildLocalProxyDistIfPossible(packageDir, errors) {
         }
         if (existsSync(distEntry))
             return distEntry;
-        const realDistEntry = path.join(realPackageDir, 'dist/index.js');
+        const realDistEntry = path.join(realPackageDir, 'dist', entryFile);
         if (existsSync(realDistEntry))
             return realDistEntry;
-        errors.push(`Built local @geometra/proxy at ${realPackageDir}, but dist/index.js is still missing`);
+        errors.push(`Built local @geometra/proxy at ${realPackageDir}, but dist/${entryFile} is still missing`);
     }
     catch (err) {
         errors.push(err instanceof Error ? err.message : String(err));
     }
     return undefined;
 }
+export async function startEmbeddedGeometraProxy(opts) {
+    const runtimePath = resolveProxyRuntimePath();
+    const runtimeModule = await import(pathToFileURL(runtimePath).href);
+    if (typeof runtimeModule.launchProxyRuntime !== 'function') {
+        throw new Error(`Resolved ${runtimePath}, but it did not export launchProxyRuntime()`);
+    }
+    const runtime = await runtimeModule.launchProxyRuntime({
+        url: opts.pageUrl,
+        port: opts.port,
+        width: opts.width,
+        height: opts.height,
+        headed: opts.headless !== true,
+        slowMo: opts.slowMo,
+    });
+    return { runtime, wsUrl: runtime.wsUrl };
+}
 export function parseProxyReadySignalLine(line) {
     const trimmed = line.trim();
     if (!trimmed)