@geometra/mcp 1.19.20 → 1.19.22

package/README.md

@@ -27,22 +27,23 @@ Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a sm
 | `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; can inline `formSchema` and/or `pageModel` for lower-turn starts |
 | `geometra_query` | Find elements by stable id, role, name, text content, ancestor/prompt context, current value, or semantic state such as `invalid`, `required`, or `busy` |
 | `geometra_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.). **Strict parameters** — use `text` plus `present: false` to wait until a substring disappears (e.g. “Parsing your resume”); there is no `textGone` field |
+| `geometra_wait_for_resume_parse` | Convenience wait until a parsing banner is gone (defaults: `text`: `"Parsing"`, `present` implied false). Same engine as `geometra_wait_for` |
 | `geometra_form_schema` | Compact, fill-oriented form schema with stable field ids and collapsed radio/button groups; can auto-connect from `pageUrl` / `url` |
 | `geometra_fill_form` | Fill a form from `valuesById` / `valuesByLabel` in one MCP call; can auto-connect from `pageUrl` / `url` for the lowest-token known-form path |
-| `geometra_fill_fields` | Fill labeled text/choice/toggle/file fields in one MCP call; can return final-only status for the smallest responses |
+| `geometra_fill_fields` | Fill text/choice/toggle/file fields in one MCP call; text/choice/toggle entries can use `fieldId` from `geometra_form_schema` without repeating the label |
 | `geometra_run_actions` | Execute a batch of high-level actions in one MCP round trip and get one consolidated result, with optional final-only output |
 | `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
 | `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand, with paging/filtering for long sections |
-| `geometra_reveal` | Scroll until a matching node is visible instead of guessing wheel deltas |
+| `geometra_reveal` | Scroll until a matching node is visible instead of guessing wheel deltas; auto-scales reveal steps for tall forms when omitted |
 | `geometra_click` | Click by coordinates or semantic target, optionally waiting for a post-click semantic condition |
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
 | `geometra_upload_files` | Attach files: labeled field / auto / hidden input / native chooser / synthetic drop (`@geometra/proxy` only) |
-| `geometra_pick_listbox_option` | Pick an option from a custom dropdown/searchable combobox; can open by field label (`@geometra/proxy` only) |
-| `geometra_select_option` | Choose an option on a native `<select>` (`@geometra/proxy` only) |
+| `geometra_pick_listbox_option` | Pick an option from a custom dropdown/searchable combobox; can open by field label, falls back to keyboard selection, and returns visible option hints on failure (`@geometra/proxy` only) |
+| `geometra_select_option` | Choose an option on a native `<select>` only; use `geometra_pick_listbox_option` for custom dropdowns (`@geometra/proxy` only) |
 | `geometra_set_checked` | Set a checkbox or radio by label instead of coordinate clicks (`@geometra/proxy` only) |
 | `geometra_wheel` | Mouse wheel / scroll (`@geometra/proxy` only) |
-| `geometra_snapshot` | Default **compact**: flat viewport-visible actionable nodes (minified JSON). `view=full` for nested tree |
+| `geometra_snapshot` | Default **compact**: flat viewport-visible actionable nodes (minified JSON). `view=full` for nested tree, `view=form-required` for required fields including offscreen ones |
 | `geometra_layout` | Raw computed geometry for every node |
 | `geometra_disconnect` | Close the connection |
 
@@ -50,6 +51,20 @@ Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a sm
 
 The tool input is **strict**: unknown keys are rejected (so mistaken names like `textGone` fail fast instead of being ignored). To wait until copy such as “Parsing…” or “Parsing your resume” is **gone**, pass a substring that matches the banner in **`text`** and set **`present`** to **`false`**. Example: `{ "text": "Parsing", "present": false }` (adjust the substring per site).
 
+For the common resume-upload case, prefer **`geometra_wait_for_resume_parse`** (optional `text`, default `"Parsing"`; optional `timeoutMs`, default `60000`) so agents do not have to remember `present: false`.
+
+### Custom dropdowns and searchable comboboxes
+
+Use **`geometra_pick_listbox_option`** for React Select / Radix / Headless UI / custom ATS dropdowns. Prefer **`fieldLabel`** so MCP opens the right combobox semantically, and pass **`query`** when the dropdown is searchable. If click-selection cannot be confirmed, the proxy now falls back to keyboard navigation for editable comboboxes.
+
+When selection fails, the error payload includes a capped **`visibleOptions`** list so an agent can retry with a real label instead of blindly guessing. Use **`geometra_select_option`** only for native HTML `<select>` controls.
+
+### Long forms and offscreen required fields
+
+For tall application forms, **`geometra_snapshot({ view: "form-required" })`** returns required fields even when they are offscreen, with **bounds**, **visibility**, and **scrollHint** data. This is useful for “what required fields are left?” without paging through a full tree.
+
+When a target is below the fold, **`geometra_reveal`** and semantic click actions auto-scale reveal steps when `maxSteps` / `maxRevealSteps` are omitted, so long forms do not fail after a hard-coded short scroll budget. If you already have schema ids, **`geometra_fill_fields`** can now use `fieldId` directly for text / choice / toggle entries without repeating `fieldLabel` / `label`.
+
 ## Setup
 
 <details>
@@ -304,13 +319,14 @@ Agent:  geometra_query({ role: "button", name: "Save" })
 1. The MCP server connects to a WebSocket peer that speaks GEOM v1 (`frame` with `layout` + `tree`, optional `patch` updates).
 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.
+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 or `view: "form-required"` for offscreen required fields plus scroll hints.
 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.
-10. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
+7. **`geometra_fill_fields`** is the lower-level field-intent path when you need direct control; text / choice / toggle entries can now resolve `fieldId` from `geometra_form_schema` without repeating labels.
+8. **`geometra_page_model`** is still the right summary-first path for non-form exploration: page archetypes, stable section ids, counts, top-level landmarks/forms/dialogs/lists, and a few primary actions.
+9. **`geometra_expand_section`** fetches richer details only for the section you care about (fields, actions, headings, nested lists, list items, text preview).
+10. After interactions, action tools return a **semantic delta** when possible (dialogs opened/closed, forms appeared/removed, list counts changed, named/focusable nodes added/removed/updated). If nothing meaningful changed, they fall back to a short current-UI overview.
+11. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
 
 ## Long Forms
 
@@ -319,11 +335,12 @@ For long application flows, prefer one of these patterns:
 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_click({ ..., waitFor: ... })` when one action should also wait for the next semantic state
-5. `geometra_run_actions` when you need mixed navigation + waits + field entry
-6. `geometra_connect({ pageUrl, returnPageModel: true })` when you want connect + summary-first exploration in one turn
-7. `geometra_page_model` + `geometra_expand_section` when you are still exploring the page rather than filling it
+4. `geometra_snapshot({ view: "form-required" })` when you need the remaining required fields including offscreen ones
+5. `geometra_reveal` for far-below-fold targets such as submit buttons (auto-scales reveal steps when you omit `maxSteps`)
+6. `geometra_click({ ..., waitFor: ... })` when one action should also wait for the next semantic state
+7. `geometra_run_actions` when you need mixed navigation + waits + field entry
+8. `geometra_connect({ pageUrl, returnPageModel: true })` when you want connect + summary-first exploration in one turn
+9. `geometra_page_model` + `geometra_expand_section` when you are still exploring the page rather than filling it
 
 Typical batch:
 

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

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

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

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

package/dist/server.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 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, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -68,19 +68,44 @@ function waitConditionShape() {
 }
 const GEOMETRA_QUERY_FILTER_REQUIRED_MESSAGE = 'Provide at least one filter (id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
     'This tool uses a strict schema: unknown keys are rejected. There is no textGone parameter — use text for substring matching. ' +
-    'To wait until text disappears from the UI, use geometra_wait_for with text and present: false.';
+    'To wait until text disappears from the UI, use geometra_wait_for with text and present: false, or geometra_wait_for_resume_parse for typical resume “Parsing…” banners.';
 const GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE = 'Provide at least one semantic filter (id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
     'This tool uses a strict schema: unknown keys are rejected. There is no textGone parameter — use text with a distinctive substring and present: false to wait until that text is gone ' +
     '(common for “Parsing…”, “Parsing your resume”, or similar). Passing only present/timeoutMs is not enough without a filter.';
 /** Strict input so unknown keys (e.g. textGone) fail parse; empty-filter checks happen in handlers / waitForSemanticCondition. */
 const geometraQueryInputSchema = z.object(nodeFilterShape()).strict();
 const geometraWaitForInputSchema = z.object(waitConditionShape()).strict();
+/** Same upper bound as geometra_wait_for; resume uploads often need the full minute. */
+const geometraWaitForResumeParseInputSchema = z
+    .object({
+    text: z
+        .string()
+        .min(1)
+        .default('Parsing')
+        .describe('Substring that appears in the loading/parsing banner while work is in progress (default matches copy like “Parsing your resume”, “Parsing…”, “Parsing resume”, etc.)'),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(50)
+        .max(60_000)
+        .default(60_000)
+        .describe('Maximum time to wait before returning an error (default 60000ms)'),
+})
+    .strict();
 const timeoutMsInput = z.number().int().min(50).max(60_000).optional();
-const fillFieldSchema = z.discriminatedUnion('kind', [
+const fillFieldSchema = z.union([
     z.object({
         kind: z.literal('text'),
         fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        fieldLabel: z.string().describe('Visible field label / accessible name'),
+        fieldLabel: z.string().describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
+        value: z.string().describe('Text value to set'),
+        exact: z.boolean().optional().describe('Exact label match'),
+        timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
+    }),
+    z.object({
+        kind: z.literal('text'),
+        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
+        fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         value: z.string().describe('Text value to set'),
         exact: z.boolean().optional().describe('Exact label match'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
@@ -88,7 +113,20 @@ const fillFieldSchema = z.discriminatedUnion('kind', [
     z.object({
         kind: z.literal('choice'),
         fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        fieldLabel: z.string().describe('Visible field label / accessible name'),
+        fieldLabel: z.string().describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
+        value: z.string().describe('Desired option value / answer label'),
+        query: z.string().optional().describe('Optional search text for searchable comboboxes'),
+        choiceType: z
+            .enum(['select', 'group', 'listbox'])
+            .optional()
+            .describe('Optional choice subtype hint. Use `group` for repeated radio/button answers, `select` for native selects, and `listbox` for searchable dropdowns.'),
+        exact: z.boolean().optional().describe('Exact label match'),
+        timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
+    }),
+    z.object({
+        kind: z.literal('choice'),
+        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
+        fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         value: z.string().describe('Desired option value / answer label'),
         query: z.string().optional().describe('Optional search text for searchable comboboxes'),
         choiceType: z
@@ -101,7 +139,16 @@ const fillFieldSchema = z.discriminatedUnion('kind', [
     z.object({
         kind: z.literal('toggle'),
         fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        label: z.string().describe('Visible checkbox/radio label to set'),
+        label: z.string().describe('Visible checkbox/radio label to set. Optional to duplicate when fieldId is present.'),
+        checked: z.boolean().optional().default(true).describe('Desired checked state (default true)'),
+        exact: z.boolean().optional().describe('Exact label match'),
+        controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
+        timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
+    }),
+    z.object({
+        kind: z.literal('toggle'),
+        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
+        label: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         checked: z.boolean().optional().default(true).describe('Desired checked state (default true)'),
         exact: z.boolean().optional().describe('Exact label match'),
         controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
@@ -115,6 +162,14 @@ const fillFieldSchema = z.discriminatedUnion('kind', [
         exact: z.boolean().optional().describe('Exact label match'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
     }),
+    z.object({
+        kind: z.literal('file'),
+        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
+        fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label when file fields are exposed by geometra_form_schema'),
+        paths: z.array(z.string()).min(1).describe('Absolute paths on the proxy machine'),
+        exact: z.boolean().optional().describe('Exact label match'),
+        timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
+    }),
 ]);
 const formValueSchema = z.union([
     z.string(),
@@ -130,7 +185,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
         ...nodeFilterShape(),
         index: z.number().int().min(0).optional().describe('Which matching semantic target to click after sorting top-to-bottom'),
         fullyVisible: z.boolean().optional().describe('When clicking by semantic target, require full visibility before clicking (default true)'),
-        maxRevealSteps: z.number().int().min(1).max(12).optional().describe('Maximum reveal attempts before clicking a semantic target'),
+        maxRevealSteps: z.number().int().min(1).max(48).optional().describe('Maximum reveal attempts before clicking a semantic target. When omitted, Geometra auto-scales from scroll distance for tall forms.'),
         revealTimeoutMs: timeoutMsInput.describe('Per-scroll wait timeout while revealing a semantic target'),
         waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the click'),
         timeoutMs: timeoutMsInput,
@@ -208,7 +263,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }),
 ]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.20' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.21' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -333,13 +388,14 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
         }
     });
     // ── query ────────────────────────────────────────────────────
-    server.tool('geometra_query', `Find elements in the current Geometra UI by stable id, role, name, text content, current value, or semantic state. Returns matching elements with their exact pixel bounds {x, y, width, height}, visible in-viewport bounds, an on-screen center point, visibility / scroll-reveal hints, role, name, value, state, and tree path.
+    server.registerTool('geometra_query', {
+        description: `Find elements in the current Geometra UI by stable id, role, name, text content, current value, or semantic state. Returns matching elements with their exact pixel bounds {x, y, width, height}, visible in-viewport bounds, an on-screen center point, visibility / scroll-reveal hints, role, name, value, state, and tree path.
 
 This is the Geometra equivalent of Playwright's locator — but instant, structured, and with no browser. Use the returned bounds to click elements or assert on layout.
 
-Unknown parameter names are rejected (strict schema). To wait until visible text goes away (e.g. a parsing banner), use geometra_wait_for with that substring in text and present: false — there is no textGone field.`, 
-    // SDK overload typings only list raw shapes; runtime accepts ZodObject via getZodSchemaObject().
-    geometraQueryInputSchema, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
+Unknown parameter names are rejected (strict schema). To wait until visible text goes away (e.g. a parsing banner), use geometra_wait_for with that substring in text and present: false — there is no textGone field.`,
+        inputSchema: geometraQueryInputSchema,
+    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -371,9 +427,12 @@ Unknown parameter names are rejected (strict schema). To wait until visible text
         const result = sortA11yNodes(matches).map(node => formatNode(node, a11y, a11y.bounds));
         return ok(JSON.stringify(result, null, 2));
     });
-    server.tool('geometra_wait_for', `Wait for a semantic UI condition without guessing sleep durations. Use this for slow SPA transitions, resume parsing, custom validation alerts, disabled submit buttons, and value/state confirmation before submit.
+    server.registerTool('geometra_wait_for', {
+        description: `Wait for a semantic UI condition without guessing sleep durations. Use this for slow SPA transitions, resume parsing, custom validation alerts, disabled submit buttons, and value/state confirmation before submit.
 
-The filter matches the same fields as geometra_query (strict schema — unknown keys error). Set \`present: false\` to wait until **no** node matches — for example Ashby/Lever-style “Parsing your resume” or any “Parsing…” banner: \`{ "text": "Parsing", "present": false }\` (tune the substring to the site). Do not use a textGone parameter; use \`text\` + \`present: false\`.`, geometraWaitForInputSchema, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
+The filter matches the same fields as geometra_query (strict schema — unknown keys error). Set \`present: false\` to wait until **no** node matches — for example Ashby/Lever-style “Parsing your resume” or any “Parsing…” banner: \`{ "text": "Parsing", "present": false }\` (tune the substring to the site). Do not use a textGone parameter; use \`text\` + \`present: false\`, or \`geometra_wait_for_resume_parse\` for the usual post-upload parsing banner.`,
+        inputSchema: geometraWaitForInputSchema,
+    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -407,10 +466,29 @@ The filter matches the same fields as geometra_query (strict schema — unknown
         }
         return ok(JSON.stringify(waited.value.matches.slice(0, 8), null, 2));
     });
+    server.registerTool('geometra_wait_for_resume_parse', {
+        description: `Wait until **no** visible text contains the given substring — optimized for ATS “parsing your resume” / file-processing banners after upload.
+
+Equivalent to \`geometra_wait_for\` with \`present: false\` and \`text\` set to a banner substring. Default \`text\` is \`Parsing\` (tune per site). Strict schema (unknown keys rejected).`,
+        inputSchema: geometraWaitForResumeParseInputSchema,
+    }, async ({ text, timeoutMs }) => {
+        const session = getSession();
+        if (!session?.tree || !session?.layout)
+            return err('Not connected. Call geometra_connect first.');
+        const filter = { text };
+        const waited = await waitForSemanticCondition(session, {
+            filter,
+            present: false,
+            timeoutMs,
+        });
+        if (!waited.ok)
+            return err(waited.error);
+        return ok(waitConditionSuccessLine(waited.value));
+    });
     server.tool('geometra_fill_fields', `Fill several labeled form fields in one MCP call. This is the preferred high-level primitive for long forms.
 
-Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / comboboxes / radio-style questions addressed by field label + answer, \`"toggle"\` for individually labeled checkboxes or radios, and \`"file"\` for labeled uploads.`, {
-        fields: z.array(fillFieldSchema).min(1).max(80).describe('Ordered labeled field operations to apply'),
+Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / comboboxes / radio-style questions addressed by field label + answer, \`"toggle"\` for individually labeled checkboxes or radios, and \`"file"\` for labeled uploads. When \`fieldId\` from \`geometra_form_schema\` is present, MCP can resolve the current label server-side so you do not need to duplicate \`fieldLabel\` / \`label\` for text, choice, and toggle fields.`, {
+        fields: z.array(fillFieldSchema).min(1).max(80).describe('Ordered field operations to apply. Use fieldId from geometra_form_schema to omit duplicate fieldLabel/label on schema-backed fields.'),
         stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing field (default true)'),
         failOnInvalid: z
             .boolean()
@@ -427,10 +505,13 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
+        const resolvedFields = resolveFillFieldInputs(session, fields);
+        if (!resolvedFields.ok)
+            return err(resolvedFields.error);
         const steps = [];
         let stoppedAt;
-        for (let index = 0; index < fields.length; index++) {
-            const field = fields[index];
+        for (let index = 0; index < resolvedFields.fields.length; index++) {
+            const field = resolvedFields.fields[index];
             try {
                 const result = await executeFillField(session, field, detail);
                 steps.push(detail === 'verbose'
@@ -452,8 +533,8 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         const successCount = steps.filter(step => step.ok === true).length;
         const errorCount = steps.length - successCount;
         const payload = {
-            completed: stoppedAt === undefined && steps.length === fields.length,
-            fieldCount: fields.length,
+            completed: stoppedAt === undefined && steps.length === resolvedFields.fields.length,
+            fieldCount: resolvedFields.fields.length,
             successCount,
             errorCount,
             ...(includeSteps ? { steps } : {}),
@@ -847,7 +928,7 @@ Use the same filters as geometra_query, plus an optional match index when repeat
         ...nodeFilterShape(),
         index: z.number().int().min(0).optional().default(0).describe('Which matching node to reveal after sorting top-to-bottom'),
         fullyVisible: z.boolean().optional().default(true).describe('Require the target to become fully visible (default true)'),
-        maxSteps: z.number().int().min(1).max(12).optional().default(6).describe('Maximum reveal attempts before returning an error'),
+        maxSteps: z.number().int().min(1).max(48).optional().describe('Maximum reveal attempts before returning an error. When omitted, Geometra auto-scales from scroll distance for tall forms.'),
         timeoutMs: z
             .number()
             .int()
@@ -882,7 +963,7 @@ Use the same filters as geometra_query, plus an optional match index when repeat
             filter,
             index: index ?? 0,
             fullyVisible: fullyVisible ?? true,
-            maxSteps: maxSteps ?? 6,
+            maxSteps,
             timeoutMs: timeoutMs ?? 2_500,
         });
         if (!revealed.ok)
@@ -902,7 +983,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
         ...nodeFilterShape(),
         index: z.number().int().min(0).optional().default(0).describe('Which matching semantic target to click after sorting top-to-bottom'),
         fullyVisible: z.boolean().optional().default(true).describe('When clicking by semantic target, require full visibility before clicking (default true)'),
-        maxRevealSteps: z.number().int().min(1).max(12).optional().default(6).describe('Maximum reveal attempts before clicking a semantic target'),
+        maxRevealSteps: z.number().int().min(1).max(48).optional().describe('Maximum reveal attempts before clicking a semantic target. When omitted, Geometra auto-scales from scroll distance for tall forms.'),
         revealTimeoutMs: z
             .number()
             .int()
@@ -1075,7 +1156,7 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
     });
     server.tool('geometra_pick_listbox_option', `Pick an option from a custom dropdown / listbox / searchable combobox (Headless UI, React Select, Radix, Ashby-style custom selects, etc.). Requires \`@geometra/proxy\`.
 
-Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying on coordinates. If the opened control is editable, MCP types \`query\` (or the option label by default) before selecting. Uses substring name match unless exact=true, prefers the popup nearest the opened field, and handles a few short affirmative/negative aliases such as \`Yes\` /\`No\` for consent-style copy.`, {
+Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying on coordinates. If the opened control is editable, MCP types \`query\` (or the option label by default) before selecting. Uses fuzzy-ish substring/alias matching unless exact=true, prefers the popup nearest the opened field, can fall back to keyboard navigation for searchable comboboxes, and returns capped \`visibleOptions\` in failure payloads so agents can retry with a real label.`, {
         label: z.string().describe('Accessible name of the option (visible text or aria-label)'),
         exact: z.boolean().optional().describe('Exact name match'),
         openX: z.number().optional().describe('Click to open dropdown'),
@@ -1117,7 +1198,7 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
     // ── select option (proxy, native <select>) ─────────────────────
     server.tool('geometra_select_option', `Set a native HTML \`<select>\` after clicking its center (x,y from geometra_query). Requires \`@geometra/proxy\`.
 
-Custom React/Vue dropdowns are not supported — open them with geometra_click and pick options by snapshot instead.`, {
+Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbox_option\` for custom dropdowns / searchable comboboxes.`, {
         x: z.number().describe('X coordinate (e.g. center of the select from geometra_query)'),
         y: z.number().describe('Y coordinate'),
         value: z.string().optional().describe('Option value= attribute'),
@@ -1206,14 +1287,14 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         }
     });
     // ── snapshot ─────────────────────────────────────────────────
-    server.tool('geometra_snapshot', `Get the current UI as JSON. Default **compact** view: flat list of viewport-visible actionable nodes plus a few pinned context anchors (for example tab strips / form roots) and root context like URL, scroll, and focus — far fewer tokens than a full nested tree. Use **full** for complete nested a11y + every wrapper when debugging layout.
+    server.tool('geometra_snapshot', `Get the current UI as JSON. Default **compact** view: flat list of viewport-visible actionable nodes plus a few pinned context anchors (for example tab strips / form roots) and root context like URL, scroll, and focus — far fewer tokens than a full nested tree. Use **full** for complete nested a11y + every wrapper when debugging layout. Use **form-required** to list required fields across forms, including offscreen ones, with bounds + visibility + scroll hints for long application flows.
 
 JSON is minified in compact view to save tokens. For a summary-first overview, use geometra_page_model, then geometra_expand_section for just the part you want.`, {
         view: z
-            .enum(['compact', 'full'])
+            .enum(['compact', 'full', 'form-required'])
             .optional()
             .default('compact')
-            .describe('compact (default): token-efficient flat index. full: nested tree, every node.'),
+            .describe('compact (default): token-efficient flat index. full: nested tree, every node. form-required: required fields across forms, including offscreen controls.'),
         maxNodes: z
             .number()
             .int()
@@ -1222,7 +1303,10 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
             .optional()
             .default(400)
             .describe('Max rows in compact view (default 400).'),
-    }, async ({ view, maxNodes }) => {
+        formId: z.string().optional().describe('Optional form id from geometra_form_schema / geometra_page_model when view=form-required'),
+        maxFields: z.number().int().min(1).max(200).optional().default(80).describe('Per-form field cap when view=form-required'),
+        includeOptions: z.boolean().optional().default(false).describe('Include explicit choice option labels when view=form-required'),
+    }, async ({ view, maxNodes, formId, maxFields, includeOptions }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -1232,6 +1316,19 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
         if (view === 'full') {
             return ok(JSON.stringify(a11y, null, 2));
         }
+        if (view === 'form-required') {
+            const payload = {
+                view: 'form-required',
+                viewport: { width: a11y.bounds.width, height: a11y.bounds.height },
+                forms: buildFormRequiredSnapshot(a11y, {
+                    formId,
+                    maxFields,
+                    includeOptions,
+                    includeContext: 'auto',
+                }),
+            };
+            return ok(JSON.stringify(payload));
+        }
         const { nodes, truncated, context } = buildCompactUiIndex(a11y, { maxNodes });
         const payload = {
             view: 'compact',
@@ -1731,9 +1828,15 @@ function waitConditionCompact(result) {
         ...(result.present ? { matchCount: result.matchCount } : {}),
     };
 }
+function inferRevealStepBudget(target, viewport) {
+    const verticalSteps = Math.ceil(Math.abs(target.scrollHint.revealDeltaY) / Math.max(1, viewport.height * 0.75));
+    const horizontalSteps = Math.ceil(Math.abs(target.scrollHint.revealDeltaX) / Math.max(1, viewport.width * 0.7));
+    return clamp(Math.max(6, Math.max(verticalSteps, horizontalSteps) + 1), 6, 48);
+}
 async function revealSemanticTarget(session, options) {
     let attempts = 0;
-    while (attempts <= options.maxSteps) {
+    let stepBudget = options.maxSteps;
+    while (attempts <= (stepBudget ?? 48)) {
         const a11y = sessionA11y(session);
         if (!a11y)
             return { ok: false, error: 'No UI tree available to reveal from' };
@@ -1748,6 +1851,7 @@ async function revealSemanticTarget(session, options) {
             };
         }
         const formatted = formatNode(matches[options.index], a11y, a11y.bounds);
+        stepBudget ??= inferRevealStepBudget(formatted, a11y.bounds);
         const visible = options.fullyVisible ? formatted.visibility.fullyVisible : formatted.visibility.intersectsViewport;
         if (visible) {
             return {
@@ -1758,12 +1862,13 @@ async function revealSemanticTarget(session, options) {
                 },
             };
         }
-        if (attempts === options.maxSteps) {
+        if (attempts === stepBudget) {
             return {
                 ok: false,
                 error: JSON.stringify({
                     revealed: false,
                     attempts,
+                    maxSteps: stepBudget,
                     target: formatted,
                 }, null, 2),
             };
@@ -1806,7 +1911,7 @@ async function resolveClickLocation(session, options) {
         filter: options.filter,
         index: options.index ?? 0,
         fullyVisible: options.fullyVisible ?? true,
-        maxSteps: options.maxRevealSteps ?? 6,
+        maxSteps: options.maxRevealSteps,
         timeoutMs: options.revealTimeoutMs ?? 2_500,
     });
     if (!revealed.ok)
@@ -1954,8 +2059,109 @@ function planFormFill(schema, opts) {
     }
     return { ok: true, fields: planned };
 }
+function isResolvedFillFieldInput(field) {
+    if (field.kind === 'toggle')
+        return typeof field.label === 'string' && field.label.length > 0;
+    return typeof field.fieldLabel === 'string' && field.fieldLabel.length > 0;
+}
+function resolveFillFieldInputs(session, fields) {
+    const unresolved = fields.filter(field => !isResolvedFillFieldInput(field));
+    if (unresolved.length === 0) {
+        return { ok: true, fields: fields };
+    }
+    const a11y = sessionA11y(session);
+    if (!a11y)
+        return { ok: false, error: 'No UI tree available to resolve fieldId entries from geometra_form_schema' };
+    const fieldById = new Map();
+    for (const schema of buildFormSchemas(a11y, { includeOptions: true, includeContext: 'always' })) {
+        for (const field of schema.fields)
+            fieldById.set(field.id, field);
+    }
+    const resolved = [];
+    for (const field of fields) {
+        if (isResolvedFillFieldInput(field)) {
+            if (field.kind === 'choice' && field.fieldId && field.choiceType === undefined) {
+                const schemaField = fieldById.get(field.fieldId);
+                resolved.push({
+                    ...field,
+                    ...(schemaField?.kind === 'choice' && schemaField.choiceType ? { choiceType: schemaField.choiceType } : {}),
+                });
+            }
+            else if (field.kind === 'toggle' && field.fieldId && field.controlType === undefined) {
+                const schemaField = fieldById.get(field.fieldId);
+                resolved.push({
+                    ...field,
+                    ...(schemaField?.kind === 'toggle' && schemaField.controlType ? { controlType: schemaField.controlType } : {}),
+                });
+            }
+            else {
+                resolved.push(field);
+            }
+            continue;
+        }
+        if (!field.fieldId) {
+            return {
+                ok: false,
+                error: field.kind === 'toggle'
+                    ? 'Toggle fields require label, or provide fieldId from geometra_form_schema so MCP can resolve the current label.'
+                    : `${field.kind} fields require fieldLabel, or provide fieldId from geometra_form_schema so MCP can resolve the current label.`,
+            };
+        }
+        const schemaField = fieldById.get(field.fieldId);
+        if (!schemaField) {
+            return { ok: false, error: `Unknown form field id ${field.fieldId}. Refresh geometra_form_schema and try again.` };
+        }
+        if (field.kind === 'text') {
+            if (schemaField.kind !== 'text') {
+                return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not text.` };
+            }
+            resolved.push({ ...field, fieldLabel: schemaField.label });
+            continue;
+        }
+        if (field.kind === 'choice') {
+            if (schemaField.kind !== 'choice') {
+                return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not choice.` };
+            }
+            resolved.push({
+                ...field,
+                fieldLabel: schemaField.label,
+                ...(field.choiceType === undefined && schemaField.choiceType ? { choiceType: schemaField.choiceType } : {}),
+            });
+            continue;
+        }
+        if (field.kind === 'toggle') {
+            if (schemaField.kind !== 'toggle') {
+                return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not toggle.` };
+            }
+            resolved.push({
+                ...field,
+                label: schemaField.label,
+                ...(field.controlType === undefined && schemaField.controlType ? { controlType: schemaField.controlType } : {}),
+            });
+            continue;
+        }
+        return {
+            ok: false,
+            error: `File field id ${field.fieldId} still needs fieldLabel. geometra_form_schema does not reliably expose proxy file inputs yet.`,
+        };
+    }
+    return { ok: true, fields: resolved };
+}
 function canFallbackToSequentialFill(error) {
     const message = error instanceof Error ? error.message : String(error);
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed?.error === 'listboxPick' ||
+            parsed?.error === 'setFieldText' ||
+            parsed?.error === 'setFieldChoice' ||
+            parsed?.error === 'setChecked' ||
+            parsed?.error === 'attachFiles') {
+            return true;
+        }
+    }
+    catch {
+        /* ignore non-JSON errors */
+    }
     return (message.includes('Unsupported client message type "fillFields"') ||
         message.includes('Client message type "fillFields" is not supported') ||
         message.startsWith('setFieldText:') ||
@@ -2270,9 +2476,12 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             };
         }
         case 'fill_fields': {
+            const resolvedFields = resolveFillFieldInputs(session, action.fields);
+            if (!resolvedFields.ok)
+                throw new Error(resolvedFields.error);
             const steps = [];
-            for (let index = 0; index < action.fields.length; index++) {
-                const field = action.fields[index];
+            for (let index = 0; index < resolvedFields.fields.length; index++) {
+                const field = resolvedFields.fields[index];
                 const result = await executeFillField(session, field, detail);
                 steps.push(detail === 'verbose'
                     ? { index, kind: field.kind, ok: true, summary: result.summary }
@@ -2281,7 +2490,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             return {
                 summary: steps.map(step => String(step.summary ?? '')).filter(Boolean).join('\n'),
                 compact: {
-                    fieldCount: action.fields.length,
+                    fieldCount: resolvedFields.fields.length,
                     ...(includeSteps ? { steps } : {}),
                 },
             };

package/dist/session.d.ts

@@ -271,6 +271,23 @@ export interface FormSchemaModel {
     invalidCount: number;
     fields: FormSchemaField[];
 }
+export interface FormRequiredFieldSnapshot extends FormSchemaField {
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    visibility: NodeVisibilityModel;
+    scrollHint: NodeScrollHintModel;
+}
+export interface FormRequiredSnapshotModel {
+    formId: string;
+    name?: string;
+    requiredCount: number;
+    invalidCount: number;
+    fields: FormRequiredFieldSnapshot[];
+}
 export interface FormSchemaBuildOptions {
     formId?: string;
     maxFields?: number;
@@ -510,6 +527,12 @@ export declare function buildPageModel(root: A11yNode, options?: {
     maxSectionsPerKind?: number;
 }): PageModel;
 export declare function buildFormSchemas(root: A11yNode, options?: FormSchemaBuildOptions): FormSchemaModel[];
+/**
+ * Required-field snapshot for automation: every required field in a form, including
+ * offscreen entries, annotated with visibility and scroll hints so agents do not
+ * mistake long-form fields for missing controls.
+ */
+export declare function buildFormRequiredSnapshot(root: A11yNode, options?: Pick<FormSchemaBuildOptions, 'formId' | 'maxFields' | 'includeOptions' | 'includeContext'>): FormRequiredSnapshotModel[];
 /**
  * Expand a page-model section by stable ID into richer, on-demand details.
  */

package/dist/session.js

@@ -755,6 +755,12 @@ export function nodeIdForPath(path) {
 function formFieldIdForPath(path) {
     return `ff:${encodePath(path)}`;
 }
+function parseFormFieldId(id) {
+    const [prefix, encoded] = id.split(':', 2);
+    if (prefix !== 'ff' || !encoded)
+        return null;
+    return decodePath(encoded);
+}
 function sectionPrefix(kind) {
     if (kind === 'landmark')
         return 'lm';
@@ -1596,6 +1602,45 @@ export function buildFormSchemas(root, options) {
         .filter(form => !options?.formId || sectionIdForPath('form', form.path) === options.formId)
         .map(form => buildFormSchemaForNode(root, form, options));
 }
+/**
+ * Required-field snapshot for automation: every required field in a form, including
+ * offscreen entries, annotated with visibility and scroll hints so agents do not
+ * mistake long-form fields for missing controls.
+ */
+export function buildFormRequiredSnapshot(root, options) {
+    const schemas = buildFormSchemas(root, {
+        formId: options?.formId,
+        maxFields: options?.maxFields,
+        onlyRequiredFields: true,
+        includeOptions: options?.includeOptions,
+        includeContext: options?.includeContext,
+    });
+    return schemas.map(schema => {
+        const parsedForm = parseSectionId(schema.formId);
+        const formNode = parsedForm ? findNodeByPath(root, parsedForm.path) : null;
+        const fields = schema.fields
+            .map(field => {
+            const fieldPath = parseFormFieldId(field.id);
+            const target = fieldPath ? findNodeByPath(root, fieldPath) ?? formNode : formNode;
+            if (!target)
+                return null;
+            return {
+                ...field,
+                bounds: cloneBounds(target.bounds),
+                visibility: buildVisibility(target.bounds, root.bounds),
+                scrollHint: buildScrollHint(target.bounds, root.bounds),
+            };
+        })
+            .filter((field) => field !== null);
+        return {
+            formId: schema.formId,
+            ...(schema.name ? { name: schema.name } : {}),
+            requiredCount: schema.requiredCount,
+            invalidCount: schema.invalidCount,
+            fields,
+        };
+    });
+}
 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.20",
+  "version": "1.19.22",
   "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.20",
+    "@geometra/proxy": "^1.19.22",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.18.0",
     "zod": "^3.23.0"