@geometra/mcp 1.19.5 → 1.19.7

package/README.md

@@ -26,7 +26,7 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
 | `geometra_upload_files` | Attach files: auto / hidden input / native chooser / synthetic drop (`@geometra/proxy` only) |
-| `geometra_pick_listbox_option` | Pick `role=option` (React Select, Headless UI, etc.; `@geometra/proxy` only) |
+| `geometra_pick_listbox_option` | Pick an option from a custom dropdown/searchable combobox; can open by field label (`@geometra/proxy` only) |
 | `geometra_select_option` | Choose an option on a native `<select>` (`@geometra/proxy` only) |
 | `geometra_set_checked` | Set a checkbox or radio by label instead of coordinate clicks (`@geometra/proxy` only) |
 | `geometra_wheel` | Mouse wheel / scroll (`@geometra/proxy` only) |

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

@@ -1,10 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+import { buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
 function node(role, name, bounds, options) {
     return {
         role,
         ...(name ? { name } : {}),
         ...(options?.state ? { state: options.state } : {}),
+        ...(options?.meta ? { meta: options.meta } : {}),
         bounds,
         path: options?.path ?? [],
         children: options?.children ?? [],
@@ -222,4 +223,61 @@ describe('buildUiDelta', () => {
         expect(delta.updated.some(update => update.after.role === 'checkbox' && update.changes.includes('checked false -> true'))).toBe(true);
         expect(summary).toContain('~ n:0.0 checkbox "New York, NY": checked false -> true');
     });
+    it('keeps pinned context nodes and reports viewport/focus/navigation drift', () => {
+        const before = node('group', undefined, { x: 0, y: 0, width: 900, height: 700 }, {
+            meta: { pageUrl: 'https://jobs.example.com/apply', scrollX: 0, scrollY: 120 },
+            children: [
+                node('tablist', 'Application tabs', { x: 16, y: -64, width: 420, height: 40 }, { path: [0] }),
+                node('form', 'Application', { x: 24, y: -20, width: 760, height: 1400 }, {
+                    path: [1],
+                    children: [
+                        node('textbox', 'Full name', { x: 48, y: 140, width: 320, height: 36 }, {
+                            path: [1, 0],
+                            focusable: true,
+                            state: { focused: true },
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const after = node('group', undefined, { x: 0, y: 0, width: 900, height: 700 }, {
+            meta: { pageUrl: 'https://jobs.example.com/apply?step=details', scrollX: 0, scrollY: 420 },
+            children: [
+                node('tablist', 'Application tabs', { x: 16, y: -96, width: 420, height: 40 }, { path: [0] }),
+                node('form', 'Application', { x: 24, y: -320, width: 760, height: 1400 }, {
+                    path: [1],
+                    children: [
+                        node('textbox', 'Country', { x: 48, y: 182, width: 320, height: 36 }, {
+                            path: [1, 1],
+                            focusable: true,
+                            state: { focused: true },
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const compact = buildCompactUiIndex(before, { maxNodes: 20 });
+        expect(compact.context.pageUrl).toBe('https://jobs.example.com/apply');
+        expect(compact.context.scrollY).toBe(120);
+        expect(compact.context.focusedNode?.name).toBe('Full name');
+        expect(compact.nodes.some(item => item.role === 'tablist' && item.pinned)).toBe(true);
+        expect(compact.nodes.some(item => item.role === 'form' && item.pinned)).toBe(true);
+        const delta = buildUiDelta(before, after);
+        const summary = summarizeUiDelta(delta);
+        expect(delta.navigation).toEqual({
+            beforeUrl: 'https://jobs.example.com/apply',
+            afterUrl: 'https://jobs.example.com/apply?step=details',
+        });
+        expect(delta.viewport).toEqual({
+            beforeScrollX: 0,
+            beforeScrollY: 120,
+            afterScrollX: 0,
+            afterScrollY: 420,
+        });
+        expect(delta.focus?.before?.name).toBe('Full name');
+        expect(delta.focus?.after?.name).toBe('Country');
+        expect(summary).toContain('~ viewport scroll (0,120) -> (0,420)');
+        expect(summary).toContain('~ focus n:1.0 textbox "Full name" -> n:1.1 textbox "Country"');
+        expect(summary).toContain('~ navigation "https://jobs.example.com/apply" -> "https://jobs.example.com/apply?step=details"');
+    });
 });

package/dist/server.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
 import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, } from './session.js';
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.5' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.7' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -69,7 +69,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
         }
     });
     // ── query ────────────────────────────────────────────────────
-    server.tool('geometra_query', `Find elements in the current Geometra UI by stable id, role, name, or text content. Returns matching elements with their exact pixel bounds {x, y, width, height}, role, name, and tree path.
+    server.tool('geometra_query', `Find elements in the current Geometra UI by stable id, role, name, or text content. Returns matching elements with their exact pixel bounds {x, y, width, height}, visible in-viewport bounds, an on-screen center point, role, name, and tree path.
 
 This is the Geometra equivalent of Playwright's locator — but instant, structured, and with no browser. Use the returned bounds to click elements or assert on layout.`, {
         id: z.string().optional().describe('Stable node id from geometra_snapshot or geometra_expand_section'),
@@ -85,7 +85,7 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
         if (matches.length === 0) {
             return ok(`No elements found matching ${JSON.stringify({ id, role, name, text })}`);
         }
-        const result = matches.map(formatNode);
+        const result = matches.map(node => formatNode(node, a11y.bounds));
         return ok(JSON.stringify(result, null, 2));
     });
     // ── page model ────────────────────────────────────────────────
@@ -221,14 +221,16 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
             return err(e.message);
         }
     });
-    server.tool('geometra_pick_listbox_option', `Pick a visible \`role=option\` (Headless UI, React Select, Radix, etc.). Requires \`@geometra/proxy\`.
+    server.tool('geometra_pick_listbox_option', `Pick an option from a custom dropdown / listbox / searchable combobox (Headless UI, React Select, Radix, Ashby-style custom selects, etc.). Requires \`@geometra/proxy\`.
 
-Optional openX,openY clicks the combobox first if the list is not open. Uses substring name match unless exact=true.`, {
+Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying on coordinates. If the opened control is editable, MCP types \`query\` (or the option label by default) before selecting. Uses substring name match unless exact=true.`, {
         label: z.string().describe('Accessible name of the option (visible text or aria-label)'),
         exact: z.boolean().optional().describe('Exact name match'),
         openX: z.number().optional().describe('Click to open dropdown'),
         openY: z.number().optional().describe('Click to open dropdown'),
-    }, async ({ label, exact, openX, openY }) => {
+        fieldLabel: z.string().optional().describe('Field label of the dropdown/combobox to open semantically (e.g. "Location")'),
+        query: z.string().optional().describe('Optional text to type into a searchable combobox before selecting'),
+    }, async ({ label, exact, openX, openY, fieldLabel, query }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -237,6 +239,8 @@ Optional openX,openY clicks the combobox first if the list is not open. Uses sub
             const wait = await sendListboxPick(session, label, {
                 exact,
                 open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
+                fieldLabel,
+                query,
             });
             const summary = postActionSummary(session, before, wait);
             return ok(`Picked listbox option "${label}".\n${summary}`);
@@ -313,7 +317,7 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         }
     });
     // ── snapshot ─────────────────────────────────────────────────
-    server.tool('geometra_snapshot', `Get the current UI as JSON. Default **compact** view: flat list of viewport-visible actionable nodes (links, buttons, inputs, headings, landmarks, text leaves, focusable elements) with bounds and tree paths — far fewer tokens than a full nested tree. Use **full** for complete nested a11y + every wrapper when debugging layout.
+    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.
 
 JSON is minified in compact view to save tokens. For a summary-first overview, use geometra_page_model, then geometra_expand_section for just the part you want.`, {
         view: z
@@ -337,10 +341,11 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
         if (view === 'full') {
             return ok(JSON.stringify(a11y, null, 2));
         }
-        const { nodes, truncated } = buildCompactUiIndex(a11y, { maxNodes });
+        const { nodes, truncated, context } = buildCompactUiIndex(a11y, { maxNodes });
         const payload = {
             view: 'compact',
             viewport: { width: a11y.bounds.width, height: a11y.bounds.height },
+            context,
             nodes,
             truncated,
         };
@@ -376,13 +381,17 @@ function sessionA11y(session) {
 }
 function sessionOverviewFromA11y(a11y) {
     const pageSummary = summarizePageModel(buildPageModel(a11y), 8);
-    const { nodes } = buildCompactUiIndex(a11y, { maxNodes: 32 });
+    const { nodes, context } = buildCompactUiIndex(a11y, { maxNodes: 32 });
+    const contextSummary = summarizeCompactContext(context);
     const keyNodes = nodes.length > 0 ? `Key nodes:\n${summarizeCompactIndex(nodes, 18)}` : '';
-    return [pageSummary, keyNodes].filter(Boolean).join('\n');
+    return [pageSummary, contextSummary, keyNodes].filter(Boolean).join('\n');
 }
 function postActionSummary(session, before, wait) {
     const after = sessionA11y(session);
     const notes = [];
+    if (wait?.status === 'acknowledged') {
+        notes.push('Proxy acknowledged the action quickly; waiting logic did not need to rely on a full frame/patch round-trip.');
+    }
     if (wait?.status === 'timed_out') {
         notes.push(`No frame or patch arrived within ${wait.timeoutMs}ms after the action. The action may still have succeeded if it did not change geometry or semantics.`);
     }
@@ -396,6 +405,19 @@ function postActionSummary(session, before, wait) {
     }
     return [...notes, `Current UI:\n${sessionOverviewFromA11y(after)}`].filter(Boolean).join('\n');
 }
+function summarizeCompactContext(context) {
+    const parts = [];
+    if (context.pageUrl)
+        parts.push(`url=${context.pageUrl}`);
+    if (typeof context.scrollX === 'number' || typeof context.scrollY === 'number') {
+        parts.push(`scroll=(${context.scrollX ?? 0},${context.scrollY ?? 0})`);
+    }
+    if (context.focusedNode) {
+        const focusName = context.focusedNode.name ? ` "${context.focusedNode.name}"` : '';
+        parts.push(`focus=${context.focusedNode.role}${focusName}`);
+    }
+    return parts.length > 0 ? `Context: ${parts.join(' | ')}` : '';
+}
 function ok(text) {
     return { content: [{ type: 'text', text }] };
 }
@@ -422,15 +444,32 @@ function findNodes(node, filter) {
     walk(node);
     return matches;
 }
-function formatNode(node) {
+function formatNode(node, viewport) {
+    const visibleLeft = Math.max(0, node.bounds.x);
+    const visibleTop = Math.max(0, node.bounds.y);
+    const visibleRight = Math.min(viewport.width, node.bounds.x + node.bounds.width);
+    const visibleBottom = Math.min(viewport.height, node.bounds.y + node.bounds.height);
+    const hasVisibleIntersection = visibleRight > visibleLeft && visibleBottom > visibleTop;
+    const centerX = hasVisibleIntersection
+        ? Math.round((visibleLeft + visibleRight) / 2)
+        : Math.round(Math.min(Math.max(node.bounds.x + node.bounds.width / 2, 0), viewport.width));
+    const centerY = hasVisibleIntersection
+        ? Math.round((visibleTop + visibleBottom) / 2)
+        : Math.round(Math.min(Math.max(node.bounds.y + node.bounds.height / 2, 0), viewport.height));
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         name: node.name,
         bounds: node.bounds,
+        visibleBounds: {
+            x: visibleLeft,
+            y: visibleTop,
+            width: Math.max(0, visibleRight - visibleLeft),
+            height: Math.max(0, visibleBottom - visibleTop),
+        },
         center: {
-            x: Math.round(node.bounds.x + node.bounds.width / 2),
-            y: Math.round(node.bounds.y + node.bounds.height / 2),
+            x: centerX,
+            y: centerY,
         },
         focusable: node.focusable,
         ...(node.state && Object.keys(node.state).length > 0 ? { state: node.state } : {}),

package/dist/session.d.ts

@@ -13,6 +13,12 @@ export interface A11yNode {
         expanded?: boolean;
         selected?: boolean;
         checked?: boolean | 'mixed';
+        focused?: boolean;
+    };
+    meta?: {
+        pageUrl?: string;
+        scrollX?: number;
+        scrollY?: number;
     };
     bounds: {
         x: number;
@@ -30,6 +36,7 @@ export interface CompactUiNode {
     role: string;
     name?: string;
     state?: A11yNode['state'];
+    pinned?: boolean;
     bounds: {
         x: number;
         y: number;
@@ -39,6 +46,12 @@ export interface CompactUiNode {
     path: number[];
     focusable: boolean;
 }
+export interface CompactUiContext {
+    pageUrl?: string;
+    scrollX?: number;
+    scrollY?: number;
+    focusedNode?: CompactUiNode;
+}
 export type PageSectionKind = 'landmark' | 'form' | 'dialog' | 'list';
 export type PageArchetype = 'shell' | 'form' | 'dialog' | 'results' | 'content' | 'dashboard';
 interface PageSectionSummaryBase {
@@ -177,6 +190,20 @@ export interface UiListCountChange {
     beforeCount: number;
     afterCount: number;
 }
+export interface UiNavigationChange {
+    beforeUrl?: string;
+    afterUrl?: string;
+}
+export interface UiViewportChange {
+    beforeScrollX?: number;
+    beforeScrollY?: number;
+    afterScrollX?: number;
+    afterScrollY?: number;
+}
+export interface UiFocusChange {
+    before?: CompactUiNode;
+    after?: CompactUiNode;
+}
 /** Semantic delta between two compact viewport models. */
 export interface UiDelta {
     added: CompactUiNode[];
@@ -187,6 +214,9 @@ export interface UiDelta {
     formsAppeared: PageFormModel[];
     formsRemoved: PageFormModel[];
     listCountsChanged: UiListCountChange[];
+    navigation?: UiNavigationChange;
+    viewport?: UiViewportChange;
+    focus?: UiFocusChange;
 }
 export interface Session {
     ws: WebSocket;
@@ -197,7 +227,7 @@ export interface Session {
     proxyChild?: ChildProcess;
 }
 export interface UpdateWaitResult {
-    status: 'updated' | 'timed_out';
+    status: 'updated' | 'acknowledged' | 'timed_out';
     timeoutMs: number;
 }
 /**
@@ -258,6 +288,8 @@ export declare function sendListboxPick(session: Session, label: string, opts?:
         x: number;
         y: number;
     };
+    fieldLabel?: string;
+    query?: string;
 }): Promise<UpdateWaitResult>;
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
 export declare function sendSelectOption(session: Session, x: number, y: number, option: {
@@ -295,6 +327,7 @@ export declare function buildCompactUiIndex(root: A11yNode, options?: {
 }): {
     nodes: CompactUiNode[];
     truncated: boolean;
+    context: CompactUiContext;
 };
 export declare function summarizeCompactIndex(nodes: CompactUiNode[], maxLines?: number): string;
 /**

package/dist/session.js

@@ -204,6 +204,10 @@ export function sendListboxPick(session, label, opts) {
         payload.openX = opts.open.x;
         payload.openY = opts.open.y;
     }
+    if (opts?.fieldLabel)
+        payload.fieldLabel = opts.fieldLabel;
+    if (opts?.query)
+        payload.query = opts.query;
     return sendAndWaitForUpdate(session, payload);
 }
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
@@ -258,8 +262,18 @@ const COMPACT_INDEX_ROLES = new Set([
     'main',
     'form',
     'article',
+    'tablist',
+    'tab',
     'listitem',
 ]);
+const PINNED_CONTEXT_ROLES = new Set([
+    'navigation',
+    'main',
+    'form',
+    'dialog',
+    'tablist',
+    'tab',
+]);
 const LANDMARK_ROLES = new Set([
     'banner',
     'navigation',
@@ -387,6 +401,45 @@ function intersectsViewport(b, vw, vh) {
         b.x < vw &&
         b.y < vh);
 }
+function intersectsViewportWithMargin(b, vw, vh, marginY) {
+    return (b.width > 0 &&
+        b.height > 0 &&
+        b.x + b.width > 0 &&
+        b.x < vw &&
+        b.y + b.height > -marginY &&
+        b.y < vh + marginY);
+}
+function compactNodeFromA11y(node, pinned = false) {
+    const name = sanitizeInlineName(node.name, 240);
+    return {
+        id: nodeIdForPath(node.path),
+        role: node.role,
+        ...(name ? { name } : {}),
+        ...(node.state && Object.keys(node.state).length > 0 ? { state: node.state } : {}),
+        ...(pinned ? { pinned: true } : {}),
+        bounds: { ...node.bounds },
+        path: node.path,
+        focusable: node.focusable,
+    };
+}
+function pinnedRolePriority(role) {
+    if (role === 'tablist')
+        return 0;
+    if (role === 'tab')
+        return 1;
+    if (role === 'form')
+        return 2;
+    if (role === 'dialog')
+        return 3;
+    if (role === 'navigation')
+        return 4;
+    if (role === 'main')
+        return 5;
+    return 6;
+}
+function shouldPinCompactContextNode(node) {
+    return PINNED_CONTEXT_ROLES.has(node.role) || node.state?.focused === true;
+}
 function includeInCompactIndex(n) {
     if (n.focusable)
         return true;
@@ -404,34 +457,60 @@ export function buildCompactUiIndex(root, options) {
     const vw = options?.viewportWidth ?? root.bounds.width;
     const vh = options?.viewportHeight ?? root.bounds.height;
     const maxNodes = options?.maxNodes ?? 400;
-    const acc = [];
-    function walk(n) {
-        if (includeInCompactIndex(n) && intersectsViewport(n.bounds, vw, vh)) {
-            const name = sanitizeInlineName(n.name, 240);
-            acc.push({
-                id: nodeIdForPath(n.path),
-                role: n.role,
-                ...(name ? { name } : {}),
-                ...(n.state && Object.keys(n.state).length > 0 ? { state: n.state } : {}),
-                bounds: { ...n.bounds },
-                path: n.path,
-                focusable: n.focusable,
-            });
+    const visibleNodes = [];
+    const pinnedNodes = new Map();
+    const marginY = Math.round(vh * 0.6);
+    function pinNode(node) {
+        if (!shouldPinCompactContextNode(node))
+            return;
+        pinnedNodes.set(nodeIdForPath(node.path), compactNodeFromA11y(node, true));
+    }
+    function walk(n, ancestors) {
+        const visibleSelf = includeInCompactIndex(n) && intersectsViewport(n.bounds, vw, vh);
+        if (visibleSelf) {
+            visibleNodes.push(compactNodeFromA11y(n));
+            for (const ancestor of ancestors) {
+                pinNode(ancestor);
+            }
+        }
+        if (shouldPinCompactContextNode(n) && intersectsViewportWithMargin(n.bounds, vw, vh, marginY)) {
+            pinNode(n);
         }
         for (const c of n.children)
-            walk(c);
+            walk(c, [...ancestors, n]);
     }
-    walk(root);
-    acc.sort((a, b) => {
+    walk(root, []);
+    const merged = new Map();
+    for (const node of pinnedNodes.values()) {
+        merged.set(node.id, node);
+    }
+    for (const node of visibleNodes) {
+        const existing = merged.get(node.id);
+        merged.set(node.id, existing?.pinned ? { ...node, pinned: true } : node);
+    }
+    const nodes = [...merged.values()];
+    nodes.sort((a, b) => {
+        if ((a.pinned ?? false) !== (b.pinned ?? false))
+            return a.pinned ? -1 : 1;
+        if (a.pinned && b.pinned && a.role !== b.role) {
+            return pinnedRolePriority(a.role) - pinnedRolePriority(b.role);
+        }
         if (a.focusable !== b.focusable)
             return a.focusable ? -1 : 1;
         if (a.bounds.y !== b.bounds.y)
             return a.bounds.y - b.bounds.y;
         return a.bounds.x - b.bounds.x;
     });
-    if (acc.length > maxNodes)
-        return { nodes: acc.slice(0, maxNodes), truncated: true };
-    return { nodes: acc, truncated: false };
+    const focusedNode = nodes.find(node => node.state?.focused);
+    const context = {
+        ...(root.meta?.pageUrl ? { pageUrl: root.meta.pageUrl } : {}),
+        ...(typeof root.meta?.scrollX === 'number' ? { scrollX: root.meta.scrollX } : {}),
+        ...(typeof root.meta?.scrollY === 'number' ? { scrollY: root.meta.scrollY } : {}),
+        ...(focusedNode ? { focusedNode } : {}),
+    };
+    if (nodes.length > maxNodes)
+        return { nodes: nodes.slice(0, maxNodes), truncated: true, context };
+    return { nodes, truncated: false, context };
 }
 export function summarizeCompactIndex(nodes, maxLines = 80) {
     const lines = [];
@@ -440,8 +519,9 @@ export function summarizeCompactIndex(nodes, maxLines = 80) {
         const nm = n.name ? ` "${truncateUiText(n.name, 48)}"` : '';
         const st = n.state && Object.keys(n.state).length ? ` ${JSON.stringify(n.state)}` : '';
         const foc = n.focusable ? ' *' : '';
+        const pin = n.pinned ? ' [pinned]' : '';
         const b = n.bounds;
-        lines.push(`${n.id} ${n.role}${nm} (${b.x},${b.y} ${b.width}x${b.height})${st}${foc}`);
+        lines.push(`${n.id} ${n.role}${nm}${pin} (${b.x},${b.y} ${b.width}x${b.height})${st}${foc}`);
     }
     if (nodes.length > maxLines) {
         lines.push(`… and ${nodes.length - maxLines} more (use geometra_snapshot with a higher maxNodes or geometra_query)`);
@@ -463,6 +543,8 @@ function cloneState(state) {
         next.selected = state.selected;
     if (state.checked !== undefined)
         next.checked = state.checked;
+    if (state.focused !== undefined)
+        next.focused = state.focused;
     return Object.keys(next).length > 0 ? next : undefined;
 }
 function clonePath(path) {
@@ -848,7 +930,7 @@ function diffCompactNodes(before, after) {
     }
     const beforeState = before.state ?? {};
     const afterState = after.state ?? {};
-    for (const key of ['disabled', 'expanded', 'selected', 'checked']) {
+    for (const key of ['disabled', 'expanded', 'selected', 'checked', 'focused']) {
         if (beforeState[key] !== afterState[key]) {
             changes.push(`${key} ${formatStateValue(beforeState[key])} -> ${formatStateValue(afterState[key])}`);
         }
@@ -869,8 +951,10 @@ function pageContainerKey(value) {
  */
 export function buildUiDelta(before, after, options) {
     const maxNodes = options?.maxNodes ?? 250;
-    const beforeCompact = buildCompactUiIndex(before, { maxNodes }).nodes;
-    const afterCompact = buildCompactUiIndex(after, { maxNodes }).nodes;
+    const beforeIndex = buildCompactUiIndex(before, { maxNodes });
+    const afterIndex = buildCompactUiIndex(after, { maxNodes });
+    const beforeCompact = beforeIndex.nodes;
+    const afterCompact = afterIndex.nodes;
     const beforeMap = new Map(beforeCompact.map(node => [node.id, node]));
     const afterMap = new Map(afterCompact.map(node => [node.id, node]));
     const added = [];
@@ -922,6 +1006,26 @@ export function buildUiDelta(before, after, options) {
             });
         }
     }
+    const navigation = beforeIndex.context.pageUrl !== afterIndex.context.pageUrl
+        ? {
+            beforeUrl: beforeIndex.context.pageUrl,
+            afterUrl: afterIndex.context.pageUrl,
+        }
+        : undefined;
+    const viewport = beforeIndex.context.scrollX !== afterIndex.context.scrollX || beforeIndex.context.scrollY !== afterIndex.context.scrollY
+        ? {
+            beforeScrollX: beforeIndex.context.scrollX,
+            beforeScrollY: beforeIndex.context.scrollY,
+            afterScrollX: afterIndex.context.scrollX,
+            afterScrollY: afterIndex.context.scrollY,
+        }
+        : undefined;
+    const focus = beforeIndex.context.focusedNode?.id !== afterIndex.context.focusedNode?.id
+        ? {
+            before: beforeIndex.context.focusedNode,
+            after: afterIndex.context.focusedNode,
+        }
+        : undefined;
     return {
         added,
         removed,
@@ -931,6 +1035,9 @@ export function buildUiDelta(before, after, options) {
         formsAppeared,
         formsRemoved,
         listCountsChanged,
+        ...(navigation ? { navigation } : {}),
+        ...(viewport ? { viewport } : {}),
+        ...(focus ? { focus } : {}),
     };
 }
 export function hasUiDelta(delta) {
@@ -941,10 +1048,24 @@ export function hasUiDelta(delta) {
         delta.dialogsClosed.length > 0 ||
         delta.formsAppeared.length > 0 ||
         delta.formsRemoved.length > 0 ||
-        delta.listCountsChanged.length > 0);
+        delta.listCountsChanged.length > 0 ||
+        !!delta.navigation ||
+        !!delta.viewport ||
+        !!delta.focus);
 }
 export function summarizeUiDelta(delta, maxLines = 14) {
     const lines = [];
+    if (delta.navigation) {
+        lines.push(`~ navigation ${JSON.stringify(delta.navigation.beforeUrl ?? 'unknown')} -> ${JSON.stringify(delta.navigation.afterUrl ?? 'unknown')}`);
+    }
+    if (delta.viewport) {
+        lines.push(`~ viewport scroll (${delta.viewport.beforeScrollX ?? 0},${delta.viewport.beforeScrollY ?? 0}) -> (${delta.viewport.afterScrollX ?? 0},${delta.viewport.afterScrollY ?? 0})`);
+    }
+    if (delta.focus) {
+        const beforeLabel = delta.focus.before ? compactNodeLabel(delta.focus.before) : 'unset';
+        const afterLabel = delta.focus.after ? compactNodeLabel(delta.focus.after) : 'unset';
+        lines.push(`~ focus ${beforeLabel} -> ${afterLabel}`);
+    }
     for (const dialog of delta.dialogsOpened.slice(0, 2)) {
         lines.push(`+ ${dialog.id} dialog${dialog.name ? ` "${truncateUiText(dialog.name, 40)}"` : ''} opened`);
     }
@@ -1040,6 +1161,15 @@ function walkNode(element, layout, path) {
     const checked = normalizeCheckedState(semantic?.ariaChecked);
     if (checked !== undefined)
         state.checked = checked;
+    if (semantic?.focused !== undefined)
+        state.focused = !!semantic.focused;
+    const meta = {};
+    if (typeof semantic?.pageUrl === 'string')
+        meta.pageUrl = semantic.pageUrl;
+    if (typeof semantic?.scrollX === 'number' && Number.isFinite(semantic.scrollX))
+        meta.scrollX = semantic.scrollX;
+    if (typeof semantic?.scrollY === 'number' && Number.isFinite(semantic.scrollY))
+        meta.scrollY = semantic.scrollY;
     const children = [];
     const elementChildren = element.children;
     const layoutChildren = layout.children;
@@ -1054,6 +1184,7 @@ function walkNode(element, layout, path) {
         role,
         ...(name ? { name } : {}),
         ...(Object.keys(state).length > 0 ? { state } : {}),
+        ...(Object.keys(meta).length > 0 ? { meta } : {}),
         bounds,
         path,
         children,
@@ -1158,6 +1289,10 @@ function waitForNextUpdate(session) {
                     cleanup();
                     resolve({ status: 'updated', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
                 }
+                else if (msg.type === 'ack') {
+                    cleanup();
+                    resolve({ status: 'acknowledged', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
+                }
             }
             catch { /* ignore */ }
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.19.5",
+  "version": "1.19.7",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "ui-testing"
   ],
   "dependencies": {
-    "@geometra/proxy": "1.19.5",
+    "@geometra/proxy": "^1.19.7",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.18.0",
     "zod": "^3.23.0"