@geometra/mcp 1.19.8 → 1.19.9

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

@@ -1,6 +1,6 @@
 import { afterAll, describe, expect, it } from 'vitest';
 import { WebSocketServer } from 'ws';
-import { connect, disconnect, sendListboxPick } from '../session.js';
+import { connect, disconnect, sendClick, sendListboxPick } from '../session.js';
 describe('proxy-backed MCP actions', () => {
     afterAll(() => {
         disconnect();
@@ -56,4 +56,100 @@ describe('proxy-backed MCP actions', () => {
             await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
         }
     });
+    it('falls back to the latest observed update when a legacy peer does not send request-scoped ack', async () => {
+        const wss = new WebSocketServer({ port: 0 });
+        wss.on('connection', ws => {
+            ws.on('message', raw => {
+                const msg = JSON.parse(String(raw));
+                if (msg.type === 'resize') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: { kind: 'box', props: {}, semantic: { tag: 'body', role: 'group' }, children: [] },
+                    }));
+                    return;
+                }
+                if (msg.type === 'event') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: { kind: 'box', props: {}, semantic: { tag: 'body', role: 'group', ariaLabel: 'Updated' }, children: [] },
+                    }));
+                }
+            });
+        });
+        const port = await new Promise((resolve, reject) => {
+            wss.once('listening', () => {
+                const address = wss.address();
+                if (typeof address === 'object' && address)
+                    resolve(address.port);
+                else
+                    reject(new Error('Failed to resolve ephemeral WebSocket port'));
+            });
+            wss.once('error', reject);
+        });
+        try {
+            const session = await connect(`ws://127.0.0.1:${port}`);
+            await expect(sendClick(session, 5, 5, 60)).resolves.toMatchObject({ status: 'updated', timeoutMs: 60 });
+        }
+        finally {
+            disconnect();
+            await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
+        }
+    });
+    it('ignores invalid patch paths instead of mutating ancestor layout nodes', async () => {
+        const wss = new WebSocketServer({ port: 0 });
+        wss.on('connection', ws => {
+            ws.on('message', raw => {
+                const msg = JSON.parse(String(raw));
+                if (msg.type === 'resize') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: {
+                            x: 0,
+                            y: 0,
+                            width: 200,
+                            height: 100,
+                            children: [{ x: 10, y: 20, width: 30, height: 40, children: [] }],
+                        },
+                        tree: {
+                            kind: 'box',
+                            props: {},
+                            semantic: { tag: 'body', role: 'group' },
+                            children: [{ kind: 'box', props: {}, semantic: { tag: 'div', role: 'group' }, children: [] }],
+                        },
+                    }));
+                    setTimeout(() => {
+                        ws.send(JSON.stringify({
+                            type: 'patch',
+                            patches: [{ path: [9], x: 999, y: 999 }],
+                        }));
+                    }, 10);
+                }
+            });
+        });
+        const port = await new Promise((resolve, reject) => {
+            wss.once('listening', () => {
+                const address = wss.address();
+                if (typeof address === 'object' && address)
+                    resolve(address.port);
+                else
+                    reject(new Error('Failed to resolve ephemeral WebSocket port'));
+            });
+            wss.once('error', reject);
+        });
+        try {
+            const session = await connect(`ws://127.0.0.1:${port}`);
+            await new Promise(resolve => setTimeout(resolve, 30));
+            expect(session.layout).toMatchObject({
+                x: 0,
+                y: 0,
+                children: [{ x: 10, y: 20 }],
+            });
+        }
+        finally {
+            disconnect();
+            await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
+        }
+    });
 });

package/dist/__tests__/server-filters.test.d.ts

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

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { findNodes } from '../server.js';
+function node(role, bounds, options) {
+    return {
+        role,
+        ...(options?.name ? { name: options.name } : {}),
+        ...(options?.value ? { value: options.value } : {}),
+        ...(options?.state ? { state: options.state } : {}),
+        bounds,
+        path: options?.path ?? [],
+        children: options?.children ?? [],
+        focusable: options?.focusable ?? false,
+    };
+}
+describe('findNodes', () => {
+    it('matches value and checked-state filters generically', () => {
+        const tree = node('group', { x: 0, y: 0, width: 800, height: 600 }, {
+            children: [
+                node('combobox', { x: 20, y: 20, width: 260, height: 36 }, {
+                    path: [0],
+                    name: 'Location',
+                    value: 'Austin, Texas, United States',
+                    focusable: true,
+                }),
+                node('checkbox', { x: 20, y: 72, width: 24, height: 24 }, {
+                    path: [1],
+                    name: 'Notion Website',
+                    state: { checked: true },
+                    focusable: true,
+                }),
+            ],
+        });
+        expect(findNodes(tree, { value: 'Austin, Texas' })).toEqual([
+            expect.objectContaining({ role: 'combobox', name: 'Location' }),
+        ]);
+        expect(findNodes(tree, { text: 'United States' })).toEqual([
+            expect.objectContaining({ role: 'combobox', value: 'Austin, Texas, United States' }),
+        ]);
+        expect(findNodes(tree, { role: 'checkbox', checked: true })).toEqual([
+            expect.objectContaining({ name: 'Notion Website' }),
+        ]);
+    });
+});

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

@@ -4,6 +4,7 @@ function node(role, name, bounds, options) {
     return {
         role,
         ...(name ? { name } : {}),
+        ...(options?.value ? { value: options.value } : {}),
         ...(options?.state ? { state: options.state } : {}),
         ...(options?.meta ? { meta: options.meta } : {}),
         bounds,
@@ -83,8 +84,14 @@ describe('buildPageModel', () => {
                             path: [0, 0],
                             children: [
                                 node('heading', 'Application', { x: 60, y: 132, width: 200, height: 24 }, { path: [0, 0, 0] }),
-                                node('textbox', 'Full name*', { x: 60, y: 160, width: 300, height: 36 }, { path: [0, 0, 1] }),
-                                node('textbox', 'Email:', { x: 60, y: 208, width: 300, height: 36 }, { path: [0, 0, 2] }),
+                                node('textbox', 'Full name*', { x: 60, y: 160, width: 300, height: 36 }, {
+                                    path: [0, 0, 1],
+                                    value: 'Taylor Applicant',
+                                }),
+                                node('textbox', 'Email:', { x: 60, y: 208, width: 300, height: 36 }, {
+                                    path: [0, 0, 2],
+                                    value: 'taylor@example.com',
+                                }),
                                 node('button', 'Submit application', { x: 60, y: 264, width: 180, height: 40 }, {
                                     path: [0, 0, 3],
                                     focusable: true,
@@ -108,6 +115,7 @@ 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?.actions.map(action => action.id)).toEqual(['n:0.0.3']);
         expect(detail?.fields[0]).not.toHaveProperty('bounds');
     });
@@ -280,4 +288,39 @@ describe('buildUiDelta', () => {
         expect(summary).toContain('~ focus n:1.0 textbox "Full name" -> n:1.1 textbox "Country"');
         expect(summary).toContain('~ navigation "https://jobs.example.com/apply" -> "https://jobs.example.com/apply?step=details"');
     });
+    it('includes control values in compact indexes and semantic deltas', () => {
+        const before = node('group', undefined, { x: 0, y: 0, width: 640, height: 480 }, {
+            children: [
+                node('textbox', 'Location', { x: 20, y: 40, width: 280, height: 36 }, {
+                    path: [0],
+                    focusable: true,
+                    value: 'Austin',
+                }),
+            ],
+        });
+        const after = node('group', undefined, { x: 0, y: 0, width: 640, height: 480 }, {
+            children: [
+                node('textbox', 'Location', { x: 20, y: 40, width: 280, height: 36 }, {
+                    path: [0],
+                    focusable: true,
+                    value: 'Austin, Texas, United States',
+                }),
+            ],
+        });
+        const compact = buildCompactUiIndex(after, { maxNodes: 10 });
+        expect(compact.nodes[0]).toMatchObject({
+            role: 'textbox',
+            name: 'Location',
+            value: 'Austin, Texas, United States',
+        });
+        const delta = buildUiDelta(before, after);
+        expect(delta.updated).toEqual([
+            expect.objectContaining({
+                changes: [
+                    'value "Austin" -> "Austin, Texas, United States"',
+                ],
+            }),
+        ]);
+        expect(summarizeUiDelta(delta)).toContain('value "Austin" -> "Austin, Texas, United States"');
+    });
 });

package/dist/server.d.ts

@@ -1,2 +1,18 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { A11yNode } from './session.js';
+type NodeStateFilterValue = boolean | 'mixed';
+interface NodeFilter {
+    id?: string;
+    role?: string;
+    name?: string;
+    text?: string;
+    value?: string;
+    checked?: NodeStateFilterValue;
+    disabled?: boolean;
+    focused?: boolean;
+    selected?: boolean;
+    expanded?: boolean;
+}
 export declare function createServer(): McpServer;
+export declare function findNodes(node: A11yNode, filter: NodeFilter): A11yNode[];
+export {};

package/dist/server.js

@@ -1,9 +1,15 @@
 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, } from './session.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';
+function checkedStateInput() {
+    return z
+        .union([z.boolean(), z.literal('mixed')])
+        .optional()
+        .describe('Match checked state (`true`, `false`, or `mixed`)');
+}
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.8' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.9' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -69,25 +75,86 @@ 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, or text content. 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, and tree path.
+    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)'),
-    }, async ({ id, role, name, text }) => {
+        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 }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
         const a11y = buildA11yTree(session.tree, session.layout);
-        const matches = findNodes(a11y, { id, role, name, text });
+        const filter = { id, role, name, text, value, checked, disabled, focused, selected, expanded };
+        if (!hasNodeFilter(filter))
+            return err('Provide at least one query filter (id, role, name, text, value, or state)');
+        const matches = findNodes(a11y, filter);
         if (matches.length === 0) {
-            return ok(`No elements found matching ${JSON.stringify({ id, role, name, text })}`);
+            return ok(`No elements found matching ${JSON.stringify(filter)}`);
         }
         const result = matches.map(node => formatNode(node, 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.
+
+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'),
+        present: z.boolean().optional().default(true).describe('Wait for a matching node to exist (default true) or disappear'),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .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 }) => {
+        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 };
+        if (!hasNodeFilter(filter))
+            return err('Provide at least one wait filter (id, role, name, text, value, or state)');
+        const matchesCondition = () => {
+            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;
+        };
+        const startedAt = Date.now();
+        const matched = await waitForUiCondition(session, matchesCondition, timeoutMs);
+        const elapsedMs = Date.now() - startedAt;
+        if (!matched) {
+            return err(`Timed out after ${timeoutMs}ms waiting for ${present ? 'presence' : 'absence'} of ${JSON.stringify(filter)}.\nCurrent UI:\n${compactSessionSummary(session)}`);
+        }
+        if (!present) {
+            return ok(`Condition satisfied after ${elapsedMs}ms: no nodes matched ${JSON.stringify(filter)}.`);
+        }
+        const after = sessionA11y(session);
+        if (!after)
+            return ok(`Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`);
+        const matches = findNodes(after, filter);
+        const result = matches.slice(0, 8).map(node => formatNode(node, after.bounds));
+        return ok(JSON.stringify(result, null, 2));
+    });
     // ── 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.
 
@@ -151,12 +218,19 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
 After clicking, returns a compact semantic delta when possible (dialogs/forms/lists/nodes changed). If nothing meaningful changed, returns a short current-UI overview.`, {
         x: z.number().describe('X coordinate to click (use center of element bounds from geometra_query)'),
         y: z.number().describe('Y coordinate to click'),
-    }, async ({ x, y }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout (use a longer value for slow submits or route transitions)'),
+    }, async ({ x, y, timeoutMs }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        const wait = await sendClick(session, x, y);
+        const wait = await sendClick(session, x, y, timeoutMs);
         const summary = postActionSummary(session, before, wait);
         return ok(`Clicked at (${x}, ${y}).\n${summary}`);
     });
@@ -165,12 +239,19 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
 
 Each character is sent as a key event through the geometry protocol. Returns a compact semantic delta when possible, otherwise a short current-UI overview.`, {
         text: z.string().describe('Text to type into the focused element'),
-    }, async ({ text }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout'),
+    }, async ({ text, timeoutMs }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        const wait = await sendType(session, text);
+        const wait = await sendType(session, text, timeoutMs);
         const summary = postActionSummary(session, before, wait);
         return ok(`Typed "${text}".\n${summary}`);
     });
@@ -181,12 +262,19 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         ctrl: z.boolean().optional().describe('Hold Ctrl'),
         meta: z.boolean().optional().describe('Hold Meta/Cmd'),
         alt: z.boolean().optional().describe('Hold Alt'),
-    }, async ({ key, shift, ctrl, meta, alt }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout'),
+    }, async ({ key, shift, ctrl, meta, alt, timeoutMs }) => {
         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 });
+        const wait = await sendKey(session, key, { shift, ctrl, meta, alt }, timeoutMs);
         const summary = postActionSummary(session, before, wait);
         return ok(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`);
     });
@@ -203,7 +291,14 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
             .describe('Upload strategy (default auto)'),
         dropX: z.number().optional().describe('Drop target X (viewport) for strategy drop'),
         dropY: z.number().optional().describe('Drop target Y (viewport) for strategy drop'),
-    }, async ({ paths, x, y, strategy, dropX, dropY }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .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 }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -213,7 +308,7 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
                 click: x !== undefined && y !== undefined ? { x, y } : undefined,
                 strategy,
                 drop: dropX !== undefined && dropY !== undefined ? { x: dropX, y: dropY } : undefined,
-            });
+            }, timeoutMs ?? 8_000);
             const summary = postActionSummary(session, before, wait);
             return ok(`Uploaded ${paths.length} file(s).\n${summary}`);
         }
@@ -230,7 +325,14 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
         openY: z.number().optional().describe('Click to open dropdown'),
         fieldLabel: z.string().optional().describe('Field label of the dropdown/combobox to open semantically (e.g. "Location")'),
         query: z.string().optional().describe('Optional text to type into a searchable combobox before selecting'),
-    }, async ({ label, exact, openX, openY, fieldLabel, query }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout for slow dropdowns / remote search results'),
+    }, async ({ label, exact, openX, openY, fieldLabel, query, timeoutMs }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -241,9 +343,14 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
                 open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
                 fieldLabel,
                 query,
-            });
+            }, timeoutMs);
             const summary = postActionSummary(session, before, wait);
-            return ok(`Picked listbox option "${label}".\n${summary}`);
+            const fieldSummary = fieldLabel ? summarizeFieldLabelState(session, fieldLabel) : undefined;
+            return ok([
+                `Picked listbox option "${label}".`,
+                fieldSummary,
+                summary,
+            ].filter(Boolean).join('\n'));
         }
         catch (e) {
             return err(e.message);
@@ -258,7 +365,14 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
         value: z.string().optional().describe('Option value= attribute'),
         label: z.string().optional().describe('Visible option label (substring match)'),
         index: z.number().int().min(0).optional().describe('Zero-based option index'),
-    }, async ({ x, y, value, label, index }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout'),
+    }, async ({ x, y, value, label, index, timeoutMs }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -267,7 +381,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 });
+            const wait = await sendSelectOption(session, x, y, { value, label, index }, timeoutMs);
             const summary = postActionSummary(session, before, wait);
             return ok(`Selected option.\n${summary}`);
         }
@@ -282,13 +396,20 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         checked: z.boolean().optional().default(true).describe('Desired checked state (radios only support true)'),
         exact: z.boolean().optional().describe('Exact label match'),
         controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
-    }, async ({ label, checked, exact, controlType }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout'),
+    }, async ({ label, checked, exact, controlType, timeoutMs }) => {
         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 });
+            const wait = await sendSetChecked(session, label, { checked, exact, controlType }, timeoutMs);
             const summary = postActionSummary(session, before, wait);
             return ok(`Set ${controlType ?? 'checkbox/radio'} "${label}" to ${String(checked ?? true)}.\n${summary}`);
         }
@@ -302,13 +423,20 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         deltaX: z.number().optional().describe('Horizontal scroll delta'),
         x: z.number().optional().describe('Move pointer to X before scrolling'),
         y: z.number().optional().describe('Move pointer to Y before scrolling'),
-    }, async ({ deltaY, deltaX, x, y }) => {
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .describe('Optional action wait timeout'),
+    }, async ({ deltaY, deltaX, x, y, timeoutMs }) => {
         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 });
+            const wait = await sendWheel(session, deltaY, { deltaX, x, y }, timeoutMs);
             const summary = postActionSummary(session, before, wait);
             return ok(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`);
         }
@@ -390,7 +518,7 @@ function postActionSummary(session, before, wait) {
     const after = sessionA11y(session);
     const notes = [];
     if (wait?.status === 'acknowledged') {
-        notes.push('Proxy acknowledged the action quickly; waiting logic did not need to rely on a full frame/patch round-trip.');
+        notes.push('The peer acknowledged the action quickly; waiting logic did not need to rely on a full frame/patch round-trip.');
     }
     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.`);
@@ -424,19 +552,43 @@ function ok(text) {
 function err(text) {
     return { content: [{ type: 'text', text }], isError: true };
 }
-function findNodes(node, filter) {
+function hasNodeFilter(filter) {
+    return Object.values(filter).some(value => value !== undefined);
+}
+function textMatches(haystack, needle) {
+    if (!needle)
+        return true;
+    if (!haystack)
+        return false;
+    return haystack.toLowerCase().includes(needle.toLowerCase());
+}
+function nodeMatchesFilter(node, filter) {
+    if (filter.id && nodeIdForPath(node.path) !== filter.id)
+        return false;
+    if (filter.role && node.role !== filter.role)
+        return false;
+    if (!textMatches(node.name, filter.name))
+        return false;
+    if (!textMatches(node.value, filter.value))
+        return false;
+    if (filter.text && !textMatches(`${node.name ?? ''} ${node.value ?? ''}`.trim(), filter.text))
+        return false;
+    if (filter.checked !== undefined && node.state?.checked !== filter.checked)
+        return false;
+    if (filter.disabled !== undefined && (node.state?.disabled ?? false) !== filter.disabled)
+        return false;
+    if (filter.focused !== undefined && (node.state?.focused ?? false) !== filter.focused)
+        return false;
+    if (filter.selected !== undefined && (node.state?.selected ?? false) !== filter.selected)
+        return false;
+    if (filter.expanded !== undefined && (node.state?.expanded ?? false) !== filter.expanded)
+        return false;
+    return true;
+}
+export function findNodes(node, filter) {
     const matches = [];
     function walk(n) {
-        let match = true;
-        if (filter.id && nodeIdForPath(n.path) !== filter.id)
-            match = false;
-        if (filter.role && n.role !== filter.role)
-            match = false;
-        if (filter.name && (!n.name || !n.name.includes(filter.name)))
-            match = false;
-        if (filter.text && (!n.name || !n.name.includes(filter.text)))
-            match = false;
-        if (match && (filter.id || filter.role || filter.name || filter.text))
+        if (nodeMatchesFilter(n, filter) && hasNodeFilter(filter))
             matches.push(n);
         for (const child of n.children)
             walk(child);
@@ -444,6 +596,30 @@ function findNodes(node, filter) {
     walk(node);
     return matches;
 }
+function summarizeFieldLabelState(session, fieldLabel) {
+    const a11y = sessionA11y(session);
+    if (!a11y)
+        return undefined;
+    const matches = findNodes(a11y, {
+        name: fieldLabel,
+        role: 'combobox',
+    });
+    if (matches.length === 0) {
+        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'textbox' }));
+    }
+    if (matches.length === 0) {
+        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'button' }));
+    }
+    const match = matches[0];
+    if (!match)
+        return undefined;
+    const parts = [`Field "${fieldLabel}"`];
+    if (match.value)
+        parts.push(`value=${JSON.stringify(match.value)}`);
+    if (match.state && Object.keys(match.state).length > 0)
+        parts.push(`state=${JSON.stringify(match.state)}`);
+    return parts.join(' ');
+}
 function formatNode(node, viewport) {
     const visibleLeft = Math.max(0, node.bounds.x);
     const visibleTop = Math.max(0, node.bounds.y);
@@ -466,6 +642,7 @@ function formatNode(node, viewport) {
         id: nodeIdForPath(node.path),
         role: node.role,
         name: node.name,
+        ...(node.value ? { value: node.value } : {}),
         bounds: node.bounds,
         visibleBounds: {
             x: visibleLeft,

package/dist/session.d.ts

@@ -8,6 +8,7 @@ import WebSocket from 'ws';
 export interface A11yNode {
     role: string;
     name?: string;
+    value?: string;
     state?: {
         disabled?: boolean;
         expanded?: boolean;
@@ -35,6 +36,7 @@ export interface CompactUiNode {
     id: string;
     role: string;
     name?: string;
+    value?: string;
     state?: A11yNode['state'];
     pinned?: boolean;
     bounds: {
@@ -124,6 +126,7 @@ export interface PageFieldModel {
     id: string;
     role: string;
     name?: string;
+    value?: string;
     state?: A11yNode['state'];
     bounds?: {
         x: number;
@@ -250,14 +253,15 @@ export declare function connectThroughProxy(options: {
 }): Promise<Session>;
 export declare function getSession(): Session | null;
 export declare function disconnect(): void;
+export declare function waitForUiCondition(session: Session, predicate: () => boolean, timeoutMs: number): Promise<boolean>;
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
  */
-export declare function sendClick(session: Session, x: number, y: number): Promise<UpdateWaitResult>;
+export declare function sendClick(session: Session, x: number, y: number, timeoutMs?: number): Promise<UpdateWaitResult>;
 /**
  * Send a sequence of key events to type text into the focused element.
  */
-export declare function sendType(session: Session, text: string): Promise<UpdateWaitResult>;
+export declare function sendType(session: Session, text: string, timeoutMs?: number): Promise<UpdateWaitResult>;
 /**
  * Send a special key (Enter, Tab, Escape, etc.)
  */
@@ -266,7 +270,7 @@ export declare function sendKey(session: Session, key: string, modifiers?: {
     ctrl?: boolean;
     meta?: boolean;
     alt?: boolean;
-}): Promise<UpdateWaitResult>;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
 /**
  * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
  * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
@@ -281,7 +285,7 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
         x: number;
         y: number;
     };
-}): Promise<UpdateWaitResult>;
+}, 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;
@@ -291,25 +295,25 @@ export declare function sendListboxPick(session: Session, label: string, opts?:
     };
     fieldLabel?: string;
     query?: string;
-}): Promise<UpdateWaitResult>;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
 export declare function sendSelectOption(session: Session, x: number, y: number, option: {
     value?: string;
     label?: string;
     index?: number;
-}): Promise<UpdateWaitResult>;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Set a checkbox/radio by label instead of relying on coordinate clicks. */
 export declare function sendSetChecked(session: Session, label: string, opts?: {
     checked?: boolean;
     exact?: boolean;
     controlType?: 'checkbox' | 'radio';
-}): Promise<UpdateWaitResult>;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
 export declare function sendWheel(session: Session, deltaY: number, opts?: {
     deltaX?: number;
     x?: number;
     y?: number;
-}): Promise<UpdateWaitResult>;
+}, timeoutMs?: number): Promise<UpdateWaitResult>;
 /**
  * Build a flat accessibility tree from the raw UI tree + layout.
  * This is a standalone reimplementation that works with raw JSON —

package/dist/session.js

@@ -127,21 +127,57 @@ export function getSession() {
 export function disconnect() {
     shutdownPreviousSession();
 }
+export function waitForUiCondition(session, predicate, timeoutMs) {
+    return new Promise((resolve) => {
+        const check = () => {
+            let matched = false;
+            try {
+                matched = predicate();
+            }
+            catch {
+                matched = false;
+            }
+            if (matched) {
+                cleanup();
+                resolve(true);
+            }
+        };
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve(false);
+        }, timeoutMs);
+        const onMessage = () => {
+            check();
+        };
+        const onClose = () => {
+            cleanup();
+            resolve(false);
+        };
+        function cleanup() {
+            clearTimeout(timeout);
+            session.ws.off('message', onMessage);
+            session.ws.off('close', onClose);
+        }
+        session.ws.on('message', onMessage);
+        session.ws.on('close', onClose);
+        check();
+    });
+}
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
  */
-export function sendClick(session, x, y) {
+export function sendClick(session, x, y, timeoutMs) {
     return sendAndWaitForUpdate(session, {
         type: 'event',
         eventType: 'onClick',
         x,
         y,
-    });
+    }, timeoutMs);
 }
 /**
  * Send a sequence of key events to type text into the focused element.
  */
-export function sendType(session, text) {
+export function sendType(session, text, timeoutMs) {
     return new Promise((resolve, reject) => {
         if (session.ws.readyState !== WebSocket.OPEN) {
             reject(new Error('Not connected'));
@@ -163,13 +199,13 @@ export function sendType(session, text) {
             session.ws.send(JSON.stringify({ ...keyEvent, eventType: 'onKeyUp' }));
         }
         // Wait briefly for server to process and send update
-        waitForNextUpdate(session).then(resolve).catch(reject);
+        waitForNextUpdate(session, timeoutMs).then(resolve).catch(reject);
     });
 }
 /**
  * Send a special key (Enter, Tab, Escape, etc.)
  */
-export function sendKey(session, key, modifiers) {
+export function sendKey(session, key, modifiers, timeoutMs) {
     return sendAndWaitForUpdate(session, {
         type: 'key',
         eventType: 'onKeyDown',
@@ -179,13 +215,13 @@ export function sendKey(session, key, modifiers) {
         ctrlKey: modifiers?.ctrl ?? false,
         metaKey: modifiers?.meta ?? false,
         altKey: modifiers?.alt ?? false,
-    });
+    }, timeoutMs);
 }
 /**
  * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
  * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
  */
-export function sendFileUpload(session, paths, opts) {
+export function sendFileUpload(session, paths, opts, timeoutMs) {
     const payload = { type: 'file', paths };
     if (opts?.click) {
         payload.x = opts.click.x;
@@ -197,10 +233,10 @@ export function sendFileUpload(session, paths, opts) {
         payload.dropX = opts.drop.x;
         payload.dropY = opts.drop.y;
     }
-    return sendAndWaitForUpdate(session, payload);
+    return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
-export function sendListboxPick(session, label, opts) {
+export function sendListboxPick(session, label, opts, timeoutMs = LISTBOX_UPDATE_TIMEOUT_MS) {
     const payload = { type: 'listboxPick', label };
     if (opts?.exact !== undefined)
         payload.exact = opts.exact;
@@ -212,19 +248,19 @@ export function sendListboxPick(session, label, opts) {
         payload.fieldLabel = opts.fieldLabel;
     if (opts?.query)
         payload.query = opts.query;
-    return sendAndWaitForUpdate(session, payload, LISTBOX_UPDATE_TIMEOUT_MS);
+    return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
-export function sendSelectOption(session, x, y, option) {
+export function sendSelectOption(session, x, y, option, timeoutMs) {
     return sendAndWaitForUpdate(session, {
         type: 'selectOption',
         x,
         y,
         ...option,
-    });
+    }, timeoutMs);
 }
 /** Set a checkbox/radio by label instead of relying on coordinate clicks. */
-export function sendSetChecked(session, label, opts) {
+export function sendSetChecked(session, label, opts, timeoutMs) {
     const payload = { type: 'setChecked', label };
     if (opts?.checked !== undefined)
         payload.checked = opts.checked;
@@ -232,17 +268,17 @@ export function sendSetChecked(session, label, opts) {
         payload.exact = opts.exact;
     if (opts?.controlType)
         payload.controlType = opts.controlType;
-    return sendAndWaitForUpdate(session, payload);
+    return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
-export function sendWheel(session, deltaY, opts) {
+export function sendWheel(session, deltaY, opts, timeoutMs) {
     return sendAndWaitForUpdate(session, {
         type: 'wheel',
         deltaY,
         deltaX: opts?.deltaX ?? 0,
         ...(opts?.x !== undefined ? { x: opts.x } : {}),
         ...(opts?.y !== undefined ? { y: opts.y } : {}),
-    });
+    }, timeoutMs);
 }
 /**
  * Build a flat accessibility tree from the raw UI tree + layout.
@@ -415,10 +451,12 @@ function intersectsViewportWithMargin(b, vw, vh, marginY) {
 }
 function compactNodeFromA11y(node, pinned = false) {
     const name = sanitizeInlineName(node.name, 240);
+    const value = sanitizeInlineName(node.value, 180);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         ...(name ? { name } : {}),
+        ...(value ? { value } : {}),
         ...(node.state && Object.keys(node.state).length > 0 ? { state: node.state } : {}),
         ...(pinned ? { pinned: true } : {}),
         bounds: { ...node.bounds },
@@ -521,11 +559,12 @@ export function summarizeCompactIndex(nodes, maxLines = 80) {
     const slice = nodes.slice(0, maxLines);
     for (const n of slice) {
         const nm = n.name ? ` "${truncateUiText(n.name, 48)}"` : '';
+        const val = n.value ? ` value=${JSON.stringify(truncateUiText(n.value, 40))}` : '';
         const st = n.state && Object.keys(n.state).length ? ` ${JSON.stringify(n.state)}` : '';
         const foc = n.focusable ? ' *' : '';
         const pin = n.pinned ? ' [pinned]' : '';
         const b = n.bounds;
-        lines.push(`${n.id} ${n.role}${nm}${pin} (${b.x},${b.y} ${b.width}x${b.height})${st}${foc}`);
+        lines.push(`${n.id} ${n.role}${nm}${pin}${val} (${b.x},${b.y} ${b.width}x${b.height})${st}${foc}`);
     }
     if (nodes.length > maxLines) {
         lines.push(`… and ${nodes.length - maxLines} more (use geometra_snapshot with a higher maxNodes or geometra_query)`);
@@ -661,10 +700,12 @@ function primaryAction(node) {
     };
 }
 function toFieldModel(node, includeBounds = true) {
+    const value = sanitizeInlineName(node.value, 120);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         ...(fieldLabel(node) ? { name: fieldLabel(node) } : {}),
+        ...(value ? { value } : {}),
         ...(cloneState(node.state) ? { state: cloneState(node.state) } : {}),
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
@@ -918,8 +959,12 @@ function pathKey(path) {
     return path.join('.');
 }
 function compactNodeLabel(node) {
-    if (node.name)
-        return `${node.id} ${node.role} "${truncateUiText(node.name, 40)}"`;
+    if (node.name) {
+        const value = node.value ? ` value=${JSON.stringify(truncateUiText(node.value, 28))}` : '';
+        return `${node.id} ${node.role} "${truncateUiText(node.name, 40)}"${value}`;
+    }
+    if (node.value)
+        return `${node.id} ${node.role} value=${JSON.stringify(truncateUiText(node.value, 28))}`;
     return `${node.id} ${node.role}`;
 }
 function formatStateValue(value) {
@@ -932,6 +977,9 @@ function diffCompactNodes(before, after) {
     if ((before.name ?? '') !== (after.name ?? '')) {
         changes.push(`name ${JSON.stringify(truncateUiText(before.name ?? 'unset', 32))} -> ${JSON.stringify(truncateUiText(after.name ?? 'unset', 32))}`);
     }
+    if ((before.value ?? '') !== (after.value ?? '')) {
+        changes.push(`value ${JSON.stringify(truncateUiText(before.value ?? 'unset', 32))} -> ${JSON.stringify(truncateUiText(after.value ?? 'unset', 32))}`);
+    }
     const beforeState = before.state ?? {};
     const afterState = after.state ?? {};
     for (const key of ['disabled', 'expanded', 'selected', 'checked', 'focused']) {
@@ -1147,6 +1195,7 @@ function walkNode(element, layout, path) {
     const handlers = element.handlers;
     const role = inferRole(kind, semantic, handlers);
     const name = inferName(kind, semantic, props);
+    const value = inferValue(semantic, props);
     const focusable = !!(handlers?.onClick || handlers?.onKeyDown || handlers?.onKeyUp ||
         handlers?.onCompositionStart || handlers?.onCompositionUpdate || handlers?.onCompositionEnd);
     const bounds = {
@@ -1187,6 +1236,7 @@ function walkNode(element, layout, path) {
     return {
         role,
         ...(name ? { name } : {}),
+        ...(value ? { value } : {}),
         ...(Object.keys(state).length > 0 ? { state } : {}),
         ...(Object.keys(meta).length > 0 ? { meta } : {}),
         bounds,
@@ -1243,15 +1293,24 @@ function inferName(kind, semantic, props) {
         return (semantic?.alt ?? props?.alt);
     return semantic?.alt;
 }
+function inferValue(semantic, props) {
+    const direct = semantic?.valueText ?? props?.value;
+    return typeof direct === 'string' && direct.trim().length > 0 ? direct : undefined;
+}
 function applyPatches(layout, patches) {
     for (const patch of patches) {
         let node = layout;
+        let validPath = true;
         for (const idx of patch.path) {
             const children = node.children;
-            if (!children?.[idx])
+            if (!children?.[idx]) {
+                validPath = false;
                 break;
+            }
             node = children[idx];
         }
+        if (!validPath)
+            continue;
         if (patch.x !== undefined)
             node.x = patch.x;
         if (patch.y !== undefined)
@@ -1281,7 +1340,7 @@ function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, reques
                 const msg = JSON.parse(String(data));
                 const messageRequestId = typeof msg.requestId === 'string' ? msg.requestId : undefined;
                 if (requestId) {
-                    if (msg.type === 'error' && messageRequestId === requestId) {
+                    if (msg.type === 'error' && (messageRequestId === requestId || messageRequestId === undefined)) {
                         cleanup();
                         reject(new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error'));
                         return;
@@ -1318,6 +1377,10 @@ function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, reques
         // Expose timeout explicitly so action handlers can tell the user the result is ambiguous.
         const timeout = setTimeout(() => {
             cleanup();
+            if (requestId && session.updateRevision > startRevision) {
+                resolve({ status: 'updated', timeoutMs });
+                return;
+            }
             resolve({ status: 'timed_out', timeoutMs });
         }, timeoutMs);
         function cleanup() {

package/package.json

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