@geometra/mcp 1.19.9 → 1.19.10

package/README.md

@@ -19,13 +19,16 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 | Tool | Description |
 |---|---|
 | `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; `url: "https://…"` is auto-coerced onto the proxy path |
-| `geometra_query` | Find elements by stable id, role, name, or text content |
+| `geometra_query` | Find elements by stable id, role, name, text content, 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_fill_fields` | Fill labeled text/choice/toggle/file fields in one MCP call |
+| `geometra_run_actions` | Execute a batch of high-level actions in one MCP round trip and get one consolidated result |
 | `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
 | `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand |
 | `geometra_click` | Click an element by coordinates |
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
-| `geometra_upload_files` | Attach files: auto / hidden input / native chooser / synthetic drop (`@geometra/proxy` only) |
+| `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_set_checked` | Set a checkbox or radio by label instead of coordinate clicks (`@geometra/proxy` only) |
@@ -173,4 +176,43 @@ Agent:  geometra_query({ role: "button", name: "Save" })
 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.
 
+## Long Forms
+
+For long application flows, prefer one of these patterns:
+
+1. `geometra_page_model`
+2. `geometra_expand_section`
+3. `geometra_fill_fields` for obvious field entry
+4. `geometra_run_actions` when you need mixed navigation + waits + field entry
+
+Typical batch:
+
+```json
+{
+  "actions": [
+    { "type": "click", "x": 412, "y": 228 },
+    { "type": "type", "text": "Taylor Applicant" },
+    { "type": "upload_files", "paths": ["/Users/you/resume.pdf"], "fieldLabel": "Resume" },
+    { "type": "wait_for", "text": "Parsing your resume", "present": false, "timeoutMs": 10000 }
+  ]
+}
+```
+
+Single action tools now default to terse summaries. Pass `detail: "verbose"` when you need a fuller current-UI fallback for debugging.
+
+Typical field fill:
+
+```json
+{
+  "fields": [
+    { "kind": "text", "fieldLabel": "Full name", "value": "Taylor Applicant" },
+    { "kind": "text", "fieldLabel": "Email", "value": "taylor@example.com" },
+    { "kind": "choice", "fieldLabel": "Country", "value": "Germany" },
+    { "kind": "choice", "fieldLabel": "Will you require sponsorship?", "value": "No" },
+    { "kind": "file", "fieldLabel": "Resume", "paths": ["/Users/you/resume.pdf"] }
+  ],
+  "failOnInvalid": true
+}
+```
+
 With a **native** Geometra server, layout comes from Textura/Yoga. With **`@geometra/proxy`**, layout comes from the browser’s computed DOM geometry; the MCP layer is the same.

package/dist/__tests__/server-filters.test.js

@@ -6,6 +6,7 @@ function node(role, bounds, options) {
         ...(options?.name ? { name: options.name } : {}),
         ...(options?.value ? { value: options.value } : {}),
         ...(options?.state ? { state: options.state } : {}),
+        ...(options?.validation ? { validation: options.validation } : {}),
         bounds,
         path: options?.path ?? [],
         children: options?.children ?? [],
@@ -22,8 +23,15 @@ describe('findNodes', () => {
                     value: 'Austin, Texas, United States',
                     focusable: true,
                 }),
-                node('checkbox', { x: 20, y: 72, width: 24, height: 24 }, {
+                node('textbox', { x: 20, y: 120, width: 260, height: 36 }, {
                     path: [1],
+                    name: 'Email',
+                    focusable: true,
+                    state: { invalid: true, required: true, busy: true },
+                    validation: { error: 'Please enter a valid email address.' },
+                }),
+                node('checkbox', { x: 20, y: 72, width: 24, height: 24 }, {
+                    path: [2],
                     name: 'Notion Website',
                     state: { checked: true },
                     focusable: true,
@@ -36,6 +44,12 @@ describe('findNodes', () => {
         expect(findNodes(tree, { text: 'United States' })).toEqual([
             expect.objectContaining({ role: 'combobox', value: 'Austin, Texas, United States' }),
         ]);
+        expect(findNodes(tree, { invalid: true, required: true, busy: true })).toEqual([
+            expect.objectContaining({ role: 'textbox', name: 'Email' }),
+        ]);
+        expect(findNodes(tree, { text: 'valid email address' })).toEqual([
+            expect.objectContaining({ role: 'textbox', name: 'Email' }),
+        ]);
         expect(findNodes(tree, { role: 'checkbox', checked: true })).toEqual([
             expect.objectContaining({ name: 'Notion Website' }),
         ]);

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

@@ -1,11 +1,12 @@
 import { describe, expect, it } from 'vitest';
-import { buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+import { buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
 function node(role, name, bounds, options) {
     return {
         role,
         ...(name ? { name } : {}),
         ...(options?.value ? { value: options.value } : {}),
         ...(options?.state ? { state: options.state } : {}),
+        ...(options?.validation ? { validation: options.validation } : {}),
         ...(options?.meta ? { meta: options.meta } : {}),
         bounds,
         path: options?.path ?? [],
@@ -87,10 +88,13 @@ describe('buildPageModel', () => {
                                 node('textbox', 'Full name*', { x: 60, y: 160, width: 300, height: 36 }, {
                                     path: [0, 0, 1],
                                     value: 'Taylor Applicant',
+                                    state: { required: true },
                                 }),
                                 node('textbox', 'Email:', { x: 60, y: 208, width: 300, height: 36 }, {
                                     path: [0, 0, 2],
                                     value: 'taylor@example.com',
+                                    state: { invalid: true, required: true },
+                                    validation: { error: 'Please enter a valid email address.' },
                                 }),
                                 node('button', 'Submit application', { x: 60, y: 264, width: 180, height: 40 }, {
                                     path: [0, 0, 3],
@@ -116,6 +120,9 @@ describe('buildPageModel', () => {
         });
         expect(detail?.fields.map(field => field.name)).toEqual(['Full name', 'Email']);
         expect(detail?.fields.map(field => field.value)).toEqual(['Taylor Applicant', 'taylor@example.com']);
+        expect(detail?.fields[0]?.state).toEqual({ required: true });
+        expect(detail?.fields[1]?.state).toEqual({ invalid: true, required: true });
+        expect(detail?.fields[1]?.validation).toEqual({ error: 'Please enter a valid email address.' });
         expect(detail?.actions.map(action => action.id)).toEqual(['n:0.0.3']);
         expect(detail?.fields[0]).not.toHaveProperty('bounds');
     });
@@ -324,3 +331,53 @@ describe('buildUiDelta', () => {
         expect(summarizeUiDelta(delta)).toContain('value "Austin" -> "Austin, Texas, United States"');
     });
 });
+describe('buildA11yTree', () => {
+    it('maps required, invalid, busy, and validation text from raw semantic nodes', () => {
+        const tree = {
+            kind: 'box',
+            props: {},
+            semantic: {},
+            children: [
+                {
+                    kind: 'box',
+                    props: { value: '' },
+                    semantic: {
+                        role: 'textbox',
+                        ariaLabel: 'Email',
+                        ariaRequired: true,
+                        ariaInvalid: true,
+                        ariaBusy: true,
+                        validationDescription: 'We will contact you about this role.',
+                        validationError: 'Please enter a valid email address.',
+                    },
+                    handlers: { onClick: true, onKeyDown: true },
+                },
+            ],
+        };
+        const layout = {
+            x: 0,
+            y: 0,
+            width: 800,
+            height: 600,
+            children: [
+                {
+                    x: 24,
+                    y: 40,
+                    width: 320,
+                    height: 36,
+                    children: [],
+                },
+            ],
+        };
+        const a11y = buildA11yTree(tree, layout);
+        expect(a11y.children[0]).toMatchObject({
+            role: 'textbox',
+            name: 'Email',
+            state: { required: true, invalid: true, busy: true },
+            validation: {
+                description: 'We will contact you about this role.',
+                error: 'Please enter a valid email address.',
+            },
+        });
+    });
+});

package/dist/server.d.ts

@@ -12,6 +12,9 @@ interface NodeFilter {
     focused?: boolean;
     selected?: boolean;
     expanded?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    busy?: boolean;
 }
 export declare function createServer(): McpServer;
 export declare function findNodes(node: A11yNode, filter: NodeFilter): A11yNode[];

package/dist/server.js

@@ -1,15 +1,151 @@
 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, 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, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
         .optional()
         .describe('Match checked state (`true`, `false`, or `mixed`)');
 }
+function detailInput() {
+    return z
+        .enum(['minimal', 'verbose'])
+        .optional()
+        .default('minimal')
+        .describe('`minimal` (default) returns terse action summaries. Use `verbose` for a fuller current-UI fallback.');
+}
+function nodeFilterShape() {
+    return {
+        id: z.string().optional().describe('Stable node id from geometra_snapshot or geometra_expand_section'),
+        role: z.string().optional().describe('ARIA role to match'),
+        name: z.string().optional().describe('Accessible name to match (exact or substring)'),
+        text: z.string().optional().describe('Text content to search for (substring match)'),
+        value: z.string().optional().describe('Displayed / current field value to match (substring match)'),
+        checked: checkedStateInput(),
+        disabled: z.boolean().optional().describe('Match disabled state'),
+        focused: z.boolean().optional().describe('Match focused state'),
+        selected: z.boolean().optional().describe('Match selected state'),
+        expanded: z.boolean().optional().describe('Match expanded state'),
+        invalid: z.boolean().optional().describe('Match invalid / failed-validation state'),
+        required: z.boolean().optional().describe('Match required-field state'),
+        busy: z.boolean().optional().describe('Match busy / in-progress state'),
+    };
+}
+const timeoutMsInput = z.number().int().min(50).max(60_000).optional();
+const fillFieldSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('text'),
+        fieldLabel: z.string().describe('Visible field label / accessible name'),
+        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('choice'),
+        fieldLabel: z.string().describe('Visible field label / accessible name'),
+        value: z.string().describe('Desired option value / answer label'),
+        query: z.string().optional().describe('Optional search text for searchable comboboxes'),
+        exact: z.boolean().optional().describe('Exact label match'),
+        timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
+    }),
+    z.object({
+        kind: z.literal('toggle'),
+        label: z.string().describe('Visible checkbox/radio label to set'),
+        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('file'),
+        fieldLabel: z.string().describe('Visible file-field label / accessible name'),
+        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 batchActionSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('click'),
+        x: z.number(),
+        y: z.number(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('type'),
+        text: z.string(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('key'),
+        key: z.string(),
+        shift: z.boolean().optional(),
+        ctrl: z.boolean().optional(),
+        meta: z.boolean().optional(),
+        alt: z.boolean().optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('upload_files'),
+        paths: z.array(z.string()).min(1),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        fieldLabel: z.string().optional(),
+        exact: z.boolean().optional(),
+        strategy: z.enum(['auto', 'chooser', 'hidden', 'drop']).optional(),
+        dropX: z.number().optional(),
+        dropY: z.number().optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('pick_listbox_option'),
+        label: z.string(),
+        exact: z.boolean().optional(),
+        openX: z.number().optional(),
+        openY: z.number().optional(),
+        fieldLabel: z.string().optional(),
+        query: z.string().optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('select_option'),
+        x: z.number(),
+        y: z.number(),
+        value: z.string().optional(),
+        label: z.string().optional(),
+        index: z.number().int().min(0).optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('set_checked'),
+        label: z.string(),
+        checked: z.boolean().optional(),
+        exact: z.boolean().optional(),
+        controlType: z.enum(['checkbox', 'radio']).optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('wheel'),
+        deltaY: z.number(),
+        deltaX: z.number().optional(),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('wait_for'),
+        ...nodeFilterShape(),
+        present: z.boolean().optional(),
+        timeoutMs: timeoutMsInput,
+    }),
+    z.object({
+        type: z.literal('fill_fields'),
+        fields: z.array(fillFieldSchema).min(1).max(80),
+    }),
+]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.9' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.10' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -77,23 +213,26 @@ 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.
 
-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.`, {
-        id: z.string().optional().describe('Stable node id from geometra_snapshot or geometra_expand_section'),
-        role: z.string().optional().describe('ARIA role to match (e.g. "button", "textbox", "text", "heading", "listitem")'),
-        name: z.string().optional().describe('Accessible name to match (exact or substring)'),
-        text: z.string().optional().describe('Text content to search for (substring match)'),
-        value: z.string().optional().describe('Displayed / current field value to match (substring match)'),
-        checked: checkedStateInput(),
-        disabled: z.boolean().optional().describe('Match disabled state'),
-        focused: z.boolean().optional().describe('Match focused state'),
-        selected: z.boolean().optional().describe('Match selected state'),
-        expanded: z.boolean().optional().describe('Match expanded state'),
-    }, async ({ id, role, name, text, value, checked, disabled, focused, selected, expanded }) => {
+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.`, nodeFilterShape(), async ({ id, role, name, text, 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.');
         const a11y = buildA11yTree(session.tree, session.layout);
-        const filter = { id, role, name, text, value, checked, disabled, focused, selected, expanded };
+        const filter = {
+            id,
+            role,
+            name,
+            text,
+            value,
+            checked,
+            disabled,
+            focused,
+            selected,
+            expanded,
+            invalid,
+            required,
+            busy,
+        };
         if (!hasNodeFilter(filter))
             return err('Provide at least one query filter (id, role, name, text, value, or state)');
         const matches = findNodes(a11y, filter);
@@ -106,16 +245,7 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
     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.
 
 The filter matches the same fields as geometra_query. Set \`present: false\` to wait for something to disappear (for example an alert or a "Parsing…" status).`, {
-        id: z.string().optional().describe('Stable node id from geometra_snapshot or geometra_expand_section'),
-        role: z.string().optional().describe('ARIA role to match'),
-        name: z.string().optional().describe('Accessible name to match (exact or substring)'),
-        text: z.string().optional().describe('Text content to search for (substring match)'),
-        value: z.string().optional().describe('Displayed / current field value to match (substring match)'),
-        checked: checkedStateInput(),
-        disabled: z.boolean().optional().describe('Match disabled state'),
-        focused: z.boolean().optional().describe('Match focused state'),
-        selected: z.boolean().optional().describe('Match selected state'),
-        expanded: z.boolean().optional().describe('Match expanded state'),
+        ...nodeFilterShape(),
         present: z.boolean().optional().default(true).describe('Wait for a matching node to exist (default true) or disappear'),
         timeoutMs: z
             .number()
@@ -125,11 +255,25 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             .optional()
             .default(10_000)
             .describe('Maximum time to wait before returning an error (default 10000ms)'),
-    }, async ({ id, role, name, text, value, checked, disabled, focused, selected, expanded, present, timeoutMs }) => {
+    }, async ({ id, role, name, text, 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.');
-        const filter = { id, role, name, text, value, checked, disabled, focused, selected, expanded };
+        const filter = {
+            id,
+            role,
+            name,
+            text,
+            value,
+            checked,
+            disabled,
+            focused,
+            selected,
+            expanded,
+            invalid,
+            required,
+            busy,
+        };
         if (!hasNodeFilter(filter))
             return err('Provide at least one wait filter (id, role, name, text, value, or state)');
         const matchesCondition = () => {
@@ -155,6 +299,90 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
         const result = matches.slice(0, 8).map(node => formatNode(node, after.bounds));
         return ok(JSON.stringify(result, null, 2));
     });
+    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'),
+        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'),
+        detail: detailInput(),
+    }, async ({ fields, stopOnError, failOnInvalid, detail }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const steps = [];
+        let stoppedAt;
+        for (let index = 0; index < fields.length; index++) {
+            const field = fields[index];
+            try {
+                const summary = await executeFillField(session, field, detail);
+                steps.push({ index, kind: field.kind, ok: true, summary });
+            }
+            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 payload = {
+            completed: stoppedAt === undefined && steps.length === fields.length,
+            fieldCount: fields.length,
+            steps,
+            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(signals ? { final: sessionSignalsPayload(signals) } : {}),
+        };
+        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\`.`, {
+        actions: z.array(batchActionSchema).min(1).max(80).describe('Ordered high-level action steps to run sequentially'),
+        stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing step (default true)'),
+        detail: detailInput(),
+    }, async ({ actions, stopOnError, detail }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const steps = [];
+        let stoppedAt;
+        for (let index = 0; index < actions.length; index++) {
+            const action = actions[index];
+            try {
+                const summary = await executeBatchAction(session, action, detail);
+                steps.push({ index, type: action.type, ok: true, summary });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                steps.push({ index, type: action.type, ok: false, error: message });
+                if (stopOnError) {
+                    stoppedAt = index;
+                    break;
+                }
+            }
+        }
+        const after = sessionA11y(session);
+        const payload = {
+            completed: stoppedAt === undefined && steps.length === actions.length,
+            stepCount: actions.length,
+            steps,
+            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after)) } : {}),
+        };
+        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+    });
     // ── page model ────────────────────────────────────────────────
     server.tool('geometra_page_model', `Get a higher-level webpage summary instead of a raw node dump. Returns stable section ids, page archetypes, summary counts, top-level landmarks/forms/dialogs/lists, and a few primary actions.
 
@@ -225,13 +453,14 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout (use a longer value for slow submits or route transitions)'),
-    }, async ({ x, y, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ x, y, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         const wait = await sendClick(session, x, y, timeoutMs);
-        const summary = postActionSummary(session, before, wait);
+        const summary = postActionSummary(session, before, wait, detail);
         return ok(`Clicked at (${x}, ${y}).\n${summary}`);
     });
     // ── type ─────────────────────────────────────────────────────
@@ -246,13 +475,14 @@ Each character is sent as a key event through the geometry protocol. Returns a c
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout'),
-    }, async ({ text, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ text, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         const wait = await sendType(session, text, timeoutMs);
-        const summary = postActionSummary(session, before, wait);
+        const summary = postActionSummary(session, before, wait, detail);
         return ok(`Typed "${text}".\n${summary}`);
     });
     // ── key ──────────────────────────────────────────────────────
@@ -269,22 +499,25 @@ Each character is sent as a key event through the geometry protocol. Returns a c
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout'),
-    }, async ({ key, shift, ctrl, meta, alt, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ key, shift, ctrl, meta, alt, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         const wait = await sendKey(session, key, { shift, ctrl, meta, alt }, timeoutMs);
-        const summary = postActionSummary(session, before, wait);
+        const summary = postActionSummary(session, before, wait, detail);
         return ok(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`);
     });
     // ── upload files (proxy) ───────────────────────────────────────
     server.tool('geometra_upload_files', `Attach local files to a file input. Requires \`@geometra/proxy\` (paths exist on the proxy host).
 
-Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`input[type=file]\`, else first visible file input. **hidden** targets hidden inputs directly. **drop** needs dropX,dropY for drag-target zones. **chooser** requires x,y.`, {
+Strategies: **auto** (default) tries chooser click if x,y given, else a labeled file input when \`fieldLabel\` is provided, else hidden \`input[type=file]\`, else first visible file input. **hidden** targets hidden inputs directly. **drop** needs dropX,dropY for drag-target zones. **chooser** requires x,y.`, {
         paths: z.array(z.string()).min(1).describe('Absolute paths on the proxy machine, e.g. /Users/you/resume.pdf'),
         x: z.number().optional().describe('Click X to trigger native file chooser'),
         y: z.number().optional().describe('Click Y to trigger native file chooser'),
+        fieldLabel: z.string().optional().describe('Prefer a specific labeled file field (for example "Resume" or "Cover letter")'),
+        exact: z.boolean().optional().describe('Exact match when using fieldLabel'),
         strategy: z
             .enum(['auto', 'chooser', 'hidden', 'drop'])
             .optional()
@@ -298,7 +531,8 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout (resume parsing / SPA upload flows often need longer than a normal click)'),
-    }, async ({ paths, x, y, strategy, dropX, dropY, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -306,10 +540,12 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
         try {
             const wait = await sendFileUpload(session, paths, {
                 click: x !== undefined && y !== undefined ? { x, y } : undefined,
+                fieldLabel,
+                exact,
                 strategy,
                 drop: dropX !== undefined && dropY !== undefined ? { x: dropX, y: dropY } : undefined,
             }, timeoutMs ?? 8_000);
-            const summary = postActionSummary(session, before, wait);
+            const summary = postActionSummary(session, before, wait, detail);
             return ok(`Uploaded ${paths.length} file(s).\n${summary}`);
         }
         catch (e) {
@@ -332,7 +568,8 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout for slow dropdowns / remote search results'),
-    }, async ({ label, exact, openX, openY, fieldLabel, query, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ label, exact, openX, openY, fieldLabel, query, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -344,7 +581,7 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
                 fieldLabel,
                 query,
             }, timeoutMs);
-            const summary = postActionSummary(session, before, wait);
+            const summary = postActionSummary(session, before, wait, detail);
             const fieldSummary = fieldLabel ? summarizeFieldLabelState(session, fieldLabel) : undefined;
             return ok([
                 `Picked listbox option "${label}".`,
@@ -372,7 +609,8 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout'),
-    }, async ({ x, y, value, label, index, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ x, y, value, label, index, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -382,7 +620,7 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
         const before = sessionA11y(session);
         try {
             const wait = await sendSelectOption(session, x, y, { value, label, index }, timeoutMs);
-            const summary = postActionSummary(session, before, wait);
+            const summary = postActionSummary(session, before, wait, detail);
             return ok(`Selected option.\n${summary}`);
         }
         catch (e) {
@@ -403,14 +641,15 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout'),
-    }, async ({ label, checked, exact, controlType, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ label, checked, exact, controlType, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
             const wait = await sendSetChecked(session, label, { checked, exact, controlType }, timeoutMs);
-            const summary = postActionSummary(session, before, wait);
+            const summary = postActionSummary(session, before, wait, detail);
             return ok(`Set ${controlType ?? 'checkbox/radio'} "${label}" to ${String(checked ?? true)}.\n${summary}`);
         }
         catch (e) {
@@ -430,14 +669,15 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
             .max(60_000)
             .optional()
             .describe('Optional action wait timeout'),
-    }, async ({ deltaY, deltaX, x, y, timeoutMs }) => {
+        detail: detailInput(),
+    }, async ({ deltaY, deltaX, x, y, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
             const wait = await sendWheel(session, deltaY, { deltaX, x, y }, timeoutMs);
-            const summary = postActionSummary(session, before, wait);
+            const summary = postActionSummary(session, before, wait, detail);
             return ok(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`);
         }
         catch (e) {
@@ -514,24 +754,37 @@ function sessionOverviewFromA11y(a11y) {
     const keyNodes = nodes.length > 0 ? `Key nodes:\n${summarizeCompactIndex(nodes, 18)}` : '';
     return [pageSummary, contextSummary, keyNodes].filter(Boolean).join('\n');
 }
-function postActionSummary(session, before, wait) {
+function postActionSummary(session, before, wait, detail = 'minimal') {
     const after = sessionA11y(session);
     const notes = [];
     if (wait?.status === 'acknowledged') {
-        notes.push('The peer acknowledged the action quickly; waiting logic did not need to rely on a full frame/patch round-trip.');
+        notes.push(detail === 'verbose'
+            ? 'The peer acknowledged the action quickly; waiting logic did not need to rely on a full frame/patch round-trip.'
+            : 'Peer acknowledged the action quickly.');
     }
     if (wait?.status === 'timed_out') {
-        notes.push(`No frame or patch arrived within ${wait.timeoutMs}ms after the action. The action may still have succeeded if it did not change geometry or semantics.`);
+        notes.push(detail === 'verbose'
+            ? `No frame or patch arrived within ${wait.timeoutMs}ms after the action. The action may still have succeeded if it did not change geometry or semantics.`
+            : `No update arrived within ${wait.timeoutMs}ms; the action may still have succeeded.`);
     }
     if (!after)
         return [...notes, 'No UI update received'].filter(Boolean).join('\n');
+    const signals = collectSessionSignals(after);
+    const validationSummary = summarizeValidationSignals(signals);
     if (before) {
         const delta = buildUiDelta(before, after);
         if (hasUiDelta(delta)) {
-            return [...notes, `Changes:\n${summarizeUiDelta(delta)}`].filter(Boolean).join('\n');
+            return [
+                ...notes,
+                `Changes:\n${summarizeUiDelta(delta, detail === 'verbose' ? 14 : 8)}`,
+                ...(detail === 'minimal' ? validationSummary : []),
+            ].filter(Boolean).join('\n');
         }
     }
-    return [...notes, `Current UI:\n${sessionOverviewFromA11y(after)}`].filter(Boolean).join('\n');
+    if (detail === 'verbose') {
+        return [...notes, `Current UI:\n${sessionOverviewFromA11y(after)}`].filter(Boolean).join('\n');
+    }
+    return [...notes, summarizeSessionSignals(signals), ...validationSummary].filter(Boolean).join('\n');
 }
 function summarizeCompactContext(context) {
     const parts = [];
@@ -546,6 +799,283 @@ function summarizeCompactContext(context) {
     }
     return parts.length > 0 ? `Context: ${parts.join(' | ')}` : '';
 }
+function collectSessionSignals(root) {
+    const signals = {
+        ...(root.meta?.pageUrl ? { pageUrl: root.meta.pageUrl } : {}),
+        ...(typeof root.meta?.scrollX === 'number' ? { scrollX: root.meta.scrollX } : {}),
+        ...(typeof root.meta?.scrollY === 'number' ? { scrollY: root.meta.scrollY } : {}),
+        dialogCount: 0,
+        busyCount: 0,
+        alerts: [],
+        invalidFields: [],
+    };
+    const seenAlerts = new Set();
+    const seenInvalidIds = new Set();
+    function walk(node) {
+        if (!signals.focus && node.state?.focused) {
+            signals.focus = {
+                id: nodeIdForPath(node.path),
+                role: node.role,
+                ...(node.name ? { name: node.name } : {}),
+                ...(node.value ? { value: node.value } : {}),
+            };
+        }
+        if (node.role === 'dialog' || node.role === 'alertdialog')
+            signals.dialogCount++;
+        if (node.state?.busy)
+            signals.busyCount++;
+        if (node.role === 'alert' || node.role === 'alertdialog') {
+            const text = truncateInlineText(node.name ?? node.validation?.error, 120);
+            if (text && !seenAlerts.has(text)) {
+                seenAlerts.add(text);
+                signals.alerts.push(text);
+            }
+        }
+        if ((node.role === 'textbox' || node.role === 'combobox' || node.role === 'checkbox' || node.role === 'radio') && node.state?.invalid) {
+            const id = nodeIdForPath(node.path);
+            if (!seenInvalidIds.has(id)) {
+                seenInvalidIds.add(id);
+                signals.invalidFields.push({
+                    id,
+                    role: node.role,
+                    ...(node.name ? { name: truncateInlineText(node.name, 80) } : {}),
+                    ...(node.validation?.error ? { error: truncateInlineText(node.validation.error, 120) } : {}),
+                });
+            }
+        }
+        for (const child of node.children)
+            walk(child);
+    }
+    walk(root);
+    return signals;
+}
+function summarizeSessionSignals(signals) {
+    const contextParts = [];
+    if (signals.pageUrl)
+        contextParts.push(`url=${signals.pageUrl}`);
+    if (signals.scrollX !== undefined || signals.scrollY !== undefined) {
+        contextParts.push(`scroll=(${signals.scrollX ?? 0},${signals.scrollY ?? 0})`);
+    }
+    if (signals.focus) {
+        const focusName = signals.focus.name ? ` "${truncateInlineText(signals.focus.name, 48)}"` : '';
+        const focusValue = signals.focus.value ? ` value=${JSON.stringify(truncateInlineText(signals.focus.value, 40))}` : '';
+        contextParts.push(`focus=${signals.focus.role}${focusName}${focusValue}`);
+    }
+    const statusParts = [
+        signals.dialogCount > 0 ? `dialogs=${signals.dialogCount}` : undefined,
+        signals.alerts.length > 0 ? `alerts=${signals.alerts.length}` : undefined,
+        signals.invalidFields.length > 0 ? `invalid=${signals.invalidFields.length}` : undefined,
+        signals.busyCount > 0 ? `busy=${signals.busyCount}` : undefined,
+    ].filter(Boolean);
+    return [
+        contextParts.length > 0 ? `Context: ${contextParts.join(' | ')}` : undefined,
+        statusParts.length > 0 ? `Status: ${statusParts.join(' | ')}` : 'Status: no semantic changes detected.',
+    ].filter(Boolean).join('\n');
+}
+function summarizeValidationSignals(signals) {
+    const lines = [];
+    if (signals.alerts.length > 0) {
+        lines.push(`Alerts: ${signals.alerts.slice(0, 2).map(text => JSON.stringify(text)).join(' | ')}`);
+    }
+    if (signals.invalidFields.length > 0) {
+        const invalidSummary = signals.invalidFields
+            .slice(0, 4)
+            .map(field => {
+            const label = field.name ? `"${field.name}"` : field.id;
+            return field.error ? `${label}: ${JSON.stringify(field.error)}` : label;
+        })
+            .join(' | ');
+        lines.push(`Validation: ${invalidSummary}`);
+    }
+    return lines;
+}
+function truncateInlineText(text, max) {
+    if (!text)
+        return undefined;
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return undefined;
+    return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+function sessionSignalsPayload(signals) {
+    return {
+        ...(signals.pageUrl ? { pageUrl: signals.pageUrl } : {}),
+        ...(signals.scrollX !== undefined || signals.scrollY !== undefined
+            ? { scroll: { x: signals.scrollX ?? 0, y: signals.scrollY ?? 0 } }
+            : {}),
+        ...(signals.focus ? { focus: signals.focus } : {}),
+        dialogCount: signals.dialogCount,
+        busyCount: signals.busyCount,
+        alerts: signals.alerts,
+        invalidFields: signals.invalidFields,
+    };
+}
+async function executeBatchAction(session, action, detail) {
+    switch (action.type) {
+        case 'click': {
+            const before = sessionA11y(session);
+            const wait = await sendClick(session, action.x, action.y, action.timeoutMs);
+            return `Clicked at (${action.x}, ${action.y}).\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'type': {
+            const before = sessionA11y(session);
+            const wait = await sendType(session, action.text, action.timeoutMs);
+            return `Typed "${action.text}".\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'key': {
+            const before = sessionA11y(session);
+            const wait = await sendKey(session, action.key, { shift: action.shift, ctrl: action.ctrl, meta: action.meta, alt: action.alt }, action.timeoutMs);
+            return `Pressed ${formatKeyCombo(action.key, action)}.\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'upload_files': {
+            const before = sessionA11y(session);
+            const wait = await sendFileUpload(session, action.paths, {
+                click: action.x !== undefined && action.y !== undefined ? { x: action.x, y: action.y } : undefined,
+                fieldLabel: action.fieldLabel,
+                exact: action.exact,
+                strategy: action.strategy,
+                drop: action.dropX !== undefined && action.dropY !== undefined ? { x: action.dropX, y: action.dropY } : undefined,
+            }, action.timeoutMs ?? 8_000);
+            return `Uploaded ${action.paths.length} file(s).\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'pick_listbox_option': {
+            const before = sessionA11y(session);
+            const wait = await sendListboxPick(session, action.label, {
+                exact: action.exact,
+                open: action.openX !== undefined && action.openY !== undefined ? { x: action.openX, y: action.openY } : undefined,
+                fieldLabel: action.fieldLabel,
+                query: action.query,
+            }, action.timeoutMs);
+            const summary = postActionSummary(session, before, wait, detail);
+            const fieldSummary = action.fieldLabel ? summarizeFieldLabelState(session, action.fieldLabel) : undefined;
+            return [`Picked listbox option "${action.label}".`, fieldSummary, summary].filter(Boolean).join('\n');
+        }
+        case 'select_option': {
+            if (action.value === undefined && action.label === undefined && action.index === undefined) {
+                throw new Error('select_option step requires at least one of value, label, or index');
+            }
+            const before = sessionA11y(session);
+            const wait = await sendSelectOption(session, action.x, action.y, {
+                value: action.value,
+                label: action.label,
+                index: action.index,
+            }, action.timeoutMs);
+            return `Selected option.\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'set_checked': {
+            const before = sessionA11y(session);
+            const wait = await sendSetChecked(session, action.label, {
+                checked: action.checked,
+                exact: action.exact,
+                controlType: action.controlType,
+            }, action.timeoutMs);
+            return `Set ${action.controlType ?? 'checkbox/radio'} "${action.label}" to ${String(action.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'wheel': {
+            const before = sessionA11y(session);
+            const wait = await sendWheel(session, action.deltaY, {
+                deltaX: action.deltaX,
+                x: action.x,
+                y: action.y,
+            }, action.timeoutMs);
+            return `Wheel delta (${action.deltaX ?? 0}, ${action.deltaY}).\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'wait_for': {
+            if (!session.tree || !session.layout)
+                throw new Error('Not connected. Call geometra_connect first.');
+            const filter = {
+                id: action.id,
+                role: action.role,
+                name: action.name,
+                text: action.text,
+                value: action.value,
+                checked: action.checked,
+                disabled: action.disabled,
+                focused: action.focused,
+                selected: action.selected,
+                expanded: action.expanded,
+                invalid: action.invalid,
+                required: action.required,
+                busy: action.busy,
+            };
+            if (!hasNodeFilter(filter)) {
+                throw new Error('wait_for step requires at least one filter');
+            }
+            const present = action.present ?? true;
+            const timeoutMs = action.timeoutMs ?? 10_000;
+            const startedAt = Date.now();
+            const matched = await waitForUiCondition(session, () => {
+                if (!session.tree || !session.layout)
+                    return false;
+                const a11y = buildA11yTree(session.tree, session.layout);
+                const matches = findNodes(a11y, filter);
+                return present ? matches.length > 0 : matches.length === 0;
+            }, timeoutMs);
+            const elapsedMs = Date.now() - startedAt;
+            if (!matched) {
+                throw new Error(`Timed out after ${timeoutMs}ms waiting for ${present ? 'presence' : 'absence'} of ${JSON.stringify(filter)}`);
+            }
+            if (!present) {
+                return `Condition satisfied after ${elapsedMs}ms: no nodes matched ${JSON.stringify(filter)}.`;
+            }
+            const after = sessionA11y(session);
+            if (!after) {
+                return `Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`;
+            }
+            const matches = findNodes(after, filter);
+            if (detail === 'verbose') {
+                return JSON.stringify(matches.slice(0, 8).map(node => formatNode(node, after.bounds)), null, 2);
+            }
+            return `Condition satisfied after ${elapsedMs}ms with ${matches.length} matching node(s).`;
+        }
+        case 'fill_fields': {
+            const lines = [];
+            for (const field of action.fields) {
+                lines.push(await executeFillField(session, field, detail));
+            }
+            return lines.join('\n');
+        }
+    }
+}
+async function executeFillField(session, field, detail) {
+    switch (field.kind) {
+        case 'text': {
+            const before = sessionA11y(session);
+            const wait = await sendFieldText(session, field.fieldLabel, field.value, { exact: field.exact }, field.timeoutMs);
+            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
+            return [
+                `Filled text field "${field.fieldLabel}".`,
+                fieldSummary,
+                postActionSummary(session, before, wait, detail),
+            ].filter(Boolean).join('\n');
+        }
+        case 'choice': {
+            const before = sessionA11y(session);
+            const wait = await sendFieldChoice(session, field.fieldLabel, field.value, { exact: field.exact, query: field.query }, field.timeoutMs);
+            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
+            return [
+                `Set choice field "${field.fieldLabel}" to "${field.value}".`,
+                fieldSummary,
+                postActionSummary(session, before, wait, detail),
+            ].filter(Boolean).join('\n');
+        }
+        case 'toggle': {
+            const before = sessionA11y(session);
+            const wait = await sendSetChecked(session, field.label, { checked: field.checked, exact: field.exact, controlType: field.controlType }, field.timeoutMs);
+            return `Set ${field.controlType ?? 'checkbox/radio'} "${field.label}" to ${String(field.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`;
+        }
+        case 'file': {
+            const before = sessionA11y(session);
+            const wait = await sendFileUpload(session, field.paths, { fieldLabel: field.fieldLabel, exact: field.exact }, field.timeoutMs ?? 8_000);
+            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
+            return [
+                `Uploaded ${field.paths.length} file(s) to "${field.fieldLabel}".`,
+                fieldSummary,
+                postActionSummary(session, before, wait, detail),
+            ].filter(Boolean).join('\n');
+        }
+    }
+}
 function ok(text) {
     return { content: [{ type: 'text', text }] };
 }
@@ -571,7 +1101,8 @@ function nodeMatchesFilter(node, filter) {
         return false;
     if (!textMatches(node.value, filter.value))
         return false;
-    if (filter.text && !textMatches(`${node.name ?? ''} ${node.value ?? ''}`.trim(), filter.text))
+    if (filter.text &&
+        !textMatches(`${node.name ?? ''} ${node.value ?? ''} ${node.validation?.error ?? ''} ${node.validation?.description ?? ''}`.trim(), filter.text))
         return false;
     if (filter.checked !== undefined && node.state?.checked !== filter.checked)
         return false;
@@ -583,6 +1114,12 @@ function nodeMatchesFilter(node, filter) {
         return false;
     if (filter.expanded !== undefined && (node.state?.expanded ?? false) !== filter.expanded)
         return false;
+    if (filter.invalid !== undefined && (node.state?.invalid ?? false) !== filter.invalid)
+        return false;
+    if (filter.required !== undefined && (node.state?.required ?? false) !== filter.required)
+        return false;
+    if (filter.busy !== undefined && (node.state?.busy ?? false) !== filter.busy)
+        return false;
     return true;
 }
 export function findNodes(node, filter) {
@@ -618,6 +1155,8 @@ function summarizeFieldLabelState(session, fieldLabel) {
         parts.push(`value=${JSON.stringify(match.value)}`);
     if (match.state && Object.keys(match.state).length > 0)
         parts.push(`state=${JSON.stringify(match.state)}`);
+    if (match.validation?.error)
+        parts.push(`error=${JSON.stringify(match.validation.error)}`);
     return parts.join(' ');
 }
 function formatNode(node, viewport) {
@@ -669,6 +1208,7 @@ function formatNode(node, viewport) {
         },
         focusable: node.focusable,
         ...(node.state && Object.keys(node.state).length > 0 ? { state: node.state } : {}),
+        ...(node.validation && Object.keys(node.validation).length > 0 ? { validation: node.validation } : {}),
         path: node.path,
     };
 }

package/dist/session.d.ts

@@ -15,6 +15,13 @@ export interface A11yNode {
         selected?: boolean;
         checked?: boolean | 'mixed';
         focused?: boolean;
+        invalid?: boolean;
+        required?: boolean;
+        busy?: boolean;
+    };
+    validation?: {
+        description?: string;
+        error?: string;
     };
     meta?: {
         pageUrl?: string;
@@ -128,6 +135,7 @@ export interface PageFieldModel {
     name?: string;
     value?: string;
     state?: A11yNode['state'];
+    validation?: A11yNode['validation'];
     bounds?: {
         x: number;
         y: number;
@@ -280,12 +288,23 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
         x: number;
         y: number;
     };
+    fieldLabel?: string;
+    exact?: boolean;
     strategy?: 'auto' | 'chooser' | 'hidden' | 'drop';
     drop?: {
         x: number;
         y: number;
     };
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
+/** Set a labeled text-like field (`input`, `textarea`, contenteditable, ARIA textbox) semantically. */
+export declare function sendFieldText(session: Session, fieldLabel: string, value: string, opts?: {
+    exact?: boolean;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
+/** Choose a value for a labeled choice field (select, custom combobox, or radio-style group). */
+export declare function sendFieldChoice(session: Session, fieldLabel: string, value: string, opts?: {
+    exact?: boolean;
+    query?: string;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
 export declare function sendListboxPick(session: Session, label: string, opts?: {
     exact?: boolean;

package/dist/session.js

@@ -227,6 +227,10 @@ export function sendFileUpload(session, paths, opts, timeoutMs) {
         payload.x = opts.click.x;
         payload.y = opts.click.y;
     }
+    if (opts?.fieldLabel)
+        payload.fieldLabel = opts.fieldLabel;
+    if (opts?.exact !== undefined)
+        payload.exact = opts.exact;
     if (opts?.strategy)
         payload.strategy = opts.strategy;
     if (opts?.drop) {
@@ -235,6 +239,30 @@ export function sendFileUpload(session, paths, opts, timeoutMs) {
     }
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
+/** Set a labeled text-like field (`input`, `textarea`, contenteditable, ARIA textbox) semantically. */
+export function sendFieldText(session, fieldLabel, value, opts, timeoutMs) {
+    const payload = {
+        type: 'setFieldText',
+        fieldLabel,
+        value,
+    };
+    if (opts?.exact !== undefined)
+        payload.exact = opts.exact;
+    return sendAndWaitForUpdate(session, payload, timeoutMs);
+}
+/** Choose a value for a labeled choice field (select, custom combobox, or radio-style group). */
+export function sendFieldChoice(session, fieldLabel, value, opts, timeoutMs = LISTBOX_UPDATE_TIMEOUT_MS) {
+    const payload = {
+        type: 'setFieldChoice',
+        fieldLabel,
+        value,
+    };
+    if (opts?.exact !== undefined)
+        payload.exact = opts.exact;
+    if (opts?.query)
+        payload.query = opts.query;
+    return sendAndWaitForUpdate(session, payload, timeoutMs);
+}
 /** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
 export function sendListboxPick(session, label, opts, timeoutMs = LISTBOX_UPDATE_TIMEOUT_MS) {
     const payload = { type: 'listboxPick', label };
@@ -588,6 +616,22 @@ function cloneState(state) {
         next.checked = state.checked;
     if (state.focused !== undefined)
         next.focused = state.focused;
+    if (state.invalid !== undefined)
+        next.invalid = state.invalid;
+    if (state.required !== undefined)
+        next.required = state.required;
+    if (state.busy !== undefined)
+        next.busy = state.busy;
+    return Object.keys(next).length > 0 ? next : undefined;
+}
+function cloneValidation(validation) {
+    if (!validation)
+        return undefined;
+    const next = {};
+    if (validation.description)
+        next.description = validation.description;
+    if (validation.error)
+        next.error = validation.error;
     return Object.keys(next).length > 0 ? next : undefined;
 }
 function clonePath(path) {
@@ -707,6 +751,7 @@ function toFieldModel(node, includeBounds = true) {
         ...(fieldLabel(node) ? { name: fieldLabel(node) } : {}),
         ...(value ? { value } : {}),
         ...(cloneState(node.state) ? { state: cloneState(node.state) } : {}),
+        ...(cloneValidation(node.validation) ? { validation: cloneValidation(node.validation) } : {}),
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
 }
@@ -982,7 +1027,7 @@ function diffCompactNodes(before, after) {
     }
     const beforeState = before.state ?? {};
     const afterState = after.state ?? {};
-    for (const key of ['disabled', 'expanded', 'selected', 'checked', 'focused']) {
+    for (const key of ['disabled', 'expanded', 'selected', 'checked', 'focused', 'invalid', 'required', 'busy']) {
         if (beforeState[key] !== afterState[key]) {
             changes.push(`${key} ${formatStateValue(beforeState[key])} -> ${formatStateValue(afterState[key])}`);
         }
@@ -1216,6 +1261,19 @@ function walkNode(element, layout, path) {
         state.checked = checked;
     if (semantic?.focused !== undefined)
         state.focused = !!semantic.focused;
+    if (semantic?.ariaInvalid !== undefined)
+        state.invalid = !!semantic.ariaInvalid;
+    if (semantic?.ariaRequired !== undefined)
+        state.required = !!semantic.ariaRequired;
+    if (semantic?.ariaBusy !== undefined)
+        state.busy = !!semantic.ariaBusy;
+    const validation = {};
+    if (typeof semantic?.validationDescription === 'string' && semantic.validationDescription.trim().length > 0) {
+        validation.description = semantic.validationDescription;
+    }
+    if (typeof semantic?.validationError === 'string' && semantic.validationError.trim().length > 0) {
+        validation.error = semantic.validationError;
+    }
     const meta = {};
     if (typeof semantic?.pageUrl === 'string')
         meta.pageUrl = semantic.pageUrl;
@@ -1238,6 +1296,7 @@ function walkNode(element, layout, path) {
         ...(name ? { name } : {}),
         ...(value ? { value } : {}),
         ...(Object.keys(state).length > 0 ? { state } : {}),
+        ...(Object.keys(validation).length > 0 ? { validation } : {}),
         ...(Object.keys(meta).length > 0 ? { meta } : {}),
         bounds,
         path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.19.9",
+  "version": "1.19.10",
   "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.9",
+    "@geometra/proxy": "^1.19.10",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.18.0",
     "zod": "^3.23.0"