styleproof 3.2.0 → 3.4.0

package/dist/capture-url.js

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
+import { detectViewportWidths } from './breakpoints.js';
+import { runSetup } from './crawl-surfaces.js';
+/**
+ * One-shot capture of a single URL's computed-style map — no spec, no config,
+ * no git. `defineStyleMapCapture` is the right tool when the surfaces live in
+ * your own app and you want the coverage guard, the map store, and record/replay.
+ * This is the tool for a page you just want to point at: a deployed URL, a
+ * static export, or a standalone HTML mockup. Capture it into a directory of
+ * `<key>@<width>.json.gz` maps (+ `.png`) that {@link diffStyleMapDirs} — i.e.
+ * `styleproof-diff <a> <b>` — compares like any other capture.
+ *
+ * The output is deliberately the same shape a surface capture writes, so a
+ * mockup's map and your app's committed map are directly diffable: capture the
+ * design once, then diff each build against it to measure how close the
+ * implementation is (a diff that shrinks toward zero as it converges).
+ */
+/** Raised for bad CLI usage so the bin can print help and exit 2. */
+export class UsageError extends Error {
+}
+const DEFAULTS = {
+    key: 'page',
+    height: 800,
+    screenshots: true,
+    crawl: false,
+    // Exhaustive by default — these are safety backstops, not budgets.
+    maxDepth: 1000,
+    maxActionsPerState: 100000,
+    maxStates: 100000,
+    resetStorage: true,
+    requireFullCoverage: false,
+    dataStates: true,
+};
+function positiveNumber(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new UsageError(`${flag}: not a positive number: ${raw}`);
+    return n;
+}
+function parseWidths(raw) {
+    const widths = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => positiveNumber(s, '--widths'));
+    if (widths.length === 0)
+        throw new UsageError('--widths: no widths given');
+    return widths;
+}
+// Table-driven so adding a flag is one entry, not another branch in the loop.
+// value flags mutate the accumulator with their argument; bool flags take none.
+const VALUE_FLAGS = {
+    '--key': (o, v) => (o.key = v),
+    '--widths': (o, v) => (o.widths = parseWidths(v)),
+    '--out': (o, v) => (o.out = v),
+    '--ignore': (o, v) => o.ignore.push(v),
+    '--wait': (o, v) => (o.waitSelector = v),
+    '--height': (o, v) => (o.height = positiveNumber(v, '--height')),
+    '--max-depth': (o, v) => (o.maxDepth = positiveNumber(v, '--max-depth')),
+    '--max-actions': (o, v) => (o.maxActionsPerState = positiveNumber(v, '--max-actions')),
+    '--max-states': (o, v) => (o.maxStates = positiveNumber(v, '--max-states')),
+    '--setup': (o, v) => (o.setupFile = v),
+};
+const BOOL_FLAGS = {
+    '--screenshots': (o) => (o.screenshots = true),
+    '--no-screenshots': (o) => (o.screenshots = false),
+    '--crawl': (o) => (o.crawl = true),
+    '--no-reset-storage': (o) => (o.resetStorage = false),
+    '--require-full-coverage': (o) => (o.requireFullCoverage = true),
+    '--data-states': (o) => (o.dataStates = true),
+    '--no-data-states': (o) => (o.dataStates = false),
+};
+// Apply one argv token to the accumulator; returns the index to resume from
+// (advanced past a consumed `--flag value` pair). Flat early-returns so the
+// parse loop stays trivial. Supports `--flag value` and `--flag=value`.
+function applyArg(o, argv, i, positional) {
+    const a = argv[i];
+    const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+    const name = eq === -1 ? a : a.slice(0, eq);
+    const bool = BOOL_FLAGS[name];
+    if (bool) {
+        bool(o);
+        return i;
+    }
+    const apply = VALUE_FLAGS[name];
+    if (apply) {
+        const v = eq === -1 ? argv[i + 1] : a.slice(eq + 1);
+        if (v === undefined)
+            throw new UsageError(`${name}: missing value`);
+        apply(o, v);
+        return eq === -1 ? i + 1 : i;
+    }
+    if (a.startsWith('--'))
+        throw new UsageError(`unknown flag: ${a}`);
+    positional.push(a);
+    return i;
+}
+/**
+ * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI
+ * flow (help/exit codes) and this parse are testable without a browser.
+ */
+export function parseCaptureUrlArgs(argv) {
+    const o = {
+        url: '',
+        key: DEFAULTS.key,
+        widths: [],
+        out: 'styleproof-capture',
+        ignore: [],
+        waitSelector: undefined,
+        height: DEFAULTS.height,
+        screenshots: DEFAULTS.screenshots,
+        crawl: DEFAULTS.crawl,
+        maxDepth: DEFAULTS.maxDepth,
+        maxActionsPerState: DEFAULTS.maxActionsPerState,
+        maxStates: DEFAULTS.maxStates,
+        resetStorage: DEFAULTS.resetStorage,
+        requireFullCoverage: DEFAULTS.requireFullCoverage,
+        setupFile: undefined,
+        dataStates: DEFAULTS.dataStates,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++)
+        i = applyArg(o, argv, i, positional);
+    if (positional.length === 0)
+        throw new UsageError('missing <url>');
+    if (positional.length > 1)
+        throw new UsageError(`expected one <url>, got ${positional.length}`);
+    o.url = positional[0];
+    return o;
+}
+/**
+ * Capture `opts.url` at each width using an already-open {@link Page}, writing
+ * `<out>/<key>@<width>.json.gz` (+ `.png`). Re-navigates per width so
+ * width-dependent rendering (media queries, `matchMedia`) is captured fresh, and
+ * arms the in-flight request tracker before each navigation so the page's own
+ * load fetches count toward the network-aware settle — same contract as a
+ * surface capture. Returns the files written.
+ */
+export async function captureUrlToDir(page, opts) {
+    fs.mkdirSync(opts.out, { recursive: true });
+    let widths = opts.widths;
+    if (widths.length === 0) {
+        await page.setViewportSize({ width: 1280, height: opts.height });
+        await page.goto(opts.url, { waitUntil: 'load' });
+        if (opts.waitSelector)
+            await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+        if (opts.setup?.length)
+            await runSetup(page, opts.setup);
+        widths = await detectViewportWidths(page);
+    }
+    const results = [];
+    for (const width of widths) {
+        await page.setViewportSize({ width, height: opts.height });
+        const requests = trackInflightRequests(page);
+        try {
+            await page.goto(opts.url, { waitUntil: 'load' });
+            if (opts.waitSelector)
+                await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+            if (opts.setup?.length)
+                await runSetup(page, opts.setup);
+            const map = await captureStyleMap(page, {
+                ignore: opts.ignore,
+                pendingRequests: requests.pending,
+                metadata: { surfaceKey: opts.key },
+            });
+            const stem = path.join(opts.out, `${opts.key}@${width}`);
+            const mapPath = `${stem}.json.gz`;
+            saveStyleMap(mapPath, map);
+            const result = { width, map: mapPath };
+            if (opts.screenshots) {
+                const shot = `${stem}.png`;
+                // captureStyleMap froze animations, so the shot matches the mapped state.
+                await page.screenshot({ path: shot, fullPage: true, animations: 'disabled' });
+                result.screenshot = shot;
+            }
+            results.push(result);
+        }
+        finally {
+            requests.dispose();
+        }
+    }
+    return results;
+}
+/** Launch Chromium, capture the URL, and close — the whole bin body given parsed options. */
+export async function runCaptureUrl(opts, launch) {
+    const browser = await launch();
+    try {
+        const page = await browser.newPage();
+        return await captureUrlToDir(page, opts);
+    }
+    finally {
+        await browser.close();
+    }
+}
+const SETUP_ACTIONS = new Set(['goto', 'fill', 'click', 'waitFor']);
+/**
+ * Load and validate a `--setup` steps file, interpolating `${ENV_VAR}` in every
+ * `value` and `url` from the environment — so credentials for an input-gated
+ * page live in env vars, never in the file, the shell history, or the maps.
+ * Throws {@link UsageError} on a malformed file or a missing variable.
+ */
+export function loadSetupSteps(file, env = process.env) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new UsageError(`--setup: cannot read ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new UsageError('--setup: the file must be a JSON array of steps');
+    const interpolate = (raw) => raw.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+        const v = env[name];
+        if (v === undefined)
+            throw new UsageError(`--setup: environment variable ${name} is not set`);
+        return v;
+    });
+    return parsed.map((raw, i) => {
+        const step = raw;
+        if (!SETUP_ACTIONS.has(step.action))
+            throw new UsageError(`--setup: step ${i} has unknown action "${String(step.action)}"`);
+        if (step.action === 'goto' && !step.url)
+            throw new UsageError(`--setup: step ${i} (goto) needs a url`);
+        if (step.action !== 'goto' && !step.selector)
+            throw new UsageError(`--setup: step ${i} (${step.action}) needs a selector`);
+        return {
+            ...step,
+            ...(step.url ? { url: interpolate(step.url) } : {}),
+            ...(step.value ? { value: interpolate(step.value) } : {}),
+        };
+    });
+}

package/dist/crawl-surfaces.d.ts

@@ -0,0 +1,122 @@
+import type { Page } from '@playwright/test';
+/**
+ * Surface crawler: deterministically map a single URL's WHOLE interactive
+ * surface — not just the state it loads in — and run to natural termination.
+ *
+ * A one-shot capture records the page as it lands, so a design that's mostly
+ * modals, drawers, and popovers has most of its surface behind clicks it never
+ * reaches. This crawls it instead: from the base state it finds every visible,
+ * non-destructive control (semantic controls AND anything the page styles as
+ * clickable — `cursor: pointer`) and drives each one, keeping whatever opens a
+ * structurally new surface. It then recurses depth-first into each new surface,
+ * so a modal's tabs, a drawer's sub-views, and a popover's panels are all mapped.
+ *
+ * EXHAUSTIVE by default: the crawl stops when the queue drains and every control
+ * has been driven once — not at a budget. Termination is guaranteed by dedup
+ * (a control is driven once by selector; a structural surface is captured once;
+ * both sets are finite). The `--max-*` options exist only as throttles.
+ *
+ * The sweep is IN-PLACE with lazy resets, which is what makes exhaustive
+ * affordable: standing in a state, each candidate is clicked where the page
+ * already is, and a cheap DOM fingerprint (tag+class in document order — no
+ * computed styles) decides what happened. A no-op click costs nothing; only a
+ * state-changing click pays a reset (fresh navigation + path replay), and every
+ * reset is VERIFIED against the state's fingerprint before the sweep continues,
+ * so children are never attributed to the wrong parent. New surfaces are
+ * captured in place the moment they're reached — a deep or animated click-path
+ * is never re-driven to capture, so it can't be the thing that drops a surface.
+ *
+ * Destructive-looking controls (delete, deploy, pay, revoke…) are never clicked —
+ * mapping must not mutate. States gated behind such an action need a spec.
+ */
+export type CrawlStep = {
+    action: 'click' | 'select-option' | 'fill-input';
+    selector: string;
+    label: string;
+    reason: string;
+    value?: string;
+};
+export type CrawledSurface = {
+    key: string;
+    depth: number;
+    path: CrawlStep[];
+    elements: number;
+};
+/** Did the crawl SEE everything the design styles? `missing` lists classes the
+ *  page's own stylesheets select on that never appeared in any captured surface —
+ *  dead CSS, or a state the crawl could not reach. Empty missing = full coverage. */
+export type CrawlCoverage = {
+    defined: number;
+    rendered: number;
+    missing: string[];
+};
+export type CrawlReport = {
+    surfaces: CrawledSurface[];
+    actionsTried: number;
+    skipped: number;
+    /** Surfaces successfully captured to disk at every width. */
+    captured: number;
+    /** Keys of surfaces discovered but whose full capture failed. */
+    failed: string[];
+    coverage: CrawlCoverage;
+};
+/**
+ * One deterministic step run after every fresh navigation, BEFORE the crawl
+ * looks at the page — how input-gated states (a login form, a search box)
+ * become crawlable. Values come from the caller with `${ENV_VAR}` interpolation
+ * done at load time, so secrets live in the environment, never in files or maps.
+ * `optional: true` skips the step silently when its selector isn't present
+ * (e.g. a cookie-session app that only shows the login form once).
+ */
+export type SetupStep = {
+    action: 'goto' | 'fill' | 'click' | 'waitFor';
+    url?: string;
+    selector?: string;
+    value?: string;
+    optional?: boolean;
+};
+export type SurfaceCrawlOptions = {
+    url: string;
+    out: string;
+    widths: number[];
+    ignore: string[];
+    height: number;
+    screenshots: boolean;
+    waitSelector?: string;
+    /** Deterministic steps (login, unlock, seed input) run after EVERY fresh
+     *  navigation, so each reset re-establishes the gated state identically. */
+    setup?: SetupStep[];
+    /** Also capture automatic data states of the entry page: `loading` (data
+     *  requests stalled — the skeleton) and `error` (data requests fulfilled with
+     *  a 500). Default true; states that render identically to base are skipped. */
+    dataStates?: boolean;
+    /** Throttle: recursion depth into opened surfaces (base = 0). Default: unbounded. */
+    maxDepth: number;
+    /** Throttle: fresh controls driven per state. Default: unbounded — try them all. */
+    maxActionsPerState: number;
+    /** Throttle: total surfaces. Default: unbounded — run to natural termination. */
+    maxStates: number;
+    /** Clear localStorage/sessionStorage on each reset so replay is deterministic. Default true. */
+    resetStorage: boolean;
+    /** Called as each surface is recorded (captured=false when its full capture failed).
+     *  Lets CLIs stream progress instead of reporting only at the end. */
+    onSurface?: (surface: CrawledSurface, captured: boolean) => void;
+};
+export declare const CRAWL_DEFAULTS: {
+    height: number;
+    screenshots: boolean;
+    maxDepth: number;
+    maxActionsPerState: number;
+    maxStates: number;
+    resetStorage: boolean;
+};
+/** Run the caller's deterministic setup steps (login, unlock, seed input). A
+ *  non-optional step that fails throws loudly — a half-established gate must
+ *  never silently crawl the ungated page instead. */
+export declare function runSetup(page: Page, steps: SetupStep[]): Promise<void>;
+/**
+ * Crawl `opts.url` and capture every reachable surface at every width — runs to
+ * natural termination by default. Returns the surfaces mapped (with the click-path
+ * that reached each), how many actions were tried/skipped, and captured/failed.
+ */
+export declare function crawlAndCapture(page: Page, opts: SurfaceCrawlOptions): Promise<CrawlReport>;