@juxtapose/core 0.2.0

package/dist/report/github.js

@@ -0,0 +1,118 @@
+// Post the run summary as a PR comment, updating rather than accumulating.
+//
+// Hand-rolled against the REST API instead of pulling in Octokit: this needs
+// three endpoints, and the CLI's install size is a real cost for a tool people
+// add to every project.
+import { readFile } from 'node:fs/promises';
+import { COMMENT_MARKER } from './comment.js';
+/**
+ * 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 async function resolveGitHubContext(env = process.env) {
+    const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    const repository = env.GITHUB_REPOSITORY;
+    if (!token || !repository)
+        return null;
+    const prNumber = await readPrNumber(env);
+    if (prNumber === null)
+        return null;
+    return {
+        token,
+        repository,
+        prNumber,
+        apiUrl: env.GITHUB_API_URL ?? 'https://api.github.com',
+    };
+}
+/**
+ * Find the PR number.
+ *
+ * `GITHUB_EVENT_PATH` points at the full webhook payload, which carries it for
+ * `pull_request` events. On a `push` there is no PR and we correctly find
+ * nothing. `GITHUB_REF` is checked as a fallback for workflows that re-dispatch
+ * with a synthesized ref.
+ */
+async function readPrNumber(env) {
+    const eventPath = env.GITHUB_EVENT_PATH;
+    if (eventPath) {
+        try {
+            const event = JSON.parse(await readFile(eventPath, 'utf8'));
+            const n = event.pull_request?.number ?? event.number;
+            if (typeof n === 'number')
+                return n;
+        }
+        catch {
+            // Malformed or unreadable payload; fall through to the ref.
+        }
+    }
+    // refs/pull/123/merge
+    const match = /^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? '');
+    return match ? Number(match[1]) : 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 async function postComment(ctx, body) {
+    try {
+        const existing = await findOwnComment(ctx);
+        const res = existing
+            ? await api(ctx, `/repos/${ctx.repository}/issues/comments/${existing.id}`, {
+                method: 'PATCH',
+                body: JSON.stringify({ body }),
+            })
+            : await api(ctx, `/repos/${ctx.repository}/issues/${ctx.prNumber}/comments`, {
+                method: 'POST',
+                body: JSON.stringify({ body }),
+            });
+        if (!res.ok)
+            return null;
+        const created = (await res.json());
+        return created.html_url ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Locate our previous comment by its marker.
+ *
+ * Paginated because a busy PR can exceed one page, and our comment is
+ * typically the oldest — posted on the first CI run — so stopping at page one
+ * would make us post a duplicate on every subsequent push.
+ */
+async function findOwnComment(ctx) {
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const res = await api(ctx, `/repos/${ctx.repository}/issues/${ctx.prNumber}/comments?per_page=100&page=${page}`);
+        if (!res.ok)
+            return null;
+        const comments = (await res.json());
+        const found = comments.find((c) => c.body?.includes(COMMENT_MARKER));
+        if (found)
+            return found;
+        if (comments.length < 100)
+            return null;
+    }
+    return null;
+}
+const MAX_PAGES = 10;
+function api(ctx, path, init = {}) {
+    return fetch(`${ctx.apiUrl}${path}`, {
+        ...init,
+        headers: {
+            accept: 'application/vnd.github+json',
+            authorization: `Bearer ${ctx.token}`,
+            'x-github-api-version': '2022-11-28',
+            'content-type': 'application/json',
+            ...init.headers,
+        },
+    });
+}
+//# sourceMappingURL=github.js.map

package/dist/report/github.js.map

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

package/dist/run/run.d.ts

@@ -0,0 +1,30 @@
+import type { Browser } from 'playwright';
+import type { Platform } from '../platform.js';
+import type { BaselineStore, DiffStatus, ProjectConfig, RunReport, StoryManifest, Viewport } from '../types.js';
+import { type AncestryCheck } from '../baseline/status.js';
+export declare const DEFAULT_VIEWPORT: Viewport;
+export interface RunOptions {
+    browser: Browser;
+    platform: Platform;
+    store: BaselineStore;
+    baseUrl: string;
+    stories: StoryManifest[];
+    /** Total story count before affected-filtering, for the report. */
+    totalCount: number;
+    config?: ProjectConfig;
+    ancestry?: AncestryCheck;
+    runId: string;
+    branch: string;
+    commitSha: string;
+    /** Receives each story's images so the caller decides where they land. */
+    onArtifact?: (artifact: RunArtifact) => Promise<void>;
+    onProgress?: (done: number, total: number, storyId: string) => void;
+    signal?: AbortSignal;
+}
+export interface RunArtifact {
+    storyId: string;
+    status: DiffStatus;
+    current: Buffer;
+    diff?: Buffer;
+}
+export declare function runCapture(opts: RunOptions): Promise<RunReport>;

package/dist/run/run.js

@@ -0,0 +1,120 @@
+// Orchestrate a run: enumerate → select → capture → judge → report.
+//
+// The ordering reflects the cost model. Hashing is cheap and decides pass/fail,
+// 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 { capturePool } from '../capture/pool.js';
+import { resolveStatus, toDiffStatus } from '../baseline/status.js';
+import { diffImages, resolveThreshold, resolveMinDiffPercent } from '../diff/diff.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 results = [];
+    const pool = capturePool(opts.stories, {
+        browser: opts.browser,
+        platform: opts.platform,
+        baseUrl: opts.baseUrl,
+        concurrency: opts.config?.concurrency,
+        warmSwitch: opts.config?.warmSwitch,
+        viewport,
+        onProgress: opts.onProgress,
+        signal: opts.signal,
+    });
+    for await (const outcome of pool) {
+        if (outcome.skipped) {
+            results.push({
+                storyId: outcome.story.storyId,
+                status: 'skip',
+                mismatchPixels: 0,
+                mismatchPercent: 0,
+                changedRegions: [],
+                durationMs: 0,
+            });
+            continue;
+        }
+        if (outcome.error || !outcome.snapshot) {
+            results.push({
+                storyId: outcome.story.storyId,
+                status: 'fail',
+                mismatchPixels: 0,
+                mismatchPercent: 0,
+                changedRegions: [],
+                error: outcome.error?.message ?? 'capture produced no snapshot',
+                durationMs: 0,
+            });
+            continue;
+        }
+        results.push(await judge(outcome.snapshot, outcome.story, manifest, opts));
+    }
+    const summary = tally(results);
+    return {
+        runId: opts.runId,
+        branch: opts.branch,
+        commitSha: opts.commitSha,
+        capturedCount: opts.stories.length,
+        totalCount: opts.totalCount,
+        results: results.sort((a, b) => a.storyId.localeCompare(b.storyId)),
+        summary,
+        durationMs: Date.now() - started,
+        startedAt: startedAt.toISOString(),
+    };
+}
+/** Decide one story's fate. Cheap path first. */
+async function judge(snapshot, story, manifest, opts) {
+    const baselineStatus = resolveStatus(story.storyId, snapshot.image, manifest, opts.ancestry);
+    const status = toDiffStatus(baselineStatus);
+    const base = {
+        storyId: story.storyId,
+        status,
+        mismatchPixels: 0,
+        mismatchPercent: 0,
+        changedRegions: [],
+        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 });
+        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 });
+        return { ...base, error: 'baseline missing from store' };
+    }
+    const diff = await 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,
+    });
+    return {
+        ...base,
+        mismatchPixels: diff.mismatchPixels,
+        mismatchPercent: diff.mismatchPercent,
+        changedRegions: diff.changedRegions,
+        error: diff.dimensionMismatch ? 'viewport size changed since baseline' : undefined,
+    };
+}
+function tally(results) {
+    const summary = {
+        pass: 0,
+        fail: 0,
+        new: 0,
+        stale: 0,
+        skip: 0,
+    };
+    for (const r of results)
+        summary[r.status]++;
+    return summary;
+}
+//# sourceMappingURL=run.js.map

package/dist/run/run.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+/** Per-story tuning, read from the platform's story parameters. */
+export interface StoryParams {
+    /** Exclude this story from capture entirely. */
+    skip?: boolean;
+    viewport?: Viewport;
+    /** Fixed extra wait after settle, ms. Escape hatch; prefer waitForSelector. */
+    delay?: number;
+    /** pixelmatch colour-distance threshold, 0..1. Default 0.1. */
+    threshold?: number;
+    /** Mismatch % below which a diff still passes. Suppresses AA noise. Default 0. */
+    minDiffPercent?: number;
+    /** CSS animations during capture. Default 'disabled' so spinners don't flake. */
+    animations?: 'play' | 'disabled';
+    /** Capture after the story's interaction/play phase rather than at first render. */
+    captureAfterPlay?: boolean;
+    /** Wait for this selector before screenshotting. For async content the
+     *  network drain can't see (SDK init, lazy canvas). */
+    waitForSelector?: string;
+    /** Max ms to wait for render-ready before screenshotting anyway. Default 2000. */
+    captureTimeout?: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/** One capturable story, normalised across platforms. */
+export interface StoryManifest {
+    /** Stable, URL-safe. Platform-native id (Storybook's `id`, Ladle's key). */
+    storyId: string;
+    /** Group/kind, e.g. "Components/Button". */
+    title: string;
+    /** Story name within the group, e.g. "Primary". */
+    name: string;
+    /** Absolute path to the source file. Drives affected-story analysis;
+     *  empty string when the platform can't report it (URL-list adapter). */
+    componentPath: string;
+    params: StoryParams;
+}
+export interface Snapshot {
+    storyId: string;
+    /** WebP-encoded. PNG is an intermediate, never stored. */
+    image: Buffer;
+    viewport: Viewport;
+    capturedAt: string;
+    /** Wall time for this story's capture, ms. */
+    durationMs: number;
+}
+export interface ChangedRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type DiffStatus = 'pass' | 'fail' | 'new' | 'stale' | 'skip';
+export interface DiffResult {
+    storyId: string;
+    status: DiffStatus;
+    mismatchPixels: number;
+    mismatchPercent: number;
+    /** Bounding boxes of changed clusters. Empty unless status is 'fail'. */
+    changedRegions: ChangedRegion[];
+    /** Set when the capture or diff threw. status is 'fail' in that case. */
+    error?: string;
+    durationMs: number;
+}
+export interface RunReport {
+    runId: string;
+    branch: string;
+    commitSha: string;
+    /** How many stories we captured vs how many exist. */
+    capturedCount: number;
+    totalCount: number;
+    results: DiffResult[];
+    summary: Record<DiffStatus, number>;
+    durationMs: number;
+    startedAt: string;
+}
+export interface ApprovalMeta {
+    commit: string;
+    approvedBy: string;
+    approvedAt: string;
+}
+export interface BaselineEntry extends ApprovalMeta {
+    /** sha256 of the baseline image bytes. Detects drift between manifest
+     *  and store without downloading the image. */
+    hash: string;
+}
+/** Committed to the repo. The source of truth for what "approved" means,
+ *  regardless of which store holds the actual bytes. */
+export interface BaselineManifest {
+    version: 1;
+    baselines: Record<string, BaselineEntry>;
+}
+/** Project config, from juxtapose.config.{ts,js,json} or package.json#juxtapose. */
+export interface ProjectConfig {
+    /** Which workbench. Autodetected when omitted. */
+    platform?: 'storybook' | 'ladle';
+    /** Where the built static workbench lives. */
+    buildDir?: string;
+    /** Capture against an already-running dev server instead of building. */
+    origin?: string;
+    /** Parallel pages. Default 8. More is not better — CPU saturation
+     *  causes render timeouts. Scale to core count. */
+    concurrency?: number;
+    /** Reuse warm pages and switch stories in place instead of navigating.
+     *  Much faster, but warm and cold captures do not currently produce
+     *  identical pixels, which makes results depend on queue order under a
+     *  byte-exact hash. Opt in only if you have measured it on your suite. */
+    warmSwitch?: boolean;
+    viewport?: Viewport;
+    threshold?: number;
+    minDiffPercent?: number;
+    /** Glob patterns of story ids to never capture. */
+    ignore?: string[];
+    storage?: StorageConfig;
+}
+export type StorageConfig = {
+    kind: 'git';
+    dir?: string;
+} | {
+    kind: 'fs';
+    dir: string;
+} | {
+    kind: 's3';
+    bucket: string;
+    prefix?: string;
+    endpoint?: string;
+};
+/** Baseline persistence. The manifest always lives in git; only the image
+ *  bytes vary by implementation. */
+export interface BaselineStore {
+    get(storyId: string): Promise<Buffer | null>;
+    put(storyId: string, image: Buffer, meta: ApprovalMeta): Promise<void>;
+    remove(storyId: string): Promise<void>;
+    readManifest(): Promise<BaselineManifest>;
+    writeManifest(manifest: BaselineManifest): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Core data model. Deliberately free of any platform (Storybook/Ladle) types —
+// adapters map their world onto these.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uCAAuC"}

package/dist/url-platform.d.ts

@@ -0,0 +1,10 @@
+import type { Page } from 'playwright';
+/**
+ * Build a `showStory` implementation from a URL builder.
+ *
+ * Note `waitUntil: 'load'` rather than `networkidle`: 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 declare function navigateToStory(storyUrl: (baseUrl: string, storyId: string) => string): (page: Page, storyId: string, baseUrl: string) => Promise<void>;

package/dist/url-platform.js

@@ -0,0 +1,22 @@
+// Helper for platforms that address a story by URL.
+//
+// Most workbenches do: Storybook has iframe.html?id=, Ladle has ?story=. For
+// those, "show me this story" is just a navigation, and there is no reason for
+// each adapter to write the same three lines.
+//
+// Playwright's component-testing galleries are the exception that made
+// `showStory` an action rather than a URL — see Platform.showStory.
+/**
+ * Build a `showStory` implementation from a URL builder.
+ *
+ * Note `waitUntil: 'load'` rather than `networkidle`: 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' });
+    };
+}
+//# sourceMappingURL=url-platform.js.map

package/dist/url-platform.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@juxtapose/core",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Platform-agnostic capture, diff, baseline and analysis core for juxtapose.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "pixelmatch": "^6.0.0",
+    "sharp": "^0.33.5"
+  },
+  "peerDependencies": {
+    "playwright": "^1.48.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/pixelmatch": "^5.2.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juxtapose-dev/juxtapose.git",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}