@geometra/mcp 1.18.1

package/README.md

@@ -0,0 +1,164 @@
+# @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.
+
+## What this does
+
+Connects Claude Code, Codex, or any MCP-compatible AI agent to a WebSocket endpoint that streams `frame` / `patch` messages. The agent gets structured `{ x, y, width, height }` geometry and semantic metadata for every UI node — not screenshots, not a vision model.
+
+```
+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
+```
+
+## 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_click` | Click an element by coordinates |
+| `geometra_type` | Type text into the focused element |
+| `geometra_key` | Send special keys (Enter, Tab, Escape, arrows) |
+| `geometra_upload_files` | Attach files: auto / hidden input / native chooser / synthetic drop (`@geometra/proxy` only) |
+| `geometra_pick_listbox_option` | Pick `role=option` (React Select, Headless UI, etc.; `@geometra/proxy` only) |
+| `geometra_select_option` | Choose an option on a native `<select>` (`@geometra/proxy` only) |
+| `geometra_wheel` | Mouse wheel / scroll (`@geometra/proxy` only) |
+| `geometra_snapshot` | Default **compact**: flat viewport-visible actionable nodes (minified JSON). `view=full` for nested tree |
+| `geometra_layout` | Raw computed geometry for every node |
+| `geometra_disconnect` | Close the connection |
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add geometra -- npx @geometra/mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "geometra": {
+      "command": "npx",
+      "args": ["@geometra/mcp"]
+    }
+  }
+}
+```
+
+### From source (this repo)
+
+```bash
+cd mcp
+npm install
+npm run build
+claude mcp add geometra -- node ./dist/index.js
+```
+
+## Usage
+
+### Native Geometra server
+
+```bash
+cd demos/server-client
+npm run server  # starts on ws://localhost:3100
+```
+
+### Any web app (Geometra proxy)
+
+In one terminal, serve or open a page (example uses the repo sample):
+
+```bash
+cd demos/proxy-mcp-sample
+python3 -m http.server 8080
+```
+
+In another terminal (from repo root after `npm install` / `bun install` and `bun run build`):
+
+```bash
+npx geometra-proxy http://localhost:8080 --port 3200
+# Requires Chromium: npx playwright install chromium
+```
+
+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):
+
+```
+> 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
+
+> Click the "Submit" button
+
+> Type "hello@example.com" into the email input
+
+> Take a snapshot and check if the dialog is visible
+```
+
+## Example: agent testing a signup form (native server)
+
+```
+Agent:  geometra_connect({ url: "ws://localhost:3100" })
+        → Connected. UI: button "Sign Up", textbox "Email", textbox "Password"
+
+Agent:  geometra_query({ role: "textbox", name: "Email" })
+        → [{ role: "textbox", name: "Email", bounds: {x:100, y:200, w:300, h:40}, center: {x:250, y:220} }]
+
+Agent:  geometra_click({ x: 250, y: 220 })
+        → Clicked. Email input focused.
+
+Agent:  geometra_type({ text: "test@example.com" })
+        → Typed. Email field updated.
+
+Agent:  geometra_query({ role: "button", name: "Sign Up" })
+        → [{ role: "button", name: "Sign Up", bounds: {x:100, y:350, w:120, h:44}, center: {x:160, y:372} }]
+
+Agent:  geometra_click({ x: 160, y: 372 })
+        → Clicked. Success message visible.
+```
+
+No screenshots and no vision model in the loop. JSON in, JSON out.
+
+## Example: static HTML via `@geometra/proxy`
+
+With `python3 -m http.server 8080` in `demos/proxy-mcp-sample` and `npx geometra-proxy http://localhost:8080 --port 3200` running:
+
+```
+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":[]}
+
+Agent:  geometra_query({ role: "textbox", name: "Email" })
+        → bounds for the email field (viewport coordinates)
+
+Agent:  geometra_click({ x: <center-x>, y: <center-y> })
+        → Focuses the input
+
+Agent:  geometra_type({ text: "hello@example.com" })
+
+Agent:  geometra_query({ role: "button", name: "Save" })
+        → Click center to submit the sample form; status text updates in the DOM
+```
+
+## How it works
+
+1. The MCP server connects to a WebSocket peer that speaks GEOM v1 (`frame` with `layout` + `tree`, optional `patch` updates).
+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.
+
+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.d.ts

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

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

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import { buildPageModel, buildUiDelta, hasUiDelta, summarizeUiDelta, } from '../session.js';
+function node(role, name, bounds, options) {
+    return {
+        role,
+        ...(name ? { name } : {}),
+        ...(options?.state ? { state: options.state } : {}),
+        bounds,
+        path: options?.path ?? [],
+        children: options?.children ?? [],
+        focusable: options?.focusable ?? false,
+    };
+}
+describe('buildPageModel', () => {
+    it('extracts landmarks, forms, and lists from a typical webpage tree', () => {
+        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] }),
+                node('main', undefined, { x: 0, y: 80, width: 1024, height: 688 }, {
+                    path: [1],
+                    children: [
+                        node('form', 'Job application', { x: 40, y: 120, width: 520, height: 280 }, {
+                            path: [1, 0],
+                            children: [
+                                node('textbox', 'Full name', { x: 60, y: 160, width: 300, height: 36 }, { path: [1, 0, 0] }),
+                                node('textbox', 'Email', { x: 60, y: 208, width: 300, height: 36 }, { path: [1, 0, 1] }),
+                                node('button', 'Submit application', { x: 60, y: 264, width: 180, height: 40 }, {
+                                    path: [1, 0, 2],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                        node('list', 'Open roles', { x: 600, y: 120, width: 360, height: 280 }, {
+                            path: [1, 1],
+                            children: [
+                                node('listitem', 'Designer', { x: 620, y: 148, width: 320, height: 32 }, { path: [1, 1, 0] }),
+                                node('listitem', 'Engineer', { x: 620, y: 188, width: 320, height: 32 }, { path: [1, 1, 1] }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        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.forms).toHaveLength(1);
+        expect(model.forms[0]).toMatchObject({
+            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({
+            name: 'Open roles',
+            itemCount: 2,
+            itemsPreview: ['Designer', 'Engineer'],
+        });
+    });
+});
+describe('buildUiDelta', () => {
+    it('captures opened dialogs, state changes, and list count changes', () => {
+        const before = 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('button', 'Save', { x: 40, y: 40, width: 120, height: 40 }, {
+                            path: [0, 0],
+                            focusable: true,
+                        }),
+                        node('list', 'Results', { x: 40, y: 120, width: 400, height: 240 }, {
+                            path: [0, 1],
+                            children: [
+                                node('listitem', 'Row 1', { x: 60, y: 144, width: 360, height: 32 }, { path: [0, 1, 0] }),
+                                node('listitem', 'Row 2', { x: 60, y: 184, width: 360, height: 32 }, { path: [0, 1, 1] }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const after = 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('button', 'Save', { x: 40, y: 40, width: 120, height: 40 }, {
+                            path: [0, 0],
+                            focusable: true,
+                            state: { disabled: true },
+                        }),
+                        node('list', 'Results', { x: 40, y: 120, width: 400, height: 280 }, {
+                            path: [0, 1],
+                            children: [
+                                node('listitem', 'Row 1', { x: 60, y: 144, width: 360, height: 32 }, { path: [0, 1, 0] }),
+                                node('listitem', 'Row 2', { x: 60, y: 184, width: 360, height: 32 }, { path: [0, 1, 1] }),
+                                node('listitem', 'Row 3', { x: 60, y: 224, width: 360, height: 32 }, { path: [0, 1, 2] }),
+                            ],
+                        }),
+                        node('dialog', 'Save complete', { x: 520, y: 80, width: 280, height: 180 }, {
+                            path: [0, 2],
+                            children: [
+                                node('button', 'Close', { x: 620, y: 200, width: 100, height: 36 }, {
+                                    path: [0, 2, 0],
+                                    focusable: true,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+        const delta = buildUiDelta(before, after);
+        expect(hasUiDelta(delta)).toBe(true);
+        expect(delta.dialogsOpened).toHaveLength(1);
+        expect(delta.dialogsOpened[0]?.name).toBe('Save complete');
+        expect(delta.listCountsChanged).toEqual([
+            { name: 'Results', path: [0, 1], 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');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('geometra-mcp: failed to start', err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,352 @@
+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';
+export function createServer() {
+    const server = new McpServer({ name: 'geometra', version: '0.1.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.
+
+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 }) => {
+        try {
+            const session = await connect(url);
+            const summary = compactSessionSummary(session);
+            return ok(`Connected to ${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.
+
+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.`, {
+        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 }) => {
+        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 });
+        if (matches.length === 0) {
+            return ok(`No elements found matching ${JSON.stringify({ 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.
+
+Use this first on normal HTML pages when you want to understand the page shape with fewer tokens than a full snapshot.`, {
+        maxFieldsPerForm: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .optional()
+            .default(12)
+            .describe('Cap returned fields per form (default 12).'),
+        maxActionsPerContainer: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .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 }) => {
+        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 });
+        return ok(JSON.stringify(model));
+    });
+    // ── 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.
+
+After clicking, returns a compact semantic delta when possible (dialogs/forms/lists/nodes changed). If nothing meaningful changed, returns a short current-UI overview.`, {
+        x: z.number().describe('X coordinate to click (use center of element bounds from geometra_query)'),
+        y: z.number().describe('Y coordinate to click'),
+    }, async ({ x, y }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const before = sessionA11y(session);
+        await sendClick(session, x, y);
+        const summary = postActionSummary(session, before);
+        return ok(`Clicked at (${x}, ${y}).\n${summary}`);
+    });
+    // ── type ─────────────────────────────────────────────────────
+    server.tool('geometra_type', `Type text into the currently focused element. First click a textbox/input with geometra_click to focus it, then use this to type.
+
+Each character is sent as a key event through the geometry protocol. Returns a compact semantic delta when possible, otherwise a short current-UI overview.`, {
+        text: z.string().describe('Text to type into the focused element'),
+    }, async ({ text }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const before = sessionA11y(session);
+        await sendType(session, text);
+        const summary = postActionSummary(session, before);
+        return ok(`Typed "${text}".\n${summary}`);
+    });
+    // ── key ──────────────────────────────────────────────────────
+    server.tool('geometra_key', `Send a special key press (Enter, Tab, Escape, ArrowDown, etc.) to the Geometra UI. Useful for form submission, focus navigation, and keyboard shortcuts.`, {
+        key: z.string().describe('Key to press (e.g. "Enter", "Tab", "Escape", "ArrowDown", "Backspace")'),
+        shift: z.boolean().optional().describe('Hold Shift'),
+        ctrl: z.boolean().optional().describe('Hold Ctrl'),
+        meta: z.boolean().optional().describe('Hold Meta/Cmd'),
+        alt: z.boolean().optional().describe('Hold Alt'),
+    }, async ({ key, shift, ctrl, meta, alt }) => {
+        const session = getSession();
+        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);
+        return ok(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`);
+    });
+    // ── upload files (proxy) ───────────────────────────────────────
+    server.tool('geometra_upload_files', `Attach local files to a file input. Requires \`@geometra/proxy\` (paths exist on the proxy host).
+
+Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`input[type=file]\`, else first visible file input. **hidden** targets hidden inputs directly. **drop** needs dropX,dropY for drag-target zones. **chooser** requires x,y.`, {
+        paths: z.array(z.string()).min(1).describe('Absolute paths on the proxy machine, e.g. /Users/you/resume.pdf'),
+        x: z.number().optional().describe('Click X to trigger native file chooser'),
+        y: z.number().optional().describe('Click Y to trigger native file chooser'),
+        strategy: z
+            .enum(['auto', 'chooser', 'hidden', 'drop'])
+            .optional()
+            .describe('Upload strategy (default auto)'),
+        dropX: z.number().optional().describe('Drop target X (viewport) for strategy drop'),
+        dropY: z.number().optional().describe('Drop target Y (viewport) for strategy drop'),
+    }, async ({ paths, x, y, strategy, dropX, dropY }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const before = sessionA11y(session);
+        try {
+            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);
+            return ok(`Uploaded ${paths.length} file(s).\n${summary}`);
+        }
+        catch (e) {
+            return err(e.message);
+        }
+    });
+    server.tool('geometra_pick_listbox_option', `Pick a visible \`role=option\` (Headless UI, React Select, Radix, etc.). Requires \`@geometra/proxy\`.
+
+Optional openX,openY clicks the combobox first if the list is not open. Uses substring name match unless exact=true.`, {
+        label: z.string().describe('Accessible name of the option (visible text or aria-label)'),
+        exact: z.boolean().optional().describe('Exact name match'),
+        openX: z.number().optional().describe('Click to open dropdown'),
+        openY: z.number().optional().describe('Click to open dropdown'),
+    }, async ({ label, exact, openX, openY }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const before = sessionA11y(session);
+        try {
+            await sendListboxPick(session, label, {
+                exact,
+                open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
+            });
+            const summary = postActionSummary(session, before);
+            return ok(`Picked listbox option "${label}".\n${summary}`);
+        }
+        catch (e) {
+            return err(e.message);
+        }
+    });
+    // ── select option (proxy, native <select>) ─────────────────────
+    server.tool('geometra_select_option', `Set a native HTML \`<select>\` after clicking its center (x,y from geometra_query). Requires \`@geometra/proxy\`.
+
+Custom React/Vue dropdowns are not supported — open them with geometra_click and pick options by snapshot instead.`, {
+        x: z.number().describe('X coordinate (e.g. center of the select from geometra_query)'),
+        y: z.number().describe('Y coordinate'),
+        value: z.string().optional().describe('Option value= attribute'),
+        label: z.string().optional().describe('Visible option label (substring match)'),
+        index: z.number().int().min(0).optional().describe('Zero-based option index'),
+    }, async ({ x, y, value, label, index }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        if (value === undefined && label === undefined && index === undefined) {
+            return err('Provide at least one of value, label, or index');
+        }
+        const before = sessionA11y(session);
+        try {
+            await sendSelectOption(session, x, y, { value, label, index });
+            const summary = postActionSummary(session, before);
+            return ok(`Selected option.\n${summary}`);
+        }
+        catch (e) {
+            return err(e.message);
+        }
+    });
+    // ── wheel / scroll (proxy) ─────────────────────────────────────
+    server.tool('geometra_wheel', `Scroll the page or an element under the pointer using the mouse wheel. Requires \`@geometra/proxy\` (e.g. virtualized lists, long application forms).`, {
+        deltaY: z.number().describe('Vertical scroll delta (positive scrolls down, typical step ~100)'),
+        deltaX: z.number().optional().describe('Horizontal scroll delta'),
+        x: z.number().optional().describe('Move pointer to X before scrolling'),
+        y: z.number().optional().describe('Move pointer to Y before scrolling'),
+    }, async ({ deltaY, deltaX, x, y }) => {
+        const session = getSession();
+        if (!session)
+            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);
+            return ok(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`);
+        }
+        catch (e) {
+            return err(e.message);
+        }
+    });
+    // ── 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.`, {
+        view: z
+            .enum(['compact', 'full'])
+            .optional()
+            .default('compact')
+            .describe('compact (default): token-efficient flat index. full: nested tree, every node.'),
+        maxNodes: z
+            .number()
+            .int()
+            .min(20)
+            .max(800)
+            .optional()
+            .default(400)
+            .describe('Max rows in compact view (default 400).'),
+    }, async ({ view, maxNodes }) => {
+        const session = getSession();
+        if (!session?.tree || !session?.layout)
+            return err('Not connected. Call geometra_connect first.');
+        const a11y = buildA11yTree(session.tree, session.layout);
+        if (view === 'full') {
+            return ok(JSON.stringify(a11y, null, 2));
+        }
+        const { nodes, truncated } = buildCompactUiIndex(a11y, { maxNodes });
+        const payload = {
+            view: 'compact',
+            viewport: { width: a11y.bounds.width, height: a11y.bounds.height },
+            nodes,
+            truncated,
+        };
+        return ok(JSON.stringify(payload));
+    });
+    // ── layout ───────────────────────────────────────────────────
+    server.tool('geometra_layout', `Get the raw computed layout geometry — the exact {x, y, width, height} for every node in the UI tree. This is the lowest-level view, useful for pixel-precise assertions in tests.
+
+For a token-efficient semantic view, use geometra_snapshot (default compact). For the complete nested tree, geometra_snapshot with view=full.`, {}, async () => {
+        const session = getSession();
+        if (!session?.layout)
+            return err('Not connected. Call geometra_connect first.');
+        return ok(JSON.stringify(session.layout, null, 2));
+    });
+    // ── disconnect ───────────────────────────────────────────────
+    server.tool('geometra_disconnect', `Disconnect from the Geometra server and clean up the WebSocket connection.`, {}, async () => {
+        disconnect();
+        return ok('Disconnected.');
+    });
+    return server;
+}
+// ── Helpers ──────────────────────────────────────────────────────
+function compactSessionSummary(session) {
+    const a11y = sessionA11y(session);
+    if (!a11y)
+        return 'No UI update received';
+    return sessionOverviewFromA11y(a11y);
+}
+function sessionA11y(session) {
+    if (!session.tree || !session.layout)
+        return null;
+    return buildA11yTree(session.tree, session.layout);
+}
+function sessionOverviewFromA11y(a11y) {
+    const pageSummary = summarizePageModel(buildPageModel(a11y), 8);
+    const { nodes } = buildCompactUiIndex(a11y, { maxNodes: 32 });
+    const keyNodes = nodes.length > 0 ? `Key nodes:\n${summarizeCompactIndex(nodes, 18)}` : '';
+    return [pageSummary, keyNodes].filter(Boolean).join('\n');
+}
+function postActionSummary(session, before) {
+    const after = sessionA11y(session);
+    if (!after)
+        return 'No UI update received';
+    if (before) {
+        const delta = buildUiDelta(before, after);
+        if (hasUiDelta(delta)) {
+            return `Changes:\n${summarizeUiDelta(delta)}`;
+        }
+    }
+    return `Current UI:\n${sessionOverviewFromA11y(after)}`;
+}
+function ok(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function err(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+function findNodes(node, filter) {
+    const matches = [];
+    function walk(n) {
+        let match = true;
+        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))
+            matches.push(n);
+        for (const child of n.children)
+            walk(child);
+    }
+    walk(node);
+    return matches;
+}
+function formatNode(node) {
+    return {
+        role: node.role,
+        name: node.name,
+        bounds: node.bounds,
+        center: {
+            x: Math.round(node.bounds.x + node.bounds.width / 2),
+            y: Math.round(node.bounds.y + node.bounds.height / 2),
+        },
+        focusable: node.focusable,
+        ...(node.state && Object.keys(node.state).length > 0 ? { state: node.state } : {}),
+        path: node.path,
+    };
+}
+function formatKeyCombo(key, mods) {
+    const parts = [];
+    if (mods?.ctrl)
+        parts.push('Ctrl');
+    if (mods?.meta)
+        parts.push('Cmd');
+    if (mods?.alt)
+        parts.push('Alt');
+    if (mods?.shift)
+        parts.push('Shift');
+    parts.push(key);
+    return parts.join('+');
+}