@crvouga/atlas 1.12.0 → 1.14.0

package/docs/reference/http-api.md

@@ -414,7 +414,7 @@ Responses: `200` It exists.; `401` No token, or an unknown one. Send `Authorizat
 
 ### Upload an object
 
-`PUT /api/store/{key}` · role: publish
+`PUT /api/store/{key}` · role: critic
 
 The write half of the `ObjectStore` interface. The server checks what it can from the bytes in hand and says no to what would corrupt the report for everyone:
 
@@ -426,6 +426,8 @@ The write half of the `ObjectStore` interface. The server checks what it can fro
 
 Upload in dependency order: blobs, then the manifest, then the catalog entry. `atlas report publish`, `atlas report stream` and `httpStore` do. Needs a `Bearer` token of role `publish` or `admin`; a browser's sign-in box is refused.
 
+A token of role `critic` may upload only what a critic publishes: blobs, and layers (and their catalog entries) whose `producer` is `critic.<name>` and whose parts are all of kind `critique`. Anything else is `403` with the rule it broke, and nothing is stored.
+
 - `key` (path, required): An object key under `layers/`, such as `layers/manifests/<id>.json`. It contains slashes, which are not percent-encoded; every other character is.
 - `content-type` (header): Stored with the object and returned when it is read.
 - `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
@@ -434,7 +436,7 @@ Responses: `200` Already there with the same bytes.; `201` Stored.; `401` No tok
 
 ### Upload an object
 
-`PUT /api/projects/{project}/store/{key}` · role: publish
+`PUT /api/projects/{project}/store/{key}` · role: critic
 
 The write half of the `ObjectStore` interface. The server checks what it can from the bytes in hand and says no to what would corrupt the report for everyone:
 
@@ -446,6 +448,8 @@ The write half of the `ObjectStore` interface. The server checks what it can fro
 
 Upload in dependency order: blobs, then the manifest, then the catalog entry. `atlas report publish`, `atlas report stream` and `httpStore` do. Needs a `Bearer` token of role `publish` or `admin`; a browser's sign-in box is refused.
 
+A token of role `critic` may upload only what a critic publishes: blobs, and layers (and their catalog entries) whose `producer` is `critic.<name>` and whose parts are all of kind `critique`. Anything else is `403` with the rule it broke, and nothing is stored.
+
 Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
 
 - `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
@@ -922,6 +926,52 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `200` The matching results and the facets.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
 
+### The UI catalog: captured UI states per profile, and what is still expected
+
+`GET /api/reports/ui-catalog` · role: read
+
+A browsable inventory of the product's user interface, computed from the winning results of the `ui-state` and `ui-plan` parts of every layer (see the UI catalog guide). Each state is a check id; each cell is one profile of it (the layer's environment and parameters) with its coverage: `captured` only when the winning capture passed, `failed`, `capturing`, `skipped`, or `missing` when a plan expects it and nothing has been captured. A picture is read from the cell's `capture.image.path` under the reports API root, or `uri`. What is expected is itself a layer, so a shard that never published leaves its states `missing`, never captured. The document equals what the viewer computes from the same report. Narrow it by `q` (words), `coverage`, `profile` (a profile `key`), `area`, `route`, `cohort`, `flag`, `surface` and `producer`: AND across parameters, OR within one; a state keeps only the cells that match `profile` and `coverage`. Page the states with `limit` and `offset`. Viewers need not poll: they hold the report over `/api/events` and read changes with `/api/reports/evidence/effective?since=`.
+
+- `limit` (query): At most this many states (default 200).
+- `offset` (query): Skip this many states (default 0).
+- `q` (query): Words that must all appear in a state's id, title, route, fixture, cohort, area, flags, surfaces or producers.
+- `coverage` (query): Coverage values: `captured`, `failed`, `capturing`, `skipped`, `missing`. Comma-separated.
+- `profile` (query): Profile keys, as listed in `profiles[].key`.
+- `area` (query): Areas.
+- `route` (query): Routes.
+- `cohort` (query): Cohorts.
+- `flag` (query): Feature flags a state was captured with.
+- `surface` (query): Surfaces a state covers.
+- `producer` (query): Producers that captured or planned a state.
+- `format` (query): `markdown` for Markdown instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The catalog.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### The UI catalog: captured UI states per profile, and what is still expected
+
+`GET /api/projects/{project}/reports/ui-catalog` · role: read
+
+A browsable inventory of the product's user interface, computed from the winning results of the `ui-state` and `ui-plan` parts of every layer (see the UI catalog guide). Each state is a check id; each cell is one profile of it (the layer's environment and parameters) with its coverage: `captured` only when the winning capture passed, `failed`, `capturing`, `skipped`, or `missing` when a plan expects it and nothing has been captured. A picture is read from the cell's `capture.image.path` under the reports API root, or `uri`. What is expected is itself a layer, so a shard that never published leaves its states `missing`, never captured. The document equals what the viewer computes from the same report. Narrow it by `q` (words), `coverage`, `profile` (a profile `key`), `area`, `route`, `cohort`, `flag`, `surface` and `producer`: AND across parameters, OR within one; a state keeps only the cells that match `profile` and `coverage`. Page the states with `limit` and `offset`. Viewers need not poll: they hold the report over `/api/events` and read changes with `/api/reports/evidence/effective?since=`.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `limit` (query): At most this many states (default 200).
+- `offset` (query): Skip this many states (default 0).
+- `q` (query): Words that must all appear in a state's id, title, route, fixture, cohort, area, flags, surfaces or producers.
+- `coverage` (query): Coverage values: `captured`, `failed`, `capturing`, `skipped`, `missing`. Comma-separated.
+- `profile` (query): Profile keys, as listed in `profiles[].key`.
+- `area` (query): Areas.
+- `route` (query): Routes.
+- `cohort` (query): Cohorts.
+- `flag` (query): Feature flags a state was captured with.
+- `surface` (query): Surfaces a state covers.
+- `producer` (query): Producers that captured or planned a state.
+- `format` (query): `markdown` for Markdown instead of JSON.
+
+Responses: `200` The catalog.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### Every test one run recorded
 
 `GET /api/reports/runs/detail` · role: read

package/docs/reference/playwright.md

@@ -104,7 +104,10 @@ recognise screens and tap or type (`screen`, `recognize`, `locate`, the signal c
 the media tools (`captureScreen`, `ScreencastRecorder`, `ffmpeg`, `PHONE` and the pacing presets). Needs the
 `playwright` package; clips and thumbnails need FFmpeg on the PATH.
 
+Also `captureUiState`, the optional Playwright adapter of the UI catalog (it needs no Playwright import itself).
+
 See docs/statecharts.md
+See docs/ui-catalog.md
 
 ### Playwright screenshots, clips and paced actions
 
@@ -301,3 +304,63 @@ const states = {
   'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] })
 };
 ```
+
+### Playwright adapter for the UI catalog
+
+Source: `packages/playwright/src/ui-catalog.ts`
+
+The optional Playwright side of the UI catalog: take a page to a state, wait until it is ready, photograph it, and hand the
+result to `uiStateLayer` (`@crvouga/atlas/reports/ui-catalog-publish`) as a capture. This is the only Playwright-specific code
+of the feature; reading, composing and exploring the catalog know nothing about it, and any other program that writes the
+same layer produces the same catalog. The page is typed by the three methods used, so no `playwright` import is needed here
+and a Playwright Test `page`, a `Page` of the driver, or a stub all fit.
+
+See docs/ui-catalog.md
+
+#### `CapturePage`
+
+```ts
+export type CapturePage = {
+  screenshot(options?: { readonly fullPage?: boolean; readonly animations?: 'disabled' | 'allow'; readonly type?: 'png' }): Promise<Uint8Array>;
+  viewportSize(): { readonly width: number; readonly height: number } | null;
+};
+```
+
+The part of a Playwright `Page` that capturing uses.
+
+#### `CaptureUiStateOptions`
+
+```ts
+export type CaptureUiStateOptions = UiStateFacts & {
+  /** The state's stable id: how a later capture replaces this one. */
+  readonly id: string;
+  readonly title?: string;
+  /** Resolves when the page shows the state (a locator is visible, the network is idle). A rejection or a timeout makes the capture `failed`, with the reason as its detail. */
+  readonly ready?: (page: CapturePage) => Promise<void>;
+  /** How long to wait for `ready`; default 15 seconds. */
+  readonly readyTimeoutMs?: number;
+  /** Photograph the whole scrollable page rather than the viewport. */
+  readonly fullPage?: boolean;
+  /** Extra labels for the capture (`browser`, `os`), which never split it. */
+  readonly labels?: Readonly<Record<string, string>>;
+};
+```
+
+What to capture and how to know the page is ready.
+
+#### `captureUiState`
+
+```ts
+export async function captureUiState(page: CapturePage, options: CaptureUiStateOptions): Promise<UiStateCapture>
+```
+
+Wait for the page to be ready, photograph it, and return the capture to publish. Never throws for the page's sake: a page
+that never became ready, or could not be photographed, is a `failed` capture that says why, so a broken state shows in the
+catalog instead of ending the run. A readiness failure still attaches a picture of what the page showed, for diagnosis.
+
+**Example**
+
+```ts
+const shot = await captureUiState(page, { id: 'checkout/payment', route: '/checkout', ready: p => expectVisible(p, '#total') });
+await publishChecks(store, uiStateLayer({ producer: 'playwright', recordedAtMs: Date.now(), environment: 'desktop-web', profile: { viewport: '1280x800' }, states: [shot] }));
+```