@juxtapose/core 0.4.0 → 0.5.0

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/run.d.ts

@@ -1,8 +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;
@@ -24,11 +25,14 @@ export interface RunOptions {
     /** 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

@@ -7,8 +7,13 @@
 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();
@@ -57,9 +62,14 @@ export async function runCapture(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));
+    // 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,
@@ -70,8 +80,9 @@ export async function runCapture(opts) {
         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(),
     };
@@ -95,13 +106,23 @@ async function judge(snapshot, story, manifest, opts, p) {
     // 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' };
     }
     // Counted as well as timed: under a byte-exact hash the number of diffs is
@@ -116,15 +137,62 @@ async function judge(snapshot, story, manifest, opts, p) {
         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":"AAAA,oEAAoE;AACpE,EAAE;AACF,gFAAgF;AAChF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AAGrE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAY/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAsB,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,MAAM,EAAe,MAAM,aAAa,CAAC;AAElD,MAAM,CAAC,MAAM,gBAAgB,GAAa,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AA+BvE,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,0EAA0E;IAC1E,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAE/B,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,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACnE,OAAO;QACP,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,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;QACrF,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,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;QACrF,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;KACrB,CAAC,CAAC;IAEH,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;KACnF,CAAC;AACJ,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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"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"}

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"}

package/dist/types.d.ts

@@ -52,6 +52,49 @@ export interface Snapshot {
     capturedAt: string;
     /** Wall time for this story's capture, ms. */
     durationMs: number;
+    /** Visible elements and their styles, from the same frame as `image`.
+     *  Absent when structure capture failed or was disabled — it explains a
+     *  failure, it never decides one. */
+    structure?: StructureSnapshot;
+}
+export interface StructureRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface StructureElement {
+    /** tag + (#id | [data-testid] | :nth-of-type) chain from <html>. */
+    path: string;
+    /** Index of the nearest kept ancestor in `elements`, null at the root. */
+    parent: number | null;
+    tag: string;
+    id?: string;
+    testId?: string;
+    classes?: string[];
+    role?: string;
+    name?: string;
+    text?: string;
+    src?: string;
+    rect: StructureRect;
+    paintOrder: number;
+    /** Compact: see effectiveStyle() in capture/structure.ts. */
+    styles: Record<string, string>;
+}
+export interface StructureSnapshot {
+    schema: 'juxtapose.structure/v1';
+    viewport: Viewport;
+    /** sha256 of the canonical JSON of `elements`. Equal ⇒ identical structure
+     *  and styles, so a pixel difference is render drift. */
+    structureHash: string;
+    /** Full document height, from CDP. Greater than viewport.height means part
+     *  of the page was never captured — PR (b)'s `below-fold` flag reads this. */
+    contentHeight: number;
+    elements: StructureElement[];
+    truncated?: {
+        kept: number;
+        total: number;
+    };
 }
 export interface ChangedRegion {
     x: number;
@@ -59,6 +102,126 @@ export interface ChangedRegion {
     width: number;
     height: number;
 }
+/** One changed fact between two structure snapshots. `el` is a short human
+ *  label (`button[name="Save"]`, `div#row-1`, `div.card`, or a trimmed path). */
+export type Delta = {
+    kind: 'text';
+    el: string;
+    from: string;
+    to: string;
+} | {
+    kind: 'style';
+    el: string;
+    prop: string;
+    from: string;
+    to: string;
+} | {
+    kind: 'attr';
+    el: string;
+    attr: 'src' | 'role' | 'name';
+    from: string;
+    to: string;
+} | {
+    kind: 'added';
+    el: string;
+    rect: StructureRect;
+} | {
+    kind: 'removed';
+    el: string;
+    rect: StructureRect;
+} | {
+    kind: 'moved';
+    el: string;
+    dx: number;
+    dy: number;
+} | {
+    kind: 'resized';
+    el: string;
+    dw: number;
+    dh: number;
+}
+/** ≥3 contiguous elements after `after` moved by the same (dx, dy). */
+ | {
+    kind: 'shift';
+    after: string;
+    dx: number;
+    dy: number;
+    count: number;
+};
+export type Classification = 'identical' | 'render-drift' | 'dimension-change' | 'element-added' | 'element-removed' | 'reflow' | 'geometry' | 'text-only' | 'style-only' | 'attr-only' | 'mixed' | 'unknown';
+/** Sub-tags of `style-only`, so "colour tweak" and "spacing change" read
+ *  differently at a glance. */
+export type StyleTag = 'color' | 'typography' | 'spacing' | 'border' | 'effects';
+export type Flag = 'element-removed' | 'text-changed' | 'large-reflow' | 'unexplained-pixels'
+/** The images differ but the pixel diff marked nothing: the change is below
+ *  its tolerance, and the structural deltas are the change. */
+ | 'sub-threshold' | 'structure-truncated' | 'no-baseline-structure' | 'no-current-structure'
+/** Either side's content is taller than the viewport: changes below the
+ *  fold are invisible to both pixels and structure. */
+ | 'below-fold';
+export type CauseKind = 
+/** At least one changed file is in the story's import closure. */
+'in-closure'
+/** A changed file reaches every story: a root lockfile or a platform config dir. */
+ | 'config'
+/** The closure was traced and no changed file is in it: the strongest
+ *  "this is not your code" the tool can give, especially beside render-drift. */
+ | 'none-in-closure'
+/** No --since, no manifest, git failed, or the story is not in the graph. */
+ | 'unknown';
+/** Why this story changed: the cheap link only (story → import closure →
+ *  changed files). Matched CSS rules and source lines are later rows. */
+export interface Cause {
+    kind: CauseKind;
+    /** At most 5, nearest first; posix paths relative to the project root. */
+    files: Array<{
+        path: string;
+        distance: number;
+    }>;
+    /** `in-closure` only: the closure was not fully traced (a bundled chunk
+     *  with no src, or a changed file the manifest never names), so the cause
+     *  may be a file not listed. Absent, never false, when the trace was full. */
+    partial?: true;
+}
+/** Tier-0: what changed, in a few hundred characters, with whether it
+ *  explains every changed pixel. The whole output of `jux diff`. */
+export interface StructuralVerdict {
+    schema: 'juxtapose.verdict/v1';
+    classification: Classification;
+    /** Empty unless classification is `style-only` or `mixed`. */
+    styleTags: StyleTag[];
+    /** Templated, deterministic, ≤ 300 chars. */
+    summary: string;
+    /** The change with every element reduced to role|tag and no per-story
+     *  tail, ≤ 160 chars: what stories sharing a `signature` have in common.
+     *  Absent when there are no deltas. */
+    change?: string;
+    /** At most 20, and only the prefix that keeps the whole verdict within
+     *  1,500 chars; `deltaCount` is the total. */
+    deltas: Delta[];
+    /** Counted after suppression: a child that only followed its parent's
+     *  move or resize, and a style inherited from where it originated, are not
+     *  deltas, nor is an added/removed element hidden by the other side's
+     *  truncation; a shift run counts once. */
+    deltaCount: number;
+    /** Fraction of changed-region area intersecting some delta's element. */
+    coverage: number;
+    /** ≥ 0.98 | ≥ 0.5 | below. */
+    explained: 'full' | 'partial' | 'none';
+    /** The prefix that fits the 1,500-char verdict; `coverage` covers all. */
+    unexplainedRegions: ChangedRegion[];
+    flags: Flag[];
+    /** Present only in `jux run --since`; absent from `jux diff`. */
+    cause?: Cause;
+    /** sha256 over the classification and the delta set with elements
+     *  abstracted to role|tag, so two pages with the same change share one.
+     *  Over the same post-suppression facts `deltaCount` counts. */
+    signature: string;
+    /** The exact command for tier-3 pixels. */
+    escalate: {
+        command: string;
+    };
+}
 export type DiffStatus = 'pass' | 'fail' | 'new' | 'stale' | 'skip';
 export interface DiffResult {
     storyId: string;
@@ -76,8 +239,22 @@ export interface DiffResult {
     viewport?: Viewport;
     /** Set when the capture or diff threw. status is 'fail' in that case. */
     error?: string;
+    /** Tier-0 explanation of a failure. Present only when status is 'fail' and
+     *  the current capture produced a structure; never consulted on pass. */
+    structural?: StructuralVerdict;
     durationMs: number;
 }
+/** One change seen on several stories: the same signature on ≥2 failing
+ *  results. Listing them is what turns 40 handoffs into one decision;
+ *  approving by group is a later row. */
+export interface RunGroup {
+    signature: string;
+    /** The shared change, as `<change> — N stories`: the verdict's `change`
+     *  (elements as role|tag), not one page's labelled summary. */
+    summary: string;
+    /** ≥ 2, code-unit sorted. */
+    storyIds: string[];
+}
 export interface RunReport {
     runId: string;
     branch: string;
@@ -90,6 +267,8 @@ export interface RunReport {
     totalCount: number;
     results: DiffResult[];
     summary: Record<DiffStatus, number>;
+    /** Present when at least one signature is shared by ≥2 failing stories. */
+    groups?: RunGroup[];
     durationMs: number;
     startedAt: string;
 }
@@ -114,6 +293,9 @@ export interface ApprovalMeta {
     /** Absent on entries approved before this was recorded. Absent must not read
      *  as "matches": an unknown origin is unknown, not current. */
     env?: CaptureEnv;
+    /** structureHash of the approved capture's sidecar. Absent when the capture
+     *  had no structure, or was approved before sidecars existed. */
+    structureHash?: string;
 }
 export interface BaselineEntry extends ApprovalMeta {
     /** sha256 of the baseline image bytes. Detects drift between manifest
@@ -126,10 +308,20 @@ export interface BaselineManifest {
     version: 1;
     baselines: Record<string, BaselineEntry>;
 }
+/** One page for the `urls` platform. */
+export interface UrlEntry {
+    /** Stable id; used as the story id and for file names. */
+    id: string;
+    /** Absolute, or relative to --origin. */
+    url: string;
+    params?: StoryParams;
+}
 /** Project config, from juxtapose.config.{ts,js,json} or package.json#juxtapose. */
 export interface ProjectConfig {
     /** Which workbench. Autodetected when omitted. */
-    platform?: 'storybook' | 'ladle';
+    platform?: 'storybook' | 'ladle' | 'urls';
+    /** Pages to capture when `platform` is 'urls'. */
+    urls?: UrlEntry[];
     /** Where the built static workbench lives. */
     buildDir?: string;
     /** Capture against an already-running dev server instead of building. */
@@ -167,4 +359,10 @@ export interface BaselineStore {
     remove(storyId: string): Promise<void>;
     readManifest(): Promise<BaselineManifest>;
     writeManifest(manifest: BaselineManifest): Promise<void>;
+    /** Optional: stores that can hold the gzipped structure sidecar. */
+    putStructure?(storyId: string, gz: Buffer): Promise<void>;
+    getStructure?(storyId: string): Promise<Buffer | null>;
+    /** Optional: where the baseline image lives on disk, for stores that keep
+     *  one. The handoff hands it to `jux diff … --crops`. */
+    locate?(storyId: string): string | undefined;
 }

package/dist/url-platform.d.ts

@@ -1,8 +1,8 @@
-import type { Page } from 'playwright';
+import type { Page } from './browser/page.js';
 /**
  * Build a `showStory` implementation from a URL builder.
  *
- * Note `waitUntil: 'load'` rather than `networkidle`: the platform's own
+ * `page.goto` resolves on the main frame's `load`, not network idle: the platform's own
  * render signal and core's settle pipeline decide when the page is actually
  * ready. Waiting for network idle here would be both slower and less reliable
  * — a story that polls would never satisfy it.

package/dist/url-platform.js

@@ -9,14 +9,14 @@
 /**
  * Build a `showStory` implementation from a URL builder.
  *
- * Note `waitUntil: 'load'` rather than `networkidle`: the platform's own
+ * `page.goto` resolves on the main frame's `load`, not network idle: the platform's own
  * render signal and core's settle pipeline decide when the page is actually
  * ready. Waiting for network idle here would be both slower and less reliable
  * — a story that polls would never satisfy it.
  */
 export function navigateToStory(storyUrl) {
     return async (page, storyId, baseUrl) => {
-        await page.goto(storyUrl(baseUrl, storyId), { waitUntil: 'load' });
+        await page.goto(storyUrl(baseUrl, storyId));
     };
 }
 //# sourceMappingURL=url-platform.js.map

package/dist/url-platform.js.map

@@ -1 +1 @@
-{"version":3,"file":"url-platform.js","sourceRoot":"","sources":["../src/url-platform.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,8CAA8C;AAC9C,EAAE;AACF,uEAAuE;AACvE,oEAAoE;AAIpE;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAsD;IAEtD,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QACtC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"url-platform.js","sourceRoot":"","sources":["../src/url-platform.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,8CAA8C;AAC9C,EAAE;AACF,uEAAuE;AACvE,oEAAoE;AAIpE;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAsD;IAEtD,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QACtC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@juxtapose/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Platform-agnostic capture, diff, baseline and analysis core for juxtapose.",
   "keywords": [
     "visual-regression",
     "screenshot-testing",
-    "playwright",
+    "cdp",
     "visual-testing",
     "pixelmatch"
   ],
@@ -15,6 +15,9 @@
     "access": "public"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=22.2.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -29,14 +32,6 @@
     "pixelmatch": "^6.0.0",
     "sharp": "^0.35.3"
   },
-  "peerDependencies": {
-    "playwright": "^1.48.0"
-  },
-  "peerDependenciesMeta": {
-    "playwright": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@types/pixelmatch": "^5.2.6"
   },