@sdods/core 0.8.0 → 0.9.0

package/dist/quality/perf-scenario.d.ts

@@ -0,0 +1,132 @@
+import type { Page } from '@playwright/test';
+import { type ApiSnapshot } from '@sdods/contracts';
+import { type BudgetConfig, type VitalsRecording } from '../perf/vitals.js';
+/**
+ * The budget check an `@perf` tag buys. Before this existed `perf.budgets` was enforced only by
+ * explicit steps, `apiP95Ms` only by a sampling step, and the tag itself by nothing.
+ *
+ * Two halves, because a page has to be watched while the scenario runs and judged after it:
+ *
+ *   · `watchNavigations` (UI and hybrid, before the scenario) installs an init script in the page.
+ *     Every document the main frame loads reports its own vitals through an exposed binding, once
+ *     the load event has finished. The document reports itself rather than being read from Node on
+ *     a `load` event, because a Node-side read races the next navigation: a step that clicks a link
+ *     straight after the load would have its read land in the NEXT document, whose load has not
+ *     ended, and report a slow page that does not exist.
+ *   · `judgeScenarioPerf` (every layer, after the scenario) compares every recorded navigation with
+ *     the page budgets (`pageLoadMs`, `lcpMs`, `fcpMs`, `ttfbMs`), and the p95 of the scenario's live
+ *     API response times (plus any latency samples it took) with `apiP95Ms`.
+ *
+ * The rules are the explicit steps' rules. A vital a budget applies to that did not fire FAILS,
+ * naming why. An `@perf` scenario on an environment with no budgets at all FAILS as CONFIG_INVALID.
+ * A scenario where no configured budget applied to anything it measured FAILS: it proved nothing.
+ * An API call replayed from a HAR is not a measurement of this environment and is not counted.
+ *
+ * One thing is NOT a failure: a document the scenario left before it could report (a navigation
+ * away before the document painted and its LCP window closed). That is not the application being slow; it is
+ * listed under `unreported` in the attachment so the gap is visible.
+ */
+/**
+ * How long a document waits, after its load event, for its first contentful paint before reporting.
+ * A client-rendered page (SauceDemo's login is one) routinely paints AFTER `load`: reading its
+ * vitals at the load event reports FCP and LCP as never having fired on a page that painted a
+ * moment later. A page that has not painted after this long reports what it has, and a budget on
+ * the missing vital then fails naming why.
+ */
+export declare const PAINT_WAIT_MS = 5000;
+/**
+ * How long the judge waits, at scenario end, for documents that loaded but have not reported: the
+ * paint wait plus the LCP settle window, with room for the binding round-trip.
+ */
+export declare const REPORT_WAIT_MS: number;
+/** The binding each document reports through. Namespaced so it cannot collide with the app. */
+export declare const VITALS_BINDING = "__sdodsReportVitals";
+/**
+ * The script every document in the page runs. Only the top-level document reports: after its load
+ * event, once it has painted (or `paintWaitMs` has passed), and after the same LCP settle window the
+ * explicit `I record the page vitals` step uses, so both measure a page the same way.
+ */
+export declare function vitalsInitScript(settleMs?: number, paintWaitMs?: number, binding?: string): string;
+/**
+ * Starts recording the vitals of every document the page's main frame loads. Must run before the
+ * scenario's first navigation, which is why the hook that calls it is a `BeforeScenario`.
+ */
+export declare function watchNavigations(deps: {
+    page: Page;
+    scenario: {
+        data: {
+            browser?: string;
+        };
+    };
+}): Promise<void>;
+export interface PerfBreach {
+    budget: string;
+    limitMs: number;
+    /** `null` when the value was never measured. */
+    measuredMs: number | null;
+    where: string;
+    message: string;
+}
+/** What `sdods/perf-scenario` contains, and what the `perfBudgets` process gate reads back. */
+export interface PerfScenarioReport {
+    kind: 'perf-scenario';
+    runnerProject: string;
+    fingerprint: string;
+    retry: number;
+    env: string;
+    status: 'judged' | 'skipped';
+    reason?: string;
+    budgets: Record<string, number>;
+    navigations: {
+        url: string;
+        vitals: VitalsRecording['vitals'];
+        unmeasured: VitalsRecording['unmeasured'];
+    }[];
+    /** Documents that loaded but were left before they could report. Listed, not failed. */
+    unreported: number;
+    api: {
+        liveCalls: number;
+        replayedFromHar: number;
+        samples: number;
+        p95Ms: number | null;
+    };
+    /** How many budget comparisons were made. Zero means the scenario proved nothing. */
+    judged: number;
+    breaches: PerfBreach[];
+}
+export interface PerfScenarioDeps {
+    config: BudgetConfig;
+    scenario: {
+        data: {
+            runnerProject: string;
+            fingerprint: string;
+            retry: number;
+            layer?: string;
+        };
+        file(rel: string): string;
+    };
+    apiContext: {
+        history: readonly ApiSnapshot[];
+    };
+    testInfo: {
+        status?: string;
+        attach(name: string, opts: {
+            path: string;
+            contentType: string;
+        }): Promise<void>;
+    };
+}
+/** Pure: every comparison and breach for a set of recordings and API timings. */
+export declare function judgeBudgets(input: {
+    budgets: Record<string, number>;
+    recordings: readonly VitalsRecording[];
+    apiMs: readonly number[];
+    apiReplayed: number;
+    envName: string;
+}): {
+    judged: number;
+    breaches: PerfBreach[];
+    p95Ms: number | null;
+};
+export declare function judgeScenarioPerf(deps: PerfScenarioDeps): Promise<PerfScenarioReport>;
+//# sourceMappingURL=perf-scenario.d.ts.map

package/dist/quality/perf-scenario.js

@@ -0,0 +1,241 @@
+import { attachmentNames, scenarioFiles } from '@sdods/contracts';
+import { writeAndAttachJson } from '../a11y/audit.js';
+import { SdodsError } from '../errors.js';
+import { API_P95_BUDGET_KEY, LCP_SETTLE_MS, LOAD_WAIT_MS, VITAL_KEYS, collectRawVitals, p95Of, perfStore, resolvedBudgets, toRecording, } from '../perf/vitals.js';
+/**
+ * The budget check an `@perf` tag buys. Before this existed `perf.budgets` was enforced only by
+ * explicit steps, `apiP95Ms` only by a sampling step, and the tag itself by nothing.
+ *
+ * Two halves, because a page has to be watched while the scenario runs and judged after it:
+ *
+ *   · `watchNavigations` (UI and hybrid, before the scenario) installs an init script in the page.
+ *     Every document the main frame loads reports its own vitals through an exposed binding, once
+ *     the load event has finished. The document reports itself rather than being read from Node on
+ *     a `load` event, because a Node-side read races the next navigation: a step that clicks a link
+ *     straight after the load would have its read land in the NEXT document, whose load has not
+ *     ended, and report a slow page that does not exist.
+ *   · `judgeScenarioPerf` (every layer, after the scenario) compares every recorded navigation with
+ *     the page budgets (`pageLoadMs`, `lcpMs`, `fcpMs`, `ttfbMs`), and the p95 of the scenario's live
+ *     API response times (plus any latency samples it took) with `apiP95Ms`.
+ *
+ * The rules are the explicit steps' rules. A vital a budget applies to that did not fire FAILS,
+ * naming why. An `@perf` scenario on an environment with no budgets at all FAILS as CONFIG_INVALID.
+ * A scenario where no configured budget applied to anything it measured FAILS: it proved nothing.
+ * An API call replayed from a HAR is not a measurement of this environment and is not counted.
+ *
+ * One thing is NOT a failure: a document the scenario left before it could report (a navigation
+ * away before the document painted and its LCP window closed). That is not the application being slow; it is
+ * listed under `unreported` in the attachment so the gap is visible.
+ */
+/**
+ * How long a document waits, after its load event, for its first contentful paint before reporting.
+ * A client-rendered page (SauceDemo's login is one) routinely paints AFTER `load`: reading its
+ * vitals at the load event reports FCP and LCP as never having fired on a page that painted a
+ * moment later. A page that has not painted after this long reports what it has, and a budget on
+ * the missing vital then fails naming why.
+ */
+export const PAINT_WAIT_MS = LOAD_WAIT_MS;
+/**
+ * How long the judge waits, at scenario end, for documents that loaded but have not reported: the
+ * paint wait plus the LCP settle window, with room for the binding round-trip.
+ */
+export const REPORT_WAIT_MS = PAINT_WAIT_MS + LCP_SETTLE_MS + 1_000;
+/** The binding each document reports through. Namespaced so it cannot collide with the app. */
+export const VITALS_BINDING = '__sdodsReportVitals';
+const watches = new WeakMap();
+/**
+ * The script every document in the page runs. Only the top-level document reports: after its load
+ * event, once it has painted (or `paintWaitMs` has passed), and after the same LCP settle window the
+ * explicit `I record the page vitals` step uses, so both measure a page the same way.
+ */
+export function vitalsInitScript(settleMs = LCP_SETTLE_MS, paintWaitMs = PAINT_WAIT_MS, binding = VITALS_BINDING) {
+    return `(() => {
+  if (window.top !== window) return;
+  const collect = ${collectRawVitals.toString()};
+  const painted = () => new Promise((resolve) => {
+    if (performance.getEntriesByName('first-contentful-paint').length) return resolve();
+    setTimeout(resolve, ${paintWaitMs});
+    try {
+      new PerformanceObserver((list) => {
+        if (list.getEntries().some((e) => e.name === 'first-contentful-paint')) resolve();
+      }).observe({ type: 'paint', buffered: true });
+    } catch (e) {
+      resolve();
+    }
+  });
+  addEventListener('load', () => {
+    setTimeout(() => {
+      painted()
+        .then(() => collect(${settleMs}))
+        .then((raw) => {
+          const report = window[${JSON.stringify(binding)}];
+          if (typeof report === 'function') report(raw);
+        }, () => undefined);
+    }, 0);
+  }, { once: true });
+})();`;
+}
+/**
+ * Starts recording the vitals of every document the page's main frame loads. Must run before the
+ * scenario's first navigation, which is why the hook that calls it is a `BeforeScenario`.
+ */
+export async function watchNavigations(deps) {
+    const { page, scenario } = deps;
+    const watch = { loads: 0, recordings: [], notify: [] };
+    watches.set(scenario, watch);
+    page.on('load', () => {
+        watch.loads++;
+    });
+    await page.exposeBinding(VITALS_BINDING, (source, raw) => {
+        if (source.frame !== page.mainFrame())
+            return;
+        watch.recordings.push(toRecording(raw, source.frame.url(), scenario.data.browser));
+        for (const fn of watch.notify.splice(0))
+            fn();
+    });
+    await page.addInitScript({ content: vitalsInitScript() });
+}
+async function waitForReports(watch) {
+    const deadline = Date.now() + REPORT_WAIT_MS;
+    while (watch.recordings.length < watch.loads && Date.now() < deadline) {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, Math.max(0, deadline - Date.now()));
+            watch.notify.push(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+}
+/** Pure: every comparison and breach for a set of recordings and API timings. */
+export function judgeBudgets(input) {
+    const { budgets, recordings, apiMs, apiReplayed, envName } = input;
+    const breaches = [];
+    let judged = 0;
+    for (const recording of recordings) {
+        for (const key of VITAL_KEYS) {
+            const limit = budgets[key];
+            if (limit === undefined)
+                continue;
+            judged++;
+            const value = recording.vitals[key];
+            if (value === null) {
+                breaches.push({
+                    budget: key,
+                    limitMs: limit,
+                    measuredMs: null,
+                    where: recording.url,
+                    message: `${key} was not measured on ${recording.url} — ${recording.unmeasured[key] ?? 'the page reported no value'}. A budget cannot be met by a vital that never fired.`,
+                });
+            }
+            else if (value > limit) {
+                breaches.push({
+                    budget: key,
+                    limitMs: limit,
+                    measuredMs: value,
+                    where: recording.url,
+                    message: `${key} measured ${value} ms on ${recording.url}, against a budget of ${limit} ms for environment "${envName}"`,
+                });
+            }
+        }
+    }
+    let p95Ms = null;
+    const apiLimit = budgets[API_P95_BUDGET_KEY];
+    if (apiLimit !== undefined && apiMs.length > 0) {
+        judged++;
+        p95Ms = p95Of(apiMs);
+        if (p95Ms > apiLimit)
+            breaches.push({
+                budget: API_P95_BUDGET_KEY,
+                limitMs: apiLimit,
+                measuredMs: p95Ms,
+                where: `${apiMs.length} API call(s)`,
+                message: `API p95 was ${p95Ms} ms over ${apiMs.length} call(s), against an ${API_P95_BUDGET_KEY} budget of ${apiLimit} ms for environment "${envName}"`,
+            });
+    }
+    else if (apiLimit !== undefined && apiReplayed > 0) {
+        judged++;
+        breaches.push({
+            budget: API_P95_BUDGET_KEY,
+            limitMs: apiLimit,
+            measuredMs: null,
+            where: `${apiReplayed} API call(s)`,
+            message: `All ${apiReplayed} API call(s) were replayed from a HAR, so their response times are the recording's, not environment "${envName}"'s. Run @perf scenarios without @har or --har-replay.`,
+        });
+    }
+    else if (apiMs.length > 0) {
+        p95Ms = p95Of(apiMs);
+    }
+    return { judged, breaches, p95Ms };
+}
+export async function judgeScenarioPerf(deps) {
+    const { config, scenario, apiContext, testInfo } = deps;
+    const envName = config.env.name ?? 'unknown';
+    const budgets = resolvedBudgets(config);
+    const watch = watches.get(scenario);
+    if (watch)
+        await waitForReports(watch);
+    const recordings = watch?.recordings ?? [];
+    const live = apiContext.history.filter((s) => !s.replayedFromHar);
+    const samples = perfStore(scenario).sampleSets.flatMap((set) => set.samples.map((s) => s.ms));
+    const apiMs = [...live.map((s) => s.response.responseTime), ...samples];
+    const apiReplayed = apiContext.history.length - live.length;
+    const report = {
+        kind: 'perf-scenario',
+        runnerProject: scenario.data.runnerProject,
+        fingerprint: scenario.data.fingerprint,
+        retry: scenario.data.retry,
+        env: envName,
+        status: 'judged',
+        budgets,
+        navigations: recordings.map((r) => ({
+            url: r.url,
+            vitals: r.vitals,
+            unmeasured: r.unmeasured,
+        })),
+        unreported: watch ? Math.max(0, watch.loads - recordings.length) : 0,
+        api: {
+            liveCalls: live.length,
+            replayedFromHar: apiReplayed,
+            samples: samples.length,
+            p95Ms: null,
+        },
+        judged: 0,
+        breaches: [],
+    };
+    const file = scenario.file(scenarioFiles.perfScenarioJson(scenario.data.runnerProject));
+    const write = () => writeAndAttachJson(testInfo, attachmentNames.perfScenario, file, report);
+    if (testInfo.status && testInfo.status !== 'passed') {
+        report.status = 'skipped';
+        report.reason = `the scenario ${testInfo.status} before its budgets could be judged`;
+        await write();
+        return report;
+    }
+    const verdict = judgeBudgets({ budgets, recordings, apiMs, apiReplayed, envName });
+    report.judged = verdict.judged;
+    report.breaches = verdict.breaches;
+    report.api.p95Ms = verdict.p95Ms;
+    if (Object.keys(budgets).length === 0) {
+        report.status = 'skipped';
+        report.reason = 'no perf budgets are configured';
+        await write();
+        throw new SdodsError('CONFIG_INVALID', `This @perf scenario runs on environment "${envName}", which has no perf budgets configured.`, {
+            hint: `Set perf.budgets (${[...VITAL_KEYS, API_P95_BUDGET_KEY].join(', ')}) in the project's sdods.project.yaml, or in envs/${envName}.yaml. Without one the @perf tag would pass no matter how slow the application is.`,
+        });
+    }
+    await write();
+    if (verdict.judged === 0) {
+        const measured = [
+            recordings.length ? `${recordings.length} page navigation(s)` : 'no page navigation',
+            apiMs.length ? `${apiMs.length} API call(s)` : 'no API call',
+        ].join(' and ');
+        throw new SdodsError('RUN_FAILED', `This @perf scenario measured ${measured}, and none of the configured budgets (${Object.keys(budgets).join(', ')}) applies to that, so it proved nothing.`, {
+            hint: 'Configure a budget for what the scenario exercises (page vitals for a UI flow, apiP95Ms for API calls), or drop @perf from it.',
+        });
+    }
+    if (verdict.breaches.length) {
+        throw new SdodsError('RUN_FAILED', `@perf: ${verdict.breaches.length} budget breach(es):\n${verdict.breaches.map((b) => `  ${b.message}`).join('\n')}`, { hint: 'The full measurements are attached as sdods/perf-scenario.' });
+    }
+    return report;
+}
+//# sourceMappingURL=perf-scenario.js.map

package/dist/shots/baselines.d.ts

@@ -0,0 +1,72 @@
+import type { VisualFailure } from '@sdods/contracts';
+import type { ShotPolicyResolved } from './policy.js';
+/** Where a project's baselines live; accept refuses to write anywhere else. */
+export declare const BASELINES_DIR: string;
+/** Baseline name as the config keys it: the step argument without `.png`. */
+export declare function baselineKey(name: string): string;
+/**
+ * Mask and threshold for one baseline check: the project/env `screenshots.mask`, plus
+ * `screenshots.baselines.<name>.mask`, plus the selectors the step passed. Duplicates are dropped.
+ * The threshold is the baseline's own `maxDiffPixelRatio`, else the project/env one.
+ */
+export declare function visualCheckOptions(name: string, policy: Pick<ShotPolicyResolved, 'mask' | 'maxDiffPixelRatio' | 'baselines'>, extraMask?: readonly string[]): {
+    mask: string[];
+    maxDiffPixelRatio: number;
+};
+/**
+ * Selectors from the `masking {string}` step argument. Comma-separated, so
+ * `"[data-test=badge], .timestamp"` masks both. A selector that itself contains a comma
+ * (`:is(a, b)`, `[title="a, b"]`) belongs in `screenshots.baselines.<name>.mask` instead.
+ */
+export declare function parseMaskArgument(value: string): string[];
+/** What Playwright's `toHaveScreenshot` error says about why the check failed. */
+export declare function parseVisualError(message: string): {
+    reason: VisualFailure['reason'];
+    diffPixels?: number;
+};
+/** Width and height from a PNG header, without decoding it. */
+export declare function pngSize(file: string): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * The visual checks that failed in a run and still need a decision: every
+ * `visual/<target>/<name>.failure.json` under the run's scenario directories, keeping only the
+ * last attempt of each check. A check that passed on a later retry is not listed.
+ */
+export declare function listVisualFailures(runDir: string): VisualFailure[];
+/**
+ * Pick failures by name. A name matches `inventory`, `inventory.png`, or
+ * `<run target>/inventory` to narrow it to one browser.
+ */
+export declare function selectVisualFailures(failures: readonly VisualFailure[], sel: {
+    names?: readonly string[];
+    all?: boolean;
+}): VisualFailure[];
+export interface AcceptedBaseline {
+    name: string;
+    project: string;
+    runnerProject: string;
+    platform: string;
+    reason: VisualFailure['reason'];
+    diffRatio?: number;
+    /** image copied, absolute */
+    from: string;
+    /** baseline written, absolute */
+    to: string;
+    /** false when a baseline existed and was replaced */
+    created: boolean;
+    /** the diff image a person reviewed, absolute, when there was one */
+    diff?: string;
+}
+/**
+ * Copy each failure's actual image over its baseline: `features/__screenshots__/<run
+ * target>/<platform>/<name>.png` of the project, for the platform the run happened on. Writes
+ * into the project tree the way `--update-snapshots` does, so a person runs it, not an agent.
+ */
+export declare function acceptVisualFailures(opts: {
+    runDir: string;
+    failures: readonly VisualFailure[];
+    projectRoot: (slug: string) => string;
+}): AcceptedBaseline[];
+//# sourceMappingURL=baselines.d.ts.map

package/dist/shots/baselines.js

@@ -0,0 +1,201 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { SdodsError } from '../errors.js';
+/** Where a project's baselines live; accept refuses to write anywhere else. */
+export const BASELINES_DIR = join('features', '__screenshots__');
+/** Baseline name as the config keys it: the step argument without `.png`. */
+export function baselineKey(name) {
+    return name.replace(/\.png$/i, '');
+}
+/**
+ * Mask and threshold for one baseline check: the project/env `screenshots.mask`, plus
+ * `screenshots.baselines.<name>.mask`, plus the selectors the step passed. Duplicates are dropped.
+ * The threshold is the baseline's own `maxDiffPixelRatio`, else the project/env one.
+ */
+export function visualCheckOptions(name, policy, extraMask = []) {
+    const own = policy.baselines?.[baselineKey(name)];
+    const mask = [...new Set([...policy.mask, ...(own?.mask ?? []), ...extraMask])].filter((s) => s.trim() !== '');
+    return { mask, maxDiffPixelRatio: own?.maxDiffPixelRatio ?? policy.maxDiffPixelRatio ?? 0.01 };
+}
+/**
+ * Selectors from the `masking {string}` step argument. Comma-separated, so
+ * `"[data-test=badge], .timestamp"` masks both. A selector that itself contains a comma
+ * (`:is(a, b)`, `[title="a, b"]`) belongs in `screenshots.baselines.<name>.mask` instead.
+ */
+export function parseMaskArgument(value) {
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** ANSI colour sequences, built by code point so the source carries no control character. */
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+/** What Playwright's `toHaveScreenshot` error says about why the check failed. */
+export function parseVisualError(message) {
+    const plain = message.replace(ANSI, '');
+    if (/snapshot doesn't exist|writing actual/i.test(plain))
+        return { reason: 'missing' };
+    if (/Expected an image \d+px by \d+px, received/i.test(plain))
+        return { reason: 'size' };
+    const px = /(\d+) pixels \(ratio [\d.]+ of all image pixels\) are different/.exec(plain);
+    return { reason: 'changed', diffPixels: px ? Number(px[1]) : undefined };
+}
+/** Width and height from a PNG header, without decoding it. */
+export function pngSize(file) {
+    try {
+        const buf = readFileSync(file);
+        if (buf.length < 24 || buf.readUInt32BE(0) !== 0x89504e47)
+            return undefined;
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The visual checks that failed in a run and still need a decision: every
+ * `visual/<target>/<name>.failure.json` under the run's scenario directories, keeping only the
+ * last attempt of each check. A check that passed on a later retry is not listed.
+ */
+export function listVisualFailures(runDir) {
+    if (!existsSync(runDir))
+        return [];
+    const latest = new Map();
+    const walk = (dir, depth) => {
+        if (depth > 6)
+            return;
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const abs = join(dir, n);
+            let isDir = false;
+            try {
+                isDir = statSync(abs).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                // Runner scratch and reports never hold records.
+                if (depth === 0 &&
+                    /^(runner-output|pw-output|html-report|shard-reports|blob-report)$/.test(n))
+                    continue;
+                walk(abs, depth + 1);
+                continue;
+            }
+            const m = /^(.*)\.(failure|passed)\.json$/.exec(n);
+            if (!m || !abs.split(sep).includes('visual'))
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(readFileSync(abs, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (!rec || typeof rec.name !== 'string' || typeof rec.runnerProject !== 'string')
+                continue;
+            const key = JSON.stringify([rec.fingerprint, rec.runnerProject, rec.name]);
+            const prev = latest.get(key);
+            const retry = Number(rec.retry ?? 0);
+            if (prev && prev.retry > retry)
+                continue;
+            if (prev && prev.retry === retry && m[2] === 'passed')
+                continue;
+            latest.set(key, { retry, failure: m[2] === 'failure' ? rec : undefined });
+        }
+    };
+    walk(runDir, 0);
+    return [...latest.values()]
+        .map((v) => v.failure)
+        .filter((f) => !!f)
+        .sort((a, b) => a.project.localeCompare(b.project) ||
+        a.runnerProject.localeCompare(b.runnerProject) ||
+        a.name.localeCompare(b.name));
+}
+/**
+ * Pick failures by name. A name matches `inventory`, `inventory.png`, or
+ * `<run target>/inventory` to narrow it to one browser.
+ */
+export function selectVisualFailures(failures, sel) {
+    if (sel.all)
+        return [...failures];
+    const names = sel.names ?? [];
+    if (!names.length)
+        throw new SdodsError('CONFIG_INVALID', 'Name the baselines to accept, or pass --all.', {
+            exitCode: 2,
+        });
+    const picked = [];
+    const unknown = [];
+    for (const raw of names) {
+        const slash = raw.lastIndexOf('/');
+        const target = slash > 0 ? raw.slice(0, slash) : undefined;
+        const key = baselineKey(slash > 0 ? raw.slice(slash + 1) : raw);
+        const hits = failures.filter((f) => baselineKey(f.name) === key && (!target || f.runnerProject === target));
+        if (!hits.length)
+            unknown.push(raw);
+        for (const h of hits)
+            if (!picked.includes(h))
+                picked.push(h);
+    }
+    if (unknown.length) {
+        const available = [...new Set(failures.map((f) => `${f.runnerProject}/${f.name}`))];
+        throw new SdodsError('CONFIG_INVALID', `No failed visual check named ${unknown.map((u) => `"${u}"`).join(', ')} in this run.`, {
+            hint: available.length
+                ? `Failed in this run: ${available.join(', ')}`
+                : 'No visual check failed in this run.',
+            exitCode: 2,
+        });
+    }
+    return picked;
+}
+/**
+ * Copy each failure's actual image over its baseline: `features/__screenshots__/<run
+ * target>/<platform>/<name>.png` of the project, for the platform the run happened on. Writes
+ * into the project tree the way `--update-snapshots` does, so a person runs it, not an agent.
+ */
+export function acceptVisualFailures(opts) {
+    const plan = opts.failures.map((f) => {
+        const root = resolve(opts.projectRoot(f.project));
+        const guard = resolve(root, BASELINES_DIR);
+        const to = resolve(root, f.baseline);
+        const inside = relative(guard, to);
+        if (!inside || inside.startsWith('..') || isAbsolute(inside) || !/\.png$/i.test(to))
+            throw new SdodsError('CONFIG_INVALID', `Refusing to write ${f.baseline}: baselines live under ${BASELINES_DIR}/.`, { exitCode: 2 });
+        const runDir = resolve(opts.runDir);
+        const from = resolve(runDir, f.actual);
+        const back = relative(runDir, from);
+        if (back.startsWith('..') || isAbsolute(back))
+            throw new SdodsError('CONFIG_INVALID', `Actual image ${f.actual} is outside the run.`, {
+                exitCode: 2,
+            });
+        if (!existsSync(from))
+            throw new SdodsError('CONFIG_NOT_FOUND', `The actual image for ${f.runnerProject}/${f.name} is missing: ${from}`, { exitCode: 2 });
+        const diff = f.diff ? resolve(runDir, f.diff) : undefined;
+        return { f, from, to, diff: diff && existsSync(diff) ? diff : undefined };
+    });
+    // Validate everything first, then write: a bad entry must not leave half the set accepted.
+    return plan.map(({ f, from, to, diff }) => {
+        const created = !existsSync(to);
+        mkdirSync(dirname(to), { recursive: true });
+        copyFileSync(from, to);
+        return {
+            name: f.name,
+            project: f.project,
+            runnerProject: f.runnerProject,
+            platform: f.platform,
+            reason: f.reason,
+            diffRatio: f.diffRatio,
+            from,
+            to,
+            created,
+            diff,
+        };
+    });
+}
+//# sourceMappingURL=baselines.js.map

package/dist/shots/hooks.js

@@ -27,8 +27,8 @@ AfterScenario({ name: 'sdods:shots:end', tags: UI }, async ({ shots, $testInfo }
 });
 AfterScenario({ name: 'sdods:finalize' }, async ({ scenario, apiContext, heal, $testInfo }) => {
     scenario.finalize({
-        status: $testInfo.status ?? 'unknown',
-        errorMessage: $testInfo.error?.message,
+        status: scenario.hookFailure ? 'failed' : ($testInfo.status ?? 'unknown'),
+        errorMessage: $testInfo.error?.message ?? scenario.hookFailure,
         apiCalls: apiContext.history.length,
         heals: heal.events.length,
     });

package/dist/shots/index.d.ts

@@ -1,3 +1,4 @@
 export * from './policy.js';
 export * from './narrator.js';
+export * from './baselines.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/shots/index.js

@@ -1,3 +1,4 @@
 export * from './policy.js';
 export * from './narrator.js';
+export * from './baselines.js';
 //# sourceMappingURL=index.js.map