@geometra/mcp 1.19.12 → 1.19.14

package/dist/proxy-spawn.js

@@ -1,5 +1,5 @@
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, realpathSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,9 +13,34 @@ export function resolveProxyScriptPath() {
 }
 export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR) {
     const errors = [];
+    const workspaceDist = path.resolve(moduleDir, '../../packages/proxy/dist/index.js');
+    const bundledDependencyDir = path.resolve(moduleDir, '../node_modules/@geometra/proxy');
+    const packageDir = resolveProxyPackageDir(customRequire);
+    if (packageDir) {
+        if (shouldPreferWorkspaceDist(packageDir, bundledDependencyDir) && existsSync(workspaceDist)) {
+            return workspaceDist;
+        }
+        const packagedDist = path.join(packageDir, 'dist/index.js');
+        if (existsSync(packagedDist))
+            return packagedDist;
+        const builtLocalDist = buildLocalProxyDistIfPossible(packageDir, errors);
+        if (builtLocalDist)
+            return builtLocalDist;
+        errors.push(`Resolved @geometra/proxy package at ${packageDir}, but dist/index.js was missing`);
+    }
+    else {
+        errors.push('Could not find @geometra/proxy/package.json via Node module search paths');
+    }
     try {
         const pkgJson = customRequire.resolve('@geometra/proxy/package.json');
-        return path.join(path.dirname(pkgJson), 'dist/index.js');
+        const exportPackageDir = path.dirname(pkgJson);
+        const packagedDist = path.join(exportPackageDir, 'dist/index.js');
+        if (existsSync(packagedDist))
+            return packagedDist;
+        const builtLocalDist = buildLocalProxyDistIfPossible(exportPackageDir, errors);
+        if (builtLocalDist)
+            return builtLocalDist;
+        errors.push(`Resolved @geometra/proxy/package.json at ${pkgJson}, but dist/index.js was missing`);
     }
     catch (err) {
         errors.push(err instanceof Error ? err.message : String(err));
@@ -31,13 +56,64 @@ export function resolveProxyScriptPathWith(customRequire, moduleDir = MODULE_DIR
         return packagedSiblingDist;
     }
     errors.push(`Packaged sibling fallback not found at ${packagedSiblingDist}`);
-    const workspaceDist = path.resolve(moduleDir, '../../packages/proxy/dist/index.js');
     if (existsSync(workspaceDist)) {
         return workspaceDist;
     }
     errors.push(`Workspace fallback not found at ${workspaceDist}`);
     throw new Error(`Could not resolve @geometra/proxy. Install it with the MCP package: npm install @geometra/proxy. Resolution errors: ${errors.join(' | ')}`);
 }
+function resolveProxyPackageDir(customRequire) {
+    const searchRoots = customRequire.resolve.paths('@geometra/proxy') ?? [];
+    for (const searchRoot of searchRoots) {
+        const packageDir = path.join(searchRoot, '@geometra', 'proxy');
+        if (existsSync(path.join(packageDir, 'package.json')))
+            return packageDir;
+    }
+    return undefined;
+}
+function shouldPreferWorkspaceDist(packageDir, bundledDependencyDir) {
+    try {
+        return realpathSync(packageDir) === realpathSync(bundledDependencyDir);
+    }
+    catch {
+        return false;
+    }
+}
+function buildLocalProxyDistIfPossible(packageDir, errors) {
+    const distEntry = path.join(packageDir, 'dist/index.js');
+    const sourceEntry = path.join(packageDir, 'src/index.ts');
+    const tsconfigPath = path.join(packageDir, 'tsconfig.build.json');
+    if (!existsSync(sourceEntry) || !existsSync(tsconfigPath)) {
+        return undefined;
+    }
+    try {
+        const realPackageDir = realpathSync(packageDir);
+        const realTsconfigPath = path.join(realPackageDir, 'tsconfig.build.json');
+        const realDistDir = path.join(realPackageDir, 'dist');
+        const tscBin = require.resolve('typescript/bin/tsc');
+        rmSync(realDistDir, { recursive: true, force: true });
+        const result = spawnSync(process.execPath, [tscBin, '-p', realTsconfigPath], {
+            cwd: realPackageDir,
+            encoding: 'utf8',
+            stdio: 'pipe',
+        });
+        if (result.status !== 0) {
+            const detail = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+            errors.push(`Failed to build local @geometra/proxy at ${realPackageDir}: ${detail || `exit ${result.status ?? 'unknown'}`}`);
+            return undefined;
+        }
+        if (existsSync(distEntry))
+            return distEntry;
+        const realDistEntry = path.join(realPackageDir, 'dist/index.js');
+        if (existsSync(realDistEntry))
+            return realDistEntry;
+        errors.push(`Built local @geometra/proxy at ${realPackageDir}, but dist/index.js is still missing`);
+    }
+    catch (err) {
+        errors.push(err instanceof Error ? err.message : String(err));
+    }
+    return undefined;
+}
 export function parseProxyReadySignalLine(line) {
     const trimmed = line.trim();
     if (!trimmed)

package/dist/server.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
-import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -66,6 +66,12 @@ const fillFieldSchema = z.discriminatedUnion('kind', [
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
     }),
 ]);
+const formValueSchema = z.union([
+    z.string(),
+    z.boolean(),
+    z.array(z.string()).min(1),
+]);
+const formValuesRecordSchema = z.record(z.string(), formValueSchema);
 const batchActionSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('click'),
@@ -146,7 +152,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }),
 ]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.11' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.14' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -184,6 +190,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
+        detail: detailInput(),
     }, async (input) => {
         const normalized = normalizeConnectTarget({ url: input.url, pageUrl: input.pageUrl });
         if (!normalized.ok)
@@ -199,13 +206,23 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     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}`);
+                return ok(JSON.stringify(connectPayload(session, {
+                    transport: 'proxy',
+                    requestedPageUrl: target.pageUrl,
+                    autoCoercedFromUrl: target.autoCoercedFromUrl,
+                    detail: input.detail,
+                }), null, input.detail === 'verbose' ? 2 : undefined));
             }
-            const session = await connect(target.wsUrl);
-            const summary = compactSessionSummary(session);
-            return ok(`Connected to ${target.wsUrl}. UI state:\n${summary}`);
+            const session = await connect(target.wsUrl, {
+                width: input.width,
+                height: input.height,
+            });
+            return ok(JSON.stringify(connectPayload(session, {
+                transport: 'ws',
+                requestedWsUrl: target.wsUrl,
+                autoCoercedFromUrl: false,
+                detail: input.detail,
+            }), null, input.detail === 'verbose' ? 2 : undefined));
         }
         catch (e) {
             return err(`Failed to connect: ${formatConnectFailureMessage(e, target)}`);
@@ -360,6 +377,138 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         }
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
     });
+    server.tool('geometra_fill_form', `Fill a form from a compact values object instead of expanding sections first. This is the lowest-token happy path for standard application flows.
+
+Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most stable matching, or \`valuesByLabel\` when labels are unique enough. MCP resolves the form schema, executes the semantic field operations server-side, and returns one consolidated result.`, {
+        formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
+        valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
+        valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
+        stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing field (default true)'),
+        failOnInvalid: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Return an error if invalid fields remain after filling'),
+        includeSteps: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include per-field step results in the JSON payload (default false for the smallest response)'),
+        detail: detailInput(),
+    }, async ({ formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, detail }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const entryCount = Object.keys(valuesById ?? {}).length + Object.keys(valuesByLabel ?? {}).length;
+        if (entryCount === 0) {
+            return err('Provide at least one value in valuesById or valuesByLabel');
+        }
+        const afterConnect = sessionA11y(session);
+        if (!afterConnect)
+            return err('No UI tree available for form filling');
+        const schemas = buildFormSchemas(afterConnect);
+        if (schemas.length === 0)
+            return err('No forms found in the current UI');
+        const resolution = resolveTargetFormSchema(schemas, { formId, valuesById, valuesByLabel });
+        if (!resolution.ok)
+            return err(resolution.error);
+        const schema = resolution.schema;
+        const planned = planFormFill(schema, { valuesById, valuesByLabel });
+        if (!planned.ok)
+            return err(planned.error);
+        if (!includeSteps) {
+            let usedBatch = false;
+            try {
+                const startRevision = session.updateRevision;
+                const wait = await sendFillFields(session, planned.fields);
+                const ackResult = parseProxyFillAckResult(wait.result);
+                if (ackResult && ackResult.invalidCount === 0) {
+                    usedBatch = true;
+                    const payload = {
+                        completed: true,
+                        execution: 'batched',
+                        finalSource: 'proxy',
+                        formId: schema.formId,
+                        requestedValueCount: entryCount,
+                        fieldCount: planned.fields.length,
+                        successCount: planned.fields.length,
+                        errorCount: 0,
+                        final: ackResult,
+                    };
+                    return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                }
+                await waitForDeferredBatchUpdate(session, startRevision, wait);
+                await waitForBatchFieldReadback(session, planned.fields);
+                usedBatch = true;
+            }
+            catch (e) {
+                if (!canFallbackToSequentialFill(e)) {
+                    const message = e instanceof Error ? e.message : String(e);
+                    return err(message);
+                }
+            }
+            if (usedBatch) {
+                const after = sessionA11y(session);
+                const signals = after ? collectSessionSignals(after) : undefined;
+                const invalidRemaining = signals?.invalidFields.length ?? 0;
+                const payload = {
+                    completed: true,
+                    execution: 'batched',
+                    finalSource: 'session',
+                    formId: schema.formId,
+                    requestedValueCount: entryCount,
+                    fieldCount: planned.fields.length,
+                    successCount: planned.fields.length,
+                    errorCount: 0,
+                    ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
+                };
+                if (failOnInvalid && invalidRemaining > 0) {
+                    return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                }
+                return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+            }
+        }
+        const steps = [];
+        let stoppedAt;
+        for (let index = 0; index < planned.fields.length; index++) {
+            const field = planned.fields[index];
+            try {
+                const result = await executeFillField(session, field, detail);
+                steps.push(detail === 'verbose'
+                    ? { index, kind: field.kind, ok: true, summary: result.summary }
+                    : { index, kind: field.kind, ok: true, ...result.compact });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                steps.push({ index, kind: field.kind, ok: false, error: message });
+                if (stopOnError) {
+                    stoppedAt = index;
+                    break;
+                }
+            }
+        }
+        const after = sessionA11y(session);
+        const signals = after ? collectSessionSignals(after) : undefined;
+        const invalidRemaining = signals?.invalidFields.length ?? 0;
+        const successCount = steps.filter(step => step.ok === true).length;
+        const errorCount = steps.length - successCount;
+        const payload = {
+            completed: stoppedAt === undefined && steps.length === planned.fields.length,
+            execution: 'sequential',
+            formId: schema.formId,
+            requestedValueCount: entryCount,
+            fieldCount: planned.fields.length,
+            successCount,
+            errorCount,
+            ...(includeSteps ? { steps } : {}),
+            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
+        };
+        if (failOnInvalid && invalidRemaining > 0) {
+            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+        }
+        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+    });
     server.tool('geometra_run_actions', `Execute several Geometra actions in one MCP round trip and return one consolidated result. This is the preferred path for long, multi-step form fills where one-tool-per-field would otherwise create too much chatter.
 
 Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, and \`fill_fields\`.`, {
@@ -436,6 +585,29 @@ Use this first on normal HTML pages when you want to understand the page shape w
         const model = buildPageModel(a11y, { maxPrimaryActions, maxSectionsPerKind });
         return ok(JSON.stringify(model));
     });
+    server.tool('geometra_form_schema', `Get a compact, fill-oriented schema for forms on the page. This is the preferred discovery step before geometra_fill_form.
+
+Unlike geometra_expand_section, this collapses repeated radio/button groups into single logical fields, keeps output compact, and omits layout-heavy detail by default.`, {
+        formId: z.string().optional().describe('Optional form id from geometra_page_model. If omitted, returns every form schema on the page.'),
+        maxFields: z.number().int().min(1).max(120).optional().default(80).describe('Cap returned fields per form'),
+        onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields'),
+        onlyInvalidFields: z.boolean().optional().default(false).describe('Only include invalid fields'),
+    }, async ({ formId, maxFields, onlyRequiredFields, onlyInvalidFields }) => {
+        const session = getSession();
+        if (!session?.tree || !session?.layout)
+            return err('Not connected. Call geometra_connect first.');
+        const a11y = buildA11yTree(session.tree, session.layout);
+        const forms = buildFormSchemas(a11y, {
+            formId,
+            maxFields,
+            onlyRequiredFields,
+            onlyInvalidFields,
+        });
+        if (forms.length === 0) {
+            return err(formId ? `No form schema found for id ${formId}` : 'No forms found in the current UI');
+        }
+        return ok(JSON.stringify({ forms }));
+    });
     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.`, {
@@ -863,6 +1035,18 @@ function compactSessionSummary(session) {
         return 'No UI update received';
     return sessionOverviewFromA11y(a11y);
 }
+function connectPayload(session, opts) {
+    const a11y = sessionA11y(session);
+    return {
+        connected: true,
+        transport: opts.transport,
+        wsUrl: session.url,
+        ...(a11y?.meta?.pageUrl || opts.requestedPageUrl ? { pageUrl: a11y?.meta?.pageUrl ?? opts.requestedPageUrl } : {}),
+        ...(opts.requestedWsUrl ? { requestedWsUrl: opts.requestedWsUrl } : {}),
+        ...(opts.autoCoercedFromUrl ? { autoCoercedFromUrl: true } : {}),
+        ...(opts.detail === 'verbose' && a11y ? { currentUi: sessionOverviewFromA11y(a11y) } : {}),
+    };
+}
 function sessionA11y(session) {
     if (!session.tree || !session.layout)
         return null;
@@ -1072,6 +1256,183 @@ function waitStatusPayload(wait) {
 function compactFilterPayload(filter) {
     return Object.fromEntries(Object.entries(filter).filter(([, value]) => value !== undefined));
 }
+function normalizeLookupKey(value) {
+    return value.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+function resolveTargetFormSchema(schemas, opts) {
+    if (opts.formId) {
+        const matched = schemas.find(schema => schema.formId === opts.formId);
+        return matched
+            ? { ok: true, schema: matched }
+            : { ok: false, error: `No form schema found for id ${opts.formId}` };
+    }
+    if (schemas.length === 1)
+        return { ok: true, schema: schemas[0] };
+    const idKeys = Object.keys(opts.valuesById ?? {});
+    const labelKeys = Object.keys(opts.valuesByLabel ?? {}).map(normalizeLookupKey);
+    const matches = schemas.filter(schema => {
+        const ids = new Set(schema.fields.map(field => field.id));
+        const labels = new Set(schema.fields.map(field => normalizeLookupKey(field.label)));
+        return idKeys.every(id => ids.has(id)) && labelKeys.every(label => labels.has(label));
+    });
+    if (matches.length === 1)
+        return { ok: true, schema: matches[0] };
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: 'Could not infer which form to fill from the provided field ids/labels. Pass formId from geometra_form_schema.',
+        };
+    }
+    return {
+        ok: false,
+        error: 'Multiple forms match the provided field ids/labels. Pass formId from geometra_form_schema.',
+    };
+}
+function coerceChoiceValue(field, value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value !== 'boolean')
+        return null;
+    const desired = value ? 'yes' : 'no';
+    const option = field.options?.find(option => normalizeLookupKey(option) === desired);
+    return option ?? (value ? 'Yes' : 'No');
+}
+function plannedFillInputsForField(field, value) {
+    if (field.kind === 'text') {
+        if (typeof value !== 'string')
+            return { error: `Field "${field.label}" expects a string value` };
+        return [{ kind: 'text', fieldLabel: field.label, value }];
+    }
+    if (field.kind === 'choice') {
+        const coerced = coerceChoiceValue(field, value);
+        if (!coerced)
+            return { error: `Field "${field.label}" expects a string value` };
+        return [{ kind: 'choice', fieldLabel: field.label, value: coerced }];
+    }
+    if (field.kind === 'toggle') {
+        if (typeof value !== 'boolean')
+            return { error: `Field "${field.label}" expects a boolean value` };
+        return [{ kind: 'toggle', label: field.label, checked: value, controlType: field.controlType }];
+    }
+    const selected = Array.isArray(value) ? value : typeof value === 'string' ? [value] : null;
+    if (!selected || selected.length === 0)
+        return { error: `Field "${field.label}" expects a string array value` };
+    if (!field.options || field.options.length === 0) {
+        return { error: `Field "${field.label}" does not expose checkbox options; use geometra_fill_fields for this field` };
+    }
+    const selectedKeys = new Set(selected.map(normalizeLookupKey));
+    return field.options.map(option => ({
+        kind: 'toggle',
+        label: option,
+        checked: selectedKeys.has(normalizeLookupKey(option)),
+        controlType: 'checkbox',
+    }));
+}
+function planFormFill(schema, opts) {
+    const fieldById = new Map(schema.fields.map(field => [field.id, field]));
+    const fieldsByLabel = new Map();
+    for (const field of schema.fields) {
+        const key = normalizeLookupKey(field.label);
+        const existing = fieldsByLabel.get(key);
+        if (existing)
+            existing.push(field);
+        else
+            fieldsByLabel.set(key, [field]);
+    }
+    const planned = [];
+    const seenFieldIds = new Set();
+    for (const [fieldId, value] of Object.entries(opts.valuesById ?? {})) {
+        const field = fieldById.get(fieldId);
+        if (!field)
+            return { ok: false, error: `Unknown form field id ${fieldId}. Refresh geometra_form_schema and try again.` };
+        const next = plannedFillInputsForField(field, value);
+        if ('error' in next)
+            return { ok: false, error: next.error };
+        planned.push(...next);
+        seenFieldIds.add(field.id);
+    }
+    for (const [label, value] of Object.entries(opts.valuesByLabel ?? {})) {
+        const matches = fieldsByLabel.get(normalizeLookupKey(label)) ?? [];
+        if (matches.length === 0)
+            return { ok: false, error: `Unknown form field label "${label}". Refresh geometra_form_schema and try again.` };
+        if (matches.length > 1) {
+            return { ok: false, error: `Label "${label}" is ambiguous in form ${schema.formId}. Use valuesById for this field.` };
+        }
+        const field = matches[0];
+        if (seenFieldIds.has(field.id)) {
+            return { ok: false, error: `Field "${label}" was provided in both valuesById and valuesByLabel` };
+        }
+        const next = plannedFillInputsForField(field, value);
+        if ('error' in next)
+            return { ok: false, error: next.error };
+        planned.push(...next);
+        seenFieldIds.add(field.id);
+    }
+    return { ok: true, fields: planned };
+}
+function canFallbackToSequentialFill(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.includes('Unsupported client message type "fillFields"') ||
+        message.includes('Client message type "fillFields" is not supported'));
+}
+function parseProxyFillAckResult(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.invalidCount !== 'number' ||
+        typeof candidate.alertCount !== 'number' ||
+        typeof candidate.dialogCount !== 'number' ||
+        typeof candidate.busyCount !== 'number') {
+        return undefined;
+    }
+    return {
+        ...(typeof candidate.pageUrl === 'string' ? { pageUrl: candidate.pageUrl } : {}),
+        invalidCount: candidate.invalidCount,
+        alertCount: candidate.alertCount,
+        dialogCount: candidate.dialogCount,
+        busyCount: candidate.busyCount,
+    };
+}
+async function waitForDeferredBatchUpdate(session, startRevision, wait) {
+    if (wait.status !== 'acknowledged' || session.updateRevision > startRevision)
+        return;
+    await waitForUiCondition(session, () => session.updateRevision > startRevision, 750);
+}
+async function waitForBatchFieldReadback(session, fields) {
+    await waitForUiCondition(session, () => {
+        const a11y = sessionA11y(session);
+        if (!a11y)
+            return false;
+        return fields.every(field => batchFieldReadbackMatches(a11y, field));
+    }, 1500);
+}
+function batchFieldReadbackMatches(a11y, field) {
+    switch (field.kind) {
+        case 'text': {
+            const matches = findNodes(a11y, { name: field.fieldLabel, role: 'textbox' });
+            return matches.some(match => normalizeLookupKey(match.value ?? '') === normalizeLookupKey(field.value));
+        }
+        case 'choice': {
+            const directMatches = [
+                ...findNodes(a11y, { name: field.fieldLabel, role: 'combobox' }),
+                ...findNodes(a11y, { name: field.fieldLabel, role: 'textbox' }),
+                ...findNodes(a11y, { name: field.fieldLabel, role: 'button' }),
+            ];
+            if (directMatches.length === 0)
+                return true;
+            return directMatches.some(match => normalizeLookupKey(match.value ?? '') === normalizeLookupKey(field.value));
+        }
+        case 'toggle':
+            return true;
+        case 'file': {
+            const matches = [
+                ...findNodes(a11y, { name: field.fieldLabel, role: 'textbox' }),
+                ...findNodes(a11y, { name: field.fieldLabel, role: 'button' }),
+            ];
+            return matches.length === 0 || matches.some(match => Boolean(match.value && match.value.trim()));
+        }
+    }
+}
 async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {

package/dist/session.d.ts

@@ -241,6 +241,30 @@ export interface PageSectionDetail {
     items: PageListItemModel[];
     textPreview: string[];
 }
+export type FormSchemaFieldKind = 'text' | 'choice' | 'toggle' | 'multi_choice';
+export interface FormSchemaField {
+    id: string;
+    kind: FormSchemaFieldKind;
+    label: string;
+    required?: boolean;
+    invalid?: boolean;
+    controlType?: 'checkbox' | 'radio';
+    value?: string;
+    valueLength?: number;
+    checked?: boolean;
+    values?: string[];
+    optionCount?: number;
+    options?: string[];
+    context?: NodeContextModel;
+}
+export interface FormSchemaModel {
+    formId: string;
+    name?: string;
+    fieldCount: number;
+    requiredCount: number;
+    invalidCount: number;
+    fields: FormSchemaField[];
+}
 export interface UiNodeUpdate {
     before: CompactUiNode;
     after: CompactUiNode;
@@ -292,12 +316,40 @@ export interface Session {
 export interface UpdateWaitResult {
     status: 'updated' | 'acknowledged' | 'timed_out';
     timeoutMs: number;
+    result?: unknown;
 }
+export type ProxyFillField = {
+    kind: 'text';
+    fieldLabel: string;
+    value: string;
+    exact?: boolean;
+} | {
+    kind: 'choice';
+    fieldLabel: string;
+    value: string;
+    query?: string;
+    exact?: boolean;
+} | {
+    kind: 'toggle';
+    label: string;
+    checked?: boolean;
+    exact?: boolean;
+    controlType?: 'checkbox' | 'radio';
+} | {
+    kind: 'file';
+    fieldLabel: string;
+    paths: string[];
+    exact?: boolean;
+};
 /**
  * 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>;
+export declare function connect(url: string, opts?: {
+    width?: number;
+    height?: number;
+    skipInitialResize?: boolean;
+}): 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.
@@ -356,6 +408,8 @@ export declare function sendFieldChoice(session: Session, fieldLabel: string, va
     exact?: boolean;
     query?: string;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
+/** Fill several semantic form fields in one proxy-side batch. */
+export declare function sendFillFields(session: Session, fields: ProxyFillField[], timeoutMs?: number): 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;
@@ -413,6 +467,12 @@ export declare function buildPageModel(root: A11yNode, options?: {
     maxPrimaryActions?: number;
     maxSectionsPerKind?: number;
 }): PageModel;
+export declare function buildFormSchemas(root: A11yNode, options?: {
+    formId?: string;
+    maxFields?: number;
+    onlyRequiredFields?: boolean;
+    onlyInvalidFields?: boolean;
+}): FormSchemaModel[];
 /**
  * Expand a page-model section by stable ID into richer, on-demand details.
  */