@geometra/mcp 1.18.1 → 1.19.1

package/README.md

@@ -1,6 +1,8 @@
 # @geometra/mcp
 
-MCP server for [Geometra](https://github.com/razroo/geometra) — interact with running Geometra apps via the geometry protocol over WebSocket. For **native** Geometra apps there is no browser in the loop. For **any existing website**, pair this MCP server with [`@geometra/proxy`](../packages/proxy/README.md) (headless Chromium) so the same tools speak the same GEOM v1 wire format.
+MCP server for [Geometra](https://github.com/razroo/geometra) — interact with running Geometra apps via the geometry protocol over WebSocket. For **native** Geometra apps there is no browser in the loop. For **any existing website**, use **`geometra_connect` with `pageUrl`** — the MCP server starts [`@geometra/proxy`](../packages/proxy/README.md) for you (bundled dependency) so you do not need a separate terminal or a `ws://` URL. You can still pass `url: "ws://…"` if a proxy is already running, and if you accidentally pass `https://…` in `url`, MCP will treat it as `pageUrl` and auto-start the proxy.
+
+See [`AGENT_MODEL.md`](./AGENT_MODEL.md) for the MCP mental model, why token usage can be lower than large browser snapshots, and how headed vs headless proxy mode works.
 
 ## What this does
 
@@ -9,16 +11,17 @@ Connects Claude Code, Codex, or any MCP-compatible AI agent to a WebSocket endpo
 ```
 Playwright + vision:  screenshot → model → guess coordinates → click → repeat
 Native Geometra:      WebSocket → JSON geometry (no browser on the agent path)
-Geometra proxy:       Headless Chromium → DOM geometry → same WebSocket as native → MCP tools unchanged
+Geometra proxy:       Chromium → DOM geometry → same WebSocket as native → MCP tools unchanged (often started via `pageUrl`, no manual CLI)
 ```
 
 ## Tools
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect to a running Geometra server |
-| `geometra_query` | Find elements by role, name, or text content |
-| `geometra_page_model` | Higher-level webpage model: landmarks, forms, dialogs, lists, short previews |
+| `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, or text content |
+| `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
+| `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand |
 | `geometra_click` | Click an element by coordinates |
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
@@ -73,6 +76,8 @@ npm run server  # starts on ws://localhost:3100
 
 ### Any web app (Geometra proxy)
 
+**Preferred path for agents:** call `geometra_connect({ pageUrl: "https://…" })` and let MCP spawn the proxy for you on an ephemeral local port. The manual CLI below is still useful for debugging or when you want to inspect the proxy directly.
+
 In one terminal, serve or open a page (example uses the repo sample):
 
 ```bash
@@ -87,6 +92,8 @@ npx geometra-proxy http://localhost:8080 --port 3200
 # Requires Chromium: npx playwright install chromium
 ```
 
+`geometra-proxy` opens a **visible Chromium window by default**. For servers or CI, pass **`--headless`** or set **`GEOMETRA_HEADLESS=1`**. Optional **`--slow-mo <ms>`** slows Playwright actions so they are easier to watch. Headed vs headless usually does **not** materially change token usage, since token usage is driven by MCP tool output rather than whether Chromium is visible.
+
 Point MCP at `ws://127.0.0.1:3200` instead of a native Geometra server. The proxy translates clicks and keyboard messages into Playwright actions and streams updated geometry.
 
 Then in Claude Code (either backend):
@@ -94,7 +101,7 @@ Then in Claude Code (either backend):
 ```
 > Connect to my Geometra app at ws://localhost:3100 and tell me what's on screen
 
-> Give me the page model first, then find the main form
+> Give me the page model first, then expand the main form
 
 > Click the "Submit" button
 
@@ -136,7 +143,10 @@ Agent:  geometra_connect({ url: "ws://127.0.0.1:3200" })
         → Connected. UI includes textbox "Email", button "Save", …
 
 Agent:  geometra_page_model({})
-        → {"viewport":{"width":1024,"height":768},"landmarks":[...],"forms":[...],"dialogs":[],"lists":[]}
+        → {"viewport":{"width":1024,"height":768},"archetypes":["shell","form"],"summary":{...},"forms":[{"id":"fm:1.0","fieldCount":3,"actionCount":1}], ...}
+
+Agent:  geometra_expand_section({ id: "fm:1.0" })
+        → {"id":"fm:1.0","kind":"form","fields":[{"id":"n:1.0.0","name":"Email"}, ...], "actions":[...]}
 
 Agent:  geometra_query({ role: "textbox", name: "Email" })
         → bounds for the email field (viewport coordinates)
@@ -156,9 +166,10 @@ 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_page_model`** extracts higher-level webpage structure (landmarks, forms, dialogs, lists) so agents can reason about normal HTML pages without pulling a full tree first.
-6. 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.
-7. Tools expose query, click, type, snapshot, and page-model operations over this structured data.
-8. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
+5. **`geometra_page_model`** is summary-first: page archetypes, stable section ids, counts, top-level landmarks/forms/dialogs/lists, and a few primary actions. It is designed to be cheaper than dumping full previews for every section.
+6. **`geometra_expand_section`** fetches richer details only for the section you care about (fields, actions, headings, nested lists, list items, text preview).
+7. 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.
+8. Tools expose query, click, type, snapshot, page-model, and section-expansion operations over this structured data.
+9. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
 
 With a **native** Geometra server, layout comes from Textura/Yoga. With **`@geometra/proxy`**, layout comes from the browser’s computed DOM geometry; the MCP layer is the same.

package/dist/__tests__/connect-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/connect-utils.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { formatConnectFailureMessage, normalizeConnectTarget } from '../connect-utils.js';
+import { formatProxyStartupFailure, parseProxyReadySignalLine } from '../proxy-spawn.js';
+describe('normalizeConnectTarget', () => {
+    it('accepts explicit pageUrl for http(s) pages', () => {
+        const result = normalizeConnectTarget({ pageUrl: 'https://example.com/jobs/123' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: 'https://example.com/jobs/123',
+                autoCoercedFromUrl: false,
+            },
+        });
+    });
+    it('rejects non-http pageUrl protocols', () => {
+        const result = normalizeConnectTarget({ pageUrl: 'ws://127.0.0.1:3100' });
+        expect(result).toEqual({
+            ok: false,
+            error: 'pageUrl must use http:// or https:// (received ws:)',
+        });
+    });
+    it('auto-coerces http url input onto the proxy path', () => {
+        const result = normalizeConnectTarget({ url: 'https://jobs.example.com/apply' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: 'https://jobs.example.com/apply',
+                autoCoercedFromUrl: true,
+            },
+        });
+    });
+    it('accepts ws url input for already-running peers', () => {
+        const result = normalizeConnectTarget({ url: 'ws://127.0.0.1:3100' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'ws',
+                wsUrl: 'ws://127.0.0.1:3100/',
+                autoCoercedFromUrl: false,
+            },
+        });
+    });
+    it('rejects ambiguous and empty connect inputs', () => {
+        expect(normalizeConnectTarget({})).toEqual({
+            ok: false,
+            error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).',
+        });
+        expect(normalizeConnectTarget({ url: 'ws://127.0.0.1:3100', pageUrl: 'https://example.com' })).toEqual({
+            ok: false,
+            error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).',
+        });
+    });
+});
+describe('formatConnectFailureMessage', () => {
+    it('adds a targeted hint when ws connect fails for a normal webpage flow', () => {
+        const message = formatConnectFailureMessage(new Error('WebSocket error connecting to ws://localhost:3100: connect ECONNREFUSED'), { kind: 'ws', wsUrl: 'ws://localhost:3100', autoCoercedFromUrl: false });
+        expect(message).toContain('ECONNREFUSED');
+        expect(message).toContain('pageUrl: "https://…"');
+    });
+});
+describe('proxy ready helpers', () => {
+    it('parses structured proxy ready JSON', () => {
+        const wsUrl = parseProxyReadySignalLine('{"type":"geometra-proxy-ready","wsUrl":"ws://127.0.0.1:41237","pageUrl":"https://example.com"}');
+        expect(wsUrl).toBe('ws://127.0.0.1:41237');
+    });
+    it('still accepts legacy human-readable ready logs', () => {
+        const wsUrl = parseProxyReadySignalLine('[geometra-proxy] WebSocket listening on ws://127.0.0.1:3200');
+        expect(wsUrl).toBe('ws://127.0.0.1:3200');
+    });
+    it('adds install and port conflict hints to proxy startup failures', () => {
+        const chromiumHint = formatProxyStartupFailure("browserType.launch: Executable doesn't exist at /tmp/chromium", { pageUrl: 'https://example.com', port: 0 });
+        expect(chromiumHint).toContain('npx playwright install chromium');
+        const portHint = formatProxyStartupFailure('listen EADDRINUSE: address already in use 127.0.0.1:3337', { pageUrl: 'https://example.com', port: 3337 });
+        expect(portHint).toContain('Requested port 3337 is unavailable');
+    });
+});

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { buildPageModel, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+import { buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
 function node(role, name, bounds, options) {
     return {
         role,
@@ -12,7 +12,7 @@ function node(role, name, bounds, options) {
     };
 }
 describe('buildPageModel', () => {
-    it('extracts landmarks, forms, and lists from a typical webpage tree', () => {
+    it('builds a summary-first page model with stable section ids', () => {
         const tree = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
             children: [
                 node('navigation', 'Primary nav', { x: 0, y: 0, width: 220, height: 80 }, { path: [0] }),
@@ -43,20 +43,82 @@ describe('buildPageModel', () => {
         });
         const model = buildPageModel(tree);
         expect(model.viewport).toEqual({ width: 1024, height: 768 });
-        expect(model.landmarks.map(item => item.role)).toEqual(['navigation', 'main', 'form']);
+        expect(model.archetypes).toEqual(expect.arrayContaining(['shell', 'form', 'results']));
+        expect(model.summary).toEqual({
+            landmarkCount: 3,
+            formCount: 1,
+            dialogCount: 0,
+            listCount: 1,
+            focusableCount: 1,
+        });
+        expect(model.landmarks.map(item => item.id)).toEqual(['lm:0', 'lm:1', 'lm:1.0']);
         expect(model.forms).toHaveLength(1);
         expect(model.forms[0]).toMatchObject({
+            id: 'fm:1.0',
             name: 'Job application',
             fieldCount: 2,
             actionCount: 1,
         });
-        expect(model.forms[0]?.fields.map(field => field.name)).toEqual(['Full name', 'Email']);
-        expect(model.forms[0]?.actions.map(action => action.name)).toEqual(['Submit application']);
         expect(model.lists[0]).toMatchObject({
+            id: 'ls:1.1',
             name: 'Open roles',
             itemCount: 2,
-            itemsPreview: ['Designer', 'Engineer'],
         });
+        expect(model.primaryActions).toEqual([
+            expect.objectContaining({
+                id: 'n:1.0.2',
+                role: 'button',
+                name: 'Submit application',
+            }),
+        ]);
+    });
+    it('expands a section by id on demand', () => {
+        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('form', 'Job application', { x: 40, y: 120, width: 520, height: 280 }, {
+                            path: [0, 0],
+                            children: [
+                                node('heading', 'Application', { x: 60, y: 132, width: 200, height: 24 }, { path: [0, 0, 0] }),
+                                node('textbox', 'Full name*', { x: 60, y: 160, width: 300, height: 36 }, { path: [0, 0, 1] }),
+                                node('textbox', 'Email:', { x: 60, y: 208, width: 300, height: 36 }, { path: [0, 0, 2] }),
+                                node('button', 'Submit application', { x: 60, y: 264, width: 180, height: 40 }, {
+                                    path: [0, 0, 3],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const detail = expandPageSection(tree, 'fm:0.0');
+        expect(detail).toMatchObject({
+            id: 'fm:0.0',
+            kind: 'form',
+            role: 'form',
+            name: 'Application',
+            summary: {
+                headingCount: 1,
+                fieldCount: 2,
+                actionCount: 1,
+            },
+        });
+        expect(detail?.fields.map(field => field.name)).toEqual(['Full name', 'Email']);
+        expect(detail?.actions.map(action => action.id)).toEqual(['n:0.0.3']);
+        expect(detail?.fields[0]).not.toHaveProperty('bounds');
+    });
+    it('drops noisy container names and falls back to unnamed summaries', () => {
+        const tree = node('group', undefined, { x: 0, y: 0, width: 800, height: 600 }, {
+            children: [
+                node('form', 'First Name* Last Name* Email* Phone* Country* Location* Resume* LinkedIn*', { x: 20, y: 20, width: 500, height: 400 }, { path: [0] }),
+            ],
+        });
+        const model = buildPageModel(tree);
+        expect(model.forms[0]?.id).toBe('fm:0');
+        expect(model.forms[0]?.name).toBeUndefined();
     });
 });
 describe('buildUiDelta', () => {
@@ -115,14 +177,15 @@ describe('buildUiDelta', () => {
         const delta = buildUiDelta(before, after);
         expect(hasUiDelta(delta)).toBe(true);
         expect(delta.dialogsOpened).toHaveLength(1);
+        expect(delta.dialogsOpened[0]?.id).toBe('dg:0.2');
         expect(delta.dialogsOpened[0]?.name).toBe('Save complete');
         expect(delta.listCountsChanged).toEqual([
-            { name: 'Results', path: [0, 1], beforeCount: 2, afterCount: 3 },
+            { id: 'ls:0.1', name: 'Results', beforeCount: 2, afterCount: 3 },
         ]);
         expect(delta.updated.some(update => update.after.name === 'Save' && update.changes.some(change => change.includes('disabled')))).toBe(true);
         const summary = summarizeUiDelta(delta);
-        expect(summary).toContain('+ dialog "Save complete" opened');
-        expect(summary).toContain('~ list "Results" items 2 -> 3');
-        expect(summary).toContain('~ button "Save": disabled unset -> true');
+        expect(summary).toContain('+ dg:0.2 dialog "Save complete" opened');
+        expect(summary).toContain('~ ls:0.1 list "Results" items 2 -> 3');
+        expect(summary).toContain('~ n:0.0 button "Save": disabled unset -> true');
     });
 });

package/dist/connect-utils.d.ts

@@ -0,0 +1,18 @@
+export interface NormalizedConnectTarget {
+    kind: 'proxy' | 'ws';
+    autoCoercedFromUrl: boolean;
+    pageUrl?: string;
+    wsUrl?: string;
+}
+export declare function normalizeConnectTarget(input: {
+    url?: string;
+    pageUrl?: string;
+}): {
+    ok: true;
+    value: NormalizedConnectTarget;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function formatConnectFailureMessage(err: unknown, target: NormalizedConnectTarget): string;
+export declare function isHttpUrl(value: string): boolean;

package/dist/connect-utils.js

@@ -0,0 +1,94 @@
+export function normalizeConnectTarget(input) {
+    const rawUrl = normalizeOptional(input.url);
+    const rawPageUrl = normalizeOptional(input.pageUrl);
+    if (rawUrl && rawPageUrl) {
+        return { ok: false, error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).' };
+    }
+    if (!rawUrl && !rawPageUrl) {
+        return { ok: false, error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).' };
+    }
+    if (rawPageUrl) {
+        const parsed = parseUrl(rawPageUrl);
+        if (!parsed) {
+            return { ok: false, error: `Invalid pageUrl: ${rawPageUrl}` };
+        }
+        if (!isHttpProtocol(parsed.protocol)) {
+            return { ok: false, error: `pageUrl must use http:// or https:// (received ${parsed.protocol})` };
+        }
+        return {
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: parsed.toString(),
+                autoCoercedFromUrl: false,
+            },
+        };
+    }
+    const parsed = parseUrl(rawUrl);
+    if (!parsed) {
+        return {
+            ok: false,
+            error: `Invalid url: ${rawUrl}. Use ws://... for an already-running Geometra server, or https://... for a normal webpage.`,
+        };
+    }
+    if (isHttpProtocol(parsed.protocol)) {
+        return {
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: parsed.toString(),
+                autoCoercedFromUrl: true,
+            },
+        };
+    }
+    if (isWsProtocol(parsed.protocol)) {
+        return {
+            ok: true,
+            value: {
+                kind: 'ws',
+                wsUrl: parsed.toString(),
+                autoCoercedFromUrl: false,
+            },
+        };
+    }
+    return {
+        ok: false,
+        error: `Unsupported url protocol ${parsed.protocol}. Use ws://... for an already-running Geometra server, or http:// / https:// for webpages.`,
+    };
+}
+export function formatConnectFailureMessage(err, target) {
+    const base = err instanceof Error ? err.message : String(err);
+    const hints = [];
+    if (target.kind === 'ws' &&
+        /ECONNREFUSED|timed out|closed before first frame|WebSocket error connecting/i.test(base)) {
+        hints.push('If this is a normal website, call geometra_connect with pageUrl: "https://…" so MCP can start @geometra/proxy for you.');
+    }
+    if (/Could not resolve @geometra\/proxy/i.test(base)) {
+        hints.push('Ensure @geometra/proxy is installed alongside @geometra/mcp.');
+    }
+    if (hints.length === 0)
+        return base;
+    return `${base}\nHint: ${hints.join(' ')}`;
+}
+export function isHttpUrl(value) {
+    const parsed = parseUrl(value);
+    return parsed !== null && isHttpProtocol(parsed.protocol);
+}
+function normalizeOptional(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function parseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function isHttpProtocol(protocol) {
+    return protocol === 'http:' || protocol === 'https:';
+}
+function isWsProtocol(protocol) {
+    return protocol === 'ws:' || protocol === 'wss:';
+}

package/dist/index.js

@@ -1,12 +1,39 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
+import { disconnect } from './session.js';
+let cleanedUp = false;
+function cleanupActiveSession() {
+    if (cleanedUp)
+        return;
+    cleanedUp = true;
+    try {
+        disconnect();
+    }
+    catch {
+        /* ignore */
+    }
+}
 async function main() {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+process.on('SIGINT', () => {
+    cleanupActiveSession();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    cleanupActiveSession();
+    process.exit(0);
+});
+process.on('SIGHUP', () => {
+    cleanupActiveSession();
+    process.exit(0);
+});
+process.on('exit', cleanupActiveSession);
 main().catch((err) => {
+    cleanupActiveSession();
     console.error('geometra-mcp: failed to start', err);
     process.exit(1);
 });

package/dist/proxy-spawn.d.ts

@@ -0,0 +1,20 @@
+import { type ChildProcess } from 'node:child_process';
+/** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
+export declare function resolveProxyScriptPath(): string;
+export interface SpawnProxyParams {
+    pageUrl: string;
+    port: number;
+    headless?: boolean;
+    width?: number;
+    height?: number;
+    slowMo?: number;
+}
+export declare function parseProxyReadySignalLine(line: string): string | undefined;
+export declare function formatProxyStartupFailure(message: string, opts: SpawnProxyParams): string;
+/**
+ * Spawn geometra-proxy as a child process and resolve when it emits a structured ready signal.
+ */
+export declare function spawnGeometraProxy(opts: SpawnProxyParams): Promise<{
+    child: ChildProcess;
+    wsUrl: string;
+}>;

package/dist/proxy-spawn.js

@@ -0,0 +1,131 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+const require = createRequire(import.meta.url);
+const READY_SIGNAL_TYPE = 'geometra-proxy-ready';
+const READY_TIMEOUT_MS = 45_000;
+/** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
+export function resolveProxyScriptPath() {
+    try {
+        const pkgJson = require.resolve('@geometra/proxy/package.json');
+        return path.join(path.dirname(pkgJson), 'dist/index.js');
+    }
+    catch {
+        throw new Error('Could not resolve @geometra/proxy. Install it with the MCP package: npm install @geometra/proxy');
+    }
+}
+export function parseProxyReadySignalLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.type === READY_SIGNAL_TYPE &&
+                typeof parsed.wsUrl === 'string' &&
+                /^ws:\/\/127\.0\.0\.1:\d+$/.test(parsed.wsUrl)) {
+                return parsed.wsUrl;
+            }
+        }
+        catch {
+            /* ignore non-JSON lines */
+        }
+    }
+    const fallback = trimmed.match(/WebSocket listening on (ws:\/\/127\.0\.0\.1:\d+)/);
+    return fallback?.[1];
+}
+export function formatProxyStartupFailure(message, opts) {
+    const hints = [];
+    if (/Executable doesn't exist|playwright install chromium|browserType\.launch/i.test(message)) {
+        hints.push('Install Chromium with: npx playwright install chromium');
+    }
+    if (opts.port > 0 && /EADDRINUSE|address already in use/i.test(message)) {
+        hints.push(`Requested port ${opts.port} is unavailable. Omit the port to use an ephemeral OS-assigned port, or choose another local port.`);
+    }
+    if (hints.length === 0)
+        return message;
+    return `${message}\nHint: ${hints.join(' ')}`;
+}
+/**
+ * Spawn geometra-proxy as a child process and resolve when it emits a structured ready signal.
+ */
+export function spawnGeometraProxy(opts) {
+    const script = resolveProxyScriptPath();
+    const args = [script, opts.pageUrl, '--port', String(opts.port)];
+    if (opts.width != null && opts.width > 0)
+        args.push('--width', String(opts.width));
+    if (opts.height != null && opts.height > 0)
+        args.push('--height', String(opts.height));
+    if (opts.slowMo != null && opts.slowMo > 0)
+        args.push('--slow-mo', String(opts.slowMo));
+    if (opts.headless === true)
+        args.push('--headless');
+    else if (opts.headless === false)
+        args.push('--headed');
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GEOMETRA_PROXY_READY_JSON: '1' },
+        });
+        let settled = false;
+        let stdoutBuf = '';
+        let stderrBuf = '';
+        const cleanup = () => {
+            clearTimeout(deadline);
+            child.stdout?.removeAllListeners('data');
+            child.stderr?.removeAllListeners('data');
+        };
+        const tryResolveReady = (line) => {
+            const wsUrl = parseProxyReadySignalLine(line);
+            if (!wsUrl || settled)
+                return false;
+            settled = true;
+            cleanup();
+            resolve({ child, wsUrl });
+            return true;
+        };
+        const consumeStdout = (chunk) => {
+            stdoutBuf += chunk.toString();
+            const lines = stdoutBuf.split(/\r?\n/);
+            stdoutBuf = lines.pop() ?? '';
+            for (const line of lines) {
+                if (tryResolveReady(line))
+                    return;
+            }
+        };
+        const consumeStderr = (chunk) => {
+            stderrBuf += chunk.toString();
+            const lines = stderrBuf.split(/\r?\n/);
+            stderrBuf = lines.pop() ?? '';
+            for (const line of lines) {
+                if (tryResolveReady(line))
+                    return;
+            }
+        };
+        const deadline = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                child.kill('SIGTERM');
+                cleanup();
+                reject(new Error(formatProxyStartupFailure('geometra-proxy did not emit a ready signal within 45s', opts)));
+            }
+        }, READY_TIMEOUT_MS);
+        child.stdout?.on('data', consumeStdout);
+        child.stderr?.on('data', consumeStderr);
+        child.on('error', err => {
+            if (!settled) {
+                settled = true;
+                cleanup();
+                reject(new Error(formatProxyStartupFailure(err.message, opts)));
+            }
+        });
+        child.on('exit', (code, sig) => {
+            if (!settled) {
+                settled = true;
+                cleanup();
+                const stderrTail = stderrBuf.trim().slice(-2000);
+                reject(new Error(formatProxyStartupFailure(`geometra-proxy exited before ready (code=${code} signal=${sig}). Stderr (tail): ${stderrTail || '(empty)'}`, opts)));
+            }
+        });
+    });
+}