@junejuly-lockstep/reconciler 0.1.0

package/dist/sync.js.map

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

package/dist/upload.d.ts

@@ -0,0 +1,33 @@
+import type { IngestClient } from '@junejuly-lockstep/sdk';
+export declare const PRESIGN_BATCH = 50;
+export interface UploadFile {
+    /** Path relative to runs/{runId}/, e.g. shots/book-a-visit/start/nora.png */
+    path: string;
+    contentType: string;
+    localPath: string;
+}
+export interface UploadResult {
+    runId: string;
+    prefix: string;
+    /** Relative path -> full S3 key, as returned by presign. */
+    keys: Map<string, string>;
+    uploaded: number;
+}
+/** Collect every PNG and trace under the artifacts dir, sorted for deterministic batching. */
+export declare function collectArtifacts(artifactsDir: string): Promise<UploadFile[]>;
+export interface UploadOptions {
+    client: Pick<IngestClient, 'presign'>;
+    files: UploadFile[];
+    /** Reserve under an existing run id (second batch onwards); omitted for the first call. */
+    runId?: string;
+    fetchImpl?: typeof fetch;
+    log?: (line: string) => void;
+    batchSize?: number;
+    retries?: number;
+}
+/**
+ * Request presigned PUTs in batches of 50 and upload each file with its content type.
+ * The first presign response reserves the run id used for every later batch and the payload.
+ */
+export declare function uploadArtifacts(opts: UploadOptions): Promise<UploadResult>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../src/upload.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAalF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACtC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAkEhF"}

package/dist/upload.js

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { InfrastructureError } from './errors.js';
+import { contentTypeFor, toPosix, withRetry } from './util.js';
+export const PRESIGN_BATCH = 50;
+/** Collect every PNG and trace under the artifacts dir, sorted for deterministic batching. */
+export async function collectArtifacts(artifactsDir) {
+    const files = await fg(['shots/**/*.png', 'diffs/**/*.png', 'traces/**/*.zip'], {
+        cwd: artifactsDir,
+        onlyFiles: true,
+    });
+    return files
+        .map(toPosix)
+        .sort()
+        .map((rel) => ({
+        path: rel,
+        contentType: contentTypeFor(rel),
+        localPath: path.join(artifactsDir, rel),
+    }));
+}
+/**
+ * Request presigned PUTs in batches of 50 and upload each file with its content type.
+ * The first presign response reserves the run id used for every later batch and the payload.
+ */
+export async function uploadArtifacts(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const log = opts.log ?? (() => { });
+    const batchSize = Math.min(opts.batchSize ?? PRESIGN_BATCH, PRESIGN_BATCH);
+    const files = [...opts.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const keys = new Map();
+    let runId = opts.runId;
+    let prefix = '';
+    let uploaded = 0;
+    const batches = [];
+    for (let i = 0; i < files.length; i += batchSize)
+        batches.push(files.slice(i, i + batchSize));
+    if (batches.length === 0) {
+        // Nothing to upload, but the run still needs an id: reserve it with a presign of nothing.
+        throw new InfrastructureError('no artifacts to upload; the walk produced no screenshots or traces');
+    }
+    for (const [bi, batch] of batches.entries()) {
+        const res = await withRetry(() => opts.client.presign({
+            runId,
+            files: batch.map((f) => ({ path: f.path, contentType: f.contentType })),
+        }), {
+            retries: opts.retries ?? 3,
+            onRetry: (err) => log(`presign batch ${bi + 1} retry: ${describe(err)}`),
+        }).catch((err) => {
+            throw new InfrastructureError(`presign batch ${bi + 1}/${batches.length} failed`, err);
+        });
+        runId ??= res.runId;
+        if (res.runId !== runId)
+            throw new InfrastructureError(`presign returned run id ${res.runId}, expected ${runId}`);
+        prefix = res.prefix;
+        const byPath = new Map(res.urls.map((u) => [u.path, u]));
+        for (const file of batch) {
+            const target = byPath.get(file.path);
+            if (!target)
+                throw new InfrastructureError(`presign response is missing a URL for ${file.path}`);
+            const body = readFileSync(file.localPath);
+            await withRetry(async () => {
+                const r = await fetchImpl(target.url, {
+                    method: 'PUT',
+                    headers: { 'content-type': file.contentType },
+                    body,
+                });
+                if (!r.ok)
+                    throw new Error(`PUT ${file.path} -> ${r.status}`);
+            }, {
+                retries: opts.retries ?? 3,
+                onRetry: (err) => log(`upload ${file.path} retry: ${describe(err)}`),
+            }).catch((err) => {
+                throw new InfrastructureError(`upload of ${file.path} failed`, err);
+            });
+            keys.set(file.path, target.key);
+            uploaded++;
+        }
+        log(`uploaded batch ${bi + 1}/${batches.length} (${batch.length} files)`);
+    }
+    return { runId: runId, prefix, keys, uploaded };
+}
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=upload.js.map

package/dist/upload.js.map

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

package/dist/util.d.ts

@@ -0,0 +1,24 @@
+import { type Jiti } from 'jiti';
+export declare function sha256(input: string | Uint8Array): string;
+/** Normalise to forward slashes so keys and payloads are identical on every OS. */
+export declare function toPosix(p: string): string;
+export declare function relPosix(from: string, to: string): string;
+export declare function ensureDir(dir: string): void;
+/** Make a journey/state/scenario name safe for an artifact path (`PresignRequest` allows [\w./-]). */
+export declare function safeSegment(s: string): string;
+export declare function normalizeNewlines(text: string): string;
+/** Sort helper producing a deterministic order regardless of locale. */
+export declare function byString<T>(key: (t: T) => string): (a: T, b: T) => number;
+/** One jiti instance per process: loads TS at runtime with no build step. */
+export declare function getJiti(): Jiti;
+export declare function importTs<T = unknown>(file: string): Promise<T>;
+export declare function packageRoot(): string;
+export declare function reconcilerVersion(): string;
+export declare function sleep(ms: number): Promise<void>;
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, opts: {
+    retries: number;
+    baseDelayMs?: number;
+    onRetry?: (err: unknown, attempt: number) => void;
+}): Promise<T>;
+export declare function contentTypeFor(file: string): string;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,MAAM,CAAC;AAE7C,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAEzD;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAMzE;AAGD,6EAA6E;AAC7E,wBAAgB,OAAO,IAAI,IAAI,CAO9B;AAED,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpE;AAED,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAS1C;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,IAAI,EAAE;IACJ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD,GACA,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBnD"}

package/dist/util.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createJiti } from 'jiti';
+export function sha256(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/** Normalise to forward slashes so keys and payloads are identical on every OS. */
+export function toPosix(p) {
+    return p.split(path.sep).join('/').replace(/\\/g, '/');
+}
+export function relPosix(from, to) {
+    return toPosix(path.relative(from, to));
+}
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+/** Make a journey/state/scenario name safe for an artifact path (`PresignRequest` allows [\w./-]). */
+export function safeSegment(s) {
+    return s.replace(/[^\w.-]+/g, '_') || '_';
+}
+export function normalizeNewlines(text) {
+    return text.replace(/\r\n?/g, '\n');
+}
+/** Sort helper producing a deterministic order regardless of locale. */
+export function byString(key) {
+    return (a, b) => {
+        const ka = key(a);
+        const kb = key(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    };
+}
+let jiti;
+/** One jiti instance per process: loads TS at runtime with no build step. */
+export function getJiti() {
+    jiti ??= createJiti(import.meta.url, {
+        interopDefault: true,
+        moduleCache: false,
+        fsCache: false,
+    });
+    return jiti;
+}
+export async function importTs(file) {
+    return getJiti().import(path.resolve(file));
+}
+export function packageRoot() {
+    // dist/util.js or src/util.ts -> package root
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+export function reconcilerVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export async function withRetry(fn, opts) {
+    let last;
+    for (let attempt = 0; attempt <= opts.retries; attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            last = err;
+            if (attempt === opts.retries)
+                break;
+            opts.onRetry?.(err, attempt);
+            await sleep((opts.baseDelayMs ?? 250) * 2 ** attempt);
+        }
+    }
+    throw last;
+}
+export function contentTypeFor(file) {
+    const ext = path.extname(file).toLowerCase();
+    switch (ext) {
+        case '.png':
+            return 'image/png';
+        case '.zip':
+            return 'application/zip';
+        case '.json':
+            return 'application/json';
+        case '.txt':
+        case '.md':
+            return 'text/plain';
+        case '.html':
+            return 'text/html';
+        default:
+            return 'application/octet-stream';
+    }
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

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

package/dist/visual.d.ts

@@ -0,0 +1,49 @@
+import { PNG } from 'pngjs';
+import { type BaselineManifest, type VisualComparison, type WalkResult } from '@junejuly-lockstep/model';
+/**
+ * Per-pixel colour distance threshold handed to pixelmatch (0..1): how different two pixels must
+ * be to count as differing. Not the `visualDiffThreshold` of lockstep.config.ts, which is the
+ * fraction of differing pixels above which the API marks a screenshot `changed`; the reconciler
+ * only reports the score.
+ */
+export declare const PIXEL_THRESHOLD = 0.1;
+export interface CompareResult {
+    /** Differing pixels / total pixels, 0..1. Size mismatch is 1. */
+    score: number;
+    diffPixels: number;
+    width: number;
+    height: number;
+    /** Encoded diff PNG, or null when sizes differ (nothing to overlay). */
+    diff: Buffer | null;
+    detail: string | null;
+}
+export declare function decodePng(buf: Buffer): PNG;
+export declare function encodePng(png: PNG): Buffer;
+/** Compare two PNG buffers with pixelmatch. */
+export declare function comparePng(actual: Buffer, baseline: Buffer, opts?: {
+    pixelThreshold?: number;
+}): CompareResult;
+export declare function baselineId(e: {
+    journeyKey: string;
+    stateKey: string;
+    scenario: string;
+}): string;
+/** Download every baseline in the manifest (presigned GETs) into `dir`; returns id -> local path. */
+export declare function downloadBaselines(manifest: BaselineManifest, dir: string, fetchImpl?: typeof fetch, log?: (msg: string) => void): Promise<Map<string, string>>;
+export interface CompareWalkOptions {
+    walk: WalkResult;
+    manifest: BaselineManifest | null;
+    /** Local directory the walk wrote relative screenshot paths into. */
+    artifactsDir: string;
+    /** Baseline id -> local path, from `downloadBaselines`. */
+    baselines: Map<string, string>;
+    /** pixelmatch colour threshold (see PIXEL_THRESHOLD); never the visualDiffThreshold. */
+    pixelThreshold?: number;
+}
+/**
+ * Compare the first screenshot of every (journey, state, scenario) against its baseline.
+ * `screenshotKey`/`diffKey` are artifact-relative paths here (`ARTIFACT_PATHS`); the uploader maps
+ * them to S3 keys under runs/{runId}/.
+ */
+export declare function compareWalk(opts: CompareWalkOptions): VisualComparison[];
+//# sourceMappingURL=visual.d.ts.map

package/dist/visual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../src/visual.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,0BAA0B,CAAC;AAIlC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAE1C;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAE1C;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACrC,aAAa,CA2Bf;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEhG;AAED,qGAAqG;AACrG,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,OAAO,KAAa,EAC/B,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe,GACpC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA4B9B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,gBAAgB,EAAE,CAgExE"}

package/dist/visual.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import { ARTIFACT_PATHS, } from '@junejuly-lockstep/model';
+import { InfrastructureError } from './errors.js';
+import { ensureDir, safeSegment, withRetry } from './util.js';
+/**
+ * Per-pixel colour distance threshold handed to pixelmatch (0..1): how different two pixels must
+ * be to count as differing. Not the `visualDiffThreshold` of lockstep.config.ts, which is the
+ * fraction of differing pixels above which the API marks a screenshot `changed`; the reconciler
+ * only reports the score.
+ */
+export const PIXEL_THRESHOLD = 0.1;
+export function decodePng(buf) {
+    return PNG.sync.read(buf);
+}
+export function encodePng(png) {
+    return PNG.sync.write(png);
+}
+/** Compare two PNG buffers with pixelmatch. */
+export function comparePng(actual, baseline, opts = {}) {
+    const a = decodePng(actual);
+    const b = decodePng(baseline);
+    if (a.width !== b.width || a.height !== b.height) {
+        return {
+            score: 1,
+            diffPixels: a.width * a.height,
+            width: a.width,
+            height: a.height,
+            diff: null,
+            detail: `size mismatch: screenshot ${a.width}x${a.height}, baseline ${b.width}x${b.height}`,
+        };
+    }
+    const diff = new PNG({ width: a.width, height: a.height });
+    const diffPixels = pixelmatch(a.data, b.data, diff.data, a.width, a.height, {
+        threshold: opts.pixelThreshold ?? PIXEL_THRESHOLD,
+        includeAA: false,
+    });
+    const total = a.width * a.height;
+    return {
+        score: total === 0 ? 0 : diffPixels / total,
+        diffPixels,
+        width: a.width,
+        height: a.height,
+        diff: diffPixels > 0 ? encodePng(diff) : null,
+        detail: null,
+    };
+}
+export function baselineId(e) {
+    return `${e.journeyKey}/${e.stateKey}/${e.scenario}`;
+}
+/** Download every baseline in the manifest (presigned GETs) into `dir`; returns id -> local path. */
+export async function downloadBaselines(manifest, dir, fetchImpl = fetch, log = () => { }) {
+    ensureDir(dir);
+    const out = new Map();
+    for (const entry of [...manifest.entries].sort((a, b) => baselineId(a).localeCompare(baselineId(b)))) {
+        const id = baselineId(entry);
+        const local = path.join(dir, `${id.replace(/\//g, '__')}.png`);
+        await withRetry(async () => {
+            const res = await fetchImpl(entry.url);
+            if (!res.ok)
+                throw new InfrastructureError(`baseline download ${id} failed with ${res.status}`);
+            writeFileSync(local, Buffer.from(await res.arrayBuffer()));
+        }, {
+            retries: 3,
+            onRetry: (err) => log(`retrying baseline ${id}: ${err instanceof Error ? err.message : String(err)}`),
+        }).catch((err) => {
+            throw err instanceof InfrastructureError
+                ? err
+                : new InfrastructureError(`baseline download ${id} failed`, err);
+        });
+        out.set(id, local);
+    }
+    return out;
+}
+/**
+ * Compare the first screenshot of every (journey, state, scenario) against its baseline.
+ * `screenshotKey`/`diffKey` are artifact-relative paths here (`ARTIFACT_PATHS`); the uploader maps
+ * them to S3 keys under runs/{runId}/.
+ */
+export function compareWalk(opts) {
+    const seen = new Set();
+    const out = [];
+    const entries = new Map((opts.manifest?.entries ?? []).map((e) => [baselineId(e), e]));
+    for (const p of opts.walk.paths) {
+        for (const step of p.steps) {
+            if (!step.screenshotKey || step.status !== 'pass')
+                continue;
+            const id = baselineId({
+                journeyKey: p.journeyKey,
+                stateKey: step.stateKey,
+                scenario: p.scenario,
+            });
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const shotPath = path.join(opts.artifactsDir, step.screenshotKey);
+            if (!existsSync(shotPath))
+                continue;
+            const actual = readFileSync(shotPath);
+            const entry = entries.get(id);
+            const local = entry ? opts.baselines.get(id) : undefined;
+            if (!entry || !local || !existsSync(local)) {
+                const png = decodePng(actual);
+                out.push({
+                    journeyKey: p.journeyKey,
+                    stateKey: step.stateKey,
+                    scenario: p.scenario,
+                    screenshotKey: step.screenshotKey,
+                    baselineKey: null,
+                    diffKey: null,
+                    score: 0,
+                    width: png.width,
+                    height: png.height,
+                });
+                continue;
+            }
+            const result = comparePng(actual, readFileSync(local), {
+                pixelThreshold: opts.pixelThreshold,
+            });
+            let diffKey = null;
+            if (result.diff) {
+                diffKey = ARTIFACT_PATHS.diff(safeSegment(p.journeyKey), safeSegment(step.stateKey), safeSegment(p.scenario));
+                const diffPath = path.join(opts.artifactsDir, diffKey);
+                ensureDir(path.dirname(diffPath));
+                writeFileSync(diffPath, result.diff);
+            }
+            out.push({
+                journeyKey: p.journeyKey,
+                stateKey: step.stateKey,
+                scenario: p.scenario,
+                screenshotKey: step.screenshotKey,
+                baselineKey: entry.s3Key,
+                diffKey,
+                score: result.score,
+                width: result.width,
+                height: result.height,
+                ...(result.detail ? { detail: result.detail } : {}),
+            });
+        }
+    }
+    return out.sort((a, b) => baselineId(a).localeCompare(baselineId(b)));
+}
+//# sourceMappingURL=visual.js.map

package/dist/visual.js.map

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

package/dist/walk.d.ts

@@ -0,0 +1,147 @@
+import type { JourneyModel, LockstepConfig, Scenario, WalkResult } from '@junejuly-lockstep/model';
+import { type BootOptions, type BootedApp } from './boot.js';
+/** 2026-01-15T09:30:00.000Z. Every walk's `Date.now()` starts here. */
+export declare const FROZEN_EPOCH_MS: number;
+export declare const VIEWPORT: {
+    readonly width: 1280;
+    readonly height: 800;
+};
+export declare const DEVICE_SCALE_FACTOR = 1;
+export declare const LOCALE = "en-US";
+export declare const TIMEZONE = "UTC";
+export declare const COLOR_SCHEME = "light";
+/** Injected on every document: no animations, no transitions, no blinking caret, no smooth scroll. */
+export declare const DISABLE_MOTION_CSS: string;
+/**
+ * Chromium flags that remove machine-dependent text rendering, plus `--disable-partial-raster`:
+ * with partial raster on, a tile whose content changed after first paint (a page that renders its
+ * state root once its data arrived) is re-rastered only inside the damage rect, and the
+ * anti-aliasing along that rect's edges differs by a unit from a full raster of the same pixels,
+ * depending on whether a frame was produced in between. Invisible, but not byte-identical.
+ */
+export declare const CHROMIUM_ARGS: string[];
+export declare const STEP_TIMEOUT_MS = 15000;
+export declare const MAX_ATTEMPTS = 2;
+export interface LocatorLike {
+    waitFor(options?: {
+        state?: 'visible' | 'attached' | 'hidden' | 'detached';
+        timeout?: number;
+    }): Promise<void>;
+    click(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    isVisible(): Promise<boolean>;
+    first(): LocatorLike;
+}
+export interface RequestLike {
+    url(): string;
+    method(): string;
+    postData(): string | null;
+}
+export interface PageLike {
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+        timeout?: number;
+    }): Promise<unknown>;
+    url(): string;
+    locator(selector: string): LocatorLike;
+    screenshot(options: {
+        path?: string;
+        fullPage?: boolean;
+        animations?: 'disabled' | 'allow';
+        caret?: 'hide' | 'initial';
+        scale?: 'css' | 'device';
+    }): Promise<Buffer>;
+    waitForLoadState(state?: 'load' | 'domcontentloaded' | 'networkidle', options?: {
+        timeout?: number;
+    }): Promise<void>;
+    evaluate(expression: string): Promise<unknown>;
+    addStyleTag(options: {
+        content?: string;
+    }): Promise<unknown>;
+    on(event: 'request', listener: (request: RequestLike) => void): unknown;
+    /** Optional in fakes; the real page parks the pointer after every click (see `park`). */
+    mouse?: {
+        move(x: number, y: number): Promise<void>;
+    };
+    clock: {
+        install(options?: {
+            time?: number | string | Date;
+        }): Promise<void>;
+        setFixedTime(time: number | string | Date): Promise<void>;
+    };
+    close(): Promise<void>;
+}
+export interface ContextLike {
+    newPage(): Promise<PageLike>;
+    addInitScript(script: string): Promise<void>;
+    tracing: {
+        start(options?: {
+            screenshots?: boolean;
+            snapshots?: boolean;
+            sources?: boolean;
+            title?: string;
+        }): Promise<void>;
+        stop(options?: {
+            path?: string;
+        }): Promise<void>;
+    };
+    close(): Promise<void>;
+}
+export interface BrowserLike {
+    newContext(options?: {
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        deviceScaleFactor?: number;
+        reducedMotion?: 'reduce' | 'no-preference';
+        colorScheme?: 'light' | 'dark';
+        locale?: string;
+        timezoneId?: string;
+        hasTouch?: boolean;
+        isMobile?: boolean;
+    }): Promise<ContextLike>;
+    close(): Promise<void>;
+}
+export interface WalkDeps {
+    launch(): Promise<BrowserLike>;
+    boot(opts: BootOptions): Promise<BootedApp>;
+}
+/** Default deps: real Playwright Chromium (imported lazily) and the real app boot. */
+export declare const defaultWalkDeps: WalkDeps;
+export interface WalkOptions {
+    journeys: JourneyModel[];
+    scenarios: Scenario[];
+    config: Pick<LockstepConfig, 'bootCommand' | 'port'>;
+    /** Repo root the boot command runs in. */
+    rootDir: string;
+    /** Local directory that mirrors `runs/{runId}/`: shots/ and traces/ are written under it. */
+    artifactsDir: string;
+    log?: (line: string) => void;
+    deps?: WalkDeps;
+    /** Override the base URL (default http://127.0.0.1:{port}). */
+    baseUrl?: string;
+    stepTimeoutMs?: number;
+    /** Skip booting (an already-running app on `port`). Only for local debugging. */
+    noBoot?: boolean;
+}
+export declare function screenshotPath(journeyKey: string, stateKey: string, scenario: string): string;
+export declare function tracePath(journeyKey: string, scenario: string, pathIndex: number): string;
+export declare function triggerTestId(journey: JourneyModel, from: string, event: string): string;
+export declare function testIdSelector(testId: string): string;
+/** Pull GraphQL operation names out of a request whose path ends in /graphql. */
+export declare function operationNamesOf(req: RequestLike): string[];
+/**
+ * One line for the walk result and the verdict detail: Playwright's first line plus the call-log
+ * lines that say what it was waiting for or navigating to (the selector lives there, not in the
+ * first line). Anything else in the call log is noise for a card.
+ */
+export declare function summarizeError(err: unknown): string;
+/**
+ * Execute every enumerated path of every journey, per scenario, and record a `WalkResult`.
+ * Order: scenarios by name, journeys by key, paths by target state. Boot happens once per
+ * scenario so `LOCKSTEP_SCENARIO`/`LOCKSTEP_SEED` reach server-side mocks too.
+ */
+export declare function walk(opts: WalkOptions): Promise<WalkResult>;
+//# sourceMappingURL=walk.d.ts.map