@cydoentis/pawprint 1.0.0

package/README.md

@@ -0,0 +1,332 @@
+# Pawprint
+
+Automated screenshot generation for web applications across themes, color palettes, and viewport sizes.
+
+Pawprint uses Playwright to capture screenshots of your app in every combination of route, mode (light/dark), palette, and viewport you configure. It handles SPA authentication, organizes output into timestamped folders, and generates metadata for each run.
+
+## Installation
+
+```bash
+npm install
+npx playwright install chromium
+npm run build
+```
+
+To make the `pawprint` command available globally:
+
+```bash
+npm link
+```
+
+## Quick Start
+
+```bash
+# 1. Generate a config file in your app directory
+pawprint init /path/to/your-app
+
+# 2. Edit the generated pawprint.config.json with your app's details
+
+# 3. Start your app, then generate screenshots
+pawprint generate /path/to/your-app
+```
+
+## CLI Commands
+
+### `pawprint generate <app-path>`
+
+Takes screenshots across all configured theme/palette/viewport combinations.
+
+```bash
+pawprint generate /path/to/app
+pawprint generate /path/to/app --config ./custom-config.json
+pawprint generate /path/to/app --output ./my-screenshots
+pawprint generate /path/to/app --debug
+```
+
+| Option | Description |
+|---|---|
+| `-c, --config <path>` | Custom config file path (default: `<app-path>/pawprint.config.json`) |
+| `-o, --output <dir>` | Override output directory |
+| `--debug` | Enable debug mode with extra error output |
+
+### `pawprint init [app-path]`
+
+Creates a sample `pawprint.config.json` at the given path (defaults to `.`).
+
+```bash
+pawprint init
+pawprint init /path/to/app
+pawprint init . --force   # overwrite existing config
+```
+
+### `pawprint list <app-path>`
+
+Lists previous screenshot runs organized by date.
+
+```bash
+pawprint list /path/to/app
+pawprint list /path/to/app --output ./my-screenshots
+```
+
+## Configuration
+
+Create a `pawprint.config.json` in your app directory or pass a custom path with `--config`.
+
+### Full Example
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "routes": ["/", "/dashboard", "/settings", "/profile"],
+  "modes": ["light", "dark"],
+  "palettes": ["default", "high-contrast"],
+  "viewports": [
+    { "name": "desktop", "width": 1440, "height": 900 },
+    { "name": "mobile", "width": 390, "height": 844 },
+    { "name": "tablet", "width": 768, "height": 1024 }
+  ],
+  "appearance": {
+    "strategy": "localStorage",
+    "modeKey": "theme",
+    "paletteKey": "palette"
+  },
+  "outputDir": "pawprint-output",
+  "auth": {
+    "strategy": "form",
+    "loginUrl": "/login",
+    "credentials": {
+      "username": "admin@example.com",
+      "password": "password123"
+    },
+    "selectors": {
+      "username": "input[type=email]",
+      "password": "input[type=password]",
+      "submit": "button[type=submit]"
+    }
+  },
+  "screenshotOptions": {
+    "fullPage": false,
+    "waitForTimeout": 500,
+    "waitUntil": "networkidle"
+  }
+}
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `baseUrl` | `string` | Base URL of the running app (e.g. `http://localhost:3000`) |
+| `routes` | `string[]` | Routes to screenshot (e.g. `["/", "/dashboard"]`) |
+| `modes` | `string[]` | Theme modes (e.g. `["light", "dark"]`) |
+| `appearance` | `object` | How themes are applied to the app |
+
+### Optional Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `palettes` | `string[]` | `["default"]` | Color palette names |
+| `viewports` | `ViewportPreset[]` | `[{name:"default", width:1440, height:900}]` | Viewport sizes |
+| `outputDir` | `string` | `"pawprint-output"` | Root output directory |
+| `auth` | `AuthStrategy` | `undefined` | Authentication config |
+| `screenshotOptions` | `object` | see below | Screenshot capture settings |
+
+### Appearance Strategies
+
+**localStorage** -- For apps that store theme preferences in localStorage:
+
+```json
+{
+  "strategy": "localStorage",
+  "modeKey": "theme",
+  "paletteKey": "palette"
+}
+```
+
+Pawprint sets the localStorage keys, then reloads the page so the app picks up the new values.
+
+**dom** -- For apps that use CSS classes or DOM attributes (planned):
+
+```json
+{
+  "strategy": "dom",
+  "modeClass": "dark",
+  "paletteAttribute": "data-palette"
+}
+```
+
+### Authentication
+
+#### Form-based login
+
+Pawprint fills in a login form, submits it, and saves the browser state for reuse:
+
+```json
+{
+  "strategy": "form",
+  "loginUrl": "/login",
+  "credentials": {
+    "username": "user@example.com",
+    "password": "password"
+  },
+  "selectors": {
+    "username": "input[type=email]",
+    "password": "input[type=password]",
+    "submit": "button[type=submit]",
+    "authCheck": ".dashboard-header"
+  }
+}
+```
+
+The saved `storageState.json` is reused for up to 1 hour before re-authenticating.
+
+#### Reusing storage state
+
+If you already have a Playwright storage state file:
+
+```json
+{
+  "strategy": "storageState",
+  "storageStatePath": "./storageState.json"
+}
+```
+
+## Output Structure
+
+Each run creates a timestamped folder to avoid overwriting previous results:
+
+```
+pawprint-output/
+  my-app/
+    2026-02-16/
+      2026-02-16_14-30-45/
+        default/
+          light/
+            home-desktop.png
+            home-mobile.png
+            dashboard-desktop.png
+          dark/
+            home-desktop.png
+            home-mobile.png
+            dashboard-desktop.png
+        high-contrast/
+          light/
+            ...
+          dark/
+            ...
+        metadata.json
+```
+
+### Screenshot Naming
+
+| Route | File Name |
+|---|---|
+| `/` | `home-{viewport}.png` |
+| `/dashboard` | `dashboard-{viewport}.png` |
+| `/user/profile` | `user_profile-{viewport}.png` |
+| (auth error) | `ERROR-{route}-{viewport}.png` |
+| (redirect to login) | `REDIRECTED-{route}-{viewport}.png` |
+
+### Metadata
+
+Each run writes a `metadata.json` with:
+
+```json
+{
+  "timestamp": "2026-02-16T14:30:45.000Z",
+  "appPath": "/path/to/app",
+  "config": { "baseUrl": "...", "routes": [...], "modes": [...] },
+  "outputPath": "pawprint-output/my-app/2026-02-16/2026-02-16_14-30-45",
+  "stats": {
+    "totalScreenshots": 24,
+    "successful": 24,
+    "failed": 0
+  }
+}
+```
+
+## Programmatic Usage
+
+Pawprint can be imported and used from another Node.js application instead of the CLI.
+
+### Basic Usage
+
+```typescript
+import { loadConfig } from "pawprint/dist/core/config.js";
+import { prepareOutputFolders, takeScreenshots } from "pawprint/dist/core/engine.js";
+
+const appPath = "/path/to/your-app";
+const config = loadConfig(appPath);
+
+const folderMap = prepareOutputFolders(config, appPath);
+await takeScreenshots(config, appPath, folderMap);
+```
+
+### With Inline Config
+
+```typescript
+import type { PawprintConfig } from "pawprint/dist/types/config.js";
+import { prepareOutputFolders, takeScreenshots } from "pawprint/dist/core/engine.js";
+
+const config: PawprintConfig = {
+  baseUrl: "http://localhost:3000",
+  routes: ["/", "/dashboard"],
+  modes: ["light", "dark"],
+  appearance: {
+    strategy: "localStorage",
+    modeKey: "theme",
+  },
+};
+
+const appPath = "/path/to/your-app";
+const folderMap = prepareOutputFolders(config, appPath);
+await takeScreenshots(config, appPath, folderMap);
+```
+
+### Available Exports
+
+| Module | Exports | Description |
+|---|---|---|
+| `core/config.js` | `loadConfig(appPath)` | Load and validate `pawprint.config.json` from a directory |
+| `core/engine.js` | `prepareOutputFolders(config, appPath)` | Create the timestamped output folder structure, returns a folder map |
+| `core/engine.js` | `takeScreenshots(config, appPath, folderMap)` | Launch Chromium and capture all screenshots |
+| `core/auth.js` | `setupAuth(context, page, config)` | Run authentication against a Playwright browser context |
+| `types/config.js` | `PawprintConfig`, `AuthStrategy`, `AppearanceStrategy`, `ViewportPreset`, `ScreenshotMetadata`, `FolderMap` | TypeScript interfaces |
+
+### Linking as a Local Dependency
+
+From another project:
+
+```bash
+# In the pawprint directory
+npm link
+
+# In your other project
+npm link pawprint
+```
+
+Then import as shown above.
+
+## Development
+
+```bash
+# Run CLI directly (no build needed)
+npm start -- generate /path/to/app
+
+# Watch mode
+npm run dev -- generate /path/to/app
+
+# Build TypeScript
+npm run build
+```
+
+## Tech Stack
+
+- **TypeScript** -- ES2022 target, NodeNext modules
+- **Playwright** -- Chromium browser automation
+- **Commander** -- CLI argument parsing
+- **Chalk** -- Terminal colors
+
+## License
+
+ISC

package/dist/cli/index.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import { prepareOutputFolders, takeScreenshots } from "../core/engine.js";
+import { writeOutputFiles } from "../core/output.js";
+import { createProgressDisplay } from "./progress.js";
+const CONFIG_FILE = "pawprint.config.json";
+const DEFAULT_OUTPUT_DIR = "pawprint-output";
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP_REGEX = /^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}$/;
+const program = new Command();
+function generateRunId() {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `r_${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+function createJsonlEmitter(runId) {
+    return (event) => {
+        const patched = { ...event, runId };
+        process.stdout.write(JSON.stringify(patched) + "\n");
+    };
+}
+function computeTotal(config) {
+    const routes = config.routes.length;
+    const modes = config.modes.length;
+    const palettes = config.palettes?.length ?? 1;
+    const viewports = config.viewports?.length ?? 1;
+    return routes * modes * palettes * viewports;
+}
+program
+    .name("pawprint")
+    .description("Screenshot tool for web apps across themes, palettes, and viewports")
+    .version("1.0.0");
+program
+    .command("capture")
+    .description("Capture screenshots for a web app")
+    .argument("<app-path>", "Path to the app or config file")
+    .option("-c, --config <path>", "Path to config file (default: <app-path>/pawprint.config.json)")
+    .option("-o, --output <dir>", "Output directory (overrides config)")
+    .option("--debug", "Enable debug mode with visible browser")
+    .option("--jsonl", "Emit JSONL events to stdout instead of human-readable output")
+    .option("--run-id <id>", "Custom run ID (default: auto-generated)")
+    .action(async (appPath, options) => {
+    const isJsonl = options.jsonl ?? false;
+    const runId = options.runId ?? generateRunId();
+    let config;
+    try {
+        const configPath = options.config
+            ? path.resolve(options.config)
+            : path.join(path.resolve(appPath), CONFIG_FILE);
+        if (!fs.existsSync(configPath)) {
+            if (isJsonl) {
+                process.stdout.write(JSON.stringify({ type: "run_finished", runId, status: "failed", count: 0, failed: 0, endedAt: new Date().toISOString() }) + "\n");
+            }
+            else {
+                console.error(chalk.red(`\nConfig not found: ${configPath}\n`));
+                console.log(chalk.dim(`  Create one with: pawprint init ${appPath}`));
+            }
+            process.exit(1);
+        }
+        const configContent = fs.readFileSync(configPath, "utf-8");
+        config = JSON.parse(configContent);
+        if (options.output) {
+            config.outputDir = options.output;
+        }
+        if (!config.baseUrl)
+            throw new Error("baseUrl is required in config");
+        if (!config.routes || config.routes.length === 0)
+            throw new Error("routes array is required in config");
+        if (!config.modes || config.modes.length === 0)
+            throw new Error("modes array is required in config");
+        const cfg = config;
+        const total = computeTotal(cfg);
+        const folderMap = prepareOutputFolders(cfg, appPath);
+        const firstFolder = Object.values(folderMap)[0];
+        const baseOutputPath = path.dirname(path.dirname(firstFolder));
+        const startedAt = new Date().toISOString();
+        const startTime = Date.now();
+        if (isJsonl) {
+            const emit = createJsonlEmitter(runId);
+            emit({ type: "run_started", runId, projectId: path.basename(appPath), startedAt });
+            const runResult = await takeScreenshots(cfg, appPath, folderMap, emit);
+            const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+            const stats = writeOutputFiles(baseOutputPath, appPath, cfg, runResult, runId, startedAt, duration);
+            emit({
+                type: "run_finished", runId,
+                status: stats.failed > 0 && stats.successful === 0 ? "failed" : "success",
+                count: stats.successful, failed: stats.failed,
+                endedAt: new Date().toISOString(),
+            });
+            return;
+        }
+        console.log("");
+        const display = createProgressDisplay(total, cfg.viewports);
+        const emit = (event) => display.onEvent(event);
+        const runResult = await takeScreenshots(cfg, appPath, folderMap, emit);
+        const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+        const stats = writeOutputFiles(baseOutputPath, appPath, cfg, runResult, runId, startedAt, duration);
+        display.finish(runResult.screenshots, stats, duration, baseOutputPath);
+    }
+    catch (error) {
+        if (isJsonl) {
+            process.stdout.write(JSON.stringify({ type: "run_finished", runId, status: "failed", count: 0, failed: 0, endedAt: new Date().toISOString() }) + "\n");
+        }
+        else {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(chalk.red(`\nError: ${msg}\n`));
+            if (msg.includes("ERR_CONNECTION_REFUSED") || msg.includes("ECONNREFUSED")) {
+                const baseUrl = config?.baseUrl ?? "your app";
+                console.log(chalk.dim(`  Could not connect to ${baseUrl}`));
+                console.log(chalk.dim(`  Make sure your dev server is running before capturing.\n`));
+            }
+            else if (msg.includes("baseUrl is required")) {
+                console.log(chalk.dim(`  Add "baseUrl" to your pawprint.config.json (e.g. "http://localhost:3000")\n`));
+            }
+            else if (msg.includes("routes array is required")) {
+                console.log(chalk.dim(`  Add a "routes" array to your config (e.g. ["/", "/dashboard"])\n`));
+            }
+            else if (msg.includes("modes array is required")) {
+                console.log(chalk.dim(`  Add a "modes" array to your config (e.g. ["light", "dark"])\n`));
+            }
+            else if (msg.includes("not found") && msg.includes("storageState")) {
+                console.log(chalk.dim(`  Authentication is configured but no session was saved.`));
+                console.log(chalk.dim(`  Check your auth selectors and credentials in pawprint.config.json\n`));
+            }
+            else if (msg.includes("Login failed")) {
+                console.log(chalk.dim(`  Check your auth credentials and selectors in pawprint.config.json`));
+                console.log(chalk.dim(`  Run with --debug to see debug screenshots in the current directory.\n`));
+            }
+            if (options.debug) {
+                console.error(error);
+            }
+        }
+        process.exit(1);
+    }
+});
+program
+    .command("init")
+    .description("Create a sample pawprint.config.json file")
+    .argument("[app-path]", "Path where to create the config file", ".")
+    .option("--force", "Overwrite existing config file")
+    .action((appPath, options) => {
+    const configPath = path.join(path.resolve(appPath), CONFIG_FILE);
+    if (fs.existsSync(configPath) && !options.force) {
+        console.error(chalk.red(`Config already exists: ${configPath}`));
+        console.log(chalk.dim("Use --force to overwrite"));
+        process.exit(1);
+    }
+    const sampleConfig = {
+        baseUrl: "http://localhost:3000",
+        routes: ["/", "/dashboard", "/settings", "/profile"],
+        modes: ["light", "dark"],
+        palettes: ["default", "alternative"],
+        viewports: [
+            { name: "desktop", width: 1440, height: 900 },
+            { name: "mobile", width: 390, height: 844 },
+            { name: "tablet", width: 768, height: 1024 },
+        ],
+        appearance: {
+            strategy: "localStorage",
+            modeKey: "theme",
+            paletteKey: "palette",
+        },
+        outputDir: DEFAULT_OUTPUT_DIR,
+        auth: {
+            strategy: "form",
+            loginUrl: "/login",
+            credentials: {
+                username: "your-email@example.com",
+                password: "your-password",
+            },
+            selectors: {
+                username: "input[type=email]",
+                password: "input[type=password]",
+                submit: "button[type=submit]",
+            },
+        },
+    };
+    fs.writeFileSync(configPath, JSON.stringify(sampleConfig, null, 2));
+    console.log(chalk.green(`Config created: ${configPath}`));
+    console.log(chalk.dim(`\nEdit it with your app's details, then run:`));
+    console.log(`  pawprint capture ${appPath}`);
+});
+program
+    .command("list")
+    .description("List all screenshot runs for an app")
+    .argument("<app-path>", "Path to the app")
+    .option("-o, --output <dir>", "Output directory (default: pawprint-output)")
+    .action((appPath, options) => {
+    const appName = path.basename(path.resolve(appPath));
+    const outputDir = options.output || DEFAULT_OUTPUT_DIR;
+    const appOutputPath = path.join(outputDir, appName);
+    if (!fs.existsSync(appOutputPath)) {
+        console.log(chalk.dim(`No runs found for ${appName}`));
+        return;
+    }
+    const dates = fs
+        .readdirSync(appOutputPath)
+        .filter((name) => DATE_REGEX.test(name))
+        .sort()
+        .reverse();
+    if (dates.length === 0) {
+        console.log(chalk.dim(`No runs found for ${appName}`));
+        return;
+    }
+    console.log(chalk.cyan(`\nRuns for ${appName}:\n`));
+    dates.forEach((date) => {
+        const datePath = path.join(appOutputPath, date);
+        const runs = fs
+            .readdirSync(datePath)
+            .filter((name) => TIMESTAMP_REGEX.test(name))
+            .sort()
+            .reverse();
+        if (runs.length > 0) {
+            console.log(`  ${chalk.bold(date)}`);
+            runs.forEach((run) => {
+                const runPath = path.join(datePath, run);
+                const metadataPath = path.join(runPath, "metadata.json");
+                const timeStr = run.replace(`${date}_`, "").replace(/-/g, ":");
+                if (fs.existsSync(metadataPath)) {
+                    try {
+                        const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+                        const count = metadata.stats?.totalScreenshots || "?";
+                        const failed = metadata.stats?.failed || 0;
+                        let line = `    ${timeStr}  ${count} screenshots`;
+                        if (failed > 0)
+                            line += chalk.yellow(` (${failed} failed)`);
+                        console.log(line);
+                    }
+                    catch {
+                        console.log(`    ${timeStr}`);
+                    }
+                }
+                else {
+                    console.log(`    ${timeStr}`);
+                }
+            });
+        }
+    });
+    console.log("");
+});
+program.parse(process.argv);

package/dist/cli/progress.js

@@ -0,0 +1,215 @@
+import chalk from "chalk";
+const isTTY = process.stdout.isTTY ?? false;
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const ERASE_LINE = "\x1b[2K";
+const CURSOR_UP = "\x1b[A";
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 1) + "…";
+}
+function formatEta(seconds) {
+    if (seconds < 60)
+        return `${Math.ceil(seconds)}s`;
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.ceil(seconds % 60);
+    return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+}
+export function createProgressDisplay(total, viewports) {
+    let completed = 0;
+    let linesDrawn = 0;
+    const startTime = Date.now();
+    const viewportCount = viewports?.length ?? 1;
+    const vpMap = new Map();
+    if (viewports) {
+        for (const vp of viewports) {
+            vpMap.set(vp.name, `${vp.width}x${vp.height}`);
+        }
+    }
+    const batches = new Map();
+    let displayedBatchKey = "";
+    const rW = 22;
+    const vW = 20;
+    const sW = 8;
+    const tableWidth = rW + vW + sW;
+    if (isTTY) {
+        process.stdout.write(HIDE_CURSOR);
+        const restore = () => process.stdout.write(SHOW_CURSOR);
+        process.on("exit", restore);
+        process.on("SIGINT", () => { restore(); process.exit(130); });
+    }
+    function batchKey(palette, mode) {
+        return `${palette}\t${mode}`;
+    }
+    function renderHeaderBar() {
+        const label = chalk.bold("PawPrint");
+        let etaStr = "";
+        let rawEtaLen = 0;
+        if (completed > 0 && completed < total) {
+            const elapsed = (Date.now() - startTime) / 1000;
+            const avgPerItem = elapsed / completed;
+            const remaining = (total - completed) * avgPerItem;
+            if (remaining > 1) {
+                const etaFormatted = formatEta(remaining);
+                etaStr = `${chalk.dim("eta")} ${chalk.dim(etaFormatted)}  `;
+                rawEtaLen = `eta ${etaFormatted}  `.length;
+            }
+        }
+        const counter = `${etaStr}${chalk.bold(`${completed}`)}${chalk.dim(`/${total}`)}`;
+        const rawCounterLen = rawEtaLen + `${completed}/${total}`.length;
+        const fixedLen = 2 + 8 + 1 + rawCounterLen + 1;
+        const barSpace = Math.max(10, tableWidth + 2 - fixedLen);
+        const pct = total > 0 ? completed / total : 0;
+        const filled = Math.round(pct * barSpace);
+        const empty = barSpace - filled;
+        const bar = chalk.yellow("━".repeat(filled)) + chalk.dim("━".repeat(empty));
+        return `  ${label} ${bar} ${counter}`;
+    }
+    function routeStatus(batch, route) {
+        const saved = batch.routeSaved.get(route) ?? 0;
+        const errors = batch.routeErrors.get(route) ?? 0;
+        if (saved === 0)
+            return chalk.dim("·");
+        if (saved >= viewportCount) {
+            return errors > 0 ? chalk.red("fail") : chalk.green("ok");
+        }
+        return chalk.yellow(`${saved}/${viewportCount}`);
+    }
+    function drawBatch() {
+        if (!isTTY)
+            return;
+        const batch = batches.get(displayedBatchKey);
+        if (!batch)
+            return;
+        if (linesDrawn > 0) {
+            for (let i = 0; i < linesDrawn; i++) {
+                process.stdout.write(`${CURSOR_UP}${ERASE_LINE}`);
+            }
+            process.stdout.write("\r");
+        }
+        let activeBatches = 0;
+        let completedBatches = 0;
+        for (const b of batches.values()) {
+            const batchTotal = b.ok + b.failed;
+            if (batchTotal >= b.routes.length * viewportCount)
+                completedBatches++;
+            else
+                activeBatches++;
+        }
+        const lines = [];
+        lines.push(renderHeaderBar());
+        lines.push("");
+        lines.push(`  Capturing ${chalk.bold(batch.palette)} ${chalk.dim("palette")} ${chalk.bold(batch.mode)} ${chalk.dim("mode")}`);
+        lines.push("");
+        lines.push(`  ${chalk.dim("Route".padEnd(rW))}${chalk.dim("Status")}`);
+        lines.push(chalk.dim(`  ${"─".repeat(rW + sW)}`));
+        for (const route of batch.routes) {
+            const name = truncate(route, rW).padEnd(rW);
+            lines.push(`  ${name}${routeStatus(batch, route)}`);
+        }
+        lines.push("");
+        if (batches.size > 1) {
+            lines.push(chalk.dim(`  ${completedBatches}/${batches.size} batches done — Ctrl+C to cancel`));
+        }
+        else {
+            lines.push(chalk.dim("  Ctrl+C to cancel"));
+        }
+        process.stdout.write(lines.join("\n") + "\n");
+        linesDrawn = lines.length;
+    }
+    function clearProgress() {
+        if (isTTY && linesDrawn > 0) {
+            for (let i = 0; i < linesDrawn; i++) {
+                process.stdout.write(`${CURSOR_UP}${ERASE_LINE}`);
+            }
+            process.stdout.write("\r");
+            linesDrawn = 0;
+        }
+    }
+    return {
+        onEvent(event) {
+            if (event.type === "batch_started") {
+                const key = batchKey(event.palette, event.mode);
+                const routeSaved = new Map();
+                const routeErrors = new Map();
+                for (const r of event.routes) {
+                    routeSaved.set(r, 0);
+                    routeErrors.set(r, 0);
+                }
+                batches.set(key, {
+                    palette: event.palette,
+                    mode: event.mode,
+                    routes: event.routes,
+                    routeSaved,
+                    routeErrors,
+                    ok: 0,
+                    failed: 0,
+                });
+                displayedBatchKey = key;
+                drawBatch();
+            }
+            if (event.type === "screenshot_saved") {
+                completed++;
+                const key = batchKey(event.palette, event.theme);
+                const batch = batches.get(key);
+                if (batch) {
+                    batch.routeSaved.set(event.route, (batch.routeSaved.get(event.route) ?? 0) + 1);
+                    if (event.status === "ok") {
+                        batch.ok++;
+                    }
+                    else {
+                        batch.failed++;
+                        batch.routeErrors.set(event.route, (batch.routeErrors.get(event.route) ?? 0) + 1);
+                    }
+                    displayedBatchKey = key;
+                }
+                drawBatch();
+            }
+            if (event.type === "route_failed") {
+                if (!isTTY) {
+                    console.log(`  ${chalk.red("fail")}  ${event.route} ${chalk.red(event.error)}`);
+                }
+            }
+        },
+        finish(results, stats, duration, outputPath) {
+            clearProgress();
+            if (isTTY) {
+                process.stdout.write(SHOW_CURSOR);
+            }
+            completed = total;
+            console.log(renderHeaderBar());
+            console.log("");
+            const pW = 16;
+            const mW = 12;
+            const groups = new Map();
+            for (const r of results) {
+                const key = `${r.palette}\t${r.mode}`;
+                const g = groups.get(key) ?? { ok: 0, failed: 0, total: 0 };
+                g.total++;
+                if (r.status === "ok")
+                    g.ok++;
+                else
+                    g.failed++;
+                groups.set(key, g);
+            }
+            console.log(`  ${chalk.dim("Palette".padEnd(pW))}${chalk.dim("Mode".padEnd(mW))}${chalk.dim("Screenshots")}`);
+            console.log(chalk.dim(`  ${"─".repeat(pW + mW + 14)}`));
+            for (const [key, g] of groups) {
+                const [palette, mode] = key.split("\t");
+                const countStr = g.failed > 0
+                    ? chalk.red(`${g.ok}/${g.total}`)
+                    : `${g.ok}/${g.total}`;
+                console.log(`  ${palette.padEnd(pW)}${mode.padEnd(mW)}${countStr}`);
+            }
+            console.log("");
+            if (stats.failed > 0) {
+                console.log(chalk.yellow(`  Done — ${stats.successful} ok, ${stats.failed} failed in ${duration}s`));
+            }
+            else {
+                console.log(chalk.green(`  Done — ${stats.successful} screenshots in ${duration}s`));
+            }
+            console.log(chalk.dim(`  Output: ${outputPath}`));
+        },
+    };
+}

package/dist/core/appearance.js

@@ -0,0 +1,80 @@
+/**
+ * Apply appearance settings (theme mode + color palette) to a page.
+ * Handles both localStorage and dom strategies.
+ * After applying, reloads the page so the app re-initializes with the new values.
+ */
+export async function applyAppearance(page, appearance, palette, mode, waitUntil = "networkidle", waitForTimeout = 500) {
+    if (appearance.strategy === "localStorage") {
+        await page.evaluate((args) => {
+            if (args.modeKey)
+                localStorage.setItem(args.modeKey, args.mode);
+            if (args.paletteKey)
+                localStorage.setItem(args.paletteKey, args.palette);
+        }, {
+            modeKey: appearance.modeKey,
+            paletteKey: appearance.paletteKey,
+            palette,
+            mode,
+        });
+        await page.reload({ waitUntil });
+        await page.waitForTimeout(waitForTimeout);
+    }
+    else if (appearance.strategy === "dom") {
+        await page.evaluate((args) => {
+            const root = document.documentElement;
+            if (args.modeClass) {
+                root.classList.remove("light", "dark");
+                root.classList.add(args.mode);
+            }
+            if (args.paletteAttribute) {
+                root.setAttribute(args.paletteAttribute, args.palette);
+            }
+        }, {
+            modeClass: appearance.modeClass,
+            paletteAttribute: appearance.paletteAttribute,
+            palette,
+            mode,
+        });
+        await page.reload({ waitUntil });
+        await page.waitForTimeout(waitForTimeout);
+    }
+}
+/**
+ * Set initial appearance values on a freshly created page context.
+ * Used before navigating to routes so the first load already has the right theme.
+ * Navigates to baseUrl first to establish origin for localStorage access.
+ */
+export async function initAppearance(page, appearance, baseUrl, palette, mode) {
+    if (appearance.strategy === "localStorage") {
+        await page.goto(baseUrl, { waitUntil: "domcontentloaded" });
+        await page.evaluate((args) => {
+            if (args.modeKey)
+                localStorage.setItem(args.modeKey, args.mode);
+            if (args.paletteKey)
+                localStorage.setItem(args.paletteKey, args.palette);
+        }, {
+            modeKey: appearance.modeKey,
+            paletteKey: appearance.paletteKey,
+            palette,
+            mode,
+        });
+    }
+    else if (appearance.strategy === "dom") {
+        await page.goto(baseUrl, { waitUntil: "domcontentloaded" });
+        await page.evaluate((args) => {
+            const root = document.documentElement;
+            if (args.modeClass) {
+                root.classList.remove("light", "dark");
+                root.classList.add(args.mode);
+            }
+            if (args.paletteAttribute) {
+                root.setAttribute(args.paletteAttribute, args.palette);
+            }
+        }, {
+            modeClass: appearance.modeClass,
+            paletteAttribute: appearance.paletteAttribute,
+            palette,
+            mode,
+        });
+    }
+}

package/dist/core/auth.js

@@ -0,0 +1,87 @@
+const STORAGE_STATE_FILE = "storageState.json";
+const AUTH_NAVIGATION_TIMEOUT = 10_000;
+const AUTH_SETTLE_DELAY = 2_000;
+const ERROR_SELECTORS = [
+    ".error",
+    ".alert",
+    '[role="alert"]',
+    ".text-red-500",
+    ".text-danger",
+    ".error-message",
+    ".invalid-feedback",
+    ".Mui-error",
+    ".ant-alert-error",
+    '[data-testid="error"]',
+];
+const ERROR_TEXT_COLORS = ["rgb(255, 0, 0)", "rgb(220, 38, 38)"];
+const AUTH_URL_PATTERNS = ["auth", "login", "signin"];
+/** Perform form-based authentication and save the browser session. */
+export async function setupAuth(context, page, config) {
+    if (!config.auth)
+        return;
+    if (config.auth.strategy === "storageState") {
+        return;
+    }
+    if (config.auth.strategy === "form") {
+        const loginUrl = new URL(config.auth.loginUrl, config.baseUrl).toString();
+        await page.goto(loginUrl, { waitUntil: "networkidle" });
+        await page.screenshot({ path: "debug-01-login-page.png" });
+        const usernameExists = await page.$(config.auth.selectors.username);
+        if (!usernameExists) {
+            throw new Error(`Username selector "${config.auth.selectors.username}" not found`);
+        }
+        await page.fill(config.auth.selectors.username, config.auth.credentials.username);
+        const passwordExists = await page.$(config.auth.selectors.password);
+        if (!passwordExists) {
+            throw new Error(`Password selector "${config.auth.selectors.password}" not found`);
+        }
+        await page.fill(config.auth.selectors.password, config.auth.credentials.password);
+        const submitExists = await page.$(config.auth.selectors.submit);
+        if (!submitExists) {
+            throw new Error(`Submit selector "${config.auth.selectors.submit}" not found`);
+        }
+        const responses = [];
+        const responseListener = (response) => {
+            const url = response.url();
+            if (AUTH_URL_PATTERNS.some(pattern => url.includes(pattern))) {
+                responses.push({ status: response.status(), url });
+            }
+        };
+        page.on("response", responseListener);
+        await Promise.all([
+            page.waitForNavigation({ waitUntil: "networkidle", timeout: AUTH_NAVIGATION_TIMEOUT }).catch(() => { }),
+            page.click(config.auth.selectors.submit),
+        ]);
+        page.removeListener("response", responseListener);
+        // Allow in-flight requests to settle
+        await page.waitForTimeout(AUTH_SETTLE_DELAY);
+        await page.screenshot({ path: "debug-02-after-login.png" });
+        const errorText = await page.evaluate((selectors) => {
+            for (const selector of selectors) {
+                const element = document.querySelector(selector);
+                if (element && element.textContent) {
+                    return element.textContent;
+                }
+            }
+            return null;
+        }, ERROR_SELECTORS);
+        if (errorText) {
+            throw new Error(`Login failed: ${errorText}`);
+        }
+        const failedResponses = responses.filter((r) => r.status === 401 || r.status === 403);
+        if (failedResponses.length > 0) {
+            throw new Error(`Login failed with status ${failedResponses[0].status}`);
+        }
+        const stillOnLogin = await page.evaluate(() => {
+            return (document.querySelector('input[type="password"]') !== null ||
+                document.querySelector('button[type="submit"]') !== null ||
+                window.location.pathname.includes("login") ||
+                window.location.pathname.includes("signin"));
+        });
+        if (stillOnLogin) {
+            throw new Error("Login failed - still on login page");
+        }
+        await context.storageState({ path: STORAGE_STATE_FILE });
+        await page.screenshot({ path: "debug-03-final-state.png" });
+    }
+}

package/dist/core/config.js

@@ -0,0 +1,24 @@
+import fs from "fs";
+import path from "path";
+const CONFIG_FILE = "pawprint.config.json";
+export function loadConfig(appPath) {
+    const configPath = path.join(appPath, CONFIG_FILE);
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`Config file not found at path: ${configPath}`);
+    }
+    const rawData = fs.readFileSync(configPath, "utf-8");
+    let config;
+    try {
+        config = JSON.parse(rawData);
+    }
+    catch (err) {
+        throw new Error(`Invalid JSON in config file: ${err.message}`);
+    }
+    const requiredFields = ["baseUrl", "routes", "modes", "appearance"];
+    for (const field of requiredFields) {
+        if (!(field in config)) {
+            throw new Error(`Missing required field in config: ${field}`);
+        }
+    }
+    return config;
+}

package/dist/core/engine.js

@@ -0,0 +1,220 @@
+import fs from "fs";
+import path from "path";
+import { chromium } from "playwright";
+import { setupAuth } from "./auth.js";
+import { applyAppearance, initAppearance } from "./appearance.js";
+function normalizeRoute(route) {
+    return typeof route === "string" ? { path: route } : route;
+}
+const DEFAULT_MODE = "default";
+const DEFAULT_PALETTE = "default";
+const DEFAULT_VIEWPORT = { name: "default", width: 1440, height: 900 };
+const DEFAULT_OUTPUT_DIR = "pawprint-output";
+const DEFAULT_WAIT_UNTIL = "networkidle";
+const DEFAULT_WAIT_TIMEOUT = 500;
+const FOLDER_KEY_SEPARATOR = "-";
+const CONCURRENCY = 3;
+const AUTH_SESSION_TTL_MS = 3_600_000;
+const STORAGE_STATE_FILE = "storageState.json";
+const ERROR_SCREENSHOT_PREFIX = "ERROR-";
+const HOME_ROUTE_NAME = "home";
+function resolveColorScheme(mode) {
+    if (mode === "dark")
+        return "dark";
+    if (mode === "light")
+        return "light";
+    return undefined;
+}
+const noopEmit = () => { };
+/** Prepare timestamped output folders for all palette/mode combinations. */
+export function prepareOutputFolders(config, appPath) {
+    const appName = path.basename(appPath);
+    const dateFolder = new Date().toISOString().split("T")[0];
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/:/g, "-")
+        .replace("T", "_")
+        .split(".")[0];
+    const baseOutput = path.join(config.outputDir ?? DEFAULT_OUTPUT_DIR, appName, dateFolder, timestamp);
+    const palettes = config.palettes?.length ? config.palettes : [DEFAULT_PALETTE];
+    const modes = config.modes?.length ? config.modes : [DEFAULT_MODE];
+    const folderMap = {};
+    for (const palette of palettes) {
+        for (const mode of modes) {
+            const folderPath = path.join(baseOutput, palette, mode);
+            fs.mkdirSync(folderPath, { recursive: true });
+            folderMap[`${palette}${FOLDER_KEY_SEPARATOR}${mode}`] = folderPath;
+        }
+    }
+    return folderMap;
+}
+function resolveStorageStatePath(config) {
+    if (config.auth?.strategy === "storageState") {
+        return config.auth.storageStatePath;
+    }
+    return STORAGE_STATE_FILE;
+}
+/** Capture all routes for a single palette/mode combination in parallel. */
+async function capturePaletteMode(browser, config, folderMap, palette, mode, routes, storageStatePath, isPublic, emit, waitUntil, waitForTimeout, viewportResizeWait, fullPage) {
+    const contextOptions = {
+        colorScheme: resolveColorScheme(mode),
+    };
+    if (!isPublic && fs.existsSync(storageStatePath)) {
+        contextOptions.storageState = storageStatePath;
+    }
+    const context = await browser.newContext(contextOptions);
+    // localStorage is shared across pages in the same context, so initialize once
+    if (config.appearance) {
+        const setupPage = await context.newPage();
+        await initAppearance(setupPage, config.appearance, config.baseUrl, palette, mode);
+        await setupPage.close();
+    }
+    emit({ type: "batch_started", runId: "", palette, mode, routes: routes.map(r => r.path) });
+    const batchResults = await Promise.all(routes.map(async (route) => {
+        const page = await context.newPage();
+        const results = [];
+        try {
+            emit({ type: "route_started", runId: "", route: route.path, palette, mode });
+            await captureRouteScreenshots(page, config, folderMap, palette, mode, route.path, results, emit, waitUntil, waitForTimeout, viewportResizeWait, fullPage);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            emit({ type: "route_failed", runId: "", route: route.path, error: msg });
+        }
+        finally {
+            await page.close();
+        }
+        return results;
+    }));
+    await context.close();
+    return batchResults.flat();
+}
+/** Run async tasks with a concurrency limit. */
+async function runWithConcurrency(tasks, limit) {
+    const results = [];
+    let index = 0;
+    async function next() {
+        while (index < tasks.length) {
+            const i = index++;
+            results[i] = await tasks[i]();
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => next());
+    await Promise.all(workers);
+    return results;
+}
+/** Run all palette/mode combos concurrently with routes parallel within each. */
+export async function takeScreenshots(config, appPath, folderMap, emit = noopEmit) {
+    const results = [];
+    const waitUntil = config.screenshotOptions?.waitUntil ?? DEFAULT_WAIT_UNTIL;
+    const waitForTimeout = config.screenshotOptions?.waitForTimeout ?? DEFAULT_WAIT_TIMEOUT;
+    const viewportResizeWait = Math.min(waitForTimeout, 300);
+    const fullPage = config.screenshotOptions?.fullPage ?? false;
+    const storageStatePath = resolveStorageStatePath(config);
+    const browser = await chromium.launch();
+    try {
+        const palettes = config.palettes?.length ? config.palettes : [DEFAULT_PALETTE];
+        const modes = config.modes?.length ? config.modes : [DEFAULT_MODE];
+        // Authenticate once if needed
+        if (config.auth?.strategy === "form") {
+            const shouldAuth = !fs.existsSync(storageStatePath) || Date.now() - fs.statSync(storageStatePath).mtimeMs > AUTH_SESSION_TTL_MS;
+            if (shouldAuth) {
+                emit({ type: "step", runId: "", message: "Setting up authentication" });
+                const authContext = await browser.newContext();
+                const authPage = await authContext.newPage();
+                try {
+                    await setupAuth(authContext, authPage, config);
+                }
+                catch (error) {
+                    throw error;
+                }
+                finally {
+                    await authPage.close();
+                    await authContext.close();
+                }
+            }
+        }
+        if (config.auth && !fs.existsSync(storageStatePath)) {
+            throw new Error(`Authentication required but ${storageStatePath} not found`);
+        }
+        const allRoutes = config.routes.map(normalizeRoute);
+        const publicRoutes = allRoutes.filter((r) => r.public);
+        const authRoutes = allRoutes.filter((r) => !r.public);
+        const tasks = [];
+        for (const palette of palettes) {
+            for (const mode of modes) {
+                if (publicRoutes.length > 0) {
+                    tasks.push(() => capturePaletteMode(browser, config, folderMap, palette, mode, publicRoutes, storageStatePath, true, emit, waitUntil, waitForTimeout, viewportResizeWait, fullPage));
+                }
+                if (authRoutes.length > 0) {
+                    tasks.push(() => capturePaletteMode(browser, config, folderMap, palette, mode, authRoutes, storageStatePath, false, emit, waitUntil, waitForTimeout, viewportResizeWait, fullPage));
+                }
+            }
+        }
+        const batchResults = await runWithConcurrency(tasks, CONCURRENCY);
+        for (const batch of batchResults) {
+            results.push(...batch);
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return { screenshots: results };
+}
+/** Sanitize a route path into a safe filename segment. */
+function sanitizeRoute(route) {
+    if (route === "/")
+        return HOME_ROUTE_NAME;
+    return route
+        .replace(/^\//, "")
+        .replace(/\//g, "_")
+        .replace(/\?/g, "--")
+        .replace(/[&=]/g, "-");
+}
+/** Capture screenshots for a single route across all viewports. */
+async function captureRouteScreenshots(page, config, folderMap, palette, mode, route, results, emit, waitUntil, waitForTimeout, viewportResizeWait, fullPage) {
+    const url = new URL(route, config.baseUrl).toString();
+    const response = await page.goto(url, { waitUntil }).catch(() => {
+        return null;
+    });
+    const viewports = config.viewports?.length ? config.viewports : [DEFAULT_VIEWPORT];
+    const safeRoute = sanitizeRoute(route);
+    if (response && (response.status() === 401 || response.status() === 403)) {
+        for (const viewport of viewports) {
+            await page.setViewportSize({ width: viewport.width, height: viewport.height });
+            const folderKey = `${palette}${FOLDER_KEY_SEPARATOR}${mode}`;
+            const folder = folderMap[folderKey];
+            const fileName = `${ERROR_SCREENSHOT_PREFIX}${safeRoute}-${viewport.name}.png`;
+            const filePath = path.join(folder, fileName);
+            await page.screenshot({ path: filePath, fullPage });
+            results.push({ route, viewport: viewport.name, palette, mode, filePath, status: "error", error: `HTTP ${response.status()}` });
+            emit({
+                type: "screenshot_saved", runId: "", route, theme: mode, palette,
+                viewport: viewport.name, path: filePath, status: "error",
+            });
+        }
+        emit({ type: "route_failed", runId: "", route, error: `HTTP ${response.status()}` });
+        return;
+    }
+    // Apply appearance and reload so the app re-initializes with correct theme values
+    if (config.appearance) {
+        await applyAppearance(page, config.appearance, palette, mode, waitUntil, waitForTimeout);
+    }
+    else {
+        await page.waitForTimeout(waitForTimeout);
+    }
+    for (const viewport of viewports) {
+        await page.setViewportSize({ width: viewport.width, height: viewport.height });
+        await page.waitForTimeout(viewportResizeWait);
+        const folderKey = `${palette}${FOLDER_KEY_SEPARATOR}${mode}`;
+        const folder = folderMap[folderKey];
+        const fileName = `${safeRoute}-${viewport.name}.png`;
+        const filePath = path.join(folder, fileName);
+        await page.screenshot({ path: filePath, fullPage });
+        results.push({ route, viewport: viewport.name, palette, mode, filePath, status: "ok" });
+        emit({
+            type: "screenshot_saved", runId: "", route, theme: mode, palette,
+            viewport: viewport.name, path: filePath, status: "ok",
+        });
+    }
+}

package/dist/core/output.js

@@ -0,0 +1,54 @@
+import fs from "fs";
+import path from "path";
+const METADATA_FILE = "metadata.json";
+const RUN_FILE = "run.json";
+export function writeOutputFiles(baseOutputPath, appPath, config, runResult, runId, startedAt, duration) {
+    const successful = runResult.screenshots.filter((s) => s.status === "ok").length;
+    const failed = runResult.screenshots.filter((s) => s.status === "error").length;
+    const total = runResult.screenshots.length;
+    const errors = runResult.screenshots
+        .filter((s) => s.status === "error" && s.error)
+        .map((s) => ({ route: s.route, mode: s.mode, palette: s.palette, error: s.error }));
+    const metadata = {
+        timestamp: new Date().toISOString(),
+        appPath,
+        config: {
+            baseUrl: config.baseUrl,
+            routes: config.routes,
+            modes: config.modes,
+            palettes: config.palettes,
+            viewports: config.viewports,
+        },
+        outputPath: baseOutputPath,
+        stats: {
+            totalScreenshots: total,
+            successful,
+            failed,
+            errors: errors.length > 0 ? errors : undefined,
+        },
+    };
+    fs.writeFileSync(path.join(baseOutputPath, METADATA_FILE), JSON.stringify(metadata, null, 2));
+    const runSummary = {
+        runId,
+        startedAt,
+        endedAt: new Date().toISOString(),
+        durationSeconds: parseFloat(duration),
+        status: failed > 0 && successful === 0 ? "failed" : "success",
+        config: {
+            baseUrl: config.baseUrl,
+            routes: config.routes,
+            modes: config.modes,
+            palettes: config.palettes,
+            viewports: config.viewports,
+            screenshotOptions: config.screenshotOptions,
+        },
+        stats: {
+            total,
+            successful,
+            failed,
+            errors: errors.length > 0 ? errors : undefined,
+        },
+    };
+    fs.writeFileSync(path.join(baseOutputPath, RUN_FILE), JSON.stringify(runSummary, null, 2));
+    return { successful, failed, total };
+}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cydoentis/pawprint",
+  "version": "1.0.0",
+  "description": "Automated screenshot tool for web apps across themes, palettes, and viewports",
+  "type": "module",
+  "bin": {
+    "pawprint": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "tsx src/cli/index.ts",
+    "dev": "tsx watch src/cli/index.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "screenshot",
+    "playwright",
+    "testing",
+    "visual-regression",
+    "theming",
+    "dark-mode",
+    "cli",
+    "automation"
+  ],
+  "author": "Cydo Entis",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CydoEntis/pawprint"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "playwright": "^1.58.2"
+  }
+}