@crvouga/atlas 1.20.0 → 1.21.0

package/dist/schema/src/cli-results.js

@@ -1,7 +1,7 @@
 /**
  * @module Command results (`--format json`)
  *
- * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings` print on standard output with `--format json` (alias
+ * What `atlas report publish`, `stream`, `merge`, `doctor` and `verify-recordings`, and `atlas ui-catalog plan`, `publish`, `status`, `diff` and `export`, print on standard output with `--format json` (alias
  * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
  * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
  * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
@@ -154,6 +154,89 @@ export const InitPlanSchema = z.looseObject({
     nextSteps: z.array(z.string()).describe('What to do next, in order, as plain instructions an agent can follow'),
     warnings: z.array(z.string())
 });
+/** The coverage of one state in one profile, as the UI catalog words it. */
+const UiCoverageSchema = z.enum(['captured', 'failed', 'capturing', 'skipped', 'missing']);
+/** What `atlas ui-catalog plan --format json` and `atlas ui-catalog publish --format json` print: the one layer that was written. */
+export const UiCatalogPublishResultSchema = z.looseObject({
+    ok: z.literal(true).describe('True: the layer was written. A state whose picture could not be read is published as `failed` and named in `warnings`; it does not fail the command'),
+    store: z.string().describe('Where it was written: a folder, `s3://…` or a server URL'),
+    layer: z.looseObject({
+        id: z.string().describe('The layer id: 64 hex digits, the SHA-256 of its content. Publishing the same input again gives the same id'),
+        kind: z.enum(['ui-state', 'ui-plan']).describe('`ui-state`: captures (`publish`). `ui-plan`: the expected set (`plan`)'),
+        producer: z.string(),
+        environment: z.string().nullable(),
+        parameters: z.record(z.string(), z.string()).describe('The rest of the profile, such as `{ "viewport": "390x844" }`'),
+        states: z.number().int().nonnegative().describe('States in the layer'),
+        captured: z.number().int().nonnegative().describe('For `publish`: states that were captured (`passed`). Zero for a plan'),
+        failed: z.number().int().nonnegative().describe('For `publish`: states recorded as failed, including those whose picture could not be read'),
+        pictures: z.number().int().nonnegative().describe('Pictures stored in the layer'),
+        pictureBytes: z.number().int().nonnegative(),
+        shard: z.string().nullable().describe('The `--shard` label, which describes the layer and never splits its slot')
+    }),
+    warnings: z.array(z.string()).describe('What was skipped and why, such as a picture file that could not be read. Never fatal')
+});
+/** One thing that keeps a UI catalog from being complete and good. */
+export const UiCatalogProblemSchema = z.looseObject({
+    kind: z.enum(['failed', 'missing', 'capturing', 'unavailable', 'unreadable', 'empty']).describe('`failed`: a capture was attempted and failed. `missing`: a plan expects it and nothing was captured. `capturing`: still being taken, so not known. `unavailable`: a backend could not be read. `unreadable`: a layer could not be read. `empty`: the catalog holds no state at all'),
+    state: z.string().optional().describe('The state id, for `failed`, `missing` and `capturing`'),
+    profile: z.string().optional().describe('The profile label, for `failed`, `missing` and `capturing`'),
+    detail: z.string().optional().describe('Why, when the producer said')
+});
+/** What `atlas ui-catalog status --format json` prints. */
+export const UiCatalogStatusSchema = z.looseObject({
+    ok: z.boolean().describe('True only when the catalog holds a state and has no problem: nothing failed, nothing expected is missing, nothing is still being captured, and every backend and layer was read (otherwise the exit code is 1). Skipped cells are counted, not problems'),
+    summary: z.looseObject({
+        states: z.number().int().nonnegative(),
+        profiles: z.number().int().nonnegative(),
+        cells: z.number().int().nonnegative().describe('States counted once per profile'),
+        coverage: z.record(UiCoverageSchema, z.number().int().nonnegative()).describe('Cells by coverage'),
+        undeclared: z.number().int().nonnegative().describe('Captured cells no plan expects; zero when no plan exists'),
+        planned: z.boolean().describe('Whether any plan was published. Without one, `missing` is always zero because what should exist is unknown'),
+        surfaces: z.number().int().nonnegative(),
+        uncoveredSurfaces: z.number().int().nonnegative()
+    }),
+    profiles: z.array(z.looseObject({ key: z.string(), label: z.string() })),
+    problems: z.array(UiCatalogProblemSchema),
+    sources: z.looseObject({ layers: z.number().int().nonnegative(), backends: z.array(z.looseObject({ id: z.string(), label: z.string(), available: z.boolean() })), notices: z.array(z.string()) })
+});
+/** One side of `atlas ui-catalog diff`. */
+const UiCatalogCommitSchema = z.looseObject({ sha: z.string(), states: z.number().int().nonnegative(), layers: z.number().int().nonnegative() });
+/** What `atlas ui-catalog diff --format json` prints. */
+export const UiCatalogDiffResultSchema = z.looseObject({
+    ok: z.boolean().describe('False when a layer or backend could not be read (the comparison may be wrong), or, with `--fail-on-change`, when anything differs. Otherwise true: a difference is not a failure by itself'),
+    from: UiCatalogCommitSchema,
+    to: UiCatalogCommitSchema,
+    summary: z.looseObject({
+        coverage: z.number().int().nonnegative().describe('Pairs that stand differently (captured against failed, for example)'),
+        picture: z.number().int().nonnegative().describe('Both captured, and the stored bytes differ. Not a measure of how many pixels'),
+        unverified: z.number().int().nonnegative().describe('Both captured, but a side has no content hash, so whether the picture changed is unknown'),
+        added: z.number().int().nonnegative().describe('Only `to` has it'),
+        removed: z.number().int().nonnegative().describe('Only `from` has it. Not a regression: the other side may not have run it'),
+        unchanged: z.number().int().nonnegative(),
+        total: z.number().int().nonnegative()
+    }),
+    changes: z.array(z.looseObject({
+        state: z.string(), title: z.string(), profile: z.string(),
+        change: z.enum(['coverage', 'picture', 'unverified', 'added', 'removed']),
+        from: UiCoverageSchema.nullable(), to: UiCoverageSchema.nullable()
+    })).describe('Every pair that is not unchanged'),
+    notices: z.array(z.string()).describe('What could not be read. Any makes `ok` false: an unreadable layer is unknown, never unchanged')
+});
+/** What `atlas ui-catalog export --format json` prints. */
+export const UiCatalogExportResultSchema = z.looseObject({
+    ok: z.literal(true),
+    out: z.string().describe('The HTML file that was written'),
+    bytes: z.number().int().nonnegative().describe('Its size'),
+    states: z.number().int().nonnegative(),
+    cells: z.number().int().nonnegative(),
+    pictures: z.looseObject({
+        embedded: z.number().int().nonnegative(),
+        embeddedBytes: z.number().int().nonnegative(),
+        left: z.number().int().nonnegative().describe('Pictures not embedded (over the size limit, not stored, not an image, or `--images none`); each is listed on the page with the reason')
+    }),
+    manifest: z.string().nullable().describe('The JSON manifest written beside it with `--manifest`, or null'),
+    warnings: z.array(z.string()).describe('Backends and layers that could not be read, and pictures left out. The page says so too')
+});
 /**
  * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
  * A new result needs an entry here and a runtime scenario in the documentation contract tests.
@@ -166,5 +249,10 @@ export const CLI_RESULTS = {
     doctor: { command: 'atlas report doctor', schemaName: 'doctor-result', schema: DoctorResultSchema },
     status: { command: 'atlas report status', schemaName: 'report-status', schema: ReportStatusSchema },
     verifyRecordings: { command: 'atlas report verify-recordings', schemaName: 'verify-recordings-result', schema: VerifyRecordingsResultSchema },
+    uiCatalogPlan: { command: 'atlas ui-catalog plan', schemaName: 'ui-catalog-publish-result', schema: UiCatalogPublishResultSchema },
+    uiCatalogPublish: { command: 'atlas ui-catalog publish', schemaName: 'ui-catalog-publish-result', schema: UiCatalogPublishResultSchema },
+    uiCatalogStatus: { command: 'atlas ui-catalog status', schemaName: 'ui-catalog-status', schema: UiCatalogStatusSchema },
+    uiCatalogDiff: { command: 'atlas ui-catalog diff', schemaName: 'ui-catalog-diff-result', schema: UiCatalogDiffResultSchema },
+    uiCatalogExport: { command: 'atlas ui-catalog export', schemaName: 'ui-catalog-export-result', schema: UiCatalogExportResultSchema },
     error: { command: 'a command that was wrong (standard error)', schemaName: 'command-error', schema: CommandErrorSchema }
 };

package/docs/agents.md

@@ -164,6 +164,11 @@ JSON Schema (`@crvouga/atlas/schemas/<name>.schema.json`, draft 2020-12):
 | `atlas report doctor` | `doctor-result` |
 | `atlas report status` | `report-status` |
 | `atlas report verify-recordings` | `verify-recordings-result` |
+| `atlas ui-catalog plan` | `ui-catalog-publish-result` |
+| `atlas ui-catalog publish` | `ui-catalog-publish-result` |
+| `atlas ui-catalog status` | `ui-catalog-status` |
+| `atlas ui-catalog diff` | `ui-catalog-diff-result` |
+| `atlas ui-catalog export` | `ui-catalog-export-result` |
 | `a command that was wrong (standard error)` | `command-error` |
 <!-- /generated:json-command-schemas -->
 

package/docs/reference/cli.md

@@ -2,7 +2,7 @@
 
 > Generated from the usage text each command prints (`atlas <command> --help`) by `bun run docs`. Do not edit.
 
-Add `--format json` (alias `--json`) to `init`, `report publish`, `stream`, `merge`, `doctor` and `status` for a JSON document on standard output (schemas in `@crvouga/atlas/schemas`). Exit codes: `0` it worked, `1` it ran and the answer is no, `2` the command was wrong.
+Add `--format json` (alias `--json`) to `init`, `report publish`, `stream`, `merge`, `doctor`, `status` and every `ui-catalog` command for a JSON document on standard output (schemas in `@crvouga/atlas/schemas`). Exit codes: `0` it worked, `1` it ran and the answer is no, `2` the command was wrong.
 
 ## atlas
 
@@ -21,6 +21,7 @@ atlas — executable statecharts
   atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
   atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
   atlas report publish|stream|status|merge|doctor|policy …       layered evidence for any kind of spec (atlas report --help)
+  atlas ui-catalog plan|publish|status|diff|export …              the UI catalog of captured states (atlas ui-catalog --help)
 
   --workers       path attempts that run at once (default: one per CPU, capped by the driver)
   --seed          only paths that start from this seed ("start" for paths setup starts); repeatable
@@ -172,3 +173,57 @@ atlas report — layered evidence for any kind of spec
 
   Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.
 ```
+
+## atlas ui-catalog
+
+```text
+atlas ui-catalog — a browsable inventory of captured UI states, from any collector
+
+  atlas ui-catalog plan    --states <file.json> --producer <name> [--store <dir|s3://bucket/prefix|https://…>]
+                           [--environment <name>] [--param key=value]... [--shard <label>]
+                           [--branch <b>] [--sha <s>] [--run-url <u>] [--run-id <id>] [--run-title <t>] [--recorded-at <iso|ms>]
+  atlas ui-catalog publish --captures <file.json> --producer <name> [the same flags as plan]
+                           [--attach-root <dir>]... [--max-picture-mb <n>]
+  atlas ui-catalog status  [--store <dir|s3://…|id=url>]... [--backends <module>] [filters] [--branch <name>]...
+                           [--ignore-modified] [--format text|json|markdown]
+  atlas ui-catalog diff    --from <commit> --to <commit> [--store …]... [--backends <module>] [filters]
+                           [--fail-on-change] [--format text|json|markdown]
+  atlas ui-catalog export  --out <file.html> [--store …]... [--backends <module>] [filters]
+                           [--images inline|none] [--max-mb <n>] [--manifest <file.json>] [--title <t>]
+
+  filters (status, diff, export): --q <words> --coverage a,b --profile <key|label>... --area a --route r --cohort c
+                           --flag f --surface s --producer p
+
+  plan      Write one layer of kind ui-plan: the states (and with "inventory": true, the surfaces) that should exist under
+            this profile. Every entry is not-run, so a plan never counts as a pass. The file is {"states":[{"id":…,
+            "title"?,"route"?,"fixture"?,"cohort"?,"area"?,"flags"?,"covers"?,"inventory"?}]} or just that list.
+  publish   Write one layer of kind ui-state: the states one collector or shard captured under this profile. The file is
+            {"states":[{"id":…,"title"?,"status"?:"passed|failed|running|not-run","detail"?,"route"?,"fixture"?,"cohort"?,
+            "area"?,"flags"?,"covers"?,"labels"?,"tags"?,"durationMs"?,"screenshot"?:"file.png"|{"path"|"uri",
+            "width"?,"height"?,"contentType"?}}]}. A picture file is read from beside the file and each --attach-root, never
+            from a hidden file or a link out. A passed state whose picture cannot be read is published as failed, with the
+            reason: a state without its picture is not shown as captured.
+            --environment and each --param key=value are the profile (a viewport, a color scheme, a device): another
+            profile is another result side by side. --shard only describes the layer; it never splits a result.
+            --recorded-at defaults to the modification time of the file, so publishing the same file twice is one layer.
+  status    Read every store and print the catalog's summary. Exit 1 unless the catalog holds a state and there is nothing
+            to attend to: a failed capture, a state a plan expects with nothing captured, a capture still in progress, a
+            backend or layer that could not be read. Without a plan nothing is expected, so nothing is missing.
+            --profile takes a profile's key or its label, as printed by status.
+  diff      Set the catalog recorded at one commit (--from) against another (--to): each state in each profile is paired
+            with itself and is unchanged, changed in coverage, changed in picture (the stored bytes differ), unverified (a
+            side has no content hash), only in --to (added) or only in --from (removed). A commit is the whole id or at
+            least 7 digits of it. Exit 0 unless a store could not be read, or, with --fail-on-change, anything differs.
+  export    Write the catalog as one HTML file with its pictures embedded and its manifest in it: no server, no network.
+            It is the catalog at the moment it was made. --images none leaves the pictures out. --max-mb (default 32) limits
+            the embedded pictures; those past it are listed in the page as left out, and the manifest stays complete.
+            --manifest writes the catalog's JSON manifest too.
+
+  --format json (alias --json)   every subcommand prints one JSON document instead of prose
+                       (schemas: ui-catalog-publish-result, ui-catalog-status, ui-catalog-diff-result, ui-catalog-export-result).
+                       A command that is wrong is {"ok":false,"error":{"message":…,"code":"usage"}} on standard error.
+  A store is a directory, s3://bucket/prefix or an Atlas server (https://…), exactly as for atlas report; select a project
+  with --project <slug> or ATLAS_PROJECT. When no --store is given, ATLAS_STORE is used.
+
+  Exit codes: 0 ok, 1 the answer is no (see each command), 2 the command was wrong.
+```

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
@@ -6992,6 +7018,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 +7053,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
@@ -10556,6 +10616,338 @@ 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 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`