@geometra/mcp 1.18.1 → 1.19.0

package/README.md

@@ -1,6 +1,8 @@
 # @geometra/mcp
 
-MCP server for [Geometra](https://github.com/razroo/geometra) — interact with running Geometra apps via the geometry protocol over WebSocket. For **native** Geometra apps there is no browser in the loop. For **any existing website**, pair this MCP server with [`@geometra/proxy`](../packages/proxy/README.md) (headless Chromium) so the same tools speak the same GEOM v1 wire format.
+MCP server for [Geometra](https://github.com/razroo/geometra) — interact with running Geometra apps via the geometry protocol over WebSocket. For **native** Geometra apps there is no browser in the loop. For **any existing website**, use **`geometra_connect` with `pageUrl`** — the MCP server starts [`@geometra/proxy`](../packages/proxy/README.md) for you (bundled dependency) so you do not need a separate terminal or a `ws://` URL. You can still pass `url: "ws://…"` if a proxy is already running.
+
+See [`AGENT_MODEL.md`](./AGENT_MODEL.md) for the MCP mental model, why token usage can be lower than large browser snapshots, and how headed vs headless proxy mode works.
 
 ## What this does
 
@@ -9,16 +11,17 @@ Connects Claude Code, Codex, or any MCP-compatible AI agent to a WebSocket endpo
 ```
 Playwright + vision:  screenshot → model → guess coordinates → click → repeat
 Native Geometra:      WebSocket → JSON geometry (no browser on the agent path)
-Geometra proxy:       Headless Chromium → DOM geometry → same WebSocket as native → MCP tools unchanged
+Geometra proxy:       Chromium → DOM geometry → same WebSocket as native → MCP tools unchanged (often started via `pageUrl`, no manual CLI)
 ```
 
 ## Tools
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect to a running Geometra server |
-| `geometra_query` | Find elements by role, name, or text content |
-| `geometra_page_model` | Higher-level webpage model: landmarks, forms, dialogs, lists, short previews |
+| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy |
+| `geometra_query` | Find elements by stable id, role, name, or text content |
+| `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
+| `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand |
 | `geometra_click` | Click an element by coordinates |
 | `geometra_type` | Type text into the focused element |
 | `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
@@ -87,6 +90,8 @@ npx geometra-proxy http://localhost:8080 --port 3200
 # Requires Chromium: npx playwright install chromium
 ```
 
+`geometra-proxy` opens a **visible Chromium window by default**. For servers or CI, pass **`--headless`** or set **`GEOMETRA_HEADLESS=1`**. Optional **`--slow-mo <ms>`** slows Playwright actions so they are easier to watch. Headed vs headless usually does **not** materially change token usage, since token usage is driven by MCP tool output rather than whether Chromium is visible.
+
 Point MCP at `ws://127.0.0.1:3200` instead of a native Geometra server. The proxy translates clicks and keyboard messages into Playwright actions and streams updated geometry.
 
 Then in Claude Code (either backend):
@@ -94,7 +99,7 @@ Then in Claude Code (either backend):
 ```
 > Connect to my Geometra app at ws://localhost:3100 and tell me what's on screen
 
-> Give me the page model first, then find the main form
+> Give me the page model first, then expand the main form
 
 > Click the "Submit" button
 
@@ -136,7 +141,10 @@ Agent:  geometra_connect({ url: "ws://127.0.0.1:3200" })
         → Connected. UI includes textbox "Email", button "Save", …
 
 Agent:  geometra_page_model({})
-        → {"viewport":{"width":1024,"height":768},"landmarks":[...],"forms":[...],"dialogs":[],"lists":[]}
+        → {"viewport":{"width":1024,"height":768},"archetypes":["shell","form"],"summary":{...},"forms":[{"id":"fm:1.0","fieldCount":3,"actionCount":1}], ...}
+
+Agent:  geometra_expand_section({ id: "fm:1.0" })
+        → {"id":"fm:1.0","kind":"form","fields":[{"id":"n:1.0.0","name":"Email"}, ...], "actions":[...]}
 
 Agent:  geometra_query({ role: "textbox", name: "Email" })
         → bounds for the email field (viewport coordinates)
@@ -156,9 +164,10 @@ Agent:  geometra_query({ role: "button", name: "Save" })
 2. It receives the computed layout (`{ x, y, width, height }` for every node) and the UI tree (`kind`, `semantic`, `props`, `handlers`, `children`).
 3. It builds an accessibility tree from that data — roles, names, focusable state, bounds.
 4. **`geometra_snapshot`** defaults to a **compact** flat list of viewport-visible actionable nodes (minified JSON) to reduce LLM tokens; use `view: "full"` for the complete nested tree.
-5. **`geometra_page_model`** extracts higher-level webpage structure (landmarks, forms, dialogs, lists) so agents can reason about normal HTML pages without pulling a full tree first.
-6. After interactions, action tools return a **semantic delta** when possible (dialogs opened/closed, forms appeared/removed, list counts changed, named/focusable nodes added/removed/updated). If nothing meaningful changed, they fall back to a short current-UI overview.
-7. Tools expose query, click, type, snapshot, and page-model operations over this structured data.
-8. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
+5. **`geometra_page_model`** is summary-first: page archetypes, stable section ids, counts, top-level landmarks/forms/dialogs/lists, and a few primary actions. It is designed to be cheaper than dumping full previews for every section.
+6. **`geometra_expand_section`** fetches richer details only for the section you care about (fields, actions, headings, nested lists, list items, text preview).
+7. After interactions, action tools return a **semantic delta** when possible (dialogs opened/closed, forms appeared/removed, list counts changed, named/focusable nodes added/removed/updated). If nothing meaningful changed, they fall back to a short current-UI overview.
+8. Tools expose query, click, type, snapshot, page-model, and section-expansion operations over this structured data.
+9. After each interaction, the peer sends updated geometry (full `frame` or `patch`) — the MCP tools interpret that into compact summaries.
 
 With a **native** Geometra server, layout comes from Textura/Yoga. With **`@geometra/proxy`**, layout comes from the browser’s computed DOM geometry; the MCP layer is the same.

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { buildPageModel, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+import { buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
 function node(role, name, bounds, options) {
     return {
         role,
@@ -12,7 +12,7 @@ function node(role, name, bounds, options) {
     };
 }
 describe('buildPageModel', () => {
-    it('extracts landmarks, forms, and lists from a typical webpage tree', () => {
+    it('builds a summary-first page model with stable section ids', () => {
         const tree = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
             children: [
                 node('navigation', 'Primary nav', { x: 0, y: 0, width: 220, height: 80 }, { path: [0] }),
@@ -43,20 +43,82 @@ describe('buildPageModel', () => {
         });
         const model = buildPageModel(tree);
         expect(model.viewport).toEqual({ width: 1024, height: 768 });
-        expect(model.landmarks.map(item => item.role)).toEqual(['navigation', 'main', 'form']);
+        expect(model.archetypes).toEqual(expect.arrayContaining(['shell', 'form', 'results']));
+        expect(model.summary).toEqual({
+            landmarkCount: 3,
+            formCount: 1,
+            dialogCount: 0,
+            listCount: 1,
+            focusableCount: 1,
+        });
+        expect(model.landmarks.map(item => item.id)).toEqual(['lm:0', 'lm:1', 'lm:1.0']);
         expect(model.forms).toHaveLength(1);
         expect(model.forms[0]).toMatchObject({
+            id: 'fm:1.0',
             name: 'Job application',
             fieldCount: 2,
             actionCount: 1,
         });
-        expect(model.forms[0]?.fields.map(field => field.name)).toEqual(['Full name', 'Email']);
-        expect(model.forms[0]?.actions.map(action => action.name)).toEqual(['Submit application']);
         expect(model.lists[0]).toMatchObject({
+            id: 'ls:1.1',
             name: 'Open roles',
             itemCount: 2,
-            itemsPreview: ['Designer', 'Engineer'],
         });
+        expect(model.primaryActions).toEqual([
+            expect.objectContaining({
+                id: 'n:1.0.2',
+                role: 'button',
+                name: 'Submit application',
+            }),
+        ]);
+    });
+    it('expands a section by id on demand', () => {
+        const tree = node('group', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
+            children: [
+                node('main', undefined, { x: 0, y: 0, width: 1024, height: 768 }, {
+                    path: [0],
+                    children: [
+                        node('form', 'Job application', { x: 40, y: 120, width: 520, height: 280 }, {
+                            path: [0, 0],
+                            children: [
+                                node('heading', 'Application', { x: 60, y: 132, width: 200, height: 24 }, { path: [0, 0, 0] }),
+                                node('textbox', 'Full name*', { x: 60, y: 160, width: 300, height: 36 }, { path: [0, 0, 1] }),
+                                node('textbox', 'Email:', { x: 60, y: 208, width: 300, height: 36 }, { path: [0, 0, 2] }),
+                                node('button', 'Submit application', { x: 60, y: 264, width: 180, height: 40 }, {
+                                    path: [0, 0, 3],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const detail = expandPageSection(tree, 'fm:0.0');
+        expect(detail).toMatchObject({
+            id: 'fm:0.0',
+            kind: 'form',
+            role: 'form',
+            name: 'Application',
+            summary: {
+                headingCount: 1,
+                fieldCount: 2,
+                actionCount: 1,
+            },
+        });
+        expect(detail?.fields.map(field => field.name)).toEqual(['Full name', 'Email']);
+        expect(detail?.actions.map(action => action.id)).toEqual(['n:0.0.3']);
+        expect(detail?.fields[0]).not.toHaveProperty('bounds');
+    });
+    it('drops noisy container names and falls back to unnamed summaries', () => {
+        const tree = node('group', undefined, { x: 0, y: 0, width: 800, height: 600 }, {
+            children: [
+                node('form', 'First Name* Last Name* Email* Phone* Country* Location* Resume* LinkedIn*', { x: 20, y: 20, width: 500, height: 400 }, { path: [0] }),
+            ],
+        });
+        const model = buildPageModel(tree);
+        expect(model.forms[0]?.id).toBe('fm:0');
+        expect(model.forms[0]?.name).toBeUndefined();
     });
 });
 describe('buildUiDelta', () => {
@@ -115,14 +177,15 @@ describe('buildUiDelta', () => {
         const delta = buildUiDelta(before, after);
         expect(hasUiDelta(delta)).toBe(true);
         expect(delta.dialogsOpened).toHaveLength(1);
+        expect(delta.dialogsOpened[0]?.id).toBe('dg:0.2');
         expect(delta.dialogsOpened[0]?.name).toBe('Save complete');
         expect(delta.listCountsChanged).toEqual([
-            { name: 'Results', path: [0, 1], beforeCount: 2, afterCount: 3 },
+            { id: 'ls:0.1', name: 'Results', beforeCount: 2, afterCount: 3 },
         ]);
         expect(delta.updated.some(update => update.after.name === 'Save' && update.changes.some(change => change.includes('disabled')))).toBe(true);
         const summary = summarizeUiDelta(delta);
-        expect(summary).toContain('+ dialog "Save complete" opened');
-        expect(summary).toContain('~ list "Results" items 2 -> 3');
-        expect(summary).toContain('~ button "Save": disabled unset -> true');
+        expect(summary).toContain('+ dg:0.2 dialog "Save complete" opened');
+        expect(summary).toContain('~ ls:0.1 list "Results" items 2 -> 3');
+        expect(summary).toContain('~ n:0.0 button "Save": disabled unset -> true');
     });
 });

package/dist/proxy-spawn.d.ts

@@ -0,0 +1,20 @@
+import { type ChildProcess } from 'node:child_process';
+/** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
+export declare function resolveProxyScriptPath(): string;
+/** Prefer `preferred` when free; otherwise an ephemeral port on 127.0.0.1. */
+export declare function pickFreePort(preferred?: number): Promise<number>;
+export interface SpawnProxyParams {
+    pageUrl: string;
+    port: number;
+    headless?: boolean;
+    width?: number;
+    height?: number;
+    slowMo?: number;
+}
+/**
+ * Spawn geometra-proxy as a child process and resolve when the WebSocket is listening.
+ */
+export declare function spawnGeometraProxy(opts: SpawnProxyParams): Promise<{
+    child: ChildProcess;
+    wsUrl: string;
+}>;

package/dist/proxy-spawn.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import path from 'node:path';
+const require = createRequire(import.meta.url);
+/** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
+export function resolveProxyScriptPath() {
+    try {
+        const pkgJson = require.resolve('@geometra/proxy/package.json');
+        return path.join(path.dirname(pkgJson), 'dist/index.js');
+    }
+    catch {
+        throw new Error('Could not resolve @geometra/proxy. Install it with the MCP package: npm install @geometra/proxy');
+    }
+}
+function canBindPort(p) {
+    return new Promise(resolve => {
+        const s = createServer();
+        s.once('error', () => resolve(false));
+        s.listen(p, '127.0.0.1', () => {
+            s.close(() => resolve(true));
+        });
+    });
+}
+function getEphemeralPort() {
+    return new Promise((resolve, reject) => {
+        const s = createServer();
+        s.once('error', reject);
+        s.listen(0, '127.0.0.1', () => {
+            const a = s.address();
+            s.close(err => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                if (typeof a === 'object' && a !== null && 'port' in a)
+                    resolve(a.port);
+                else
+                    reject(new Error('Could not allocate ephemeral port'));
+            });
+        });
+    });
+}
+/** Prefer `preferred` when free; otherwise an ephemeral port on 127.0.0.1. */
+export async function pickFreePort(preferred) {
+    if (preferred != null && preferred > 0 && preferred <= 65535) {
+        if (await canBindPort(preferred))
+            return preferred;
+    }
+    return getEphemeralPort();
+}
+const LISTEN_RE = /WebSocket listening on (ws:\/\/127\.0\.0\.1:\d+)/;
+/**
+ * Spawn geometra-proxy as a child process and resolve when the WebSocket is listening.
+ */
+export function spawnGeometraProxy(opts) {
+    const script = resolveProxyScriptPath();
+    const args = [script, opts.pageUrl, '--port', String(opts.port)];
+    if (opts.width != null && opts.width > 0)
+        args.push('--width', String(opts.width));
+    if (opts.height != null && opts.height > 0)
+        args.push('--height', String(opts.height));
+    if (opts.slowMo != null && opts.slowMo > 0)
+        args.push('--slow-mo', String(opts.slowMo));
+    if (opts.headless === true)
+        args.push('--headless');
+    else if (opts.headless === false)
+        args.push('--headed');
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env },
+        });
+        let settled = false;
+        let stderrBuf = '';
+        const deadline = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                child.kill('SIGTERM');
+                reject(new Error('geometra-proxy did not report a listening WebSocket within 45s'));
+            }
+        }, 45_000);
+        const flushStderr = (chunk) => {
+            stderrBuf += chunk.toString();
+            const m = stderrBuf.match(LISTEN_RE);
+            if (m && !settled) {
+                settled = true;
+                clearTimeout(deadline);
+                child.stderr?.removeAllListeners('data');
+                resolve({ child, wsUrl: m[1] });
+            }
+        };
+        child.stderr?.on('data', flushStderr);
+        child.on('error', err => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(deadline);
+                reject(err);
+            }
+        });
+        child.on('exit', (code, sig) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(deadline);
+                const tail = stderrBuf.trim().slice(-2000);
+                reject(new Error(`geometra-proxy exited before ready (code=${code} signal=${sig}). Stderr (tail): ${tail || '(empty)'}`));
+            }
+        });
+    });
+}

package/dist/server.js

@@ -1,78 +1,148 @@
 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 { 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.0' }, { 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, picks a free 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.
+
+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). Omit if using pageUrl.'),
+        pageUrl: z
+            .string()
+            .url()
+            .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('Local port for spawned proxy (default: ephemeral free 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) => {
         try {
-            const session = await connect(url);
+            const hasUrl = typeof input.url === 'string' && input.url.length > 0;
+            const hasPage = typeof input.pageUrl === 'string' && input.pageUrl.length > 0;
+            if (hasUrl === hasPage) {
+                return err('Provide exactly one of: url (WebSocket) or pageUrl (https://…).');
+            }
+            if (hasPage) {
+                const session = await connectThroughProxy({
+                    pageUrl: input.pageUrl,
+                    port: input.port,
+                    headless: input.headless,
+                    width: input.width,
+                    height: input.height,
+                    slowMo: input.slowMo,
+                });
+                const summary = compactSessionSummary(session);
+                return ok(`Started geometra-proxy and connected at ${session.url} (page: ${input.pageUrl}). UI state:\n${summary}`);
+            }
+            const session = await connect(input.url);
             const summary = compactSessionSummary(session);
-            return ok(`Connected to ${url}. UI state:\n${summary}`);
+            return ok(`Connected to ${input.url}. UI state:\n${summary}`);
         }
         catch (e) {
             return err(`Failed to connect: ${e.message}`);
         }
     });
     // ── 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.
 
@@ -222,7 +292,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()
@@ -309,13 +379,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 +397,7 @@ function findNodes(node, filter) {
 }
 function formatNode(node) {
     return {
+        id: nodeIdForPath(node.path),
         role: node.role,
         name: node.name,
         bounds: node.bounds,