@crvouga/atlas 1.13.0 → 1.15.0

package/docs/reference/reports.md

@@ -1694,6 +1694,16 @@ Like {@link summarizeEvidence} for the checks of a part: a video that declares n
 declares none, takes the scope `inherited` from its part or layer (the nearest declaration of the two, see
 `effectiveScope`). Without `inherited` it is the same as `summarizeEvidence`.
 
+#### `summarizeStoredEvidence`
+
+```ts
+export function summarizeStoredEvidence(inherited: EvidenceScope | undefined, unstored: ReadonlySet<string> | undefined, ...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined
+```
+
+Like {@link summarizeEvidenceIn}, knowing which bundle keys the layer names but does not hold (`unstored`, see
+`unstoredKeys`): a video whose only bytes are such a key is `available: false`, never a recording. Without
+`unstored` it is the same as `summarizeEvidenceIn`.
+
 #### `summarizeLayerEvidence`
 
 ```ts
@@ -1703,6 +1713,14 @@ export function summarizeLayerEvidence(...holders: readonly EvidenceHolder[]): E
 Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
 part is owned by the `layer`, not by a check.
 
+#### `summarizeStoredLayerEvidence`
+
+```ts
+export function summarizeStoredLayerEvidence(unstored: ReadonlySet<string> | undefined, ...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined
+```
+
+Like {@link summarizeLayerEvidence}, knowing which bundle keys the layer names but does not hold (see {@link summarizeStoredEvidence}).
+
 #### `isVideoAttachment`
 
 ```ts
@@ -1804,6 +1822,16 @@ export function bundleKeysOf(holder: EvidenceHolder): string[]
 
 Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none.
 
+#### `unstoredKeys`
+
+```ts
+export function unstoredKeys(layer: EvidenceHolder & { readonly parts: readonly (EvidenceHolder & { readonly checks: readonly EvidenceHolder[] })[]; readonly bundle: Readonly<Record<string, unknown>> }): string[]
+```
+
+The bundle keys that attachments of a layer, its parts and their checks name, but that the layer's `bundle` index does
+not hold: files the producer referenced and never stored. Empty for a layer whose every file is there. This reads only
+the index, never a blob, so it is cheap enough to ask of every layer as it is read.
+
 ### Live evidence from running suites
 
 Source: `packages/reports/src/evidence-live.ts`. Import: `@crvouga/atlas/reports/evidence-live`
@@ -2109,7 +2137,7 @@ export type VideoRef = {
   readonly tags?: readonly string[];
   /** What identifies the bytes (digest, bundle key or address); references with the same one are the same recording. Absent when `available` is false. */
   readonly recording?: string;
-  /** False when the reference names no bytes at all (no bundle key, address or inline text), so it can never be played. */
+  /** False when the reference names no bytes at all (no bundle key, address or inline text), or a bundle key that the layer's own bundle does not hold, so it can never be played. */
   readonly available: boolean;
   /** What this recording shows, as declared for it: its own `scope`, else its attempt's, check's, part's or layer's. Absent when none declared one: its scope is unknown, not live, physical or audible. */
   readonly scope?: EvidenceScope;
@@ -2128,7 +2156,7 @@ export type VideoCounts = {
   readonly references: number;
   /** Distinct playable recordings: identical bytes referenced twice are one. */
   readonly recordings: number;
-  /** References that name no bytes. A report that predates availability metadata has none of these and none of the others. */
+  /** References that name no bytes, or bytes the layer does not hold. A report that predates availability metadata has none of these and none of the others. */
   readonly unavailable: number;
 };
 ```
@@ -2252,6 +2280,8 @@ export type LayerRow = {
   readonly durationMs: number | null;
   /** What this result carries beyond its outcome. Absent when nothing. */
   readonly evidence?: EvidenceSummary;
+  /** For a check of a `ui-state` or `ui-plan` part: its picture and declared facts, so a catalog is listed without another request (see `ui-state.ts`). Absent for every other kind. */
+  readonly state?: UiStateFact;
   /** What became of this check's expected recording: `uploaded`, `referenced`, `skipped`, `unresolved` or `not-applicable`, with a reason when it is not uploaded. Absent when the check declared no expectation. Independent of `status`. */
   readonly recording?: { readonly state: string; readonly reason?: string };
 };
@@ -4581,7 +4611,9 @@ Serialises parameters as JSON key/value pairs sorted by key, so equal parameter
 export function isDiagnosticKind(kind: string): boolean
 ```
 
-Whether a part `kind` only qualifies an outcome (today only `performance`) and so is not counted as a check when anything else is recorded.
+Whether a part `kind` only qualifies an outcome and so is not counted as a check when anything else is recorded: a
+`performance` timing, or a `ui-plan` entry (what a UI catalog expects, which a capture of the same state replaces in the
+tests' view). It never decides a slot: both still fill their own.
 
 #### `isOpinionKind`
 
@@ -4866,7 +4898,7 @@ Reads one captured file (a screenshot, a frame, a recorded report) of a layer, o
 export function layerSummary(layer: ReportLayer): LayerSummary
 ```
 
-Drops a layer's bundle index, leaving the summary composition reads.
+Drops a layer's bundle index, leaving the summary composition reads, plus the bundle keys its attachments name that the bundle does not hold (`unstored`), so a video that was never stored is not counted as a recording.
 
 ### Layer types
 
@@ -4927,6 +4959,8 @@ export type LayerSummary = LayerExtras & {
   readonly source: SourceRecord | null;
   /** Where the layer's timelines and captured files are read from: its own bundle (`layer`), an older commit-keyed recording (`commit`), or nowhere (`null`). */
   readonly recording: { readonly type: 'layer' } | { readonly type: 'commit'; readonly sha: string; readonly source: string } | null;
+  /** Bundle keys that attachments name but the layer's bundle does not hold, read from the layer's index when its summary was made (see `unstoredKeys`). Absent when there are none. In memory only: never part of the layer document. */
+  readonly unstored?: readonly string[];
 };
 ```
 
@@ -8158,6 +8192,319 @@ export async function readRunFile(store: ObjectStore, id: string, relative: stri
 
 Reads one file of a run, or `null` when it is missing. Also `null`, without reading, for an `id` that is not a plain run name or a `relative` path with an empty, `.`, `..` or backslash segment, so a path can never leave the run.
 
+### Run comparison
+
+Source: `packages/reports/src/run-compare.ts`. Import: `@crvouga/atlas/reports/run-compare`
+
+Answers "what changed between these two runs?" without claiming more than the evidence supports. A run is a pinned
+source: the comparison reads two {@link RunDetail}s as they are and never reaches for a newer run. Pure functions,
+safe in a browser; nothing here changes a status, a slot or a winner.
+
+The rules, each of which keeps a comparison from looking more certain than it is:
+
+- **Identity is explicit.** Results are paired by the check they record (`TestSummary.key`: spec path and check id),
+  then by the condition they were recorded under (kind, producer, environment, parameters). A title is never what
+  pairs two results. A result with the same check but another condition is paired as well, marked as recorded under
+  different conditions, and is not framed as the same experiment. Results of one side with no partner are `added`
+  (only the candidate has them) or `removed` (only the baseline has them); a `removed` result is not a regression,
+  because the candidate may not have run, renamed or dropped it, and the comparison cannot tell which.
+- **Not run is not regressed.** A result that did not run, or is still running, on either side is `unknown`; it is
+  counted as neither a pass nor a failure. Only a completed result against a completed result is a movement.
+- **A changed promise is not the same experiment.** When the wording of a behavior differs between the two sides, the
+  pair is `not-comparable` and both outcomes are shown beside the changed promise instead of as a regression or a
+  recovery. A different spec-file revision with the same wording is disclosed beside the movement: a fingerprint is
+  of the whole file, so it cannot say that this behavior's own promise changed. A revision that was not recorded is
+  unknown, never the same.
+- **Figures are compared like for like.** Product latency and reliability are compared only when both sides were
+  recorded under the same conditions and support the figure; otherwise the reason is given and no improvement is
+  computed. A metric only one side has is named, not compared.
+
+See docs/ui.md
+
+#### `COMPARE_GROUPS`
+
+```ts
+export const COMPARE_GROUPS = …
+```
+
+Where a pair of results (or one result with no partner) stands, in the order a review reads them.
+
+#### `CompareGroup`
+
+```ts
+export type CompareGroup = (typeof COMPARE_GROUPS)[number];
+```
+
+One of {@link COMPARE_GROUPS}.
+
+#### `COMPARE_GROUP_TEXT`
+
+```ts
+export const COMPARE_GROUP_TEXT: Readonly<Record<CompareGroup, { readonly label: string; readonly meaning: string }>>
+```
+
+What each group is called and what it does and does not say.
+
+#### `PromiseState`
+
+```ts
+export type PromiseState = 'same' | 'changed' | 'revision-differs' | 'unknown';
+```
+
+Whether the promise (what the behavior says should happen) is the same on both sides: `same` (same wording and the
+same recorded spec revision), `changed` (the wording differs), `revision-differs` (same wording, another spec-file
+revision), or `unknown` (a revision was not recorded on a side, so nothing can be said).
+
+#### `PromiseReading`
+
+```ts
+export type PromiseReading = {
+  readonly state: PromiseState;
+  readonly baselineTitle: string | null;
+  readonly candidateTitle: string | null;
+  readonly baselineRevision: string | null;
+  readonly candidateRevision: string | null;
+  /** In words, for a person. */
+  readonly reasons: readonly string[];
+};
+```
+
+What is known about whether the promise changed, and why.
+
+#### `Condition`
+
+```ts
+export type Condition = {
+  readonly kind: string | null;
+  readonly producer: string;
+  readonly environment: string | null;
+  readonly parameters: Readonly<Record<string, string>>;
+};
+```
+
+The condition a result was recorded under: with the check, what makes it its own result.
+
+#### `conditionOf`
+
+```ts
+export function conditionOf(result: Pick<RunResult, 'kind' | 'producer' | 'environment' | 'parameters'>): Condition
+```
+
+The condition of a result. A server that does not send `kind` leaves it null: unknown, equal only to another unknown.
+
+#### `conditionId`
+
+```ts
+export function conditionId(condition: Condition): string
+```
+
+A stable text for a condition, equal exactly when two conditions are.
+
+#### `conditionDifferences`
+
+```ts
+export function conditionDifferences(baseline: Condition, candidate: Condition): string[]
+```
+
+How two conditions differ, in words; empty when they are the same.
+
+#### `ComparedResult`
+
+```ts
+export type ComparedResult = {
+  /** Identifies the pair within one comparison: the check, and the condition of each side. Stable for the same two runs. */
+  readonly id: string;
+  /** The check's identity (`TestSummary.key`). */
+  readonly key: string;
+  /** The check's title: the candidate's when it has one, else the baseline's. */
+  readonly title: string;
+  readonly specPath: string | null;
+  readonly baseline: RunResult | null;
+  readonly candidate: RunResult | null;
+  readonly group: CompareGroup;
+  /** One sentence saying what happened, and what is not known. */
+  readonly summary: string;
+  readonly promise: PromiseReading;
+  /** How the two conditions differ, in words, when both sides have a result and they were recorded under different conditions. */
+  readonly conditions: readonly string[];
+  /** What a reader must not assume about this pair, in words. */
+  readonly caveats: readonly string[];
+};
+```
+
+One behavior's results on the two sides.
+
+#### `RunComparison`
+
+```ts
+export type RunComparison = {
+  readonly baseline: RunSummary;
+  readonly candidate: RunSummary;
+  /** Every pair and every unpaired result, in the order of {@link COMPARE_GROUPS}, then spec and title. */
+  readonly results: readonly ComparedResult[];
+  readonly counts: Readonly<Record<CompareGroup, number>>;
+  /** What a reader must not assume about the two runs as a whole: the same run on both sides, different branches, a candidate older than the baseline. */
+  readonly notes: readonly string[];
+};
+```
+
+The whole comparison of two pinned runs.
+
+#### `shortRevision`
+
+```ts
+export function shortRevision(revision: string | null | undefined): string
+```
+
+Short form of a spec fingerprint, to show.
+
+#### `recordedTitle`
+
+```ts
+export function recordedTitle(result: Pick<RunResult, 'title' | 'recordedTitle'>): string
+```
+
+The wording a run recorded for a check: what that run's layer called it, else the check's newest title.
+
+#### `compareRuns`
+
+```ts
+export function compareRuns(baseline: RunDetail, candidate: RunDetail): RunComparison
+```
+
+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`).
+
+- `baseline`: The run to compare against.
+
+- `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');
+```
+
+#### `MetricComparison`
+
+```ts
+export type MetricComparison =
+  | { readonly state: 'compared'; readonly name: string; readonly baseline: LatencySummary; readonly candidate: LatencySummary; readonly change: LatencyChange; readonly reasons: readonly string[] }
+  | { readonly state: 'incompatible'; readonly name: string; readonly baseline: LatencySummary; readonly candidate: LatencySummary; readonly change: LatencyChange | null; readonly reasons: readonly string[] }
+  | { readonly state: 'baseline-only' | 'candidate-only'; readonly name: string; readonly summary: LatencySummary; readonly reasons: readonly string[] };
+```
+
+What one product-latency metric shows on the two sides.
+
+#### `compareProductLatency`
+
+```ts
+export function compareProductLatency(baseline: readonly LatencyEntry[], candidate: readonly LatencyEntry[], conditionsDiffer: readonly string[] = []): MetricComparison[]
+```
+
+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.
+
+#### `ReliabilityComparison`
+
+```ts
+export type ReliabilityComparison = {
+  /** True only when both figures are established, were counted in the same scope and against the same recorded spec revision. */
+  readonly comparable: boolean;
+  readonly baseline: ReliabilityRate;
+  readonly candidate: ReliabilityRate;
+  /** Candidate minus baseline, in percentage points, only when comparable. */
+  readonly points?: number;
+  /** `higher` or `lower` only when the two intervals do not overlap; `indistinguishable` when they do. Absent when not comparable. */
+  readonly direction?: 'higher' | 'lower' | 'indistinguishable';
+  /** Why no change is stated, or what qualifies one. */
+  readonly reasons: readonly string[];
+};
+```
+
+How reliable a check was on each side, and whether the two figures can be set against each other.
+
+#### `reliabilityScopeAt`
+
+```ts
+export function reliabilityScopeAt(result: Pick<RunResult, 'environment' | 'producer' | 'parameters' | 'specRevision'>, run: Pick<RunSummary, 'endedAtMs'>): ReliabilityScope
+```
+
+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.
+
+#### `compareReliability`
+
+```ts
+export function compareReliability(baseline: ReliabilityDocument, candidate: ReliabilityDocument, conditionsDiffer: readonly string[] = []): ReliabilityComparison
+```
+
+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.
+
+#### `StepLike`
+
+```ts
+export type StepLike = { readonly name: string; readonly offsetMs?: number | undefined };
+```
+
+The part of a recorded step this module reads.
+
+#### `AlignedStep`
+
+```ts
+export type AlignedStep = {
+  readonly name: string;
+  /** Milliseconds after the check began, on each side; absent when that side did not record it or its time. */
+  readonly baselineOffsetMs?: number;
+  readonly candidateOffsetMs?: number;
+  readonly onBaseline: boolean;
+  readonly onCandidate: boolean;
+};
+```
+
+One step, found on one or both sides.
+
+#### `StepAlignment`
+
+```ts
+export type StepAlignment = {
+  /** `aligned`: some step is on both sides with a time on both (a recording can be sought to it); `unaligned`: otherwise. */
+  readonly state: 'aligned' | 'unaligned';
+  readonly steps: readonly AlignedStep[];
+  /** The steps with a time on both sides: where both recordings can be sought together. */
+  readonly seekable: readonly (AlignedStep & { readonly baselineOffsetMs: number; readonly candidateOffsetMs: number })[];
+  /** Whether the two lists of step names differ (the steps themselves are part of the promise). */
+  readonly differs: boolean;
+  /** In words, why the recordings are or are not aligned. */
+  readonly explanation: string;
+};
+```
+
+How the recorded steps of two results line up.
+
+#### `alignSteps`
+
+```ts
+export function alignSteps(baseline: readonly StepLike[], candidate: readonly StepLike[]): StepAlignment
+```
+
+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.
+
 ### S3 object store
 
 Source: `packages/reports/src/s3-store.ts`. Import: `@crvouga/atlas/reports/s3-store`
@@ -9616,6 +9963,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;
 };
 ```
 
@@ -9982,6 +10337,589 @@ export type ReportData = HtmlReportBundle & {
 
 A run's tests (`HtmlReportBundle`) plus the document title shown for them, for the standalone / Solid report viewer.
 
+### Writing a UI catalog from any collector
+
+Source: `packages/reports/src/ui-catalog-publish.ts`. Import: `@crvouga/atlas/reports/ui-catalog-publish`
+
+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
+
+#### `UiPicture`
+
+```ts
+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;
+};
+```
+
+A picture to store with a capture: its bytes (`data`, `base64`), or where it already is (`uri`).
+
+#### `UiStateCapture`
+
+```ts
+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 captured state. `id` must be stable across runs: it is how a new capture replaces an old one.
+
+#### `UiStatePlan`
+
+```ts
+export type UiStatePlan = UiStateFacts & {
+  readonly id: string;
+  readonly title?: string;
+};
+```
+
+One expected state, or (with `inventory`) one surface of the product's inventory.
+
+#### `UiLayerOrigin`
+
+```ts
+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 };
+};
+```
+
+What every layer of a catalog says about where and when it was recorded.
+
+#### `uiStateLayer`
+
+```ts
+export function uiStateLayer(input: UiLayerOrigin & { readonly states: readonly UiStateCapture[] }): PublishChecksInput
+```
+
+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 } }]
+}));
+```
+
+#### `uiPlanLayer`
+
+```ts
+export function uiPlanLayer(input: UiLayerOrigin & { readonly states: readonly UiStatePlan[] }): 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.
+
+### UI catalog
+
+Source: `packages/reports/src/ui-catalog.ts`. Import: `@crvouga/atlas/reports/ui-catalog`
+
+A browsable inventory of a product's user interface, computed from layers and nothing else: each **state** (a screen, or
+one state of a screen) captured once per **profile** (viewport, color scheme, device), with the facts needed to find and
+trust it, and what should exist but has not been captured yet. `uiCatalog` is a pure function of the winning results of
+the layers it is given, so it inherits the report contract's laws: the same layers in any order, split any way across
+backends, shards and machines, give the same catalog; a layer changes only the cells it fills; an unreadable layer is
+absent, never captured. It imports no collection framework and knows nothing about how a picture was taken.
+
+How the convention maps onto the layer format is in {@link ./ui-state}: a state is a check of a `ui-state` part, a profile
+is the layer's `environment` and `parameters`, the expected set is a `ui-plan` part. The viewer computes the catalog from
+the report it already streams (so it fills in as results arrive), and the server answers the same document at
+`GET /api/reports/ui-catalog`.
+
+See docs/ui-catalog.md
+See docs/report-contract.md#how-layers-compose
+
+#### `UI_CATALOG_VERSION`
+
+```ts
+export const UI_CATALOG_VERSION = …
+```
+
+The `schemaVersion` of the catalog document.
+
+#### `UiProfile`
+
+```ts
+export type UiProfile = {
+  /** Stable identity: the environment and the sorted parameters. */
+  readonly key: string;
+  /** The client (`desktop-web`, `ios`…), or null when the layer named none. */
+  readonly environment: string | null;
+  /** The layer's other choices, such as `{ viewport: '390x844', scheme: 'dark' }`. */
+  readonly parameters: Readonly<Record<string, string>>;
+  /** For a person: the client and each parameter's value. */
+  readonly label: string;
+};
+```
+
+One profile: the client and the choices a state was captured under. Its `key` identifies it across layers.
+
+#### `UiCoverage`
+
+```ts
+export type UiCoverage = 'captured' | 'failed' | 'capturing' | 'skipped' | 'missing';
+```
+
+How one state stands in one profile. `captured`: a capture passed. `failed`: it was attempted and failed (its `detail`
+says why). `capturing`: it is being taken now. `skipped`: a producer recorded it as not run. `missing`: expected, and
+nothing has been recorded. Only `captured` is ever shown as captured; every other value means there is no picture to trust.
+
+#### `UI_COVERAGE`
+
+```ts
+export const UI_COVERAGE = …
+```
+
+The values of {@link UiCoverage}, in the order a person reads them.
+
+#### `UiImage`
+
+```ts
+export type UiImage = UiScreenshot & {
+  /** Where the stored bytes are, relative to the reports API root (`/layers/<layer>/blobs/attachments/<sha256>`). Absent for an address-only or omitted picture. */
+  readonly path?: string;
+};
+```
+
+A picture, with the address a browser loads it from.
+
+#### `UiOrigin`
+
+```ts
+export type UiOrigin = {
+  readonly layer: string;
+  readonly backend: string;
+  readonly producer: string;
+  readonly recordedAtMs: number;
+  readonly sha: string | null;
+  readonly branch: string | null;
+  readonly runUrl: string | null;
+  readonly freshness?: 'unknown' | 'modified';
+};
+```
+
+Where a capture came from: the layer, the backend that holds it, and the provenance the layer recorded.
+
+#### `UiCapture`
+
+```ts
+export type UiCapture = {
+  readonly status: EvidenceStatus;
+  /** Why it failed or was skipped; empty otherwise. */
+  readonly detail: string;
+  readonly durationMs: number | null;
+  /** The picture, or null when the capture has none (or it was left out: see `omitted`). */
+  readonly image: UiImage | null;
+  /** The check's labels: what describes the capture without splitting it (a `shard`, a `browser`). */
+  readonly labels: Readonly<Record<string, string>>;
+  readonly origin: UiOrigin;
+  /** How many other captures of this cell exist from other producers. The winner is the one the report contract picks. */
+  readonly alternatives: number;
+};
+```
+
+The winning capture of one cell.
+
+#### `UiCell`
+
+```ts
+export type UiCell = {
+  readonly profile: UiProfile;
+  readonly coverage: UiCoverage;
+  /** Whether a plan expects this state in this profile: `declared`; `undeclared` when plans exist and none names it; `unknown` when no plan was published at all. */
+  readonly expected: 'declared' | 'undeclared' | 'unknown';
+  readonly capture: UiCapture | null;
+  /** The layer of the plan that expects it, when one does. */
+  readonly planned: { readonly layer: string; readonly backend: string } | null;
+};
+```
+
+One state in one profile.
+
+#### `UiCatalogState`
+
+```ts
+export type UiCatalogState = {
+  /** The check id the producers gave it. */
+  readonly id: string;
+  readonly title: string;
+  readonly route: string | null;
+  readonly fixture: string | null;
+  readonly cohort: string | null;
+  readonly area: string | null;
+  readonly flags: readonly string[];
+  /** The surfaces it covers. */
+  readonly covers: readonly string[];
+  /** The producers that captured or planned it. */
+  readonly producers: readonly string[];
+  /** One cell per profile, ordered by the profile's label. */
+  readonly cells: readonly UiCell[];
+};
+```
+
+One state of the product's interface, across its profiles.
+
+#### `UiSurface`
+
+```ts
+export type UiSurface = {
+  readonly id: string;
+  /** True when a `ui-plan` inventory entry names it: the product is known to have it. */
+  readonly inventoried: boolean;
+  /** States that cover it. */
+  readonly states: number;
+  /** Of those, states with at least one captured profile. */
+  readonly captured: number;
+  /** `covered`: some covering state is captured. `uncaptured`: states cover it and none is captured yet. `uncovered`: no state covers it. */
+  readonly status: 'covered' | 'uncaptured' | 'uncovered';
+};
+```
+
+One surface of the product: an inventory entry, or something a state says it covers.
+
+#### `UiFacetValue`
+
+```ts
+export type UiFacetValue = { readonly value: string; readonly count: number; readonly label?: string };
+```
+
+A value of a facet and how many states have it.
+
+#### `UiCatalogFacets`
+
+```ts
+export type UiCatalogFacets = {
+  readonly profiles: readonly UiFacetValue[];
+  readonly coverage: readonly UiFacetValue[];
+  readonly areas: readonly UiFacetValue[];
+  readonly routes: readonly UiFacetValue[];
+  readonly cohorts: readonly UiFacetValue[];
+  readonly flags: readonly UiFacetValue[];
+  readonly surfaces: readonly UiFacetValue[];
+  readonly producers: readonly UiFacetValue[];
+};
+```
+
+The values each filter offers, over every state of the catalog.
+
+#### `UiCatalogSummary`
+
+```ts
+export type UiCatalogSummary = {
+  readonly states: number;
+  readonly profiles: number;
+  readonly cells: number;
+  readonly coverage: Readonly<Record<UiCoverage, number>>;
+  /** Captured or failed cells no plan expects. Zero when no plan was published, because then nothing is known to be unexpected. */
+  readonly undeclared: number;
+  /** Whether any plan (an expected set) was published. Without one, `missing` can only ever be zero. */
+  readonly planned: boolean;
+  readonly surfaces: number;
+  readonly uncoveredSurfaces: number;
+};
+```
+
+The catalog in numbers. Cells count a state once per profile.
+
+#### `UiCatalog`
+
+```ts
+export type UiCatalog = {
+  readonly schemaVersion: typeof UI_CATALOG_VERSION;
+  readonly version?: string;
+  readonly summary: UiCatalogSummary;
+  readonly profiles: readonly UiProfile[];
+  readonly states: readonly UiCatalogState[];
+  readonly surfaces: readonly UiSurface[];
+  readonly facets: UiCatalogFacets;
+  /** What could not be read. A state that depended on it is not in the catalog as captured. Filled by the caller who read the backends. */
+  readonly sources: { readonly layers: number; readonly backends: readonly BackendInfo[]; readonly notices: readonly string[] };
+};
+```
+
+The catalog, as `GET /api/reports/ui-catalog` answers it (`version` is the report's, when the caller knows it).
+
+#### `UiCatalogOptions`
+
+```ts
+export type UiCatalogOptions = {
+  /** The report's version, repeated in the document. */
+  readonly version?: string;
+  /** The backends, with whether each could be read. */
+  readonly backends?: readonly BackendInfo[];
+  /** What could not be read. */
+  readonly notices?: readonly string[];
+};
+```
+
+What a caller may say about how the layers were read.
+
+#### `uiProfile`
+
+```ts
+export function uiProfile(layer: Pick<LayerHeader, 'environment' | 'parameters'>): UiProfile
+```
+
+The profile of a layer: its environment and its other parameters.
+
+#### `uiCatalog`
+
+```ts
+export function uiCatalog(layers: readonly LayerEvidence[], options: UiCatalogOptions = {}): UiCatalog
+```
+
+The UI catalog of some layers (as the effective report holds them, or any set of {@link LayerEvidence}).
+
+Only rows of `ui-state` and `ui-plan` parts take part. The winner of every slot is decided by the report contract
+(`combineEvidence`), so the result does not depend on the order of `layers` or on how they are divided among backends. A
+state is the set of cells that share a check `id`; a cell is one profile of it. A cell is `captured` only when the winning
+capture passed; a plan that nothing has captured is `missing`. When no plan exists nothing is `missing` and nothing is
+`undeclared`: what is expected is then unknown, and the catalog says so (`summary.planned`).
+
+**Example**
+
+```ts
+const catalog = uiCatalog(effective.layers, { version: effective.version, backends: effective.backends });
+catalog.states.map(state => [state.id, state.cells.map(cell => cell.coverage)]);
+```
+
+#### `UiCatalogQuery`
+
+```ts
+export type UiCatalogQuery = {
+  /** Words (all of them) found in the id, title, route, fixture, cohort, area, flags, surfaces or producers. */
+  readonly q?: string;
+  readonly coverage?: readonly UiCoverage[];
+  /** Profile keys, as {@link UiProfile.key}. */
+  readonly profile?: readonly string[];
+  readonly area?: readonly string[];
+  readonly route?: readonly string[];
+  readonly cohort?: readonly string[];
+  readonly flag?: readonly string[];
+  /** Surfaces a state covers. */
+  readonly surface?: readonly string[];
+  readonly producer?: readonly string[];
+};
+```
+
+What a person narrows the catalog by. Every field is optional; nothing asked is everything. Values within a field are alternatives, fields combine with AND.
+
+#### `parseUiCatalogQuery`
+
+```ts
+export function parseUiCatalogQuery(params: URLSearchParams): UiCatalogQuery
+```
+
+Reads a query from URL search parameters (`q`, and the comma-separated {@link UiCatalogQuery} lists). Unknown coverage values are left out, never an error.
+
+#### `uiCatalogParams`
+
+```ts
+export function uiCatalogParams(query: UiCatalogQuery): URLSearchParams
+```
+
+A query as URL search parameters, the form {@link parseUiCatalogQuery} reads back.
+
+#### `isUiCatalogFiltered`
+
+```ts
+export function isUiCatalogFiltered(query: UiCatalogQuery): boolean
+```
+
+Whether a query narrows anything.
+
+#### `filterUiCatalog`
+
+```ts
+export function filterUiCatalog(catalog: UiCatalog, query: UiCatalogQuery): UiCatalog
+```
+
+The part of a catalog a query asks for. A state is kept when it matches the words and the fact filters; its cells are
+kept when they match the `profile` and `coverage` filters, and a state left with no cell is dropped. The summary is
+recomputed for what is kept; the profiles, surfaces, facets and sources stay those of the whole catalog, so the
+controls keep offering every choice.
+
+#### `pageUiCatalog`
+
+```ts
+export function pageUiCatalog(catalog: UiCatalog, page: { readonly limit?: number; readonly offset?: number }): UiCatalog & { readonly total: number; readonly offset: number; readonly limit: number }
+```
+
+A page of a catalog's states, for a document that would otherwise be large. The summary, facets and sources are the whole catalog's.
+
+#### `uiCatalogMarkdown`
+
+```ts
+export function uiCatalogMarkdown(catalog: UiCatalog): string
+```
+
+The catalog as Markdown for a person or an agent reading text: the summary in words, the surfaces that are not covered, and
+one line per state with its coverage in each profile. Only `captured` is called captured.
+
+### UI state conventions
+
+Source: `packages/reports/src/ui-state.ts`. Import: `@crvouga/atlas/reports/ui-state`
+
+How a captured UI state is written in a layer, using nothing but what the layer format already has. A **state** is a
+check in a part of kind `ui-state`: its `id` names the state, its `status` says how the capture went, a `screenshot`
+attachment is the picture, and the facts the producer declares about it (route, fixture, cohort, flags, the surfaces it
+covers) sit under the `atlas.ui-state` extension. A **profile** (viewport, color scheme, device) is the layer's
+`environment` and `parameters`, so a state captured at another viewport is another result, side by side. What is
+**expected** is a layer of kind `ui-plan` with the same ids and profiles, every check `not-run`.
+
+Nothing here decides a result: a status, a slot and a winner are what the report contract says they are. This module
+only reads the convention into a small optional row field ({@link UiStateFact}) so a viewer needs no second request to
+list a catalog. A producer that writes something else is still read; what cannot be read is left out, never rejected.
+
+See docs/ui-catalog.md
+
+#### `UI_STATE_KIND`
+
+```ts
+export const UI_STATE_KIND = …
+```
+
+The part kind of captured states.
+
+#### `UI_PLAN_KIND`
+
+```ts
+export const UI_PLAN_KIND = …
+```
+
+The part kind of the expected set: states (and surfaces) that should exist, whether or not they were captured.
+
+#### `UI_STATE_EXTENSION`
+
+```ts
+export const UI_STATE_EXTENSION = …
+```
+
+The check extension that carries the facts a producer declares about a state.
+
+#### `isUiKind`
+
+```ts
+export function isUiKind(kind: string): boolean
+```
+
+Whether a part kind belongs to the UI catalog (`ui-state` or `ui-plan`).
+
+#### `UiScreenshot`
+
+```ts
+export type UiScreenshot = {
+  readonly name: string;
+  readonly bundleKey?: string;
+  readonly uri?: string;
+  readonly contentType?: string;
+  readonly width?: number;
+  readonly height?: number;
+  readonly bytes?: number;
+  readonly sha256?: string;
+  /** Why the producer left the bytes out (`too-large`, `policy`…): a picture that was never taken is told apart from one left out. */
+  readonly omitted?: string;
+};
+```
+
+The picture of a captured state: a stored file (`bundleKey`), or an address (`uri`). Everything but `name` is optional.
+
+#### `UiStateFacts`
+
+```ts
+export type UiStateFacts = {
+  /** The address or screen the state is of (`/checkout/payment`). */
+  readonly route?: string;
+  /** The test data it was captured with. */
+  readonly fixture?: string;
+  /** The audience or account kind it shows (`new-customer`). */
+  readonly cohort?: string;
+  /** Feature flags that were on. */
+  readonly flags?: readonly string[];
+  /** The product surfaces (screens, components) this state covers, for coverage against an inventory. */
+  readonly covers?: readonly string[];
+  /** A grouping a person navigates by (`checkout`). */
+  readonly area?: string;
+  /** On a `ui-plan` check only: this entry is a surface of the product's inventory, not a state. Nothing is captured for it. */
+  readonly inventory?: boolean;
+};
+```
+
+The facts a producer declares about a state, under the `atlas.ui-state` extension. All optional, all strings or lists of strings.
+
+#### `UiStateFact`
+
+```ts
+export type UiStateFact = UiStateFacts & {
+  /** The check's picture: its `screenshot` attachment, else its first image. */
+  readonly screenshot?: UiScreenshot;
+};
+```
+
+What a row of a `ui-state` or `ui-plan` part carries for the catalog. Rides in the report row, only for those kinds.
+
+#### `uiStateFacts`
+
+```ts
+export function uiStateFacts(check: Pick<Check, 'extensions'>): UiStateFacts
+```
+
+The declared facts of a check, read from its `atlas.ui-state` extension. Strings are trimmed and bounded, lists are
+distinct and bounded, and anything of another shape is dropped; a check without the extension has no facts.
+
+#### `uiStateOf`
+
+```ts
+export function uiStateOf(kind: string, check: Pick<Check, 'extensions' | 'attachments'>): UiStateFact | undefined
+```
+
+What a check of a part of `kind` carries for the catalog: its declared facts and, in a `ui-state` part, its picture.
+`undefined` for any other kind, and for a UI check that carries neither, so ordinary rows stay as small as they were.
+
 ### Report viewer navigation state
 
 Source: `packages/reports/src/use-report-nav.ts`. Import: `@crvouga/atlas/reports/use-report-nav`