Add pagination (page) feature for clipped tree content

Add Session.page() to serve slices of cached raw tree for offscreen
items without UI scrolling. Includes page MCP tool, serializePage
formatter, findNodeById utility, updated clipping hints to reference
page(), streamlined ALL_ROLES set, and pagination tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: k4cper-g

docs/api-reference.md

@@ -246,7 +246,7 @@ Each node in the tree:
 }
 ```
 
-**Roles:** 54 ARIA-derived roles. See [schema/mappings.json](../schema/mappings.json) for the full list and per-platform mappings.
+**Roles:** 59 ARIA-derived roles. See [schema/mappings.json](../schema/mappings.json) for the full list and per-platform mappings.
 
 **States:** `busy`, `checked`, `collapsed`, `disabled`, `editable`, `expanded`, `focused`, `hidden`, `mixed`, `modal`, `multiselectable`, `offscreen`, `pressed`, `readonly`, `required`, `selected`
 

src/format.ts

@@ -255,7 +255,7 @@ function pruneNode(
     const childBounds = child.bounds;
     if (childViewport && childBounds && isOutsideViewport(childBounds, childViewport)) {
       const dir = clipDirection(childBounds, childViewport);
-      clipped[dir as keyof typeof clipped] += countNodes([child]);
+      clipped[dir as keyof typeof clipped] += 1;
       hasClipped = true;
       continue;
     }
@@ -306,6 +306,22 @@ export function pruneTree(
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// Tree utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a node by its element ID in a tree (recursive DFS).
+ */
+export function findNodeById(tree: CupNode[], id: string): CupNode | null {
+  for (const node of tree) {
+    if (node.id === id) return node;
+    const found = findNodeById(node.children ?? [], id);
+    if (found) return found;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Compact text serializer
 // ---------------------------------------------------------------------------
@@ -500,7 +516,8 @@ function emitCompact(node: CupNode, depth: number, lines: string[], counter: num
       if (left > 0) directions.push("left");
       if (right_ > 0) directions.push("right");
       const hintIndent = "  ".repeat(depth + 1);
-      lines.push(`${hintIndent}# ${total} more items — scroll ${directions.join("/")} to see`);
+      const dir = directions[0] ?? "down";
+      lines.push(`${hintIndent}# ${total} more items — page(element_id='${node.id}', direction='${dir}') to see`);
     }
   }
 }
@@ -573,3 +590,46 @@ export function serializeCompact(
 
   return output;
 }
+
+/**
+ * Serialize a page of children from a scrollable container as compact text.
+ *
+ * Used by Session.page() to return a slice of clipped children without
+ * re-capturing the full tree.
+ */
+export function serializePage(
+  container: CupNode,
+  pageItems: CupNode[],
+  offset: number,
+  total: number,
+): string {
+  const roleName = ROLE_CODES[container.role] ?? container.role;
+  const nameStr = container.name ? ` "${container.name}"` : "";
+  const end = Math.min(offset + pageItems.length, total);
+  const headerLines = [
+    `# page ${container.id} | items ${offset + 1}-${end} of ${total} | ${roleName}${nameStr}`,
+    "",
+  ];
+
+  const lines: string[] = [];
+  const counter = [0];
+  for (const item of pageItems) {
+    emitCompact(item, 0, lines, counter);
+  }
+
+  const footerLines: string[] = [];
+  const remaining = total - end;
+  if (remaining > 0) {
+    footerLines.push("");
+    footerLines.push(
+      `# ${remaining} more — page(element_id='${container.id}', direction='down')`,
+    );
+  }
+  if (offset > 0) {
+    footerLines.push(
+      `# ${offset} before — page(element_id='${container.id}', direction='up')`,
+    );
+  }
+
+  return [...headerLines, ...lines, ...footerLines].join("\n") + "\n";
+}

src/index.ts

@@ -25,6 +25,8 @@ import {
   pruneTree,
   serializeCompact,
   serializeOverview,
+  serializePage,
+  findNodeById,
   formatLine,
 } from "./format.js";
 import { searchTree } from "./search.js";
@@ -49,6 +51,7 @@ export class Session {
   private executor: ActionExecutor;
   private lastTree: CupNode[] | null = null;
   private lastRawTree: CupNode[] | null = null;
+  private _pageCursors: Map<string, number> = new Map();
 
   private constructor(adapter: PlatformAdapter) {
     this.adapter = adapter;
@@ -174,6 +177,7 @@ export class Session {
     // Store raw tree for search + pruned tree for compact
     this.lastRawTree = envelope.tree;
     this.lastTree = pruneTree(envelope.tree, { detail });
+    this._pageCursors.clear();
 
     if (compact) {
       return serializeCompact(envelope, { windowList, detail });
@@ -189,20 +193,23 @@ export class Session {
     actionName: string,
     params?: Record<string, unknown>,
   ): Promise<ActionResult> {
+    this._pageCursors.clear();
     return this.executor.action(elementId, actionName, params);
   }
 
   /**
    * Send a keyboard shortcut to the focused window.
    */
   async press(combo: string): Promise<ActionResult> {
+    this._pageCursors.clear();
     return this.executor.press(combo);
   }
 
   /**
    * Open an application by name (fuzzy matched).
    */
   async openApp(name: string): Promise<ActionResult> {
+    this._pageCursors.clear();
     return this.executor.openApp(name);
   }
 
@@ -231,6 +238,107 @@ export class Session {
     return results.map((r) => r.node);
   }
 
+  /**
+   * Page through clipped content in a scrollable container.
+   *
+   * Serves slices of the cached raw tree — no UI scrolling needed.
+   * Provides deterministic, contiguous pagination of offscreen items.
+   */
+  page(
+    elementId: string,
+    options?: {
+      direction?: "up" | "down" | "left" | "right";
+      offset?: number;
+      limit?: number;
+    },
+  ): string {
+    if (this.lastRawTree === null || this.lastTree === null) {
+      throw new Error("No tree captured. Call snapshot() first.");
+    }
+
+    const rawContainer = findNodeById(this.lastRawTree, elementId);
+    if (!rawContainer) {
+      throw new Error(`Element '${elementId}' not found in current tree.`);
+    }
+
+    const rawChildren = rawContainer.children ?? [];
+    if (rawChildren.length === 0) {
+      throw new Error(`Container '${elementId}' has no children to paginate.`);
+    }
+
+    // Get pruned container for visible count and _clipped metadata
+    const prunedContainer = findNodeById(this.lastTree, elementId);
+    const visibleCount = prunedContainer?.children?.length ?? 0;
+    const clipped = prunedContainer?._clipped;
+    const clippedAbove = clipped?.above ?? 0;
+    const clippedBelow = clipped?.below ?? 0;
+    const clippedLeft = clipped?.left ?? 0;
+    const clippedRight = clipped?.right ?? 0;
+    const clippedCount = clippedAbove + clippedBelow + clippedLeft + clippedRight;
+
+    // Virtual scroll detection: if raw tree has far fewer children than
+    // visible + clipped, the content is likely lazy-loaded
+    if (clippedCount > 0) {
+      const expectedTotal = visibleCount + clippedCount;
+      if (rawChildren.length < expectedTotal * 0.8) {
+        throw new Error(
+          `Container '${elementId}' appears to use virtual scrolling ` +
+          `(raw: ${rawChildren.length}, expected: ~${expectedTotal}). ` +
+          `Use action(action='scroll', element_id='${elementId}', direction='...') ` +
+          `followed by snapshot() instead.`,
+        );
+      }
+    }
+
+    const direction = options?.direction;
+    const total = rawChildren.length;
+    const defaultPageSize = visibleCount > 0 ? visibleCount : 20;
+    const pageSize = options?.limit ?? defaultPageSize;
+
+    // Compute directional start offsets from clipping metadata.
+    // Clipped-above items are at the start of the children array (low indices),
+    // clipped-below items are at the end (high indices), because children are
+    // in document/spatial order.
+    const startDown = total - clippedBelow;   // first below-clipped child
+    const startUp = clippedAbove - 1;          // last above-clipped child (page backwards from here)
+    const startRight = total - clippedRight;
+    const startLeft = clippedLeft - 1;
+
+    // Determine offset
+    let currentOffset: number;
+    if (options?.offset != null) {
+      currentOffset = options.offset;
+    } else if (direction) {
+      const cursor = this._pageCursors.get(elementId);
+      if (cursor == null) {
+        // First page call — start at the boundary of clipped content
+        if (direction === "down") currentOffset = startDown;
+        else if (direction === "right") currentOffset = startRight;
+        else if (direction === "up") currentOffset = Math.max(0, startUp - pageSize + 1);
+        else /* left */ currentOffset = Math.max(0, startLeft - pageSize + 1);
+      } else {
+        currentOffset =
+          direction === "down" || direction === "right"
+            ? cursor + pageSize
+            : Math.max(0, cursor - pageSize);
+      }
+    } else {
+      // No direction or offset — show first page of hidden content
+      currentOffset = startDown;
+    }
+
+    // Clamp
+    currentOffset = Math.max(0, Math.min(currentOffset, total - 1));
+
+    // Slice
+    const pageItems = rawChildren.slice(currentOffset, currentOffset + pageSize);
+
+    // Track cursor
+    this._pageCursors.set(elementId, currentOffset);
+
+    return serializePage(rawContainer, pageItems, currentOffset, total);
+  }
+
   /**
    * Execute a sequence of actions, stopping on first failure.
    */

src/mcp/server.ts

@@ -20,15 +20,17 @@ export const server = new McpServer(
       "tree of the user's computer.\n\n" +
       "WORKFLOW — follow this pattern:\n" +
       "1. snapshot to capture the active window's UI\n" +
-      "2. find to locate specific elements (PREFERRED over re-capturing)\n" +
-      "3. action to interact (click, type, press, etc.)\n" +
-      "4. Re-capture ONLY after actions change the UI\n\n" +
+      "2. If you see 'N more items — page(...)', call page to see hidden items\n" +
+      "3. find to locate specific elements (PREFERRED over re-capturing)\n" +
+      "4. action to interact (click, type, press, etc.)\n" +
+      "5. Re-capture ONLY after actions change the UI\n\n" +
       "TOOLS:\n" +
       "- snapshot() — active window tree + window list (most common)\n" +
       "- snapshot_app(app) — specific app by title (when not in foreground)\n" +
       "- overview() — just the window list, near-instant\n" +
       "- snapshot_desktop() — desktop icons and widgets\n" +
       "- find(role/name/state) — search last tree without re-capturing\n" +
+      "- page(element_id, direction) — page through clipped items in a scrollable container\n" +
       "- action(action, ...) — interact with elements or press keys\n" +
       "- open_app(name) — open an app by name with fuzzy matching\n" +
       "- screenshot(region) — visual context when tree isn't enough\n\n" +
@@ -322,6 +324,52 @@ Both modes can be combined: query + state="focused" narrows to focused elements.
   },
 );
 
+// ---------------------------------------------------------------------------
+// Pagination tool
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "page",
+  `Page through clipped content in a scrollable container.
+
+When a snapshot shows "N more items — page(...) to see", use this
+tool to retrieve the next batch of hidden children from the cached tree.
+
+This does NOT scroll the actual UI — it serves from the cached tree.
+For guaranteed contiguity, call with just element_id and direction.
+
+After any action or new snapshot, pagination resets.`,
+  {
+    element_id: z.string().describe("Scrollable container element ID (e.g., 'e5')"),
+    direction: z
+      .enum(["up", "down", "left", "right"])
+      .optional()
+      .describe("Page direction — advance or retreat one page"),
+    offset: z.number().int().optional().describe("Jump to a specific child index (overrides direction)"),
+    limit: z.number().int().optional().describe("Override page size (default: match viewport count)"),
+  },
+  async ({ element_id, direction, offset, limit }) => {
+    const session = await getSession();
+    try {
+      const result = session.page(element_id, { direction, offset, limit });
+      return { content: [{ type: "text", text: result }] };
+    } catch (err: any) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              message: "",
+              error: err.message ?? String(err),
+            }),
+          },
+        ],
+      };
+    }
+  },
+);
+
 // ---------------------------------------------------------------------------
 // Screenshot
 // ---------------------------------------------------------------------------

src/search.ts

@@ -16,16 +16,14 @@ import type { CupNode, SearchResult } from "./types.js";
 // ---------------------------------------------------------------------------
 
 export const ALL_ROLES: ReadonlySet<string> = new Set([
-  "alert", "alertdialog", "application", "banner", "blockquote", "button",
-  "caption", "cell", "checkbox", "code", "columnheader", "combobox",
-  "complementary", "contentinfo", "deletion", "dialog", "document",
-  "emphasis", "figure", "form", "generic", "grid", "group", "heading",
-  "img", "insertion", "link", "list", "listitem", "log", "main", "marquee",
-  "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio",
-  "navigation", "none", "note", "option", "paragraph", "progressbar",
-  "radio", "region", "row", "rowheader", "scrollbar", "search", "searchbox",
-  "separator", "slider", "spinbutton", "status", "strong", "subscript",
-  "superscript", "switch", "tab", "table", "tablist", "tabpanel", "text",
+  "alert", "alertdialog", "application", "banner", "button", "cell",
+  "checkbox", "columnheader", "combobox", "complementary", "contentinfo",
+  "dialog", "document", "form", "generic", "grid", "group", "heading",
+  "img", "link", "list", "listitem", "log", "main", "marquee", "menu",
+  "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "navigation",
+  "none", "option", "progressbar", "radio", "region", "row", "rowheader",
+  "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton",
+  "status", "switch", "tab", "table", "tablist", "tabpanel", "text",
   "textbox", "timer", "titlebar", "toolbar", "tooltip", "tree", "treeitem",
   "window",
 ]);