@geometra/mcp 1.19.11 → 1.19.12

package/README.md

@@ -19,12 +19,13 @@ 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, text content, current value, or semantic state such as `invalid`, `required`, or `busy` |
+| `geometra_query` | Find elements by stable id, role, name, text content, ancestor/prompt context, current value, or semantic state such as `invalid`, `required`, or `busy` |
 | `geometra_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.) |
 | `geometra_fill_fields` | Fill labeled text/choice/toggle/file fields in one MCP call; can return final-only status for the smallest responses |
 | `geometra_run_actions` | Execute a batch of high-level actions in one MCP round trip and get one consolidated result, with optional final-only output |
 | `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
-| `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand |
+| `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand, with paging/filtering for long sections |
+| `geometra_reveal` | Scroll until a matching node is visible instead of guessing wheel deltas |
 | `geometra_click` | Click an element by coordinates |
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
@@ -310,8 +311,9 @@ 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
+3. `geometra_reveal` for far-below-fold targets such as submit buttons
+4. `geometra_fill_fields` for obvious field entry
+5. `geometra_run_actions` when you need mixed navigation + waits + field entry
 
 Typical batch:
 
@@ -333,6 +335,13 @@ For the smallest long-form responses, prefer:
 1. `detail: "minimal"` for structured step metadata instead of narrated deltas
 2. `includeSteps: false` when you only need aggregate success/error counts plus the final validation/state payload
 
+For long single-page forms:
+
+1. Use `geometra_expand_section` with `fieldOffset` / `actionOffset` to page through large forms instead of taking a full snapshot.
+2. Add `onlyRequiredFields: true` or `onlyInvalidFields: true` when you want the actionable subset.
+3. Use `contextText` in `geometra_query` / `geometra_wait_for` to disambiguate repeated `Yes` / `No` controls by question text.
+4. Use `geometra_reveal` instead of manual wheel loops when the next target is offscreen.
+
 Typical field fill:
 
 ```json

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

@@ -7,7 +7,7 @@ function node(role, name, options) {
         ...(options?.state ? { state: options.state } : {}),
         ...(options?.validation ? { validation: options.validation } : {}),
         ...(options?.meta ? { meta: options.meta } : {}),
-        bounds: { x: 0, y: 0, width: 120, height: 40 },
+        bounds: options?.bounds ?? { x: 0, y: 0, width: 120, height: 40 },
         path: options?.path ?? [],
         children: options?.children ?? [],
         focusable: role !== 'group',
@@ -204,3 +204,108 @@ describe('batch MCP result shaping', () => {
         expect(final.alerts.length).toBe(1);
     });
 });
+describe('query and reveal tools', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('lets query disambiguate repeated controls by context text', async () => {
+        const handler = getToolHandler('geometra_query');
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 900 },
+            children: [
+                node('form', 'Application', {
+                    path: [0],
+                    children: [
+                        node('group', undefined, {
+                            path: [0, 0],
+                            children: [
+                                node('text', 'Are you legally authorized to work here?', { path: [0, 0, 0] }),
+                                node('button', 'Yes', { path: [0, 0, 1] }),
+                                node('button', 'No', { path: [0, 0, 2] }),
+                            ],
+                        }),
+                        node('group', undefined, {
+                            path: [0, 1],
+                            children: [
+                                node('text', 'Will you require sponsorship?', { path: [0, 1, 0] }),
+                                node('button', 'Yes', { path: [0, 1, 1] }),
+                                node('button', 'No', { path: [0, 1, 2] }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const result = await handler({
+            role: 'button',
+            name: 'Yes',
+            contextText: 'sponsorship',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toHaveLength(1);
+        expect(payload[0]).toMatchObject({
+            role: 'button',
+            name: 'Yes',
+            context: {
+                prompt: 'Will you require sponsorship?',
+                section: 'Application',
+            },
+        });
+    });
+    it('reveals an offscreen target with semantic scrolling instead of requiring manual wheels', async () => {
+        const handler = getToolHandler('geometra_reveal');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('form', 'Application', {
+                    bounds: { x: 20, y: -200, width: 760, height: 1900 },
+                    path: [0],
+                    children: [
+                        node('button', 'Submit application', {
+                            bounds: { x: 60, y: 1540, width: 180, height: 40 },
+                            path: [0, 0],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        mockState.sendWheel.mockImplementationOnce(async () => {
+            mockState.currentA11yRoot = node('group', undefined, {
+                bounds: { x: 0, y: 0, width: 1280, height: 800 },
+                meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 1220 },
+                children: [
+                    node('form', 'Application', {
+                        bounds: { x: 20, y: -1420, width: 760, height: 1900 },
+                        path: [0],
+                        children: [
+                            node('button', 'Submit application', {
+                                bounds: { x: 60, y: 320, width: 180, height: 40 },
+                                path: [0, 0],
+                            }),
+                        ],
+                    }),
+                ],
+            });
+            return { status: 'updated', timeoutMs: 2500 };
+        });
+        const result = await handler({
+            role: 'button',
+            name: 'Submit application',
+            maxSteps: 3,
+            fullyVisible: true,
+            timeoutMs: 2500,
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(mockState.sendWheel).toHaveBeenCalledWith(mockState.session, expect.any(Number), expect.objectContaining({ x: expect.any(Number), y: expect.any(Number) }), 2500);
+        expect(payload).toMatchObject({
+            revealed: true,
+            attempts: 1,
+            target: {
+                role: 'button',
+                name: 'Submit application',
+                visibility: { fullyVisible: true },
+            },
+        });
+    });
+});

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

@@ -115,17 +115,117 @@ describe('buildPageModel', () => {
             summary: {
                 headingCount: 1,
                 fieldCount: 2,
+                requiredFieldCount: 2,
+                invalidFieldCount: 1,
                 actionCount: 1,
             },
+            page: {
+                fields: { offset: 0, returned: 2, total: 2, hasMore: false },
+                actions: { offset: 0, returned: 1, total: 1, hasMore: false },
+            },
         });
         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?.fields[1]?.visibility).toMatchObject({ intersectsViewport: true, fullyVisible: true });
+        expect(detail?.actions[0]?.scrollHint).toMatchObject({ status: 'visible' });
         expect(detail?.actions.map(action => action.id)).toEqual(['n:0.0.3']);
         expect(detail?.fields[0]).not.toHaveProperty('bounds');
     });
+    it('paginates long sections and carries context on repeated answers', () => {
+        const tree = node('group', undefined, { x: 0, y: 0, width: 900, height: 700 }, {
+            children: [
+                node('form', 'Application', { x: 20, y: -120, width: 760, height: 1800 }, {
+                    path: [0],
+                    children: [
+                        node('heading', 'Application', { x: 40, y: 40, width: 240, height: 28 }, { path: [0, 0] }),
+                        node('textbox', 'Full name', { x: 48, y: 120, width: 320, height: 36 }, {
+                            path: [0, 1],
+                            state: { required: true },
+                        }),
+                        node('textbox', 'Email', { x: 48, y: 176, width: 320, height: 36 }, {
+                            path: [0, 2],
+                            state: { required: true, invalid: true },
+                            validation: { error: 'Enter a valid email.' },
+                        }),
+                        node('textbox', 'Phone', { x: 48, y: 232, width: 320, height: 36 }, {
+                            path: [0, 3],
+                            state: { required: true },
+                        }),
+                        node('group', undefined, { x: 40, y: 980, width: 520, height: 96 }, {
+                            path: [0, 4],
+                            children: [
+                                node('text', 'Are you legally authorized to work here?', { x: 48, y: 980, width: 340, height: 24 }, {
+                                    path: [0, 4, 0],
+                                }),
+                                node('button', 'Yes', { x: 48, y: 1020, width: 88, height: 40 }, {
+                                    path: [0, 4, 1],
+                                    focusable: true,
+                                }),
+                                node('button', 'No', { x: 148, y: 1020, width: 88, height: 40 }, {
+                                    path: [0, 4, 2],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                        node('group', undefined, { x: 40, y: 1120, width: 520, height: 96 }, {
+                            path: [0, 5],
+                            children: [
+                                node('text', 'Will you require sponsorship?', { x: 48, y: 1120, width: 260, height: 24 }, {
+                                    path: [0, 5, 0],
+                                }),
+                                node('button', 'Yes', { x: 48, y: 1160, width: 88, height: 40 }, {
+                                    path: [0, 5, 1],
+                                    focusable: true,
+                                }),
+                                node('button', 'No', { x: 148, y: 1160, width: 88, height: 40 }, {
+                                    path: [0, 5, 2],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                        node('button', 'Submit application', { x: 48, y: 1540, width: 180, height: 40 }, {
+                            path: [0, 6],
+                            focusable: true,
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const detail = expandPageSection(tree, 'fm:0', {
+            maxFields: 2,
+            fieldOffset: 1,
+            onlyRequiredFields: true,
+        });
+        expect(detail).toMatchObject({
+            summary: {
+                fieldCount: 3,
+                requiredFieldCount: 3,
+                invalidFieldCount: 1,
+                actionCount: 5,
+            },
+            page: {
+                fields: { offset: 1, returned: 2, total: 3, hasMore: false },
+                actions: { offset: 0, returned: 5, total: 5, hasMore: false },
+            },
+        });
+        expect(detail?.fields.map(field => field.name)).toEqual(['Email', 'Phone']);
+        expect(detail?.fields[0]?.scrollHint).toMatchObject({ status: 'visible' });
+        const authorizedYes = detail?.actions.find(action => action.name === 'Yes' && action.context?.prompt === 'Are you legally authorized to work here?');
+        const sponsorshipYes = detail?.actions.find(action => action.name === 'Yes' && action.context?.prompt === 'Will you require sponsorship?');
+        expect(authorizedYes).toMatchObject({
+            name: 'Yes',
+            context: { prompt: 'Are you legally authorized to work here?', section: 'Application' },
+            visibility: { fullyVisible: false, offscreenBelow: true },
+        });
+        expect(sponsorshipYes).toMatchObject({
+            name: 'Yes',
+            context: { prompt: 'Will you require sponsorship?', section: 'Application' },
+            visibility: { fullyVisible: false, offscreenBelow: true },
+        });
+    });
     it('drops noisy container names and falls back to unnamed summaries', () => {
         const tree = node('group', undefined, { x: 0, y: 0, width: 800, height: 600 }, {
             children: [

package/dist/server.d.ts

@@ -6,6 +6,7 @@ interface NodeFilter {
     role?: string;
     name?: string;
     text?: string;
+    contextText?: string;
     value?: string;
     checked?: NodeStateFilterValue;
     disabled?: boolean;

package/dist/server.js

@@ -21,6 +21,7 @@ function nodeFilterShape() {
         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)'),
+        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated controls with the same visible name'),
         value: z.string().optional().describe('Displayed / current field value to match (substring match)'),
         checked: checkedStateInput(),
         disabled: z.boolean().optional().describe('Match disabled state'),
@@ -213,7 +214,7 @@ 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.`, nodeFilterShape(), async ({ id, role, name, text, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
+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, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -223,6 +224,7 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
             role,
             name,
             text,
+            contextText,
             value,
             checked,
             disabled,
@@ -234,12 +236,12 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
             busy,
         };
         if (!hasNodeFilter(filter))
-            return err('Provide at least one query filter (id, role, name, text, value, or state)');
+            return err('Provide at least one query filter (id, role, name, text, contextText, value, or state)');
         const matches = findNodes(a11y, filter);
         if (matches.length === 0) {
             return ok(`No elements found matching ${JSON.stringify(filter)}`);
         }
-        const result = matches.map(node => formatNode(node, a11y.bounds));
+        const result = sortA11yNodes(matches).map(node => formatNode(node, a11y, a11y.bounds));
         return ok(JSON.stringify(result, null, 2));
     });
     server.tool('geometra_wait_for', `Wait for a semantic UI condition without guessing sleep durations. Use this for slow SPA transitions, resume parsing, custom validation alerts, disabled submit buttons, and value/state confirmation before submit.
@@ -255,7 +257,7 @@ 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, invalid, required, busy, present, timeoutMs }) => {
+    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -264,6 +266,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             role,
             name,
             text,
+            contextText,
             value,
             checked,
             disabled,
@@ -275,7 +278,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             busy,
         };
         if (!hasNodeFilter(filter))
-            return err('Provide at least one wait filter (id, role, name, text, value, or state)');
+            return err('Provide at least one wait filter (id, role, name, text, contextText, value, or state)');
         const matchesCondition = () => {
             if (!session.tree || !session.layout)
                 return false;
@@ -296,7 +299,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
         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));
+        const result = sortA11yNodes(matches).slice(0, 8).map(node => formatNode(node, after, 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.
@@ -439,12 +442,18 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
         id: z.string().describe('Section id from geometra_page_model, e.g. fm:1.0 or ls:2.1'),
         maxHeadings: z.number().int().min(1).max(20).optional().default(6).describe('Cap heading rows'),
         maxFields: z.number().int().min(1).max(40).optional().default(18).describe('Cap field rows'),
+        fieldOffset: z.number().int().min(0).optional().default(0).describe('Field row offset for long forms'),
+        onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields'),
+        onlyInvalidFields: z.boolean().optional().default(false).describe('Only include invalid fields'),
         maxActions: z.number().int().min(1).max(30).optional().default(12).describe('Cap action rows'),
+        actionOffset: z.number().int().min(0).optional().default(0).describe('Action row offset'),
         maxLists: z.number().int().min(0).max(20).optional().default(8).describe('Cap nested lists'),
+        listOffset: z.number().int().min(0).optional().default(0).describe('Nested-list offset'),
         maxItems: z.number().int().min(0).max(50).optional().default(20).describe('Cap list items'),
+        itemOffset: z.number().int().min(0).optional().default(0).describe('List-item offset'),
         maxTextPreview: z.number().int().min(0).max(20).optional().default(6).describe('Cap text preview lines'),
         includeBounds: z.boolean().optional().default(false).describe('Include bounds for fields/actions/headings/items'),
-    }, async ({ id, maxHeadings, maxFields, maxActions, maxLists, maxItems, maxTextPreview, includeBounds }) => {
+    }, async ({ id, maxHeadings, maxFields, fieldOffset, onlyRequiredFields, onlyInvalidFields, maxActions, actionOffset, maxLists, listOffset, maxItems, itemOffset, maxTextPreview, includeBounds, }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -452,9 +461,15 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
         const detail = expandPageSection(a11y, id, {
             maxHeadings,
             maxFields,
+            fieldOffset,
+            onlyRequiredFields,
+            onlyInvalidFields,
             maxActions,
+            actionOffset,
             maxLists,
+            listOffset,
             maxItems,
+            itemOffset,
             maxTextPreview,
             includeBounds,
         });
@@ -462,6 +477,90 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
             return err(`No expandable section found for id ${id}`);
         return ok(JSON.stringify(detail));
     });
+    server.tool('geometra_reveal', `Scroll until a matching node is revealed. This is the generic alternative to trial-and-error wheel calls on long forms.
+
+Use the same filters as geometra_query, plus an optional match index when repeated controls share the same visible label.`, {
+        ...nodeFilterShape(),
+        index: z.number().int().min(0).optional().default(0).describe('Which matching node to reveal after sorting top-to-bottom'),
+        fullyVisible: z.boolean().optional().default(true).describe('Require the target to become fully visible (default true)'),
+        maxSteps: z.number().int().min(1).max(12).optional().default(6).describe('Maximum reveal attempts before returning an error'),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .default(2_500)
+            .describe('Per-scroll wait timeout (default 2500ms)'),
+    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxSteps, timeoutMs }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const matchIndex = index ?? 0;
+        const requireFullyVisible = fullyVisible ?? true;
+        const revealSteps = maxSteps ?? 6;
+        const waitTimeout = timeoutMs ?? 2_500;
+        const filter = {
+            id,
+            role,
+            name,
+            text,
+            contextText,
+            value,
+            checked,
+            disabled,
+            focused,
+            selected,
+            expanded,
+            invalid,
+            required,
+            busy,
+        };
+        if (!hasNodeFilter(filter))
+            return err('Provide at least one reveal filter (id, role, name, text, contextText, value, or state)');
+        let attempts = 0;
+        while (attempts <= revealSteps) {
+            const a11y = sessionA11y(session);
+            if (!a11y)
+                return err('No UI tree available to reveal from');
+            const matches = sortA11yNodes(findNodes(a11y, filter));
+            if (matches.length === 0) {
+                return err(`No elements found matching ${JSON.stringify(filter)}`);
+            }
+            if (matchIndex >= matches.length) {
+                return err(`Requested reveal index ${matchIndex} but only ${matches.length} matching element(s) were found`);
+            }
+            const target = matches[matchIndex];
+            const formatted = formatNode(target, a11y, a11y.bounds);
+            const visible = requireFullyVisible ? formatted.visibility.fullyVisible : formatted.visibility.intersectsViewport;
+            if (visible) {
+                return ok(JSON.stringify({
+                    revealed: true,
+                    attempts,
+                    target: formatted,
+                }, null, 2));
+            }
+            if (attempts === revealSteps) {
+                return err(JSON.stringify({
+                    revealed: false,
+                    attempts,
+                    target: formatted,
+                }, null, 2));
+            }
+            const deltaX = clamp(formatted.scrollHint.revealDeltaX, -Math.round(a11y.bounds.width * 0.75), Math.round(a11y.bounds.width * 0.75));
+            let deltaY = clamp(formatted.scrollHint.revealDeltaY, -Math.round(a11y.bounds.height * 0.85), Math.round(a11y.bounds.height * 0.85));
+            if (deltaY === 0 && !formatted.visibility.fullyVisible) {
+                deltaY = formatted.visibility.offscreenAbove ? -Math.round(a11y.bounds.height * 0.4) : Math.round(a11y.bounds.height * 0.4);
+            }
+            await sendWheel(session, deltaY, {
+                deltaX,
+                x: formatted.center.x,
+                y: formatted.center.y,
+            }, waitTimeout);
+            attempts++;
+        }
+        return err(`Failed to reveal ${JSON.stringify(filter)}`);
+    });
     // ── click ────────────────────────────────────────────────────
     server.tool('geometra_click', `Click an element in the Geometra UI. Provide either the element's bounds (from geometra_query) or raw x,y coordinates. The click is dispatched server-side via the geometry protocol — no browser, no simulated DOM events.
 
@@ -1111,6 +1210,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 role: action.role,
                 name: action.name,
                 text: action.text,
+                contextText: action.contextText,
                 value: action.value,
                 checked: action.checked,
                 disabled: action.disabled,
@@ -1162,7 +1262,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             const matches = findNodes(after, filter);
             if (detail === 'verbose') {
                 return {
-                    summary: JSON.stringify(matches.slice(0, 8).map(node => formatNode(node, after.bounds)), null, 2),
+                    summary: JSON.stringify(sortA11yNodes(matches).slice(0, 8).map(node => formatNode(node, after, after.bounds)), null, 2),
                     compact: {
                         present,
                         elapsedMs,
@@ -1287,7 +1387,96 @@ function textMatches(haystack, needle) {
         return false;
     return haystack.toLowerCase().includes(needle.toLowerCase());
 }
-function nodeMatchesFilter(node, filter) {
+function sortA11yNodes(nodes) {
+    return [...nodes].sort((a, b) => {
+        if (a.bounds.y !== b.bounds.y)
+            return a.bounds.y - b.bounds.y;
+        if (a.bounds.x !== b.bounds.x)
+            return a.bounds.x - b.bounds.x;
+        return a.path.length - b.path.length;
+    });
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function pathStartsWith(path, prefix) {
+    if (prefix.length > path.length)
+        return false;
+    for (let index = 0; index < prefix.length; index++) {
+        if (path[index] !== prefix[index])
+            return false;
+    }
+    return true;
+}
+function namedAncestors(root, path) {
+    const out = [];
+    let current = root;
+    for (const index of path) {
+        out.push(current);
+        if (!current.children[index])
+            break;
+        current = current.children[index];
+    }
+    return out;
+}
+function collectDescendants(node, predicate) {
+    const out = [];
+    function walk(current) {
+        for (const child of current.children) {
+            if (predicate(child))
+                out.push(child);
+            walk(child);
+        }
+    }
+    walk(node);
+    return out;
+}
+function promptContext(root, node) {
+    const ancestors = namedAncestors(root, node.path);
+    const normalizedName = (node.name ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        const grouped = collectDescendants(ancestor, candidate => candidate.role === 'button' || candidate.role === 'radio' || candidate.role === 'checkbox').length >= 2;
+        if (!grouped && ancestor.role !== 'group' && ancestor.role !== 'form' && ancestor.role !== 'dialog')
+            continue;
+        const best = collectDescendants(ancestor, candidate => (candidate.role === 'heading' || candidate.role === 'text') &&
+            !!truncateInlineText(candidate.name, 120) &&
+            !pathStartsWith(candidate.path, node.path))
+            .filter(candidate => candidate.bounds.y <= node.bounds.y + 8)
+            .map(candidate => {
+            const text = truncateInlineText(candidate.name, 120);
+            if (!text)
+                return null;
+            if (text.toLowerCase() === normalizedName)
+                return null;
+            const dy = Math.max(0, node.bounds.y - candidate.bounds.y);
+            const dx = Math.abs(node.bounds.x - candidate.bounds.x);
+            const headingBonus = candidate.role === 'heading' ? -32 : 0;
+            return { text, score: dy * 4 + dx + headingBonus };
+        })
+            .filter((candidate) => !!candidate)
+            .sort((a, b) => a.score - b.score)[0];
+        if (best?.text)
+            return best.text;
+    }
+    return undefined;
+}
+function sectionContext(root, node) {
+    const ancestors = namedAncestors(root, node.path);
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        if (ancestor.role === 'form' || ancestor.role === 'dialog' || ancestor.role === 'main' || ancestor.role === 'navigation' || ancestor.role === 'region') {
+            const name = truncateInlineText(ancestor.name, 80);
+            if (name)
+                return name;
+        }
+    }
+    return undefined;
+}
+function nodeContextText(root, node) {
+    return [promptContext(root, node), sectionContext(root, node)].filter(Boolean).join(' | ') || undefined;
+}
+function nodeMatchesFilter(node, filter, contextText) {
     if (filter.id && nodeIdForPath(node.path) !== filter.id)
         return false;
     if (filter.role && node.role !== filter.role)
@@ -1299,6 +1488,8 @@ function nodeMatchesFilter(node, filter) {
     if (filter.text &&
         !textMatches(`${node.name ?? ''} ${node.value ?? ''} ${node.validation?.error ?? ''} ${node.validation?.description ?? ''}`.trim(), filter.text))
         return false;
+    if (!textMatches(contextText, filter.contextText))
+        return false;
     if (filter.checked !== undefined && node.state?.checked !== filter.checked)
         return false;
     if (filter.disabled !== undefined && (node.state?.disabled ?? false) !== filter.disabled)
@@ -1320,7 +1511,8 @@ function nodeMatchesFilter(node, filter) {
 export function findNodes(node, filter) {
     const matches = [];
     function walk(n) {
-        if (nodeMatchesFilter(n, filter) && hasNodeFilter(filter))
+        const contextText = filter.contextText ? nodeContextText(node, n) : undefined;
+        if (nodeMatchesFilter(n, filter, contextText) && hasNodeFilter(filter))
             matches.push(n);
         for (const child of n.children)
             walk(child);
@@ -1345,7 +1537,7 @@ function summarizeFieldLabelState(session, fieldLabel) {
         parts.push(`error=${JSON.stringify(payload.error)}`);
     return parts.join(' ');
 }
-function formatNode(node, viewport) {
+function formatNode(node, root, viewport) {
     const visibleLeft = Math.max(0, node.bounds.x);
     const visibleTop = Math.max(0, node.bounds.y);
     const visibleRight = Math.min(viewport.width, node.bounds.x + node.bounds.width);
@@ -1363,11 +1555,14 @@ function formatNode(node, viewport) {
         : Math.round(Math.min(Math.max(node.bounds.y + node.bounds.height / 2, 0), viewport.height));
     const revealDeltaX = Math.round(node.bounds.x + node.bounds.width / 2 - viewport.width / 2);
     const revealDeltaY = Math.round(node.bounds.y + node.bounds.height / 2 - viewport.height / 2);
+    const prompt = promptContext(root, node);
+    const section = sectionContext(root, node);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         name: node.name,
         ...(node.value ? { value: node.value } : {}),
+        ...(prompt || section ? { context: { ...(prompt ? { prompt } : {}), ...(section ? { section } : {}) } } : {}),
         bounds: node.bounds,
         visibleBounds: {
             x: visibleLeft,

package/dist/session.d.ts

@@ -61,6 +61,23 @@ export interface CompactUiContext {
     scrollY?: number;
     focusedNode?: CompactUiNode;
 }
+export interface NodeContextModel {
+    prompt?: string;
+    section?: string;
+}
+export interface NodeVisibilityModel {
+    intersectsViewport: boolean;
+    fullyVisible: boolean;
+    offscreenAbove: boolean;
+    offscreenBelow: boolean;
+    offscreenLeft: boolean;
+    offscreenRight: boolean;
+}
+export interface NodeScrollHintModel {
+    status: 'visible' | 'partial' | 'offscreen';
+    revealDeltaX: number;
+    revealDeltaY: number;
+}
 export type PageSectionKind = 'landmark' | 'form' | 'dialog' | 'list';
 export type PageArchetype = 'shell' | 'form' | 'dialog' | 'results' | 'content' | 'dashboard';
 interface PageSectionSummaryBase {
@@ -136,6 +153,9 @@ export interface PageFieldModel {
     value?: string;
     state?: A11yNode['state'];
     validation?: A11yNode['validation'];
+    context?: NodeContextModel;
+    visibility?: NodeVisibilityModel;
+    scrollHint?: NodeScrollHintModel;
     bounds?: {
         x: number;
         y: number;
@@ -148,6 +168,9 @@ export interface PageActionModel {
     role: string;
     name?: string;
     state?: A11yNode['state'];
+    context?: NodeContextModel;
+    visibility?: NodeVisibilityModel;
+    scrollHint?: NodeScrollHintModel;
     bounds?: {
         x: number;
         y: number;
@@ -179,10 +202,38 @@ export interface PageSectionDetail {
     summary: {
         headingCount: number;
         fieldCount: number;
+        requiredFieldCount: number;
+        invalidFieldCount: number;
         actionCount: number;
         listCount: number;
         itemCount: number;
     };
+    page: {
+        fields: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+        actions: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+        lists: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+        items: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+    };
     headings: PageHeadingModel[];
     fields: PageFieldModel[];
     actions: PageActionModel[];
@@ -368,9 +419,15 @@ export declare function buildPageModel(root: A11yNode, options?: {
 export declare function expandPageSection(root: A11yNode, id: string, options?: {
     maxHeadings?: number;
     maxFields?: number;
+    fieldOffset?: number;
+    onlyRequiredFields?: boolean;
+    onlyInvalidFields?: boolean;
     maxActions?: number;
+    actionOffset?: number;
     maxLists?: number;
+    listOffset?: number;
     maxItems?: number;
+    itemOffset?: number;
     maxTextPreview?: number;
     includeBounds?: boolean;
 }): PageSectionDetail | null;

package/dist/session.js

@@ -743,8 +743,103 @@ function primaryAction(node) {
         bounds: cloneBounds(node.bounds),
     };
 }
-function toFieldModel(node, includeBounds = true) {
+function buildVisibility(bounds, viewport) {
+    const visibleLeft = Math.max(0, bounds.x);
+    const visibleTop = Math.max(0, bounds.y);
+    const visibleRight = Math.min(viewport.width, bounds.x + bounds.width);
+    const visibleBottom = Math.min(viewport.height, bounds.y + bounds.height);
+    const hasVisibleIntersection = visibleRight > visibleLeft && visibleBottom > visibleTop;
+    const fullyVisible = bounds.x >= 0 &&
+        bounds.y >= 0 &&
+        bounds.x + bounds.width <= viewport.width &&
+        bounds.y + bounds.height <= viewport.height;
+    return {
+        intersectsViewport: hasVisibleIntersection,
+        fullyVisible,
+        offscreenAbove: bounds.y + bounds.height <= 0,
+        offscreenBelow: bounds.y >= viewport.height,
+        offscreenLeft: bounds.x + bounds.width <= 0,
+        offscreenRight: bounds.x >= viewport.width,
+    };
+}
+function buildScrollHint(bounds, viewport) {
+    const visibility = buildVisibility(bounds, viewport);
+    return {
+        status: visibility.fullyVisible ? 'visible' : visibility.intersectsViewport ? 'partial' : 'offscreen',
+        revealDeltaX: Math.round(bounds.x + bounds.width / 2 - viewport.width / 2),
+        revealDeltaY: Math.round(bounds.y + bounds.height / 2 - viewport.height / 2),
+    };
+}
+function ancestorNodes(root, path) {
+    const out = [];
+    let current = root;
+    for (const index of path) {
+        out.push(current);
+        if (!current.children[index])
+            break;
+        current = current.children[index];
+    }
+    return out;
+}
+function countGroupedChoiceControls(node) {
+    return collectDescendants(node, candidate => candidate.role === 'radio' || candidate.role === 'checkbox' || candidate.role === 'button').length;
+}
+function nearestPromptText(container, target) {
+    const candidates = collectDescendants(container, candidate => (candidate.role === 'heading' || candidate.role === 'text') &&
+        !!sanitizeInlineName(candidate.name, 120) &&
+        pathKey(candidate.path) !== pathKey(target.path));
+    const normalizedTarget = normalizeUiText(target.name ?? '');
+    const best = candidates
+        .filter(candidate => candidate.bounds.y <= target.bounds.y + 8)
+        .map(candidate => {
+        const text = sanitizeInlineName(candidate.name, 120);
+        if (!text)
+            return null;
+        if (normalizeUiText(text) === normalizedTarget)
+            return null;
+        const dy = Math.max(0, target.bounds.y - candidate.bounds.y);
+        const dx = Math.abs(target.bounds.x - candidate.bounds.x);
+        const headingBonus = candidate.role === 'heading' ? -32 : 0;
+        return { text, score: dy * 4 + dx + headingBonus };
+    })
+        .filter((candidate) => !!candidate)
+        .sort((a, b) => a.score - b.score)[0];
+    return best?.text;
+}
+function nodeContext(root, node) {
+    const ancestors = ancestorNodes(root, node.path);
+    let prompt;
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        const grouped = countGroupedChoiceControls(ancestor) >= 2;
+        if (grouped || ancestor.role === 'group' || ancestor.role === 'form' || ancestor.role === 'dialog') {
+            prompt = nearestPromptText(ancestor, node);
+            if (prompt)
+                break;
+        }
+    }
+    let section;
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        const kind = sectionKindForNode(ancestor);
+        if (!kind)
+            continue;
+        section = sectionDisplayName(ancestor, kind);
+        if (section)
+            break;
+    }
+    if (!prompt && !section)
+        return undefined;
+    return {
+        ...(prompt ? { prompt } : {}),
+        ...(section ? { section } : {}),
+    };
+}
+function toFieldModel(root, node, includeBounds = true) {
     const value = sanitizeInlineName(node.value, 120);
+    const context = nodeContext(root, node);
+    const visibility = buildVisibility(node.bounds, root.bounds);
+    const scrollHint = buildScrollHint(node.bounds, root.bounds);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
@@ -752,15 +847,24 @@ function toFieldModel(node, includeBounds = true) {
         ...(value ? { value } : {}),
         ...(cloneState(node.state) ? { state: cloneState(node.state) } : {}),
         ...(cloneValidation(node.validation) ? { validation: cloneValidation(node.validation) } : {}),
+        ...(context ? { context } : {}),
+        visibility,
+        scrollHint,
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
 }
-function toActionModel(node, includeBounds = true) {
+function toActionModel(root, node, includeBounds = true) {
+    const context = nodeContext(root, node);
+    const visibility = buildVisibility(node.bounds, root.bounds);
+    const scrollHint = buildScrollHint(node.bounds, root.bounds);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         ...(sanitizeInlineName(node.name, 80) ? { name: sanitizeInlineName(node.name, 80) } : {}),
         ...(cloneState(node.state) ? { state: cloneState(node.state) } : {}),
+        ...(context ? { context } : {}),
+        visibility,
+        scrollHint,
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
 }
@@ -931,9 +1035,15 @@ export function expandPageSection(root, id, options) {
         return null;
     const maxHeadings = options?.maxHeadings ?? 6;
     const maxFields = options?.maxFields ?? 18;
+    const fieldOffset = Math.max(0, options?.fieldOffset ?? 0);
+    const onlyRequiredFields = options?.onlyRequiredFields ?? false;
+    const onlyInvalidFields = options?.onlyInvalidFields ?? false;
     const maxActions = options?.maxActions ?? 12;
+    const actionOffset = Math.max(0, options?.actionOffset ?? 0);
     const maxLists = options?.maxLists ?? 8;
+    const listOffset = Math.max(0, options?.listOffset ?? 0);
     const maxItems = options?.maxItems ?? 20;
+    const itemOffset = Math.max(0, options?.itemOffset ?? 0);
     const maxTextPreview = options?.maxTextPreview ?? 6;
     const includeBounds = options?.includeBounds ?? false;
     const headingsAll = sortByBounds(collectDescendants(node, candidate => candidate.role === 'heading' && !!sanitizeInlineName(candidate.name, 80)));
@@ -943,6 +1053,19 @@ export function expandPageSection(root, id, options) {
     const itemsAll = actualKind === 'list'
         ? sortByBounds(collectDescendants(node, candidate => candidate.role === 'listitem'))
         : [];
+    const requiredFieldCount = fieldsAll.filter(field => field.state?.required).length;
+    const invalidFieldCount = fieldsAll.filter(field => field.state?.invalid).length;
+    const filteredFields = fieldsAll.filter(field => {
+        if (onlyRequiredFields && !field.state?.required)
+            return false;
+        if (onlyInvalidFields && !field.state?.invalid)
+            return false;
+        return true;
+    });
+    const pageFields = filteredFields.slice(fieldOffset, fieldOffset + maxFields);
+    const pageActions = actionsAll.slice(actionOffset, actionOffset + maxActions);
+    const pageLists = nestedListsAll.slice(listOffset, listOffset + maxLists);
+    const pageItems = itemsAll.slice(itemOffset, itemOffset + maxItems);
     const name = sectionDisplayName(node, actualKind);
     return {
         id: sectionIdForPath(actualKind, node.path),
@@ -953,15 +1076,49 @@ export function expandPageSection(root, id, options) {
         summary: {
             headingCount: headingsAll.length,
             fieldCount: fieldsAll.length,
+            requiredFieldCount,
+            invalidFieldCount,
             actionCount: actionsAll.length,
             listCount: nestedListsAll.length,
             itemCount: itemsAll.length,
         },
+        page: {
+            fields: {
+                offset: fieldOffset,
+                returned: pageFields.length,
+                total: filteredFields.length,
+                hasMore: fieldOffset + pageFields.length < filteredFields.length,
+            },
+            actions: {
+                offset: actionOffset,
+                returned: pageActions.length,
+                total: actionsAll.length,
+                hasMore: actionOffset + pageActions.length < actionsAll.length,
+            },
+            lists: {
+                offset: listOffset,
+                returned: pageLists.length,
+                total: nestedListsAll.length,
+                hasMore: listOffset + pageLists.length < nestedListsAll.length,
+            },
+            items: {
+                offset: itemOffset,
+                returned: pageItems.length,
+                total: itemsAll.length,
+                hasMore: itemOffset + pageItems.length < itemsAll.length,
+            },
+        },
         headings: headingModels(node, maxHeadings, includeBounds),
-        fields: fieldsAll.slice(0, maxFields).map(field => toFieldModel(field, includeBounds)),
-        actions: actionsAll.slice(0, maxActions).map(action => toActionModel(action, includeBounds)),
-        lists: nestedListSummaries(node, maxLists, node.path),
-        items: itemsAll.slice(0, maxItems).map(item => ({
+        fields: pageFields.map(field => toFieldModel(root, field, includeBounds)),
+        actions: pageActions.map(action => toActionModel(root, action, includeBounds)),
+        lists: pageLists.map(list => ({
+            id: sectionIdForPath('list', list.path),
+            role: list.role,
+            ...(sectionDisplayName(list, 'list') ? { name: sectionDisplayName(list, 'list') } : {}),
+            bounds: cloneBounds(list.bounds),
+            itemCount: collectDescendants(list, candidate => candidate.role === 'listitem').length,
+        })),
+        items: pageItems.map(item => ({
             id: nodeIdForPath(item.path),
             ...(listItemName(item) ? { name: listItemName(item) } : {}),
             ...(includeBounds ? { bounds: cloneBounds(item.bounds) } : {}),

package/package.json

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