@geometra/mcp 1.19.18 → 1.19.20

package/dist/server.js

@@ -48,6 +48,33 @@ function nodeFilterShape() {
         busy: z.boolean().optional().describe('Match busy / in-progress state'),
     };
 }
+function waitConditionShape() {
+    return {
+        ...nodeFilterShape(),
+        present: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Wait until at least one node matches the filter (default true), or until no node matches (set false to wait out loading/parsing banners like “Parsing…” or “Parsing your resume”)'),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .default(10_000)
+            .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). ' +
+    '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.';
+const GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE = 'Provide at least one semantic filter (id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, or busy). ' +
+    'This tool uses a strict schema: unknown keys are rejected. There is no textGone parameter — use text with a distinctive substring and present: false to wait until that text is gone ' +
+    '(common for “Parsing…”, “Parsing your resume”, or similar). Passing only present/timeoutMs is not enough without a filter.';
+/** Strict input so unknown keys (e.g. textGone) fail parse; empty-filter checks happen in handlers / waitForSemanticCondition. */
+const geometraQueryInputSchema = z.object(nodeFilterShape()).strict();
+const geometraWaitForInputSchema = z.object(waitConditionShape()).strict();
 const timeoutMsInput = z.number().int().min(50).max(60_000).optional();
 const fillFieldSchema = z.discriminatedUnion('kind', [
     z.object({
@@ -98,8 +125,14 @@ const formValuesRecordSchema = z.record(z.string(), formValueSchema);
 const batchActionSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('click'),
-        x: z.number(),
-        y: z.number(),
+        x: z.number().optional().describe('X coordinate to click'),
+        y: z.number().optional().describe('Y coordinate to click'),
+        ...nodeFilterShape(),
+        index: z.number().int().min(0).optional().describe('Which matching semantic target to click after sorting top-to-bottom'),
+        fullyVisible: z.boolean().optional().describe('When clicking by semantic target, require full visibility before clicking (default true)'),
+        maxRevealSteps: z.number().int().min(1).max(12).optional().describe('Maximum reveal attempts before clicking a semantic target'),
+        revealTimeoutMs: timeoutMsInput.describe('Per-scroll wait timeout while revealing a semantic target'),
+        waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the click'),
         timeoutMs: timeoutMsInput,
     }),
     z.object({
@@ -175,7 +208,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }),
 ]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.17' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.20' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -183,7 +216,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).`, {
+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.`, {
         url: z
             .string()
             .optional()
@@ -218,6 +251,11 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .optional()
             .default(false)
             .describe('Include compact form schema discovery in the connect response so form flows can start in one turn.'),
+        returnPageModel: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include geometra_page_model output in the connect response so exploration can start in one turn.'),
         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'),
@@ -226,6 +264,8 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
         includeContext: formSchemaContextInput(),
         sinceSchemaId: z.string().optional().describe('If the current schema matches this id, return changed=false without resending forms'),
         schemaFormat: formSchemaFormatInput(),
+        maxPrimaryActions: z.number().int().min(1).max(12).optional().default(6).describe('Cap top-level primary actions when returnPageModel=true'),
+        maxSectionsPerKind: z.number().int().min(1).max(16).optional().default(8).describe('Cap returned landmarks/forms/dialogs/lists per kind when returnPageModel=true'),
         detail: detailInput(),
     }, async (input) => {
         const normalized = normalizeConnectTarget({ url: input.url, pageUrl: input.pageUrl });
@@ -242,6 +282,10 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             sinceSchemaId: input.sinceSchemaId,
             format: input.schemaFormat,
         };
+        const pageModelOptions = {
+            maxPrimaryActions: input.maxPrimaryActions,
+            maxSectionsPerKind: input.maxSectionsPerKind,
+        };
         try {
             if (target.kind === 'proxy') {
                 const session = await connectThroughProxy({
@@ -261,7 +305,9 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     autoCoercedFromUrl: target.autoCoercedFromUrl,
                     detail: input.detail,
                     returnForms: input.returnForms,
+                    returnPageModel: input.returnPageModel,
                     formSchema,
+                    pageModelOptions,
                 }), null, input.detail === 'verbose' ? 2 : undefined));
             }
             const session = await connect(target.wsUrl, {
@@ -277,7 +323,9 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                 autoCoercedFromUrl: false,
                 detail: input.detail,
                 returnForms: input.returnForms,
+                returnPageModel: input.returnPageModel,
                 formSchema,
+                pageModelOptions,
             }), null, input.detail === 'verbose' ? 2 : undefined));
         }
         catch (e) {
@@ -287,7 +335,11 @@ 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, contextText, 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.
+
+Unknown parameter names are rejected (strict schema). To wait until visible text goes away (e.g. a parsing banner), use geometra_wait_for with that substring in text and present: false — there is no textGone field.`, 
+    // SDK overload typings only list raw shapes; runtime accepts ZodObject via getZodSchemaObject().
+    geometraQueryInputSchema, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -311,7 +363,7 @@ 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, contextText, value, or state)');
+            return err(GEOMETRA_QUERY_FILTER_REQUIRED_MESSAGE);
         const matches = findNodes(a11y, filter);
         if (matches.length === 0) {
             return ok(`No elements found matching ${JSON.stringify(filter)}`);
@@ -321,22 +373,11 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
     });
     server.tool('geometra_wait_for', `Wait for a semantic UI condition without guessing sleep durations. Use this for slow SPA transitions, resume parsing, custom validation alerts, disabled submit buttons, and value/state confirmation before submit.
 
-The filter matches the same fields as geometra_query. Set \`present: false\` to wait for something to disappear (for example an alert or a "Parsing…" status).`, {
-        ...nodeFilterShape(),
-        present: z.boolean().optional().default(true).describe('Wait for a matching node to exist (default true) or disappear'),
-        timeoutMs: z
-            .number()
-            .int()
-            .min(50)
-            .max(60_000)
-            .optional()
-            .default(10_000)
-            .describe('Maximum time to wait before returning an error (default 10000ms)'),
-    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
+The filter matches the same fields as geometra_query (strict schema — unknown keys error). Set \`present: false\` to wait until **no** node matches — for example Ashby/Lever-style “Parsing your resume” or any “Parsing…” banner: \`{ "text": "Parsing", "present": false }\` (tune the substring to the site). Do not use a textGone parameter; use \`text\` + \`present: false\`.`, geometraWaitForInputSchema, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
-        const filter = {
+        const filterProbe = {
             id,
             role,
             name,
@@ -352,32 +393,19 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             required,
             busy,
         };
-        if (!hasNodeFilter(filter))
-            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;
-            const a11y = sessionA11y(session);
-            if (!a11y)
-                return false;
-            const matches = findNodes(a11y, filter);
-            return present ? matches.length > 0 : matches.length === 0;
-        };
-        const startedAt = Date.now();
-        const matched = await waitForUiCondition(session, matchesCondition, timeoutMs);
-        const elapsedMs = Date.now() - startedAt;
-        if (!matched) {
-            return err(`Timed out after ${timeoutMs}ms waiting for ${present ? 'presence' : 'absence'} of ${JSON.stringify(filter)}.\nCurrent UI:\n${compactSessionSummary(session)}`);
-        }
-        if (!present) {
-            return ok(`Condition satisfied after ${elapsedMs}ms: no nodes matched ${JSON.stringify(filter)}.`);
+        if (!hasNodeFilter(filterProbe))
+            return err(GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE);
+        const waited = await waitForSemanticCondition(session, {
+            filter: filterProbe,
+            present: present ?? true,
+            timeoutMs: timeoutMs ?? 10_000,
+        });
+        if (!waited.ok)
+            return err(waited.error);
+        if (!waited.value.present) {
+            return ok(waitConditionSuccessLine(waited.value));
         }
-        const after = sessionA11y(session);
-        if (!after)
-            return ok(`Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`);
-        const matches = findNodes(after, filter);
-        const result = sortA11yNodes(matches).slice(0, 8).map(node => formatNode(node, after, after.bounds));
-        return ok(JSON.stringify(result, null, 2));
+        return ok(JSON.stringify(waited.value.matches.slice(0, 8), 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.
 
@@ -653,7 +681,7 @@ 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\`.`, {
+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.`, {
         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
@@ -832,10 +860,6 @@ Use the same filters as geometra_query, plus an optional match index when repeat
         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,
@@ -854,55 +878,40 @@ Use the same filters as geometra_query, plus an optional match index when repeat
         };
         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)}`);
+        const revealed = await revealSemanticTarget(session, {
+            filter,
+            index: index ?? 0,
+            fullyVisible: fullyVisible ?? true,
+            maxSteps: maxSteps ?? 6,
+            timeoutMs: timeoutMs ?? 2_500,
+        });
+        if (!revealed.ok)
+            return err(revealed.error);
+        return ok(JSON.stringify({
+            revealed: true,
+            attempts: revealed.value.attempts,
+            target: revealed.value.target,
+        }, null, 2));
     });
     // ── 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.
+    server.tool('geometra_click', `Click an element in the Geometra UI. Provide either raw x,y coordinates or a semantic target (\`id\`, \`role\`, \`name\`, \`text\`, \`contextText\`, \`value\`, or state filters). You can also attach \`waitFor\` to block on the post-click semantic state in the same call. The click is dispatched server-side via the geometry protocol — no browser, no simulated DOM events.
 
 After clicking, returns a compact semantic delta when possible (dialogs/forms/lists/nodes changed). If nothing meaningful changed, returns a short current-UI overview.`, {
-        x: z.number().describe('X coordinate to click (use center of element bounds from geometra_query)'),
-        y: z.number().describe('Y coordinate to click'),
+        x: z.number().optional().describe('X coordinate to click (use center of element bounds from geometra_query)'),
+        y: z.number().optional().describe('Y coordinate to click'),
+        ...nodeFilterShape(),
+        index: z.number().int().min(0).optional().default(0).describe('Which matching semantic target to click after sorting top-to-bottom'),
+        fullyVisible: z.boolean().optional().default(true).describe('When clicking by semantic target, require full visibility before clicking (default true)'),
+        maxRevealSteps: z.number().int().min(1).max(12).optional().default(6).describe('Maximum reveal attempts before clicking a semantic target'),
+        revealTimeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .default(2_500)
+            .describe('Per-scroll wait timeout while revealing a semantic target (default 2500ms)'),
+        waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the click'),
         timeoutMs: z
             .number()
             .int()
@@ -911,14 +920,69 @@ 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, timeoutMs, detail }) => {
+    }, async ({ x, y, id, role, name, text, contextText, 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.');
         const before = sessionA11y(session);
-        const wait = await sendClick(session, x, y, timeoutMs);
+        const resolved = await resolveClickLocation(session, {
+            x,
+            y,
+            filter: {
+                id,
+                role,
+                name,
+                text,
+                contextText,
+                value,
+                checked,
+                disabled,
+                focused,
+                selected,
+                expanded,
+                invalid,
+                required,
+                busy,
+            },
+            index,
+            fullyVisible,
+            maxRevealSteps,
+            revealTimeoutMs,
+        });
+        if (!resolved.ok)
+            return err(resolved.error);
+        const wait = await sendClick(session, resolved.value.x, resolved.value.y, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
-        return ok(`Clicked at (${x}, ${y}).\n${summary}`);
+        const clickLine = !resolved.value.target
+            ? `Clicked at (${resolved.value.x}, ${resolved.value.y}).`
+            : `Clicked ${describeFormattedNode(resolved.value.target)} at (${resolved.value.x}, ${resolved.value.y})${resolved.value.revealAttempts && resolved.value.revealAttempts > 0 ? ` after ${resolved.value.revealAttempts} reveal step${resolved.value.revealAttempts === 1 ? '' : 's'}` : ''}.`;
+        const lines = [clickLine, summary];
+        if (waitFor) {
+            const postWait = await waitForSemanticCondition(session, {
+                filter: {
+                    id: waitFor.id,
+                    role: waitFor.role,
+                    name: waitFor.name,
+                    text: waitFor.text,
+                    contextText: waitFor.contextText,
+                    value: waitFor.value,
+                    checked: waitFor.checked,
+                    disabled: waitFor.disabled,
+                    focused: waitFor.focused,
+                    selected: waitFor.selected,
+                    expanded: waitFor.expanded,
+                    invalid: waitFor.invalid,
+                    required: waitFor.required,
+                    busy: waitFor.busy,
+                },
+                present: waitFor.present ?? true,
+                timeoutMs: waitFor.timeoutMs ?? 10_000,
+            });
+            if (!postWait.ok)
+                return err([...lines, postWait.error].join('\n'));
+            lines.push(`Post-click ${waitConditionSuccessLine(postWait.value)}`);
+        }
+        return ok(lines.filter(Boolean).join('\n'));
     });
     // ── 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.
@@ -1188,7 +1252,7 @@ For a token-efficient semantic view, use geometra_snapshot (default compact). Fo
         return ok(JSON.stringify(session.layout, null, 2));
     });
     // ── disconnect ───────────────────────────────────────────────
-    server.tool('geometra_disconnect', `Disconnect from the Geometra server. Proxy-backed sessions keep the browser alive by default so the next geometra_connect can reuse it quickly; pass closeBrowser=true to fully tear down the proxy/browser.`, {
+    server.tool('geometra_disconnect', `Disconnect from the Geometra server. Proxy-backed sessions keep compatible browsers alive by default so the next geometra_connect can reuse them quickly; pass closeBrowser=true to fully tear down the warm proxy/browser pool.`, {
         closeBrowser: z.boolean().optional().default(false).describe('Fully close the spawned proxy/browser instead of keeping it warm for reuse'),
     }, async ({ closeBrowser }) => {
         disconnect({ closeProxy: closeBrowser });
@@ -1338,12 +1402,23 @@ async function stabilizeInlineFormSchemas(session, options, opts) {
 }
 function connectResponsePayload(session, opts) {
     const payload = connectPayload(session, opts);
-    if (!opts.returnForms)
+    if (!opts.returnForms && !opts.returnPageModel)
         return payload;
-    return {
-        ...payload,
-        formSchema: formSchemaResponsePayload(session, opts.formSchema ?? {}),
-    };
+    const nextPayload = { ...payload };
+    if (opts.returnForms) {
+        nextPayload.formSchema = formSchemaResponsePayload(session, opts.formSchema ?? {});
+    }
+    if (opts.returnPageModel) {
+        nextPayload.pageModel = pageModelResponsePayload(session, opts.pageModelOptions);
+    }
+    return nextPayload;
+}
+function pageModelResponsePayload(session, options) {
+    const a11y = sessionA11y(session);
+    if (!a11y) {
+        return { available: false };
+    }
+    return buildPageModel(a11y, options);
 }
 async function ensureToolSession(target, missingConnectionMessage = 'Not connected. Call geometra_connect first.') {
     if (!target.url && !target.pageUrl) {
@@ -1608,6 +1683,154 @@ function waitStatusPayload(wait) {
 function compactFilterPayload(filter) {
     return Object.fromEntries(Object.entries(filter).filter(([, value]) => value !== undefined));
 }
+async function waitForSemanticCondition(session, options) {
+    if (!hasNodeFilter(options.filter)) {
+        return { ok: false, error: GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE };
+    }
+    const startedAt = Date.now();
+    const matched = await waitForUiCondition(session, () => {
+        const a11y = sessionA11y(session);
+        if (!a11y)
+            return false;
+        const matches = findNodes(a11y, options.filter);
+        return options.present ? matches.length > 0 : matches.length === 0;
+    }, options.timeoutMs);
+    const elapsedMs = Date.now() - startedAt;
+    if (!matched) {
+        return {
+            ok: false,
+            error: `Timed out after ${options.timeoutMs}ms waiting for ${options.present ? 'presence' : 'absence'} of ${JSON.stringify(options.filter)}.\nCurrent UI:\n${compactSessionSummary(session)}`,
+        };
+    }
+    const after = sessionA11y(session);
+    const matches = options.present && after
+        ? sortA11yNodes(findNodes(after, options.filter)).slice(0, 8).map(node => formatNode(node, after, after.bounds))
+        : [];
+    return {
+        ok: true,
+        value: {
+            filter: options.filter,
+            present: options.present,
+            elapsedMs,
+            matchCount: matches.length,
+            matches,
+        },
+    };
+}
+function waitConditionSuccessLine(result) {
+    if (!result.present) {
+        return `condition satisfied after ${result.elapsedMs}ms: no nodes matched ${JSON.stringify(result.filter)}.`;
+    }
+    return `condition satisfied after ${result.elapsedMs}ms with ${result.matchCount} matching node(s).`;
+}
+function waitConditionCompact(result) {
+    return {
+        present: result.present,
+        elapsedMs: result.elapsedMs,
+        filter: compactFilterPayload(result.filter),
+        ...(result.present ? { matchCount: result.matchCount } : {}),
+    };
+}
+async function revealSemanticTarget(session, options) {
+    let attempts = 0;
+    while (attempts <= options.maxSteps) {
+        const a11y = sessionA11y(session);
+        if (!a11y)
+            return { ok: false, error: 'No UI tree available to reveal from' };
+        const matches = sortA11yNodes(findNodes(a11y, options.filter));
+        if (matches.length === 0) {
+            return { ok: false, error: `No elements found matching ${JSON.stringify(options.filter)}` };
+        }
+        if (options.index >= matches.length) {
+            return {
+                ok: false,
+                error: `Requested reveal index ${options.index} but only ${matches.length} matching element(s) were found`,
+            };
+        }
+        const formatted = formatNode(matches[options.index], a11y, a11y.bounds);
+        const visible = options.fullyVisible ? formatted.visibility.fullyVisible : formatted.visibility.intersectsViewport;
+        if (visible) {
+            return {
+                ok: true,
+                value: {
+                    attempts,
+                    target: formatted,
+                },
+            };
+        }
+        if (attempts === options.maxSteps) {
+            return {
+                ok: false,
+                error: 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,
+        }, options.timeoutMs);
+        attempts++;
+    }
+    return { ok: false, error: `Failed to reveal ${JSON.stringify(options.filter)}` };
+}
+async function resolveClickLocation(session, options) {
+    const hasExplicitCoordinates = options.x !== undefined || options.y !== undefined;
+    if (hasExplicitCoordinates) {
+        if (options.x === undefined || options.y === undefined) {
+            return { ok: false, error: 'Provide both x and y when clicking by coordinates' };
+        }
+        return {
+            ok: true,
+            value: {
+                x: options.x,
+                y: options.y,
+            },
+        };
+    }
+    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)',
+        };
+    }
+    const revealed = await revealSemanticTarget(session, {
+        filter: options.filter,
+        index: options.index ?? 0,
+        fullyVisible: options.fullyVisible ?? true,
+        maxSteps: options.maxRevealSteps ?? 6,
+        timeoutMs: options.revealTimeoutMs ?? 2_500,
+    });
+    if (!revealed.ok)
+        return revealed;
+    return {
+        ok: true,
+        value: {
+            x: revealed.value.target.center.x,
+            y: revealed.value.target.center.y,
+            target: revealed.value.target,
+            revealAttempts: revealed.value.attempts,
+        },
+    };
+}
+function describeFormattedNode(node) {
+    return `${node.role}${node.name ? ` ${JSON.stringify(node.name)}` : ''} (${node.id})`;
+}
+function compactNodeReference(node) {
+    return {
+        id: node.id,
+        role: node.role,
+        ...(node.name ? { name: node.name } : {}),
+    };
+}
 function normalizeLookupKey(value) {
     return value.replace(/\s+/g, ' ').trim().toLowerCase();
 }
@@ -1817,12 +2040,72 @@ async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {
             const before = sessionA11y(session);
-            const wait = await sendClick(session, action.x, action.y, action.timeoutMs);
+            const resolved = await resolveClickLocation(session, {
+                x: action.x,
+                y: action.y,
+                filter: {
+                    id: action.id,
+                    role: action.role,
+                    name: action.name,
+                    text: action.text,
+                    contextText: action.contextText,
+                    value: action.value,
+                    checked: action.checked,
+                    disabled: action.disabled,
+                    focused: action.focused,
+                    selected: action.selected,
+                    expanded: action.expanded,
+                    invalid: action.invalid,
+                    required: action.required,
+                    busy: action.busy,
+                },
+                index: action.index,
+                fullyVisible: action.fullyVisible,
+                maxRevealSteps: action.maxRevealSteps,
+                revealTimeoutMs: action.revealTimeoutMs,
+            });
+            if (!resolved.ok)
+                throw new Error(resolved.error);
+            const wait = await sendClick(session, resolved.value.x, resolved.value.y, action.timeoutMs);
+            const targetSummary = resolved.value.target
+                ? `Clicked ${describeFormattedNode(resolved.value.target)} at (${resolved.value.x}, ${resolved.value.y}).`
+                : `Clicked at (${resolved.value.x}, ${resolved.value.y}).`;
+            let postWaitSummary;
+            let postWaitCompact;
+            if (action.waitFor) {
+                const postWait = await waitForSemanticCondition(session, {
+                    filter: {
+                        id: action.waitFor.id,
+                        role: action.waitFor.role,
+                        name: action.waitFor.name,
+                        text: action.waitFor.text,
+                        contextText: action.waitFor.contextText,
+                        value: action.waitFor.value,
+                        checked: action.waitFor.checked,
+                        disabled: action.waitFor.disabled,
+                        focused: action.waitFor.focused,
+                        selected: action.waitFor.selected,
+                        expanded: action.waitFor.expanded,
+                        invalid: action.waitFor.invalid,
+                        required: action.waitFor.required,
+                        busy: action.waitFor.busy,
+                    },
+                    present: action.waitFor.present ?? true,
+                    timeoutMs: action.waitFor.timeoutMs ?? 10_000,
+                });
+                if (!postWait.ok) {
+                    throw new Error(`Post-click wait failed after ${targetSummary.toLowerCase()}\n${postWait.error}`);
+                }
+                postWaitSummary = `Post-click ${waitConditionSuccessLine(postWait.value)}`;
+                postWaitCompact = waitConditionCompact(postWait.value);
+            }
             return {
-                summary: `Clicked at (${action.x}, ${action.y}).\n${postActionSummary(session, before, wait, detail)}`,
+                summary: [targetSummary, postActionSummary(session, before, wait, detail), postWaitSummary].filter(Boolean).join('\n'),
                 compact: {
-                    at: { x: action.x, y: action.y },
+                    at: { x: resolved.value.x, y: resolved.value.y },
+                    ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
                     ...waitStatusPayload(wait),
+                    ...(postWaitCompact ? { postWait: postWaitCompact } : {}),
                 },
             };
         }
@@ -1946,80 +2229,44 @@ async function executeBatchAction(session, action, detail, includeSteps) {
         case 'wait_for': {
             if (!session.tree || !session.layout)
                 throw new Error('Not connected. Call geometra_connect first.');
-            const filter = {
-                id: action.id,
-                role: action.role,
-                name: action.name,
-                text: action.text,
-                contextText: action.contextText,
-                value: action.value,
-                checked: action.checked,
-                disabled: action.disabled,
-                focused: action.focused,
-                selected: action.selected,
-                expanded: action.expanded,
-                invalid: action.invalid,
-                required: action.required,
-                busy: action.busy,
-            };
-            if (!hasNodeFilter(filter)) {
-                throw new Error('wait_for step requires at least one filter');
-            }
-            const present = action.present ?? true;
-            const timeoutMs = action.timeoutMs ?? 10_000;
-            const startedAt = Date.now();
-            const matched = await waitForUiCondition(session, () => {
-                const a11y = sessionA11y(session);
-                if (!a11y)
-                    return false;
-                const matches = findNodes(a11y, filter);
-                return present ? matches.length > 0 : matches.length === 0;
-            }, timeoutMs);
-            const elapsedMs = Date.now() - startedAt;
-            if (!matched) {
-                throw new Error(`Timed out after ${timeoutMs}ms waiting for ${present ? 'presence' : 'absence'} of ${JSON.stringify(filter)}`);
-            }
-            if (!present) {
-                return {
-                    summary: `Condition satisfied after ${elapsedMs}ms: no nodes matched ${JSON.stringify(filter)}.`,
-                    compact: {
-                        present,
-                        elapsedMs,
-                        filter: compactFilterPayload(filter),
-                    },
-                };
+            const waited = await waitForSemanticCondition(session, {
+                filter: {
+                    id: action.id,
+                    role: action.role,
+                    name: action.name,
+                    text: action.text,
+                    contextText: action.contextText,
+                    value: action.value,
+                    checked: action.checked,
+                    disabled: action.disabled,
+                    focused: action.focused,
+                    selected: action.selected,
+                    expanded: action.expanded,
+                    invalid: action.invalid,
+                    required: action.required,
+                    busy: action.busy,
+                },
+                present: action.present ?? true,
+                timeoutMs: action.timeoutMs ?? 10_000,
+            });
+            if (!waited.ok) {
+                throw new Error(waited.error);
             }
-            const after = sessionA11y(session);
-            if (!after) {
+            if (!waited.value.present) {
                 return {
-                    summary: `Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`,
-                    compact: {
-                        present,
-                        elapsedMs,
-                        filter: compactFilterPayload(filter),
-                    },
+                    summary: waitConditionSuccessLine(waited.value),
+                    compact: waitConditionCompact(waited.value),
                 };
             }
-            const matches = findNodes(after, filter);
             if (detail === 'verbose') {
                 return {
-                    summary: JSON.stringify(sortA11yNodes(matches).slice(0, 8).map(node => formatNode(node, after, after.bounds)), null, 2),
-                    compact: {
-                        present,
-                        elapsedMs,
-                        matchCount: matches.length,
-                        filter: compactFilterPayload(filter),
-                    },
+                    summary: JSON.stringify(waited.value.matches, null, 2),
+                    compact: waitConditionCompact(waited.value),
                 };
             }
             return {
-                summary: `Condition satisfied after ${elapsedMs}ms with ${matches.length} matching node(s).`,
-                compact: {
-                    present,
-                    elapsedMs,
-                    matchCount: matches.length,
-                    filter: compactFilterPayload(filter),
-                },
+                summary: waitConditionSuccessLine(waited.value),
+                compact: waitConditionCompact(waited.value),
             };
         }
         case 'fill_fields': {