Project Structure

This guide covers the internal layout of the peek codebase and how the modules fit together.

Directory Layout

peek/
├── src/
│   ├── cli.ts              # CLI entry point (Commander-based)
│   ├── snap.ts             # Core screenshot orchestration
│   ├── browser.ts          # Chrome detection and launch
│   ├── pool.ts             # Browser pooling (persistent Chrome)
│   ├── native.ts           # macOS native window capture
│   ├── runner.ts           # Check orchestration
│   ├── reporter.ts         # Output formatting (text, json, junit)
│   ├── scene.ts            # Scene checks for game engines
│   ├── types.ts            # TypeScript type definitions
│   ├── index.ts            # Programmatic API exports
│   ├── checks/
│   │   ├── index.ts        # Check registry
│   │   ├── overflow.ts     # Horizontal overflow detection
│   │   ├── clickability.ts # Covered interactive elements
│   │   ├── touch-targets.ts# Touch target size and spacing
│   │   ├── text-overflow.ts# Clipped or overflowing text
│   │   ├── visibility.ts   # Invisible interactive elements
│   │   └── viewport-meta.ts# Viewport meta tag validation
│   └── frameworks/
│       ├── index.ts        # Framework API (start server, hydration)
│       ├── detector.ts     # Auto-detect project framework
│       ├── next.ts         # Next.js integration
│       ├── sveltekit.ts    # SvelteKit integration
│       └── vite.ts         # Vite/CRA/Remix/Astro/Nuxt integration
├── dist/                   # Compiled output
├── build.ts                # Build script (dev, prod, compile, types)
├── package.json
└── tsconfig.json

Key Modules

cli.ts

The CLI entry point. Uses Commander to define the snap, check, dev, scene, pool, and clean commands. Each command parses its flags and delegates to the appropriate module.

snap.ts

Orchestrates web screenshots. Acquires a browser from the pool (or launches a fresh one with --no-pool), navigates to the URL, takes the screenshot, and optionally runs layout checks on the same page.

browser.ts

Handles Chrome executable detection with a 3-tier strategy: system Chrome via chrome-launcher, cached Chromium in ~/.cache/peek/, or auto-download on first use. Also provides the launchBrowser() function for non-pooled usage.

pool.ts

Manages a persistent browser pool. Launches Chrome as a detached process and stores its WebSocket endpoint in ~/.peek/pool.json. Subsequent invocations connect via puppeteer.connect(). Includes file-based locking for safe concurrent access and a 5-minute idle timeout.

native.ts

macOS native window capture. Compiles a Swift helper using ScreenCaptureKit on first use (cached at ~/.cache/peek/peek-capture). The helper lists on-screen windows and captures them by window ID.

runner.ts

The check orchestration engine. Takes a Puppeteer Page, runs all enabled checks (or a filtered subset), collects issues, and applies severity overrides from config.

reporter.ts

Formats check results in three output modes: human-readable text with colored output, structured JSON, or JUnit XML for CI integration.

scene.ts

Scene adapter for game engines (Bevy, Unity). Reads a SceneManifest JSON and runs spatial checks on entities (overlap, bounds, size, visibility) without needing a browser.

checks/

Six layout checks, each implementing the Check interface with a name, description, and run(ctx) method. All checks respect the global ignore selector list and the data-peek-ignore attribute.

frameworks/

Framework detection and dev server management. Auto-detects Next.js, SvelteKit, Vite, Create React App, Remix, Astro, and Nuxt from package.json. Handles hydration waiting with framework-specific strategies.

File Paths Used at Runtime

Build System

peek uses a custom build.ts script with several modes:

bun build.ts dev           # Development build (tsc)
bun build.ts prod          # Production build (minified, Bun bundler)
bun build.ts compile       # Standalone binary for current platform
bun build.ts compile:all   # Binaries for all platforms
bun build.ts types         # TypeScript declaration files
bun build.ts clean         # Remove dist/