@geometra/mcp 1.19.6 → 1.19.8

package/dist/__tests__/proxy-session-actions.test.d.ts

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

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

@@ -0,0 +1,59 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { WebSocketServer } from 'ws';
+import { connect, disconnect, sendListboxPick } from '../session.js';
+describe('proxy-backed MCP actions', () => {
+    afterAll(() => {
+        disconnect();
+    });
+    it('waits for final listbox outcome instead of resolving on intermediate updates', async () => {
+        const wss = new WebSocketServer({ port: 0 });
+        wss.on('connection', ws => {
+            ws.on('message', raw => {
+                const msg = JSON.parse(String(raw));
+                if (msg.type === 'resize') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: { kind: 'box', props: {}, semantic: { tag: 'body', role: 'group' }, children: [] },
+                    }));
+                    return;
+                }
+                if (msg.type === 'listboxPick') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: { kind: 'box', props: {}, semantic: { tag: 'body', role: 'group' }, children: [] },
+                    }));
+                    setTimeout(() => {
+                        ws.send(JSON.stringify({
+                            type: 'error',
+                            requestId: msg.requestId,
+                            message: 'listboxPick: no visible option matching \"Japan\"',
+                        }));
+                    }, 20);
+                }
+            });
+        });
+        const port = await new Promise((resolve, reject) => {
+            wss.once('listening', () => {
+                const address = wss.address();
+                if (typeof address === 'object' && address)
+                    resolve(address.port);
+                else
+                    reject(new Error('Failed to resolve ephemeral WebSocket port'));
+            });
+            wss.once('error', reject);
+        });
+        try {
+            const session = await connect(`ws://127.0.0.1:${port}`);
+            await expect(sendListboxPick(session, 'Japan', {
+                fieldLabel: 'Country',
+                exact: true,
+            })).rejects.toThrow('listboxPick: no visible option matching "Japan"');
+        }
+        finally {
+            disconnect();
+            await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
+        }
+    });
+});

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.6' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.8' }, { 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, visibility / scroll-reveal hints, 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 ────────────────────────────────────────────────
@@ -223,7 +223,7 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
     });
     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\`.
 
-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.`, {
+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, prefers the popup nearest the opened field, and handles a few short affirmative/negative aliases such as \`Yes\` /\`No\` for consent-style copy.`, {
         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'),
@@ -317,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
@@ -341,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,
         };
@@ -380,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.`);
     }
@@ -400,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 }] };
 }
@@ -426,15 +444,51 @@ 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 fullyVisible = node.bounds.x >= 0 &&
+        node.bounds.y >= 0 &&
+        node.bounds.x + node.bounds.width <= viewport.width &&
+        node.bounds.y + node.bounds.height <= viewport.height;
+    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));
+    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);
     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,
+        },
+        visibility: {
+            intersectsViewport: hasVisibleIntersection,
+            fullyVisible,
+            offscreenAbove: node.bounds.y + node.bounds.height <= 0,
+            offscreenBelow: node.bounds.y >= viewport.height,
+            offscreenLeft: node.bounds.x + node.bounds.width <= 0,
+            offscreenRight: node.bounds.x >= viewport.width,
+        },
+        scrollHint: {
+            status: fullyVisible ? 'visible' : hasVisibleIntersection ? 'partial' : 'offscreen',
+            revealDeltaX,
+            revealDeltaY,
         },
         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,12 +214,16 @@ export interface UiDelta {
     formsAppeared: PageFormModel[];
     formsRemoved: PageFormModel[];
     listCountsChanged: UiListCountChange[];
+    navigation?: UiNavigationChange;
+    viewport?: UiViewportChange;
+    focus?: UiFocusChange;
 }
 export interface Session {
     ws: WebSocket;
     layout: Record<string, unknown> | null;
     tree: Record<string, unknown> | null;
     url: string;
+    updateRevision: number;
     /** Present when this session owns a child geometra-proxy process (pageUrl connect). */
     proxyChild?: ChildProcess;
 }
@@ -297,6 +328,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

@@ -2,6 +2,8 @@ import WebSocket from 'ws';
 import { spawnGeometraProxy } from './proxy-spawn.js';
 let activeSession = null;
 const ACTION_UPDATE_TIMEOUT_MS = 2000;
+const LISTBOX_UPDATE_TIMEOUT_MS = 4500;
+let nextRequestSequence = 0;
 function shutdownPreviousSession() {
     const prev = activeSession;
     if (!prev)
@@ -30,7 +32,7 @@ export function connect(url) {
     return new Promise((resolve, reject) => {
         shutdownPreviousSession();
         const ws = new WebSocket(url);
-        const session = { ws, layout: null, tree: null, url };
+        const session = { ws, layout: null, tree: null, url, updateRevision: 0 };
         let resolved = false;
         const timeout = setTimeout(() => {
             if (!resolved) {
@@ -49,6 +51,7 @@ export function connect(url) {
                 if (msg.type === 'frame') {
                     session.layout = msg.layout;
                     session.tree = msg.tree;
+                    session.updateRevision++;
                     if (!resolved) {
                         resolved = true;
                         clearTimeout(timeout);
@@ -58,6 +61,7 @@ export function connect(url) {
                 }
                 else if (msg.type === 'patch' && session.layout) {
                     applyPatches(session.layout, msg.patches);
+                    session.updateRevision++;
                 }
             }
             catch { /* ignore malformed messages */ }
@@ -208,7 +212,7 @@ export function sendListboxPick(session, label, opts) {
         payload.fieldLabel = opts.fieldLabel;
     if (opts?.query)
         payload.query = opts.query;
-    return sendAndWaitForUpdate(session, payload);
+    return sendAndWaitForUpdate(session, payload, LISTBOX_UPDATE_TIMEOUT_MS);
 }
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
 export function sendSelectOption(session, x, y, option) {
@@ -262,8 +266,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',
@@ -391,6 +405,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;
@@ -408,34 +461,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 = [];
@@ -444,8 +523,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)`);
@@ -467,6 +547,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) {
@@ -852,7 +934,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])}`);
         }
@@ -873,8 +955,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 = [];
@@ -926,6 +1010,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,
@@ -935,6 +1039,9 @@ export function buildUiDelta(before, after, options) {
         formsAppeared,
         formsRemoved,
         listCountsChanged,
+        ...(navigation ? { navigation } : {}),
+        ...(viewport ? { viewport } : {}),
+        ...(focus ? { focus } : {}),
     };
 }
 export function hasUiDelta(delta) {
@@ -945,10 +1052,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`);
     }
@@ -1044,6 +1165,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;
@@ -1058,6 +1188,7 @@ function walkNode(element, layout, path) {
         role,
         ...(name ? { name } : {}),
         ...(Object.keys(state).length > 0 ? { state } : {}),
+        ...(Object.keys(meta).length > 0 ? { meta } : {}),
         bounds,
         path,
         children,
@@ -1131,40 +1262,55 @@ function applyPatches(layout, patches) {
             node.height = patch.height;
     }
 }
-function sendAndWaitForUpdate(session, message) {
+function sendAndWaitForUpdate(session, message, timeoutMs = ACTION_UPDATE_TIMEOUT_MS) {
     return new Promise((resolve, reject) => {
         if (session.ws.readyState !== WebSocket.OPEN) {
             reject(new Error('Not connected'));
             return;
         }
-        session.ws.send(JSON.stringify(message));
-        waitForNextUpdate(session).then(resolve).catch(reject);
+        const requestId = `req-${++nextRequestSequence}`;
+        const startRevision = session.updateRevision;
+        session.ws.send(JSON.stringify({ ...message, requestId }));
+        waitForNextUpdate(session, timeoutMs, requestId, startRevision).then(resolve).catch(reject);
     });
 }
-function waitForNextUpdate(session) {
+function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, requestId, startRevision = session.updateRevision) {
     return new Promise((resolve, reject) => {
         const onMessage = (data) => {
             try {
                 const msg = JSON.parse(String(data));
+                const messageRequestId = typeof msg.requestId === 'string' ? msg.requestId : undefined;
+                if (requestId) {
+                    if (msg.type === 'error' && messageRequestId === requestId) {
+                        cleanup();
+                        reject(new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error'));
+                        return;
+                    }
+                    if (msg.type === 'ack' && messageRequestId === requestId) {
+                        cleanup();
+                        resolve({
+                            status: session.updateRevision > startRevision ? 'updated' : 'acknowledged',
+                            timeoutMs,
+                        });
+                    }
+                    return;
+                }
                 if (msg.type === 'error') {
                     cleanup();
                     reject(new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error'));
                     return;
                 }
                 if (msg.type === 'frame') {
-                    session.layout = msg.layout;
-                    session.tree = msg.tree;
                     cleanup();
-                    resolve({ status: 'updated', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
+                    resolve({ status: 'updated', timeoutMs });
                 }
                 else if (msg.type === 'patch' && session.layout) {
-                    applyPatches(session.layout, msg.patches);
                     cleanup();
-                    resolve({ status: 'updated', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
+                    resolve({ status: 'updated', timeoutMs });
                 }
                 else if (msg.type === 'ack') {
                     cleanup();
-                    resolve({ status: 'acknowledged', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
+                    resolve({ status: 'acknowledged', timeoutMs });
                 }
             }
             catch { /* ignore */ }
@@ -1172,8 +1318,8 @@ function waitForNextUpdate(session) {
         // Expose timeout explicitly so action handlers can tell the user the result is ambiguous.
         const timeout = setTimeout(() => {
             cleanup();
-            resolve({ status: 'timed_out', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
-        }, ACTION_UPDATE_TIMEOUT_MS);
+            resolve({ status: 'timed_out', timeoutMs });
+        }, timeoutMs);
         function cleanup() {
             clearTimeout(timeout);
             session.ws.off('message', onMessage);

package/package.json

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