@juxtapose/core 0.2.0 → 0.4.0

package/dist/report/html.js

@@ -0,0 +1,202 @@
+// A single self-contained report.html.
+//
+// The constraint that shapes everything here: it must work opened from
+// `file://`, because that is how someone downloads a CI artifact and looks at
+// it. No external stylesheet, no script src, no sibling image directory —
+// images inline as data URIs and the whole thing is one file you can email.
+//
+// This complements rather than duplicates the addon panel. The panel is for
+// local review with a dev server running; this is for a reviewer looking at a
+// pull request who has checked nothing out.
+import { formatPercent } from './format.js';
+export function buildHtmlReport({ report, images }) {
+    const needsReview = report.results.filter((r) => r.status === 'fail' || r.status === 'new' || r.status === 'stale');
+    const s = report.summary;
+    return `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>juxtapose — ${escapeHtml(report.branch)} @ ${escapeHtml(report.commitSha.slice(0, 7))}</title>
+<style>${STYLE}</style>
+
+<header>
+  <h1>${needsReview.length === 0 ? 'Visual tests passed' : 'Visual changes need review'}</h1>
+  <dl>
+    ${stat('pass', s.pass)}
+    ${s.fail ? stat('changed', s.fail, 'bad') : ''}
+    ${s.new ? stat('new', s.new, 'warn') : ''}
+    ${s.stale ? stat('stale', s.stale, 'warn') : ''}
+    ${s.skip ? stat('skipped', s.skip) : ''}
+  </dl>
+  <p class="meta">
+    ${escapeHtml(report.branch)} ·
+    <code>${escapeHtml(report.commitSha.slice(0, 7))}</code> ·
+    ${report.capturedCount}/${report.totalCount} captured ·
+    ${(report.durationMs / 1000).toFixed(1)}s
+  </p>
+</header>
+
+${needsReview.length === 0
+        ? `<p class="empty">Every captured story matches its approved baseline.</p>`
+        : needsReview.map((r) => storySection(r, images.get(r.storyId))).join('\n')}
+
+<script>${SCRIPT}</script>
+`;
+}
+function stat(label, value, tone = '') {
+    return `<div class="${tone}"><dt>${label}</dt><dd>${value}</dd></div>`;
+}
+function storySection(result, imgs) {
+    const baseline = dataUri(imgs?.baseline);
+    const current = dataUri(imgs?.current);
+    const diff = dataUri(imgs?.diff);
+    // A new story has no baseline, so there is nothing to compare — show the
+    // capture alone rather than an empty half. Same reasoning as the panel:
+    // controls that compare nothing read as broken.
+    const comparable = Boolean(baseline && current);
+    return `
+<section>
+  <h2>
+    <span class="badge ${result.status}">${statusLabel(result.status)}</span>
+    ${escapeHtml(result.storyId)}
+    ${result.status === 'fail' ? `<span class="pct">${escapeHtml(formatPercent(result.mismatchPercent))} changed</span>` : ''}
+  </h2>
+  ${result.error ? `<p class="error">${escapeHtml(result.error)}</p>` : ''}
+  ${comparable
+        ? `
+  <div class="tabs">
+    <button data-mode="sxs" class="on">Side by side</button>
+    <button data-mode="slider">Slider</button>
+    ${diff ? `<button data-mode="diff">Diff</button>` : ''}
+  </div>
+
+  <div class="views">
+    <div class="view sxs on">
+      <figure><figcaption>Baseline</figcaption><img src="${baseline}" alt="baseline"></figure>
+      <figure><figcaption>Current</figcaption><img src="${current}" alt="current"></figure>
+    </div>
+
+    <div class="view slider">
+      <div class="wipe" style="--pos:50%">
+        <img src="${baseline}" alt="baseline">
+        <img class="over" src="${current}" alt="current">
+        <div class="handle"></div>
+      </div>
+      <input type="range" min="0" max="100" value="50" aria-label="Wipe between baseline and current">
+    </div>
+
+    ${diff ? `<div class="view diff"><img src="${diff}" alt="diff overlay"></div>` : ''}
+  </div>`
+        : current
+            ? `<div class="single"><img src="${current}" alt="capture"></div>`
+            : `<p class="error">No capture available for this story.</p>`}
+</section>`;
+}
+/**
+ * Inline an image.
+ *
+ * Data URIs are what make the file portable — a sibling images/ directory
+ * breaks the moment someone moves or emails the html. The cost is roughly 33%
+ * inflation from base64, acceptable for a CI artifact.
+ */
+function dataUri(bytes) {
+    return bytes ? `data:image/webp;base64,${bytes.toString('base64')}` : null;
+}
+function statusLabel(status) {
+    switch (status) {
+        case 'fail':
+            return 'changed';
+        case 'new':
+            return 'no baseline';
+        case 'stale':
+            return 'stale';
+        default:
+            return status;
+    }
+}
+/** Escape anything interpolated into markup. Story ids come from the platform
+ *  and are not ours to trust. */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+const STYLE = `
+:root {
+  --fg: #0f172a; --muted: #64748b; --line: #e2e8f0; --bg: #fff;
+  --bad: #dc2626; --warn: #d97706;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --fg: #e2e8f0; --muted: #94a3b8; --line: #334155; --bg: #0f172a; }
+}
+* { box-sizing: border-box; }
+body { margin: 0 auto; padding: 24px; max-width: 1200px;
+       color: var(--fg); background: var(--bg); }
+h1 { font-size: 20px; margin: 0 0 12px; }
+dl { display: flex; gap: 20px; margin: 0 0 8px; padding: 0; }
+dl div { display: flex; gap: 6px; align-items: baseline; }
+dt { color: var(--muted); font-size: 13px; }
+dd { margin: 0; font-weight: 600; font-variant-numeric: tabular-nums; }
+dl .bad dd { color: var(--bad); } dl .warn dd { color: var(--warn); }
+.meta { color: var(--muted); font-size: 13px; margin: 0 0 28px; }
+.empty { color: var(--muted); }
+section { border-top: 1px solid var(--line); padding: 20px 0; }
+h2 { font-size: 15px; font-weight: 600; display: flex; align-items: center;
+     gap: 10px; margin: 0 0 12px; }
+.badge { font-size: 11px; text-transform: uppercase; letter-spacing: .04em;
+         padding: 2px 8px; border-radius: 999px; color: #fff; }
+.badge.fail { background: var(--bad); }
+.badge.new, .badge.stale { background: var(--warn); }
+.pct { color: var(--muted); font-weight: 400; font-size: 13px; }
+.error { color: var(--bad); font-size: 13px; margin: 0 0 12px; }
+.tabs { display: flex; gap: 4px; margin-bottom: 12px; }
+.tabs button { font: inherit; font-size: 12px; padding: 4px 10px; cursor: pointer;
+               border: 1px solid var(--line); background: transparent;
+               color: var(--muted); border-radius: 4px; }
+.tabs button.on { background: var(--fg); color: var(--bg); border-color: var(--fg); }
+.view { display: none; }
+.view.on { display: block; }
+.view.sxs.on { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+figure { margin: 0; }
+figcaption { font-size: 11px; text-transform: uppercase; letter-spacing: .04em;
+             color: var(--muted); margin-bottom: 6px; }
+img { max-width: 100%; height: auto; display: block; border: 1px solid var(--line); }
+.single img { max-width: 640px; }
+.wipe { position: relative; display: inline-block; max-width: 100%; }
+.wipe .over { position: absolute; inset: 0; clip-path: inset(0 0 0 var(--pos)); }
+.wipe .handle { position: absolute; top: 0; bottom: 0; left: var(--pos);
+                width: 2px; background: var(--bad); pointer-events: none; }
+input[type=range] { width: 100%; margin-top: 8px; }
+`;
+/**
+ * Tab switching and the wipe slider.
+ *
+ * Inline and dependency-free on purpose: a `file://` page cannot load anything
+ * external, and a report needing a build step to view defeats the point of
+ * being an artifact.
+ */
+const SCRIPT = `
+document.querySelectorAll('section').forEach(function (section) {
+  section.querySelectorAll('.tabs button').forEach(function (btn) {
+    btn.addEventListener('click', function () {
+      section.querySelectorAll('.tabs button').forEach(function (b) {
+        b.classList.toggle('on', b === btn);
+      });
+      section.querySelectorAll('.view').forEach(function (v) {
+        v.classList.toggle('on', v.classList.contains(btn.dataset.mode));
+      });
+    });
+  });
+
+  var range = section.querySelector('input[type=range]');
+  var wipe = section.querySelector('.wipe');
+  if (range && wipe) {
+    range.addEventListener('input', function () {
+      wipe.style.setProperty('--pos', range.value + '%');
+    });
+  }
+});
+`;
+//# sourceMappingURL=html.js.map

package/dist/report/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/report/html.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,uEAAuE;AACvE,8EAA8E;AAC9E,0EAA0E;AAC1E,4EAA4E;AAC5E,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,4CAA4C;AAG5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAS5C,MAAM,UAAU,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,EAAqB;IACnE,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CACvC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CACzE,CAAC;IACF,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;IAEzB,OAAO;;;qBAGY,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;SACnF,KAAK;;;QAGN,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,4BAA4B;;MAEjF,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;MACpB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;MAC5C,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;MACvC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;MAC7C,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE;;;MAGrC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;YACnB,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;MAC9C,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,UAAU;MACzC,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;;;;EAKzC,WAAW,CAAC,MAAM,KAAK,CAAC;QACtB,CAAC,CAAC,0EAA0E;QAC5E,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAC9E;;UAEU,MAAM;CACf,CAAC;AACF,CAAC;AAED,SAAS,IAAI,CAAC,KAAa,EAAE,KAAa,EAAE,IAAI,GAAG,EAAE;IACnD,OAAO,eAAe,IAAI,SAAS,KAAK,YAAY,KAAK,aAAa,CAAC;AACzE,CAAC;AAED,SAAS,YAAY,CACnB,MAAkB,EAClB,IAAwE;IAExE,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAEjC,yEAAyE;IACzE,wEAAwE;IACxE,gDAAgD;IAChD,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,CAAC;IAEhD,OAAO;;;yBAGgB,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;MAC/D,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC;MAC1B,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,qBAAqB,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE;;IAEzH,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,oBAAoB,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;IAEtE,UAAU;QACR,CAAC,CAAC;;;;MAIF,IAAI,CAAC,CAAC,CAAC,wCAAwC,CAAC,CAAC,CAAC,EAAE;;;;;2DAKC,QAAQ;0DACT,OAAO;;;;;oBAK7C,QAAQ;iCACK,OAAO;;;;;;MAMlC,IAAI,CAAC,CAAC,CAAC,oCAAoC,IAAI,6BAA6B,CAAC,CAAC,CAAC,EAAE;SAC9E;QACH,CAAC,CAAC,OAAO;YACP,CAAC,CAAC,iCAAiC,OAAO,wBAAwB;YAClE,CAAC,CAAC,2DACR;WACS,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,OAAO,CAAC,KAAyB;IACxC,OAAO,KAAK,CAAC,CAAC,CAAC,0BAA0B,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7E,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,SAAS,CAAC;QACnB,KAAK,KAAK;YACR,OAAO,aAAa,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;QACjB;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC;AAED;iCACiC;AACjC,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+Cb,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBd,CAAC"}

package/dist/run/phases.d.ts

@@ -0,0 +1,19 @@
+export interface Phases {
+    /** Time a promise-returning step, recording it under `name`. */
+    time<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /** Add to a phase directly, for work not shaped like a single call. */
+    add(name: string, ms: number): void;
+    /** Count of things a phase handled, e.g. how many diffs actually ran. */
+    count(name: string, n?: number): void;
+    readonly timings: Record<string, number>;
+    readonly counts: Record<string, number>;
+}
+export declare function phases(): Phases;
+/**
+ * `enumerate 12ms | capture 48.2s | diff(7) 810ms`
+ *
+ * Phases are printed in insertion order, which is execution order, so the line
+ * reads as the run happened. Sub-millisecond phases are dropped: they are noise
+ * next to a capture measured in seconds.
+ */
+export declare function formatPhases(p: Pick<Phases, 'timings' | 'counts'>): string;

package/dist/run/phases.js

@@ -0,0 +1,50 @@
+// Wall-time per stage of a run.
+//
+// A run reports one total today, which is enough to know it was slow and not
+// enough to know why. The phases have very different cost profiles — capture
+// dominates, diff is a cold path that only runs for stories that already
+// failed, and enumerate/affected are fixed overhead — so the total alone
+// cannot distinguish "700 stories" from "7 stories and a broken diff".
+export function phases() {
+    const timings = {};
+    const counts = {};
+    const add = (name, ms) => {
+        timings[name] = (timings[name] ?? 0) + ms;
+    };
+    return {
+        timings,
+        counts,
+        add,
+        count(name, n = 1) {
+            counts[name] = (counts[name] ?? 0) + n;
+        },
+        async time(name, fn) {
+            const started = Date.now();
+            try {
+                return await fn();
+            }
+            finally {
+                add(name, Date.now() - started);
+            }
+        },
+    };
+}
+/**
+ * `enumerate 12ms | capture 48.2s | diff(7) 810ms`
+ *
+ * Phases are printed in insertion order, which is execution order, so the line
+ * reads as the run happened. Sub-millisecond phases are dropped: they are noise
+ * next to a capture measured in seconds.
+ */
+export function formatPhases(p) {
+    const parts = [];
+    for (const [name, ms] of Object.entries(p.timings)) {
+        if (ms < 1)
+            continue;
+        const n = p.counts[name];
+        const label = n === undefined ? name : `${name}(${n})`;
+        parts.push(`${label} ${ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`}`);
+    }
+    return parts.join(' | ');
+}
+//# sourceMappingURL=phases.js.map

package/dist/run/phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phases.js","sourceRoot":"","sources":["../../src/run/phases.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,yEAAyE;AACzE,uEAAuE;AAavE,MAAM,UAAU,MAAM;IACpB,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,EAAE;QACvC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IAC5C,CAAC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,MAAM;QACN,GAAG;QACH,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE;YACjB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;oBAAS,CAAC;gBACT,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,CAAqC;IAChE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,EAAE,GAAG,CAAC;YAAE,SAAS;QACrB,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC"}

package/dist/run/run.d.ts

@@ -2,6 +2,7 @@ import type { Browser } from 'playwright';
 import type { Platform } from '../platform.js';
 import type { BaselineStore, DiffStatus, ProjectConfig, RunReport, StoryManifest, Viewport } from '../types.js';
 import { type AncestryCheck } from '../baseline/status.js';
+import { type Phases } from './phases.js';
 export declare const DEFAULT_VIEWPORT: Viewport;
 export interface RunOptions {
     browser: Browser;
@@ -20,6 +21,9 @@ export interface RunOptions {
     onArtifact?: (artifact: RunArtifact) => Promise<void>;
     onProgress?: (done: number, total: number, storyId: string) => void;
     signal?: AbortSignal;
+    /** Collects per-phase wall time. Pass one to fold in phases the caller timed
+     *  itself (enumerate, affected, launch); omit and one is made internally. */
+    phases?: Phases;
 }
 export interface RunArtifact {
     storyId: string;

package/dist/run/run.js

@@ -4,15 +4,18 @@
 // so it runs for every story. Decoding and diffing are expensive and explain
 // nothing about a passing story, so they run only for stories that already
 // failed. On a green run this function never decodes a single image.
+import { captureEnv } from '../capture/env.js';
 import { capturePool } from '../capture/pool.js';
 import { resolveStatus, toDiffStatus } from '../baseline/status.js';
 import { diffImages, resolveThreshold, resolveMinDiffPercent } from '../diff/diff.js';
+import { phases } from './phases.js';
 export const DEFAULT_VIEWPORT = { width: 1280, height: 800 };
 export async function runCapture(opts) {
     const startedAt = new Date();
     const started = Date.now();
     const viewport = opts.config?.viewport ?? DEFAULT_VIEWPORT;
-    const manifest = await opts.store.readManifest();
+    const p = opts.phases ?? phases();
+    const manifest = await p.time('baselines', () => opts.store.readManifest());
     const results = [];
     const pool = capturePool(opts.stories, {
         browser: opts.browser,
@@ -24,6 +27,10 @@ export async function runCapture(opts) {
         onProgress: opts.onProgress,
         signal: opts.signal,
     });
+    // Capture is measured as the whole streamed loop rather than per story: the
+    // pool runs `concurrency` pages at once, so summing per-story durations would
+    // report several times the wall-clock actually spent.
+    const captureStarted = Date.now();
     for await (const outcome of pool) {
         if (outcome.skipped) {
             results.push({
@@ -48,13 +55,19 @@ export async function runCapture(opts) {
             });
             continue;
         }
-        results.push(await judge(outcome.snapshot, outcome.story, manifest, opts));
+        results.push(await judge(outcome.snapshot, outcome.story, manifest, opts, p));
     }
+    // Diffing happens inside the loop, so subtract it to leave capture alone.
+    p.add('capture', Date.now() - captureStarted - (p.timings.diff ?? 0));
     const summary = tally(results);
     return {
         runId: opts.runId,
         branch: opts.branch,
         commitSha: opts.commitSha,
+        // Carried on the report because `approve` has no browser of its own — it
+        // reads captured images off disk, so this is the only path by which the
+        // fingerprint reaches a baseline entry.
+        env: captureEnv(opts.browser),
         capturedCount: opts.stories.length,
         totalCount: opts.totalCount,
         results: results.sort((a, b) => a.storyId.localeCompare(b.storyId)),
@@ -64,7 +77,7 @@ export async function runCapture(opts) {
     };
 }
 /** Decide one story's fate. Cheap path first. */
-async function judge(snapshot, story, manifest, opts) {
+async function judge(snapshot, story, manifest, opts, p) {
     const baselineStatus = resolveStatus(story.storyId, snapshot.image, manifest, opts.ancestry);
     const status = toDiffStatus(baselineStatus);
     const base = {
@@ -73,6 +86,10 @@ async function judge(snapshot, story, manifest, opts) {
         mismatchPixels: 0,
         mismatchPercent: 0,
         changedRegions: [],
+        // The effective viewport, including any per-story override. Recording it
+        // with the regions means nobody downstream has to re-enumerate stories to
+        // find out what the coordinates are relative to.
+        viewport: snapshot.viewport,
         durationMs: snapshot.durationMs,
     };
     // pass / new / stale need no pixel work: there is either nothing to explain
@@ -87,10 +104,13 @@ async function judge(snapshot, story, manifest, opts) {
         await opts.onArtifact?.({ storyId: story.storyId, status, current: snapshot.image });
         return { ...base, error: 'baseline missing from store' };
     }
-    const diff = await diffImages(baseline, snapshot.image, {
+    // Counted as well as timed: under a byte-exact hash the number of diffs is
+    // how broken the run was, and it is the figure that explains a slow one.
+    p.count('diff');
+    const diff = await p.time('diff', () => diffImages(baseline, snapshot.image, {
         threshold: resolveThreshold(story.params, opts.config),
         minDiffPercent: resolveMinDiffPercent(story.params, opts.config),
-    });
+    }));
     await opts.onArtifact?.({
         storyId: story.storyId,
         status,

package/dist/run/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -18,6 +18,14 @@ export interface StoryParams {
     waitForSelector?: string;
     /** Max ms to wait for render-ready before screenshotting anyway. Default 2000. */
     captureTimeout?: number;
+    /** Selectors to cover with a solid box before the screenshot. For a clock or
+     *  a random avatar; prefer stubbing the input. Masks the element's bounding
+     *  box, so give it a fixed size or the box resizes with the content. */
+    mask?: string[];
+    /** Exclude from watch-mode recapture while leaving normal runs alone. For
+     *  stories whose play function or delay makes a keystroke-triggered capture
+     *  cost more than it returns. Default true. */
+    liveCapture?: boolean;
 }
 export interface Viewport {
     width: number;
@@ -59,6 +67,13 @@ export interface DiffResult {
     mismatchPercent: number;
     /** Bounding boxes of changed clusters. Empty unless status is 'fail'. */
     changedRegions: ChangedRegion[];
+    /** The viewport the capture was taken at — what `changedRegions` coordinates
+     *  are relative to. Absent only when the capture never produced a snapshot.
+     *
+     *  Recording it here is what lets a consumer describe a region spatially
+     *  without re-enumerating stories to recover a per-story viewport override,
+     *  which is both slow and wrong when the override exists. */
+    viewport?: Viewport;
     /** Set when the capture or diff threw. status is 'fail' in that case. */
     error?: string;
     durationMs: number;
@@ -67,6 +82,9 @@ export interface RunReport {
     runId: string;
     branch: string;
     commitSha: string;
+    /** What captured these pixels. Optional so a report written by an older
+     *  version still parses. */
+    env?: CaptureEnv;
     /** How many stories we captured vs how many exist. */
     capturedCount: number;
     totalCount: number;
@@ -75,10 +93,27 @@ export interface RunReport {
     durationMs: number;
     startedAt: string;
 }
+/** What rendered the pixels. Baselines from different environments are not
+ *  comparable byte-for-byte, so recording this is what lets an all-red suite
+ *  after a toolchain bump be reported as a bump rather than as N regressions. */
+export interface CaptureEnv {
+    /** Playwright's `browser.version()`, e.g. "151.0.7922.34". */
+    browser: string;
+    /** `${platform}-${arch}`, e.g. "darwin-arm64". */
+    os: string;
+    /** libvips, which encodes the WebP. Measured to move bytes far more readily
+     *  than the browser does: a libvips bump changed all 17 example baseline
+     *  hashes with zero changed pixels, while Chromium 149 -> 151 left 16 of 18
+     *  byte-identical. */
+    encoder: string;
+}
 export interface ApprovalMeta {
     commit: string;
     approvedBy: string;
     approvedAt: string;
+    /** Absent on entries approved before this was recorded. Absent must not read
+     *  as "matches": an unknown origin is unknown, not current. */
+    env?: CaptureEnv;
 }
 export interface BaselineEntry extends ApprovalMeta {
     /** sha256 of the baseline image bytes. Detects drift between manifest
@@ -110,8 +145,6 @@ export interface ProjectConfig {
     viewport?: Viewport;
     threshold?: number;
     minDiffPercent?: number;
-    /** Glob patterns of story ids to never capture. */
-    ignore?: string[];
     storage?: StorageConfig;
 }
 export type StorageConfig = {

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@juxtapose/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Platform-agnostic capture, diff, baseline and analysis core for juxtapose.",
+  "keywords": [
+    "visual-regression",
+    "screenshot-testing",
+    "playwright",
+    "visual-testing",
+    "pixelmatch"
+  ],
+  "homepage": "https://github.com/juxtapose-dev/juxtapose/tree/main/packages/core#readme",
   "publishConfig": {
     "access": "public"
   },
@@ -11,6 +19,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./format": "./dist/report/format.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -18,7 +27,7 @@
   ],
   "dependencies": {
     "pixelmatch": "^6.0.0",
-    "sharp": "^0.33.5"
+    "sharp": "^0.35.3"
   },
   "peerDependencies": {
     "playwright": "^1.48.0"