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

Add ROLE_CODES, STATE_CODES, ACTION_CODES dicts 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

@@ -59,13 +59,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]
 ```
 
 ## CLI

cup/__init__.py

@@ -142,7 +142,7 @@ def snapshot(
         app: str | None = None,
         max_depth: int = 999,
         compact: bool = True,
-        detail: Detail = "standard",
+        detail: Detail = "compact",
     ) -> str | dict:
         """Capture the accessibility tree.
 
@@ -156,7 +156,7 @@ def snapshot(
             max_depth: Maximum tree depth.
             compact: If True, return compact LLM text; if False, return
                      the full CUP envelope dict.
-            detail: Pruning level ("standard", "minimal", or "full").
+            detail: Pruning level ("compact" or "full").
 
         Returns:
             Compact text string or CUP envelope dict.

cup/format.py

@@ -10,7 +10,7 @@
 import time
 from typing import Literal
 
-Detail = Literal["standard", "minimal", "full"]
+Detail = Literal["compact", "full"]
 
 
 # ---------------------------------------------------------------------------
@@ -122,6 +122,110 @@ def _count_nodes(nodes: list[dict]) -> int:
 
 _CHROME_ROLES = frozenset({"scrollbar", "separator", "titlebar", "tooltip", "status"})
 
+# ---------------------------------------------------------------------------
+# Vocabulary short codes — compact aliases for roles, states, and actions.
+# These reduce per-node token cost by ~50% on role/state/action strings.
+# ---------------------------------------------------------------------------
+
+ROLE_CODES: dict[str, str] = {
+    "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",
+}
+
+STATE_CODES: dict[str, str] = {
+    "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",
+}
+
+ACTION_CODES: dict[str, str] = {
+    "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",
+}
+
 
 def _should_skip(node: dict, parent: dict | None, siblings: int) -> bool:
     """Decide if a node should be pruned (entire subtree is dropped)."""
@@ -346,64 +450,28 @@ def _has_meaningful_actions(node: dict) -> bool:
     return any(a != "focus" for a in actions)
 
 
-def _prune_minimal_node(node: dict) -> dict | None:
-    """Minimal pruning: keep only nodes with meaningful actions + ancestors.
-
-    Returns a pruned copy of the node if it or any descendant has meaningful
-    actions, or None if the entire subtree can be dropped.
-    """
-    children = node.get("children", [])
-
-    # Recursively prune children first
-    kept_children = []
-    for child in children:
-        pruned_child = _prune_minimal_node(child)
-        if pruned_child is not None:
-            kept_children.append(pruned_child)
-
-    # Keep this node if it has meaningful actions OR if any child was kept
-    if _has_meaningful_actions(node) or kept_children:
-        pruned = {k: v for k, v in node.items() if k != "children"}
-        if kept_children:
-            pruned["children"] = kept_children
-        return pruned
-
-    return None
-
-
 def prune_tree(
     tree: list[dict],
     *,
-    detail: Detail = "standard",
+    detail: Detail = "compact",
     screen: dict | None = None,
 ) -> list[dict]:
     """Apply pruning to a CUP tree, returning a new pruned tree.
 
     Args:
         tree: List of root CUP node dicts.
         detail: Pruning level:
-            "standard" — Remove unnamed generics, decorative images, empty
-                         text, offscreen noise, etc. (default)
-            "minimal"  — Keep only nodes with meaningful actions (not just
-                         focus) and their ancestors. Dramatically reduces
-                         token count.
-            "full"     — No pruning; return every node from the raw tree.
+            "compact" — Remove unnamed generics, decorative images, empty
+                        text, offscreen noise, etc. (default)
+            "full"    — No pruning; return every node from the raw tree.
         screen: Screen dimensions dict with "w" and "h" keys. When provided,
                 elements entirely outside the screen bounds are clipped even
                 if no scrollable ancestor is present.
     """
     if detail == "full":
         return copy.deepcopy(tree)
 
-    if detail == "minimal":
-        result = []
-        for root in tree:
-            pruned = _prune_minimal_node(root)
-            if pruned is not None:
-                result.append(pruned)
-        return result
-
-    # "standard" — use screen as baseline viewport so elements far offscreen
+    # "compact" — use screen as baseline viewport so elements far offscreen
     # (e.g. in web-based apps with virtual scroll) are clipped even when no
     # ancestor exposes the "scroll" action.
     screen_viewport = None
@@ -417,7 +485,8 @@ def prune_tree(
 
 def _format_line(node: dict) -> str:
     """Format a single CUP node as a compact one-liner."""
-    parts = [f"[{node['id']}]", node["role"]]
+    role = node["role"]
+    parts = [f"[{node['id']}]", ROLE_CODES.get(role, role)]
 
     name = node.get("name", "")
     if name:
@@ -426,22 +495,26 @@ def _format_line(node: dict) -> str:
         truncated = truncated.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ")
         parts.append(f'"{truncated}"')
 
+    # Actions (drop "focus" -- it's noise)
+    actions = [a for a in node.get("actions", []) if 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.
     bounds = node.get("bounds")
-    if bounds:
-        parts.append(f"@{bounds['x']},{bounds['y']} {bounds['w']}x{bounds['h']}")
+    if bounds and actions:
+        parts.append(f"{bounds['x']},{bounds['y']} {bounds['w']}x{bounds['h']}")
 
     states = node.get("states", [])
     if states:
-        parts.append("{" + ",".join(states) + "}")
+        parts.append("{" + ",".join(STATE_CODES.get(s, s) for s in states) + "}")
 
-    # Actions (drop "focus" -- it's noise)
-    actions = [a for a in node.get("actions", []) if a != "focus"]
     if actions:
-        parts.append("[" + ",".join(actions) + "]")
+        parts.append("[" + ",".join(ACTION_CODES.get(a, a) for a in actions) + "]")
 
     # Value for input-type elements
     value = node.get("value", "")
-    if value and node["role"] in ("textbox", "searchbox", "combobox", "spinbutton", "slider"):
+    if value and role in ("textbox", "searchbox", "combobox", "spinbutton", "slider"):
         truncated_val = value[:120] + ("..." if len(value) > 120 else "")
         truncated_val = truncated_val.replace('"', '\\"').replace("\n", " ")
         parts.append(f'val="{truncated_val}"')
@@ -513,7 +586,7 @@ def serialize_compact(
     envelope: dict,
     *,
     window_list: list[dict] | None = None,
-    detail: Detail = "standard",
+    detail: Detail = "compact",
     max_chars: int = MAX_OUTPUT_CHARS,
 ) -> str:
     """Serialize a CUP envelope to compact LLM-friendly text.
@@ -526,7 +599,7 @@ def serialize_compact(
         envelope: CUP envelope dict with tree data.
         window_list: Optional list of open windows to include in header
                      for situational awareness (used by foreground scope).
-        detail: Pruning level ("standard", "minimal", or "full").
+        detail: Pruning level ("compact" or "full").
         max_chars: Hard character limit for output. When exceeded, the
                    output is truncated with a diagnostic message.
     """

cup/mcp/server.py

@@ -86,7 +86,7 @@ def snapshot() -> str:
         scope="foreground",
         max_depth=999,
         compact=True,
-        detail="standard",
+        detail="compact",
     )
 
 
@@ -114,7 +114,7 @@ def snapshot_app(app: str) -> str:
         app=app,
         max_depth=999,
         compact=True,
-        detail="standard",
+        detail="compact",
     )
 
 
@@ -134,7 +134,7 @@ def snapshot_desktop() -> str:
         scope="desktop",
         max_depth=999,
         compact=True,
-        detail="standard",
+        detail="compact",
     )
 
 

docs/api-reference.md

@@ -25,7 +25,7 @@ result = session.snapshot(
     app=None,             # filter by window title (scope="full" only)
     max_depth=999,        # maximum tree depth
     compact=True,         # True → compact text, False → CUP envelope dict
-    detail="standard",    # "standard" | "minimal" | "full"
+    detail="compact",     # "compact" | "full"
 )
 ```
 
@@ -44,8 +44,7 @@ result = 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 |
 
 ---
@@ -274,14 +273,14 @@ The text format returned by `session.snapshot(compact=True)`. Optimized for LLM
 # 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/computeruseprotocol/blob/main/schema/compact.md)