@crvouga/atlas 1.13.0 → 1.15.0

package/dist/reports/src/run-compare.js

@@ -0,0 +1,329 @@
+import { compareLatency, groupOf, latencyObservations, latencyReview } from './latency.js';
+/** Where a pair of results (or one result with no partner) stands, in the order a review reads them. */
+export const COMPARE_GROUPS = ['regressed', 'recovered', 'still-failing', 'not-comparable', 'unknown', 'removed', 'added', 'unchanged'];
+/** What each group is called and what it does and does not say. */
+export const COMPARE_GROUP_TEXT = {
+    regressed: { label: 'Newly failing', meaning: 'Passed in the baseline run and failed in the candidate run, under the same conditions and the same wording.' },
+    recovered: { label: 'Recovered', meaning: 'Failed in the baseline run and passed in the candidate run. One later pass is not a proven fix.' },
+    'still-failing': { label: 'Still failing', meaning: 'Failed in both runs.' },
+    'not-comparable': { label: 'Promise or conditions differ', meaning: 'The behavior is worded differently, or the two results were recorded under different conditions, so the two outcomes are not the same experiment and no regression or recovery is claimed.' },
+    unknown: { label: 'Not run or unfinished', meaning: 'One side did not run it or it is still running. That is unknown: not a failure and not a pass.' },
+    removed: { label: 'Not in the candidate run', meaning: 'Only the baseline run recorded it. The candidate may not have run it, or it was renamed or dropped: unknown, not a regression and not a pass.' },
+    added: { label: 'Not in the baseline run', meaning: 'Only the candidate run recorded it. It may be new, or the baseline may not have run it.' },
+    unchanged: { label: 'Same outcome', meaning: 'Passed in both runs, or not run in both.' }
+};
+/** The condition of a result. A server that does not send `kind` leaves it null: unknown, equal only to another unknown. */
+export function conditionOf(result) {
+    return { kind: result.kind ?? null, producer: result.producer, environment: result.environment, parameters: result.parameters ?? {} };
+}
+/** A stable text for a condition, equal exactly when two conditions are. */
+export function conditionId(condition) {
+    const parameters = Object.keys(condition.parameters).sort().map(name => `${name}=${condition.parameters[name]}`).join(',');
+    return [condition.kind ?? '', condition.producer, condition.environment ?? '', parameters].join('/');
+}
+/** How two conditions differ, in words; empty when they are the same. */
+export function conditionDifferences(baseline, candidate) {
+    const out = [];
+    if (baseline.environment !== candidate.environment)
+        out.push(`environment ${baseline.environment ?? 'not declared'} against ${candidate.environment ?? 'not declared'}`);
+    if (baseline.producer !== candidate.producer)
+        out.push(`producer ${baseline.producer} against ${candidate.producer}`);
+    if ((baseline.kind ?? '') !== (candidate.kind ?? ''))
+        out.push(`kind ${baseline.kind ?? 'not declared'} against ${candidate.kind ?? 'not declared'}`);
+    for (const name of [...new Set([...Object.keys(baseline.parameters), ...Object.keys(candidate.parameters)])].sort()) {
+        if (baseline.parameters[name] !== candidate.parameters[name])
+            out.push(`${name} ${baseline.parameters[name] ?? 'not set'} against ${candidate.parameters[name] ?? 'not set'}`);
+    }
+    return out;
+}
+const completed = (status) => status === 'passed' || status === 'failed';
+const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Short form of a spec fingerprint, to show. */
+export function shortRevision(revision) {
+    return revision ? revision.slice(0, 8) : 'not recorded';
+}
+/** The wording a run recorded for a check: what that run's layer called it, else the check's newest title. */
+export function recordedTitle(result) {
+    return result.recordedTitle ?? result.title;
+}
+function readPromise(baseline, candidate) {
+    const baselineTitle = baseline ? recordedTitle(baseline) : null;
+    const candidateTitle = candidate ? recordedTitle(candidate) : null;
+    const baselineRevision = baseline?.specRevision ?? null;
+    const candidateRevision = candidate?.specRevision ?? null;
+    const reasons = [];
+    const base = { baselineTitle, candidateTitle, baselineRevision, candidateRevision };
+    if (!baseline || !candidate)
+        return { ...base, state: 'unknown', reasons: ['Only one run recorded this behavior, so its promise cannot be compared.'] };
+    const titleDiffers = baselineTitle !== candidateTitle;
+    const revisionKnown = baselineRevision !== null && candidateRevision !== null;
+    const revisionDiffers = revisionKnown && baselineRevision !== candidateRevision;
+    if (titleDiffers)
+        reasons.push(`The behavior is worded differently: “${baselineTitle}” became “${candidateTitle}”.`);
+    if (revisionDiffers)
+        reasons.push(`The spec file was recorded at revision ${shortRevision(baselineRevision)} and then ${shortRevision(candidateRevision)}. A revision is of the whole file, so it does not say that this behavior's own promise changed.`);
+    if (titleDiffers)
+        return { ...base, state: 'changed', reasons };
+    if (revisionDiffers)
+        return { ...base, state: 'revision-differs', reasons };
+    if (!revisionKnown) {
+        reasons.push(`${baselineRevision === null && candidateRevision === null ? 'Neither run' : baselineRevision === null ? 'The baseline run' : 'The candidate run'} recorded no spec revision, so whether the promise is the same is unknown.`);
+        return { ...base, state: 'unknown', reasons };
+    }
+    return { ...base, state: 'same', reasons };
+}
+function movement(baseline, candidate) {
+    const b = baseline.status;
+    const c = candidate.status;
+    if (!completed(b) || !completed(c)) {
+        const where = !completed(c) ? 'candidate' : 'baseline';
+        const what = (status) => (status === 'running' ? 'still running' : 'not run');
+        const side = !completed(c) ? c : b;
+        return { group: 'unknown', summary: `${what(side)[0].toUpperCase()}${what(side).slice(1)} in the ${where} run, so there is no outcome to compare. That is unknown, not a failure or a pass.` };
+    }
+    if (b === 'passed' && c === 'failed')
+        return { group: 'regressed', summary: 'Passed in the baseline run, failed in the candidate run.' };
+    if (b === 'failed' && c === 'passed')
+        return { group: 'recovered', summary: 'Failed in the baseline run, passed in the candidate run.' };
+    if (b === 'failed')
+        return { group: 'still-failing', summary: 'Failed in both runs.' };
+    return { group: 'unchanged', summary: 'Passed in both runs.' };
+}
+function pairOf(key, baseline, candidate, differences) {
+    const promise = readPromise(baseline, candidate);
+    const id = [key, baseline ? conditionId(conditionOf(baseline)) : '', candidate ? conditionId(conditionOf(candidate)) : ''].join('\u0001');
+    const title = candidate ? recordedTitle(candidate) : recordedTitle(baseline);
+    const specPath = (candidate ?? baseline).specPath;
+    const caveats = [];
+    const common = { id, key, title, specPath, baseline, candidate, promise, conditions: differences, caveats };
+    if (!baseline)
+        return { ...common, group: 'added', summary: 'Only the candidate run recorded it. It may be new, or the baseline may not have run it.' };
+    if (!candidate)
+        return { ...common, group: 'removed', summary: 'The candidate run recorded no result for it. It may not have run it, or it was renamed or dropped: unknown, not a regression.' };
+    if (promise.state === 'changed' || differences.length > 0) {
+        const why = [...(promise.state === 'changed' ? ['the behavior is worded differently'] : []), ...(differences.length ? [`it was recorded under different conditions (${differences.join('; ')})`] : [])];
+        return { ...common, group: 'not-comparable', summary: `Not the same experiment: ${why.join(' and ')}. Both outcomes are shown; no regression or recovery is claimed.` };
+    }
+    const moved = movement(baseline, candidate);
+    if (promise.state === 'revision-differs')
+        caveats.push(...promise.reasons);
+    else if (promise.state === 'unknown' && moved.group !== 'unknown')
+        caveats.push(...promise.reasons);
+    return { ...common, ...moved };
+}
+/**
+ * Pairs the results of two runs and reads what changed. Results are paired by check identity and then by condition (see
+ * the module comment); titles never pair two results. Each side's results are those the run recorded last for each
+ * check and condition (`RunDetail.results`).
+ *
+ * @param baseline - The run to compare against.
+ * @param candidate - The run under review. Both are used as given: a newer run never replaces either.
+ * @returns Every result of either run, grouped by what changed, with the reasons.
+ * @example
+ * ```ts
+ * const comparison = compareRuns(await runDetail('run:ci-100'), await runDetail('run:ci-101'));
+ * comparison.results.filter(item => item.group === 'regressed');
+ * ```
+ */
+export function compareRuns(baseline, candidate) {
+    const byKey = (results) => {
+        const map = new Map();
+        for (const result of results) {
+            const list = map.get(result.key);
+            if (list)
+                list.push(result);
+            else
+                map.set(result.key, [result]);
+        }
+        return map;
+    };
+    const left = byKey(baseline.results);
+    const right = byKey(candidate.results);
+    const pairs = [];
+    for (const key of [...new Set([...left.keys(), ...right.keys()])]) {
+        const sides = { base: [...(left.get(key) ?? [])], cand: [...(right.get(key) ?? [])] };
+        const order = (a, b) => compareText(conditionId(conditionOf(a)), conditionId(conditionOf(b))) || compareText(a.layer, b.layer);
+        sides.base.sort(order);
+        sides.cand.sort(order);
+        // First the same condition on both sides, then whatever is left of the same check under other conditions.
+        const restBase = [];
+        for (const result of sides.base) {
+            const at = sides.cand.findIndex(other => conditionId(conditionOf(other)) === conditionId(conditionOf(result)));
+            if (at < 0)
+                restBase.push(result);
+            else
+                pairs.push(pairOf(key, result, sides.cand.splice(at, 1)[0], []));
+        }
+        while (restBase.length && sides.cand.length) {
+            const result = restBase.shift();
+            const other = sides.cand.shift();
+            pairs.push(pairOf(key, result, other, conditionDifferences(conditionOf(result), conditionOf(other))));
+        }
+        for (const result of restBase)
+            pairs.push(pairOf(key, result, null, []));
+        for (const result of sides.cand)
+            pairs.push(pairOf(key, null, result, []));
+    }
+    pairs.sort((a, b) => COMPARE_GROUPS.indexOf(a.group) - COMPARE_GROUPS.indexOf(b.group) ||
+        compareText(a.specPath ?? '', b.specPath ?? '') ||
+        compareText(a.title, b.title) ||
+        compareText(a.id, b.id));
+    const counts = Object.fromEntries(COMPARE_GROUPS.map(group => [group, 0]));
+    for (const pair of pairs)
+        counts[pair.group] += 1;
+    const notes = [];
+    if (baseline.run.key === candidate.run.key)
+        notes.push('The same run is on both sides, so nothing can differ.');
+    if (baseline.run.branch !== candidate.run.branch)
+        notes.push(`The runs are on different branches (${baseline.run.branch ?? 'none recorded'} and ${candidate.run.branch ?? 'none recorded'}).`);
+    if (candidate.run.endedAtMs < baseline.run.endedAtMs)
+        notes.push('The candidate run ended before the baseline run.');
+    for (const [name, side] of [['baseline', baseline], ['candidate', candidate]]) {
+        if (side.run.freshness === 'modified')
+            notes.push(`The ${name} run was recorded from a checkout with uncommitted changes.`);
+        if (side.run.counts.running > 0)
+            notes.push(`The ${name} run still has results running, so its outcomes may change.`);
+    }
+    return { baseline: baseline.run, candidate: candidate.run, results: pairs, counts, notes };
+}
+const devicesOf = (entries) => [...new Set(latencyObservations(entries).map(o => groupOf(o, 'device')))].sort();
+/**
+ * Compares the product latency recorded in two sets of results of one check, one per side. A metric is compared only
+ * when it is the same measurement (name, unit, boundaries) and both sides were measured on the same devices, in the
+ * same environments, with the same instrumentation and other conditions; otherwise it is `incompatible` and no change
+ * is computed, with the reasons. A metric only one side recorded is named as such. A side without any latency is unknown,
+ * not fast: it contributes no metric. `conditionsDiffer` names differences of the results' own conditions, which make
+ * every metric incompatible.
+ */
+export function compareProductLatency(baseline, candidate, conditionsDiffer = []) {
+    const left = latencyReview(baseline).metrics;
+    const right = latencyReview(candidate).metrics;
+    const sameDevices = devicesOf(baseline).join('\u0001') === devicesOf(candidate).join('\u0001');
+    const out = [];
+    for (const { metric, groups } of left) {
+        const base = groups[0];
+        const other = right.find(item => item.metric.key === metric.key)?.groups[0];
+        if (!other) {
+            const renamed = right.find(item => item.metric.name === metric.name);
+            out.push({ state: 'baseline-only', name: metric.name, summary: base, reasons: [renamed ? `The candidate measures ${metric.name} over a different interval (${renamed.metric.boundary.label}), so the two are not the same measurement.` : 'The candidate recorded no such measurement.'] });
+            continue;
+        }
+        const change = compareLatency(base, other);
+        const reasons = [...conditionsDiffer.map(line => `Recorded under different conditions: ${line}.`)];
+        if (!sameDevices)
+            reasons.push(`Devices differ: ${devicesOf(baseline).join(', ')} against ${devicesOf(candidate).join(', ')}.`);
+        if (change.comparable) {
+            reasons.push(...change.disclosures.filter(line => /^(Environments differ|Test conditions differ|Instrumentation changed)/.test(line)));
+        }
+        else
+            reasons.push(...change.reasons);
+        if (reasons.length)
+            out.push({ state: 'incompatible', name: metric.name, baseline: base, candidate: other, change: null, reasons });
+        else
+            out.push({ state: 'compared', name: metric.name, baseline: base, candidate: other, change, reasons: change.disclosures });
+    }
+    for (const { metric, groups } of right) {
+        if (!left.some(item => item.metric.key === metric.key) && !left.some(item => item.metric.name === metric.name)) {
+            out.push({ state: 'candidate-only', name: metric.name, summary: groups[0], reasons: ['The baseline recorded no such measurement.'] });
+        }
+    }
+    return out;
+}
+/**
+ * The scope that counts the independent executions of one result's check up to the end of its run: the same
+ * environment, producer and parameters, and the spec revision that result was recorded against (executions against
+ * another revision are other promises). A result that recorded no revision is counted across revisions, which
+ * {@link compareReliability} will not compare. Use it for each side, with that side's result and run.
+ */
+export function reliabilityScopeAt(result, run) {
+    return {
+        ...(result.environment ? { environment: [result.environment] } : {}),
+        producer: [result.producer],
+        ...(result.parameters && Object.keys(result.parameters).length ? { parameter: Object.entries(result.parameters).map(([name, value]) => `${name}=${value}`).sort() } : {}),
+        ...(result.specRevision ? { specRevision: [result.specRevision] } : { revision: 'any' }),
+        until: run.endedAtMs
+    };
+}
+/**
+ * Sets the reliability of a check up to the baseline run against its reliability up to the candidate run. A change is
+ * stated only when both samples are established (at least `minimumExecutions` independent executions), both counted the
+ * same recorded spec revision (see {@link reliabilityScopeAt}) and the conditions match; whether the difference exceeds the uncertainty is
+ * said by `direction`. Otherwise each figure stands alone and the reasons say why.
+ */
+export function compareReliability(baseline, candidate, conditionsDiffer = []) {
+    const reasons = conditionsDiffer.map(line => `Counted under different conditions: ${line}.`);
+    for (const [name, document] of [['baseline', baseline], ['candidate', candidate]]) {
+        if (document.sample === 'none')
+            reasons.push(`The ${name} figure has no completed execution, so it is unknown, not reliable.`);
+        else if (document.sample === 'insufficient')
+            reasons.push(`The ${name} figure rests on ${document.eventual.executions} independent ${document.eventual.executions === 1 ? 'execution' : 'executions'}; at least ${document.minimumExecutions} are needed.`);
+    }
+    const revisionOf = (document) => document.scope.specRevision?.join(',') ?? null;
+    if (revisionOf(baseline) === null || revisionOf(candidate) === null)
+        reasons.push('A side recorded no spec revision, so whether both count the same promise is unknown.');
+    else if (revisionOf(baseline) !== revisionOf(candidate))
+        reasons.push('The executions were counted against different revisions of the spec, so they describe different promises.');
+    const base = baseline.eventual;
+    const cand = candidate.eventual;
+    if (reasons.length || base.rate === null || cand.rate === null)
+        return { comparable: false, baseline: base, candidate: cand, reasons };
+    const separate = baseline.interval && candidate.interval ? baseline.interval.upper < candidate.interval.lower || candidate.interval.upper < baseline.interval.lower : false;
+    const points = Math.round((cand.rate - base.rate) * 1000) / 10;
+    return {
+        comparable: true,
+        baseline: base,
+        candidate: cand,
+        points,
+        direction: !separate ? 'indistinguishable' : cand.rate > base.rate ? 'higher' : 'lower',
+        reasons: separate ? [] : ['The two intervals overlap, so the difference may be chance. It is not shown as an improvement or a decline.']
+    };
+}
+/**
+ * Lines up the recorded steps of two results by name (the n-th step of a name on one side with the n-th of that name on
+ * the other), keeping each side's own time origin: an offset is milliseconds after that side's check began. Nothing is
+ * aligned by position or by fuzzy wording. When nothing lines up, `explanation` says why.
+ */
+export function alignSteps(baseline, candidate) {
+    const keyed = (steps) => {
+        const seen = new Map();
+        return steps.map(step => {
+            const n = seen.get(step.name) ?? 0;
+            seen.set(step.name, n + 1);
+            return { step, id: `${n}\u0001${step.name}` };
+        });
+    };
+    const left = keyed(baseline);
+    const right = keyed(candidate);
+    const rightById = new Map(right.map(item => [item.id, item.step]));
+    const leftIds = new Set(left.map(item => item.id));
+    const steps = [];
+    for (const { step, id } of left) {
+        const other = rightById.get(id);
+        steps.push({
+            name: step.name,
+            ...(step.offsetMs === undefined ? {} : { baselineOffsetMs: step.offsetMs }),
+            ...(other?.offsetMs === undefined ? {} : { candidateOffsetMs: other.offsetMs }),
+            onBaseline: true,
+            onCandidate: other !== undefined
+        });
+    }
+    for (const { step, id } of right) {
+        if (!leftIds.has(id))
+            steps.push({ name: step.name, ...(step.offsetMs === undefined ? {} : { candidateOffsetMs: step.offsetMs }), onBaseline: false, onCandidate: true });
+    }
+    const seekable = steps.filter((step) => step.baselineOffsetMs !== undefined && step.candidateOffsetMs !== undefined);
+    const shared = steps.filter(step => step.onBaseline && step.onCandidate).length;
+    const differs = steps.some(step => !(step.onBaseline && step.onCandidate));
+    let explanation;
+    if (seekable.length > 0)
+        explanation = `${seekable.length} recorded ${seekable.length === 1 ? 'step is' : 'steps are'} on both sides with a time. Seeking uses each side's own step time from the start of its own check; the recordings are otherwise not synchronized.`;
+    else if (!baseline.length && !candidate.length)
+        explanation = 'Neither side recorded steps, so the recordings cannot be aligned. Each plays from its own start.';
+    else if (!baseline.length || !candidate.length)
+        explanation = `Only the ${baseline.length ? 'baseline' : 'candidate'} recorded steps, so the recordings cannot be aligned. Each plays from its own start.`;
+    else if (shared === 0)
+        explanation = 'The two sides share no step name, so the recordings cannot be aligned. Each plays from its own start.';
+    else
+        explanation = 'The shared steps carry no time on both sides, so the recordings cannot be aligned. Each plays from its own start.';
+    return { state: seekable.length > 0 ? 'aligned' : 'unaligned', steps, seekable, differs, explanation };
+}

package/dist/reports/src/test-catalog.d.ts

@@ -322,6 +322,14 @@ export type RunResult = {
     readonly detail: string;
     /** Every video its evidence references, with who holds it (check, retry attempt or step). Absent when there is none. */
     readonly videos?: readonly VideoRef[];
+    /** The kind of the part that held it (`behavior`, `checks`…). With the producer, environment and parameters it is the condition the result was recorded under. Absent from an older server. */
+    readonly kind?: string;
+    /** The other choices that made it its own result (a device size, a locale…). Absent when there are none, and from an older server. */
+    readonly parameters?: Readonly<Record<string, string>>;
+    /** The fingerprint of its spec file the layer recorded: results with different ones were recorded against different revisions of the spec. Absent means not recorded, never "the same". */
+    readonly specRevision?: string;
+    /** The title this run's layer gave the check. `title` is the newest title the check has in the whole history, so a check that was reworded shows its newest wording in both runs; this is the wording as recorded. Absent from an older server. */
+    readonly recordedTitle?: string;
 };
 /**
  * One layer of a run, as the run's artifact hub names it: who recorded it, how many checks it holds (zero is possible

package/dist/reports/src/test-catalog.js

@@ -105,6 +105,8 @@ export class TestHistory {
     #idents = new Map();
     #runs = new Map();
     #specs = new RecordedSpecs();
+    /** Titles seen, so the many results that share one hold one string. */
+    #titles = new Map();
     #seen = new Set();
     #rev = 0;
     #cells = null;
@@ -187,9 +189,16 @@ export class TestHistory {
                 ident.title = row.title;
                 ident.titledAt = layer.recordedAtMs;
             }
-            this.#remember(slot, { o: origin, s: row.status, d: row.durationMs, k: row.kind, t: row.detail, e: row.evidence, m: productLatency(row.measurements), f: row.specPath ? fingerprints[row.specPath] : undefined });
+            this.#remember(slot, { o: origin, s: row.status, d: row.durationMs, k: row.kind, t: row.detail, e: row.evidence, m: productLatency(row.measurements), f: row.specPath ? fingerprints[row.specPath] : undefined, ti: this.#title(row.title) });
         }
     }
+    #title(title) {
+        const held = this.#titles.get(title);
+        if (held !== undefined)
+            return held;
+        this.#titles.set(title, title);
+        return title;
+    }
     /** Sorted insert, newest first; past the bound, the oldest is dropped. */
     #remember(slot, entry) {
         const list = this.#bySlot.get(slot);
@@ -262,6 +271,10 @@ export class TestHistory {
             key: i.slot, id: i.id, title: i.title, specPath: i.specPath, environment: r.o.environment, producer: r.o.producer,
             status: r.s, durationMs: r.d, at: r.o.at, layer: r.o.layer, detail: shortDetail(r.t),
             ...(r.e?.videos ? { videos: r.e.videos } : {}),
+            kind: r.k,
+            ...(Object.keys(r.o.parameters).length ? { parameters: r.o.parameters } : {}),
+            ...(r.f ? { specRevision: r.f } : {}),
+            ...(r.ti !== undefined ? { recordedTitle: r.ti } : {}),
         }));
         results.sort((a, b) => FAILURE_RANK[b.status] - FAILURE_RANK[a.status] || compareText(a.specPath ?? '', b.specPath ?? '') || compareText(a.title, b.title) || compareText(a.environment ?? '', b.environment ?? '') || compareText(a.producer, b.producer) || compareText(a.key, b.key));
         const layers = [...run.members].sort((a, b) => a.recordedAtMs - b.recordedAtMs || compareText(a.id, b.id));

package/dist/reports/src/ui-catalog-publish.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module Writing a UI catalog from any collector
+ *
+ * Two small builders that turn what a collector captured, or what a planner expects, into the input of `publishChecks`
+ * (and of `atlas report publish --checks`), following the convention in {@link ./ui-state}. They are plain data in and plain
+ * data out: no browser, no test framework, no file system. A Playwright test, a Cypress run, a mobile device lab, a Storybook
+ * crawler or a shell script that writes the same JSON all produce the same catalog.
+ *
+ * Shards need no coordination: each shard calls {@link uiStateLayer} for the states it captured (and optionally
+ * {@link uiPlanLayer} for the states it was given), with its own `shard` label, and publishes. A planner that knows the whole
+ * product publishes the plan once.
+ *
+ * @see docs/ui-catalog.md
+ */
+import type { PublishChecksInput } from '../../schema/src/layer.js';
+import { type UiStateFacts } from './ui-state.js';
+/** A picture to store with a capture: its bytes (`data`, `base64`), or where it already is (`uri`). */
+export type UiPicture = {
+    /** The file name; default `<id>.png`. */
+    readonly name?: string;
+    readonly data?: Uint8Array;
+    readonly base64?: string;
+    readonly uri?: string;
+    /** Default `image/png`. */
+    readonly contentType?: string;
+    readonly width?: number;
+    readonly height?: number;
+};
+/** One captured state. `id` must be stable across runs: it is how a new capture replaces an old one. */
+export type UiStateCapture = UiStateFacts & {
+    readonly id: string;
+    /** For a person; default the id. */
+    readonly title?: string;
+    /** `passed` (default): captured. `failed`: the capture was attempted and did not work (say why in `detail`). `running`: being taken. `not-run`: skipped. */
+    readonly status?: 'passed' | 'failed' | 'running' | 'not-run';
+    /** Why it failed or was skipped: a readiness check that never became true, a console error. */
+    readonly detail?: string;
+    readonly screenshot?: UiPicture;
+    readonly durationMs?: number;
+    /** More facts about the capture that never split it (`browser`, `os`). */
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly tags?: readonly string[];
+};
+/** One expected state, or (with `inventory`) one surface of the product's inventory. */
+export type UiStatePlan = UiStateFacts & {
+    readonly id: string;
+    readonly title?: string;
+};
+/** What every layer of a catalog says about where and when it was recorded. */
+export type UiLayerOrigin = {
+    /** The suite or tool that makes the layer. Part of the slot; a planner and a collector normally differ. */
+    readonly producer: string;
+    /** When the captures were taken (or the plan was made), epoch milliseconds. Take it from the run, not from the moment of publishing. */
+    readonly recordedAtMs: number;
+    /** The client: `desktop-web`, `mobile-web`, `ios`, `android`… Part of the slot. */
+    readonly environment?: string;
+    /** The rest of the profile, such as `{ viewport: '390x844', scheme: 'dark' }`. Each combination is its own result. Part of the slot. */
+    readonly profile?: Readonly<Record<string, string>>;
+    readonly sha?: string | null;
+    readonly branch?: string | null;
+    readonly runUrl?: string | null;
+    /** Which shard this is (`2/4`, `checkout`, a machine name). Shown with each capture; never part of the slot. */
+    readonly shard?: string;
+    /** The execution these layers belong to, so shards of one run stay one run. */
+    readonly run?: {
+        readonly id: string;
+        readonly title?: string;
+    };
+};
+/**
+ * The input of `publishChecks` for the states one collector (or one shard) captured under one profile. Throws when a state id
+ * repeats, because the second would silently replace the first. A state without a `status` is `passed`: it was captured.
+ *
+ * @example
+ * ```ts
+ * await publishChecks(store, uiStateLayer({
+ *   producer: 'web-capture', recordedAtMs: Date.now(), environment: 'mobile-web', profile: { viewport: '390x844', scheme: 'dark' }, shard: '1/4',
+ *   states: [{ id: 'checkout/payment', title: 'Payment', route: '/checkout', covers: ['payment-form'], screenshot: { data: png } }]
+ * }));
+ * ```
+ */
+export declare function uiStateLayer(input: UiLayerOrigin & {
+    readonly states: readonly UiStateCapture[];
+}): PublishChecksInput;
+/**
+ * The input of `publishChecks` for what is expected: states that should be captured under this profile and, with `inventory`,
+ * surfaces the product is known to have. Every entry is `not-run`, so a plan never counts as a pass, and it fills a slot of
+ * its own (kind `ui-plan`), so a capture never erases it and it never hides a capture. Throws when an id repeats.
+ */
+export declare function uiPlanLayer(input: UiLayerOrigin & {
+    readonly states: readonly UiStatePlan[];
+}): PublishChecksInput;

package/dist/reports/src/ui-catalog-publish.js

@@ -0,0 +1,68 @@
+import { UI_PLAN_KIND, UI_STATE_EXTENSION, UI_STATE_KIND } from './ui-state.js';
+function common(origin, kind, title) {
+    return {
+        producer: origin.producer, kind, title, recordedAtMs: origin.recordedAtMs,
+        ...(origin.environment ? { environment: origin.environment } : {}),
+        parameters: { ...origin.profile },
+        ...(origin.sha !== undefined ? { sha: origin.sha } : {}), ...(origin.branch !== undefined ? { branch: origin.branch } : {}), ...(origin.runUrl !== undefined ? { runUrl: origin.runUrl } : {}),
+        ...(origin.run ? { run: origin.run } : {})
+    };
+}
+function facts(source) {
+    const { route, fixture, cohort, area, flags, covers, inventory } = source;
+    return { ...(route ? { route } : {}), ...(fixture ? { fixture } : {}), ...(cohort ? { cohort } : {}), ...(area ? { area } : {}), ...(flags?.length ? { flags } : {}), ...(covers?.length ? { covers } : {}), ...(inventory ? { inventory } : {}) };
+}
+/**
+ * The input of `publishChecks` for the states one collector (or one shard) captured under one profile. Throws when a state id
+ * repeats, because the second would silently replace the first. A state without a `status` is `passed`: it was captured.
+ *
+ * @example
+ * ```ts
+ * await publishChecks(store, uiStateLayer({
+ *   producer: 'web-capture', recordedAtMs: Date.now(), environment: 'mobile-web', profile: { viewport: '390x844', scheme: 'dark' }, shard: '1/4',
+ *   states: [{ id: 'checkout/payment', title: 'Payment', route: '/checkout', covers: ['payment-form'], screenshot: { data: png } }]
+ * }));
+ * ```
+ */
+export function uiStateLayer(input) {
+    const seen = new Set();
+    const checks = input.states.map(state => {
+        if (seen.has(state.id))
+            throw new Error(`uiStateLayer: the state "${state.id}" appears twice; give each state of one profile its own id`);
+        seen.add(state.id);
+        const shot = state.screenshot;
+        const attachments = shot ? [{
+                name: shot.name ?? `${state.id.replace(/[^\w.-]+/g, '-')}.png`, role: 'screenshot', contentType: shot.contentType ?? 'image/png',
+                ...(shot.data ? { data: shot.data } : {}), ...(shot.base64 ? { base64: shot.base64 } : {}), ...(shot.uri ? { uri: shot.uri } : {}),
+                ...(shot.width !== undefined ? { width: shot.width } : {}), ...(shot.height !== undefined ? { height: shot.height } : {})
+            }] : undefined;
+        const labels = { ...state.labels, ...(input.shard ? { shard: input.shard } : {}) };
+        return {
+            id: state.id, title: state.title ?? state.id, status: state.status ?? 'passed', detail: state.detail ?? '',
+            ...(state.durationMs !== undefined ? { durationMs: state.durationMs } : {}),
+            ...(attachments ? { attachments } : {}),
+            ...(Object.keys(labels).length ? { labels } : {}), ...(state.tags?.length ? { tags: [...state.tags] } : {}),
+            extensions: { [UI_STATE_EXTENSION]: facts(state) }
+        };
+    });
+    return { ...common(input, UI_STATE_KIND, 'UI states'), checks };
+}
+/**
+ * The input of `publishChecks` for what is expected: states that should be captured under this profile and, with `inventory`,
+ * surfaces the product is known to have. Every entry is `not-run`, so a plan never counts as a pass, and it fills a slot of
+ * its own (kind `ui-plan`), so a capture never erases it and it never hides a capture. Throws when an id repeats.
+ */
+export function uiPlanLayer(input) {
+    const seen = new Set();
+    const checks = input.states.map(state => {
+        if (seen.has(state.id))
+            throw new Error(`uiPlanLayer: "${state.id}" appears twice`);
+        seen.add(state.id);
+        return {
+            id: state.id, title: state.title ?? state.id, status: 'not-run', detail: state.inventory ? 'In the product inventory' : 'Expected, not captured yet',
+            ...(input.shard ? { labels: { shard: input.shard } } : {}),
+            extensions: { [UI_STATE_EXTENSION]: facts(state) }
+        };
+    });
+    return { ...common(input, UI_PLAN_KIND, 'UI states expected'), checks };
+}