App Screenshots

App Screenshots & Browser Verification

Drives the real app in headless Edge to verify changes end-to-end: screenshots, element adds, screenshot uploads, PNG exports, and pixel-level quality checks.

Prerequisites

• Dev server on http://localhost:9002 — usually already running (npm run dev; EADDRINUSE means reuse it, Next.js hot-reloads your edits).
• A Chromium browser. lib.js finds it per platform (Edge first, then Chrome/Chromium/Brave; C:/Program Files... on Windows, /Applications/... on macOS, /usr/bin/... on Linux) and every script imports EDGE from there. Set APP_BROWSER to override. Headless Edge via puppeteer uses the real GPU (verified: ANGLE D3D11), so WebGL renders match what the user sees. No swiftshader flags needed.
• ffmpeg/ffprobe at C:/ffmpeg-2026-02-04-git-627da1111c-essentials_build/bin/.
• One-time: cd .claude/skills/app-screenshots/scripts && npm install (installs puppeteer-core).

Golden rules (each one cost real debugging time — do not skip)

1. Never use page.screenshot({ clip }). Clipped captures briefly resize the emulated viewport, which trips the responsive sidebar breakpoint and remounts the palette, wiping tab/drill-in state. Always take full-page screenshots and crop afterwards with ffmpeg.
2. Radix tabs ignore synthetic .click() — switch tabs with a real mouse click at the trigger's bounding-box center (page.mouse.click). Plain buttons/tiles are fine with DOM .click() via page.evaluate (also bypasses overlays).
3. waitForFunction needs polling: 500 — the default rAF polling starves on static headless pages. Prefer string-expression predicates ("document.querySelectorAll(...).length > 3") over function+args.
4. After clicking "Start Blank", wait for ?projectId= in the URL before interacting — project creation settles asynchronously.
5. File uploads: start page.waitForFileChooser() before clicking the app's "Upload Screenshot" button, then chooser.accept([path]).
6. Exports: set Browser.setDownloadBehavior (CDP) to a download dir, click the export button, poll the dir until the expected number of .png files appears, then wait ~3s for writes to finish.

App selectors

• Start screen: the blank-canvas card is a button whose text contains Start blank (lowercase b — it reads "Start blank" inside the "Start with a blank canvas" card). The template gallery is still the first thing on screen; an AI agent banner sits above the tabs. lib.js openAgentScreen(page) steps into that agent screen (back out via button[aria-label="Back"]), and clickByTextContains clicks a button by a text fragment.
• Agent screen: its first tab, selected when the screen opens, is Claude Code ([role="tab"] with that text and the orange logo). On desktop it holds a detection card ("Claude Code 2.1.202 is ready", or a not installed or not signed in card with Check again), a model picker and Start with Claude Code; on the web it says Claude Code runs in the desktop app and has no Start button. The plan modes come after it (Free, use my account, the desktop-only Free, built in, Use my API key), so a script that drives one of them has to click its tab first, with a real mouse click (rule 2). Step 1 holds, on every tab, the code folder row Your app's code (Claude Code only) with button[aria-label="Add your app's code folder"] and its chips (hidden in the Mac App Store build). A folder alone can start a Claude Code run. On the web that button toggles an alert titled Code folders need the desktop app; scope any locator to that alert, because the Claude Code tab has its own Get the desktop app button.
• Tabs: [role="tab"] containing Elements / Devices / Images / Previews. Previews holds whole App Preview boards (see src/lib/previewScenes.ts); its tiles read Add the <Scene Name> preview board (scene:<id>) and each one adds an ARTBOARD, not an element, so count [data-artboard-dom-id] rather than [data-element-id] to detect the add. To review the scenes themselves, do NOT drive the canvas: headless Edge returns torn frames after scrolling the board row. Bundle StaticArtboard + previewScenes.ts with esbuild (same recipe as regen-3d-thumbs.js), serve the harness from public/ so the posters resolve, and screenshot the mount node per scene. There is NO Layers tab anymore: Properties (top) and Layers (bottom) live in one right dock with a draggable divider ([role="separator"]) between them. Collapse the dock via button[aria-label="Collapse right panel"]; collapsed it becomes a slim vertical rail — expand via button[aria-label="Expand right panel"] or the rotated Open Properties / Open Layers buttons (by title). Dock state persists in localStorage (abs-right-dock-open, abs-right-dock-layers-height, abs-right-dock-width), so reset those keys if a test needs the default layout. The dock's left edge is [role="separator"][aria-orientation="vertical"] (aria-label="Resize right panel"): drag it left to widen the dock from 320px up to 720px, double-click to reset.
• Agent dock tab (desktop only): the dock gains an Agent tab, first in the strip, once a first Start with Claude Code turns it on, and the Layers list steps aside while it is active. The panel root carries data-agent-panel. The input is textarea[aria-label="Message the agent"] (Enter sends, Shift+Enter is a new line), next to button[aria-label="Send"], which becomes button[title="Stop the agent"] while a turn runs, button[aria-label="Attach screenshots"], button[aria-label="Add your app's code folder"] (aria-busy while the native folder dialog is open; CDP cannot answer that dialog, so a debug build started with OSG_CLAUDE_TEST_FOLDER=<path> grants that folder instead), the chip list [aria-label="Folders Claude Code can read"] with one button[aria-label="Remove the <name> folder"] per folder, button[aria-label="Past chats"] (toggles the list of saved chats in place of the transcript, aria-pressed while open; a row is a button named by the chat's first message), button[aria-label="Start a new chat"] and button[aria-label="Agent options"] (model, Recent runs, Check Claude Code again). Collapsed, the rail button is title="Open Agent"; on a phone it is aria-label="Open agent chat". localStorage keys: osg-claude-agent-v1 (the chat, its code folders included), osg-claude-agent-panel (1 keeps the tab) and osg-claude-agent-model. Remove all three for a clean start. Past chats live in the agentChats IndexedDB table, and opening another project swaps the panel to that project's latest chat (or an empty one).
• Palette categories: button[title="Browse <Category>"] (e.g. Browse 3D iPhone 17 Pro Max, Browse Colored iPhone, Browse Basic); close with the Back button.
• Tiles: button[aria-label="Add <label> (<libraryId>)"] — they carry no title (a Radix hover card shows the label + library id instead), so match on the accessible name. lib.js clickByTitle handles both: pass Add Transparent device and it matches the (devicecolor:iphone-transparent) suffix for you. button[aria-label^="Add "] selects every tile in the open group.
• Elements tab search: input[aria-label="Search elements by name or id"] filters the whole Elements tab (Basic, App Preview and the vector library) by name, library id, group or keyword; button[aria-label="Clear search"] restores the category overview. Results replace the category grid, so type into it instead of opening a category.
• Toolbar by title attr: New Artboard (new artboard becomes active), Zoom In, Zoom Out.
• Import and Export are dropdown menus, button[title="Open a project"] and button[title="Export"]. Their items are [role="menuitem"]: From a project file / From your account, and Project file plus the render item, whose label depends on the project: Artboards as images for screenshot projects, App preview video for App Preview ones (match on either, or on the .mp4 suffix). Radix opens them on pointerdown, so a DOM .click() does nothing: use lib.js clickMenuItem(page, 'Export', 'Artboards as images'), which mouse-clicks the trigger and then the item in the portal.
• Canvas elements: [data-element-id] (count them to detect adds).
• Export dialog: the Export menu's Artboards as images opens the "Export Screenshots" dialog (it no longer downloads directly). Checkboxes by id: #export-as-is (checked by default), #gen-ios, #gen-ipad-pro-13, #gen-ipad-11 (App Store sizes to generate; disabled when the current canvas already covers that format). Confirm with the dialog button whose text is Export. lib.js exportArtboards handles all of this and takes an optional extraFormats array of those ids.
• App Preview video projects get a DIFFERENT dialog ("Export App Preview Video", radio ids #apv-styled / #apv-raw, buttons Export Styled Video / Export Store-Ready Recording, plus Export PNG stills instead for the still path). Any project holding a recording mockup (video-device), a video/gesture element or an animation routes here — there are no App Store screenshot-size options. lib.js exportArtboards detects which dialog opened and takes the PNG path in both, so preview generation still works for the pv-* templates.
• Exported files are named <NN>_<Artboard_Name>[_<Device_Format>].png with spaces → underscores; NN is the zero-padded canvas order and the device-format suffix (iPhone/Android/iPad_13-inch/iPad_11-inch/7-inch_tablet/10-inch_tablet) appears when the artboard's mockups resolve to one format (e.g. 01_Blank_Artboard.png, 01_Blank_Artboard_iPhone.png). Generated App Store formats download extra files per artboard (e.g. 01_Blank_Artboard_iPad_13-inch.png at exactly 2064×2752).