@geometra/mcp 1.19.11 → 1.19.13

package/dist/session.d.ts

@@ -61,6 +61,23 @@ export interface CompactUiContext {
     scrollY?: number;
     focusedNode?: CompactUiNode;
 }
+export interface NodeContextModel {
+    prompt?: string;
+    section?: string;
+}
+export interface NodeVisibilityModel {
+    intersectsViewport: boolean;
+    fullyVisible: boolean;
+    offscreenAbove: boolean;
+    offscreenBelow: boolean;
+    offscreenLeft: boolean;
+    offscreenRight: boolean;
+}
+export interface NodeScrollHintModel {
+    status: 'visible' | 'partial' | 'offscreen';
+    revealDeltaX: number;
+    revealDeltaY: number;
+}
 export type PageSectionKind = 'landmark' | 'form' | 'dialog' | 'list';
 export type PageArchetype = 'shell' | 'form' | 'dialog' | 'results' | 'content' | 'dashboard';
 interface PageSectionSummaryBase {
@@ -136,6 +153,9 @@ export interface PageFieldModel {
     value?: string;
     state?: A11yNode['state'];
     validation?: A11yNode['validation'];
+    context?: NodeContextModel;
+    visibility?: NodeVisibilityModel;
+    scrollHint?: NodeScrollHintModel;
     bounds?: {
         x: number;
         y: number;
@@ -148,6 +168,9 @@ export interface PageActionModel {
     role: string;
     name?: string;
     state?: A11yNode['state'];
+    context?: NodeContextModel;
+    visibility?: NodeVisibilityModel;
+    scrollHint?: NodeScrollHintModel;
     bounds?: {
         x: number;
         y: number;
@@ -179,10 +202,38 @@ export interface PageSectionDetail {
     summary: {
         headingCount: number;
         fieldCount: number;
+        requiredFieldCount: number;
+        invalidFieldCount: number;
         actionCount: number;
         listCount: number;
         itemCount: number;
     };
+    page: {
+        fields: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+        actions: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+        lists: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+        items: {
+            offset: number;
+            returned: number;
+            total: number;
+            hasMore: boolean;
+        };
+    };
     headings: PageHeadingModel[];
     fields: PageFieldModel[];
     actions: PageActionModel[];
@@ -190,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;
@@ -362,15 +437,27 @@ 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.
  */
 export declare function expandPageSection(root: A11yNode, id: string, options?: {
     maxHeadings?: number;
     maxFields?: number;
+    fieldOffset?: number;
+    onlyRequiredFields?: boolean;
+    onlyInvalidFields?: boolean;
     maxActions?: number;
+    actionOffset?: number;
     maxLists?: number;
+    listOffset?: number;
     maxItems?: number;
+    itemOffset?: number;
     maxTextPreview?: number;
     includeBounds?: boolean;
 }): PageSectionDetail | null;

package/dist/session.js

@@ -387,6 +387,9 @@ function decodePath(encoded) {
 export function nodeIdForPath(path) {
     return `n:${encodePath(path)}`;
 }
+function formFieldIdForPath(path) {
+    return `ff:${encodePath(path)}`;
+}
 function sectionPrefix(kind) {
     if (kind === 'landmark')
         return 'lm';
@@ -743,8 +746,111 @@ function primaryAction(node) {
         bounds: cloneBounds(node.bounds),
     };
 }
-function toFieldModel(node, includeBounds = true) {
+function buildVisibility(bounds, viewport) {
+    const visibleLeft = Math.max(0, bounds.x);
+    const visibleTop = Math.max(0, bounds.y);
+    const visibleRight = Math.min(viewport.width, bounds.x + bounds.width);
+    const visibleBottom = Math.min(viewport.height, bounds.y + bounds.height);
+    const hasVisibleIntersection = visibleRight > visibleLeft && visibleBottom > visibleTop;
+    const fullyVisible = bounds.x >= 0 &&
+        bounds.y >= 0 &&
+        bounds.x + bounds.width <= viewport.width &&
+        bounds.y + bounds.height <= viewport.height;
+    return {
+        intersectsViewport: hasVisibleIntersection,
+        fullyVisible,
+        offscreenAbove: bounds.y + bounds.height <= 0,
+        offscreenBelow: bounds.y >= viewport.height,
+        offscreenLeft: bounds.x + bounds.width <= 0,
+        offscreenRight: bounds.x >= viewport.width,
+    };
+}
+function buildScrollHint(bounds, viewport) {
+    const visibility = buildVisibility(bounds, viewport);
+    return {
+        status: visibility.fullyVisible ? 'visible' : visibility.intersectsViewport ? 'partial' : 'offscreen',
+        revealDeltaX: Math.round(bounds.x + bounds.width / 2 - viewport.width / 2),
+        revealDeltaY: Math.round(bounds.y + bounds.height / 2 - viewport.height / 2),
+    };
+}
+function ancestorNodes(root, path) {
+    const out = [];
+    let current = root;
+    for (const index of path) {
+        out.push(current);
+        if (!current.children[index])
+            break;
+        current = current.children[index];
+    }
+    return out;
+}
+function countGroupedChoiceControls(node) {
+    return collectDescendants(node, candidate => candidate.role === 'radio' || candidate.role === 'checkbox' || candidate.role === 'button').length;
+}
+function nearestPromptText(container, target) {
+    const candidates = collectDescendants(container, candidate => (candidate.role === 'heading' || candidate.role === 'text') &&
+        !!sanitizeInlineName(candidate.name, 120) &&
+        pathKey(candidate.path) !== pathKey(target.path));
+    const normalizedTarget = normalizeUiText(target.name ?? '');
+    const best = candidates
+        .filter(candidate => candidate.bounds.y <= target.bounds.y + 8)
+        .map(candidate => {
+        const text = sanitizeInlineName(candidate.name, 120);
+        if (!text)
+            return null;
+        if (normalizeUiText(text) === normalizedTarget)
+            return null;
+        const dy = Math.max(0, target.bounds.y - candidate.bounds.y);
+        const dx = Math.abs(target.bounds.x - candidate.bounds.x);
+        const headingBonus = candidate.role === 'heading' ? -32 : 0;
+        const questionBonus = /\?\s*$/.test(text) ? -160 : 0;
+        const lengthPenalty = text.length > 90 ? 80 : text.length > 60 ? 40 : text.length > 45 ? 20 : 0;
+        return { text, score: dy * 4 + dx + headingBonus + questionBonus + lengthPenalty };
+    })
+        .filter((candidate) => !!candidate)
+        .sort((a, b) => a.score - b.score)[0];
+    return best?.text;
+}
+function nodeContext(root, node) {
+    const ancestors = ancestorNodes(root, node.path);
+    let prompt;
+    const promptEligibleNode = node.role === 'radio' || node.role === 'button';
+    if (promptEligibleNode) {
+        for (let index = ancestors.length - 1; index >= 0; index--) {
+            const ancestor = ancestors[index];
+            const grouped = countGroupedChoiceControls(ancestor) >= 2;
+            const eligiblePromptContainer = (ancestor.role === 'group' && ancestor.path.length > 0) ||
+                ancestor.role === 'dialog' ||
+                (ancestor.role === 'form' && grouped);
+            if (eligiblePromptContainer) {
+                prompt = nearestPromptText(ancestor, node);
+                if (prompt)
+                    break;
+            }
+        }
+    }
+    let section;
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        const kind = sectionKindForNode(ancestor);
+        if (!kind)
+            continue;
+        section = sectionDisplayName(ancestor, kind);
+        if (section)
+            break;
+    }
+    if (!prompt && !section)
+        return undefined;
+    return {
+        ...(prompt ? { prompt } : {}),
+        ...(section ? { section } : {}),
+    };
+}
+function toFieldModel(root, node, includeBounds = true) {
     const value = sanitizeInlineName(node.value, 120);
+    const context = nodeContext(root, node);
+    const visibility = buildVisibility(node.bounds, root.bounds);
+    const scrollHint = buildScrollHint(node.bounds, root.bounds);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
@@ -752,18 +858,194 @@ function toFieldModel(node, includeBounds = true) {
         ...(value ? { value } : {}),
         ...(cloneState(node.state) ? { state: cloneState(node.state) } : {}),
         ...(cloneValidation(node.validation) ? { validation: cloneValidation(node.validation) } : {}),
+        ...(context ? { context } : {}),
+        visibility,
+        scrollHint,
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
 }
-function toActionModel(node, includeBounds = true) {
+function toActionModel(root, node, includeBounds = true) {
+    const context = nodeContext(root, node);
+    const visibility = buildVisibility(node.bounds, root.bounds);
+    const scrollHint = buildScrollHint(node.bounds, root.bounds);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         ...(sanitizeInlineName(node.name, 80) ? { name: sanitizeInlineName(node.name, 80) } : {}),
         ...(cloneState(node.state) ? { state: cloneState(node.state) } : {}),
+        ...(context ? { context } : {}),
+        visibility,
+        scrollHint,
         ...(includeBounds ? { bounds: cloneBounds(node.bounds) } : {}),
     };
 }
+function compactSchemaContext(context, label) {
+    if (!context)
+        return undefined;
+    const out = {};
+    if (context.prompt && normalizeUiText(context.prompt) !== normalizeUiText(label))
+        out.prompt = context.prompt;
+    if (context.section)
+        out.section = context.section;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function compactSchemaValue(value, inlineLimit = 80) {
+    const normalized = sanitizeInlineName(value, Math.max(120, inlineLimit + 32));
+    if (!normalized)
+        return {};
+    return normalized.length <= inlineLimit
+        ? { value: normalized }
+        : { valueLength: normalized.length };
+}
+function schemaOptionLabel(node) {
+    return sanitizeFieldName(node.name, 80) ?? sanitizeInlineName(node.name, 80);
+}
+function isGroupedChoiceControl(node) {
+    return node.role === 'radio' || node.role === 'checkbox' || (node.role === 'button' && node.focusable);
+}
+function groupedChoiceForNode(root, formNode, seed) {
+    const context = nodeContext(root, seed);
+    const prompt = context?.prompt;
+    if (!prompt)
+        return null;
+    const matchesPrompt = (candidate) => {
+        if (!isGroupedChoiceControl(candidate))
+            return false;
+        return nodeContext(root, candidate)?.prompt === prompt;
+    };
+    const ancestors = ancestorNodes(root, seed.path);
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        if (ancestor.role === 'form')
+            continue;
+        const controls = sortByBounds(collectDescendants(ancestor, matchesPrompt));
+        if (controls.length >= 2) {
+            return { container: ancestor, prompt, controls };
+        }
+    }
+    if (seed.role !== 'radio' && seed.role !== 'button')
+        return null;
+    const controls = sortByBounds(collectDescendants(formNode, matchesPrompt));
+    return controls.length >= 2 ? { container: formNode, prompt, controls } : null;
+}
+function simpleSchemaField(root, node) {
+    const context = nodeContext(root, node);
+    const label = fieldLabel(node) ?? sanitizeInlineName(node.name, 80) ?? context?.prompt;
+    if (!label)
+        return null;
+    return {
+        id: formFieldIdForPath(node.path),
+        kind: node.role === 'combobox' ? 'choice' : 'text',
+        label,
+        ...(node.state?.required ? { required: true } : {}),
+        ...(node.state?.invalid ? { invalid: true } : {}),
+        ...compactSchemaValue(node.value, 72),
+        ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
+    };
+}
+function groupedSchemaField(root, grouped) {
+    const optionEntries = grouped.controls
+        .map(control => ({
+        label: schemaOptionLabel(control),
+        selected: control.state?.checked === true || control.state?.selected === true,
+        role: control.role,
+    }))
+        .filter((entry) => !!entry.label);
+    if (optionEntries.length < 2)
+        return null;
+    const options = dedupeStrings(optionEntries.map(entry => entry.label), 16);
+    const selectedOptions = dedupeStrings(optionEntries.filter(entry => entry.selected).map(entry => entry.label), 16);
+    const radioLike = optionEntries.every(entry => entry.role === 'radio' || entry.role === 'button');
+    const context = nodeContext(root, grouped.controls[0]);
+    return {
+        id: formFieldIdForPath(grouped.container.path),
+        kind: radioLike ? 'choice' : 'multi_choice',
+        label: grouped.prompt,
+        ...(grouped.controls.some(control => control.state?.required) ? { required: true } : {}),
+        ...(grouped.controls.some(control => control.state?.invalid) ? { invalid: true } : {}),
+        ...(radioLike
+            ? {
+                ...(selectedOptions[0] ? { value: selectedOptions[0] } : {}),
+            }
+            : {
+                ...(selectedOptions.length > 0 ? { values: selectedOptions } : {}),
+            }),
+        optionCount: options.length,
+        options,
+        ...(compactSchemaContext(context, grouped.prompt) ? { context: compactSchemaContext(context, grouped.prompt) } : {}),
+    };
+}
+function toggleSchemaField(root, node) {
+    const label = schemaOptionLabel(node);
+    if (!label)
+        return null;
+    const context = nodeContext(root, node);
+    const controlType = node.role === 'radio' ? 'radio' : 'checkbox';
+    return {
+        id: formFieldIdForPath(node.path),
+        kind: 'toggle',
+        label,
+        controlType,
+        ...(node.state?.required ? { required: true } : {}),
+        ...(node.state?.invalid ? { invalid: true } : {}),
+        ...(node.state?.checked !== undefined ? { checked: node.state.checked === true } : {}),
+        ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
+    };
+}
+function buildFormSchemaForNode(root, formNode, options) {
+    const candidates = sortByBounds(collectDescendants(formNode, candidate => candidate.role === 'textbox' ||
+        candidate.role === 'combobox' ||
+        candidate.role === 'checkbox' ||
+        candidate.role === 'radio' ||
+        (candidate.role === 'button' && candidate.focusable)));
+    const consumed = new Set();
+    const fields = [];
+    for (const candidate of candidates) {
+        const candidateKey = pathKey(candidate.path);
+        if (consumed.has(candidateKey))
+            continue;
+        if (candidate.role === 'textbox' || candidate.role === 'combobox') {
+            const field = simpleSchemaField(root, candidate);
+            if (field)
+                fields.push(field);
+            consumed.add(candidateKey);
+            continue;
+        }
+        const grouped = groupedChoiceForNode(root, formNode, candidate);
+        if (grouped && grouped.controls.some(control => pathKey(control.path) === candidateKey)) {
+            const field = groupedSchemaField(root, grouped);
+            for (const control of grouped.controls)
+                consumed.add(pathKey(control.path));
+            if (field)
+                fields.push(field);
+            continue;
+        }
+        if (candidate.role === 'checkbox' || candidate.role === 'radio') {
+            const field = toggleSchemaField(root, candidate);
+            if (field)
+                fields.push(field);
+            consumed.add(candidateKey);
+        }
+    }
+    const filteredFields = fields.filter(field => {
+        if (options?.onlyRequiredFields && !field.required)
+            return false;
+        if (options?.onlyInvalidFields && !field.invalid)
+            return false;
+        return true;
+    });
+    const maxFields = options?.maxFields ?? filteredFields.length;
+    const pageFields = filteredFields.slice(0, maxFields);
+    const name = sectionDisplayName(formNode, 'form');
+    return {
+        formId: sectionIdForPath('form', formNode.path),
+        ...(name ? { name } : {}),
+        fieldCount: fields.length,
+        requiredCount: fields.filter(field => field.required).length,
+        invalidCount: fields.filter(field => field.invalid).length,
+        fields: pageFields,
+    };
+}
 function toLandmarkModel(node) {
     const name = sectionDisplayName(node, 'landmark');
     return {
@@ -887,6 +1169,15 @@ export function buildPageModel(root, options) {
         archetypes: inferPageArchetypes(baseModel),
     };
 }
+export function buildFormSchemas(root, options) {
+    const forms = sortByBounds([
+        ...(root.role === 'form' ? [root] : []),
+        ...collectDescendants(root, candidate => candidate.role === 'form'),
+    ]);
+    return forms
+        .filter(form => !options?.formId || sectionIdForPath('form', form.path) === options.formId)
+        .map(form => buildFormSchemaForNode(root, form, options));
+}
 function headingModels(node, maxHeadings, includeBounds) {
     const headings = sortByBounds(collectDescendants(node, candidate => candidate.role === 'heading' && !!sanitizeInlineName(candidate.name, 80)));
     return headings.slice(0, maxHeadings).map(heading => ({
@@ -931,9 +1222,15 @@ export function expandPageSection(root, id, options) {
         return null;
     const maxHeadings = options?.maxHeadings ?? 6;
     const maxFields = options?.maxFields ?? 18;
+    const fieldOffset = Math.max(0, options?.fieldOffset ?? 0);
+    const onlyRequiredFields = options?.onlyRequiredFields ?? false;
+    const onlyInvalidFields = options?.onlyInvalidFields ?? false;
     const maxActions = options?.maxActions ?? 12;
+    const actionOffset = Math.max(0, options?.actionOffset ?? 0);
     const maxLists = options?.maxLists ?? 8;
+    const listOffset = Math.max(0, options?.listOffset ?? 0);
     const maxItems = options?.maxItems ?? 20;
+    const itemOffset = Math.max(0, options?.itemOffset ?? 0);
     const maxTextPreview = options?.maxTextPreview ?? 6;
     const includeBounds = options?.includeBounds ?? false;
     const headingsAll = sortByBounds(collectDescendants(node, candidate => candidate.role === 'heading' && !!sanitizeInlineName(candidate.name, 80)));
@@ -943,6 +1240,19 @@ export function expandPageSection(root, id, options) {
     const itemsAll = actualKind === 'list'
         ? sortByBounds(collectDescendants(node, candidate => candidate.role === 'listitem'))
         : [];
+    const requiredFieldCount = fieldsAll.filter(field => field.state?.required).length;
+    const invalidFieldCount = fieldsAll.filter(field => field.state?.invalid).length;
+    const filteredFields = fieldsAll.filter(field => {
+        if (onlyRequiredFields && !field.state?.required)
+            return false;
+        if (onlyInvalidFields && !field.state?.invalid)
+            return false;
+        return true;
+    });
+    const pageFields = filteredFields.slice(fieldOffset, fieldOffset + maxFields);
+    const pageActions = actionsAll.slice(actionOffset, actionOffset + maxActions);
+    const pageLists = nestedListsAll.slice(listOffset, listOffset + maxLists);
+    const pageItems = itemsAll.slice(itemOffset, itemOffset + maxItems);
     const name = sectionDisplayName(node, actualKind);
     return {
         id: sectionIdForPath(actualKind, node.path),
@@ -953,15 +1263,49 @@ export function expandPageSection(root, id, options) {
         summary: {
             headingCount: headingsAll.length,
             fieldCount: fieldsAll.length,
+            requiredFieldCount,
+            invalidFieldCount,
             actionCount: actionsAll.length,
             listCount: nestedListsAll.length,
             itemCount: itemsAll.length,
         },
+        page: {
+            fields: {
+                offset: fieldOffset,
+                returned: pageFields.length,
+                total: filteredFields.length,
+                hasMore: fieldOffset + pageFields.length < filteredFields.length,
+            },
+            actions: {
+                offset: actionOffset,
+                returned: pageActions.length,
+                total: actionsAll.length,
+                hasMore: actionOffset + pageActions.length < actionsAll.length,
+            },
+            lists: {
+                offset: listOffset,
+                returned: pageLists.length,
+                total: nestedListsAll.length,
+                hasMore: listOffset + pageLists.length < nestedListsAll.length,
+            },
+            items: {
+                offset: itemOffset,
+                returned: pageItems.length,
+                total: itemsAll.length,
+                hasMore: itemOffset + pageItems.length < itemsAll.length,
+            },
+        },
         headings: headingModels(node, maxHeadings, includeBounds),
-        fields: fieldsAll.slice(0, maxFields).map(field => toFieldModel(field, includeBounds)),
-        actions: actionsAll.slice(0, maxActions).map(action => toActionModel(action, includeBounds)),
-        lists: nestedListSummaries(node, maxLists, node.path),
-        items: itemsAll.slice(0, maxItems).map(item => ({
+        fields: pageFields.map(field => toFieldModel(root, field, includeBounds)),
+        actions: pageActions.map(action => toActionModel(root, action, includeBounds)),
+        lists: pageLists.map(list => ({
+            id: sectionIdForPath('list', list.path),
+            role: list.role,
+            ...(sectionDisplayName(list, 'list') ? { name: sectionDisplayName(list, 'list') } : {}),
+            bounds: cloneBounds(list.bounds),
+            itemCount: collectDescendants(list, candidate => candidate.role === 'listitem').length,
+        })),
+        items: pageItems.map(item => ({
             id: nodeIdForPath(item.path),
             ...(listItemName(item) ? { name: listItemName(item) } : {}),
             ...(includeBounds ? { bounds: cloneBounds(item.bounds) } : {}),

package/package.json

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