@crvouga/atlas 1.13.0 → 1.14.0

package/dist/schema/src/api.d.ts

@@ -325,6 +325,26 @@ export declare const LayerRowSchema: z.ZodObject<{
             }, z.core.$loose>>;
         }, z.core.$loose>>>;
     }, z.core.$loose>>;
+    state: z.ZodOptional<z.ZodObject<{
+        route: z.ZodOptional<z.ZodString>;
+        fixture: z.ZodOptional<z.ZodString>;
+        cohort: z.ZodOptional<z.ZodString>;
+        area: z.ZodOptional<z.ZodString>;
+        flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inventory: z.ZodOptional<z.ZodBoolean>;
+        screenshot: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            bundleKey: z.ZodOptional<z.ZodString>;
+            uri: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            bytes: z.ZodOptional<z.ZodNumber>;
+            sha256: z.ZodOptional<z.ZodString>;
+            omitted: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
     recording: z.ZodOptional<z.ZodObject<{
         state: z.ZodString;
         reason: z.ZodOptional<z.ZodString>;
@@ -410,6 +430,26 @@ export declare const LayerRowsSchema: z.ZodObject<{
                 }, z.core.$loose>>;
             }, z.core.$loose>>>;
         }, z.core.$loose>>;
+        state: z.ZodOptional<z.ZodObject<{
+            route: z.ZodOptional<z.ZodString>;
+            fixture: z.ZodOptional<z.ZodString>;
+            cohort: z.ZodOptional<z.ZodString>;
+            area: z.ZodOptional<z.ZodString>;
+            flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inventory: z.ZodOptional<z.ZodBoolean>;
+            screenshot: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                bundleKey: z.ZodOptional<z.ZodString>;
+                uri: z.ZodOptional<z.ZodString>;
+                contentType: z.ZodOptional<z.ZodString>;
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                bytes: z.ZodOptional<z.ZodNumber>;
+                sha256: z.ZodOptional<z.ZodString>;
+                omitted: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
         recording: z.ZodOptional<z.ZodObject<{
             state: z.ZodString;
             reason: z.ZodOptional<z.ZodString>;
@@ -497,6 +537,26 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 }, z.core.$loose>>;
             }, z.core.$loose>>>;
         }, z.core.$loose>>;
+        state: z.ZodOptional<z.ZodObject<{
+            route: z.ZodOptional<z.ZodString>;
+            fixture: z.ZodOptional<z.ZodString>;
+            cohort: z.ZodOptional<z.ZodString>;
+            area: z.ZodOptional<z.ZodString>;
+            flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inventory: z.ZodOptional<z.ZodBoolean>;
+            screenshot: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                bundleKey: z.ZodOptional<z.ZodString>;
+                uri: z.ZodOptional<z.ZodString>;
+                contentType: z.ZodOptional<z.ZodString>;
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                bytes: z.ZodOptional<z.ZodNumber>;
+                sha256: z.ZodOptional<z.ZodString>;
+                omitted: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
         recording: z.ZodOptional<z.ZodObject<{
             state: z.ZodString;
             reason: z.ZodOptional<z.ZodString>;
@@ -674,6 +734,26 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     }, z.core.$loose>>;
                 }, z.core.$loose>>>;
             }, z.core.$loose>>;
+            state: z.ZodOptional<z.ZodObject<{
+                route: z.ZodOptional<z.ZodString>;
+                fixture: z.ZodOptional<z.ZodString>;
+                cohort: z.ZodOptional<z.ZodString>;
+                area: z.ZodOptional<z.ZodString>;
+                flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                inventory: z.ZodOptional<z.ZodBoolean>;
+                screenshot: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodString;
+                    bundleKey: z.ZodOptional<z.ZodString>;
+                    uri: z.ZodOptional<z.ZodString>;
+                    contentType: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    bytes: z.ZodOptional<z.ZodNumber>;
+                    sha256: z.ZodOptional<z.ZodString>;
+                    omitted: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+            }, z.core.$loose>>;
             recording: z.ZodOptional<z.ZodObject<{
                 state: z.ZodString;
                 reason: z.ZodOptional<z.ZodString>;
@@ -872,6 +952,26 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     }, z.core.$loose>>;
                 }, z.core.$loose>>>;
             }, z.core.$loose>>;
+            state: z.ZodOptional<z.ZodObject<{
+                route: z.ZodOptional<z.ZodString>;
+                fixture: z.ZodOptional<z.ZodString>;
+                cohort: z.ZodOptional<z.ZodString>;
+                area: z.ZodOptional<z.ZodString>;
+                flags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                covers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                inventory: z.ZodOptional<z.ZodBoolean>;
+                screenshot: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodString;
+                    bundleKey: z.ZodOptional<z.ZodString>;
+                    uri: z.ZodOptional<z.ZodString>;
+                    contentType: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    bytes: z.ZodOptional<z.ZodNumber>;
+                    sha256: z.ZodOptional<z.ZodString>;
+                    omitted: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+            }, z.core.$loose>>;
             recording: z.ZodOptional<z.ZodObject<{
                 state: z.ZodString;
                 reason: z.ZodOptional<z.ZodString>;
@@ -3540,3 +3640,253 @@ export declare const RunDetailSchema: z.ZodObject<{
         }, z.core.$loose>>;
     }, z.core.$loose>>>;
 }, z.core.$loose>;
+/** A state's profile: the client and the choices it was captured under. */
+export declare const UiProfileSchema: z.ZodObject<{
+    key: z.ZodString;
+    environment: z.ZodNullable<z.ZodString>;
+    parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+    label: z.ZodString;
+}, z.core.$loose>;
+/** The picture of a capture. */
+export declare const UiImageSchema: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    bytes: z.ZodOptional<z.ZodNumber>;
+    sha256: z.ZodOptional<z.ZodString>;
+    bundleKey: z.ZodOptional<z.ZodString>;
+    uri: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    omitted: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** One state in one profile. */
+export declare const UiCellSchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        key: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        label: z.ZodString;
+    }, z.core.$loose>;
+    coverage: z.ZodEnum<{
+        failed: "failed";
+        skipped: "skipped";
+        missing: "missing";
+        captured: "captured";
+        capturing: "capturing";
+    }>;
+    expected: z.ZodEnum<{
+        unknown: "unknown";
+        declared: "declared";
+        undeclared: "undeclared";
+    }>;
+    capture: z.ZodNullable<z.ZodObject<{
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodString;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        image: z.ZodNullable<z.ZodObject<{
+            name: z.ZodString;
+            contentType: z.ZodOptional<z.ZodString>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            bytes: z.ZodOptional<z.ZodNumber>;
+            sha256: z.ZodOptional<z.ZodString>;
+            bundleKey: z.ZodOptional<z.ZodString>;
+            uri: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            omitted: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        labels: z.ZodRecord<z.ZodString, z.ZodString>;
+        origin: z.ZodObject<{
+            layer: z.ZodString;
+            backend: z.ZodString;
+            producer: z.ZodString;
+            recordedAtMs: z.ZodNumber;
+            sha: z.ZodNullable<z.ZodString>;
+            branch: z.ZodNullable<z.ZodString>;
+            runUrl: z.ZodNullable<z.ZodString>;
+            freshness: z.ZodOptional<z.ZodEnum<{
+                unknown: "unknown";
+                modified: "modified";
+            }>>;
+        }, z.core.$loose>;
+        alternatives: z.ZodNumber;
+    }, z.core.$loose>>;
+    planned: z.ZodNullable<z.ZodObject<{
+        layer: z.ZodString;
+        backend: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * `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.
+ */
+export declare const UiCatalogSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    version: z.ZodOptional<z.ZodString>;
+    summary: z.ZodObject<{
+        states: z.ZodNumber;
+        profiles: z.ZodNumber;
+        cells: z.ZodNumber;
+        coverage: z.ZodObject<{
+            captured: z.ZodNumber;
+            failed: z.ZodNumber;
+            capturing: z.ZodNumber;
+            skipped: z.ZodNumber;
+            missing: z.ZodNumber;
+        }, z.core.$loose>;
+        undeclared: z.ZodNumber;
+        planned: z.ZodBoolean;
+        surfaces: z.ZodNumber;
+        uncoveredSurfaces: z.ZodNumber;
+    }, z.core.$loose>;
+    profiles: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        label: z.ZodString;
+    }, z.core.$loose>>;
+    states: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        route: z.ZodNullable<z.ZodString>;
+        fixture: z.ZodNullable<z.ZodString>;
+        cohort: z.ZodNullable<z.ZodString>;
+        area: z.ZodNullable<z.ZodString>;
+        flags: z.ZodArray<z.ZodString>;
+        covers: z.ZodArray<z.ZodString>;
+        producers: z.ZodArray<z.ZodString>;
+        cells: z.ZodArray<z.ZodObject<{
+            profile: z.ZodObject<{
+                key: z.ZodString;
+                environment: z.ZodNullable<z.ZodString>;
+                parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+                label: z.ZodString;
+            }, z.core.$loose>;
+            coverage: z.ZodEnum<{
+                failed: "failed";
+                skipped: "skipped";
+                missing: "missing";
+                captured: "captured";
+                capturing: "capturing";
+            }>;
+            expected: z.ZodEnum<{
+                unknown: "unknown";
+                declared: "declared";
+                undeclared: "undeclared";
+            }>;
+            capture: z.ZodNullable<z.ZodObject<{
+                status: z.ZodEnum<{
+                    passed: "passed";
+                    failed: "failed";
+                    running: "running";
+                    "not-run": "not-run";
+                }>;
+                detail: z.ZodString;
+                durationMs: z.ZodNullable<z.ZodNumber>;
+                image: z.ZodNullable<z.ZodObject<{
+                    name: z.ZodString;
+                    contentType: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    bytes: z.ZodOptional<z.ZodNumber>;
+                    sha256: z.ZodOptional<z.ZodString>;
+                    bundleKey: z.ZodOptional<z.ZodString>;
+                    uri: z.ZodOptional<z.ZodString>;
+                    path: z.ZodOptional<z.ZodString>;
+                    omitted: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                labels: z.ZodRecord<z.ZodString, z.ZodString>;
+                origin: z.ZodObject<{
+                    layer: z.ZodString;
+                    backend: z.ZodString;
+                    producer: z.ZodString;
+                    recordedAtMs: z.ZodNumber;
+                    sha: z.ZodNullable<z.ZodString>;
+                    branch: z.ZodNullable<z.ZodString>;
+                    runUrl: z.ZodNullable<z.ZodString>;
+                    freshness: z.ZodOptional<z.ZodEnum<{
+                        unknown: "unknown";
+                        modified: "modified";
+                    }>>;
+                }, z.core.$loose>;
+                alternatives: z.ZodNumber;
+            }, z.core.$loose>>;
+            planned: z.ZodNullable<z.ZodObject<{
+                layer: z.ZodString;
+                backend: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    surfaces: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        inventoried: z.ZodBoolean;
+        states: z.ZodNumber;
+        captured: z.ZodNumber;
+        status: z.ZodEnum<{
+            covered: "covered";
+            uncaptured: "uncaptured";
+            uncovered: "uncovered";
+        }>;
+    }, z.core.$loose>>;
+    facets: z.ZodObject<{
+        profiles: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        coverage: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        areas: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        routes: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        cohorts: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        flags: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        surfaces: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        producers: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    sources: z.ZodObject<{
+        layers: z.ZodNumber;
+        backends: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            live: z.ZodBoolean;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>;
+        notices: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    total: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;

package/dist/schema/src/api.js

@@ -130,6 +130,16 @@ export const LayerRowSchema = z.looseObject({
     variant: z.record(z.string(), z.string()),
     durationMs: z.number().nullable(),
     evidence: EvidenceSummarySchema.optional(),
+    state: z.looseObject({
+        route: z.string().optional(), fixture: z.string().optional(), cohort: z.string().optional(), area: z.string().optional(),
+        flags: z.array(z.string()).optional(), covers: z.array(z.string()).optional(),
+        inventory: z.boolean().optional().describe('A `ui-plan` entry that names a surface of the product\'s inventory, not a state'),
+        screenshot: z.looseObject({
+            name: z.string(), bundleKey: z.string().optional(), uri: z.string().optional(), contentType: z.string().optional(),
+            width: z.number().optional(), height: z.number().optional(), bytes: z.number().optional(), sha256: z.string().optional(),
+            omitted: z.string().optional().describe('Why the producer left the bytes out')
+        }).optional().describe('The check\'s picture: its `screenshot` attachment, else its first image')
+    }).optional().describe('Only for a check of a `ui-state` or `ui-plan` part: its picture and the facts its producer declared under the `atlas.ui-state` extension. See the UI catalog guide. Never decides a result'),
     recording: z.looseObject({ state: z.string(), reason: z.string().optional() }).optional().describe('What became of the check\'s expected recording: uploaded, referenced, skipped, unresolved or not-applicable. Independent of `status`')
 });
 /** A layer with its checks: the rows of one layer, read apart from its header. */
@@ -671,3 +681,64 @@ export const RunDetailSchema = z.looseObject({
         videos: VideoCountsSchema.optional()
     })).optional().describe('Every layer of the run, oldest first. Absent from an older server')
 });
+/** A state's profile: the client and the choices it was captured under. */
+export const UiProfileSchema = z.looseObject({
+    key: z.string().describe('Identifies the profile across layers: the environment and the sorted parameters'),
+    environment: z.string().nullable(), parameters: z.record(z.string(), z.string()),
+    label: z.string().describe('For a person: the client and each parameter\'s value')
+});
+/** The picture of a capture. */
+export const UiImageSchema = z.looseObject({
+    name: z.string(), contentType: z.string().optional(), width: z.number().optional(), height: z.number().optional(), bytes: z.number().optional(), sha256: z.string().optional(),
+    bundleKey: z.string().optional(), uri: z.string().optional().describe('An http(s) address, when the picture lives elsewhere'),
+    path: z.string().optional().describe('Where the stored bytes are, relative to the reports API root (`/api/reports` on a server): `/layers/<layer>/blobs/attachments/<sha256>`'),
+    omitted: z.string().optional().describe('Why the producer left the bytes out. A picture that is left out is not a picture that was never taken')
+});
+/** One state in one profile. */
+export const UiCellSchema = z.looseObject({
+    profile: UiProfileSchema,
+    coverage: z.enum(['captured', 'failed', 'capturing', 'skipped', 'missing']).describe('`captured` only when the winning capture passed. Every other value means there is no picture to trust'),
+    expected: z.enum(['declared', 'undeclared', 'unknown']).describe('`declared`: a plan expects it. `undeclared`: plans exist and none names it. `unknown`: no plan was published, so nothing is known to be unexpected'),
+    capture: z.looseObject({
+        status: EvidenceStatusSchema, detail: z.string(), durationMs: z.number().nullable(), image: UiImageSchema.nullable(),
+        labels: z.record(z.string(), z.string()).describe('What describes the capture without splitting it: a `shard`, a `browser`'),
+        origin: z.looseObject({
+            layer: z.string(), backend: z.string(), producer: z.string(), recordedAtMs: z.number(), sha: z.string().nullable(), branch: z.string().nullable(), runUrl: z.string().nullable(),
+            freshness: z.enum(['unknown', 'modified']).optional()
+        }),
+        alternatives: z.number().int().nonnegative().describe('Other captures of this cell from other producers; the winner is the one the report contract picks')
+    }).nullable(),
+    planned: z.looseObject({ layer: z.string(), backend: z.string() }).nullable().describe('The plan layer that expects this cell')
+});
+const UiFacetSchema = z.array(z.looseObject({ value: z.string(), count: z.number().int().nonnegative(), label: z.string().optional() }));
+/**
+ * `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.
+ */
+export const UiCatalogSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    version: z.string().optional().describe('The report version this was computed from; equal exactly when the report is'),
+    summary: z.looseObject({
+        states: z.number().int().nonnegative(), profiles: z.number().int().nonnegative(), cells: z.number().int().nonnegative(),
+        coverage: z.looseObject({ captured: z.number(), failed: z.number(), capturing: z.number(), skipped: z.number(), missing: z.number() }),
+        undeclared: z.number().int().nonnegative().describe('Cells captured or failed that no plan expects. Zero when no plan was published'),
+        planned: z.boolean().describe('Whether any plan was published. Without one `missing` is always zero: what should exist is unknown'),
+        surfaces: z.number().int().nonnegative(), uncoveredSurfaces: z.number().int().nonnegative()
+    }),
+    profiles: z.array(UiProfileSchema),
+    states: z.array(z.looseObject({
+        id: z.string(), title: z.string(),
+        route: z.string().nullable(), fixture: z.string().nullable(), cohort: z.string().nullable(), area: z.string().nullable(),
+        flags: z.array(z.string()), covers: z.array(z.string()).describe('The surfaces it covers'), producers: z.array(z.string()),
+        cells: z.array(UiCellSchema)
+    })),
+    surfaces: z.array(z.looseObject({
+        id: z.string(), inventoried: z.boolean().describe('A `ui-plan` inventory entry names it: the product is known to have it'),
+        states: z.number().int().nonnegative(), captured: z.number().int().nonnegative(),
+        status: z.enum(['covered', 'uncaptured', 'uncovered'])
+    })),
+    facets: z.looseObject({ profiles: UiFacetSchema, coverage: UiFacetSchema, areas: UiFacetSchema, routes: UiFacetSchema, cohorts: UiFacetSchema, flags: UiFacetSchema, surfaces: UiFacetSchema, producers: UiFacetSchema }),
+    sources: z.looseObject({ layers: z.number().int().nonnegative(), backends: z.array(BackendInfoSchema), notices: z.array(z.string()) }).describe('What was read. A backend that is unavailable, or a layer that could not be read, is named here; what depended on it is not shown as captured'),
+    total: z.number().int().nonnegative().optional().describe('States that matched, before `offset` and `limit`'),
+    offset: z.number().int().nonnegative().optional(), limit: z.number().int().nonnegative().optional()
+});

package/dist/server/src/app.js

@@ -28,6 +28,7 @@ import { listRunSummaries, readRunFile } from '../../reports/src/run-bundle.js';
 import { latestSpecSet, readSpecBody } from '../../reports/src/spec-set.js';
 import { catalogHealth, healthMarkdown, parseRootMappings } from '../../reports/src/catalog-health.js';
 import { parseArtifactFilter } from '../../reports/src/artifact-query.js';
+import { filterUiCatalog, pageUiCatalog, parseUiCatalogQuery, uiCatalog, uiCatalogMarkdown } from '../../reports/src/ui-catalog.js';
 import { parseReliabilityScope, reliability, reliabilityMarkdown } from '../../reports/src/reliability.js';
 import { artifactList, artifactsMarkdown, catalogMarkdown, catalogModel, historyMarkdown, parseTestQuery, runDetail, runList, runMarkdown, runsMarkdown, testCatalog, testHistory } from '../../reports/src/test-catalog.js';
 import { llmsTxt } from './llms.js';
@@ -418,6 +419,7 @@ function createProjectApplication(options) {
         }
         return model.value;
     };
+    let uiModel;
     const wantsMarkdown = (c) => {
         const format = c.req.query('format');
         return format === 'markdown' || format === 'md' || (format === undefined && /\btext\/markdown\b/.test(c.req.header('accept') ?? ''));
@@ -502,6 +504,19 @@ function createProjectApplication(options) {
         const document = () => artifactList(index.history, found.version, parseArtifactFilter(search), { limit: number('limit', 100), offset: number('offset', 0), domainOf: path => domains.get(path) });
         return answer(c, found.version, document, () => artifactsMarkdown(document()), `artifacts|${search.toString()}|${wantsMarkdown(c)}`);
     });
+    app.get('/api/reports/ui-catalog', async (c) => {
+        if (!index.ready)
+            return notReady(c);
+        const snapshot = index.snapshot();
+        const search = new URL(c.req.url).searchParams;
+        const number = (name, fallback) => (/^\d+$/.test(search.get(name) ?? '') ? Number(search.get(name)) : fallback);
+        // The catalog is a function of the report, so it is built once per version and narrowed per question.
+        if (uiModel?.version !== snapshot.version)
+            uiModel = { version: snapshot.version, value: uiCatalog(snapshot.layers, { version: snapshot.version, backends: snapshot.backends, notices: snapshot.notices }) };
+        const whole = uiModel.value;
+        const document = () => pageUiCatalog(filterUiCatalog(whole, parseUiCatalogQuery(search)), { limit: number('limit', 200), offset: number('offset', 0) });
+        return answer(c, snapshot.version, document, () => uiCatalogMarkdown(document()), `ui-catalog|${search.toString()}|${wantsMarkdown(c)}`);
+    });
     app.get('/api/reports/runs/detail', async (c) => {
         if (!index.ready)
             return notReady(c);

package/dist/server/src/openapi.js

@@ -14,7 +14,7 @@
  */
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
-import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, CatalogHealthSchema, TestHistorySchema, TestReliabilitySchema, RunListSchema, RunDetailSchema, ArtifactListSchema, UiCatalogSchema, ArtifactTagEditSchema, ArtifactTagEntrySchema, ArtifactTagsSchema, ReviewCollectionRequestSchema, ReviewCollectionSchema, ReviewCollectionListSchema, ReviewCollectionDetailSchema, ReviewNoteInputSchema, ReviewNoteSchema, ReviewManifestSchema } from '../../schema/src/api.js';
 import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, GcPolicySchema, GcSnapshotSchema, GcRunResultSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
 export const API_VERSION = '1.6.0';
@@ -38,7 +38,7 @@ const COMPONENTS = {
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
     ArtifactTagEdit: [ArtifactTagEditSchema, 'input'], ArtifactTagEntry: [ArtifactTagEntrySchema, 'output'], ArtifactTags: [ArtifactTagsSchema, 'output'],
     ReviewCollectionRequest: [ReviewCollectionRequestSchema, 'input'], ReviewCollection: [ReviewCollectionSchema, 'output'], ReviewCollectionList: [ReviewCollectionListSchema, 'output'], ReviewCollectionDetail: [ReviewCollectionDetailSchema, 'output'], ReviewNoteInput: [ReviewNoteInputSchema, 'input'], ReviewNote: [ReviewNoteSchema, 'output'], ReviewManifest: [ReviewManifestSchema, 'output'],
-    TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
+    TestCatalog: [TestCatalogSchema, 'output'], CatalogHealth: [CatalogHealthSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], TestReliability: [TestReliabilitySchema, 'output'], RunList: [RunListSchema, 'output'], ArtifactList: [ArtifactListSchema, 'output'], UiCatalog: [UiCatalogSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
 };
@@ -460,6 +460,26 @@ const BASE_OPERATIONS = [
         ],
         responses: { '200': json('The matching results and the facets.', 'ArtifactList'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
     },
+    {
+        route: 'GET /api/reports/ui-catalog', path: '/api/reports/ui-catalog', operationId: 'getUiCatalog', tag: 'Report', role: 'read',
+        summary: 'The UI catalog: captured UI states per profile, and what is still expected',
+        description: '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=`.',
+        parameters: [
+            { name: 'limit', in: 'query', description: 'At most this many states (default 200).', schema: { type: 'integer', minimum: 0 } },
+            { name: 'offset', in: 'query', description: 'Skip this many states (default 0).', schema: { type: 'integer', minimum: 0 } },
+            { name: 'q', in: 'query', description: 'Words that must all appear in a state\'s id, title, route, fixture, cohort, area, flags, surfaces or producers.', schema: str },
+            { name: 'coverage', in: 'query', description: 'Coverage values: `captured`, `failed`, `capturing`, `skipped`, `missing`. Comma-separated.', schema: str },
+            { name: 'profile', in: 'query', description: 'Profile keys, as listed in `profiles[].key`.', schema: str },
+            { name: 'area', in: 'query', description: 'Areas.', schema: str },
+            { name: 'route', in: 'query', description: 'Routes.', schema: str },
+            { name: 'cohort', in: 'query', description: 'Cohorts.', schema: str },
+            { name: 'flag', in: 'query', description: 'Feature flags a state was captured with.', schema: str },
+            { name: 'surface', in: 'query', description: 'Surfaces a state covers.', schema: str },
+            { name: 'producer', in: 'query', description: 'Producers that captured or planned a state.', schema: str },
+            { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': json('The catalog.', 'UiCatalog'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
+    },
     {
         route: 'GET /api/reports/runs/detail', path: '/api/reports/runs/detail', operationId: 'getReportRun', tag: 'Report', role: 'read',
         summary: 'Every test one run recorded',

package/docs/reference/http-api.md

@@ -926,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