@geometra/mcp 1.19.22 → 1.20.0

package/dist/server.js

@@ -1,8 +1,9 @@
 import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
-import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { connect, connectThroughProxy, disconnect, getSession, prewarmProxy, sendClick, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -11,10 +12,10 @@ function checkedStateInput() {
 }
 function detailInput() {
     return z
-        .enum(['minimal', 'verbose'])
+        .enum(['terse', 'minimal', 'verbose'])
         .optional()
         .default('minimal')
-        .describe('`minimal` (default) returns terse action summaries. Use `verbose` for a fuller current-UI fallback.');
+        .describe('`terse` returns compact machine-friendly JSON. `minimal` (default) returns short human-readable summaries. `verbose` adds fuller fallback context.');
 }
 function formSchemaFormatInput() {
     return z
@@ -23,6 +24,13 @@ function formSchemaFormatInput() {
         .default('compact')
         .describe('`compact` (default) returns readable JSON fields. Use `packed` for the smallest schema payload with short keys.');
 }
+function pageModelModeInput() {
+    return z
+        .enum(['inline', 'deferred'])
+        .optional()
+        .default('inline')
+        .describe('When returnPageModel=true, `inline` includes the full page model in the connect response. `deferred` returns connect as soon as the transport is ready and lets the caller fetch geometra_page_model separately.');
+}
 function formSchemaContextInput() {
     return z
         .enum(['auto', 'always', 'none'])
@@ -37,6 +45,9 @@ function nodeFilterShape() {
         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'),
+        promptText: z.string().optional().describe('Nearby question/prompt text to disambiguate repeated controls or actions'),
+        sectionText: z.string().optional().describe('Containing section/landmark/form/dialog text to disambiguate repeated controls or actions'),
+        itemText: z.string().optional().describe('Nearby card/row/item label to disambiguate repeated actions like “Add to cart” or “Open incident”'),
         value: z.string().optional().describe('Displayed / current field value to match (substring match)'),
         checked: checkedStateInput(),
         disabled: z.boolean().optional().describe('Match disabled state'),
@@ -66,15 +77,22 @@ function waitConditionShape() {
             .describe('Maximum time to wait before returning an error (default 10000ms)'),
     };
 }
-const GEOMETRA_QUERY_FILTER_REQUIRED_MESSAGE = 'Provide at least one filter (id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
+const GEOMETRA_QUERY_FILTER_REQUIRED_MESSAGE = 'Provide at least one filter (id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
     'This tool uses a strict schema: unknown keys are rejected. There is no textGone parameter — use text for substring matching. ' +
     'To wait until text disappears from the UI, use geometra_wait_for with text and present: false, or geometra_wait_for_resume_parse for typical resume “Parsing…” banners.';
-const GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE = 'Provide at least one semantic filter (id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
+const GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE = 'Provide at least one semantic filter (id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
     'This tool uses a strict schema: unknown keys are rejected. There is no textGone parameter — use text with a distinctive substring and present: false to wait until that text is gone ' +
     '(common for “Parsing…”, “Parsing your resume”, or similar). Passing only present/timeoutMs is not enough without a filter.';
 /** Strict input so unknown keys (e.g. textGone) fail parse; empty-filter checks happen in handlers / waitForSemanticCondition. */
-const geometraQueryInputSchema = z.object(nodeFilterShape()).strict();
-const geometraWaitForInputSchema = z.object(waitConditionShape()).strict();
+const geometraQueryInputSchema = z.object({
+    ...nodeFilterShape(),
+    maxResults: z.number().int().min(1).max(50).optional().describe('Optional cap on returned matches; terse mode defaults to 8'),
+    detail: detailInput(),
+}).strict();
+const geometraWaitForInputSchema = z.object({
+    ...waitConditionShape(),
+    detail: detailInput(),
+}).strict();
 /** Same upper bound as geometra_wait_for; resume uploads often need the full minute. */
 const geometraWaitForResumeParseInputSchema = z
     .object({
@@ -271,7 +289,7 @@ export function createServer() {
 
 Use \`url\` (ws://…) only when a Geometra/native server or an already-running proxy is listening. If you accidentally pass \`https://…\` in \`url\`, MCP treats it like \`pageUrl\` and starts the proxy for you.
 
-Chromium opens **visible** by default unless \`headless: true\`. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response.`, {
+Chromium opens **visible** by default unless \`headless: true\`. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response. When connect first-response latency matters more than inlining the page model, pair \`returnPageModel: true\` with \`pageModelMode: "deferred"\` and call \`geometra_page_model\` next.`, {
         url: z
             .string()
             .optional()
@@ -311,6 +329,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .optional()
             .default(false)
             .describe('Include geometra_page_model output in the connect response so exploration can start in one turn.'),
+        pageModelMode: pageModelModeInput(),
         formId: z.string().optional().describe('Optional form id filter when returnForms=true'),
         maxFields: z.number().int().min(1).max(120).optional().default(80).describe('Cap returned fields per form when returnForms=true'),
         onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields when returnForms=true'),
@@ -341,6 +360,10 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             maxPrimaryActions: input.maxPrimaryActions,
             maxSectionsPerKind: input.maxSectionsPerKind,
         };
+        const deferInlinePageModel = input.returnPageModel
+            && input.pageModelMode === 'deferred'
+            && !input.returnForms
+            && input.detail !== 'verbose';
         try {
             if (target.kind === 'proxy') {
                 const session = await connectThroughProxy({
@@ -350,6 +373,8 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     width: input.width,
                     height: input.height,
                     slowMo: input.slowMo,
+                    awaitInitialFrame: deferInlinePageModel ? false : undefined,
+                    eagerInitialExtract: deferInlinePageModel ? true : undefined,
                 });
                 if (input.returnForms) {
                     await stabilizeInlineFormSchemas(session, formSchema);
@@ -361,6 +386,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     detail: input.detail,
                     returnForms: input.returnForms,
                     returnPageModel: input.returnPageModel,
+                    pageModelMode: input.pageModelMode,
                     formSchema,
                     pageModelOptions,
                 }), null, input.detail === 'verbose' ? 2 : undefined));
@@ -368,6 +394,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             const session = await connect(target.wsUrl, {
                 width: input.width,
                 height: input.height,
+                awaitInitialFrame: deferInlinePageModel ? false : undefined,
             });
             if (input.returnForms) {
                 await stabilizeInlineFormSchemas(session, formSchema);
@@ -379,6 +406,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                 detail: input.detail,
                 returnForms: input.returnForms,
                 returnPageModel: input.returnPageModel,
+                pageModelMode: input.pageModelMode,
                 formSchema,
                 pageModelOptions,
             }), null, input.detail === 'verbose' ? 2 : undefined));
@@ -387,6 +415,43 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             return err(`Failed to connect: ${formatConnectFailureMessage(e, target)}`);
         }
     });
+    // ── prepare browser ──────────────────────────────────────────
+    server.tool('geometra_prepare_browser', `Pre-launch and pre-navigate a reusable geometra-proxy browser for a normal web page without creating an active MCP session.
+
+Use this when you can prepare ahead of the user-facing task so the next \`geometra_connect\` or one-call \`geometra_run_actions\` on the same \`pageUrl\` / viewport / headless settings skips the cold browser launch.`, {
+        pageUrl: z
+            .string()
+            .url()
+            .refine(isHttpUrl, 'pageUrl must use http:// or https://')
+            .describe('HTTP(S) page to open and keep warm for the next proxy-backed task.'),
+        port: z
+            .number()
+            .int()
+            .positive()
+            .max(65535)
+            .optional()
+            .describe('Preferred local port for spawned proxy (default: ephemeral OS-assigned port).'),
+        headless: z
+            .boolean()
+            .optional()
+            .describe('Run Chromium headless (default false = visible window).'),
+        width: z.number().int().positive().optional().describe('Viewport width for the warmed browser.'),
+        height: z.number().int().positive().optional().describe('Viewport height for the warmed browser.'),
+        slowMo: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Playwright slowMo (ms) for the warmed browser.'),
+    }, async ({ pageUrl, port, headless, width, height, slowMo }) => {
+        try {
+            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo });
+            return ok(JSON.stringify(prepared));
+        }
+        catch (e) {
+            return err(`Failed to prepare browser: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     // ── query ────────────────────────────────────────────────────
     server.registerTool('geometra_query', {
         description: `Find elements in the current Geometra UI by stable id, role, name, text content, current value, or semantic state. Returns matching elements with their exact pixel bounds {x, y, width, height}, visible in-viewport bounds, an on-screen center point, visibility / scroll-reveal hints, role, name, value, state, and tree path.
@@ -395,11 +460,11 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
 
 Unknown parameter names are rejected (strict schema). To wait until visible text goes away (e.g. a parsing banner), use geometra_wait_for with that substring in text and present: false — there is no textGone field.`,
         inputSchema: geometraQueryInputSchema,
-    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
+    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, maxResults, detail }) => {
         const session = getSession();
-        if (!session?.tree || !session?.layout)
+        if (!session)
             return err('Not connected. Call geometra_connect first.');
-        const a11y = sessionA11y(session);
+        const a11y = await sessionA11yWhenReady(session);
         if (!a11y)
             return err('No UI tree available');
         const filter = {
@@ -408,6 +473,9 @@ Unknown parameter names are rejected (strict schema). To wait until visible text
             name,
             text,
             contextText,
+            promptText,
+            sectionText,
+            itemText,
             value,
             checked,
             disabled,
@@ -422,19 +490,70 @@ Unknown parameter names are rejected (strict schema). To wait until visible text
             return err(GEOMETRA_QUERY_FILTER_REQUIRED_MESSAGE);
         const matches = findNodes(a11y, filter);
         if (matches.length === 0) {
+            if (detail === 'terse') {
+                return ok(JSON.stringify({ matchCount: 0, filter: compactFilterPayload(filter) }));
+            }
             return ok(`No elements found matching ${JSON.stringify(filter)}`);
         }
-        const result = sortA11yNodes(matches).map(node => formatNode(node, a11y, a11y.bounds));
+        const formatted = sortA11yNodes(matches).map(node => formatNode(node, a11y, a11y.bounds));
+        if (detail === 'terse') {
+            const limited = formatted.slice(0, maxResults ?? 8);
+            return ok(JSON.stringify({
+                matchCount: formatted.length,
+                matches: limited.map(compactFormattedNode),
+            }));
+        }
+        const result = typeof maxResults === 'number' ? formatted.slice(0, maxResults) : formatted;
         return ok(JSON.stringify(result, null, 2));
     });
+    server.tool('geometra_find_action', `Resolve a clickable action by action label plus optional section, prompt, or item/card text. This is a narrower, lower-token path for repeated actions like "Open incident" in a queue row or "Add to cart" inside a product card.
+
+Use this when geometra_page_model tells you the page shape, but you want one direct semantic action target instead of expanding a whole section.`, {
+        name: z.string().describe('Action label / accessible name to match'),
+        role: z.enum(['button', 'link']).optional().describe('Optional action role hint (button or link)'),
+        sectionText: z.string().optional().describe('Containing section/landmark/form/dialog text to disambiguate repeated actions'),
+        promptText: z.string().optional().describe('Nearby question/prompt text to disambiguate repeated actions'),
+        itemText: z.string().optional().describe('Nearby card/row/item label to disambiguate repeated actions'),
+        maxResults: z.number().int().min(1).max(12).optional().default(6).describe('Maximum number of matches to return'),
+        detail: detailInput(),
+    }, async ({ name, role, sectionText, promptText, itemText, maxResults, detail }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const a11y = await sessionA11yWhenReady(session);
+        if (!a11y)
+            return err('No UI tree available');
+        const filter = {
+            ...(role ? { role } : {}),
+            name,
+            ...(sectionText ? { sectionText } : {}),
+            ...(promptText ? { promptText } : {}),
+            ...(itemText ? { itemText } : {}),
+        };
+        const matches = sortA11yNodes(findNodes(a11y, filter).filter(node => node.focusable && (node.role === 'button' || node.role === 'link')));
+        if (matches.length === 0) {
+            if (detail === 'terse') {
+                return ok(JSON.stringify({ matchCount: 0, filter: compactFilterPayload(filter) }));
+            }
+            return ok(`No actions found matching ${JSON.stringify(filter)}`);
+        }
+        const formatted = matches.slice(0, maxResults).map(node => formatNode(node, a11y, a11y.bounds));
+        if (detail === 'terse') {
+            return ok(JSON.stringify({
+                matchCount: matches.length,
+                matches: formatted.map(compactFormattedNode),
+            }));
+        }
+        return ok(JSON.stringify(formatted));
+    });
     server.registerTool('geometra_wait_for', {
         description: `Wait for a semantic UI condition without guessing sleep durations. Use this for slow SPA transitions, resume parsing, custom validation alerts, disabled submit buttons, and value/state confirmation before submit.
 
 The filter matches the same fields as geometra_query (strict schema — unknown keys error). Set \`present: false\` to wait until **no** node matches — for example Ashby/Lever-style “Parsing your resume” or any “Parsing…” banner: \`{ "text": "Parsing", "present": false }\` (tune the substring to the site). Do not use a textGone parameter; use \`text\` + \`present: false\`, or \`geometra_wait_for_resume_parse\` for the usual post-upload parsing banner.`,
         inputSchema: geometraWaitForInputSchema,
-    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
+    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs, detail }) => {
         const session = getSession();
-        if (!session?.tree || !session?.layout)
+        if (!session)
             return err('Not connected. Call geometra_connect first.');
         const filterProbe = {
             id,
@@ -442,6 +561,9 @@ The filter matches the same fields as geometra_query (strict schema — unknown
             name,
             text,
             contextText,
+            promptText,
+            sectionText,
+            itemText,
             value,
             checked,
             disabled,
@@ -461,6 +583,16 @@ The filter matches the same fields as geometra_query (strict schema — unknown
         });
         if (!waited.ok)
             return err(waited.error);
+        if (detail === 'terse') {
+            const compact = waitConditionCompact(waited.value);
+            const matches = waited.value.matches
+                .slice(0, 3)
+                .map(match => compactFormattedNode(match));
+            return ok(JSON.stringify({
+                ...compact,
+                ...(matches.length > 0 ? { matches } : {}),
+            }));
+        }
         if (!waited.value.present) {
             return ok(waitConditionSuccessLine(waited.value));
         }
@@ -473,7 +605,7 @@ Equivalent to \`geometra_wait_for\` with \`present: false\` and \`text\` set to
         inputSchema: geometraWaitForResumeParseInputSchema,
     }, async ({ text, timeoutMs }) => {
         const session = getSession();
-        if (!session?.tree || !session?.layout)
+        if (!session)
             return err('Not connected. Call geometra_connect first.');
         const filter = { text };
         const waited = await waitForSemanticCondition(session, {
@@ -508,6 +640,30 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         const resolvedFields = resolveFillFieldInputs(session, fields);
         if (!resolvedFields.ok)
             return err(resolvedFields.error);
+        if (!includeSteps) {
+            try {
+                const batched = await tryBatchedResolvedFields(session, resolvedFields.fields, detail);
+                if (batched.ok) {
+                    const payload = {
+                        completed: true,
+                        execution: 'batched',
+                        finalSource: batched.finalSource,
+                        fieldCount: resolvedFields.fields.length,
+                        successCount: resolvedFields.fields.length,
+                        errorCount: 0,
+                        final: batched.final,
+                    };
+                    if (failOnInvalid && batched.invalidRemaining > 0) {
+                        return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                    }
+                    return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                }
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return err(message);
+            }
+        }
         const steps = [];
         let stoppedAt;
         for (let index = 0; index < resolvedFields.fields.length; index++) {
@@ -570,8 +726,14 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             .optional()
             .default(false)
             .describe('Include per-field step results in the JSON payload (default false for the smallest response)'),
+        resumeFromIndex: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Resume a partial fill from this field index (from a previous stoppedAt + 1). Skips already-filled fields.'),
         detail: detailInput(),
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, detail }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, detail }) => {
         const directFields = !includeSteps && !formId && Object.keys(valuesById ?? {}).length === 0
             ? directLabelBatchFields(valuesByLabel)
             : null;
@@ -720,7 +882,8 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         }
         const steps = [];
         let stoppedAt;
-        for (let index = 0; index < planned.fields.length; index++) {
+        const startIndex = resumeFromIndex ?? 0;
+        for (let index = startIndex; index < planned.fields.length; index++) {
             const field = planned.fields[index];
             try {
                 const result = await executeFillField(session, field, detail);
@@ -744,15 +907,16 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         const errorCount = steps.length - successCount;
         const payload = {
             ...connection,
-            completed: stoppedAt === undefined && steps.length === planned.fields.length,
+            completed: stoppedAt === undefined && (startIndex + steps.length) === planned.fields.length,
             execution: 'sequential',
             formId: schema.formId,
             requestedValueCount: entryCount,
             fieldCount: planned.fields.length,
             successCount,
             errorCount,
+            ...(startIndex > 0 ? { resumedFromIndex: startIndex } : {}),
             ...(includeSteps ? { steps } : {}),
-            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(stoppedAt !== undefined ? { stoppedAt, resumeFromIndex: stoppedAt + 1 } : {}),
             ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
         };
         if (failOnInvalid && invalidRemaining > 0) {
@@ -762,7 +926,14 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
     });
     server.tool('geometra_run_actions', `Execute several Geometra actions in one MCP round trip and return one consolidated result. This is the preferred path for long, multi-step form fills where one-tool-per-field would otherwise create too much chatter.
 
-Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, and \`fill_fields\`. \`click\` steps can also carry a nested \`waitFor\` condition.`, {
+Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, and \`fill_fields\`. \`click\` steps can also carry a nested \`waitFor\` condition. Pass \`pageUrl\` / \`url\` to auto-connect so an entire flow can run in one MCP call.`, {
+        url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before running actions.'),
+        pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before running actions. Prefer this over url for browser pages.'),
+        port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
+        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default false = visible window).'),
+        width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
+        height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
+        slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
         actions: z.array(batchActionSchema).min(1).max(80).describe('Ordered high-level action steps to run sequentially'),
         stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing step (default true)'),
         includeSteps: z
@@ -770,24 +941,81 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             .optional()
             .default(true)
             .describe('Include per-action step results in the JSON payload (default true). Set false for the smallest batch response.'),
+        output: z.enum(['full', 'final']).optional().default('full').describe('`full` (default) returns counts and optional step listings. `final` keeps only completion state plus final semantic signals.'),
         detail: detailInput(),
-    }, async ({ actions, stopOnError, includeSteps, detail }) => {
-        const session = getSession();
-        if (!session)
-            return err('Not connected. Call geometra_connect first.');
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, actions, stopOnError, includeSteps, output, detail }) => {
+        const resolved = await ensureToolSession({
+            url,
+            pageUrl,
+            port,
+            headless,
+            width,
+            height,
+            slowMo,
+            awaitInitialFrame: canDeferInitialFrameForRunActions(actions) ? false : undefined,
+        }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_run_actions.');
+        if (!resolved.ok)
+            return err(resolved.error);
+        const session = resolved.session;
+        const connection = autoConnectionPayload(resolved);
         const steps = [];
         let stoppedAt;
+        const batchStartedAt = performance.now();
         for (let index = 0; index < actions.length; index++) {
             const action = actions[index];
+            const startedAt = performance.now();
+            let uiTreeWaitMs = 0;
             try {
+                if (actionNeedsUiTree(action) && (!session.tree || !session.layout)) {
+                    const uiTreeWaitStartedAt = performance.now();
+                    await waitForUiCondition(session, () => Boolean(session.tree && session.layout), 2_000);
+                    uiTreeWaitMs = performance.now() - uiTreeWaitStartedAt;
+                }
                 const result = await executeBatchAction(session, action, detail, includeSteps);
+                const elapsedMs = Number((performance.now() - startedAt).toFixed(1));
+                const cumulativeMs = Number((performance.now() - batchStartedAt).toFixed(1));
+                const stepSignals = includeSteps ? (() => {
+                    const a = sessionA11y(session);
+                    if (!a)
+                        return undefined;
+                    const s = collectSessionSignals(a);
+                    return { invalidCount: s.invalidFields.length, alertCount: s.alerts.length, dialogCount: s.dialogCount, busyCount: s.busyCount };
+                })() : undefined;
                 steps.push(detail === 'verbose'
-                    ? { index, type: action.type, ok: true, summary: result.summary }
-                    : { index, type: action.type, ok: true, ...result.compact });
+                    ? {
+                        index,
+                        type: action.type,
+                        ok: true,
+                        elapsedMs,
+                        cumulativeMs,
+                        ...(uiTreeWaitMs > 0 ? { uiTreeWaitMs: Number(uiTreeWaitMs.toFixed(1)) } : {}),
+                        summary: result.summary,
+                        ...(stepSignals ? { signals: stepSignals } : {}),
+                    }
+                    : {
+                        index,
+                        type: action.type,
+                        ok: true,
+                        elapsedMs,
+                        cumulativeMs,
+                        ...(uiTreeWaitMs > 0 ? { uiTreeWaitMs: Number(uiTreeWaitMs.toFixed(1)) } : {}),
+                        ...result.compact,
+                        ...(stepSignals ? { signals: stepSignals } : {}),
+                    });
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
-                steps.push({ index, type: action.type, ok: false, error: message });
+                const elapsedMs = Number((performance.now() - startedAt).toFixed(1));
+                const cumulativeMs = Number((performance.now() - batchStartedAt).toFixed(1));
+                steps.push({
+                    index,
+                    type: action.type,
+                    ok: false,
+                    elapsedMs,
+                    cumulativeMs,
+                    ...(uiTreeWaitMs > 0 ? { uiTreeWaitMs: Number(uiTreeWaitMs.toFixed(1)) } : {}),
+                    error: message,
+                });
                 if (stopOnError) {
                     stoppedAt = index;
                     break;
@@ -797,15 +1025,23 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         const after = sessionA11y(session);
         const successCount = steps.filter(step => step.ok === true).length;
         const errorCount = steps.length - successCount;
-        const payload = {
-            completed: stoppedAt === undefined && steps.length === actions.length,
-            stepCount: actions.length,
-            successCount,
-            errorCount,
-            ...(includeSteps ? { steps } : {}),
-            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
-            ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
-        };
+        const payload = output === 'final'
+            ? {
+                ...connection,
+                completed: stoppedAt === undefined && steps.length === actions.length,
+                ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+                ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
+            }
+            : {
+                ...connection,
+                completed: stoppedAt === undefined && steps.length === actions.length,
+                stepCount: actions.length,
+                successCount,
+                errorCount,
+                ...(includeSteps ? { steps } : {}),
+                ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+                ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
+            };
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
     });
     // ── page model ────────────────────────────────────────────────
@@ -828,15 +1064,21 @@ Use this first on normal HTML pages when you want to understand the page shape w
             .optional()
             .default(8)
             .describe('Cap returned landmarks/forms/dialogs/lists per kind (default 8).'),
-    }, async ({ maxPrimaryActions, maxSectionsPerKind }) => {
+        includeScreenshot: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Attach a base64 PNG viewport screenshot. Requires @geometra/proxy. Use when geometry alone is ambiguous (icon-only buttons, visual styling cues).'),
+    }, async ({ maxPrimaryActions, maxSectionsPerKind, includeScreenshot }) => {
         const session = getSession();
-        if (!session?.tree || !session?.layout)
+        if (!session)
             return err('Not connected. Call geometra_connect first.');
-        const a11y = sessionA11y(session);
+        const a11y = await sessionA11yWhenReady(session);
         if (!a11y)
             return err('No UI tree available');
         const model = buildPageModel(a11y, { maxPrimaryActions, maxSectionsPerKind });
-        return ok(JSON.stringify(model));
+        const screenshot = includeScreenshot ? await captureScreenshotBase64(session) : undefined;
+        return ok(JSON.stringify(model), screenshot);
     });
     server.tool('geometra_form_schema', `Get a compact, fill-oriented schema for forms on the page. This is the preferred discovery step before geometra_fill_form.
 
@@ -861,6 +1103,9 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
+        if (!(await ensureSessionUiTree(session, 4_000))) {
+            return err('Timed out waiting for the initial UI tree after connect.');
+        }
         const payload = formSchemaResponsePayload(session, {
             formId,
             maxFields,
@@ -898,9 +1143,9 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
         includeBounds: z.boolean().optional().default(false).describe('Include bounds for fields/actions/headings/items'),
     }, async ({ id, maxHeadings, maxFields, fieldOffset, onlyRequiredFields, onlyInvalidFields, maxActions, actionOffset, maxLists, listOffset, maxItems, itemOffset, maxTextPreview, includeBounds, }) => {
         const session = getSession();
-        if (!session?.tree || !session?.layout)
+        if (!session)
             return err('Not connected. Call geometra_connect first.');
-        const a11y = sessionA11y(session);
+        const a11y = await sessionA11yWhenReady(session);
         if (!a11y)
             return err('No UI tree available');
         const detail = expandPageSection(a11y, id, {
@@ -937,7 +1182,7 @@ Use the same filters as geometra_query, plus an optional match index when repeat
             .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 }) => {
+    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, 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.');
@@ -947,6 +1192,9 @@ Use the same filters as geometra_query, plus an optional match index when repeat
             name,
             text,
             contextText,
+            promptText,
+            sectionText,
+            itemText,
             value,
             checked,
             disabled,
@@ -958,7 +1206,7 @@ Use the same filters as geometra_query, plus an optional match index when repeat
             busy,
         };
         if (!hasNodeFilter(filter))
-            return err('Provide at least one reveal filter (id, role, name, text, contextText, value, or state)');
+            return err('Provide at least one reveal filter (id, role, name, text, contextText, promptText, sectionText, itemText, value, or state)');
         const revealed = await revealSemanticTarget(session, {
             filter,
             index: index ?? 0,
@@ -1001,7 +1249,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             .optional()
             .describe('Optional action wait timeout (use a longer value for slow submits or route transitions)'),
         detail: detailInput(),
-    }, async ({ x, y, id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxRevealSteps, revealTimeoutMs, waitFor, timeoutMs, detail }) => {
+    }, async ({ x, y, id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxRevealSteps, revealTimeoutMs, waitFor, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -1015,6 +1263,9 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
                 name,
                 text,
                 contextText,
+                promptText,
+                sectionText,
+                itemText,
                 value,
                 checked,
                 disabled,
@@ -1046,6 +1297,9 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
                     name: waitFor.name,
                     text: waitFor.text,
                     contextText: waitFor.contextText,
+                    promptText: waitFor.promptText,
+                    sectionText: waitFor.sectionText,
+                    itemText: waitFor.itemText,
                     value: waitFor.value,
                     checked: waitFor.checked,
                     disabled: waitFor.disabled,
@@ -1062,8 +1316,20 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             if (!postWait.ok)
                 return err([...lines, postWait.error].join('\n'));
             lines.push(`Post-click ${waitConditionSuccessLine(postWait.value)}`);
+            const compact = {
+                at: { x: resolved.value.x, y: resolved.value.y },
+                ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
+                ...waitStatusPayload(wait),
+                postWait: waitConditionCompact(postWait.value),
+            };
+            return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
         }
-        return ok(lines.filter(Boolean).join('\n'));
+        const compact = {
+            at: { x: resolved.value.x, y: resolved.value.y },
+            ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
+            ...waitStatusPayload(wait),
+        };
+        return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
     });
     // ── type ─────────────────────────────────────────────────────
     server.tool('geometra_type', `Type text into the currently focused element. First click a textbox/input with geometra_click to focus it, then use this to type.
@@ -1085,7 +1351,10 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         const before = sessionA11y(session);
         const wait = await sendType(session, text, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
-        return ok(`Typed "${text}".\n${summary}`);
+        return ok(detailText(`Typed "${text}".\n${summary}`, {
+            ...compactTextValue(text),
+            ...waitStatusPayload(wait),
+        }, detail));
     });
     // ── key ──────────────────────────────────────────────────────
     server.tool('geometra_key', `Send a special key press (Enter, Tab, Escape, ArrowDown, etc.) to the Geometra UI. Useful for form submission, focus navigation, and keyboard shortcuts.`, {
@@ -1109,7 +1378,10 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         const before = sessionA11y(session);
         const wait = await sendKey(session, key, { shift, ctrl, meta, alt }, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
-        return ok(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`);
+        return ok(detailText(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`, {
+            key: formatKeyCombo(key, { shift, ctrl, meta, alt }),
+            ...waitStatusPayload(wait),
+        }, detail));
     });
     // ── upload files (proxy) ───────────────────────────────────────
     server.tool('geometra_upload_files', `Attach local files to a file input. Requires \`@geometra/proxy\` (paths exist on the proxy host).
@@ -1126,6 +1398,8 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
             .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'),
+        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated file inputs'),
+        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated file inputs'),
         timeoutMs: z
             .number()
             .int()
@@ -1134,7 +1408,7 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
             .optional()
             .describe('Optional action wait timeout (resume parsing / SPA upload flows often need longer than a normal click)'),
         detail: detailInput(),
-    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, timeoutMs, detail }) => {
+    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -1148,7 +1422,13 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
                 drop: dropX !== undefined && dropY !== undefined ? { x: dropX, y: dropY } : undefined,
             }, timeoutMs ?? 8_000);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(`Uploaded ${paths.length} file(s).\n${summary}`);
+            return ok(detailText(`Uploaded ${paths.length} file(s).\n${summary}`, {
+                fileCount: paths.length,
+                ...(fieldLabel ? { fieldLabel } : {}),
+                ...(strategy ? { strategy } : {}),
+                ...waitStatusPayload(wait),
+                ...(fieldLabel ? { readback: fieldStatePayload(session, fieldLabel) } : {}),
+            }, detail));
         }
         catch (e) {
             return err(e.message);
@@ -1162,6 +1442,8 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
         openX: z.number().optional().describe('Click to open dropdown'),
         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")'),
+        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated dropdowns with the same label'),
+        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated dropdowns'),
         query: z.string().optional().describe('Optional text to type into a searchable combobox before selecting'),
         timeoutMs: z
             .number()
@@ -1171,7 +1453,7 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
             .optional()
             .describe('Optional action wait timeout for slow dropdowns / remote search results'),
         detail: detailInput(),
-    }, async ({ label, exact, openX, openY, fieldLabel, query, timeoutMs, detail }) => {
+    }, async ({ label, exact, openX, openY, fieldLabel, contextText, sectionText, query, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -1185,11 +1467,17 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
             }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
             const fieldSummary = fieldLabel ? summarizeFieldLabelState(session, fieldLabel) : undefined;
-            return ok([
+            const summaryText = [
                 `Picked listbox option "${label}".`,
                 fieldSummary,
                 summary,
-            ].filter(Boolean).join('\n'));
+            ].filter(Boolean).join('\n');
+            return ok(detailText(summaryText, {
+                label,
+                ...(fieldLabel ? { fieldLabel } : {}),
+                ...waitStatusPayload(wait),
+                ...(fieldLabel ? { readback: fieldStatePayload(session, fieldLabel) } : {}),
+            }, detail));
         }
         catch (e) {
             return err(e.message);
@@ -1204,6 +1492,8 @@ Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbo
         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'),
+        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated selects'),
+        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated selects'),
         timeoutMs: z
             .number()
             .int()
@@ -1212,7 +1502,7 @@ Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbo
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ x, y, value, label, index, timeoutMs, detail }) => {
+    }, async ({ x, y, value, label, index, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -1223,7 +1513,13 @@ Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbo
         try {
             const wait = await sendSelectOption(session, x, y, { value, label, index }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(`Selected option.\n${summary}`);
+            return ok(detailText(`Selected option.\n${summary}`, {
+                at: { x, y },
+                ...(value !== undefined ? { value } : {}),
+                ...(label !== undefined ? { label } : {}),
+                ...(index !== undefined ? { index } : {}),
+                ...waitStatusPayload(wait),
+            }, detail));
         }
         catch (e) {
             return err(e.message);
@@ -1236,6 +1532,8 @@ 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'),
+        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated checkboxes/radios'),
+        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated checkboxes/radios'),
         timeoutMs: z
             .number()
             .int()
@@ -1244,7 +1542,7 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ label, checked, exact, controlType, timeoutMs, detail }) => {
+    }, async ({ label, checked, exact, controlType, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -1252,7 +1550,12 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         try {
             const wait = await sendSetChecked(session, label, { checked, exact, controlType }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(`Set ${controlType ?? 'checkbox/radio'} "${label}" to ${String(checked ?? true)}.\n${summary}`);
+            return ok(detailText(`Set ${controlType ?? 'checkbox/radio'} "${label}" to ${String(checked ?? true)}.\n${summary}`, {
+                label,
+                checked: checked ?? true,
+                ...(controlType ? { controlType } : {}),
+                ...waitStatusPayload(wait),
+            }, detail));
         }
         catch (e) {
             return err(e.message);
@@ -1280,12 +1583,68 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         try {
             const wait = await sendWheel(session, deltaY, { deltaX, x, y }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`);
+            return ok(detailText(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`, {
+                deltaY,
+                ...(deltaX !== undefined ? { deltaX } : {}),
+                ...(x !== undefined && y !== undefined ? { at: { x, y } } : {}),
+                ...waitStatusPayload(wait),
+            }, detail));
         }
         catch (e) {
             return err(e.message);
         }
     });
+    // ── list items (virtualized list pagination) ─────────────────
+    server.tool('geometra_list_items', `Auto-scroll a virtualized or long list and collect all visible items across scroll positions. Requires \`@geometra/proxy\`.
+
+Use this for dropdowns, location pickers, or any scrollable list where items are rendered on demand. Scrolls down in steps, collecting new items each time, until no new items appear or the cap is reached.`, {
+        listId: z.string().optional().describe('Stable section id from geometra_page_model (e.g. ls:2.1) to scope item collection'),
+        role: z.string().optional().describe('Role filter for list items (default: listitem)'),
+        scrollX: z.number().optional().describe('X coordinate to position mouse for scrolling (default: viewport center)'),
+        scrollY: z.number().optional().describe('Y coordinate to position mouse for scrolling (default: viewport center)'),
+        maxItems: z.number().int().min(1).max(500).optional().default(100).describe('Cap collected items (default 100)'),
+        maxScrollSteps: z.number().int().min(1).max(50).optional().default(20).describe('Max scroll steps before stopping (default 20)'),
+        scrollDelta: z.number().optional().default(300).describe('Vertical scroll delta per step (default 300)'),
+    }, async ({ listId: _listId, role, scrollX, scrollY, maxItems, maxScrollSteps, scrollDelta }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const itemRole = role ?? 'listitem';
+        const collected = new Map();
+        const cx = scrollX ?? 400;
+        const cy = scrollY ?? 400;
+        for (let step = 0; step < maxScrollSteps; step++) {
+            const a11y = await sessionA11yWhenReady(session);
+            if (!a11y)
+                break;
+            const items = findNodes(a11y, { role: itemRole });
+            let newCount = 0;
+            for (const item of items) {
+                const id = nodeIdForPath(item.path);
+                if (!collected.has(id)) {
+                    collected.set(id, {
+                        ...(item.name ? { name: item.name } : {}),
+                        ...(item.value ? { value: item.value } : {}),
+                    });
+                    newCount++;
+                }
+            }
+            if (collected.size >= maxItems || newCount === 0)
+                break;
+            try {
+                await sendWheel(session, scrollDelta, { x: cx, y: cy }, 1_000);
+            }
+            catch {
+                break;
+            }
+        }
+        const items = [...collected.entries()].slice(0, maxItems).map(([id, data]) => ({ id, ...data }));
+        return ok(JSON.stringify({
+            itemCount: items.length,
+            items,
+            truncated: collected.size > maxItems,
+        }));
+    });
     // ── snapshot ─────────────────────────────────────────────────
     server.tool('geometra_snapshot', `Get the current UI as JSON. Default **compact** view: flat list of viewport-visible actionable nodes plus a few pinned context anchors (for example tab strips / form roots) and root context like URL, scroll, and focus — far fewer tokens than a full nested tree. Use **full** for complete nested a11y + every wrapper when debugging layout. Use **form-required** to list required fields across forms, including offscreen ones, with bounds + visibility + scroll hints for long application flows.
 
@@ -1306,15 +1665,21 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
         formId: z.string().optional().describe('Optional form id from geometra_form_schema / geometra_page_model when view=form-required'),
         maxFields: z.number().int().min(1).max(200).optional().default(80).describe('Per-form field cap when view=form-required'),
         includeOptions: z.boolean().optional().default(false).describe('Include explicit choice option labels when view=form-required'),
-    }, async ({ view, maxNodes, formId, maxFields, includeOptions }) => {
+        includeScreenshot: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Attach a base64 PNG viewport screenshot. Requires @geometra/proxy.'),
+    }, async ({ view, maxNodes, formId, maxFields, includeOptions, includeScreenshot }) => {
         const session = getSession();
-        if (!session?.tree || !session?.layout)
+        if (!session)
             return err('Not connected. Call geometra_connect first.');
-        const a11y = sessionA11y(session);
+        const a11y = await sessionA11yWhenReady(session);
         if (!a11y)
             return err('No UI tree available');
+        const screenshot = includeScreenshot ? await captureScreenshotBase64(session) : undefined;
         if (view === 'full') {
-            return ok(JSON.stringify(a11y, null, 2));
+            return ok(JSON.stringify(a11y, null, 2), screenshot);
         }
         if (view === 'form-required') {
             const payload = {
@@ -1327,7 +1692,7 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
                     includeContext: 'auto',
                 }),
             };
-            return ok(JSON.stringify(payload));
+            return ok(JSON.stringify(payload), screenshot);
         }
         const { nodes, truncated, context } = buildCompactUiIndex(a11y, { maxNodes });
         const payload = {
@@ -1337,7 +1702,7 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
             nodes,
             truncated,
         };
-        return ok(JSON.stringify(payload));
+        return ok(JSON.stringify(payload), screenshot);
     });
     // ── layout ───────────────────────────────────────────────────
     server.tool('geometra_layout', `Get the raw computed layout geometry — the exact {x, y, width, height} for every node in the UI tree. This is the lowest-level view, useful for pixel-precise assertions in tests.
@@ -1365,7 +1730,7 @@ function compactSessionSummary(session) {
     return sessionOverviewFromA11y(a11y);
 }
 function connectPayload(session, opts) {
-    const a11y = sessionA11y(session);
+    const a11y = opts.detail === 'verbose' ? sessionA11y(session) : null;
     return {
         connected: true,
         transport: opts.transport,
@@ -1387,6 +1752,17 @@ function sessionA11y(session) {
     session.cachedA11yRevision = session.updateRevision;
     return a11y;
 }
+async function ensureSessionUiTree(session, timeoutMs = 4_000) {
+    if (session.tree && session.layout)
+        return true;
+    return await waitForUiCondition(session, () => Boolean(session.tree && session.layout), timeoutMs);
+}
+async function sessionA11yWhenReady(session, timeoutMs = 4_000) {
+    const ready = await ensureSessionUiTree(session, timeoutMs);
+    if (!ready)
+        return null;
+    return sessionA11y(session);
+}
 function shortHash(value) {
     return createHash('sha1').update(value).digest('hex').slice(0, 12);
 }
@@ -1438,8 +1814,10 @@ function packedFormSchemas(forms) {
             ...(field.valueLength !== undefined ? { vl: field.valueLength } : {}),
             ...(field.checked !== undefined ? { c: field.checked ? 1 : 0 } : {}),
             ...(field.values && field.values.length > 0 ? { vs: field.values } : {}),
+            ...(field.aliases ? { al: field.aliases } : {}),
             ...(field.context ? { x: field.context } : {}),
         })),
+        ...(form.sections ? { s: form.sections.map(s => ({ n: s.name, fi: s.fieldIds })) } : {}),
     }));
 }
 function formSchemaResponsePayload(session, opts) {
@@ -1506,10 +1884,23 @@ function connectResponsePayload(session, opts) {
         nextPayload.formSchema = formSchemaResponsePayload(session, opts.formSchema ?? {});
     }
     if (opts.returnPageModel) {
-        nextPayload.pageModel = pageModelResponsePayload(session, opts.pageModelOptions);
+        nextPayload.pageModel = opts.pageModelMode === 'deferred'
+            ? deferredPageModelConnectPayload(session, opts.pageModelOptions)
+            : pageModelResponsePayload(session, opts.pageModelOptions);
     }
     return nextPayload;
 }
+function deferredPageModelConnectPayload(session, options) {
+    return {
+        deferred: true,
+        ready: Boolean(session.tree && session.layout),
+        tool: 'geometra_page_model',
+        options: {
+            maxPrimaryActions: options?.maxPrimaryActions ?? 6,
+            maxSectionsPerKind: options?.maxSectionsPerKind ?? 8,
+        },
+    };
+}
 function pageModelResponsePayload(session, options) {
     const a11y = sessionA11y(session);
     if (!a11y) {
@@ -1737,8 +2128,15 @@ function sessionSignalsPayload(signals, detail = 'minimal') {
         busyCount: signals.busyCount,
         alertCount: signals.alerts.length,
         invalidCount: signals.invalidFields.length,
-        alerts: detail === 'verbose' ? signals.alerts : signals.alerts.slice(0, 2),
-        invalidFields: detail === 'verbose' ? signals.invalidFields : signals.invalidFields.slice(0, 4),
+        ...(detail === 'verbose'
+            ? {
+                alerts: signals.alerts,
+                invalidFields: signals.invalidFields,
+            }
+            : {
+                alerts: signals.alerts.slice(0, 2),
+                invalidFields: signals.invalidFields.slice(0, 6),
+            }),
     };
 }
 function compactTextValue(value, inlineLimit = 48) {
@@ -1834,6 +2232,10 @@ function inferRevealStepBudget(target, viewport) {
     return clamp(Math.max(6, Math.max(verticalSteps, horizontalSteps) + 1), 6, 48);
 }
 async function revealSemanticTarget(session, options) {
+    const initialTreeReady = await ensureSessionUiTree(session, Math.max(4_000, options.timeoutMs));
+    if (!initialTreeReady) {
+        return { ok: false, error: 'Timed out waiting for the initial UI tree after connect.' };
+    }
     let attempts = 0;
     let stepBudget = options.maxSteps;
     while (attempts <= (stepBudget ?? 48)) {
@@ -1904,7 +2306,7 @@ async function resolveClickLocation(session, options) {
     if (!hasNodeFilter(options.filter)) {
         return {
             ok: false,
-            error: 'Provide x and y, or at least one semantic target filter (id, role, name, text, contextText, value, or state)',
+            error: 'Provide x and y, or at least one semantic target filter (id, role, name, text, contextText, promptText, sectionText, itemText, value, or state)',
         };
     }
     const revealed = await revealSemanticTarget(session, {
@@ -1936,6 +2338,18 @@ function compactNodeReference(node) {
         ...(node.name ? { name: node.name } : {}),
     };
 }
+function compactFormattedNode(node) {
+    return {
+        ...compactNodeReference(node),
+        ...(node.context ? { context: node.context } : {}),
+        ...(node.value ? { value: node.value } : {}),
+        center: node.center,
+        bounds: node.bounds,
+    };
+}
+function detailText(summary, compact, detail) {
+    return detail === 'terse' ? JSON.stringify(compact) : summary;
+}
 function normalizeLookupKey(value) {
     return value.replace(/\s+/g, ' ').trim().toLowerCase();
 }
@@ -2182,12 +2596,14 @@ function parseProxyFillAckResult(value) {
         typeof candidate.busyCount !== 'number') {
         return undefined;
     }
+    const invalidFields = Array.isArray(candidate.invalidFields) ? candidate.invalidFields : undefined;
     return {
         ...(typeof candidate.pageUrl === 'string' ? { pageUrl: candidate.pageUrl } : {}),
         invalidCount: candidate.invalidCount,
         alertCount: candidate.alertCount,
         dialogCount: candidate.dialogCount,
         busyCount: candidate.busyCount,
+        ...(invalidFields && invalidFields.length > 0 ? { invalidFields } : {}),
     };
 }
 function directLabelBatchFields(valuesByLabel) {
@@ -2202,6 +2618,44 @@ function directLabelBatchFields(valuesByLabel) {
     }
     return fields;
 }
+async function tryBatchedResolvedFields(session, fields, detail) {
+    let batchAckResult;
+    try {
+        const startRevision = session.updateRevision;
+        const wait = await sendFillFields(session, fields);
+        const ackResult = parseProxyFillAckResult(wait.result);
+        batchAckResult = ackResult;
+        if (ackResult && ackResult.invalidCount === 0) {
+            return {
+                ok: true,
+                finalSource: 'proxy',
+                final: ackResult,
+                invalidRemaining: 0,
+            };
+        }
+        await waitForDeferredBatchUpdate(session, startRevision, wait);
+        await waitForBatchFieldReadback(session, fields);
+    }
+    catch (e) {
+        if (canFallbackToSequentialFill(e))
+            return { ok: false };
+        throw e;
+    }
+    const after = sessionA11y(session);
+    if (!after)
+        return { ok: false };
+    const signals = collectSessionSignals(after);
+    const invalidRemaining = signals.invalidFields.length;
+    if ((!batchAckResult || batchAckResult.invalidCount > 0) && invalidRemaining > 0) {
+        return { ok: false };
+    }
+    return {
+        ok: true,
+        finalSource: 'session',
+        final: sessionSignalsPayload(signals, detail),
+        invalidRemaining,
+    };
+}
 async function waitForDeferredBatchUpdate(session, startRevision, wait) {
     if (wait.status !== 'acknowledged' || session.updateRevision > startRevision)
         return;
@@ -2242,6 +2696,22 @@ function batchFieldReadbackMatches(a11y, field) {
         }
     }
 }
+function actionNeedsUiTree(action) {
+    switch (action.type) {
+        case 'wait_for':
+            return true;
+        case 'click':
+            return action.x === undefined || action.y === undefined || Boolean(action.waitFor);
+        default:
+            return false;
+    }
+}
+function canDeferInitialFrameForRunActions(actions) {
+    const first = actions[0];
+    if (!first)
+        return false;
+    return first.type === 'fill_fields';
+}
 async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {
@@ -2255,6 +2725,9 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                     name: action.name,
                     text: action.text,
                     contextText: action.contextText,
+                    promptText: action.promptText,
+                    sectionText: action.sectionText,
+                    itemText: action.itemText,
                     value: action.value,
                     checked: action.checked,
                     disabled: action.disabled,
@@ -2286,6 +2759,9 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                         name: action.waitFor.name,
                         text: action.waitFor.text,
                         contextText: action.waitFor.contextText,
+                        promptText: action.waitFor.promptText,
+                        sectionText: action.waitFor.sectionText,
+                        itemText: action.waitFor.itemText,
                         value: action.waitFor.value,
                         checked: action.waitFor.checked,
                         disabled: action.waitFor.disabled,
@@ -2442,6 +2918,9 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                     name: action.name,
                     text: action.text,
                     contextText: action.contextText,
+                    promptText: action.promptText,
+                    sectionText: action.sectionText,
+                    itemText: action.itemText,
                     value: action.value,
                     checked: action.checked,
                     disabled: action.disabled,
@@ -2479,6 +2958,20 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             const resolvedFields = resolveFillFieldInputs(session, action.fields);
             if (!resolvedFields.ok)
                 throw new Error(resolvedFields.error);
+            if (!includeSteps) {
+                const batched = await tryBatchedResolvedFields(session, resolvedFields.fields, detail);
+                if (batched.ok) {
+                    return {
+                        summary: `Filled ${resolvedFields.fields.length} field(s) in one proxy batch.`,
+                        compact: {
+                            fieldCount: resolvedFields.fields.length,
+                            execution: 'batched',
+                            finalSource: batched.finalSource,
+                            final: batched.final,
+                        },
+                    };
+                }
+            }
             const steps = [];
             for (let index = 0; index < resolvedFields.fields.length; index++) {
                 const field = resolvedFields.fields[index];
@@ -2571,8 +3064,24 @@ async function executeFillField(session, field, detail) {
         }
     }
 }
-function ok(text) {
-    return { content: [{ type: 'text', text }] };
+function ok(text, screenshot) {
+    const content = [
+        { type: 'text', text },
+    ];
+    if (screenshot) {
+        content.push({ type: 'image', data: screenshot, mimeType: 'image/png' });
+    }
+    return { content };
+}
+async function captureScreenshotBase64(session) {
+    try {
+        const wait = await sendScreenshot(session);
+        const result = wait.result;
+        return typeof result?.screenshot === 'string' ? result.screenshot : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 function err(text) {
     return { content: [{ type: 'text', text }], isError: true };
@@ -2673,10 +3182,10 @@ function sectionContext(root, node) {
     }
     return undefined;
 }
-function nodeContextText(root, node) {
-    return [promptContext(root, node), sectionContext(root, node)].filter(Boolean).join(' | ') || undefined;
+function nodeContextText(context) {
+    return [context?.prompt, context?.section, context?.item].filter(Boolean).join(' | ') || undefined;
 }
-function nodeMatchesFilter(node, filter, contextText) {
+function nodeMatchesFilter(node, filter, context) {
     if (filter.id && nodeIdForPath(node.path) !== filter.id)
         return false;
     if (filter.role && node.role !== filter.role)
@@ -2688,7 +3197,13 @@ function nodeMatchesFilter(node, filter, contextText) {
     if (filter.text &&
         !textMatches(`${node.name ?? ''} ${node.value ?? ''} ${node.validation?.error ?? ''} ${node.validation?.description ?? ''}`.trim(), filter.text))
         return false;
-    if (!textMatches(contextText, filter.contextText))
+    if (!textMatches(nodeContextText(context), filter.contextText))
+        return false;
+    if (!textMatches(context?.prompt, filter.promptText))
+        return false;
+    if (!textMatches(context?.section, filter.sectionText))
+        return false;
+    if (!textMatches(context?.item, filter.itemText))
         return false;
     if (filter.checked !== undefined && node.state?.checked !== filter.checked)
         return false;
@@ -2711,8 +3226,10 @@ function nodeMatchesFilter(node, filter, contextText) {
 export function findNodes(node, filter) {
     const matches = [];
     function walk(n) {
-        const contextText = filter.contextText ? nodeContextText(node, n) : undefined;
-        if (nodeMatchesFilter(n, filter, contextText) && hasNodeFilter(filter))
+        const context = filter.contextText || filter.promptText || filter.sectionText || filter.itemText
+            ? nodeContextForNode(node, n)
+            : undefined;
+        if (nodeMatchesFilter(n, filter, context) && hasNodeFilter(filter))
             matches.push(n);
         for (const child of n.children)
             walk(child);
@@ -2755,14 +3272,13 @@ function formatNode(node, root, 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);
+    const context = nodeContextForNode(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 } : {}) } } : {}),
+        ...(context ? { context } : {}),
         bounds: node.bounds,
         visibleBounds: {
             x: visibleLeft,