@juxtapose/core 0.2.0 → 0.5.0

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;
@@ -44,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;
@@ -51,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;
@@ -59,26 +230,72 @@ 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;
+    /** 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;
     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;
     results: DiffResult[];
     summary: Record<DiffStatus, number>;
+    /** Present when at least one signature is shared by ≥2 failing stories. */
+    groups?: RunGroup[];
     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;
+    /** 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
@@ -91,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. */
@@ -110,8 +337,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 = {
@@ -134,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,16 +1,28 @@
 {
   "name": "@juxtapose/core",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Platform-agnostic capture, diff, baseline and analysis core for juxtapose.",
+  "keywords": [
+    "visual-regression",
+    "screenshot-testing",
+    "cdp",
+    "visual-testing",
+    "pixelmatch"
+  ],
+  "homepage": "https://github.com/juxtapose-dev/juxtapose/tree/main/packages/core#readme",
   "publishConfig": {
     "access": "public"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=22.2.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./format": "./dist/report/format.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -18,15 +30,7 @@
   ],
   "dependencies": {
     "pixelmatch": "^6.0.0",
-    "sharp": "^0.33.5"
-  },
-  "peerDependencies": {
-    "playwright": "^1.48.0"
-  },
-  "peerDependenciesMeta": {
-    "playwright": {
-      "optional": true
-    }
+    "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@types/pixelmatch": "^5.2.6"