Playwright Capture Pipeline

Purpose

The Playwright capture pipeline provides visual capture for the whole Prox OS front-end surface. It starts from global route intelligence instead of asking each app to add one-off screenshot buttons or temporary capture selectors.

This keeps capture responsibility at the root developer-tooling layer:

• the OS Shell owns global routing and composition;
• app packages own their interiors;
• Playwright opens route URLs and shell controls as a user would;
• screenshot PNGs stay outside git.

V1 And V2

V1 could capture every route whose route inventory entry had capture enabled. That proved the route inventory and browser automation path, but a 200+ route blind capture is noisy, expensive, and artifact-heavy for ordinary development.

V2 adds an explicit Full Snapshot Preset. It is a curated, typed plan for the surfaces the project owner wants when they ask for a full visual pass:

• route-level screenshots for known public, Studio, Settings, and app surfaces;
• modal screenshots for New, Switcher, Prox Switchbar, and CMD+K;
• grouped output folders inside one timestamped run directory;
• count mismatches when the real registry differs from expected milestone counts.

Explicit-Only Capture Policy

CodeX and other AI vibe-coding sessions must not run full screenshots by default. Full screenshots are expensive, noisy, and create many local artifacts.

Only run the full preset when the maintainer explicitly asks for a full snapshot or capture preset, for example "run full snapshot" or "capture full snapshot":

pnpm capture:full

Small code changes should default to implementation plus normal validation, not screenshots. capture:changed is also manual-trigger only; use it only when the maintainer explicitly asks for a changed-route capture.

Do not run these commands during ordinary validation unless explicitly asked:

pnpm capture:full
pnpm capture:preset:full
pnpm capture:routes
pnpm capture:changed

Commands

pnpm route:extract
pnpm route:graph
pnpm capture:routes
pnpm capture:changed
pnpm capture:full
pnpm capture:preset:full

route:extract writes the front-route inventory and the generated Shell module. route:graph writes the Mermaid route graph artifact. capture:routes keeps the v1 route-inventory capture path. capture:changed keeps the lightweight affected-route foundation. capture:full and capture:preset:full run the v2 Full Snapshot Preset.

Playwright Placement

Playwright is a root devDependency because capture spans the shell, Studio routes, app manifests, iframe tools, docs-like surfaces, and public routes. It is not a runtime dependency of apps/os-shell, and it is not a shared UI package.

playwright.config.ts targets the OS Shell dev server at http://localhost:3000 by default and can be overridden with PLAYWRIGHT_BASE_URL.

Full Snapshot Output

The v2 full preset writes one timestamped root folder:

.prox-captures/YYYY-MM-DD_HH-mm-ss/

The root contains grouped subfolders and one metadata file:

.prox-captures/YYYY-MM-DD_HH-mm-ss/
  Home/
  Modal/
  New/
  Site Studio/
    Onboarding/
  Desktop Runtime/
    Apps/
  OS Studio/
  Settings/
  External/
  capture-run.json

Every screenshot file keeps the same run timestamp:

YYYY-MM-DD_HH-mm-ss--slug.png

The metadata records preset, timestamps, root folder, base URL, totals, per-group counts, mismatches, results, output files, and errors.

.prox-captures/, artifacts/captures/, playwright-report/, and test-results/ are git ignored because screenshots are local verification outputs, not route intelligence source artifacts.

Full Snapshot Preset

The typed plan lives in tools/capture/full-snapshot-plan.ts.

The current groups are:

• Home
• Modal
• New
• Site Studio
• Site Studio/Onboarding
• Desktop Runtime
• Desktop Runtime/Apps
• OS Studio
• Settings
• External

The preset uses the current route inventory, Site Studio route-card config, Settings tab config, and Introduction App step config. If the real count differs from expected milestone counts such as 14 New routes, 16 Site Studio pages, or 7 onboarding steps, the run records a mismatch instead of inventing routes.

V2 uses the current owner-scoped routes such as /@esmadrider/runtime/os, /@esmadrider/studios/site, and /@esmadrider/studios/atlas. Generic canonical route patterns are /@username/runtime/:runtimeSlug and /@username/studios/:studioSlug.

Modal And Tab Capture

Modal-level capture is intentionally limited to known shell surfaces:

• New opens through the existing New button.
• Switcher opens through the system Switcher shortcut.
• Prox Switchbar is best-effort through managed external link UI and records a skipped result if a stable trigger is unavailable.
• CMD+K Runtime Search and Studio Search open through the command menu shortcut and tab controls.

The runner tries to screenshot the dialog panel. If a future shell surface cannot expose a stable dialog locator, the result should be marked skipped or captured at page level with an explicit note in metadata.

Changed Capture Heuristics

capture:changed currently uses simple rules:

• changed manifest or route-source files capture matching routes;
• changed app package files capture the related route group;
• changed shared shell UI or design tokens capture p0 routes;
• unknown changes fall back to p0 routes.

This remains route-level only and manual-trigger only.

Future Partial Capture Direction

Partial screenshot capture should start from durable semantics, not temporary selectors:

• semantic locator first;
• ARIA snapshot and accessibility tree inspection;
• temporary Playwright-injected highlight overlays;
• stable data-route-section only for long-lived layout landmarks;
• avoid adding many temporary capture IDs into business UI.

Future local capture can combine route inventory, accessibility snapshots, semantic section metadata, and AI-assisted bounding boxes after the explicit full snapshot preset is reliable.