@crvouga/atlas 1.20.0 → 1.22.0

package/docs/reference/schema.md

@@ -572,11 +572,27 @@ export const UiCatalogSchema = …
 `GET /api/reports/ui-catalog`: the UI catalog, computed from the winning results of the `ui-state` and `ui-plan` parts
 of every layer. States are in id order and cells in profile order, so the same layers always give the same document.
 
+#### `CatalogEntrySchema`
+
+```ts
+export const CatalogEntrySchema = …
+```
+
+An entry of the catalog as a critic reads it: one captured state in one profile, with the hash of its stored picture and the critiques already made of it.
+
+#### `CatalogEntriesSchema`
+
+```ts
+export const CatalogEntriesSchema = …
+```
+
+`GET /api/reports/ui-catalog/entries`: the UI catalog as a flat, cursor-paged list of captured states for a critic.
+
 ### Command results (`--format json`)
 
 Source: `packages/schema/src/cli-results.ts`
 
-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`, `atlas ui-catalog plan`, `publish`, `status`, `diff` and `export`, and `atlas critic list`, `setup`, `doctor` and `run`, 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.
@@ -686,6 +702,142 @@ export const InitPlanSchema = …
 What `atlas init --format json` prints: everything found about the project, and everything it would change.
 Without `--write` nothing is changed. With `--write`, the files are written and `written` says which.
 
+#### `CriticListEntrySchema`
+
+```ts
+export const CriticListEntrySchema = …
+```
+
+One critic as `atlas critic list` shows it.
+
+#### `CriticListResultSchema`
+
+```ts
+export const CriticListResultSchema = …
+```
+
+What `atlas critic list --format json` prints.
+
+#### `CriticSetupResultSchema`
+
+```ts
+export const CriticSetupResultSchema = …
+```
+
+What `atlas critic setup --format json` prints.
+
+#### `CriticDoctorCheckSchema`
+
+```ts
+export const CriticDoctorCheckSchema = …
+```
+
+One thing `atlas critic doctor` checked.
+
+#### `CriticDoctorResultSchema`
+
+```ts
+export const CriticDoctorResultSchema = …
+```
+
+What `atlas critic doctor --format json` prints.
+
+#### `CriticRunCriticSchema`
+
+```ts
+export const CriticRunCriticSchema = …
+```
+
+What `atlas critic run` did for one critic.
+
+#### `CriticRunResultSchema`
+
+```ts
+export const CriticRunResultSchema = …
+```
+
+What `atlas critic run --format json` prints. A dry run publishes and sends nothing.
+
+#### `CriticWatchCriticSchema`
+
+```ts
+export const CriticWatchCriticSchema = …
+```
+
+What `atlas critic watch` did for one critic.
+
+#### `CriticWatchResultSchema`
+
+```ts
+export const CriticWatchResultSchema = …
+```
+
+What `atlas critic watch --format json` prints, once, when the watch ends.
+
+#### `CriticMarkStandingSchema`
+
+```ts
+export const CriticMarkStandingSchema = …
+```
+
+What reviewers decided about one opinion, as `atlas critic review` reports it.
+
+#### `CriticReviewResultSchema`
+
+```ts
+export const CriticReviewResultSchema = …
+```
+
+What `atlas critic review --format json` prints.
+
+#### `CriticCalibrateResultSchema`
+
+```ts
+export const CriticCalibrateResultSchema = …
+```
+
+What `atlas critic calibrate --format json` prints. A dry run measures nothing and writes nothing.
+
+#### `UiCatalogPublishResultSchema`
+
+```ts
+export const UiCatalogPublishResultSchema = …
+```
+
+What `atlas ui-catalog plan --format json` and `atlas ui-catalog publish --format json` print: the one layer that was written.
+
+#### `UiCatalogProblemSchema`
+
+```ts
+export const UiCatalogProblemSchema = …
+```
+
+One thing that keeps a UI catalog from being complete and good.
+
+#### `UiCatalogStatusSchema`
+
+```ts
+export const UiCatalogStatusSchema = …
+```
+
+What `atlas ui-catalog status --format json` prints.
+
+#### `UiCatalogDiffResultSchema`
+
+```ts
+export const UiCatalogDiffResultSchema = …
+```
+
+What `atlas ui-catalog diff --format json` prints.
+
+#### `UiCatalogExportResultSchema`
+
+```ts
+export const UiCatalogExportResultSchema = …
+```
+
+What `atlas ui-catalog export --format json` prints.
+
 #### `CLI_RESULTS`
 
 ```ts
@@ -983,6 +1135,50 @@ export type CritiqueFinding = z.output<typeof CritiqueFindingSchema>;
 
 One finding of a critique.
 
+#### `CRITIQUE_MARK_EXTENSION`
+
+```ts
+export const CRITIQUE_MARK_EXTENSION = …
+```
+
+The key under which a reviewer's mark of a critique is stored in a check's `extensions`.
+
+#### `CRITIQUE_MARK_SCHEMA_VERSION`
+
+```ts
+export const CRITIQUE_MARK_SCHEMA_VERSION = …
+```
+
+The version of the `atlas.critique-mark` extension a reader of this release understands. A mark of another version is unknown, not wrong.
+
+#### `CRITIQUE_MARK_PRODUCER_PREFIX`
+
+```ts
+export const CRITIQUE_MARK_PRODUCER_PREFIX = …
+```
+
+The prefix of the `producer` of a layer of marks: `critic.review.<reviewer>`. It is within what a critic-role token may publish.
+
+#### `CritiqueMarkSchema`
+
+```ts
+export const CritiqueMarkSchema = …
+```
+
+The `atlas.critique-mark` extension, version 1: a person's verdict on a critic's opinion. `accept` says the opinion was right
+(the finding is valid, the UI needs polish); `dismiss` says it was not. A mark names the entry and the exact picture it was made
+about, the critic whose opinion it marks, and optionally one finding of it; without `finding` it marks the critique as a whole.
+Like the critique it is evidence in a part of kind `critique`: it is never counted and never changes a status, a slot or the gate.
+A newer mark of the same reviewer for the same subject replaces an older one. Emitted as `critique-mark.schema.json`.
+
+#### `CritiqueMark`
+
+```ts
+export type CritiqueMark = z.output<typeof CritiqueMarkSchema>;
+```
+
+A mark as stored in a check's `extensions["atlas.critique-mark"]`.
+
 ### Schema package entry point (`@crvouga/atlas/schema`)
 
 Source: `packages/schema/src/index.ts`. Import: `@crvouga/atlas/schema`

package/docs/report-contract.md

@@ -232,7 +232,8 @@ anything else is recorded. A measurement over its allowance is reported and neve
 
 Opinions (parts of kind `critique`, the verdicts of [automated UI reviewers](critics.md)) are never counted as checks,
 even when they are all that was recorded, and are never part of the gate: a low score, or a critic that crashed, leaves
-`atlas report status` as it was. The `status` of a critique check says only whether the critic ran.
+`atlas report status` as it was. The `status` of a critique check says only whether the critic ran. A person's accept or dismiss of an
+opinion (`atlas.critique-mark`) is evidence in the same kind of part and has the same properties.
 
 **Freshness never changes a status.** A layer whose spec fingerprint no longer matches, whose
 checkout was modified, or whose related code changed still shows its recorded outcome, with a

package/docs/server.md

@@ -545,6 +545,8 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /api/projects/{project}/reports/artifacts` | read | Recorded results that carry evidence, across the whole history. |
 | `GET /api/reports/ui-catalog` | read | The UI catalog: captured UI states per profile, and what is still expected. |
 | `GET /api/projects/{project}/reports/ui-catalog` | read | The UI catalog: captured UI states per profile, and what is still expected. |
+| `GET /api/reports/ui-catalog/entries` | read | The UI catalog as a list a critic iterates: captured states with their picture hash and critiques. |
+| `GET /api/projects/{project}/reports/ui-catalog/entries` | read | The UI catalog as a list a critic iterates: captured states with their picture hash and critiques. |
 | `GET /api/reports/runs/detail` | read | Every test one run recorded. |
 | `GET /api/projects/{project}/reports/runs/detail` | read | Every test one run recorded. |
 | `GET /api/reports/outline` | read | The specs a report is laid over. |

package/docs/ui-catalog.md

@@ -7,16 +7,19 @@ thousands of captures can be watched while it happens and split across as many m
 
 Nothing about it is new to the report contract. A state is an ordinary check with a screenshot, the expected set is an ordinary
 layer, and the stream is the one every viewer already holds. This page is the convention that makes those usable as a catalog, the
-decisions behind it, and what is not built yet.
+decisions behind it, the command line, and what stays in your project.
 
 - [How a state is written](#how-a-state-is-written)
 - [What is expected](#what-is-expected)
 - [Publishing from any collector](#publishing-from-any-collector)
+- [The command line](#the-command-line)
 - [Sharding](#sharding)
 - [Streaming and loading](#streaming-and-loading)
 - [Exploring it](#exploring-it)
+- [Comparing two commits or two profiles](#comparing-two-commits-or-two-profiles)
+- [A single file that needs no server](#a-single-file-that-needs-no-server)
 - [Decisions](#decisions)
-- [What stays in your project, and what is not built yet](#what-stays-in-your-project-and-what-is-not-built-yet)
+- [What stays in your project, and what Atlas does not do](#what-stays-in-your-project-and-what-atlas-does-not-do)
 
 ## How a state is written
 
@@ -28,7 +31,7 @@ A state is one **check** in a layer whose part has `kind` **`ui-state`**.
 | How the capture went | `status`: `passed` is **captured**, `failed` is attempted and failed (say why in `detail`), `running` is being taken, `not-run` is skipped. |
 | The picture | An attachment with `role: "screenshot"` (else the first image), stored in the layer by content or given as an `https` `uri`. `width` and `height` help the viewer lay it out. |
 | The profile | The layer's `environment` (`desktop-web`, `mobile-web`, `ios`, `android`) and `parameters` (`{ "viewport": "390x844", "scheme": "dark" }`). Parameters split a slot, so the same state at another viewport is **another result, side by side**, never a replacement. |
-| Facts the producer declares | The check's `extensions["atlas.ui-state"]`: `route`, `fixture`, `cohort`, `area`, `flags` (a list), `covers` (the product surfaces the state shows). All optional. |
+| Facts the producer declares | The check's `extensions["atlas.ui-state"]`: `route`, `fixture`, `cohort`, `area`, `kind` (the kind of UI state: `screen`, `overlay`, `loading`, `error`, `empty`… an open vocabulary that [critics](critics.md#reading-the-catalog) judge a state by), `flags` (a list), `covers` (the product surfaces the state shows). All optional. |
 | Facts that describe without splitting | The check's `labels` (`shard`, `browser`) and `tags`. Labels never make a different slot. |
 | Where it came from | The layer's `producer`, `sha`, `branch`, `runUrl`, `freshness`, `recordedAtMs`: shown with every capture, with the layer id and the backend that holds it. |
 
@@ -101,6 +104,35 @@ for a readiness check (bounded), photographs the page and returns the capture fo
 a `failed` capture that says why (with a picture of what it showed), never an exception that ends the run. Nothing that reads,
 composes or shows the catalog imports a collection framework, and a test keeps it that way.
 
+## The command line
+
+`atlas ui-catalog` does the same without a script. Every subcommand prints a JSON document with `--format json`
+([`atlas ui-catalog --help`](reference/cli.md) lists every flag), and exits `0` it worked, `1` the answer is no, `2` the command was wrong.
+
+```sh
+# The expected set under one profile. The file is {"states":[{"id":"checkout/payment","covers":["payment-form"]},{"id":"settings","inventory":true}]}.
+atlas ui-catalog plan --states plan.json --producer catalog-plan --environment mobile-web --param viewport=390x844 --param scheme=dark
+
+# The states one collector or shard captured. "screenshot" names a file beside captures.json.
+atlas ui-catalog publish --captures captures.json --producer web-capture --environment mobile-web --param viewport=390x844 --param scheme=dark --shard 2/8
+
+atlas ui-catalog status                          # exit 1 while anything failed, is missing, is still being captured or could not be read
+atlas ui-catalog diff --from 3f9a2c1 --to 8b41d70 # two commits (the whole id, or at least 7 digits)
+atlas ui-catalog export --out public/catalog.html # one file, no server
+```
+
+`captures.json` is `{"states":[…]}` (or just the list); a state is `{"id","title"?,"status"?,"detail"?,"route"?,"fixture"?,"cohort"?,"area"?,
+"flags"?,"covers"?,"labels"?,"tags"?,"durationMs"?,"screenshot"?}` with `screenshot` a file name or `{"path"|"uri","width"?,"height"?,"contentType"?}`.
+A misspelled field is refused with its path, not ignored. A picture file is read from beside the file and from 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. `--recorded-at` defaults to the file's modification time, so publishing the same
+file twice is the same layer.
+
+`status` is the gate: it exits `1` unless the catalog holds a state and nothing needs attention (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 can be missing: it says so. A skipped cell is counted, not a problem. Schemas: `ui-catalog-publish-result`,
+`ui-catalog-status`, `ui-catalog-diff-result`, `ui-catalog-export-result`.
+
 ## Sharding
 
 A shard is **any publisher that does not know the others**: by case, by profile, by area or by machine; Atlas does not care which.
@@ -140,10 +172,54 @@ and time. *Download the manifest* saves the filtered catalog as JSON.
 curl "$ATLAS_SERVER_URL/api/reports/ui-catalog?coverage=failed,missing&profile=…"   # JSON; add format=markdown for text
 ```
 
+A separate process that reviews the pictures (a [critic](critics.md#reading-the-catalog)) reads the same catalog as a flat list at
+`GET /api/reports/ui-catalog/entries`: cursor-paged, `since` a report version, with the hash of each stored picture.
+
 `GET /api/reports/ui-catalog` answers the same document the viewer computes (`uiCatalog` from
 `@crvouga/atlas/reports/ui-catalog`), filtered by `q`, `coverage`, `profile`, `area`, `route`, `cohort`, `flag`, `surface` and
 `producer`, paged with `limit` and `offset`, with an ETag. Its picture `path` is relative to `/api/reports`.
 
+## Comparing two commits or two profiles
+
+The viewer's **Compare** button on `/catalog` (`?compare=commit&from=<commit>&to=<commit>`, or `?compare=profile&from=<profile>&to=<profile>`,
+so a link reproduces it) and `atlas ui-catalog diff` set one side against the other. Every pair is one state in one profile.
+
+| A pair is | When |
+| --- | --- |
+| **Unchanged** | the same coverage and, when captured, the same stored picture |
+| **Picture changed** | captured on both sides, and the picture's bytes (SHA-256) differ. This is not a measure of how many pixels differ |
+| **Coverage changed** | it stands differently (captured against failed, failed against not captured yet…). A capture that did not pass is never compared by picture |
+| **Cannot tell** | captured on both sides, but a picture has no content hash (it is given only by address, or was left out) |
+| **Only after** / **Only before** | one side has no such cell. It may be new, renamed, or the other side's shard may not have run: it is not called a regression |
+
+- **Two commits** compares the layers recorded at each commit. A layer replaces the older one of its slot, so the report keeps only the
+  newest capture of every state; the comparison therefore reads the layers themselves (the viewer asks for the layer list and the rows of
+  the two commits only; the command line reads the stores). Layers recorded from a checkout with uncommitted changes are not a commit's
+  own result and are left out. A commit is the whole id or at least 7 digits that name exactly one commit; anything else is an error
+  that lists the commits found, never a guess.
+- **Two profiles** sets each state's cell in one profile beside its cell in another (desktop against mobile, light against dark) in
+  the report the viewer holds.
+- A layer or backend that could not be read is named, and what it held is unknown, never "unchanged": `diff` exits `1` for it.
+  `--fail-on-change` also exits `1` for any difference, for a gate that must stay the same.
+- The filters (words, area, route, cohort, flag, surface, producer) narrow a comparison; coverage does not, because coverage is what is
+  compared.
+
+## A single file that needs no server
+
+`atlas ui-catalog export --out catalog.html` writes the catalog as **one HTML file**: the pictures embedded as `data:` addresses, the
+manifest embedded as JSON (`<script type="application/json" id="ui-catalog">`), a search box and a coverage filter. Open it from a disk,
+attach it to a ticket or serve it as a file. It is the catalog at the moment it was made, and says so; it does not stream (for that,
+serve the store with `atlas serve` or build the site with `atlas client build`, which shows the same catalog).
+
+- **Size.** Hosting platforms cap the size of one file. `--max-mb` (default 32) limits the embedded pictures; pictures past it are listed
+  in the page as left out, with the reason, in the order the page shows them, and the manifest stays complete. `--images none` embeds none.
+  `--manifest catalog.json` also writes the manifest as its own file.
+- **Safe to open.** The page is generated from data written by test runs, and treats it so: text is escaped, only PNG, JPEG, GIF and WebP
+  bytes (by their first bytes, never SVG, never a layer's claimed type) are embedded, a picture given by address is linked only if it is
+  `http` or `https`, and a Content-Security-Policy forbids every network request. Without scripts every state is simply shown.
+- It is a generated document, not the viewer: it carries its own small inline style and script because it must work with no build
+  and no server, which [the viewer's UI conventions](ui.md) forbid inside the viewer.
+
 ## Decisions
 
 The questions the original proposal left open, and how they are answered here. Each is the simplest answer that stays inside the
@@ -161,13 +237,34 @@ The questions the original proposal left open, and how they are answered here. E
 | What moves | Reading, composing, the viewer, the document and the API, the publish builders, a Playwright capture adapter. Staying with a product: its state declarations, its inventory, its fixtures and its runner. |
 | Where it lives | `@crvouga/atlas/reports/ui-catalog` (model), `…/ui-catalog-publish` (builders), `…/ui-state` (convention); the viewer's `/catalog`; the server's `/api/reports/ui-catalog`; `@crvouga/atlas/playwright`'s `captureUiState`. |
 | Exploration capabilities | Search, filters, profile comparison, coverage and surface coverage, failure diagnostics, deep links, manifest export. |
-| Static export | The catalog is computed from the layers a viewer holds, so a static export (`atlas client build`) shows it; it just does not stream. |
-
-## What stays in your project, and what is not built yet
-
-**Stays in a project** (it is specific to the product): the list of states and profiles to capture, the inventory of surfaces,
-fixtures and test data, the runner that drives the product to each state, and the readiness conditions of each screen.
-
-**Not built yet:** a command line to list and publish a catalog without a script (use `atlas report publish --checks` today), a
-dedicated static single-file export, diff views that compare two commits of a state, and a hosting-platform publish step beyond
-`atlas serve`. The first slice makes the catalog explorable, streaming, shardable and independent of how it was collected.
+| Static export | Two ways, neither needs a server. The catalog is computed from the layers a viewer holds, so the static site (`atlas client build`) shows it, without streaming. `atlas ui-catalog export` writes it as one self-contained HTML file with a size budget. |
+| Comparing | Two commits (from the layers recorded at each, because the report keeps only the newest) or two profiles; pictures by content hash, never by a pixel measure; one-sided states are not regressions. |
+| Command line | `atlas ui-catalog plan`, `publish`, `status`, `diff` and `export`, each with `--format json`. Running a collector is not one: that is the product's. |
+
+## What stays in your project, and what Atlas does not do
+
+A project that had its own catalog moves each role it had to Atlas, and keeps only what is specific to its product. The eight roles, and
+where each now is:
+
+| # | Role | In Atlas | Stays in your project |
+| --- | --- | --- | --- |
+| 1 | Declaration of the states to capture, and the plan of what is expected | The plan format (`ui-plan` layers), `uiPlanLayer`, `atlas ui-catalog plan` | **The list itself**: which states and profiles your product has |
+| 2 | A capture helper, with readiness checks and diagnostics | An optional adapter, `captureUiState` in `@crvouga/atlas/playwright`; any other tool writes the same layer | **The readiness condition of each screen**, and the helper for a framework Atlas has no adapter for |
+| 3 | An evidence store: one atomic record per capture, images by content | Layers and the stores that hold them (`publishChecks`, a directory, S3, a server) | Nothing |
+| 4 | An inventory of the product's surfaces, and reconciliation against it | Reconciliation: `inventory` plan entries and `covers`, the surface coverage table | **The inventory**: the list of surfaces your product has |
+| 5 | A manifest and report builder | `uiCatalog`, the JSON manifest, Markdown, the single HTML file | Nothing |
+| 6 | A viewer: as a single file, as a site, and live | `atlas ui-catalog export`, `atlas client build`, and `/catalog` on `atlas serve` | Nothing |
+| 7 | A command line (list, run, report, publish, watch) | `atlas ui-catalog plan\|publish\|status\|diff\|export`; watching is the live `/catalog` and `atlas report stream` | **Run**: the runner that drives your product to each state |
+| 8 | A publish step to a hosting platform | Not in Atlas, see below | **The deploy step** of your platform |
+
+What stays is, in one list: the states and profiles to capture, the inventory of surfaces, the fixtures and test data, the runner that
+drives the product to each state, the readiness condition of each screen, and the deploy step of your hosting platform. Nothing else is
+specific to your product, so a project that installs a release holds none of the reporting and exploring code, only that.
+
+**A hosting publish step is not a command, on purpose.** Publishing to a platform needs that platform's credentials and API, which Atlas
+neither holds nor should. Hand the platform what Atlas produces: the `export` file (or a folder of them) for any host that serves
+files, the output of `atlas client build` for a static site, or run `atlas serve` for a live one. Keep the credentials in the CI of the
+project, where they already are.
+
+**Not built:** reconciliation against an external inventory beyond `inventory` entries and `covers`; a comparison of pictures by pixels
+(only by content); a comparison fetched from the server (the viewer and the command line read the layers themselves).

package/docs/ui.md

@@ -119,6 +119,9 @@ same coverage state, revisions and recording in both.
 - The search words (`q`), the coverage filter (`coverage`), the selection (`behavior`) and the expanded state (`workspace`) are in the
   address. Selecting shows the Read / Watch / Inspect panel beside the list (below it on narrow screens), and *Read and watch* in the
   selected-behavior bar is reachable before the list in keyboard order.
+- The same release controls as a feature page (*Release build*, *commit*, *platform*, and the *Stale or unverified* filter) sit above the list;
+  they are the address (`release`, `releaseSha`, `releasePlatform`, `evidence=stale`), and the selected behavior and the workspace read their
+  evidence against that release.
 - **Read and watch workspace.** Expanding a behavior replaces the index with a page that uses the width: a two-column
   `SimpleGrid` (one column below `md`) with *What should happen* (the steps, an outline's example filled in) beside *Recording* (the
   player, status and provenance, promise and evidence revisions, applicability), the scoped summary below, and Inspect behind a
@@ -135,6 +138,39 @@ same coverage state, revisions and recording in both.
   budget and breaches). Absent evidence is stated as unknown, never as good; the test's duration is not product latency, and the
   summary says it describes the checks Atlas holds, not production. The full reliability and latency detail is one link away.
 
+## The review destination
+
+A team asks four connected questions of one project: what behavior it promises (**Read**), what that looks like (**Watch**), what
+evidence supports it (**Inspect**) and where the gaps are. The viewer answers them in three places that lead to one another, and
+`tests/review-destination.test.tsx` walks the whole workflow against a real server, one test per acceptance behavior of the
+tracking issue (#20).
+
+| Step | Where | Built by |
+| --- | --- | --- |
+| Find a promise by approximate words, a domain, a device and recordings; see each in its own coverage state | **Behaviors** (`/behaviors`) | #55, #74, #57, #44 |
+| Name the build and device to read the evidence against | the applicability controls of Behaviors and of a feature | #61, #73 |
+| Read what should happen beside the recording, with the scoped outcome, reliability and latency | the Read and watch workspace | #74, #60, #62, #63 |
+| Find recordings by tag and media type and play them as a labelled playlist | **Artifacts** (`?tab=artifacts`), Watch these N results | #49, #56, #59, #75 |
+| Go from a clip to its promise (**Read the promise**, also in a test's detail) or to its exact run (**Developer details**) | the playlist | #47, #54 |
+| See which run and execution a result came from, and which recordings never arrived or are gone | **Runs** (`?tab=runs`) | #45, #46, #48, #70, #72, #76 |
+| Seek to the step in a recording and share the moment | Timeline, Watch | #68 |
+| Freeze a selection with notes and gaps | **Collections** | #66 |
+| Compare two pinned runs | **Compare** | #67 |
+
+How the pieces stay honest, and what a test in that file holds them to:
+
+- The four states (not executed, API only, failed with a recording, demonstrated) are told apart in words and never counted as one
+  pass. A recording that was expected and not uploaded, or stored and then lost, is shown beside its green tests, never in place of them.
+- Behaviors, Runs and Videos and artifacts link to one another (the header of Behaviors and the Specs block of the explorer), and a
+  result in the playlist or in a test's detail links back to the exact check of its feature. Read names the check and no run;
+  Inspect names the run (`layer`), so it never falls back to the latest combined evidence.
+- The address holds the scope: the release (`release`, `releaseSha`, `releasePlatform`) and `evidence=stale` on Behaviors as on a feature,
+  the filters and the open playlist on Artifacts, the pinned runs on Compare, and the revision of a frozen collection.
+  A frozen collection does not change when newer runs arrive; the filtered view it was frozen from does.
+- An older producer (no spec fingerprint, no recording expectation, no tags) or an older server (no artifact search, read-back,
+  collections or health route) stays readable. What it cannot say is unknown: the revision is "not recorded", a run is not "complete",
+  and an unreported behavior is "Not executed", never passed.
+
 ## Catalog health
 
 The **Catalog health** tab (`explorer/HealthView.tsx`, `?tab=health`; `@crvouga/atlas/reports/catalog-health`) explains why the Specs
@@ -167,6 +203,36 @@ it works without a server. Cards are Mantine `Card`s in a responsive `SimpleGrid
   incomplete. Waiting follows the loading policy below, and layers still arriving are counted.
 - Pictures are `loading="lazy"` and only the cards on screen are fetched. The grid is bounded with *Show more*.
 - The open state shows every profile side by side with the layer, backend, producer, shard, commit and time of each picture.
+- **Compare** (`catalog/UiCatalogCompare.tsx`, `?compare=commit|profile&from&to`) sets two commits or two profiles against each other. Two
+  commits need the layers a newer layer replaced, which the held report no longer has, so `catalog/history.ts` reads the layer list and
+  the rows of the two commits only while the comparison is open (sharing the rows cache). Say what "changed" means (the stored bytes
+  differ, not a pixel measure), never call a one-sided state a regression, and say a layer that could not be read is unknown. The
+  coverage filter does not apply to a comparison.
+
+## Needs polish
+
+`/critiques` (`critiques/`, in the spec-type menu once a critic has recorded an opinion) ranks the captured UI states one critic
+judged, lowest first ([the guide](critics.md#the-viewer-needs-polish)). It is computed in the page from the layers the viewer already
+holds (`critiques/ranking.ts`), so a critique appears as its layer arrives.
+
+- A critique is an opinion: no `StatusMark`, no passed or failed words, never in a test count. Use a Mantine `Badge` with the
+  label the critic gave (an open string), the severity as text, and never a color alone.
+- A state judged at an earlier picture, or that the critic could not judge, is listed in its own table with the reason and is not
+  ranked. Unknown categories and severities are shown as written.
+- The critic and the state kind are `NativeSelect`s whose values are the address (`critic`, `kind`, `entry`); the open entry is a
+  `Drawer` with the findings in a `Table` and the provenance in an `Accordion`.
+- Pictures are `loading="lazy"`. Waiting, an unavailable backend and incomplete layers are named as on the UI catalog.
+- **Finding overlays** (`critiques/FindingOverlay.tsx`): in the open entry each finding with a region is a numbered box over the picture,
+  positioned with Mantine style props (`pos`, `left`, `top`, `w`, `h` as percentages of the picture, `bd`) and a numbered `Badge`; no
+  `style`, `className` or stylesheet. The number is the finding's row in the table (where a `Button` locates it, `aria-pressed`), so color
+  is never the only signal; the boxes are `aria-hidden` because the table says the same in words, and a `Switch` hides them. A region in
+  an unknown unit, or of a critique that judged an earlier picture, is not drawn.
+- **Agreement** is a `Tabs` view of the same page (`?view=agreement`, `keepMounted={false}`): a `Table` with one column per critic, each
+  cell a `Badge` in words (*Flags it*, *Does not flag it*, *No view*) with a link to that critic's critique, and the outcome as text.
+  The rule for a stance is stated on the page (`reports/critique-review`); a score without standing or a failure gives no view.
+- **Marks** are read, never written, by the viewer (a browser sign-in only looks): each finding and the whole opinion show a `Badge` in
+  words (*Accepted by*, *Dismissed by*, *Reviewers disagree*, *Not reviewed*) with the reviewers' notes, and the page names
+  `atlas critic review`. No mark uses a passed or failed word or a status color.
 
 ## Reliability
 
@@ -255,7 +321,8 @@ over the same filtered set the page lists, in the same order (`explorer/playlist
   Speed, "Play the next clip when one ends" and "Repeat" are labelled controls. Captions (`text/vtt` attachments) are offered
   as `<track>` elements.
 - The scenario (title, recorded steps, why it failed) sits beside the player with the recording's scope badges
-  (paced, scripted, silent, synthetic) and the sentence that the length is the recording's, not production latency. Developer
+  (paced, scripted, silent, synthetic) and the sentence that the length is the recording's, not production latency. **Read the promise** opens the feature on that
+  exact check (the playlist stays in the address, so Back returns to the same clip); Developer
   details opens the test pinned to that run's record and closes the playlist.
 
 ## Steps and moments in a recording
@@ -384,7 +451,7 @@ The narrowly scoped exceptions are:
 | Area | Screens/interactions | Mantine composition |
 | --- | --- | --- |
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
-| UI catalog | Captured UI states per profile as cards with coverage badges, filters in the index column, surface coverage, an open state with its profiles side by side and where each picture came from, manifest download | AppShell navbar, SimpleGrid, Card, Image, MultiSelect, TextInput, Drawer, Accordion, Table, Badge, Alert |
+| UI catalog | Captured UI states per profile as cards with coverage badges, filters in the index column, surface coverage, an open state with its profiles side by side and where each picture came from, manifest download, a Compare of two commits or profiles (SegmentedControl, NativeSelect, Switch) | AppShell navbar, SimpleGrid, Card, Image, MultiSelect, TextInput, Drawer, Accordion, Table, Badge, Alert |
 | Project home | Tests/runs/artifacts/compare/catalog health tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
 | Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |