@geometra/mcp 1.19.12 → 1.19.13

package/README.md

@@ -21,6 +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_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 |
@@ -275,19 +277,15 @@ With `python3 -m http.server 8080` in `demos/proxy-mcp-sample` and `npx geometra
 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},"archetypes":["shell","form"],"summary":{...},"forms":[{"id":"fm:1.0","fieldCount":3,"actionCount":1}], ...}
+Agent:  geometra_form_schema({})
+        → {"forms":[{"formId":"fm:1.0","fields":[{"id":"ff:1.0.0","label":"Email"}, ...]}]}
 
-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)
-
-Agent:  geometra_click({ x: <center-x>, y: <center-y> })
-        → Focuses the input
-
-Agent:  geometra_type({ text: "hello@example.com" })
+Agent:  geometra_fill_form({
+          formId: "fm:1.0",
+          valuesByLabel: { "Email": "hello@example.com" },
+          failOnInvalid: true
+        })
+        → {"completed":true,"successCount":1,"errorCount":0,"final":{"invalidCount":0,...}}
 
 Agent:  geometra_query({ role: "button", name: "Save" })
         → Click center to submit the sample form; status text updates in the DOM
@@ -299,21 +297,22 @@ 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`** 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.
+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.
+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.
+10. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
 
 ## Long Forms
 
 For long application flows, prefer one of these patterns:
 
-1. `geometra_page_model`
-2. `geometra_expand_section`
+1. `geometra_form_schema`
+2. `geometra_fill_form`
 3. `geometra_reveal` for far-below-fold targets such as submit buttons
-4. `geometra_fill_fields` for obvious field entry
-5. `geometra_run_actions` when you need mixed navigation + waits + field entry
+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
 
 Typical batch:
 
@@ -335,6 +334,23 @@ For the smallest long-form responses, prefer:
 1. `detail: "minimal"` for structured step metadata instead of narrated deltas
 2. `includeSteps: false` when you only need aggregate success/error counts plus the final validation/state payload
 
+Typical low-token form fill:
+
+```json
+{
+  "formId": "fm:1.0",
+  "valuesById": {
+    "ff:1.0.0": "Taylor Applicant",
+    "ff:1.0.1": "taylor@example.com",
+    "ff:1.0.2": "Germany",
+    "ff:1.0.3": "No"
+  },
+  "failOnInvalid": true,
+  "includeSteps": false,
+  "detail": "minimal"
+}
+```
+
 For long single-page forms:
 
 1. Use `geometra_expand_section` with `fieldOffset` / `actionOffset` to page through large forms instead of taking a full snapshot.

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
@@ -78,7 +78,22 @@ describe('proxy ready helpers', () => {
             const packageDir = path.join(scopeDir, 'proxy');
             const probePath = path.join(tempRoot, 'probe.cjs');
             mkdirSync(scopeDir, { recursive: true });
-            symlinkSync(path.resolve(process.cwd(), 'packages/proxy'), packageDir, 'dir');
+            mkdirSync(path.join(packageDir, 'src'), { recursive: true });
+            writeFileSync(path.join(packageDir, 'package.json'), JSON.stringify({
+                name: '@geometra/proxy',
+                version: '0.0.0-test',
+                type: 'module',
+            }));
+            writeFileSync(path.join(packageDir, 'tsconfig.build.json'), JSON.stringify({
+                extends: path.resolve(process.cwd(), 'tsconfig.base.json'),
+                compilerOptions: {
+                    outDir: 'dist',
+                    rootDir: 'src',
+                    noEmit: false,
+                },
+                include: ['src'],
+            }));
+            writeFileSync(path.join(packageDir, 'src', 'index.ts'), 'console.log("proxy");\n');
             writeFileSync(probePath, 'module.exports = {}');
             const customRequire = createRequire(probePath);
             const scriptPath = resolveProxyScriptPathWith(customRequire);
@@ -89,6 +104,33 @@ describe('proxy ready helpers', () => {
             rmSync(tempRoot, { recursive: true, force: true });
         }
     });
+    it('prefers the current workspace proxy dist over a bundled nested dependency in source checkouts', () => {
+        const tempRoot = mkdtempSync(path.join(tmpdir(), 'geometra-proxy-workspace-prefer-'));
+        try {
+            const workspaceDistDir = path.join(tempRoot, 'packages', 'proxy', 'dist');
+            const bundledProxyDir = path.join(tempRoot, 'mcp', 'node_modules', '@geometra', 'proxy');
+            const bundledDistDir = path.join(bundledProxyDir, 'dist');
+            const mcpDistDir = path.join(tempRoot, 'mcp', 'dist');
+            const probePath = path.join(mcpDistDir, 'proxy-spawn.cjs');
+            mkdirSync(workspaceDistDir, { recursive: true });
+            mkdirSync(bundledDistDir, { recursive: true });
+            mkdirSync(mcpDistDir, { recursive: true });
+            writeFileSync(path.join(workspaceDistDir, 'index.js'), 'export const source = "workspace";\n');
+            writeFileSync(path.join(bundledDistDir, 'index.js'), 'export const source = "bundled";\n');
+            writeFileSync(path.join(bundledProxyDir, 'package.json'), JSON.stringify({
+                name: '@geometra/proxy',
+                version: '0.0.0-test',
+                type: 'module',
+            }));
+            writeFileSync(probePath, 'module.exports = {};\n');
+            const customRequire = createRequire(probePath);
+            const scriptPath = resolveProxyScriptPathWith(customRequire, mcpDistDir);
+            expect(scriptPath).toBe(path.join(workspaceDistDir, 'index.js'));
+        }
+        finally {
+            rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
     it('falls back to the packaged sibling proxy dist when package exports are stale', () => {
         const tempRoot = mkdtempSync(path.join(tmpdir(), 'geometra-proxy-stale-exports-'));
         try {

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

@@ -23,6 +23,9 @@ const mockState = vi.hoisted(() => ({
         url: 'ws://127.0.0.1:3200',
         updateRevision: 1,
     },
+    formSchemas: [],
+    connect: vi.fn(),
+    connectThroughProxy: 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 })),
@@ -36,8 +39,8 @@ const mockState = vi.hoisted(() => ({
     waitForUiCondition: vi.fn(async () => true),
 }));
 vi.mock('../session.js', () => ({
-    connect: vi.fn(),
-    connectThroughProxy: vi.fn(),
+    connect: mockState.connect,
+    connectThroughProxy: mockState.connectThroughProxy,
     disconnect: vi.fn(),
     getSession: vi.fn(() => mockState.session),
     sendClick: mockState.sendClick,
@@ -62,6 +65,7 @@ vi.mock('../session.js', () => ({
         dialogs: [],
         lists: [],
     })),
+    buildFormSchemas: vi.fn(() => mockState.formSchemas),
     expandPageSection: vi.fn(() => null),
     buildUiDelta: vi.fn(() => ({})),
     hasUiDelta: vi.fn(() => false),
@@ -79,6 +83,9 @@ function getToolHandler(name) {
 describe('batch MCP result shaping', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        mockState.connect.mockResolvedValue(mockState.session);
+        mockState.connectThroughProxy.mockResolvedValue(mockState.session);
+        mockState.formSchemas = [];
         mockState.currentA11yRoot = node('group', undefined, {
             meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 420 },
             children: [
@@ -203,6 +210,110 @@ describe('batch MCP result shaping', () => {
         expect(final.invalidFields.length).toBe(4);
         expect(final.alerts.length).toBe(1);
     });
+    it('returns a compact structured connect payload by default', async () => {
+        const handler = getToolHandler('geometra_connect');
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            connected: true,
+            transport: 'proxy',
+            wsUrl: 'ws://127.0.0.1:3200',
+            pageUrl: 'https://jobs.example.com/application',
+        });
+        expect(payload).not.toHaveProperty('currentUi');
+    });
+    it('returns compact form schemas without requiring section expansion', async () => {
+        const handler = getToolHandler('geometra_form_schema');
+        mockState.formSchemas = [
+            {
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 4,
+                requiredCount: 3,
+                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.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({
+                formId: 'fm:0',
+                fieldCount: 4,
+                requiredCount: 3,
+                invalidCount: 0,
+            }),
+        ]);
+    });
+    it('fills a form from ids and labels without echoing long essay content', async () => {
+        const longAnswer = 'B'.repeat(220);
+        const handler = getToolHandler('geometra_fill_form');
+        mockState.formSchemas = [
+            {
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 4,
+                requiredCount: 3,
+                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.2', kind: 'toggle', label: 'Share my profile for future roles', controlType: 'checkbox' },
+                    { id: 'ff:0.3', kind: 'text', label: 'Why Geometra?' },
+                ],
+            },
+        ];
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 640 },
+            children: [
+                node('textbox', 'Full name', { value: 'Taylor Applicant', path: [0] }),
+                node('textbox', 'Why Geometra?', { value: longAnswer, path: [1] }),
+                node('checkbox', 'Share my profile for future roles', {
+                    path: [2],
+                    state: { checked: true },
+                }),
+            ],
+        });
+        const result = await handler({
+            valuesById: {
+                'ff:0.0': 'Taylor Applicant',
+            },
+            valuesByLabel: {
+                'Are you legally authorized to work in Germany?': true,
+                'Share my profile for future roles': true,
+                'Why Geometra?': longAnswer,
+            },
+            includeSteps: true,
+            detail: 'minimal',
+        });
+        const text = result.content[0].text;
+        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(payload).toMatchObject({
+            completed: true,
+            formId: 'fm:0',
+            requestedValueCount: 4,
+            fieldCount: 4,
+            successCount: 4,
+            errorCount: 0,
+        });
+        expect(steps[3]).toMatchObject({
+            kind: 'text',
+            fieldLabel: 'Why Geometra?',
+            valueLength: 220,
+            readback: { role: 'textbox', valueLength: 220 },
+        });
+    });
 });
 describe('query and reveal tools', () => {
     beforeEach(() => {

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+import { buildA11yTree, buildCompactUiIndex, buildFormSchemas, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
 function node(role, name, bounds, options) {
     return {
         role,
@@ -237,6 +237,135 @@ describe('buildPageModel', () => {
         expect(model.forms[0]?.name).toBeUndefined();
     });
 });
+describe('buildFormSchemas', () => {
+    it('builds a compact fill-oriented schema and collapses repeated answer groups', () => {
+        const longEssay = 'Semantic browser automation should be reliable, compact, and predictable across large forms.';
+        const tree = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
+            children: [
+                node('form', 'Application', { x: 32, y: 32, width: 760, height: 1500 }, {
+                    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: 180, width: 320, height: 36 }, {
+                            path: [0, 1],
+                            state: { required: true },
+                            value: 'Berlin, Germany',
+                        }),
+                        node('group', undefined, { x: 40, y: 260, width: 520, height: 96 }, {
+                            path: [0, 2],
+                            children: [
+                                node('text', 'Are you legally authorized to work in Germany?', { x: 48, y: 260, width: 360, height: 24 }, {
+                                    path: [0, 2, 0],
+                                }),
+                                node('button', 'Yes', { x: 48, y: 300, width: 88, height: 40 }, {
+                                    path: [0, 2, 1],
+                                    focusable: true,
+                                    state: { required: true },
+                                }),
+                                node('button', 'No', { x: 148, y: 300, width: 88, height: 40 }, {
+                                    path: [0, 2, 2],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                        node('checkbox', 'Share my profile for future roles', { x: 48, y: 400, width: 24, height: 24 }, {
+                            path: [0, 3],
+                            focusable: true,
+                            state: { checked: true },
+                        }),
+                        node('textbox', 'Why Geometra?', { x: 48, y: 480, width: 520, height: 180 }, {
+                            path: [0, 4],
+                            state: { required: true, invalid: true },
+                            validation: { error: 'Please enter at least 40 characters.' },
+                            value: longEssay,
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const schemas = buildFormSchemas(tree);
+        expect(schemas).toHaveLength(1);
+        expect(schemas[0]).toMatchObject({
+            formId: 'fm:0',
+            name: 'Application',
+            fieldCount: 5,
+            requiredCount: 4,
+            invalidCount: 1,
+        });
+        expect(schemas[0]?.fields).toEqual([
+            expect.objectContaining({
+                kind: 'text',
+                label: 'Full name',
+                required: true,
+            }),
+            expect.objectContaining({
+                kind: 'choice',
+                label: 'Preferred location',
+                required: true,
+                value: 'Berlin, Germany',
+            }),
+            expect.objectContaining({
+                kind: 'choice',
+                label: 'Are you legally authorized to work in Germany?',
+                required: true,
+                optionCount: 2,
+                options: ['Yes', 'No'],
+            }),
+            expect.objectContaining({
+                kind: 'toggle',
+                label: 'Share my profile for future roles',
+                checked: true,
+                controlType: 'checkbox',
+            }),
+            expect.objectContaining({
+                kind: 'text',
+                label: 'Why Geometra?',
+                required: true,
+                invalid: true,
+                valueLength: longEssay.length,
+            }),
+        ]);
+    });
+    it('prefers question prompts over nearby explanatory copy for grouped choices', () => {
+        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 }, {
+                    path: [0],
+                    children: [
+                        node('group', undefined, { x: 32, y: 80, width: 520, height: 120 }, {
+                            path: [0, 0],
+                            children: [
+                                node('text', 'Will you now or in the future require sponsorship?', { x: 40, y: 80, width: 420, height: 24 }, {
+                                    path: [0, 0, 0],
+                                }),
+                                node('text', 'This intentionally repeats Yes / No labels to test contextual disambiguation.', { x: 40, y: 112, width: 520, height: 24 }, {
+                                    path: [0, 0, 1],
+                                }),
+                                node('button', 'Yes', { x: 40, y: 152, width: 88, height: 40 }, {
+                                    path: [0, 0, 2],
+                                    focusable: true,
+                                }),
+                                node('button', 'No', { x: 140, y: 152, width: 88, height: 40 }, {
+                                    path: [0, 0, 3],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const schema = buildFormSchemas(tree)[0];
+        expect(schema?.fields[0]).toMatchObject({
+            kind: 'choice',
+            label: 'Will you now or in the future require sponsorship?',
+            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.js

@@ -1,5 +1,5 @@
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+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';
@@ -13,9 +13,34 @@ export function resolveProxyScriptPath() {
 }
 export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR) {
     const errors = [];
+    const workspaceDist = path.resolve(moduleDir, '../../packages/proxy/dist/index.js');
+    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');
+        if (existsSync(packagedDist))
+            return packagedDist;
+        const builtLocalDist = buildLocalProxyDistIfPossible(packageDir, errors);
+        if (builtLocalDist)
+            return builtLocalDist;
+        errors.push(`Resolved @geometra/proxy package at ${packageDir}, but dist/index.js was missing`);
+    }
+    else {
+        errors.push('Could not find @geometra/proxy/package.json via Node module search paths');
+    }
     try {
         const pkgJson = customRequire.resolve('@geometra/proxy/package.json');
-        return path.join(path.dirname(pkgJson), 'dist/index.js');
+        const exportPackageDir = path.dirname(pkgJson);
+        const packagedDist = path.join(exportPackageDir, 'dist/index.js');
+        if (existsSync(packagedDist))
+            return packagedDist;
+        const builtLocalDist = buildLocalProxyDistIfPossible(exportPackageDir, errors);
+        if (builtLocalDist)
+            return builtLocalDist;
+        errors.push(`Resolved @geometra/proxy/package.json at ${pkgJson}, but dist/index.js was missing`);
     }
     catch (err) {
         errors.push(err instanceof Error ? err.message : String(err));
@@ -31,13 +56,64 @@ export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR
         return packagedSiblingDist;
     }
     errors.push(`Packaged sibling fallback not found at ${packagedSiblingDist}`);
-    const workspaceDist = path.resolve(moduleDir, '../../packages/proxy/dist/index.js');
     if (existsSync(workspaceDist)) {
         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(' | ')}`);
 }
+function resolveProxyPackageDir(customRequire) {
+    const searchRoots = customRequire.resolve.paths('@geometra/proxy') ?? [];
+    for (const searchRoot of searchRoots) {
+        const packageDir = path.join(searchRoot, '@geometra', 'proxy');
+        if (existsSync(path.join(packageDir, 'package.json')))
+            return packageDir;
+    }
+    return undefined;
+}
+function shouldPreferWorkspaceDist(packageDir, bundledDependencyDir) {
+    try {
+        return realpathSync(packageDir) === realpathSync(bundledDependencyDir);
+    }
+    catch {
+        return false;
+    }
+}
+function buildLocalProxyDistIfPossible(packageDir, errors) {
+    const distEntry = path.join(packageDir, 'dist/index.js');
+    const sourceEntry = path.join(packageDir, 'src/index.ts');
+    const tsconfigPath = path.join(packageDir, 'tsconfig.build.json');
+    if (!existsSync(sourceEntry) || !existsSync(tsconfigPath)) {
+        return undefined;
+    }
+    try {
+        const realPackageDir = realpathSync(packageDir);
+        const realTsconfigPath = path.join(realPackageDir, 'tsconfig.build.json');
+        const realDistDir = path.join(realPackageDir, 'dist');
+        const tscBin = require.resolve('typescript/bin/tsc');
+        rmSync(realDistDir, { recursive: true, force: true });
+        const result = spawnSync(process.execPath, [tscBin, '-p', realTsconfigPath], {
+            cwd: realPackageDir,
+            encoding: 'utf8',
+            stdio: 'pipe',
+        });
+        if (result.status !== 0) {
+            const detail = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+            errors.push(`Failed to build local @geometra/proxy at ${realPackageDir}: ${detail || `exit ${result.status ?? 'unknown'}`}`);
+            return undefined;
+        }
+        if (existsSync(distEntry))
+            return distEntry;
+        const realDistEntry = path.join(realPackageDir, 'dist/index.js');
+        if (existsSync(realDistEntry))
+            return realDistEntry;
+        errors.push(`Built local @geometra/proxy at ${realPackageDir}, but dist/index.js is still missing`);
+    }
+    catch (err) {
+        errors.push(err instanceof Error ? err.message : String(err));
+    }
+    return undefined;
+}
 export function parseProxyReadySignalLine(line) {
     const trimmed = line.trim();
     if (!trimmed)

package/dist/server.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
-import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -66,6 +66,12 @@ const fillFieldSchema = z.discriminatedUnion('kind', [
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
     }),
 ]);
+const formValueSchema = z.union([
+    z.string(),
+    z.boolean(),
+    z.array(z.string()).min(1),
+]);
+const formValuesRecordSchema = z.record(z.string(), formValueSchema);
 const batchActionSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('click'),
@@ -146,7 +152,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }),
 ]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.11' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.13' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -184,6 +190,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
+        detail: detailInput(),
     }, async (input) => {
         const normalized = normalizeConnectTarget({ url: input.url, pageUrl: input.pageUrl });
         if (!normalized.ok)
@@ -199,13 +206,20 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     height: input.height,
                     slowMo: input.slowMo,
                 });
-                const summary = compactSessionSummary(session);
-                const inferred = target.autoCoercedFromUrl ? ' inferred from url input' : '';
-                return ok(`Started geometra-proxy and connected at ${session.url} (page: ${target.pageUrl}${inferred}). UI state:\n${summary}`);
+                return ok(JSON.stringify(connectPayload(session, {
+                    transport: 'proxy',
+                    requestedPageUrl: target.pageUrl,
+                    autoCoercedFromUrl: target.autoCoercedFromUrl,
+                    detail: input.detail,
+                }), null, input.detail === 'verbose' ? 2 : undefined));
             }
             const session = await connect(target.wsUrl);
-            const summary = compactSessionSummary(session);
-            return ok(`Connected to ${target.wsUrl}. UI state:\n${summary}`);
+            return ok(JSON.stringify(connectPayload(session, {
+                transport: 'ws',
+                requestedWsUrl: target.wsUrl,
+                autoCoercedFromUrl: false,
+                detail: input.detail,
+            }), null, input.detail === 'verbose' ? 2 : undefined));
         }
         catch (e) {
             return err(`Failed to connect: ${formatConnectFailureMessage(e, target)}`);
@@ -360,6 +374,85 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         }
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
     });
+    server.tool('geometra_fill_form', `Fill a form from a compact values object instead of expanding sections first. This is the lowest-token happy path for standard application flows.
+
+Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most stable matching, or \`valuesByLabel\` when labels are unique enough. MCP resolves the form schema, executes the semantic field operations server-side, and returns one consolidated result.`, {
+        formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
+        valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
+        valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
+        stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing field (default true)'),
+        failOnInvalid: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Return an error if invalid fields remain after filling'),
+        includeSteps: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include per-field step results in the JSON payload (default false for the smallest response)'),
+        detail: detailInput(),
+    }, async ({ formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, detail }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const entryCount = Object.keys(valuesById ?? {}).length + Object.keys(valuesByLabel ?? {}).length;
+        if (entryCount === 0) {
+            return err('Provide at least one value in valuesById or valuesByLabel');
+        }
+        const afterConnect = sessionA11y(session);
+        if (!afterConnect)
+            return err('No UI tree available for form filling');
+        const schemas = buildFormSchemas(afterConnect);
+        if (schemas.length === 0)
+            return err('No forms found in the current UI');
+        const resolution = resolveTargetFormSchema(schemas, { formId, valuesById, valuesByLabel });
+        if (!resolution.ok)
+            return err(resolution.error);
+        const schema = resolution.schema;
+        const planned = planFormFill(schema, { valuesById, valuesByLabel });
+        if (!planned.ok)
+            return err(planned.error);
+        const steps = [];
+        let stoppedAt;
+        for (let index = 0; index < planned.fields.length; index++) {
+            const field = planned.fields[index];
+            try {
+                const result = await executeFillField(session, field, detail);
+                steps.push(detail === 'verbose'
+                    ? { index, kind: field.kind, ok: true, summary: result.summary }
+                    : { index, kind: field.kind, ok: true, ...result.compact });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                steps.push({ index, kind: field.kind, ok: false, error: message });
+                if (stopOnError) {
+                    stoppedAt = index;
+                    break;
+                }
+            }
+        }
+        const after = sessionA11y(session);
+        const signals = after ? collectSessionSignals(after) : undefined;
+        const invalidRemaining = signals?.invalidFields.length ?? 0;
+        const successCount = steps.filter(step => step.ok === true).length;
+        const errorCount = steps.length - successCount;
+        const payload = {
+            completed: stoppedAt === undefined && steps.length === planned.fields.length,
+            formId: schema.formId,
+            requestedValueCount: entryCount,
+            fieldCount: planned.fields.length,
+            successCount,
+            errorCount,
+            ...(includeSteps ? { steps } : {}),
+            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
+        };
+        if (failOnInvalid && invalidRemaining > 0) {
+            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+        }
+        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+    });
     server.tool('geometra_run_actions', `Execute several Geometra actions in one MCP round trip and return one consolidated result. This is the preferred path for long, multi-step form fills where one-tool-per-field would otherwise create too much chatter.
 
 Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, and \`fill_fields\`.`, {
@@ -436,6 +529,29 @@ Use this first on normal HTML pages when you want to understand the page shape w
         const model = buildPageModel(a11y, { maxPrimaryActions, maxSectionsPerKind });
         return ok(JSON.stringify(model));
     });
+    server.tool('geometra_form_schema', `Get a compact, fill-oriented schema for forms on the page. This is the preferred discovery step before geometra_fill_form.
+
+Unlike geometra_expand_section, this collapses repeated radio/button groups into single logical fields, keeps output compact, and omits layout-heavy detail by default.`, {
+        formId: z.string().optional().describe('Optional form id from geometra_page_model. If omitted, returns every form schema on the page.'),
+        maxFields: z.number().int().min(1).max(120).optional().default(80).describe('Cap returned fields per form'),
+        onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields'),
+        onlyInvalidFields: z.boolean().optional().default(false).describe('Only include invalid fields'),
+    }, async ({ formId, maxFields, onlyRequiredFields, onlyInvalidFields }) => {
+        const session = getSession();
+        if (!session?.tree || !session?.layout)
+            return err('Not connected. Call geometra_connect first.');
+        const a11y = buildA11yTree(session.tree, session.layout);
+        const forms = buildFormSchemas(a11y, {
+            formId,
+            maxFields,
+            onlyRequiredFields,
+            onlyInvalidFields,
+        });
+        if (forms.length === 0) {
+            return err(formId ? `No form schema found for id ${formId}` : 'No forms found in the current UI');
+        }
+        return ok(JSON.stringify({ forms }));
+    });
     server.tool('geometra_expand_section', `Expand one section from geometra_page_model by stable id. Returns richer on-demand details such as headings, fields, actions, nested lists, list items, and text preview.
 
 Use this after geometra_page_model when you know which form/dialog/list/landmark you want to inspect more closely. Per-item bounds are omitted by default to save tokens; set includeBounds=true if you need them immediately.`, {
@@ -863,6 +979,18 @@ function compactSessionSummary(session) {
         return 'No UI update received';
     return sessionOverviewFromA11y(a11y);
 }
+function connectPayload(session, opts) {
+    const a11y = sessionA11y(session);
+    return {
+        connected: true,
+        transport: opts.transport,
+        wsUrl: session.url,
+        ...(a11y?.meta?.pageUrl || opts.requestedPageUrl ? { pageUrl: a11y?.meta?.pageUrl ?? opts.requestedPageUrl } : {}),
+        ...(opts.requestedWsUrl ? { requestedWsUrl: opts.requestedWsUrl } : {}),
+        ...(opts.autoCoercedFromUrl ? { autoCoercedFromUrl: true } : {}),
+        ...(opts.detail === 'verbose' && a11y ? { currentUi: sessionOverviewFromA11y(a11y) } : {}),
+    };
+}
 function sessionA11y(session) {
     if (!session.tree || !session.layout)
         return null;
@@ -1072,6 +1200,120 @@ function waitStatusPayload(wait) {
 function compactFilterPayload(filter) {
     return Object.fromEntries(Object.entries(filter).filter(([, value]) => value !== undefined));
 }
+function normalizeLookupKey(value) {
+    return value.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+function resolveTargetFormSchema(schemas, opts) {
+    if (opts.formId) {
+        const matched = schemas.find(schema => schema.formId === opts.formId);
+        return matched
+            ? { ok: true, schema: matched }
+            : { ok: false, error: `No form schema found for id ${opts.formId}` };
+    }
+    if (schemas.length === 1)
+        return { ok: true, schema: schemas[0] };
+    const idKeys = Object.keys(opts.valuesById ?? {});
+    const labelKeys = Object.keys(opts.valuesByLabel ?? {}).map(normalizeLookupKey);
+    const matches = schemas.filter(schema => {
+        const ids = new Set(schema.fields.map(field => field.id));
+        const labels = new Set(schema.fields.map(field => normalizeLookupKey(field.label)));
+        return idKeys.every(id => ids.has(id)) && labelKeys.every(label => labels.has(label));
+    });
+    if (matches.length === 1)
+        return { ok: true, schema: matches[0] };
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: 'Could not infer which form to fill from the provided field ids/labels. Pass formId from geometra_form_schema.',
+        };
+    }
+    return {
+        ok: false,
+        error: 'Multiple forms match the provided field ids/labels. Pass formId from geometra_form_schema.',
+    };
+}
+function coerceChoiceValue(field, value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value !== 'boolean')
+        return null;
+    const desired = value ? 'yes' : 'no';
+    const option = field.options?.find(option => normalizeLookupKey(option) === desired);
+    return option ?? (value ? 'Yes' : 'No');
+}
+function plannedFillInputsForField(field, value) {
+    if (field.kind === 'text') {
+        if (typeof value !== 'string')
+            return { error: `Field "${field.label}" expects a string value` };
+        return [{ kind: 'text', fieldLabel: field.label, value }];
+    }
+    if (field.kind === 'choice') {
+        const coerced = coerceChoiceValue(field, value);
+        if (!coerced)
+            return { error: `Field "${field.label}" expects a string value` };
+        return [{ kind: 'choice', fieldLabel: field.label, value: coerced }];
+    }
+    if (field.kind === 'toggle') {
+        if (typeof value !== 'boolean')
+            return { error: `Field "${field.label}" expects a boolean value` };
+        return [{ kind: 'toggle', label: field.label, checked: value, controlType: field.controlType }];
+    }
+    const selected = Array.isArray(value) ? value : typeof value === 'string' ? [value] : null;
+    if (!selected || selected.length === 0)
+        return { error: `Field "${field.label}" expects a string array value` };
+    if (!field.options || field.options.length === 0) {
+        return { error: `Field "${field.label}" does not expose checkbox options; use geometra_fill_fields for this field` };
+    }
+    const selectedKeys = new Set(selected.map(normalizeLookupKey));
+    return field.options.map(option => ({
+        kind: 'toggle',
+        label: option,
+        checked: selectedKeys.has(normalizeLookupKey(option)),
+        controlType: 'checkbox',
+    }));
+}
+function planFormFill(schema, opts) {
+    const fieldById = new Map(schema.fields.map(field => [field.id, field]));
+    const fieldsByLabel = new Map();
+    for (const field of schema.fields) {
+        const key = normalizeLookupKey(field.label);
+        const existing = fieldsByLabel.get(key);
+        if (existing)
+            existing.push(field);
+        else
+            fieldsByLabel.set(key, [field]);
+    }
+    const planned = [];
+    const seenFieldIds = new Set();
+    for (const [fieldId, value] of Object.entries(opts.valuesById ?? {})) {
+        const field = fieldById.get(fieldId);
+        if (!field)
+            return { ok: false, error: `Unknown form field id ${fieldId}. Refresh geometra_form_schema and try again.` };
+        const next = plannedFillInputsForField(field, value);
+        if ('error' in next)
+            return { ok: false, error: next.error };
+        planned.push(...next);
+        seenFieldIds.add(field.id);
+    }
+    for (const [label, value] of Object.entries(opts.valuesByLabel ?? {})) {
+        const matches = fieldsByLabel.get(normalizeLookupKey(label)) ?? [];
+        if (matches.length === 0)
+            return { ok: false, error: `Unknown form field label "${label}". Refresh geometra_form_schema and try again.` };
+        if (matches.length > 1) {
+            return { ok: false, error: `Label "${label}" is ambiguous in form ${schema.formId}. Use valuesById for this field.` };
+        }
+        const field = matches[0];
+        if (seenFieldIds.has(field.id)) {
+            return { ok: false, error: `Field "${label}" was provided in both valuesById and valuesByLabel` };
+        }
+        const next = plannedFillInputsForField(field, value);
+        if ('error' in next)
+            return { ok: false, error: next.error };
+        planned.push(...next);
+        seenFieldIds.add(field.id);
+    }
+    return { ok: true, fields: planned };
+}
 async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {

package/dist/session.d.ts

@@ -241,6 +241,30 @@ export interface PageSectionDetail {
     items: PageListItemModel[];
     textPreview: string[];
 }
+export type FormSchemaFieldKind = 'text' | 'choice' | 'toggle' | 'multi_choice';
+export interface FormSchemaField {
+    id: string;
+    kind: FormSchemaFieldKind;
+    label: string;
+    required?: boolean;
+    invalid?: boolean;
+    controlType?: 'checkbox' | 'radio';
+    value?: string;
+    valueLength?: number;
+    checked?: boolean;
+    values?: string[];
+    optionCount?: number;
+    options?: string[];
+    context?: NodeContextModel;
+}
+export interface FormSchemaModel {
+    formId: string;
+    name?: string;
+    fieldCount: number;
+    requiredCount: number;
+    invalidCount: number;
+    fields: FormSchemaField[];
+}
 export interface UiNodeUpdate {
     before: CompactUiNode;
     after: CompactUiNode;
@@ -413,6 +437,12 @@ export declare function buildPageModel(root: A11yNode, options?: {
     maxPrimaryActions?: number;
     maxSectionsPerKind?: number;
 }): PageModel;
+export declare function buildFormSchemas(root: A11yNode, options?: {
+    formId?: string;
+    maxFields?: number;
+    onlyRequiredFields?: boolean;
+    onlyInvalidFields?: boolean;
+}): FormSchemaModel[];
 /**
  * Expand a page-model section by stable ID into richer, on-demand details.
  */

package/dist/session.js

@@ -387,6 +387,9 @@ function decodePath(encoded) {
 export function nodeIdForPath(path) {
     return `n:${encodePath(path)}`;
 }
+function formFieldIdForPath(path) {
+    return `ff:${encodePath(path)}`;
+}
 function sectionPrefix(kind) {
     if (kind === 'landmark')
         return 'lm';
@@ -800,7 +803,9 @@ function nearestPromptText(container, target) {
         const dy = Math.max(0, target.bounds.y - candidate.bounds.y);
         const dx = Math.abs(target.bounds.x - candidate.bounds.x);
         const headingBonus = candidate.role === 'heading' ? -32 : 0;
-        return { text, score: dy * 4 + dx + headingBonus };
+        const questionBonus = /\?\s*$/.test(text) ? -160 : 0;
+        const lengthPenalty = text.length > 90 ? 80 : text.length > 60 ? 40 : text.length > 45 ? 20 : 0;
+        return { text, score: dy * 4 + dx + headingBonus + questionBonus + lengthPenalty };
     })
         .filter((candidate) => !!candidate)
         .sort((a, b) => a.score - b.score)[0];
@@ -809,13 +814,19 @@ function nearestPromptText(container, target) {
 function nodeContext(root, node) {
     const ancestors = ancestorNodes(root, node.path);
     let prompt;
-    for (let index = ancestors.length - 1; index >= 0; index--) {
-        const ancestor = ancestors[index];
-        const grouped = countGroupedChoiceControls(ancestor) >= 2;
-        if (grouped || ancestor.role === 'group' || ancestor.role === 'form' || ancestor.role === 'dialog') {
-            prompt = nearestPromptText(ancestor, node);
-            if (prompt)
-                break;
+    const promptEligibleNode = node.role === 'radio' || node.role === 'button';
+    if (promptEligibleNode) {
+        for (let index = ancestors.length - 1; index >= 0; index--) {
+            const ancestor = ancestors[index];
+            const grouped = countGroupedChoiceControls(ancestor) >= 2;
+            const eligiblePromptContainer = (ancestor.role === 'group' && ancestor.path.length > 0) ||
+                ancestor.role === 'dialog' ||
+                (ancestor.role === 'form' && grouped);
+            if (eligiblePromptContainer) {
+                prompt = nearestPromptText(ancestor, node);
+                if (prompt)
+                    break;
+            }
         }
     }
     let section;
@@ -868,6 +879,173 @@ function toActionModel(root, node, includeBounds = true) {
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
 }
+function compactSchemaContext(context, label) {
+    if (!context)
+        return undefined;
+    const out = {};
+    if (context.prompt && normalizeUiText(context.prompt) !== normalizeUiText(label))
+        out.prompt = context.prompt;
+    if (context.section)
+        out.section = context.section;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function compactSchemaValue(value, inlineLimit = 80) {
+    const normalized = sanitizeInlineName(value, Math.max(120, inlineLimit + 32));
+    if (!normalized)
+        return {};
+    return normalized.length <= inlineLimit
+        ? { value: normalized }
+        : { valueLength: normalized.length };
+}
+function schemaOptionLabel(node) {
+    return sanitizeFieldName(node.name, 80) ?? sanitizeInlineName(node.name, 80);
+}
+function isGroupedChoiceControl(node) {
+    return node.role === 'radio' || node.role === 'checkbox' || (node.role === 'button' && node.focusable);
+}
+function groupedChoiceForNode(root, formNode, seed) {
+    const context = nodeContext(root, seed);
+    const prompt = context?.prompt;
+    if (!prompt)
+        return null;
+    const matchesPrompt = (candidate) => {
+        if (!isGroupedChoiceControl(candidate))
+            return false;
+        return nodeContext(root, candidate)?.prompt === prompt;
+    };
+    const ancestors = ancestorNodes(root, seed.path);
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        if (ancestor.role === 'form')
+            continue;
+        const controls = sortByBounds(collectDescendants(ancestor, matchesPrompt));
+        if (controls.length >= 2) {
+            return { container: ancestor, prompt, controls };
+        }
+    }
+    if (seed.role !== 'radio' && seed.role !== 'button')
+        return null;
+    const controls = sortByBounds(collectDescendants(formNode, matchesPrompt));
+    return controls.length >= 2 ? { container: formNode, prompt, controls } : null;
+}
+function simpleSchemaField(root, node) {
+    const context = nodeContext(root, node);
+    const label = fieldLabel(node) ?? sanitizeInlineName(node.name, 80) ?? context?.prompt;
+    if (!label)
+        return null;
+    return {
+        id: formFieldIdForPath(node.path),
+        kind: node.role === 'combobox' ? 'choice' : 'text',
+        label,
+        ...(node.state?.required ? { required: true } : {}),
+        ...(node.state?.invalid ? { invalid: true } : {}),
+        ...compactSchemaValue(node.value, 72),
+        ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
+    };
+}
+function groupedSchemaField(root, grouped) {
+    const optionEntries = grouped.controls
+        .map(control => ({
+        label: schemaOptionLabel(control),
+        selected: control.state?.checked === true || control.state?.selected === true,
+        role: control.role,
+    }))
+        .filter((entry) => !!entry.label);
+    if (optionEntries.length < 2)
+        return null;
+    const options = dedupeStrings(optionEntries.map(entry => entry.label), 16);
+    const selectedOptions = dedupeStrings(optionEntries.filter(entry => entry.selected).map(entry => entry.label), 16);
+    const radioLike = optionEntries.every(entry => entry.role === 'radio' || entry.role === 'button');
+    const context = nodeContext(root, grouped.controls[0]);
+    return {
+        id: formFieldIdForPath(grouped.container.path),
+        kind: radioLike ? 'choice' : 'multi_choice',
+        label: grouped.prompt,
+        ...(grouped.controls.some(control => control.state?.required) ? { required: true } : {}),
+        ...(grouped.controls.some(control => control.state?.invalid) ? { invalid: true } : {}),
+        ...(radioLike
+            ? {
+                ...(selectedOptions[0] ? { value: selectedOptions[0] } : {}),
+            }
+            : {
+                ...(selectedOptions.length > 0 ? { values: selectedOptions } : {}),
+            }),
+        optionCount: options.length,
+        options,
+        ...(compactSchemaContext(context, grouped.prompt) ? { context: compactSchemaContext(context, grouped.prompt) } : {}),
+    };
+}
+function toggleSchemaField(root, node) {
+    const label = schemaOptionLabel(node);
+    if (!label)
+        return null;
+    const context = nodeContext(root, node);
+    const controlType = node.role === 'radio' ? 'radio' : 'checkbox';
+    return {
+        id: formFieldIdForPath(node.path),
+        kind: 'toggle',
+        label,
+        controlType,
+        ...(node.state?.required ? { required: true } : {}),
+        ...(node.state?.invalid ? { invalid: true } : {}),
+        ...(node.state?.checked !== undefined ? { checked: node.state.checked === true } : {}),
+        ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
+    };
+}
+function buildFormSchemaForNode(root, formNode, options) {
+    const candidates = sortByBounds(collectDescendants(formNode, candidate => candidate.role === 'textbox' ||
+        candidate.role === 'combobox' ||
+        candidate.role === 'checkbox' ||
+        candidate.role === 'radio' ||
+        (candidate.role === 'button' && candidate.focusable)));
+    const consumed = new Set();
+    const fields = [];
+    for (const candidate of candidates) {
+        const candidateKey = pathKey(candidate.path);
+        if (consumed.has(candidateKey))
+            continue;
+        if (candidate.role === 'textbox' || candidate.role === 'combobox') {
+            const field = simpleSchemaField(root, candidate);
+            if (field)
+                fields.push(field);
+            consumed.add(candidateKey);
+            continue;
+        }
+        const grouped = groupedChoiceForNode(root, formNode, candidate);
+        if (grouped && grouped.controls.some(control => pathKey(control.path) === candidateKey)) {
+            const field = groupedSchemaField(root, grouped);
+            for (const control of grouped.controls)
+                consumed.add(pathKey(control.path));
+            if (field)
+                fields.push(field);
+            continue;
+        }
+        if (candidate.role === 'checkbox' || candidate.role === 'radio') {
+            const field = toggleSchemaField(root, candidate);
+            if (field)
+                fields.push(field);
+            consumed.add(candidateKey);
+        }
+    }
+    const filteredFields = fields.filter(field => {
+        if (options?.onlyRequiredFields && !field.required)
+            return false;
+        if (options?.onlyInvalidFields && !field.invalid)
+            return false;
+        return true;
+    });
+    const maxFields = options?.maxFields ?? filteredFields.length;
+    const pageFields = filteredFields.slice(0, maxFields);
+    const name = sectionDisplayName(formNode, 'form');
+    return {
+        formId: sectionIdForPath('form', formNode.path),
+        ...(name ? { name } : {}),
+        fieldCount: fields.length,
+        requiredCount: fields.filter(field => field.required).length,
+        invalidCount: fields.filter(field => field.invalid).length,
+        fields: pageFields,
+    };
+}
 function toLandmarkModel(node) {
     const name = sectionDisplayName(node, 'landmark');
     return {
@@ -991,6 +1169,15 @@ export function buildPageModel(root, options) {
         archetypes: inferPageArchetypes(baseModel),
     };
 }
+export function buildFormSchemas(root, options) {
+    const forms = sortByBounds([
+        ...(root.role === 'form' ? [root] : []),
+        ...collectDescendants(root, candidate => candidate.role === 'form'),
+    ]);
+    return forms
+        .filter(form => !options?.formId || sectionIdForPath('form', form.path) === options.formId)
+        .map(form => buildFormSchemaForNode(root, form, options));
+}
 function headingModels(node, maxHeadings, includeBounds) {
     const headings = sortByBounds(collectDescendants(node, candidate => candidate.role === 'heading' && !!sanitizeInlineName(candidate.name, 80)));
     return headings.slice(0, maxHeadings).map(heading => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.19.12",
+  "version": "1.19.13",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "ui-testing"
   ],
   "dependencies": {
-    "@geometra/proxy": "^1.19.12",
+    "@geometra/proxy": "^1.19.13",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.18.0",
     "zod": "^3.23.0"