@geometra/mcp 1.63.0 → 1.64.0

package/dist/session.js

@@ -37,6 +37,7 @@ const FILL_BATCH_TOGGLE_FIELD_TIMEOUT_MS = 225;
 const FILL_BATCH_FILE_FIELD_TIMEOUT_MS = 5000;
 const FILL_BATCH_MAX_TIMEOUT_MS = 60_000;
 const SESSION_RECONNECT_TIMEOUT_MS = 5_000;
+const PROXY_PROTOCOL_VERSION = 2;
 let nextRequestSequence = 0;
 function invalidateSessionCaches(session) {
     session.cachedA11y = null;
@@ -854,7 +855,7 @@ export function connect(url, opts) {
             if (!opts?.skipInitialResize) {
                 const width = opts?.width ?? 1024;
                 const height = opts?.height ?? 768;
-                ws.send(JSON.stringify({ type: 'resize', width, height }));
+                ws.send(JSON.stringify({ type: 'resize', width, height, protocolVersion: PROXY_PROTOCOL_VERSION }));
             }
             if (opts?.awaitInitialFrame === false && !resolved) {
                 resolved = true;
@@ -1279,7 +1280,7 @@ async function ensureSessionConnected(session) {
 async function sendResizeAndWaitForUpdate(session, width, height, timeoutMs = 5_000) {
     await ensureSessionConnected(session);
     const startRevision = session.updateRevision;
-    session.ws.send(JSON.stringify({ type: 'resize', width, height }));
+    session.ws.send(JSON.stringify({ type: 'resize', width, height, protocolVersion: PROXY_PROTOCOL_VERSION }));
     return await waitForNextUpdate(session, timeoutMs, undefined, startRevision);
 }
 /**
@@ -1303,6 +1304,7 @@ export function sendType(session, text, timeoutMs) {
         for (const char of text) {
             const keyEvent = {
                 type: 'key',
+                protocolVersion: PROXY_PROTOCOL_VERSION,
                 eventType: 'onKeyDown',
                 key: char,
                 code: `Key${char.toUpperCase()}`,
@@ -1345,6 +1347,10 @@ export function sendFileUpload(session, paths, opts, timeoutMs) {
     }
     if (opts?.fieldLabel)
         payload.fieldLabel = opts.fieldLabel;
+    if (opts?.fieldId)
+        payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
     if (opts?.exact !== undefined)
         payload.exact = opts.exact;
     if (opts?.strategy)
@@ -1366,6 +1372,8 @@ export function sendFieldText(session, fieldLabel, value, opts, timeoutMs) {
         payload.exact = opts.exact;
     if (opts?.fieldId)
         payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
     if (opts?.typingDelayMs !== undefined)
         payload.typingDelayMs = opts.typingDelayMs;
     if (opts?.imeFriendly !== undefined)
@@ -1387,6 +1395,10 @@ export function sendFieldChoice(session, fieldLabel, value, opts, timeoutMs = LI
         payload.choiceType = opts.choiceType;
     if (opts?.fieldId)
         payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
+    if (opts?.optionIndex !== undefined)
+        payload.optionIndex = opts.optionIndex;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Fill several semantic form fields in one proxy-side batch. */
@@ -1425,6 +1437,10 @@ export function sendListboxPick(session, label, opts, timeoutMs = LISTBOX_UPDATE
         payload.fieldLabel = opts.fieldLabel;
     if (opts?.query)
         payload.query = opts.query;
+    if (opts?.fieldId)
+        payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
@@ -1445,6 +1461,12 @@ export function sendSetChecked(session, label, opts, timeoutMs) {
         payload.exact = opts.exact;
     if (opts?.controlType)
         payload.controlType = opts.controlType;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
+    if (opts?.contextText)
+        payload.contextText = opts.contextText;
+    if (opts?.sectionText)
+        payload.sectionText = opts.sectionText;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
@@ -2223,6 +2245,26 @@ function buildFieldFormat(node) {
         format.autocomplete = m.autocomplete;
     return Object.keys(format).length > 0 ? format : undefined;
 }
+function nativeSchemaOptions(node, fieldIdentity) {
+    const options = node.meta?.options;
+    if (!options)
+        return undefined;
+    return options.map(option => ({
+        id: `${fieldIdentity}:option:${option.index}`,
+        value: option.value,
+        label: option.label,
+        index: option.index,
+        ...(option.disabled ? { disabled: true } : {}),
+        ...(option.selected ? { selected: true } : {}),
+    }));
+}
+function uniqueSchemaFieldKey(root, node) {
+    const fieldKey = node.meta?.controlKey;
+    if (!fieldKey)
+        return undefined;
+    const matches = collectDescendants(root, candidate => candidate.meta?.controlKey === fieldKey);
+    return matches.length === 1 ? fieldKey : undefined;
+}
 function simpleSchemaField(root, node) {
     const context = nodeContextForNode(root, node);
     const label = fieldLabel(node) ?? sanitizeInlineName(node.name, 80) ?? context?.prompt;
@@ -2251,15 +2293,25 @@ function simpleSchemaField(root, node) {
                 ? 'select'
                 : 'listbox'
         : undefined;
+    const fieldKey = uniqueSchemaFieldKey(root, node);
+    const id = fieldKey ?? formFieldIdForPath(node.path);
     const format = buildFieldFormat(node);
+    const optionDetails = classifiedChoiceType === 'select' ? nativeSchemaOptions(node, id) : undefined;
+    const enabledOptions = optionDetails
+        ? dedupeStrings(optionDetails.filter(option => !option.disabled).map(option => option.label), 64)
+        : undefined;
     return {
-        id: formFieldIdForPath(node.path),
+        id,
+        ...(fieldKey ? { fieldKey } : {}),
         kind: classifiedRole === 'combobox' ? 'choice' : 'text',
         label,
         ...(classifiedChoiceType ? { choiceType: classifiedChoiceType } : {}),
         ...(node.state?.required ? { required: true } : {}),
         ...(node.state?.invalid ? { invalid: true } : {}),
         ...compactSchemaValue(node.value, 72),
+        ...(optionDetails ? { optionCount: optionDetails.length, optionDetails } : {}),
+        ...(enabledOptions && enabledOptions.length > 0 ? { options: enabledOptions } : {}),
+        ...(enabledOptions && computeOptionAliases(enabledOptions) ? { aliases: computeOptionAliases(enabledOptions) } : {}),
         ...(format ? { format } : {}),
         ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
     };
@@ -2304,8 +2356,10 @@ function toggleSchemaField(root, node) {
         return null;
     const context = nodeContextForNode(root, node);
     const controlType = node.role === 'radio' ? 'radio' : 'checkbox';
+    const fieldKey = uniqueSchemaFieldKey(root, node);
     return {
-        id: formFieldIdForPath(node.path),
+        id: fieldKey ?? formFieldIdForPath(node.path),
+        ...(fieldKey ? { fieldKey } : {}),
         kind: 'toggle',
         label,
         controlType,
@@ -2330,7 +2384,10 @@ function detectFormSections(formNode, fields) {
         return [];
     const fieldIdToPath = new Map();
     for (const field of fields) {
-        const parsed = parseFormFieldId(field.id);
+        const authoredMatches = field.fieldKey
+            ? collectDescendants(formNode, node => node.meta?.controlKey === field.fieldKey)
+            : [];
+        const parsed = authoredMatches.length === 1 ? authoredMatches[0].path : parseFormFieldId(field.id);
         if (parsed)
             fieldIdToPath.set(field.id, parsed);
     }
@@ -2428,6 +2485,7 @@ function presentFormSchemaFields(fields, options) {
             next.booleanChoice = true;
         if (!includeOptions) {
             delete next.options;
+            delete next.optionDetails;
             delete next.aliases;
         }
         if (includeContext === 'none') {
@@ -2761,6 +2819,135 @@ export function buildFormSchemas(root, options) {
         .filter(form => !options?.formId || sectionIdForPath('form', form.path) === options.formId)
         .map(form => buildFormSchemaForNode(root, form, options));
 }
+export function buildFormGraphs(root, options) {
+    const pageUrl = typeof root.meta?.pageUrl === 'string' && root.meta.pageUrl.length > 0 ? root.meta.pageUrl : undefined;
+    return buildFormSchemas(root, {
+        ...options,
+        includeOptions: true,
+    }).map(schema => formSchemaToFormGraph(schema, pageUrl));
+}
+export function formSchemaToFormGraph(schema, pageUrl) {
+    const sourceId = 'geometra-page';
+    const formSlug = slugPathSegment(schema.name ?? schema.formId);
+    const pathCounts = new Map();
+    return {
+        formgraph: '0.1',
+        id: `geometra:${schema.formId}`,
+        title: schema.name ?? `Geometra form ${schema.formId}`,
+        description: 'FormGraph-compatible projection of a Geometra form schema.',
+        sources: [
+            {
+                id: sourceId,
+                kind: 'html',
+                title: schema.name ?? 'Geometra-discovered web form',
+                ...(pageUrl ? { url: pageUrl } : {}),
+            },
+        ],
+        fields: schema.fields.map(field => formSchemaFieldToFormGraphField(field, {
+            formSlug,
+            sourceId,
+            pathCounts,
+        })),
+        evidence: [],
+        dependencies: [],
+        review: {
+            autoSubmitAllowed: false,
+            requiredBeforeSubmit: true,
+        },
+        metadata: {
+            producer: 'geometra',
+            geometra: {
+                formId: schema.formId,
+                fieldCount: schema.fieldCount,
+                requiredCount: schema.requiredCount,
+                invalidCount: schema.invalidCount,
+                ...(schema.sections ? { sections: schema.sections } : {}),
+            },
+        },
+    };
+}
+function formSchemaFieldToFormGraphField(field, opts) {
+    const basePath = `web.forms.${opts.formSlug}.${slugPathSegment(field.label || field.id)}`;
+    const path = uniquePath(basePath, opts.pathCounts);
+    const aliases = fieldAliases(field);
+    const options = field.optionDetails
+        ?.filter(option => !option.disabled)
+        .map(option => ({ value: option.value, label: option.label }))
+        ?? field.options?.map(option => ({ value: option, label: option }));
+    const inputType = field.format?.inputType?.toLowerCase();
+    const metadata = {
+        geometra: {
+            fieldId: field.id,
+            ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+            kind: field.kind,
+            ...(field.choiceType ? { choiceType: field.choiceType } : {}),
+            ...(field.controlType ? { controlType: field.controlType } : {}),
+            ...(field.booleanChoice ? { booleanChoice: true } : {}),
+            ...(field.invalid ? { invalid: true } : {}),
+            ...(field.context ? { context: field.context } : {}),
+            ...(field.optionDetails ? { optionDetails: field.optionDetails } : {}),
+        },
+    };
+    return {
+        id: field.fieldKey ?? field.id,
+        path,
+        label: field.label,
+        kind: formGraphFieldKind(field),
+        ...(field.required ? { required: true } : {}),
+        ...(field.invalid ? { reviewRequired: true } : {}),
+        ...(aliases.length > 0 ? { aliases } : {}),
+        ...(options && options.length > 0 ? { options } : {}),
+        ...(field.format?.pattern ? { constraints: { pattern: field.format.pattern } } : {}),
+        sourceAnchors: [
+            {
+                sourceId: opts.sourceId,
+                kind: 'html',
+                fieldName: field.fieldKey ?? field.id,
+                pointer: `geometra:${field.fieldKey ?? field.id}`,
+            },
+        ],
+        ...(inputType ? { metadata: { ...metadata, inputType } } : { metadata }),
+    };
+}
+function formGraphFieldKind(field) {
+    if (field.kind === 'toggle' || field.booleanChoice)
+        return 'boolean';
+    if (field.kind === 'choice' || field.kind === 'multi_choice')
+        return 'enum';
+    const inputType = field.format?.inputType?.toLowerCase();
+    if (inputType === 'email')
+        return 'email';
+    if (inputType === 'tel' || inputType === 'phone')
+        return 'phone';
+    if (inputType === 'date')
+        return 'date';
+    if (inputType === 'number')
+        return 'number';
+    if (field.valueLength !== undefined && field.valueLength > 120)
+        return 'textarea';
+    return 'text';
+}
+function fieldAliases(field) {
+    const values = new Set();
+    if (field.format?.placeholder)
+        values.add(field.format.placeholder);
+    if (field.context?.prompt && normalizeUiText(field.context.prompt) !== normalizeUiText(field.label)) {
+        values.add(field.context.prompt);
+    }
+    return [...values].filter(value => value.trim().length > 0);
+}
+function uniquePath(basePath, seen) {
+    const count = seen.get(basePath) ?? 0;
+    seen.set(basePath, count + 1);
+    return count === 0 ? basePath : `${basePath}.${count + 1}`;
+}
+function slugPathSegment(value) {
+    const normalized = normalizeUiText(value)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return normalized || 'field';
+}
 /**
  * Required-field snapshot for automation: every required field in a form, including
  * offscreen entries, annotated with visibility and scroll hints so agents do not
@@ -2779,7 +2966,10 @@ export function buildFormRequiredSnapshot(root, options) {
         const formNode = parsedForm ? findNodeByPath(root, parsedForm.path) : null;
         const fields = schema.fields
             .map(field => {
-            const fieldPath = parseFormFieldId(field.id);
+            const authoredMatches = field.fieldKey && formNode
+                ? collectDescendants(formNode, node => node.meta?.controlKey === field.fieldKey)
+                : [];
+            const fieldPath = authoredMatches.length === 1 ? authoredMatches[0].path : parseFormFieldId(field.id);
             const target = fieldPath ? findNodeByPath(root, fieldPath) ?? formNode : formNode;
             if (!target)
                 return null;
@@ -3183,6 +3373,32 @@ function normalizeCheckedState(value) {
         return false;
     return undefined;
 }
+function normalizeSemanticOptions(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const options = [];
+    const seenIndices = new Set();
+    for (const entry of value.slice(0, 500)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        if (typeof record.value !== 'string' || typeof record.label !== 'string')
+            continue;
+        if (typeof record.index !== 'number' || !Number.isInteger(record.index) || record.index < 0)
+            continue;
+        if (seenIndices.has(record.index))
+            continue;
+        seenIndices.add(record.index);
+        options.push({
+            value: record.value,
+            label: record.label,
+            disabled: record.disabled === true,
+            selected: record.selected === true,
+            index: record.index,
+        });
+    }
+    return options;
+}
 function normalizeA11yRoleHint(value) {
     if (typeof value !== 'string')
         return undefined;
@@ -3239,6 +3455,15 @@ function walkNode(element, layout, path) {
         meta.scrollY = semantic.scrollY;
     if (typeof semantic?.tag === 'string' && semantic.tag.trim().length > 0)
         meta.controlTag = semantic.tag;
+    if (typeof semantic?.controlKey === 'string' && semantic.controlKey.trim().length > 0)
+        meta.controlKey = semantic.controlKey.trim();
+    if (typeof semantic?.controlId === 'string' && semantic.controlId.trim().length > 0)
+        meta.controlId = semantic.controlId.trim();
+    if (typeof semantic?.controlName === 'string' && semantic.controlName.trim().length > 0)
+        meta.controlName = semantic.controlName.trim();
+    const semanticOptions = normalizeSemanticOptions(semantic?.options);
+    if (semanticOptions)
+        meta.options = semanticOptions;
     if (typeof semantic?.placeholder === 'string')
         meta.placeholder = semantic.placeholder;
     if (typeof semantic?.inputPattern === 'string')
@@ -3352,8 +3577,14 @@ async function sendAndWaitForUpdate(session, message, timeoutMs = ACTION_UPDATE_
     await ensureSessionConnected(session);
     const requestId = `req-${++nextRequestSequence}`;
     const startRevision = session.updateRevision;
-    session.ws.send(JSON.stringify({ ...message, requestId }));
-    return await waitForNextUpdate(session, timeoutMs, requestId, startRevision, opts);
+    session.ws.send(JSON.stringify({ ...message, requestId, protocolVersion: PROXY_PROTOCOL_VERSION }));
+    const requiresExactFieldIdentity = typeof message.fieldKey === 'string' || (message.type === 'fillFields' &&
+        Array.isArray(message.fields) &&
+        message.fields.some(field => typeof field === 'object' && field !== null && typeof field.fieldKey === 'string'));
+    return await waitForNextUpdate(session, timeoutMs, requestId, startRevision, {
+        ...opts,
+        ...(requiresExactFieldIdentity ? { requiredProtocolVersion: PROXY_PROTOCOL_VERSION } : {}),
+    });
 }
 function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, requestId, startRevision = session.updateRevision, opts) {
     return new Promise((resolve, reject) => {
@@ -3380,6 +3611,12 @@ function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, reques
                         return;
                     }
                     if (msg.type === 'ack' && messageRequestId === requestId) {
+                        const peerProtocolVersion = typeof msg.protocolVersion === 'number' ? msg.protocolVersion : undefined;
+                        if (opts?.requiredProtocolVersion !== undefined && (peerProtocolVersion === undefined || peerProtocolVersion < opts.requiredProtocolVersion)) {
+                            cleanup();
+                            reject(new Error(`Proxy protocol ${peerProtocolVersion ?? 'unknown'} cannot guarantee exact field identity; protocol ${opts.requiredProtocolVersion}+ is required. Update and reconnect the Geometra proxy.`));
+                            return;
+                        }
                         ackSeen = true;
                         ackResult = msg.result;
                         if (!opts?.requireUpdateOnAck || session.updateRevision > startRevision) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.63.0",
+  "version": "1.64.0",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     "ui-testing"
   ],
   "dependencies": {
-    "@geometra/proxy": "^1.63.0",
+    "@geometra/proxy": "^1.64.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@razroo/parallel-mcp": "^0.1.0",
     "ws": "^8.18.0",