@crvouga/atlas 1.20.0 → 1.22.0

package/docs/reference/reports.md

@@ -1420,6 +1420,32 @@ export function summarize(combined: CombinedEvidence): ReportSummary
 
 Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all.
 
+#### `BackendLayers`
+
+```ts
+export type BackendLayers = {
+  /** Each layer that could be read, with the specs it recorded. A layer several backends hold appears once per backend. */
+  readonly loaded: readonly { readonly evidence: LayerEvidence; readonly specs: readonly SpecEntry[] }[];
+  /** Every backend given, sorted by id, with whether it could be listed. */
+  readonly backends: readonly BackendInfo[];
+  /** What could not be read, sorted and without repeats. */
+  readonly notices: readonly string[];
+};
+```
+
+Every layer of some backends, read but not yet composed.
+
+#### `readBackendLayers`
+
+```ts
+export async function readBackendLayers(backends: readonly BackendInput[], options: { readonly concurrency?: number } = {}): Promise<BackendLayers>
+```
+
+Reads every layer of every backend, superseded ones included, without composing them. This is what {@link combineBackends}
+starts from; a caller that needs layers a newer layer has replaced (to compare two commits, for example) reads them here.
+A backend that cannot be listed, or a layer that cannot be understood, is a notice, never an omission that looks like a pass.
+Throws for an invalid or repeated backend `id`, before anything is read.
+
 #### `combineBackends`
 
 ```ts
@@ -1474,6 +1500,220 @@ commutative and safe to repeat after a failure.
 A layer's catalog entry is copied last, and its manifest after its files, so a reader of `to` never sees an
 entry for a layer whose content has not arrived.
 
+### Reading critiques together
+
+Source: `packages/reports/src/critique-review.ts`. Import: `@crvouga/atlas/reports/critique-review`
+
+What a person or a command wants to know after critics have spoken: which states need polish first (`rankCritiques`), do the
+critics agree (`critiqueAgreement`), and what did people decide about the opinions (`markStanding`). These are readings of
+evidence that is already in the report. They count nothing toward a test total and decide no status, slot or gate: an
+opinion is an opinion, and so is a person's mark of it. Everything here is pure, so the viewer and `atlas critic review`
+read the same way.
+
+See docs/critics.md
+
+#### `RankedEntry`
+
+```ts
+export type RankedEntry<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = { readonly entry: E; readonly found: EntryCritique };
+```
+
+One entry and the critic's newest critique of it.
+
+#### `CritiqueRanking`
+
+```ts
+export type CritiqueRanking<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+  /** Entries judged at their current picture with a score, lowest first. */
+  readonly ranked: readonly RankedEntry<E>[];
+  /** How the list was ranked: by standing within the state kind (when every score has one), or by raw score. */
+  readonly rankedBy: 'standing-within-kind' | 'score';
+  /** Entries whose newest critique judged an earlier picture, or that the critic could not judge: listed, never ranked. */
+  readonly unranked: readonly RankedEntry<E>[];
+  /** Entries in scope the critic has not judged at all. */
+  readonly unjudged: number;
+};
+```
+
+The ranking of the entries one critic judged.
+
+#### `rankCritiques`
+
+```ts
+export function rankCritiques<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'>>(entries: readonly E[], critic: string | null, kind?: string): CritiqueRanking<E>
+```
+
+Ranks the entries a critic judged, lowest first, so the likeliest problems are reviewed first. A score is read as
+higher-is-better (the convention of the critique format). When every ranked score also carries its standing among the scores
+of the same state kind (`verdict.relative.percentile`) that standing ranks them instead, because a loading overlay is not
+compared with a full screen. An entry whose picture changed since it was judged, or that the critic could not judge, is not
+ranked but is returned; an entry the critic never saw is only counted.
+
+- `entries`: the entries in view.
+
+- `critic`: the critic whose critiques rank them.
+
+- `kind`: when given, only entries of this state kind.
+
+#### `Stance`
+
+```ts
+export type Stance = 'flags' | 'clear' | 'no-view';
+```
+
+What a critic's opinion amounts to for a reader who wants to know whether it flags the UI: it does, it does not, or it gives no view.
+
+#### `FLAGGING_PERCENTILE`
+
+```ts
+export const FLAGGING_PERCENTILE = …
+```
+
+A score at or below this standing within its state kind (the lowest quarter) counts as flagging, when the critic gave no label.
+
+#### `critiqueStance`
+
+```ts
+export function critiqueStance(critique: Critique): Stance
+```
+
+Whether a critique flags the UI. A failed critique, or one with nothing to go on, gives no view and is never read as fine.
+Otherwise the critic's own label decides (`needs-polish` flags, `ok` clears); with no label, findings flag; with neither, a score
+in the lowest quarter of its state kind (`relative.percentile` at most {@link FLAGGING_PERCENTILE}) flags and a higher one clears. A bare
+score with no standing gives no view, because a raw score is not absolute.
+
+#### `AgreementOutcome`
+
+```ts
+export type AgreementOutcome = 'agree-flag' | 'agree-clear' | 'disagree' | 'unclear';
+```
+
+How the critics who judged an entry at its current picture stand together.
+
+#### `CriticView`
+
+```ts
+export type CriticView = {
+  readonly critic: string;
+  readonly version: string;
+  readonly stance: Stance;
+  readonly score?: number;
+  readonly percentile?: number;
+  readonly label?: string;
+};
+```
+
+One critic's view of an entry.
+
+#### `AgreementRow`
+
+```ts
+export type AgreementRow<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+  readonly entry: E;
+  readonly views: readonly CriticView[];
+  readonly outcome: AgreementOutcome;
+};
+```
+
+An entry judged at its current picture by two or more critics, and whether they agree.
+
+#### `CritiqueAgreement`
+
+```ts
+export type CritiqueAgreement<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'> = CatalogEntry> = {
+  /** Entries judged by two or more critics at their current picture, those every critic flags first, then those they disagree on. */
+  readonly rows: readonly AgreementRow<E>[];
+  /** Entries only one critic has judged at the current picture: there is nothing to compare. */
+  readonly single: number;
+  /** The critics that have judged at least one entry at its current picture. */
+  readonly critics: readonly string[];
+};
+```
+
+The agreement of critics over some entries.
+
+#### `critiqueAgreement`
+
+```ts
+export function critiqueAgreement<E extends Pick<CatalogEntry, 'key' | 'state' | 'critiques'>>(entries: readonly E[], kind?: string): CritiqueAgreement<E>
+```
+
+Compares what the critics think of the same pictures. Only critiques of an entry's current picture count, and only each critic's
+newest. Critics that give no view ({@link critiqueStance}) are shown but do not make an entry agree or disagree: with fewer than
+two views the outcome is `unclear`, never agreement. An agreement is a reading for people; it is not a verdict, a status or a gate.
+
+#### `MarkStanding`
+
+```ts
+export type MarkStanding = {
+  /** `accepted`: only accepts. `dismissed`: only dismissals. `disputed`: reviewers disagree. `unmarked`: nobody has marked it at the current picture. */
+  readonly state: 'accepted' | 'dismissed' | 'disputed' | 'unmarked';
+  /** Reviewers who accepted it (their name, or the producer when they gave none). */
+  readonly accepted: readonly string[];
+  /** Reviewers who dismissed it. */
+  readonly dismissed: readonly string[];
+  /** Marks made about an earlier picture, which count for nothing now. */
+  readonly earlier: number;
+  /** The notes reviewers left, newest first. */
+  readonly notes: readonly string[];
+};
+```
+
+What people decided about one opinion (a critic's critique of an entry, or one of its findings).
+
+#### `markDecision`
+
+```ts
+export function markDecision(mark: Pick<EntryMark['mark'], 'decision'>): 'accept' | 'dismiss' | null
+```
+
+The decision a mark records: `accept`, `dismiss`, or `null` for a word this reader does not know (shown as written, counted as neither).
+
+#### `markStanding`
+
+```ts
+export function markStanding(marks: readonly EntryMark[], target: { readonly critic: string; readonly finding?: string | undefined }): MarkStanding
+```
+
+What reviewers decided about a critic's opinion of an entry. Only marks made about the picture the entry has now count; those
+about an earlier picture are tallied apart. Each reviewer's newest mark is the one that is held (the slot rule); a reviewer who
+accepted and later dismissed has dismissed. Marks with a decision this reader does not know count as neither.
+
+- `marks`: the entry's marks (`CatalogEntry.marks`).
+
+- `target`: the critic whose opinion is marked; `finding` names one finding, and without it the critique as a whole.
+
+### Critiques in report rows
+
+Source: `packages/reports/src/critique-row.ts`. Import: `@crvouga/atlas/reports/critique-row`
+
+A check of a part of kind `critique` carries an automated reviewer's opinion in `extensions["atlas.critique"]`
+(see `@crvouga/atlas/critics`). This module reads that extension into the optional `critique` field of a report row,
+so a viewer can list critiques without a second request, exactly as `state` carries a UI state. It decides nothing:
+the row's `status` says only whether the critic ran, a critique is never counted, and an extension this reader cannot
+read (a missing subject, a score that is not a number, a version it does not know) leaves the row as it was, an
+unknown opinion and never a pass.
+
+See docs/critics.md
+
+#### `critiqueOf`
+
+```ts
+export function critiqueOf(kind: string, check: Pick<Check, 'extensions'>): Critique | undefined
+```
+
+The critique a check of a part of `kind` carries, or `undefined` for any other kind and for an extension that cannot be
+read. Unknown fields and values inside a readable critique are kept.
+
+#### `critiqueMarkOf`
+
+```ts
+export function critiqueMarkOf(kind: string, check: Pick<Check, 'extensions'>): CritiqueMark | undefined
+```
+
+The mark a check of a part of `kind` carries (a reviewer's accept or dismiss of a critic's opinion, `atlas.critique-mark`), or
+`undefined` for any other kind and for an extension that cannot be read. Like a critique it is evidence: it decides nothing.
+
 ### Spec outline from a directory
 
 Source: `packages/reports/src/directory-outline.ts`. Import: `@crvouga/atlas/reports/directory-outline`
@@ -2330,6 +2570,10 @@ export type LayerRow = {
   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;
+  /** For a check of a `critique` part whose `atlas.critique` extension can be read: the opinion of an automated reviewer (see `critique-row.ts`). An opinion, never a result: it does not decide `status`, a slot or the gate. Absent for every other kind, and for an extension that cannot be read. */
+  readonly critique?: Critique;
+  /** For a check of a `critique` part whose `atlas.critique-mark` extension can be read: a person's accept or dismiss of a critic's opinion (see `critique-row.ts`). Evidence, never a result: it does not decide `status`, a slot or the gate. Absent for every other kind, and for an extension that cannot be read. */
+  readonly critiqueMark?: CritiqueMark;
   /** 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 };
 };
@@ -6992,6 +7236,32 @@ Whether the checks ran on exactly the commit they name. A CI checkout does. A de
 with edits to tracked files does not: its layer is `modified`, shown with a warning and never mistaken
 for the commit's own result. Outside git the origin is `unknown`.
 
+#### `keyValue`
+
+```ts
+export function keyValue(pair: string, flag: string): [string, string]
+```
+
+Splits `key=value` (the form of `--param` and `--label`), or throws a message naming `flag`.
+
+#### `parseTime`
+
+```ts
+export function parseTime(text: string | undefined, flag = '--recorded-at'): number | null
+```
+
+An ISO date or epoch milliseconds from a flag, `null` when the flag was not given. Throws a message naming `flag` for anything else.
+
+#### `executionOf`
+
+```ts
+export function executionOf(rest: readonly string[], env: Env, given?: unknown): LayerRun | undefined
+```
+
+The execution the producer named, from `--run-id`, `--run-title`, `--run-started-at`, `--run-ended-at` and then
+`ATLAS_RUN_ID` / `ATLAS_RUN_TITLE`, laid over a `run` the checks file gave. `undefined` when nothing names one, so the
+documented grouping (CI run URL, else branch@sha) applies. A title or time without an id is refused: it would have nothing to belong to.
+
 #### `runReportCommand`
 
 ```ts
@@ -7001,6 +7271,14 @@ export async function runReportCommand(argv: readonly string[]): Promise<number>
 `atlas report …` for a terminal: a mistake in the command or a path is a message on stderr and exit
 code 2, so a CI job can tell a broken invocation (2) from a report that does not pass (1).
 
+#### `wantsJson`
+
+```ts
+export function wantsJson(argv: readonly string[]): boolean
+```
+
+Does the command ask for a JSON document (`--format json` or `--json`) instead of prose?
+
 #### `reportMain`
 
 ```ts
@@ -7076,6 +7354,7 @@ It reads only immutable layers (`layers/index/…`), which is what makes "read o
 - `snapshot(): EffectiveEvidence` — The current report, ready to send. Built once per change, and only the layers that changed are rebuilt.
 - `json(): { readonly version: string; readonly text: string }` — The report as JSON text: exactly what `JSON.stringify({ ...snapshot(), active: [] })` writes, put together from the text of each layer, which is written once. `active` is what a store without live runs always sends: none.
 - `delta(since: string): { readonly text: string; readonly version: string } | null` — What differs between the report a viewer holds (named by its version) and the current one: the layers that changed in full, and the ids of those that no longer hold a winner. Null when that version is not remembered, and the viewer should ask for the whole report. See `applyEffectiveDelta`.
+- `changedSince(since: string): ReadonlySet<string> | null` — The ids of the layers that were added or changed (took a slot, or lost one) since the report a reader holds, named by its version: what `delta` sends, without the text. `null` when that version is not remembered, and the reader should take everything. Used to answer "what changed" about a view of the report, such as the entries of the UI catalog.
 - `get history(): TestHistory { return this.#history; }` — Every recorded result of every test and every run, as layers were folded in: what the test catalog, a test's history and the run list are built from. Read-only for callers; `history.rev` changes whenever a layer is taken in.
 - `superseded(): ReadonlySet<string>` — The ids of layers this index has read and that no longer decide any result. Removing one from its store cannot change the report (every slot it filled is held by a newer layer), which is what makes it safe for garbage collection to delete. A layer that failed to load, is hidden by `include`, or still holds a result is not here.
 - `stats()` — For `/readyz` and logs.
@@ -10556,6 +10835,578 @@ export type ReportData = HtmlReportBundle & {
 
 A run's tests (`HtmlReportBundle`) plus the document title shown for them, for the standalone / Solid report viewer.
 
+### The `atlas ui-catalog` command
+
+Source: `packages/reports/src/ui-catalog-cli.ts`. Import: `@crvouga/atlas/reports/ui-catalog-cli`
+
+`uiCatalogMain` is `atlas ui-catalog plan | publish | status | diff | export`: the UI catalog ({@link ./ui-catalog}) without
+a script. `plan` and `publish` turn a small JSON file (and the pictures beside it) into the layers of the expected set and of
+the captures; `status` reads every store and says whether the catalog is complete and free of failures; `diff` sets two
+commits against each other; `export` writes the catalog as one HTML file that needs no server. Like `atlas report`, it is
+written so it can be called from code and tests: it takes its arguments, environment, working directory, clock and git as
+parameters and returns the exit code, every command prints a JSON document with `--format json`, and a command that is wrong
+throws, which `runUiCatalogCommand` turns into a message (or a JSON error) and exit code 2.
+
+Nothing here knows how a picture was taken: the files it reads are the same data any collector can write. Publishing a
+catalog to a hosting platform is not a command: it would need that platform's credentials and API, which Atlas does not
+hold. The file `export` writes, or a folder of them, is what to hand to whatever hosts static files.
+
+Exit codes: 0 it worked, 1 it ran and the answer is no (an incomplete catalog, a failed capture, an unreadable store, a
+difference under `--fail-on-change`), 2 the command itself was wrong.
+
+See docs/ui-catalog.md
+See docs/agents.md
+
+#### `UI_CATALOG_USAGE`
+
+```ts
+export const UI_CATALOG_USAGE = …
+```
+
+The text `atlas ui-catalog --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of its entry in `docs/reference/cli.md`.
+
+#### `uiCatalogMain`
+
+```ts
+export async function uiCatalogMain(argv: readonly string[], io: ReportIo = { out: text => process.stdout.write(text) }): Promise<number>
+```
+
+`atlas ui-catalog …`. Returns the exit code. Throws on a mistake in the command (see {@link runUiCatalogCommand}).
+
+#### `runUiCatalogCommand`
+
+```ts
+export async function runUiCatalogCommand(argv: readonly string[]): Promise<number>
+```
+
+`atlas ui-catalog …` for a terminal: a mistake in the command or a path is a message on stderr and exit code 2, so a CI job can
+tell a broken invocation (2) from a catalog that needs attention (1). With `--format json` the mistake is a JSON document.
+
+### UI catalog comparison
+
+Source: `packages/reports/src/ui-catalog-diff.ts`. Import: `@crvouga/atlas/reports/ui-catalog-diff`
+
+What changed in the UI catalog between two commits, or between two profiles, without claiming more than the evidence
+supports. Pure functions of {@link UiCatalog} documents (and of the layers they came from), safe in a browser; nothing here
+changes a status, a slot or a winner.
+
+- **Two commits.** The catalog of a commit is the catalog of the layers recorded at that commit ({@link uiCatalogAtCommit}).
+  A state is paired with itself in the same profile. A layer replaces the older one of its slot, so the effective report no
+  longer holds an earlier commit's captures: compare from the layers themselves ({@link readBackendLayers}), which keep them.
+- **Two profiles.** Within one catalog, each state's cell in one profile is set beside its cell in another
+  ({@link diffUiProfiles}): desktop against mobile, light against dark.
+- **Pictures are compared by content.** Two captures have the same picture when their stored bytes have the same SHA-256.
+  A different hash means different bytes, which is not a measure of how different the pixels are. When a side has no
+  content hash (a picture given only by address, or left out), whether it changed is `unverified`, never "unchanged".
+- **A state only one side has** is `added` or `removed`. It may be new or renamed, or the other side's shard may not have
+  run, and the comparison cannot tell which: it is not called a regression.
+- **A capture that did not pass is not a picture.** A cell that failed, is being taken or was skipped on a side is a change of
+  `coverage`, never compared by picture.
+
+See docs/ui-catalog.md
+
+#### `UI_DIFF_VERSION`
+
+```ts
+export const UI_DIFF_VERSION = …
+```
+
+The `schemaVersion` of the comparison document.
+
+#### `UiCellChange`
+
+```ts
+export type UiCellChange = 'added' | 'removed' | 'coverage' | 'picture' | 'unverified' | 'unchanged';
+```
+
+How one pair of cells stands. `added`: only the after side has the cell. `removed`: only the before side has it.
+`coverage`: both have it and it stands differently (captured against failed, for example). `picture`: both captured and
+the bytes differ. `unverified`: both captured, but a side has no content hash, so whether the picture changed is unknown.
+`unchanged`: the same coverage and, when captured, the same bytes.
+
+#### `UI_CELL_CHANGES`
+
+```ts
+export const UI_CELL_CHANGES = …
+```
+
+The values of {@link UiCellChange}, in the order a review reads them.
+
+#### `UiDiffEntry`
+
+```ts
+export type UiDiffEntry = {
+  /** The state's id. */
+  readonly id: string;
+  /** Its title, from the after side when it has the state. */
+  readonly title: string;
+  /** The profile both sides are in (a comparison of commits), or null when the two sides are different profiles. */
+  readonly profile: UiProfile | null;
+  readonly before: UiCell | null;
+  readonly after: UiCell | null;
+  readonly change: UiCellChange;
+};
+```
+
+One state in one profile on each side.
+
+#### `UiCatalogDiff`
+
+```ts
+export type UiCatalogDiff = {
+  readonly schemaVersion: typeof UI_DIFF_VERSION;
+  /** How many entries are in each {@link UiCellChange}. */
+  readonly summary: Readonly<Record<UiCellChange, number>> & { readonly total: number };
+  /** Every pair, ordered by state id and then profile label. */
+  readonly entries: readonly UiDiffEntry[];
+};
+```
+
+A comparison, as `atlas ui-catalog diff --format json` prints it and the viewer shows it.
+
+#### `pictureIdentity`
+
+```ts
+export function pictureIdentity(image: UiImage | null | undefined): string | null
+```
+
+What identifies a picture's content: its recorded SHA-256, else the hash in a content-addressed bundle key
+(`attachments/<sha256>`), else `null`. A picture given only by address, or left out, has no identity here: its content is
+not Atlas's to vouch for.
+
+#### `diffUiCatalogs`
+
+```ts
+export function diffUiCatalogs(before: UiCatalog, after: UiCatalog): UiCatalogDiff
+```
+
+Sets the catalog of an earlier commit (`before`) against a later one (`after`): each state in each profile is paired with
+itself. A cell that is only a plan (`missing`) on one side is a change of coverage like any other. The order of the
+states in either catalog does not matter.
+
+#### `diffUiProfiles`
+
+```ts
+export function diffUiProfiles(catalog: UiCatalog, from: string, to: string): UiCatalogDiff
+```
+
+Sets one profile of a catalog (`from`, a {@link UiProfile.key}) against another (`to`): each state's cell in `from` beside its
+cell in `to`. A state that has a cell in only one of them is `added` or `removed`. Throws when the two are the same profile,
+because that compares a catalog with itself.
+
+#### `changedUiEntries`
+
+```ts
+export function changedUiEntries(diff: UiCatalogDiff): readonly UiDiffEntry[]
+```
+
+The entries of a comparison that changed, or all of them. A change the comparison cannot verify is a change worth looking at, so it is kept.
+
+#### `UiCommit`
+
+```ts
+export type UiCommit = {
+  readonly sha: string;
+  /** The branch of the newest layer recorded at the commit, or null. */
+  readonly branch: string | null;
+  /** When the newest layer at the commit was recorded, epoch milliseconds. */
+  readonly recordedAtMs: number;
+  /** How many layers were recorded at the commit. */
+  readonly layers: number;
+};
+```
+
+A commit that has layers of the catalog's producers.
+
+#### `uiCatalogCommits`
+
+```ts
+export function uiCatalogCommits(layers: readonly Pick<LayerEvidence['layer'], 'sha' | 'branch' | 'recordedAtMs' | 'freshness'>[]): UiCommit[]
+```
+
+The commits layers were recorded at, newest first. A layer with no commit is left out: it cannot be compared by commit.
+Layers recorded from a checkout with uncommitted changes (`freshness` `modified`) are not the commit's own result and are
+left out too, as the gate does by default for comparisons.
+
+#### `layersAtCommit`
+
+```ts
+export function layersAtCommit(layers: readonly LayerEvidence[], sha: string): LayerEvidence[]
+```
+
+The layers recorded at one commit (`sha` is the whole commit id, or a prefix of at least 7 hexadecimal digits that names
+exactly one commit among `layers`). Throws when a prefix names none, or more than one, so a comparison never silently uses
+the wrong commit.
+
+#### `uiCatalogAtCommit`
+
+```ts
+export function uiCatalogAtCommit(layers: readonly LayerEvidence[], sha: string, options: UiCatalogOptions = {}): UiCatalog
+```
+
+The UI catalog as it was recorded at one commit: only the layers recorded there take part. A state the commit's layers do
+not hold is absent, not failed. See {@link layersAtCommit} for how `sha` is matched.
+
+### UI catalog entries for critics
+
+Source: `packages/reports/src/ui-catalog-entries.ts`. Import: `@crvouga/atlas/reports/ui-catalog-entries`
+
+The UI catalog seen as a flat, orderable list that a separate process can iterate: one **entry** per captured state in
+one profile that has a stored picture, with the hash of that picture and the critiques already made of it. A critic
+lists entries a page at a time with a stable cursor, asks only for those that changed since a report version it holds,
+asks only for those a given critic has not judged at the picture they have now, and fetches the picture itself by the
+`image.path` (served by the same safe attachment path as every other file). Nothing here is stored: entries are a function of the
+report, so the same layers in any order give the same list, and a missed event is covered by the next read.
+
+Critiques are opinions, never results: they ride along as evidence of an entry and change nothing about whether a
+report passes.
+
+See docs/critics.md#reading-the-catalog
+See docs/ui-catalog.md
+
+#### `CATALOG_ENTRIES_VERSION`
+
+```ts
+export const CATALOG_ENTRIES_VERSION = …
+```
+
+The `schemaVersion` of the entries document.
+
+#### `UNKNOWN_STATE_KIND`
+
+```ts
+export const UNKNOWN_STATE_KIND = …
+```
+
+The state kind of an entry whose producers declared none. It is unknown, not `screen`.
+
+#### `EntryImage`
+
+```ts
+export type EntryImage = {
+  /** SHA-256 of the exact stored bytes, lowercase hex. */
+  readonly sha256: string;
+  /** Where the bytes are, relative to the reports API root: `/layers/<layer>/blobs/attachments/<sha256>`. */
+  readonly path: string;
+  readonly contentType?: string;
+  readonly width?: number;
+  readonly height?: number;
+  readonly bytes?: number;
+};
+```
+
+The picture an entry was captured as: the hash critiques are anchored to, and where its stored bytes are.
+
+#### `EntryCritique`
+
+```ts
+export type EntryCritique = {
+  readonly layer: string;
+  readonly producer: string;
+  readonly recordedAtMs: number;
+  /** The check's own status: whether the critic ran, never what it thought. */
+  readonly status: EvidenceStatus;
+  /** `current`: it judged this picture. `earlier-image`: the picture changed since, so the entry counts as not yet judged by that critic. */
+  readonly currency: 'current' | 'earlier-image';
+  readonly critique: Critique;
+};
+```
+
+A critique already made of an entry (any critic), and whether it judged the picture the entry has now.
+
+#### `EntryMark`
+
+```ts
+export type EntryMark = {
+  readonly layer: string;
+  /** `critic.review.<reviewer>`. */
+  readonly producer: string;
+  readonly recordedAtMs: number;
+  /** `current`: made about this picture. `earlier-image`: the picture changed since, so the mark is shown as about an earlier picture and counts for nothing now. */
+  readonly currency: 'current' | 'earlier-image';
+  readonly mark: CritiqueMark;
+};
+```
+
+A person's accept or dismiss of a critic's opinion about an entry that wins its slot, and whether it was made about the picture the entry has now.
+
+#### `CatalogEntry`
+
+```ts
+export type CatalogEntry = {
+  /** Stable identity, unique in the catalog: the state id, then `@` and the profile when it has one. */
+  readonly key: string;
+  readonly stateId: string;
+  readonly title: string;
+  readonly route: string | null;
+  readonly area: string | null;
+  /** The kind of UI state (`screen`, `overlay`, `loading`, `error`, `empty`…), or `unknown`. */
+  readonly state: string;
+  readonly profile: UiProfile;
+  readonly image: EntryImage;
+  /** The layer, backend and provenance of the capture. */
+  readonly origin: UiOrigin;
+  /** Critiques of this entry that win their slot, newest first. */
+  readonly critiques: readonly EntryCritique[];
+  /** Reviewers' marks (accept or dismiss) of those critiques that win their slot, newest first. Evidence: they never decide a result. */
+  readonly marks: readonly EntryMark[];
+};
+```
+
+One captured state in one profile, ready to be judged.
+
+#### `CatalogEntrySet`
+
+```ts
+export type CatalogEntrySet = {
+  readonly entries: readonly CatalogEntry[];
+  /** Captured cells without a stored picture of a known hash (given only by address, left out, or not yet archived). They are not entries. */
+  readonly unjudgeable: number;
+};
+```
+
+The entries of a report, and how many captured cells could not be offered for judging.
+
+#### `catalogEntryKey`
+
+```ts
+export function catalogEntryKey(stateId: string, profile: Pick<UiProfile, 'environment' | 'parameters'>): string
+```
+
+The key of the entry for a state in a profile. The state id alone when the profile says nothing; else
+`id@environment;name=value;…` with the parameters sorted and every part percent-encoded, so two profiles never share a key.
+
+#### `catalogEntries`
+
+```ts
+export function catalogEntries(layers: readonly LayerEvidence[]): CatalogEntrySet
+```
+
+The entries of some layers, in key order. Only a `captured` cell with a picture stored in its layer (`image.path`) and a
+known hash is an entry. Critiques are matched to entries by `subject.entryKey`, take the winner of each of their slots by
+the report contract, and are marked `earlier-image` when they judged other bytes.
+
+#### `isJudgedBy`
+
+```ts
+export function isJudgedBy(entry: Pick<CatalogEntry, 'critiques'>, critic: { readonly name: string; readonly version?: string }): boolean
+```
+
+Whether an entry has a current critique with a verdict from the critic (and, when given, its version). A failed critique is not a judgement: the next run retries it.
+
+#### `CatalogEntriesQuery`
+
+```ts
+export type CatalogEntriesQuery = {
+  /** Words (all of them) found in the key, title, route or area. */
+  readonly q?: string;
+  readonly area?: readonly string[];
+  /** Profile keys, as `UiProfile.key`. */
+  readonly profile?: readonly string[];
+  /** State kinds: `screen`, `overlay`, `loading`… */
+  readonly state?: readonly string[];
+  readonly route?: readonly string[];
+  /** Only entries with no current critique with a verdict from this critic (`name`, or `name@version`). */
+  readonly unjudgedBy?: { readonly name: string; readonly version?: string };
+  /** Only entries added or changed since this report version. A version the server does not remember is answered with everything. */
+  readonly since?: string;
+  /** Resume after the entry this cursor names. Opaque: take it from the previous page. */
+  readonly cursor?: string;
+  /** Entries per page. Default 100, at most 1000. */
+  readonly limit?: number;
+};
+```
+
+What a critic narrows the entries by. Every field is optional; nothing asked is everything. Values within a field are alternatives, fields combine with AND.
+
+#### `MAX_ENTRIES_LIMIT`
+
+```ts
+export const MAX_ENTRIES_LIMIT = …
+```
+
+The most entries one page holds.
+
+#### `parseCatalogEntriesQuery`
+
+```ts
+export function parseCatalogEntriesQuery(params: URLSearchParams): CatalogEntriesQuery
+```
+
+Reads a query from URL search parameters; the comma-separated lists, `q`, `unjudgedBy=name@version`, `since`, `cursor` and `limit`. A `limit` that is not a whole number is left out.
+
+#### `catalogEntriesParams`
+
+```ts
+export function catalogEntriesParams(query: CatalogEntriesQuery): URLSearchParams
+```
+
+A query as URL search parameters, the form {@link parseCatalogEntriesQuery} reads back.
+
+#### `encodeEntryCursor`
+
+```ts
+export function encodeEntryCursor(key: string): string
+```
+
+The opaque cursor after an entry.
+
+#### `decodeEntryCursor`
+
+```ts
+export function decodeEntryCursor(cursor: string): string | null
+```
+
+The key a cursor names, or `null` when it is not a cursor this reader made.
+
+#### `CatalogEntryPage`
+
+```ts
+export type CatalogEntryPage = {
+  /** The page, in key order. */
+  readonly entries: readonly CatalogEntry[];
+  /** Entries that match the query (all pages). */
+  readonly total: number;
+  /** The `cursor` of the next page, absent on the last. */
+  readonly nextCursor?: string;
+};
+```
+
+One page of entries and where to resume.
+
+#### `pageCatalogEntries`
+
+```ts
+export function pageCatalogEntries(all: readonly CatalogEntry[], query: CatalogEntriesQuery, changed: ReadonlySet<string> | null = null): CatalogEntryPage
+```
+
+One page of the entries that match a query, in key order. The order is by key and the cursor names the last key of a page, so
+a critic that iterates sees each entry exactly once however the catalog grows meanwhile (a new entry that sorts before the
+cursor is found by the next `since` read). `changed` is the set of layer ids that changed since `query.since`
+(`ReportIndex.changedSince`): `null` means the version was not remembered, and then everything matches.
+
+**Throws** Error when `query.cursor` is not a cursor.
+
+### UI catalog single-file export
+
+Source: `packages/reports/src/ui-catalog-export.ts`. Import: `@crvouga/atlas/reports/ui-catalog-export`
+
+The UI catalog as one HTML file that needs no server, no network and no build: open it from a disk, attach it to a ticket,
+host it anywhere that serves a file. Pictures are embedded as `data:` addresses, the manifest is embedded as JSON
+(`<script type="application/json" id="ui-catalog">`), and a few lines of script filter the states; with scripts off, every
+state is simply shown. It shows what the viewer's catalog shows, but it does not stream: it is the catalog at the moment it
+was made, and says when.
+
+Hosting platforms cap the size of one file, which is the reason a catalog is also a store and a viewer. The export keeps to a
+budget ({@link gatherUiPictures}): pictures past it are listed as left out with the reason, never silently dropped, and the
+manifest stays complete.
+
+Everything in the page is data from a test run. Text is escaped; only PNG, JPEG, GIF and WebP bytes whose first bytes say so
+are embedded (never SVG, never what a layer merely claims); a page address is linked only when it is `http` or `https`; the
+page carries a Content-Security-Policy that allows no network request at all.
+
+See docs/ui-catalog.md
+
+#### `UiExportPicture`
+
+```ts
+export type UiExportPicture = { readonly contentType: string; readonly data: Uint8Array };
+```
+
+A picture ready to embed.
+
+#### `UiExportOptions`
+
+```ts
+export type UiExportOptions = {
+  /** The page's title. Default `UI catalog`. */
+  readonly title?: string;
+  /** The pictures to embed, by {@link uiPictureKey}. A cell whose key is not here shows why it has no picture. */
+  readonly pictures?: ReadonlyMap<string, UiExportPicture>;
+  /** Why a picture that could not be embedded is not here, by {@link uiPictureKey}: shown in its place. */
+  readonly left?: ReadonlyMap<string, string>;
+  /** When the export was made, epoch milliseconds. It is stated on the page so nobody mistakes it for a live view. Default: now. */
+  readonly generatedAtMs?: number;
+};
+```
+
+What {@link uiCatalogHtml} may be given besides the catalog.
+
+#### `uiPictureKey`
+
+```ts
+export function uiPictureKey(capture: Pick<UiCapture, 'origin' | 'image'> | null | undefined): string | null
+```
+
+The key of a capture's picture in {@link UiExportOptions.pictures}: its layer and its bundle key, or `null` when the picture is not stored in a layer.
+
+#### `UiPictureWant`
+
+```ts
+export type UiPictureWant = { readonly key: string; readonly layer: string; readonly backend: string; readonly bundleKey: string; readonly bytes?: number };
+```
+
+One picture an export may embed.
+
+#### `uiPicturesWanted`
+
+```ts
+export function uiPicturesWanted(catalog: UiCatalog): UiPictureWant[]
+```
+
+The pictures of a catalog an export would embed, once each, in the order the page shows them. Only a cell that was captured, or
+that failed (a picture of what the page showed), and whose picture is stored in a layer, has one.
+
+#### `sniffImage`
+
+```ts
+export function sniffImage(data: Uint8Array): string | null
+```
+
+The media type a picture's first bytes say it has (`image/png`, `image/jpeg`, `image/gif`, `image/webp`), or `null` for anything else, SVG included.
+
+#### `UiPicturesGathered`
+
+```ts
+export type UiPicturesGathered = {
+  readonly pictures: ReadonlyMap<string, UiExportPicture>;
+  /** Why each picture that is not in `pictures` is not. */
+  readonly left: ReadonlyMap<string, string>;
+  /** Bytes embedded. */
+  readonly bytes: number;
+};
+```
+
+What {@link gatherUiPictures} found.
+
+#### `gatherUiPictures`
+
+```ts
+export async function gatherUiPictures(wanted: readonly UiPictureWant[], read: (want: UiPictureWant) => Promise<Uint8Array | null>, options: { readonly maxBytes: number }): Promise<UiPicturesGathered>
+```
+
+Reads the pictures an export wants through `read` (which returns the stored bytes of a picture, or `null` when the store
+no longer holds it) and keeps those that fit in `maxBytes` in total. A picture that is not stored, is not a PNG, JPEG, GIF or
+WebP, cannot be read, or would pass the budget is recorded in `left` with the reason; the pictures are taken in the page's
+order, so which are left out is deterministic. A `read` that throws is a picture left out, never a failed export.
+
+#### `uiCatalogHtml`
+
+```ts
+export function uiCatalogHtml(catalog: UiCatalog, options: UiExportOptions = {}): string
+```
+
+The whole catalog as one self-contained HTML document. See the module description for what it contains and how it treats
+the data in it. Deterministic for the same catalog, pictures and `generatedAtMs`.
+
+**Example**
+
+```ts
+const wanted = uiPicturesWanted(catalog);
+const { pictures, left } = await gatherUiPictures(wanted, want => readPicture(want), { maxBytes: 32 * 1024 * 1024 });
+await writeFile('catalog.html', uiCatalogHtml(catalog, { pictures, left }));
+```
+
 ### Writing a UI catalog from any collector
 
 Source: `packages/reports/src/ui-catalog-publish.ts`. Import: `@crvouga/atlas/reports/ui-catalog-publish`
@@ -10810,6 +11661,8 @@ export type UiCatalogState = {
   readonly fixture: string | null;
   readonly cohort: string | null;
   readonly area: string | null;
+  /** The kind of UI state the producers declared (`screen`, `overlay`, `loading`…), or null when none did. */
+  readonly kind: string | null;
   readonly flags: readonly string[];
   /** The surfaces it covers. */
   readonly covers: readonly string[];
@@ -11103,6 +11956,8 @@ export type UiStateFacts = {
   readonly covers?: readonly string[];
   /** A grouping a person navigates by (`checkout`). */
   readonly area?: string;
+  /** The kind of UI state: `screen`, `overlay`, `loading`, `error`, `empty`, or any other word. Open vocabulary. Critics judge a state against others of its kind, so declare it; when it is absent the kind is unknown. */
+  readonly kind?: 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;
 };