Add vocabulary short codes, simplify detail levels to compact/full

Add ROLE_CODES, STATE_CODES, ACTION_CODES maps for compact output.
Remove "minimal" detail level — consolidate to "compact" (default) and
"full". Only emit bounds for interactable nodes. Update docs, MCP
server defaults, and tests to match.

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

Author: k4cper-g

README.md

@@ -51,13 +51,13 @@ Output:
 # app: Spotify
 # 63 nodes (280 before pruning)
 
-[e0] window "Spotify" @120,40 1680x1020
-    [e1] document "Spotify" @120,40 1680x1020
-        [e2] button "Back" @132,52 32x32 [click]
-        [e3] button "Forward" @170,52 32x32 {disabled} [click]
-        [e7] navigation "Main" @120,88 240x972
-            [e8] link "Home" @132,100 216x40 {selected} [click]
-            [e9] link "Search" @132,148 216x40 [click]
+[e0] win "Spotify" 120,40 1680x1020
+  [e1] doc "Spotify" 120,40 1680x1020
+    [e2] btn "Back" 132,52 32x32 [clk]
+    [e3] btn "Forward" 170,52 32x32 {dis} [clk]
+    [e7] nav "Main" 120,88 240x972
+      [e8] lnk "Home" 132,100 216x40 {sel} [clk]
+      [e9] lnk "Search" 132,148 216x40 [clk]
 ```
 
 ### Session API

docs/api-reference.md

@@ -25,7 +25,7 @@ const result = await session.snapshot({
     app: undefined,        // filter by window title (scope="full" only)
     maxDepth: 999,         // maximum tree depth
     compact: true,         // true → compact text, false → CUP envelope object
-    detail: "standard",    // "standard" | "minimal" | "full"
+    detail: "compact",     // "compact" | "full"
 });
 ```
 
@@ -44,8 +44,7 @@ const result = await session.snapshot({
 
 | Level | Behavior |
 |-------|----------|
-| `standard` | Prunes unnamed generics, empty text, decorative images (~75% smaller) |
-| `minimal` | Keep only interactive nodes and their ancestors |
+| `compact` | Prunes unnamed generics, empty text, decorative images (~75% smaller) |
 | `full` | No pruning — every node included |
 
 ---
@@ -266,14 +265,14 @@ The text format returned by `session.snapshot({ compact: true })`. Optimized for
 # app: Discord
 # 87 nodes (353 before pruning)
 
-[e0] window "Discord" @509,62 1992x1274
-    [e1] document "General" @509,62 1992x1274 {readonly}
-        [e2] button "Back" @518,66 26x24 [click]
-        [e7] tree "Servers" @509,94 72x1242
-            [e8] treeitem "Lechownia" @513,190 64x48 {selected} [click,select]
+[e0] win "Discord" 509,62 1992x1274
+  [e1] doc "General" 509,62 1992x1274 {ro}
+    [e2] btn "Back" 518,66 26x24 [clk]
+    [e7] tre "Servers" 509,94 72x1242
+      [e8] ti "Lechownia" 513,190 64x48 {sel} [clk,sel]
 ```
 
-Line format: `[id] role "name" @x,y wxh {states} [actions] val="value" (attrs)`
+Line format: `[id] role "name" x,y wxh {states} [actions] val="value" (attrs)`
 
 Full spec: [compact.md](https://github.com/computeruseprotocol/computer-use-protocol/blob/main/schema/compact.md)
 

src/format.ts

@@ -283,48 +283,18 @@ function pruneNode(
   return [pruned];
 }
 
-function pruneMinimalNode(node: CupNode): CupNode | null {
-  const children = node.children ?? [];
-  const keptChildren: CupNode[] = [];
-
-  for (const child of children) {
-    const pruned = pruneMinimalNode(child);
-    if (pruned) keptChildren.push(pruned);
-  }
-
-  if (hasMeaningfulActions(node) || keptChildren.length > 0) {
-    const pruned: CupNode = { ...node };
-    delete pruned.children;
-    if (keptChildren.length > 0) {
-      pruned.children = keptChildren;
-    }
-    return pruned;
-  }
-
-  return null;
-}
-
 export function pruneTree(
   tree: CupNode[],
   options?: { detail?: Detail; screen?: { w: number; h: number } | null },
 ): CupNode[] {
-  const detail = options?.detail ?? "standard";
+  const detail = options?.detail ?? "compact";
   const screen = options?.screen;
 
   if (detail === "full") {
     return structuredClone(tree);
   }
 
-  if (detail === "minimal") {
-    const result: CupNode[] = [];
-    for (const root of tree) {
-      const pruned = pruneMinimalNode(root);
-      if (pruned) result.push(pruned);
-    }
-    return result;
-  }
-
-  // "standard"
+  // "compact"
   let screenViewport: Rect | null = null;
   if (screen) {
     screenViewport = { x: 0, y: 0, w: screen.w, h: screen.h };
@@ -342,8 +312,113 @@ export function pruneTree(
 
 const VALUE_ROLES = new Set(["textbox", "searchbox", "combobox", "spinbutton", "slider"]);
 
+// ---------------------------------------------------------------------------
+// Vocabulary short codes — compact aliases for roles, states, and actions.
+// These reduce per-node token cost by ~50% on role/state/action strings.
+// ---------------------------------------------------------------------------
+
+export const ROLE_CODES: Record<string, string> = {
+  alert: "alrt",
+  alertdialog: "adlg",
+  application: "app",
+  banner: "bnr",
+  button: "btn",
+  cell: "cel",
+  checkbox: "chk",
+  columnheader: "colh",
+  combobox: "cmb",
+  complementary: "cmp",
+  contentinfo: "ci",
+  dialog: "dlg",
+  document: "doc",
+  form: "frm",
+  generic: "gen",
+  grid: "grd",
+  group: "grp",
+  heading: "hdg",
+  img: "img",
+  link: "lnk",
+  list: "lst",
+  listitem: "li",
+  log: "log",
+  main: "main",
+  marquee: "mrq",
+  menu: "mnu",
+  menubar: "mnub",
+  menuitem: "mi",
+  menuitemcheckbox: "mic",
+  menuitemradio: "mir",
+  navigation: "nav",
+  none: "none",
+  option: "opt",
+  progressbar: "pbar",
+  radio: "rad",
+  region: "rgn",
+  row: "row",
+  rowheader: "rowh",
+  scrollbar: "sb",
+  search: "srch",
+  searchbox: "sbx",
+  separator: "sep",
+  slider: "sld",
+  spinbutton: "spn",
+  status: "sts",
+  switch: "sw",
+  tab: "tab",
+  table: "tbl",
+  tablist: "tabs",
+  tabpanel: "tpnl",
+  text: "txt",
+  textbox: "tbx",
+  timer: "tmr",
+  titlebar: "ttlb",
+  toolbar: "tlbr",
+  tooltip: "ttp",
+  tree: "tre",
+  treeitem: "ti",
+  window: "win",
+};
+
+export const STATE_CODES: Record<string, string> = {
+  busy: "bsy",
+  checked: "chk",
+  collapsed: "col",
+  disabled: "dis",
+  editable: "edt",
+  expanded: "exp",
+  focused: "foc",
+  hidden: "hid",
+  mixed: "mix",
+  modal: "mod",
+  multiselectable: "msel",
+  offscreen: "off",
+  pressed: "prs",
+  readonly: "ro",
+  required: "req",
+  selected: "sel",
+};
+
+export const ACTION_CODES: Record<string, string> = {
+  click: "clk",
+  collapse: "col",
+  decrement: "dec",
+  dismiss: "dsm",
+  doubleclick: "dbl",
+  expand: "exp",
+  focus: "foc",
+  increment: "inc",
+  longpress: "lp",
+  rightclick: "rclk",
+  scroll: "scr",
+  select: "sel",
+  setvalue: "sv",
+  toggle: "tog",
+  type: "typ",
+};
+
 export function formatLine(node: CupNode): string {
-  const parts = [`[${node.id}]`, node.role];
+  const role = node.role;
+  const parts = [`[${node.id}]`, ROLE_CODES[role] ?? role];
 
   const name = node.name || "";
   if (name) {
@@ -352,25 +427,29 @@ export function formatLine(node: CupNode): string {
     parts.push(`"${truncated}"`);
   }
 
+  // Actions (drop "focus" — it's noise)
+  const actions = (node.actions ?? []).filter((a) => a !== "focus");
+
+  // Only include bounds for interactable nodes (nodes with meaningful actions).
+  // Non-interactable nodes are context-only — agents reference them by ID, not
+  // by coordinates, so spatial info adds tokens without value.
   const bounds = node.bounds;
-  if (bounds) {
-    parts.push(`@${bounds.x},${bounds.y} ${bounds.w}x${bounds.h}`);
+  if (bounds && actions.length > 0) {
+    parts.push(`${bounds.x},${bounds.y} ${bounds.w}x${bounds.h}`);
   }
 
   const states = node.states ?? [];
   if (states.length > 0) {
-    parts.push("{" + states.join(",") + "}");
+    parts.push("{" + states.map((s) => STATE_CODES[s] ?? s).join(",") + "}");
   }
 
-  // Actions (drop "focus" — it's noise)
-  const actions = (node.actions ?? []).filter((a) => a !== "focus");
   if (actions.length > 0) {
-    parts.push("[" + actions.join(",") + "]");
+    parts.push("[" + actions.map((a) => ACTION_CODES[a] ?? a).join(",") + "]");
   }
 
   // Value for input-type elements
   const value = node.value || "";
-  if (value && VALUE_ROLES.has(node.role)) {
+  if (value && VALUE_ROLES.has(role)) {
     let truncatedVal = value.length > 120 ? value.slice(0, 120) + "..." : value;
     truncatedVal = truncatedVal.replace(/"/g, '\\"').replace(/\n/g, " ");
     parts.push(`val="${truncatedVal}"`);
@@ -436,7 +515,7 @@ export function serializeCompact(
     maxChars?: number;
   },
 ): string {
-  const detail = options?.detail ?? "standard";
+  const detail = options?.detail ?? "compact";
   const maxChars = options?.maxChars ?? MAX_OUTPUT_CHARS;
   const windowList = options?.windowList ?? null;
 

src/index.ts

@@ -77,7 +77,7 @@ export class Session {
     const scope = options?.scope ?? "foreground";
     const maxDepth = options?.maxDepth ?? 999;
     const compact = options?.compact ?? true;
-    const detail = options?.detail ?? "standard";
+    const detail = options?.detail ?? "compact";
 
     const [sw, sh, scale] = await this.adapter.getScreenInfo();
 
@@ -442,7 +442,7 @@ export async function overview(): Promise<string> {
 // ---------------------------------------------------------------------------
 
 export { getAdapter, detectPlatform } from "./router.js";
-export { buildEnvelope, serializeCompact, serializeOverview, pruneTree, formatLine } from "./format.js";
+export { buildEnvelope, serializeCompact, serializeOverview, pruneTree, formatLine, ROLE_CODES, STATE_CODES, ACTION_CODES } from "./format.js";
 export { searchTree, resolveRoles, tokenize } from "./search.js";
 export { ActionExecutor, VALID_ACTIONS } from "./actions/executor.js";
 export { parseCombo } from "./actions/keys.js";

src/mcp/server.ts

@@ -84,7 +84,7 @@ After executing any action, you MUST call this again for fresh IDs.`,
       scope: "foreground",
       maxDepth: 999,
       compact: true,
-      detail: "standard",
+      detail: "compact",
     });
     return { content: [{ type: "text", text: result as string }] };
   },
@@ -109,7 +109,7 @@ Element IDs are ephemeral — only valid for THIS snapshot.`,
       app,
       maxDepth: 999,
       compact: true,
-      detail: "standard",
+      detail: "compact",
     });
     return { content: [{ type: "text", text: result as string }] };
   },
@@ -130,7 +130,7 @@ Element IDs are ephemeral — only valid for THIS snapshot.`,
       scope: "desktop",
       maxDepth: 999,
       compact: true,
-      detail: "standard",
+      detail: "compact",
     });
     return { content: [{ type: "text", text: result as string }] };
   },

src/types.ts

@@ -300,7 +300,7 @@ export interface CupEnvelope {
 
 export type Scope = "overview" | "foreground" | "desktop" | "full";
 
-export type Detail = "standard" | "minimal" | "full";
+export type Detail = "compact" | "full";
 
 // ---------------------------------------------------------------------------
 // Window metadata (internal, from adapters)