@geometra/mcp 1.18.1 → 1.19.1

package/dist/server.js

@@ -1,78 +1,150 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { connect, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendListboxPick, sendSelectOption, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, buildUiDelta, hasUiDelta, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, } from './session.js';
+import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
+import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendListboxPick, sendSelectOption, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, } from './session.js';
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '0.1.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.1' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
-    server.tool('geometra_connect', `Connect to a running Geometra server over WebSocket. This replaces Playwright/browser automation — you get direct access to the UI's pixel-exact geometry as JSON.
+    server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
-Call this first before using any other geometra tools. The peer must be listening (native Geometra server, or \`geometra-proxy\` for real web pages). File upload / wheel / native \`<select>\` require \`@geometra/proxy\`; native Textura servers return an error for those messages.`, {
-        url: z.string().describe('WebSocket URL of the Geometra server (e.g. ws://localhost:3100)'),
-    }, async ({ url }) => {
+**Prefer \`pageUrl\` for job sites and SPAs:** pass \`https://…\` and this server spawns geometra-proxy on an ephemeral local port and connects — you do **not** need a separate terminal or a \`ws://\` URL (fewer IDE approval steps for the human).
+
+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).`, {
+        url: z
+            .string()
+            .optional()
+            .describe('WebSocket URL when a server is already running (e.g. ws://127.0.0.1:3200 or ws://localhost:3100). If you pass http(s) here by mistake, MCP will treat it as a page URL and start geometra-proxy.'),
+        pageUrl: z
+            .string()
+            .url()
+            .refine(isHttpUrl, 'pageUrl must use http:// or https://')
+            .optional()
+            .describe('HTTP(S) page to open. MCP starts geometra-proxy and connects automatically. Use this instead of url for most web apply flows.'),
+        port: z
+            .number()
+            .int()
+            .positive()
+            .max(65535)
+            .optional()
+            .describe('Preferred local port for spawned proxy (default: ephemeral OS-assigned port).'),
+        headless: z
+            .boolean()
+            .optional()
+            .describe('Run Chromium headless (default false = visible window).'),
+        width: z.number().int().positive().optional().describe('Viewport width for spawned proxy.'),
+        height: z.number().int().positive().optional().describe('Viewport height for spawned proxy.'),
+        slowMo: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
+    }, async (input) => {
+        const normalized = normalizeConnectTarget({ url: input.url, pageUrl: input.pageUrl });
+        if (!normalized.ok)
+            return err(normalized.error);
+        const target = normalized.value;
         try {
-            const session = await connect(url);
+            if (target.kind === 'proxy') {
+                const session = await connectThroughProxy({
+                    pageUrl: target.pageUrl,
+                    port: input.port,
+                    headless: input.headless,
+                    width: input.width,
+                    height: input.height,
+                    slowMo: input.slowMo,
+                });
+                const summary = compactSessionSummary(session);
+                const inferred = target.autoCoercedFromUrl ? ' inferred from url input' : '';
+                return ok(`Started geometra-proxy and connected at ${session.url} (page: ${target.pageUrl}${inferred}). UI state:\n${summary}`);
+            }
+            const session = await connect(target.wsUrl);
             const summary = compactSessionSummary(session);
-            return ok(`Connected to ${url}. UI state:\n${summary}`);
+            return ok(`Connected to ${target.wsUrl}. UI state:\n${summary}`);
         }
         catch (e) {
-            return err(`Failed to connect: ${e.message}`);
+            return err(`Failed to connect: ${formatConnectFailureMessage(e, target)}`);
         }
     });
     // ── query ────────────────────────────────────────────────────
-    server.tool('geometra_query', `Find elements in the current Geometra UI by 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}, 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'),
         role: z.string().optional().describe('ARIA role to match (e.g. "button", "textbox", "text", "heading", "listitem")'),
         name: z.string().optional().describe('Accessible name to match (exact or substring)'),
         text: z.string().optional().describe('Text content to search for (substring match)'),
-    }, async ({ role, name, text }) => {
+    }, async ({ id, role, name, text }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
         const a11y = buildA11yTree(session.tree, session.layout);
-        const matches = findNodes(a11y, { role, name, text });
+        const matches = findNodes(a11y, { id, role, name, text });
         if (matches.length === 0) {
-            return ok(`No elements found matching ${JSON.stringify({ role, name, text })}`);
+            return ok(`No elements found matching ${JSON.stringify({ id, role, name, text })}`);
         }
         const result = matches.map(formatNode);
         return ok(JSON.stringify(result, null, 2));
     });
     // ── page model ────────────────────────────────────────────────
-    server.tool('geometra_page_model', `Get a higher-level webpage model instead of a raw node dump. Extracts common structures such as landmarks, forms, dialogs, and lists, with short previews of fields/actions/items.
+    server.tool('geometra_page_model', `Get a higher-level webpage summary instead of a raw node dump. Returns stable section ids, page archetypes, summary counts, top-level landmarks/forms/dialogs/lists, and a few primary actions.
 
-Use this first on normal HTML pages when you want to understand the page shape with fewer tokens than a full snapshot.`, {
-        maxFieldsPerForm: z
+Use this first on normal HTML pages when you want to understand the page shape with fewer tokens than a full snapshot. Then call geometra_expand_section on a returned section id when you need details.`, {
+        maxPrimaryActions: z
             .number()
             .int()
             .min(1)
-            .max(40)
+            .max(12)
             .optional()
-            .default(12)
-            .describe('Cap returned fields per form (default 12).'),
-        maxActionsPerContainer: z
+            .default(6)
+            .describe('Cap top-level primary actions (default 6).'),
+        maxSectionsPerKind: z
             .number()
             .int()
             .min(1)
-            .max(20)
+            .max(16)
             .optional()
             .default(8)
-            .describe('Cap returned actions per form/dialog (default 8).'),
-        maxItemsPerList: z
-            .number()
-            .int()
-            .min(1)
-            .max(20)
-            .optional()
-            .default(5)
-            .describe('Cap list item preview strings (default 5).'),
-    }, async ({ maxFieldsPerForm, maxActionsPerContainer, maxItemsPerList }) => {
+            .describe('Cap returned landmarks/forms/dialogs/lists per kind (default 8).'),
+    }, async ({ maxPrimaryActions, maxSectionsPerKind }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
         const a11y = buildA11yTree(session.tree, session.layout);
-        const model = buildPageModel(a11y, { maxFieldsPerForm, maxActionsPerContainer, maxItemsPerList });
+        const model = buildPageModel(a11y, { maxPrimaryActions, maxSectionsPerKind });
         return ok(JSON.stringify(model));
     });
+    server.tool('geometra_expand_section', `Expand one section from geometra_page_model by stable id. Returns richer on-demand details such as headings, fields, actions, nested lists, list items, and text preview.
+
+Use this after geometra_page_model when you know which form/dialog/list/landmark you want to inspect more closely. Per-item bounds are omitted by default to save tokens; set includeBounds=true if you need them immediately.`, {
+        id: z.string().describe('Section id from geometra_page_model, e.g. fm:1.0 or ls:2.1'),
+        maxHeadings: z.number().int().min(1).max(20).optional().default(6).describe('Cap heading rows'),
+        maxFields: z.number().int().min(1).max(40).optional().default(18).describe('Cap field rows'),
+        maxActions: z.number().int().min(1).max(30).optional().default(12).describe('Cap action rows'),
+        maxLists: z.number().int().min(0).max(20).optional().default(8).describe('Cap nested lists'),
+        maxItems: z.number().int().min(0).max(50).optional().default(20).describe('Cap list items'),
+        maxTextPreview: z.number().int().min(0).max(20).optional().default(6).describe('Cap text preview lines'),
+        includeBounds: z.boolean().optional().default(false).describe('Include bounds for fields/actions/headings/items'),
+    }, async ({ id, maxHeadings, maxFields, maxActions, maxLists, maxItems, maxTextPreview, includeBounds }) => {
+        const session = getSession();
+        if (!session?.tree || !session?.layout)
+            return err('Not connected. Call geometra_connect first.');
+        const a11y = buildA11yTree(session.tree, session.layout);
+        const detail = expandPageSection(a11y, id, {
+            maxHeadings,
+            maxFields,
+            maxActions,
+            maxLists,
+            maxItems,
+            maxTextPreview,
+            includeBounds,
+        });
+        if (!detail)
+            return err(`No expandable section found for id ${id}`);
+        return ok(JSON.stringify(detail));
+    });
     // ── 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.
 
@@ -84,8 +156,8 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        await sendClick(session, x, y);
-        const summary = postActionSummary(session, before);
+        const wait = await sendClick(session, x, y);
+        const summary = postActionSummary(session, before, wait);
         return ok(`Clicked at (${x}, ${y}).\n${summary}`);
     });
     // ── type ─────────────────────────────────────────────────────
@@ -98,8 +170,8 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        await sendType(session, text);
-        const summary = postActionSummary(session, before);
+        const wait = await sendType(session, text);
+        const summary = postActionSummary(session, before, wait);
         return ok(`Typed "${text}".\n${summary}`);
     });
     // ── key ──────────────────────────────────────────────────────
@@ -114,8 +186,8 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        await sendKey(session, key, { shift, ctrl, meta, alt });
-        const summary = postActionSummary(session, before);
+        const wait = await sendKey(session, key, { shift, ctrl, meta, alt });
+        const summary = postActionSummary(session, before, wait);
         return ok(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`);
     });
     // ── upload files (proxy) ───────────────────────────────────────
@@ -137,12 +209,12 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
-            await sendFileUpload(session, paths, {
+            const wait = await sendFileUpload(session, paths, {
                 click: x !== undefined && y !== undefined ? { x, y } : undefined,
                 strategy,
                 drop: dropX !== undefined && dropY !== undefined ? { x: dropX, y: dropY } : undefined,
             });
-            const summary = postActionSummary(session, before);
+            const summary = postActionSummary(session, before, wait);
             return ok(`Uploaded ${paths.length} file(s).\n${summary}`);
         }
         catch (e) {
@@ -162,11 +234,11 @@ Optional openX,openY clicks the combobox first if the list is not open. Uses sub
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
-            await sendListboxPick(session, label, {
+            const wait = await sendListboxPick(session, label, {
                 exact,
                 open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
             });
-            const summary = postActionSummary(session, before);
+            const summary = postActionSummary(session, before, wait);
             return ok(`Picked listbox option "${label}".\n${summary}`);
         }
         catch (e) {
@@ -191,8 +263,8 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
         }
         const before = sessionA11y(session);
         try {
-            await sendSelectOption(session, x, y, { value, label, index });
-            const summary = postActionSummary(session, before);
+            const wait = await sendSelectOption(session, x, y, { value, label, index });
+            const summary = postActionSummary(session, before, wait);
             return ok(`Selected option.\n${summary}`);
         }
         catch (e) {
@@ -211,8 +283,8 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
-            await sendWheel(session, deltaY, { deltaX, x, y });
-            const summary = postActionSummary(session, before);
+            const wait = await sendWheel(session, deltaY, { deltaX, x, y });
+            const summary = postActionSummary(session, before, wait);
             return ok(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`);
         }
         catch (e) {
@@ -222,7 +294,7 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
     // ── 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.
 
-JSON is minified in compact view to save tokens. For a webpage-shaped overview (forms, dialogs, lists, landmarks), use geometra_page_model.`, {
+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
             .enum(['compact', 'full'])
             .optional()
@@ -287,17 +359,21 @@ function sessionOverviewFromA11y(a11y) {
     const keyNodes = nodes.length > 0 ? `Key nodes:\n${summarizeCompactIndex(nodes, 18)}` : '';
     return [pageSummary, keyNodes].filter(Boolean).join('\n');
 }
-function postActionSummary(session, before) {
+function postActionSummary(session, before, wait) {
     const after = sessionA11y(session);
+    const notes = [];
+    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.`);
+    }
     if (!after)
-        return 'No UI update received';
+        return [...notes, 'No UI update received'].filter(Boolean).join('\n');
     if (before) {
         const delta = buildUiDelta(before, after);
         if (hasUiDelta(delta)) {
-            return `Changes:\n${summarizeUiDelta(delta)}`;
+            return [...notes, `Changes:\n${summarizeUiDelta(delta)}`].filter(Boolean).join('\n');
         }
     }
-    return `Current UI:\n${sessionOverviewFromA11y(after)}`;
+    return [...notes, `Current UI:\n${sessionOverviewFromA11y(after)}`].filter(Boolean).join('\n');
 }
 function ok(text) {
     return { content: [{ type: 'text', text }] };
@@ -309,13 +385,15 @@ function findNodes(node, filter) {
     const matches = [];
     function walk(n) {
         let match = true;
+        if (filter.id && nodeIdForPath(n.path) !== filter.id)
+            match = false;
         if (filter.role && n.role !== filter.role)
             match = false;
         if (filter.name && (!n.name || !n.name.includes(filter.name)))
             match = false;
         if (filter.text && (!n.name || !n.name.includes(filter.text)))
             match = false;
-        if (match && (filter.role || filter.name || filter.text))
+        if (match && (filter.id || filter.role || filter.name || filter.text))
             matches.push(n);
         for (const child of n.children)
             walk(child);
@@ -325,6 +403,7 @@ function findNodes(node, filter) {
 }
 function formatNode(node) {
     return {
+        id: nodeIdForPath(node.path),
         role: node.role,
         name: node.name,
         bounds: node.bounds,

package/dist/session.d.ts

@@ -1,3 +1,4 @@
+import type { ChildProcess } from 'node:child_process';
 import WebSocket from 'ws';
 /**
  * Parsed accessibility node from the UI tree + computed layout.
@@ -24,6 +25,7 @@ export interface A11yNode {
 }
 /** Flat, viewport-filtered index for token-efficient agent context (see `buildCompactUiIndex`). */
 export interface CompactUiNode {
+    id: string;
     role: string;
     name?: string;
     state?: A11yNode['state'];
@@ -36,8 +38,10 @@ export interface CompactUiNode {
     path: number[];
     focusable: boolean;
 }
-/** Higher-level webpage structures extracted from the a11y tree. */
-export interface PageLandmark {
+export type PageSectionKind = 'landmark' | 'form' | 'dialog' | 'list';
+export type PageArchetype = 'shell' | 'form' | 'dialog' | 'results' | 'content' | 'dashboard';
+interface PageSectionSummaryBase {
+    id: string;
     role: string;
     name?: string;
     bounds: {
@@ -46,9 +50,12 @@ export interface PageLandmark {
         width: number;
         height: number;
     };
-    path: number[];
 }
-export interface PageFieldModel {
+/** Higher-level webpage structures extracted from the a11y tree. */
+export interface PageLandmark extends PageSectionSummaryBase {
+}
+export interface PagePrimaryAction {
+    id: string;
     role: string;
     name?: string;
     state?: A11yNode['state'];
@@ -58,47 +65,85 @@ export interface PageFieldModel {
         width: number;
         height: number;
     };
-    path: number[];
 }
-export interface PageActionModel {
+export interface PageFormModel extends PageSectionSummaryBase {
+    fieldCount: number;
+    actionCount: number;
+}
+export interface PageDialogModel extends PageSectionSummaryBase {
+    fieldCount: number;
+    actionCount: number;
+}
+export interface PageListModel extends PageSectionSummaryBase {
+    itemCount: number;
+}
+export interface PageModel {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    archetypes: PageArchetype[];
+    summary: {
+        landmarkCount: number;
+        formCount: number;
+        dialogCount: number;
+        listCount: number;
+        focusableCount: number;
+    };
+    primaryActions: PagePrimaryAction[];
+    landmarks: PageLandmark[];
+    forms: PageFormModel[];
+    dialogs: PageDialogModel[];
+    lists: PageListModel[];
+}
+export interface PageHeadingModel {
+    id: string;
+    name: string;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface PageFieldModel {
+    id: string;
     role: string;
     name?: string;
     state?: A11yNode['state'];
-    bounds: {
+    bounds?: {
         x: number;
         y: number;
         width: number;
         height: number;
     };
-    path: number[];
 }
-export interface PageFormModel {
+export interface PageActionModel {
+    id: string;
+    role: string;
     name?: string;
-    bounds: {
+    state?: A11yNode['state'];
+    bounds?: {
         x: number;
         y: number;
         width: number;
         height: number;
     };
-    path: number[];
-    fieldCount: number;
-    actionCount: number;
-    fields: PageFieldModel[];
-    actions: PageActionModel[];
 }
-export interface PageDialogModel {
+export interface PageListItemModel {
+    id: string;
     name?: string;
-    bounds: {
+    bounds?: {
         x: number;
         y: number;
         width: number;
         height: number;
     };
-    path: number[];
-    actionCount: number;
-    actions: PageActionModel[];
 }
-export interface PageListModel {
+export interface PageSectionDetail {
+    id: string;
+    kind: PageSectionKind;
+    role: string;
     name?: string;
     bounds: {
         x: number;
@@ -106,19 +151,19 @@ export interface PageListModel {
         width: number;
         height: number;
     };
-    path: number[];
-    itemCount: number;
-    itemsPreview: string[];
-}
-export interface PageModel {
-    viewport: {
-        width: number;
-        height: number;
+    summary: {
+        headingCount: number;
+        fieldCount: number;
+        actionCount: number;
+        listCount: number;
+        itemCount: number;
     };
-    landmarks: PageLandmark[];
-    forms: PageFormModel[];
-    dialogs: PageDialogModel[];
+    headings: PageHeadingModel[];
+    fields: PageFieldModel[];
+    actions: PageActionModel[];
     lists: PageListModel[];
+    items: PageListItemModel[];
+    textPreview: string[];
 }
 export interface UiNodeUpdate {
     before: CompactUiNode;
@@ -126,8 +171,8 @@ export interface UiNodeUpdate {
     changes: string[];
 }
 export interface UiListCountChange {
+    id: string;
     name?: string;
-    path: number[];
     beforeCount: number;
     afterCount: number;
 }
@@ -147,22 +192,40 @@ export interface Session {
     layout: Record<string, unknown> | null;
     tree: Record<string, unknown> | null;
     url: string;
+    /** Present when this session owns a child geometra-proxy process (pageUrl connect). */
+    proxyChild?: ChildProcess;
+}
+export interface UpdateWaitResult {
+    status: 'updated' | 'timed_out';
+    timeoutMs: number;
 }
 /**
  * Connect to a running Geometra server. Waits for the first frame so that
  * layout/tree state is available immediately after connection.
  */
 export declare function connect(url: string): Promise<Session>;
+/**
+ * Start geometra-proxy for `pageUrl`, connect to its WebSocket, and attach the child
+ * process to the session so disconnect / reconnect can clean it up.
+ */
+export declare function connectThroughProxy(options: {
+    pageUrl: string;
+    port?: number;
+    headless?: boolean;
+    width?: number;
+    height?: number;
+    slowMo?: number;
+}): Promise<Session>;
 export declare function getSession(): Session | null;
 export declare function disconnect(): void;
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
  */
-export declare function sendClick(session: Session, x: number, y: number): Promise<void>;
+export declare function sendClick(session: Session, x: number, y: number): Promise<UpdateWaitResult>;
 /**
  * Send a sequence of key events to type text into the focused element.
  */
-export declare function sendType(session: Session, text: string): Promise<void>;
+export declare function sendType(session: Session, text: string): Promise<UpdateWaitResult>;
 /**
  * Send a special key (Enter, Tab, Escape, etc.)
  */
@@ -171,7 +234,7 @@ export declare function sendKey(session: Session, key: string, modifiers?: {
     ctrl?: boolean;
     meta?: boolean;
     alt?: boolean;
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /**
  * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
  * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
@@ -186,7 +249,7 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
         x: number;
         y: number;
     };
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
 export declare function sendListboxPick(session: Session, label: string, opts?: {
     exact?: boolean;
@@ -194,25 +257,26 @@ export declare function sendListboxPick(session: Session, label: string, opts?:
         x: number;
         y: number;
     };
-}): Promise<void>;
+}): 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: {
     value?: string;
     label?: string;
     index?: number;
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
 export declare function sendWheel(session: Session, deltaY: number, opts?: {
     deltaX?: number;
     x?: number;
     y?: number;
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /**
  * Build a flat accessibility tree from the raw UI tree + layout.
  * This is a standalone reimplementation that works with raw JSON —
  * no dependency on @geometra/core.
  */
 export declare function buildA11yTree(tree: Record<string, unknown>, layout: Record<string, unknown>): A11yNode;
+export declare function nodeIdForPath(path: number[]): string;
 /**
  * Flat list of actionable / semantic nodes in the viewport, sorted with focusable first
  * then top-to-bottom reading order. Intended to minimize LLM tokens vs a full nested tree.
@@ -227,14 +291,25 @@ export declare function buildCompactUiIndex(root: A11yNode, options?: {
 };
 export declare function summarizeCompactIndex(nodes: CompactUiNode[], maxLines?: number): string;
 /**
- * Build a compact, webpage-shaped model from the accessibility tree:
- * landmarks, dialogs, forms, and lists with short previews.
+ * Build a summary-first, stable-ID webpage model from the accessibility tree.
+ * Use {@link expandPageSection} to fetch details for a specific section on demand.
  */
 export declare function buildPageModel(root: A11yNode, options?: {
-    maxFieldsPerForm?: number;
-    maxActionsPerContainer?: number;
-    maxItemsPerList?: number;
+    maxPrimaryActions?: number;
+    maxSectionsPerKind?: number;
 }): PageModel;
+/**
+ * Expand a page-model section by stable ID into richer, on-demand details.
+ */
+export declare function expandPageSection(root: A11yNode, id: string, options?: {
+    maxHeadings?: number;
+    maxFields?: number;
+    maxActions?: number;
+    maxLists?: number;
+    maxItems?: number;
+    maxTextPreview?: number;
+    includeBounds?: boolean;
+}): PageSectionDetail | null;
 export declare function summarizePageModel(model: PageModel, maxLines?: number): string;
 /**
  * Compare two accessibility trees at the compact viewport layer plus a few
@@ -245,3 +320,4 @@ export declare function buildUiDelta(before: A11yNode, after: A11yNode, options?
 }): UiDelta;
 export declare function hasUiDelta(delta: UiDelta): boolean;
 export declare function summarizeUiDelta(delta: UiDelta, maxLines?: number): string;
+export {};