app-screenshot-debug

name

app-screenshot-debug

description

Drive the running termio app via AppleScript / System Events to reach a UI state (focus the window, click a sidebar project, a terminal pane, a control), capture a pixel-accurate screenshot of just that window, and read it back for visual analysis — for diagnosing layout / spacing / alignment / 'this looks ugly' issues that can't be judged from code alone. Invoke when the user says 'screenshot the app', 'take a screenshot', 'show me what it looks like', 'what does X look like', 'debug this visually', 'verify the UI change', '截图看看', '看看长什么样', '帮我截个图分析'. Pairs with `macos-rebuild-dev` — rebuild first if code changed, then capture.

Screenshot-driven UI debugging (AppleScript + screencapture)

The loop for seeing a termio UI change instead of guessing from code:

(rebuild if code changed)  →  drive app into the target state  →  capture the window  →  Read the PNG  →  judge / iterate

You cannot evaluate spacing, alignment, overlap, ghosting, or "this looks ugly" from source. Get a real screenshot, Read it, then decide.

Prerequisites

• The app must be running and built. If you just changed code, run the macos-rebuild-dev skill first. The process name for System Events is termio and the main window's title is termio.
• These calls need macOS Accessibility + Screen Recording permission for the terminal / Claude Code host. If System Events errors with -25211 or the capture is black, that permission is missing — tell the user to grant it in System Settings → Privacy & Security.
• termio is a single-window app (sidebar + terminal panes); there is no Settings window. Everything you need is in window 1.

The two helper scripts (in scripts/)

Run them with bash; they take the app name from $TERMIO_APP_NAME (default termio).

1. capture-window.sh [out.png] — screenshot just the frontmost termio window (-o no shadow, -x silent), reading its live bounds first. Prints the window origin + size. Captures the region 1:1 in points, so a point you read off the resulting image is window-relative: image (dx,dy) == screen (originX+dx, originY+dy).

2. click-in-window.sh <dx> <dy> — click at a window-relative point: it re-reads the live window origin and adds your offset. Use the exact (dx,dy) you measured on a capture-window.sh image — this survives the window moving or reopening on a different display.

Canonical recipe

SK=skills/app-screenshot-debug/scripts

osascript -e 'tell application "System Events" to tell process "termio" to set frontmost to true'
bash $SK/capture-window.sh /tmp/shot.png
# → Read /tmp/shot.png with the Read tool, find the control you want at (dx,dy)
bash $SK/click-in-window.sh 120 180   # e.g. click a sidebar project row
bash $SK/capture-window.sh /tmp/shot2.png   # Read again to see the result

Then Read each PNG to analyze. Capture before and after a change for an honest before/after.

Driving the UI — patterns that actually work

• Focus the window: tell application "System Events" to tell process "termio" to set frontmost to true (or tell application "termio" to activate).
• Click a control: prefer click-in-window.sh with coords read off the screenshot. click at {x,y} (global points) conveniently returns the AX element path it hit — use that to confirm you hit the right thing.
• Get window bounds live: get position of window 1 / get size of window 1.
• Type into the focused terminal: keystroke "ls\n" after the window is frontmost — useful to put the terminal surface into a known state before capturing.

Gotchas (learned the hard way)

• Never hardcode window coordinates across calls. The window can reopen at a different origin or on another display. Always re-read bounds (the scripts do) — that's the whole reason click-in-window.sh exists.
• screencapture -R x,y,w,h uses the same global point coords as System Events, mapping points→pixels 1:1 for the width you ask for, so window-relative math is trivial: dx = screenX - originX.
• Always -o (no shadow) and -x (silent) so the crop is exact and there's no shutter sound.
• Add a sleep (~0.8–1.2s) after navigation/clicks before capturing so the animation settles — otherwise you screenshot a mid-transition frame.
• The terminal surface is a libghostty-rendered view, mostly opaque to AX — drive it by focusing + keystrokes, and judge it from the screenshot, not the AX tree.
• Save shots under /tmp/<task>/…png and Read them; don't leave them in the repo.