@geometra/mcp 1.18.1

package/dist/session.d.ts

@@ -0,0 +1,247 @@
+import WebSocket from 'ws';
+/**
+ * Parsed accessibility node from the UI tree + computed layout.
+ * Mirrors the shape of @geometra/core's AccessibilityNode without importing it
+ * (this package is standalone — no dependency on geometra packages).
+ */
+export interface A11yNode {
+    role: string;
+    name?: string;
+    state?: {
+        disabled?: boolean;
+        expanded?: boolean;
+        selected?: boolean;
+    };
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+    children: A11yNode[];
+    focusable: boolean;
+}
+/** Flat, viewport-filtered index for token-efficient agent context (see `buildCompactUiIndex`). */
+export interface CompactUiNode {
+    role: string;
+    name?: string;
+    state?: A11yNode['state'];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+    focusable: boolean;
+}
+/** Higher-level webpage structures extracted from the a11y tree. */
+export interface PageLandmark {
+    role: string;
+    name?: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+}
+export interface PageFieldModel {
+    role: string;
+    name?: string;
+    state?: A11yNode['state'];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+}
+export interface PageActionModel {
+    role: string;
+    name?: string;
+    state?: A11yNode['state'];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+}
+export interface PageFormModel {
+    name?: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+    fieldCount: number;
+    actionCount: number;
+    fields: PageFieldModel[];
+    actions: PageActionModel[];
+}
+export interface PageDialogModel {
+    name?: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+    actionCount: number;
+    actions: PageActionModel[];
+}
+export interface PageListModel {
+    name?: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+    itemCount: number;
+    itemsPreview: string[];
+}
+export interface PageModel {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    landmarks: PageLandmark[];
+    forms: PageFormModel[];
+    dialogs: PageDialogModel[];
+    lists: PageListModel[];
+}
+export interface UiNodeUpdate {
+    before: CompactUiNode;
+    after: CompactUiNode;
+    changes: string[];
+}
+export interface UiListCountChange {
+    name?: string;
+    path: number[];
+    beforeCount: number;
+    afterCount: number;
+}
+/** Semantic delta between two compact viewport models. */
+export interface UiDelta {
+    added: CompactUiNode[];
+    removed: CompactUiNode[];
+    updated: UiNodeUpdate[];
+    dialogsOpened: PageDialogModel[];
+    dialogsClosed: PageDialogModel[];
+    formsAppeared: PageFormModel[];
+    formsRemoved: PageFormModel[];
+    listCountsChanged: UiListCountChange[];
+}
+export interface Session {
+    ws: WebSocket;
+    layout: Record<string, unknown> | null;
+    tree: Record<string, unknown> | null;
+    url: string;
+}
+/**
+ * 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 getSession(): Session | null;
+export declare function disconnect(): void;
+/**
+ * Send a click event at (x, y) and wait for the next frame/patch response.
+ */
+export declare function sendClick(session: Session, x: number, y: number): Promise<void>;
+/**
+ * Send a sequence of key events to type text into the focused element.
+ */
+export declare function sendType(session: Session, text: string): Promise<void>;
+/**
+ * Send a special key (Enter, Tab, Escape, etc.)
+ */
+export declare function sendKey(session: Session, key: string, modifiers?: {
+    shift?: boolean;
+    ctrl?: boolean;
+    meta?: boolean;
+    alt?: boolean;
+}): Promise<void>;
+/**
+ * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
+ * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
+ */
+export declare function sendFileUpload(session: Session, paths: string[], opts?: {
+    click?: {
+        x: number;
+        y: number;
+    };
+    strategy?: 'auto' | 'chooser' | 'hidden' | 'drop';
+    drop?: {
+        x: number;
+        y: number;
+    };
+}): Promise<void>;
+/** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
+export declare function sendListboxPick(session: Session, label: string, opts?: {
+    exact?: boolean;
+    open?: {
+        x: number;
+        y: number;
+    };
+}): Promise<void>;
+/** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
+export declare function sendSelectOption(session: Session, x: number, y: number, option: {
+    value?: string;
+    label?: string;
+    index?: number;
+}): Promise<void>;
+/** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
+export declare function sendWheel(session: Session, deltaY: number, opts?: {
+    deltaX?: number;
+    x?: number;
+    y?: number;
+}): Promise<void>;
+/**
+ * Build a flat accessibility tree from the raw UI tree + layout.
+ * This is a standalone reimplementation that works with raw JSON —
+ * no dependency on @geometra/core.
+ */
+export declare function buildA11yTree(tree: Record<string, unknown>, layout: Record<string, unknown>): A11yNode;
+/**
+ * Flat list of actionable / semantic nodes in the viewport, sorted with focusable first
+ * then top-to-bottom reading order. Intended to minimize LLM tokens vs a full nested tree.
+ */
+export declare function buildCompactUiIndex(root: A11yNode, options?: {
+    viewportWidth?: number;
+    viewportHeight?: number;
+    maxNodes?: number;
+}): {
+    nodes: CompactUiNode[];
+    truncated: boolean;
+};
+export declare function summarizeCompactIndex(nodes: CompactUiNode[], maxLines?: number): string;
+/**
+ * Build a compact, webpage-shaped model from the accessibility tree:
+ * landmarks, dialogs, forms, and lists with short previews.
+ */
+export declare function buildPageModel(root: A11yNode, options?: {
+    maxFieldsPerForm?: number;
+    maxActionsPerContainer?: number;
+    maxItemsPerList?: number;
+}): PageModel;
+export declare function summarizePageModel(model: PageModel, maxLines?: number): string;
+/**
+ * Compare two accessibility trees at the compact viewport layer plus a few
+ * higher-level structures (dialogs, forms, lists).
+ */
+export declare function buildUiDelta(before: A11yNode, after: A11yNode, options?: {
+    maxNodes?: number;
+}): UiDelta;
+export declare function hasUiDelta(delta: UiDelta): boolean;
+export declare function summarizeUiDelta(delta: UiDelta, maxLines?: number): string;