@juxtapose/core 0.2.0

package/dist/diff/diff.d.ts

@@ -0,0 +1,25 @@
+import type { ChangedRegion, StoryParams, ProjectConfig } from '../types.js';
+export interface DiffOutput {
+    mismatchPixels: number;
+    mismatchPercent: number;
+    changedRegions: ChangedRegion[];
+    /** WebP overlay marking changed pixels. Absent when nothing changed. */
+    diffImage?: Buffer;
+    /** True when dimensions differ — no pixel comparison was possible. */
+    dimensionMismatch: boolean;
+}
+/**
+ * Compare two encoded images.
+ *
+ * `threshold` is pixelmatch's YIQ colour-distance tolerance (0-1), not a
+ * pixel count. `includeAA: false` makes pixelmatch detect and exclude
+ * antialiased pixels, which is what keeps sub-pixel text rendering from
+ * dominating every diff.
+ */
+export declare function diffImages(baseline: Buffer, current: Buffer, opts?: {
+    threshold?: number;
+    minDiffPercent?: number;
+}): Promise<DiffOutput>;
+/** Story params override project config override the built-in default. */
+export declare function resolveThreshold(params: StoryParams | undefined, config: ProjectConfig | undefined): number;
+export declare function resolveMinDiffPercent(params: StoryParams | undefined, config: ProjectConfig | undefined): number;

package/dist/diff/diff.js

@@ -0,0 +1,86 @@
+// Pixel diff — the COLD path.
+//
+// This only runs for stories that already failed the hash check in
+// baseline/status.ts. It decides nothing; it exists to turn "these bytes
+// differ" into something a reviewer or an agent can act on.
+//
+// Consequence worth keeping in mind while optimizing: on a green run this
+// module never executes. Effort spent here pays off only in proportion to how
+// broken the run already is.
+import sharp from 'sharp';
+import pixelmatch from 'pixelmatch';
+import { computeChangedRegions } from './regions.js';
+const DEFAULT_THRESHOLD = 0.1;
+const DEFAULT_MIN_DIFF_PERCENT = 0;
+/**
+ * Compare two encoded images.
+ *
+ * `threshold` is pixelmatch's YIQ colour-distance tolerance (0-1), not a
+ * pixel count. `includeAA: false` makes pixelmatch detect and exclude
+ * antialiased pixels, which is what keeps sub-pixel text rendering from
+ * dominating every diff.
+ */
+export async function diffImages(baseline, current, opts = {}) {
+    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    const minDiffPercent = opts.minDiffPercent ?? DEFAULT_MIN_DIFF_PERCENT;
+    // sharp sniffs the format, so baselines can be WebP and current can be PNG
+    // without an explicit conversion step.
+    const [a, b] = await Promise.all([
+        sharp(baseline).ensureAlpha().raw().toBuffer({ resolveWithObject: true }),
+        sharp(current).ensureAlpha().raw().toBuffer({ resolveWithObject: true }),
+    ]);
+    if (a.info.width !== b.info.width || a.info.height !== b.info.height) {
+        // No meaningful pixel comparison exists across different dimensions.
+        // Report it as total change rather than inventing a number.
+        return {
+            mismatchPixels: 0,
+            mismatchPercent: 100,
+            changedRegions: [],
+            dimensionMismatch: true,
+        };
+    }
+    const { width, height } = b.info;
+    const diff = Buffer.alloc(width * height * 4);
+    const mismatchPixels = pixelmatch(a.data, b.data, diff, width, height, {
+        threshold,
+        includeAA: false,
+    });
+    const mismatchPercent = (mismatchPixels / (width * height)) * 100;
+    if (mismatchPixels === 0 || mismatchPercent < minDiffPercent) {
+        return {
+            mismatchPixels,
+            mismatchPercent,
+            changedRegions: [],
+            dimensionMismatch: false,
+        };
+    }
+    // Lossless: the overlay is a sparse mask of flat colour, which lossless
+    // compresses better than lossy anyway, and blurring the marked pixels would
+    // defeat the point of the image.
+    const diffImage = await sharp(diff, { raw: { width, height, channels: 4 } })
+        .webp({ lossless: true, effort: 0 })
+        .toBuffer();
+    return {
+        mismatchPixels,
+        mismatchPercent,
+        changedRegions: computeChangedRegions(diff, width, height),
+        diffImage,
+        dimensionMismatch: false,
+    };
+}
+/** Story params override project config override the built-in default. */
+export function resolveThreshold(params, config) {
+    return clamp(firstFinite(params?.threshold, config?.threshold, DEFAULT_THRESHOLD), 0, 1);
+}
+export function resolveMinDiffPercent(params, config) {
+    return clamp(firstFinite(params?.minDiffPercent, config?.minDiffPercent, DEFAULT_MIN_DIFF_PERCENT), 0, 100);
+}
+function firstFinite(...values) {
+    for (const v of values) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return 0;
+}
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+//# sourceMappingURL=diff.js.map

package/dist/diff/diff.js.map

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

package/dist/diff/regions.d.ts

@@ -0,0 +1,8 @@
+import type { ChangedRegion } from '../types.js';
+/**
+ * Extract merged bounding boxes of changed pixel clusters.
+ *
+ * Boxes within `gap` pixels of each other merge, so antialiased edges and
+ * inter-letter spacing don't fragment one logical change into many.
+ */
+export declare function computeChangedRegions(diff: Buffer, width: number, height: number, gap?: number): ChangedRegion[];

package/dist/diff/regions.js

@@ -0,0 +1,90 @@
+// Turn a pixelmatch diff buffer into a handful of bounding boxes.
+//
+// Why: a one-word text change produces hundreds of disconnected changed pixels.
+// Reporting those raw is useless to a human and to an agent. Merging them into
+// gap-tolerant boxes turns "412 changed pixels" into "one region, at the
+// heading" — which is reviewable.
+const DEFAULT_GAP = 8;
+/**
+ * Is this pixel one pixelmatch marked as changed?
+ *
+ * Subtle and worth stating, because getting it wrong is silent: pixelmatch
+ * writes the WHOLE frame into the diff buffer, not just the differences.
+ * Unchanged pixels come back as the faded original at full alpha; changed
+ * pixels are painted in its diff colour, red by default.
+ *
+ * So testing `alpha > 0` matches every pixel in the image and collapses every
+ * report into one full-viewport region — which is exactly the bug this
+ * replaced. Test for the red marking instead.
+ */
+function isChanged(diff, offset) {
+    return diff[offset] > 200 && diff[offset + 1] < 100 && diff[offset + 2] < 100;
+}
+/**
+ * Extract merged bounding boxes of changed pixel clusters.
+ *
+ * Boxes within `gap` pixels of each other merge, so antialiased edges and
+ * inter-letter spacing don't fragment one logical change into many.
+ */
+export function computeChangedRegions(diff, width, height, gap = DEFAULT_GAP) {
+    // Pass 1: per-row runs of changed pixels. Rows are cheap to scan and
+    // collapse most of the pixel count immediately.
+    const spans = [];
+    for (let y = 0; y < height; y++) {
+        let start = -1;
+        for (let x = 0; x <= width; x++) {
+            const changed = x < width && isChanged(diff, (y * width + x) * 4);
+            if (changed && start === -1)
+                start = x;
+            else if (!changed && start !== -1) {
+                spans.push({ y, x1: start, x2: x - 1 });
+                start = -1;
+            }
+        }
+    }
+    // Pass 2: merge spans into boxes.
+    //
+    // Unlike a naive greedy merge, a span that touches several existing boxes
+    // must merge *all* of them together — otherwise a change shaped like a "U"
+    // reports as two regions that a later span should have joined.
+    const boxes = [];
+    for (const span of spans) {
+        const touched = [];
+        for (let i = 0; i < boxes.length; i++) {
+            if (overlaps(span, boxes[i], gap))
+                touched.push(i);
+        }
+        if (touched.length === 0) {
+            boxes.push({ x1: span.x1, y1: span.y, x2: span.x2, y2: span.y });
+            continue;
+        }
+        const target = boxes[touched[0]];
+        target.x1 = Math.min(target.x1, span.x1);
+        target.x2 = Math.max(target.x2, span.x2);
+        target.y1 = Math.min(target.y1, span.y);
+        target.y2 = Math.max(target.y2, span.y);
+        // Fold any other boxes this span bridged into the first, back-to-front so
+        // the splices don't shift indices we still need.
+        for (let i = touched.length - 1; i >= 1; i--) {
+            const other = boxes[touched[i]];
+            target.x1 = Math.min(target.x1, other.x1);
+            target.x2 = Math.max(target.x2, other.x2);
+            target.y1 = Math.min(target.y1, other.y1);
+            target.y2 = Math.max(target.y2, other.y2);
+            boxes.splice(touched[i], 1);
+        }
+    }
+    return boxes.map((b) => ({
+        x: b.x1,
+        y: b.y1,
+        width: b.x2 - b.x1 + 1,
+        height: b.y2 - b.y1 + 1,
+    }));
+}
+function overlaps(span, box, gap) {
+    return (span.y >= box.y1 - gap &&
+        span.y <= box.y2 + gap &&
+        span.x1 <= box.x2 + gap &&
+        span.x2 >= box.x1 - gap);
+}
+//# sourceMappingURL=regions.js.map

package/dist/diff/regions.js.map

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

package/dist/git/ancestry.d.ts

@@ -0,0 +1,5 @@
+import type { AncestryCheck } from '../baseline/status.js';
+export declare function createAncestryCheck(cwd: string): AncestryCheck;
+/** Ancestry check that passes everything. For non-git checkouts, where
+ *  staleness is unknowable and blocking on it would be wrong. */
+export declare const alwaysAncestor: AncestryCheck;

package/dist/git/ancestry.js

@@ -0,0 +1,43 @@
+// Git ancestry, memoized.
+//
+// `git merge-base --is-ancestor` forks a process at ~40ms. Most stories in a
+// run share a handful of baseline commits, so caching by commit takes this from
+// O(stories) forks to O(distinct commits) — roughly 30s to 50ms on a
+// 738-story suite. The memoization is not an optimization detail; without it
+// the stale check is unaffordable and would get dropped.
+import { execFileSync } from 'node:child_process';
+const SHA_RE = /^[0-9a-f]{40}$/i;
+export function createAncestryCheck(cwd) {
+    const cache = new Map();
+    return {
+        isAncestor(commit) {
+            // Sentinels like "unknown" predate proper commit tracking. Treat them as
+            // valid rather than marking every such baseline stale.
+            if (!SHA_RE.test(commit))
+                return true;
+            const hit = cache.get(commit);
+            if (hit !== undefined)
+                return hit;
+            let result;
+            try {
+                execFileSync('git', ['merge-base', '--is-ancestor', commit, 'HEAD'], {
+                    cwd,
+                    stdio: 'ignore',
+                });
+                result = true;
+            }
+            catch {
+                // Non-zero exit means "not an ancestor". It also means "unknown commit"
+                // — e.g. a shallow clone that lacks the object. Both should read as
+                // stale: we cannot prove the baseline is reachable from HEAD.
+                result = false;
+            }
+            cache.set(commit, result);
+            return result;
+        },
+    };
+}
+/** Ancestry check that passes everything. For non-git checkouts, where
+ *  staleness is unknowable and blocking on it would be wrong. */
+export const alwaysAncestor = { isAncestor: () => true };
+//# sourceMappingURL=ancestry.js.map

package/dist/git/ancestry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestry.js","sourceRoot":"","sources":["../../src/git/ancestry.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,qEAAqE;AACrE,6EAA6E;AAC7E,yDAAyD;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,MAAM,MAAM,GAAG,iBAAiB,CAAC;AAEjC,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEzC,OAAO;QACL,UAAU,CAAC,MAAc;YACvB,yEAAyE;YACzE,uDAAuD;YACvD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,OAAO,IAAI,CAAC;YAEtC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9B,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC;YAElC,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,YAAY,CAAC,KAAK,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;oBACnE,GAAG;oBACH,KAAK,EAAE,QAAQ;iBAChB,CAAC,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC;YAChB,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;gBACxE,oEAAoE;gBACpE,8DAA8D;gBAC9D,MAAM,GAAG,KAAK,CAAC;YACjB,CAAC;YAED,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC1B,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;iEACiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAkB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { StoryParams, Viewport, StoryManifest, Snapshot, ChangedRegion, DiffStatus, DiffResult, RunReport, ApprovalMeta, BaselineEntry, BaselineManifest, ProjectConfig, StorageConfig, BaselineStore, } from './types.js';
+export type { Platform, EnumerateTarget, SettleContext } from './platform.js';
+export { navigateToStory } from './url-platform.js';
+export { hashImage, resolveStatus, toDiffStatus, type BaselineStatus, type AncestryCheck, } from './baseline/status.js';
+export { GitBaselineStore, encodeStoryId } from './baseline/git-store.js';
+export { createAncestryCheck, alwaysAncestor } from './git/ancestry.js';
+export { armSettle, drain, waitForSelector, waitForPaint, FREEZE_ANIMATIONS_CSS, DOM_IDLE_MS, DOM_IDLE_TIMEOUT_MS, } from './capture/settle.js';
+export { captureStory, type CaptureDeps } from './capture/capture.js';
+export { deterministicLaunchOptions, DETERMINISTIC_CHROMIUM_ARGS, type LaunchOptions, } from './capture/launch.js';
+export { capturePool, DEFAULT_CONCURRENCY, type PoolOptions, type CaptureOutcome, } from './capture/pool.js';
+export { diffImages, resolveThreshold, resolveMinDiffPercent, type DiffOutput, } from './diff/diff.js';
+export { computeChangedRegions } from './diff/regions.js';
+export { resolveAffected, type AffectedOptions, type AffectedResult, } from './analysis/affected.js';
+export { runCapture, DEFAULT_VIEWPORT, type RunOptions, type RunArtifact, } from './run/run.js';
+export { buildHandoffPrompt, describeRegion, type HandoffPayload, } from './agent/handoff.js';
+export { buildComment, COMMENT_MARKER, type CommentOptions } from './report/comment.js';
+export { resolveGitHubContext, postComment, type GitHubContext, } from './report/github.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+export { navigateToStory } from './url-platform.js';
+export { hashImage, resolveStatus, toDiffStatus, } from './baseline/status.js';
+export { GitBaselineStore, encodeStoryId } from './baseline/git-store.js';
+export { createAncestryCheck, alwaysAncestor } from './git/ancestry.js';
+export { armSettle, drain, waitForSelector, waitForPaint, FREEZE_ANIMATIONS_CSS, DOM_IDLE_MS, DOM_IDLE_TIMEOUT_MS, } from './capture/settle.js';
+export { captureStory } from './capture/capture.js';
+export { deterministicLaunchOptions, DETERMINISTIC_CHROMIUM_ARGS, } from './capture/launch.js';
+export { capturePool, DEFAULT_CONCURRENCY, } from './capture/pool.js';
+export { diffImages, resolveThreshold, resolveMinDiffPercent, } from './diff/diff.js';
+export { computeChangedRegions } from './diff/regions.js';
+export { resolveAffected, } from './analysis/affected.js';
+export { runCapture, DEFAULT_VIEWPORT, } from './run/run.js';
+export { buildHandoffPrompt, describeRegion, } from './agent/handoff.js';
+export { buildComment, COMMENT_MARKER } from './report/comment.js';
+export { resolveGitHubContext, postComment, } from './report/github.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,SAAS,EACT,aAAa,EACb,YAAY,GAGb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EACL,SAAS,EACT,KAAK,EACL,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAoB,MAAM,sBAAsB,CAAC;AACtE,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,GAE5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,mBAAmB,GAGpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EACL,eAAe,GAGhB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,UAAU,EACV,gBAAgB,GAGjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,cAAc,GAEf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,cAAc,EAAuB,MAAM,qBAAqB,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,WAAW,GAEZ,MAAM,oBAAoB,CAAC"}

package/dist/platform.d.ts

@@ -0,0 +1,83 @@
+import type { Page } from 'playwright';
+import type { StoryManifest, StoryParams } from './types.js';
+export interface EnumerateTarget {
+    /** Built workbench directory, when capturing a static build. */
+    buildDir?: string;
+    /** Running dev-server origin, when capturing live. */
+    origin?: string;
+    /** Project root, for resolving story source paths to absolute. */
+    projectRoot: string;
+}
+export interface SettleContext {
+    story: StoryManifest;
+    params: StoryParams;
+    /** Max ms to wait for render-ready before giving up and screenshotting. */
+    timeoutMs: number;
+}
+export interface Platform {
+    readonly name: string;
+    /** True if this platform looks present at the target. Used for autodetection. */
+    detect(target: EnumerateTarget): Promise<boolean>;
+    /** Discover every capturable story. */
+    enumerate(target: EnumerateTarget): Promise<StoryManifest[]>;
+    /**
+     * Put this story on screen, from whatever state the page is in.
+     *
+     * The one operation every platform must provide, and deliberately phrased as
+     * an action rather than a URL. Most workbenches address a story by URL and
+     * implement this as a navigation — `showStory` in `url-platform.ts` builds
+     * exactly that. But Playwright's component-testing galleries have no
+     * per-story URL at all: every story lives at the same base URL and is
+     * rendered by calling `window.mount(storyId)`. Requiring a URL would have
+     * excluded them.
+     *
+     * Implementations must leave the page ready for `settle()` to run.
+     */
+    showStory(page: Page, storyId: string, baseUrl: string): Promise<void>;
+    /** Blank preview URL, for warming a page before any story is selected.
+     *  Prewarming here means the first real story doesn't pay for bundle
+     *  compile and service-worker registration. */
+    previewUrl(baseUrl: string): string;
+    /**
+     * URL that renders one story in isolation, when the platform has one.
+     *
+     * Optional because gallery-based platforms genuinely don't. Only used for
+     * reporting — linking a reviewer to a story — never for capture, which goes
+     * through `showStory`.
+     */
+    storyUrl?(baseUrl: string, storyId: string): string;
+    /**
+     * Block until the story has finished rendering.
+     *
+     * This is the platform's core responsibility and the thing that makes
+     * captures deterministic. Implementations should resolve on the platform's
+     * own render signal rather than a fixed sleep. Generic settling that applies
+     * to every platform — DOM quiescence, network drain, animation freezing —
+     * lives in core and runs after this resolves.
+     *
+     * Must not throw on timeout: resolve and let core screenshot anyway. A
+     * late-rendering story should produce a visible diff, not an error.
+     */
+    settle(page: Page, ctx: SettleContext): Promise<void>;
+    /**
+     * Switch a warm page to another story without a navigation.
+     *
+     * Optional, and purely an optimization — but a ~4x one, so implement it if
+     * the platform exposes any client-side story-switch channel. Return false
+     * if the switch could not be performed; the pool falls back to `goto`.
+     */
+    switchStory?(page: Page, storyId: string, ctx: SettleContext): Promise<boolean>;
+    /**
+     * Read per-story config from the live preview.
+     *
+     * Optional because not every platform hides parameters from its static
+     * index. Storybook does — it only serializes a whitelist — so reading the
+     * index alone silently drops per-story thresholds.
+     */
+    readLiveParams?(page: Page, storyId: string): Promise<StoryParams | undefined>;
+    /** Directories whose contents invalidate every story when changed
+     *  (`.storybook`, `.ladle`). Project-relative. */
+    readonly configDirs: readonly string[];
+    /** Globs identifying story files, for cache keys and change detection. */
+    readonly storyFileGlobs: readonly string[];
+}

package/dist/platform.js

@@ -0,0 +1,5 @@
+// The platform seam. Everything Storybook-specific in the original tool
+// reduces to the four operations below; Ladle and Histoire implement the same
+// four. `core` depends on this interface and never on a concrete platform.
+export {};
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,8EAA8E;AAC9E,2EAA2E"}

package/dist/report/comment.d.ts

@@ -0,0 +1,16 @@
+import type { RunReport } from '../types.js';
+/**
+ * Invisible marker identifying our own comment.
+ *
+ * This is what makes the reporter update rather than accumulate: on each run
+ * we list the PR's comments, find the one carrying this marker, and edit it.
+ * A PR with ten pushes ends up with one comment, not ten.
+ */
+export declare const COMMENT_MARKER = "<!-- juxtapose-bot -->";
+export interface CommentOptions {
+    report: RunReport;
+    /** Where to point someone who wants the images. Omitted when there is no
+     *  artifact to link to. */
+    artifactUrl?: string;
+}
+export declare function buildComment({ report, artifactUrl }: CommentOptions): string;

package/dist/report/comment.js

@@ -0,0 +1,99 @@
+// Build the PR comment body.
+//
+// A pure function, separate from posting it, so the formatting can be tested
+// without a network or a token — and so `jux run --json` consumers can render
+// the same summary elsewhere.
+/**
+ * Invisible marker identifying our own comment.
+ *
+ * This is what makes the reporter update rather than accumulate: on each run
+ * we list the PR's comments, find the one carrying this marker, and edit it.
+ * A PR with ten pushes ends up with one comment, not ten.
+ */
+export const COMMENT_MARKER = '<!-- juxtapose-bot -->';
+/** Stories that block a merge — anything a human or agent must judge. */
+function blocking(report) {
+    return report.results.filter((r) => r.status === 'fail' || r.status === 'new' || r.status === 'stale');
+}
+export function buildComment({ report, artifactUrl }) {
+    const s = report.summary;
+    const needsReview = blocking(report);
+    const lines = [COMMENT_MARKER, ''];
+    // Lead with the verdict. Someone scanning a PR should not have to parse a
+    // table to learn whether they need to do anything.
+    if (needsReview.length === 0) {
+        lines.push(`### Visual tests passed`, '');
+        lines.push(`${s.pass} ${s.pass === 1 ? 'story' : 'stories'} match their baselines.`);
+        if (s.skip > 0)
+            lines.push(`${s.skip} skipped.`);
+        lines.push('', footer(report, artifactUrl));
+        return lines.join('\n');
+    }
+    lines.push(`### Visual changes need review`, '');
+    lines.push('| | count |', '| --- | --- |');
+    if (s.pass > 0)
+        lines.push(`| pass | ${s.pass} |`);
+    if (s.fail > 0)
+        lines.push(`| **changed** | **${s.fail}** |`);
+    if (s.new > 0)
+        lines.push(`| **new** | **${s.new}** |`);
+    if (s.stale > 0)
+        lines.push(`| **stale** | **${s.stale}** |`);
+    if (s.skip > 0)
+        lines.push(`| skipped | ${s.skip} |`);
+    lines.push('');
+    // Open by default: the whole point is that a reviewer sees what changed
+    // without clicking. Collapsed only when the list is long enough to bury the
+    // rest of the PR conversation.
+    const open = needsReview.length <= 10 ? ' open' : '';
+    lines.push(`<details${open}>`, `<summary>${needsReview.length} ${needsReview.length === 1 ? 'story' : 'stories'}</summary>`, '');
+    lines.push('| story | status | changed |', '| --- | --- | --- |');
+    for (const r of needsReview.slice(0, MAX_ROWS)) {
+        lines.push(`| \`${r.storyId}\` | ${label(r.status)} | ${detail(r)} |`);
+    }
+    if (needsReview.length > MAX_ROWS) {
+        lines.push(`| …and ${needsReview.length - MAX_ROWS} more | | |`);
+    }
+    lines.push('', '</details>', '');
+    lines.push('To accept these changes:', '', '```bash', 'jux approve --all', '```', '');
+    lines.push(footer(report, artifactUrl));
+    return lines.join('\n');
+}
+/** GitHub comments have a size limit; a suite where everything changed should
+ *  not produce an unpostable comment. */
+const MAX_ROWS = 50;
+function label(status) {
+    switch (status) {
+        case 'fail':
+            return 'changed';
+        case 'new':
+            return 'no baseline';
+        case 'stale':
+            return 'stale baseline';
+        default:
+            return status;
+    }
+}
+function detail(r) {
+    if (r.error)
+        return r.error;
+    if (r.status !== 'fail')
+        return '—';
+    return formatPercent(r.mismatchPercent);
+}
+function footer(report, artifactUrl) {
+    const parts = [
+        `\`${report.commitSha.slice(0, 7)}\``,
+        `${report.capturedCount}/${report.totalCount} captured`,
+        `${(report.durationMs / 1000).toFixed(1)}s`,
+    ];
+    const meta = `<sub>juxtapose · ${parts.join(' · ')}</sub>`;
+    return artifactUrl ? `${meta}\n\n<sub>[Images and diffs](${artifactUrl})</sub>` : meta;
+}
+/** Never show "0.00%" next to the word "changed" — it reads as a tool bug. */
+function formatPercent(pct) {
+    if (pct >= 0.01)
+        return `${pct.toFixed(2)}%`;
+    return pct > 0 ? '<0.01%' : '0%';
+}
+//# sourceMappingURL=comment.js.map

package/dist/report/comment.js.map

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

package/dist/report/github.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Everything needed to post, read from the environment GitHub Actions
+ * provides. Absent outside Actions, which is the normal local case.
+ */
+export interface GitHubContext {
+    token: string;
+    /** `owner/repo` */
+    repository: string;
+    prNumber: number;
+    apiUrl: string;
+}
+/**
+ * Assemble the context from the workflow environment.
+ *
+ * Returns null when anything is missing — running locally, on a push rather
+ * than a pull request, or without a token. That is an ordinary state, not an
+ * error: reporting is a side effect, and a missing token should never fail a
+ * build that otherwise passed.
+ */
+export declare function resolveGitHubContext(env?: NodeJS.ProcessEnv): Promise<GitHubContext | null>;
+/**
+ * Create or update the juxtapose comment.
+ *
+ * Returns the comment's URL, or null if nothing was posted. Never throws: a
+ * reporting failure must not fail a build. The caller decides the exit code
+ * from the run itself, which is the thing that actually matters.
+ */
+export declare function postComment(ctx: GitHubContext, body: string): Promise<string | null>;