@juxtapose/core 0.2.0 → 0.5.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 { describeMagnitude } 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(describeMagnitude(result))}</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":"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"}

package/dist/run/groups.d.ts

@@ -0,0 +1,2 @@
+import type { DiffResult, RunGroup } from '../types.js';
+export declare function computeGroups(results: DiffResult[]): RunGroup[];

package/dist/run/groups.js

@@ -0,0 +1,45 @@
+// Which failing stories changed the same way. The verdict's signature
+// already abstracts the element to role|tag and keeps the values, so "every
+// button background #2563eb→#1d4ed8" hashes alike on every page that made
+// that change; grouping is a bucket sort on it. Cold path: runs once per
+// report, after every story is judged.
+import { compareCodeUnits } from '../diff/structural/deltas.js';
+export function computeGroups(results) {
+    const bySignature = new Map();
+    for (const r of results) {
+        // A verdict with no deltas has a signature that depends on the
+        // classification alone: unrelated identical, drifting or resized
+        // stories would "share" it, and there is no change to state.
+        if (r.status !== 'fail' || !r.structural || r.structural.deltaCount === 0)
+            continue;
+        const { signature, change, summary } = r.structural;
+        const text = change ?? summary;
+        const g = bySignature.get(signature);
+        if (!g)
+            bySignature.set(signature, { ids: [r.storyId], first: r.storyId, change: text });
+        else {
+            g.ids.push(r.storyId);
+            // The wording of the first story in code-unit order, whatever the
+            // input order: two verdicts of one signature can word it differently.
+            if (compareCodeUnits(r.storyId, g.first) < 0) {
+                g.first = r.storyId;
+                g.change = text;
+            }
+        }
+    }
+    // Collected through a Map, emitted through a sort: insertion order never
+    // reaches the report.
+    const groups = [];
+    for (const [signature, g] of bySignature) {
+        if (g.ids.length < 2)
+            continue;
+        const storyIds = [...g.ids].sort(compareCodeUnits);
+        groups.push({
+            signature,
+            summary: `${g.change} — ${storyIds.length} stories`,
+            storyIds,
+        });
+    }
+    return groups.sort((x, y) => y.storyIds.length - x.storyIds.length || compareCodeUnits(x.signature, y.signature));
+}
+//# sourceMappingURL=groups.js.map

package/dist/run/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../src/run/groups.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,4EAA4E;AAC5E,0EAA0E;AAC1E,yEAAyE;AACzE,uCAAuC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,MAAM,WAAW,GAAG,IAAI,GAAG,EAA4D,CAAC;IACxF,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,+DAA+D;QAC/D,iEAAiE;QACjE,6DAA6D;QAC7D,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,CAAC,UAAU,KAAK,CAAC;YAAE,SAAS;QACpF,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC;QACpD,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAC;QAC/B,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,CAAC,CAAC;YACJ,WAAW,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;aAC9E,CAAC;YACJ,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACtB,kEAAkE;YAClE,sEAAsE;YACtE,IAAI,gBAAgB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC;gBACpB,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,yEAAyE;IACzE,sBAAsB;IACtB,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC;QACzC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QAC/B,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACnD,MAAM,CAAC,IAAI,CAAC;YACV,SAAS;YACT,OAAO,EAAE,GAAG,CAAC,CAAC,MAAM,MAAM,QAAQ,CAAC,MAAM,UAAU;YACnD,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CACtF,CAAC;AACJ,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

@@ -1,7 +1,9 @@
-import type { Browser } from 'playwright';
+import type { Browser } from '../browser/browser.js';
 import type { Platform } from '../platform.js';
-import type { BaselineStore, DiffStatus, ProjectConfig, RunReport, StoryManifest, Viewport } from '../types.js';
+import type { BaselineStore, DiffStatus, ProjectConfig, RunReport, StoryManifest, StructureSnapshot, Viewport } from '../types.js';
 import { type AncestryCheck } from '../baseline/status.js';
+import { type Phases } from './phases.js';
+import type { CauseIndex } from '../analysis/cause.js';
 export declare const DEFAULT_VIEWPORT: Viewport;
 export interface RunOptions {
     browser: Browser;
@@ -20,11 +22,17 @@ 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;
+    /** From `jux run --since`: consulted only for a story that failed. */
+    cause?: CauseIndex;
 }
 export interface RunArtifact {
     storyId: string;
     status: DiffStatus;
     current: Buffer;
     diff?: Buffer;
+    structure?: StructureSnapshot;
 }
 export declare function runCapture(opts: RunOptions): Promise<RunReport>;

package/dist/run/run.js

@@ -4,15 +4,23 @@
 // 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 { decodeStructure } from '../capture/structure.js';
+import { structuralDiff } from '../diff/structural.js';
+import { compareCodeUnits } from '../diff/structural/deltas.js';
+import { computeGroups } from './groups.js';
+import { diffImages, resolveThreshold, resolveMinDiffPercent, } from '../diff/diff.js';
+import { phases } from './phases.js';
+import { shellQuote } from '../shell-quote.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 +32,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,23 +60,35 @@ 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 and cause tracing happen inside the loop; subtract both to
+    // leave capture alone.
+    p.add('capture', Date.now() - captureStarted - (p.timings.diff ?? 0) - (p.timings.cause ?? 0));
     const summary = tally(results);
+    // Code-unit order: the report is byte-stable across machines, and
+    // localeCompare is not.
+    results.sort((a, b) => compareCodeUnits(a.storyId, b.storyId));
+    const groups = computeGroups(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)),
+        results,
         summary,
+        ...(groups.length > 0 ? { groups } : {}),
         durationMs: Date.now() - started,
         startedAt: startedAt.toISOString(),
     };
 }
 /** 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,38 +97,102 @@ 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
     // or nothing to compare against.
     if (status !== 'fail') {
-        await opts.onArtifact?.({ storyId: story.storyId, status, current: snapshot.image });
+        await opts.onArtifact?.({
+            storyId: story.storyId,
+            status,
+            current: snapshot.image,
+            structure: snapshot.structure,
+        });
         return base;
     }
     const baseline = await opts.store.get(story.storyId);
     if (!baseline) {
         // The manifest claimed a baseline the store can't produce.
-        await opts.onArtifact?.({ storyId: story.storyId, status, current: snapshot.image });
+        await opts.onArtifact?.({
+            storyId: story.storyId,
+            status,
+            current: snapshot.image,
+            structure: snapshot.structure,
+        });
         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,
         current: snapshot.image,
         diff: diff.diffImage,
+        structure: snapshot.structure,
     });
+    // Structure explains the failure after the pixels have decided it. The
+    // baseline sidecar is read only here, so a green run never touches one. A
+    // manifest hash is not a file: read the store, and treat anything
+    // unreadable as absent. This code runs only on a hash mismatch.
+    const structural = await tryStructural(opts, story, snapshot, diff, p);
     return {
         ...base,
         mismatchPixels: diff.mismatchPixels,
         mismatchPercent: diff.mismatchPercent,
         changedRegions: diff.changedRegions,
         error: diff.dimensionMismatch ? 'viewport size changed since baseline' : undefined,
+        ...(structural ? { structural } : {}),
     };
 }
+/** A sidecar that is absent or unreadable is simply no baseline structure. */
+async function readBaselineStructure(store, storyId) {
+    try {
+        const gz = store.getStructure ? await store.getStructure(storyId) : null;
+        return gz ? decodeStructure(gz) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Structure explains a failure, never decides one, so nothing in here may
+ *  fail the story: a missing, corrupt or malformed sidecar, a cause index
+ *  that throws, or a bug in the diff, yields no verdict (or one without a
+ *  cause) and the pixel result stands. */
+async function tryStructural(opts, story, snapshot, pixels, p) {
+    if (!snapshot.structure)
+        return undefined;
+    let cause;
+    if (opts.cause) {
+        try {
+            cause = await p.time('cause', () => opts.cause.causeFor(story.componentPath));
+        }
+        catch {
+            cause = undefined;
+        }
+    }
+    try {
+        return structuralDiff({
+            baseline: await readBaselineStructure(opts.store, story.storyId),
+            current: snapshot.structure,
+            imagesIdentical: false,
+            pixels,
+            escalate: { command: `jux handoff ${shellQuote(story.storyId)}` },
+            ...(cause ? { cause } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
 function tally(results) {
     const summary = {
         pass: 0,

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":"AAAA,oEAAoE;AACpE,EAAE;AACF,gFAAgF;AAChF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AAGrE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAc/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAsB,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACL,UAAU,EAEV,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,MAAM,EAAe,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAa,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAkCvE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAgB;IAC/C,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,IAAI,gBAAgB,CAAC;IAC3D,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE;QACrC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW;QACrC,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU;QACnC,QAAQ;QACR,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,4EAA4E;IAC5E,8EAA8E;IAC9E,sDAAsD;IACtD,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAElC,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QACjC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC;gBACX,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;gBAC9B,MAAM,EAAE,MAAM;gBACd,cAAc,EAAE,CAAC;gBACjB,eAAe,EAAE,CAAC;gBAClB,cAAc,EAAE,EAAE;gBAClB,UAAU,EAAE,CAAC;aACd,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACvC,OAAO,CAAC,IAAI,CAAC;gBACX,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;gBAC9B,MAAM,EAAE,MAAM;gBACd,cAAc,EAAE,CAAC;gBACjB,eAAe,EAAE,CAAC;gBAClB,cAAc,EAAE,EAAE;gBAClB,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,IAAI,8BAA8B;gBAC/D,UAAU,EAAE,CAAC;aACd,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,qEAAqE;IACrE,uBAAuB;IACvB,CAAC,CAAC,GAAG,CACH,SAAS,EACT,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAC7E,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,kEAAkE;IAClE,wBAAwB;IACxB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,yEAAyE;QACzE,wEAAwE;QACxE,wCAAwC;QACxC,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAC7B,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;QAClC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO;QACP,OAAO;QACP,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;QAChC,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE;KACnC,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,KAAK,UAAU,KAAK,CAClB,QAAkB,EAClB,KAAoB,EACpB,QAA4D,EAC5D,IAAgB,EAChB,CAAS;IAET,MAAM,cAAc,GAAG,aAAa,CAClC,KAAK,CAAC,OAAO,EACb,QAAQ,CAAC,KAAK,EACd,QAAQ,EACR,IAAI,CAAC,QAAQ,CACd,CAAC;IACF,MAAM,MAAM,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC;IAE5C,MAAM,IAAI,GAAe;QACvB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM;QACN,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,CAAC;QAClB,cAAc,EAAE,EAAE;QAClB,yEAAyE;QACzE,0EAA0E;QAC1E,iDAAiD;QACjD,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;IAEF,4EAA4E;IAC5E,iCAAiC;IACjC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,MAAM;YACN,OAAO,EAAE,QAAQ,CAAC,KAAK;YACvB,SAAS,EAAE,QAAQ,CAAC,SAAS;SAC9B,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,2DAA2D;QAC3D,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,MAAM;YACN,OAAO,EAAE,QAAQ,CAAC,KAAK;YACvB,SAAS,EAAE,QAAQ,CAAC,SAAS;SAC9B,CAAC,CAAC;QACH,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;IAC3D,CAAC;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CACrC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE;QACnC,SAAS,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;QACtD,cAAc,EAAE,qBAAqB,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;KACjE,CAAC,CACH,CAAC;IAEF,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM;QACN,OAAO,EAAE,QAAQ,CAAC,KAAK;QACvB,IAAI,EAAE,IAAI,CAAC,SAAS;QACpB,SAAS,EAAE,QAAQ,CAAC,SAAS;KAC9B,CAAC,CAAC;IAEH,uEAAuE;IACvE,0EAA0E;IAC1E,kEAAkE;IAClE,gEAAgE;IAChE,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEvE,OAAO;QACL,GAAG,IAAI;QACP,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,KAAK,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC,SAAS;QAClF,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,KAAK,UAAU,qBAAqB,CAClC,KAAoB,EACpB,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACzE,OAAO,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;0CAG0C;AAC1C,KAAK,UAAU,aAAa,CAC1B,IAAgB,EAChB,KAAoB,EACpB,QAAkB,EAClB,MAAgE,EAChE,CAAS;IAET,IAAI,CAAC,QAAQ,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAA8D,CAAC;IACnE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;QACjF,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,cAAc,CAAC;YACpB,QAAQ,EAAE,MAAM,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YAChE,OAAO,EAAE,QAAQ,CAAC,SAAS;YAC3B,eAAe,EAAE,KAAK;YACtB,MAAM;YACN,QAAQ,EAAE,EAAE,OAAO,EAAE,eAAe,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE;YACjE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,KAAK,CAAC,OAAqB;IAClC,MAAM,OAAO,GAA+B;QAC1C,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,CAAC;QACP,GAAG,EAAE,CAAC;QACN,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,CAAC;KACR,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IAC7C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/shell-quote.d.ts

@@ -0,0 +1,2 @@
+/** Single-quote a value for a POSIX shell unless it is plainly safe. */
+export declare function shellQuote(v: string): string;

package/dist/shell-quote.js

@@ -0,0 +1,10 @@
+// Every hint that prints a command prints one an agent can paste. A snap
+// name with a space (`jux diff 'a b' x`) printed bare made the suggested
+// `jux snap <url> --as a b` a different command. In core so the verdict's
+// `escalate.command` and the CLI's hints share one implementation.
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/** Single-quote a value for a POSIX shell unless it is plainly safe. */
+export function shellQuote(v) {
+    return SHELL_SAFE.test(v) ? v : `'${v.replaceAll("'", "'\\''")}'`;
+}
+//# sourceMappingURL=shell-quote.js.map

package/dist/shell-quote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-quote.js","sourceRoot":"","sources":["../src/shell-quote.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,yEAAyE;AACzE,0EAA0E;AAC1E,mEAAmE;AAEnE,MAAM,UAAU,GAAG,0BAA0B,CAAC;AAE9C,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AACpE,CAAC"}