@crvouga/atlas 1.13.0 → 1.15.0

package/dist/reports/src/ui-catalog.d.ts

@@ -0,0 +1,229 @@
+/**
+ * @module UI catalog
+ *
+ * A browsable inventory of a product's user interface, computed from layers and nothing else: each **state** (a screen, or
+ * one state of a screen) captured once per **profile** (viewport, color scheme, device), with the facts needed to find and
+ * trust it, and what should exist but has not been captured yet. `uiCatalog` is a pure function of the winning results of
+ * the layers it is given, so it inherits the report contract's laws: the same layers in any order, split any way across
+ * backends, shards and machines, give the same catalog; a layer changes only the cells it fills; an unreadable layer is
+ * absent, never captured. It imports no collection framework and knows nothing about how a picture was taken.
+ *
+ * How the convention maps onto the layer format is in {@link ./ui-state}: a state is a check of a `ui-state` part, a profile
+ * is the layer's `environment` and `parameters`, the expected set is a `ui-plan` part. The viewer computes the catalog from
+ * the report it already streams (so it fills in as results arrive), and the server answers the same document at
+ * `GET /api/reports/ui-catalog`.
+ *
+ * @see docs/ui-catalog.md
+ * @see docs/report-contract.md#how-layers-compose
+ */
+import type { BackendInfo, LayerEvidence, LayerHeader } from './evidence-types.js';
+import type { EvidenceStatus } from './explorer-types.js';
+import { type UiScreenshot } from './ui-state.js';
+/** The `schemaVersion` of the catalog document. */
+export declare const UI_CATALOG_VERSION = 1;
+/** One profile: the client and the choices a state was captured under. Its `key` identifies it across layers. */
+export type UiProfile = {
+    /** Stable identity: the environment and the sorted parameters. */
+    readonly key: string;
+    /** The client (`desktop-web`, `ios`…), or null when the layer named none. */
+    readonly environment: string | null;
+    /** The layer's other choices, such as `{ viewport: '390x844', scheme: 'dark' }`. */
+    readonly parameters: Readonly<Record<string, string>>;
+    /** For a person: the client and each parameter's value. */
+    readonly label: string;
+};
+/**
+ * How one state stands in one profile. `captured`: a capture passed. `failed`: it was attempted and failed (its `detail`
+ * says why). `capturing`: it is being taken now. `skipped`: a producer recorded it as not run. `missing`: expected, and
+ * nothing has been recorded. Only `captured` is ever shown as captured; every other value means there is no picture to trust.
+ */
+export type UiCoverage = 'captured' | 'failed' | 'capturing' | 'skipped' | 'missing';
+/** The values of {@link UiCoverage}, in the order a person reads them. */
+export declare const UI_COVERAGE: readonly ["captured", "failed", "capturing", "skipped", "missing"];
+/** A picture, with the address a browser loads it from. */
+export type UiImage = UiScreenshot & {
+    /** Where the stored bytes are, relative to the reports API root (`/layers/<layer>/blobs/attachments/<sha256>`). Absent for an address-only or omitted picture. */
+    readonly path?: string;
+};
+/** Where a capture came from: the layer, the backend that holds it, and the provenance the layer recorded. */
+export type UiOrigin = {
+    readonly layer: string;
+    readonly backend: string;
+    readonly producer: string;
+    readonly recordedAtMs: number;
+    readonly sha: string | null;
+    readonly branch: string | null;
+    readonly runUrl: string | null;
+    readonly freshness?: 'unknown' | 'modified';
+};
+/** The winning capture of one cell. */
+export type UiCapture = {
+    readonly status: EvidenceStatus;
+    /** Why it failed or was skipped; empty otherwise. */
+    readonly detail: string;
+    readonly durationMs: number | null;
+    /** The picture, or null when the capture has none (or it was left out: see `omitted`). */
+    readonly image: UiImage | null;
+    /** The check's labels: what describes the capture without splitting it (a `shard`, a `browser`). */
+    readonly labels: Readonly<Record<string, string>>;
+    readonly origin: UiOrigin;
+    /** How many other captures of this cell exist from other producers. The winner is the one the report contract picks. */
+    readonly alternatives: number;
+};
+/** One state in one profile. */
+export type UiCell = {
+    readonly profile: UiProfile;
+    readonly coverage: UiCoverage;
+    /** Whether a plan expects this state in this profile: `declared`; `undeclared` when plans exist and none names it; `unknown` when no plan was published at all. */
+    readonly expected: 'declared' | 'undeclared' | 'unknown';
+    readonly capture: UiCapture | null;
+    /** The layer of the plan that expects it, when one does. */
+    readonly planned: {
+        readonly layer: string;
+        readonly backend: string;
+    } | null;
+};
+/** One state of the product's interface, across its profiles. */
+export type UiCatalogState = {
+    /** The check id the producers gave it. */
+    readonly id: string;
+    readonly title: string;
+    readonly route: string | null;
+    readonly fixture: string | null;
+    readonly cohort: string | null;
+    readonly area: string | null;
+    readonly flags: readonly string[];
+    /** The surfaces it covers. */
+    readonly covers: readonly string[];
+    /** The producers that captured or planned it. */
+    readonly producers: readonly string[];
+    /** One cell per profile, ordered by the profile's label. */
+    readonly cells: readonly UiCell[];
+};
+/** One surface of the product: an inventory entry, or something a state says it covers. */
+export type UiSurface = {
+    readonly id: string;
+    /** True when a `ui-plan` inventory entry names it: the product is known to have it. */
+    readonly inventoried: boolean;
+    /** States that cover it. */
+    readonly states: number;
+    /** Of those, states with at least one captured profile. */
+    readonly captured: number;
+    /** `covered`: some covering state is captured. `uncaptured`: states cover it and none is captured yet. `uncovered`: no state covers it. */
+    readonly status: 'covered' | 'uncaptured' | 'uncovered';
+};
+/** A value of a facet and how many states have it. */
+export type UiFacetValue = {
+    readonly value: string;
+    readonly count: number;
+    readonly label?: string;
+};
+/** The values each filter offers, over every state of the catalog. */
+export type UiCatalogFacets = {
+    readonly profiles: readonly UiFacetValue[];
+    readonly coverage: readonly UiFacetValue[];
+    readonly areas: readonly UiFacetValue[];
+    readonly routes: readonly UiFacetValue[];
+    readonly cohorts: readonly UiFacetValue[];
+    readonly flags: readonly UiFacetValue[];
+    readonly surfaces: readonly UiFacetValue[];
+    readonly producers: readonly UiFacetValue[];
+};
+/** The catalog in numbers. Cells count a state once per profile. */
+export type UiCatalogSummary = {
+    readonly states: number;
+    readonly profiles: number;
+    readonly cells: number;
+    readonly coverage: Readonly<Record<UiCoverage, number>>;
+    /** Captured or failed cells no plan expects. Zero when no plan was published, because then nothing is known to be unexpected. */
+    readonly undeclared: number;
+    /** Whether any plan (an expected set) was published. Without one, `missing` can only ever be zero. */
+    readonly planned: boolean;
+    readonly surfaces: number;
+    readonly uncoveredSurfaces: number;
+};
+/** The catalog, as `GET /api/reports/ui-catalog` answers it (`version` is the report's, when the caller knows it). */
+export type UiCatalog = {
+    readonly schemaVersion: typeof UI_CATALOG_VERSION;
+    readonly version?: string;
+    readonly summary: UiCatalogSummary;
+    readonly profiles: readonly UiProfile[];
+    readonly states: readonly UiCatalogState[];
+    readonly surfaces: readonly UiSurface[];
+    readonly facets: UiCatalogFacets;
+    /** What could not be read. A state that depended on it is not in the catalog as captured. Filled by the caller who read the backends. */
+    readonly sources: {
+        readonly layers: number;
+        readonly backends: readonly BackendInfo[];
+        readonly notices: readonly string[];
+    };
+};
+/** What a caller may say about how the layers were read. */
+export type UiCatalogOptions = {
+    /** The report's version, repeated in the document. */
+    readonly version?: string;
+    /** The backends, with whether each could be read. */
+    readonly backends?: readonly BackendInfo[];
+    /** What could not be read. */
+    readonly notices?: readonly string[];
+};
+/** The profile of a layer: its environment and its other parameters. */
+export declare function uiProfile(layer: Pick<LayerHeader, 'environment' | 'parameters'>): UiProfile;
+/**
+ * The UI catalog of some layers (as the effective report holds them, or any set of {@link LayerEvidence}).
+ *
+ * Only rows of `ui-state` and `ui-plan` parts take part. The winner of every slot is decided by the report contract
+ * (`combineEvidence`), so the result does not depend on the order of `layers` or on how they are divided among backends. A
+ * state is the set of cells that share a check `id`; a cell is one profile of it. A cell is `captured` only when the winning
+ * capture passed; a plan that nothing has captured is `missing`. When no plan exists nothing is `missing` and nothing is
+ * `undeclared`: what is expected is then unknown, and the catalog says so (`summary.planned`).
+ *
+ * @example
+ * ```ts
+ * const catalog = uiCatalog(effective.layers, { version: effective.version, backends: effective.backends });
+ * catalog.states.map(state => [state.id, state.cells.map(cell => cell.coverage)]);
+ * ```
+ */
+export declare function uiCatalog(layers: readonly LayerEvidence[], options?: UiCatalogOptions): UiCatalog;
+/** What a person narrows the catalog by. Every field is optional; nothing asked is everything. Values within a field are alternatives, fields combine with AND. */
+export type UiCatalogQuery = {
+    /** Words (all of them) found in the id, title, route, fixture, cohort, area, flags, surfaces or producers. */
+    readonly q?: string;
+    readonly coverage?: readonly UiCoverage[];
+    /** Profile keys, as {@link UiProfile.key}. */
+    readonly profile?: readonly string[];
+    readonly area?: readonly string[];
+    readonly route?: readonly string[];
+    readonly cohort?: readonly string[];
+    readonly flag?: readonly string[];
+    /** Surfaces a state covers. */
+    readonly surface?: readonly string[];
+    readonly producer?: readonly string[];
+};
+/** Reads a query from URL search parameters (`q`, and the comma-separated {@link UiCatalogQuery} lists). Unknown coverage values are left out, never an error. */
+export declare function parseUiCatalogQuery(params: URLSearchParams): UiCatalogQuery;
+/** A query as URL search parameters, the form {@link parseUiCatalogQuery} reads back. */
+export declare function uiCatalogParams(query: UiCatalogQuery): URLSearchParams;
+/** Whether a query narrows anything. */
+export declare function isUiCatalogFiltered(query: UiCatalogQuery): boolean;
+/**
+ * The part of a catalog a query asks for. A state is kept when it matches the words and the fact filters; its cells are
+ * kept when they match the `profile` and `coverage` filters, and a state left with no cell is dropped. The summary is
+ * recomputed for what is kept; the profiles, surfaces, facets and sources stay those of the whole catalog, so the
+ * controls keep offering every choice.
+ */
+export declare function filterUiCatalog(catalog: UiCatalog, query: UiCatalogQuery): UiCatalog;
+/** A page of a catalog's states, for a document that would otherwise be large. The summary, facets and sources are the whole catalog's. */
+export declare function pageUiCatalog(catalog: UiCatalog, page: {
+    readonly limit?: number;
+    readonly offset?: number;
+}): UiCatalog & {
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+};
+/**
+ * The catalog as Markdown for a person or an agent reading text: the summary in words, the surfaces that are not covered, and
+ * one line per state with its coverage in each profile. Only `captured` is called captured.
+ */
+export declare function uiCatalogMarkdown(catalog: UiCatalog): string;

package/dist/reports/src/ui-catalog.js

@@ -0,0 +1,273 @@
+import { joinList, splitList } from './artifact-query.js';
+import { combineEvidence, parameterKey, replaces } from './layer-merge.js';
+import { environmentLabel } from './layer-axes.js';
+import { UI_PLAN_KIND, UI_STATE_KIND } from './ui-state.js';
+/** The `schemaVersion` of the catalog document. */
+export const UI_CATALOG_VERSION = 1;
+/** The values of {@link UiCoverage}, in the order a person reads them. */
+export const UI_COVERAGE = ['captured', 'failed', 'capturing', 'skipped', 'missing'];
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** The profile of a layer: its environment and its other parameters. */
+export function uiProfile(layer) {
+    const parameters = layer.parameters;
+    const values = Object.entries(parameters).sort(([a], [b]) => compare(a, b)).map(([, value]) => value);
+    return {
+        key: `${layer.environment ?? ''}|${parameterKey(parameters)}`,
+        environment: layer.environment,
+        parameters,
+        label: [layer.environment ? environmentLabel(layer.environment) : 'No environment', ...values].join(' · ')
+    };
+}
+function encodeKey(key) {
+    return key.split('/').map(encodeURIComponent).join('/');
+}
+function imageOf(result) {
+    const shot = result.row.state?.screenshot;
+    if (!shot)
+        return null;
+    const webAddress = shot.uri && /^https?:\/\//i.test(shot.uri) ? shot.uri : undefined;
+    const { uri: _uri, ...rest } = shot;
+    // A live layer has no stored files; an archived one serves them by their key.
+    const path = shot.bundleKey && !result.layer.live ? `/layers/${encodeURIComponent(result.layer.id)}/blobs/${encodeKey(shot.bundleKey)}` : undefined;
+    return { ...rest, ...(webAddress ? { uri: webAddress } : {}), ...(path ? { path } : {}) };
+}
+function originOf(layer) {
+    return {
+        layer: layer.id, backend: layer.backend, producer: layer.producer, recordedAtMs: layer.recordedAtMs, sha: layer.sha, branch: layer.branch, runUrl: layer.runUrl,
+        ...(layer.freshness ? { freshness: layer.freshness } : {})
+    };
+}
+function coverageOf(status) {
+    return status === 'passed' ? 'captured' : status === 'failed' ? 'failed' : status === 'running' ? 'capturing' : 'skipped';
+}
+/** The newest result first, ties broken by the report contract's own order so no input order shows. */
+function newestFirst(a, b) {
+    return replaces(a, b) ? -1 : replaces(b, a) ? 1 : 0;
+}
+function facetOf(values, labels) {
+    const counts = new Map();
+    for (const list of values)
+        for (const value of new Set(list))
+            counts.set(value, (counts.get(value) ?? 0) + 1);
+    return [...counts].map(([value, count]) => ({ value, count, ...(labels?.get(value) ? { label: labels.get(value) } : {}) })).sort((a, b) => b.count - a.count || compare(a.value, b.value));
+}
+function emptyCoverage() {
+    return { captured: 0, failed: 0, capturing: 0, skipped: 0, missing: 0 };
+}
+/**
+ * The UI catalog of some layers (as the effective report holds them, or any set of {@link LayerEvidence}).
+ *
+ * Only rows of `ui-state` and `ui-plan` parts take part. The winner of every slot is decided by the report contract
+ * (`combineEvidence`), so the result does not depend on the order of `layers` or on how they are divided among backends. A
+ * state is the set of cells that share a check `id`; a cell is one profile of it. A cell is `captured` only when the winning
+ * capture passed; a plan that nothing has captured is `missing`. When no plan exists nothing is `missing` and nothing is
+ * `undeclared`: what is expected is then unknown, and the catalog says so (`summary.planned`).
+ *
+ * @example
+ * ```ts
+ * const catalog = uiCatalog(effective.layers, { version: effective.version, backends: effective.backends });
+ * catalog.states.map(state => [state.id, state.cells.map(cell => cell.coverage)]);
+ * ```
+ */
+export function uiCatalog(layers, options = {}) {
+    const taking = [];
+    for (const entry of layers) {
+        const rows = entry.rows.filter(row => row.kind === UI_STATE_KIND || row.kind === UI_PLAN_KIND);
+        if (rows.length)
+            taking.push({ ...entry, rows });
+    }
+    const winners = combineEvidence({ specs: [], sha: null, changedFiles: [] }, taking).unassigned;
+    const planned = winners.some(result => result.row.kind === UI_PLAN_KIND && !result.row.state?.inventory);
+    const states = new Map();
+    const inventory = new Set();
+    for (const result of winners) {
+        if (result.row.kind === UI_PLAN_KIND && result.row.state?.inventory) {
+            inventory.add(result.row.id);
+            continue;
+        }
+        let state = states.get(result.row.id);
+        if (!state)
+            states.set(result.row.id, state = { results: [], cells: new Map() });
+        state.results.push(result);
+        const profile = uiProfile(result.layer);
+        let cell = state.cells.get(profile.key);
+        if (!cell)
+            state.cells.set(profile.key, cell = { profile, captures: [], plans: [] });
+        (result.row.kind === UI_PLAN_KIND ? cell.plans : cell.captures).push(result);
+    }
+    const profiles = new Map();
+    const catalogStates = [];
+    for (const [id, state] of [...states].sort(([a], [b]) => compare(a, b))) {
+        const ordered = state.results.slice().sort(newestFirst);
+        const scalar = (pick) => ordered.map(pick).find((value) => value !== undefined) ?? null;
+        const union = (pick) => [...new Set(ordered.flatMap(result => pick(result) ?? []))].sort(compare);
+        const cells = [...state.cells.values()].sort((a, b) => compare(a.profile.label, b.profile.label) || compare(a.profile.key, b.profile.key)).map(cell => {
+            profiles.set(cell.profile.key, cell.profile);
+            const best = cell.captures.slice().sort(newestFirst)[0];
+            const plan = cell.plans.slice().sort(newestFirst)[0];
+            const capture = best ? {
+                status: best.row.status, detail: best.row.detail, durationMs: best.row.durationMs, image: imageOf(best),
+                labels: best.row.evidence?.labels ?? {}, origin: originOf(best.layer), alternatives: cell.captures.length - 1
+            } : null;
+            return {
+                profile: cell.profile,
+                coverage: best ? coverageOf(best.row.status) : 'missing',
+                expected: plan ? 'declared' : planned ? 'undeclared' : 'unknown',
+                capture,
+                planned: plan ? { layer: plan.layer.id, backend: plan.layer.backend } : null
+            };
+        });
+        catalogStates.push({
+            id, title: ordered[0]?.row.title ?? id,
+            route: scalar(result => result.row.state?.route), fixture: scalar(result => result.row.state?.fixture), cohort: scalar(result => result.row.state?.cohort), area: scalar(result => result.row.state?.area),
+            flags: union(result => result.row.state?.flags), covers: union(result => result.row.state?.covers),
+            producers: [...new Set(ordered.map(result => result.layer.producer))].sort(compare), cells
+        });
+    }
+    const surfaces = new Map();
+    for (const id of inventory)
+        surfaces.set(id, { states: 0, captured: 0 });
+    for (const state of catalogStates) {
+        const has = state.cells.some(cell => cell.coverage === 'captured');
+        for (const surface of state.covers) {
+            const found = surfaces.get(surface) ?? { states: 0, captured: 0 };
+            found.states += 1;
+            if (has)
+                found.captured += 1;
+            surfaces.set(surface, found);
+        }
+    }
+    const surfaceList = [...surfaces].sort(([a], [b]) => compare(a, b)).map(([id, found]) => ({
+        id, inventoried: inventory.has(id), states: found.states, captured: found.captured,
+        status: found.captured > 0 ? 'covered' : found.states > 0 ? 'uncaptured' : 'uncovered'
+    }));
+    const coverage = emptyCoverage();
+    let undeclared = 0, cells = 0;
+    for (const state of catalogStates)
+        for (const cell of state.cells) {
+            coverage[cell.coverage] += 1;
+            cells += 1;
+            if (cell.expected === 'undeclared')
+                undeclared += 1;
+        }
+    const profileList = [...profiles.values()].sort((a, b) => compare(a.label, b.label) || compare(a.key, b.key));
+    const labels = new Map(profileList.map(profile => [profile.key, profile.label]));
+    return {
+        schemaVersion: UI_CATALOG_VERSION,
+        ...(options.version ? { version: options.version } : {}),
+        summary: { states: catalogStates.length, profiles: profileList.length, cells, coverage, undeclared, planned, surfaces: surfaceList.length, uncoveredSurfaces: surfaceList.filter(surface => surface.status !== 'covered').length },
+        profiles: profileList,
+        states: catalogStates,
+        surfaces: surfaceList,
+        facets: {
+            profiles: facetOf(catalogStates.map(state => state.cells.map(cell => cell.profile.key)), labels),
+            coverage: UI_COVERAGE.map(value => ({ value, count: catalogStates.filter(state => state.cells.some(cell => cell.coverage === value)).length })),
+            areas: facetOf(catalogStates.map(state => (state.area ? [state.area] : []))),
+            routes: facetOf(catalogStates.map(state => (state.route ? [state.route] : []))),
+            cohorts: facetOf(catalogStates.map(state => (state.cohort ? [state.cohort] : []))),
+            flags: facetOf(catalogStates.map(state => state.flags)),
+            surfaces: facetOf(catalogStates.map(state => state.covers)),
+            producers: facetOf(catalogStates.map(state => state.producers))
+        },
+        sources: { layers: taking.length, backends: options.backends ?? [], notices: options.notices ?? [] }
+    };
+}
+const LIST_FIELDS = ['coverage', 'profile', 'area', 'route', 'cohort', 'flag', 'surface', 'producer'];
+/** Reads a query from URL search parameters (`q`, and the comma-separated {@link UiCatalogQuery} lists). Unknown coverage values are left out, never an error. */
+export function parseUiCatalogQuery(params) {
+    const query = {};
+    const q = params.get('q')?.trim();
+    if (q)
+        query.q = q;
+    for (const name of LIST_FIELDS) {
+        const values = params.getAll(name).flatMap(splitList);
+        const kept = name === 'coverage' ? values.filter(value => UI_COVERAGE.includes(value)) : values;
+        if (kept.length)
+            query[name] = kept;
+    }
+    return query;
+}
+/** A query as URL search parameters, the form {@link parseUiCatalogQuery} reads back. */
+export function uiCatalogParams(query) {
+    const params = new URLSearchParams();
+    if (query.q)
+        params.set('q', query.q);
+    for (const name of LIST_FIELDS) {
+        const joined = joinList(query[name] ?? []);
+        if (joined)
+            params.set(name, joined);
+    }
+    return params;
+}
+/** Whether a query narrows anything. */
+export function isUiCatalogFiltered(query) {
+    return Boolean(query.q) || LIST_FIELDS.some(name => (query[name]?.length ?? 0) > 0);
+}
+function haystack(state) {
+    return [state.id, state.title, state.route, state.fixture, state.cohort, state.area, ...state.flags, ...state.covers, ...state.producers].filter(Boolean).join(' ').toLowerCase();
+}
+/**
+ * The part of a catalog a query asks for. A state is kept when it matches the words and the fact filters; its cells are
+ * kept when they match the `profile` and `coverage` filters, and a state left with no cell is dropped. The summary is
+ * recomputed for what is kept; the profiles, surfaces, facets and sources stay those of the whole catalog, so the
+ * controls keep offering every choice.
+ */
+export function filterUiCatalog(catalog, query) {
+    if (!isUiCatalogFiltered(query))
+        return catalog;
+    const terms = (query.q ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    const any = (wanted, has) => !wanted?.length || wanted.some(has);
+    const states = [];
+    for (const state of catalog.states) {
+        if (terms.length) {
+            const text = haystack(state);
+            if (!terms.every(term => text.includes(term)))
+                continue;
+        }
+        if (!any(query.area, value => state.area === value) || !any(query.route, value => state.route === value) || !any(query.cohort, value => state.cohort === value))
+            continue;
+        if (!any(query.flag, value => state.flags.includes(value)) || !any(query.surface, value => state.covers.includes(value)) || !any(query.producer, value => state.producers.includes(value)))
+            continue;
+        const cells = state.cells.filter(cell => any(query.profile, value => cell.profile.key === value) && any(query.coverage, value => cell.coverage === value));
+        if (cells.length)
+            states.push(cells.length === state.cells.length ? state : { ...state, cells });
+    }
+    const coverage = emptyCoverage();
+    let cells = 0, undeclared = 0;
+    for (const state of states)
+        for (const cell of state.cells) {
+            coverage[cell.coverage] += 1;
+            cells += 1;
+            if (cell.expected === 'undeclared')
+                undeclared += 1;
+        }
+    return { ...catalog, states, summary: { ...catalog.summary, states: states.length, cells, coverage, undeclared } };
+}
+/** A page of a catalog's states, for a document that would otherwise be large. The summary, facets and sources are the whole catalog's. */
+export function pageUiCatalog(catalog, page) {
+    const offset = Math.max(0, page.offset ?? 0);
+    const limit = Math.max(0, page.limit ?? 200);
+    return { ...catalog, total: catalog.states.length, offset, limit, states: catalog.states.slice(offset, offset + limit) };
+}
+/**
+ * The catalog as Markdown for a person or an agent reading text: the summary in words, the surfaces that are not covered, and
+ * one line per state with its coverage in each profile. Only `captured` is called captured.
+ */
+export function uiCatalogMarkdown(catalog) {
+    const { summary } = catalog;
+    const lines = [
+        '# UI catalog', '',
+        `${summary.states} states in ${summary.profiles} profiles: ${UI_COVERAGE.map(value => `${summary.coverage[value]} ${value}`).join(', ')}.`,
+        summary.planned ? `${summary.undeclared} captured cells are not in any plan.` : 'No plan was published, so what should exist is unknown and nothing is shown as missing.'
+    ];
+    for (const notice of catalog.sources.notices)
+        lines.push('', `> ${notice}`);
+    const open = catalog.surfaces.filter(surface => surface.status !== 'covered');
+    if (open.length)
+        lines.push('', '## Surfaces without a captured state', '', ...open.map(surface => `- ${surface.id}: ${surface.status === 'uncovered' ? 'no state covers it' : 'covered by states that are not captured'}`));
+    lines.push('', '## States', '');
+    for (const state of catalog.states) {
+        lines.push(`- **${state.title}** (${state.id})${state.route ? ` ${state.route}` : ''}: ${state.cells.map(cell => `${cell.profile.label} ${cell.coverage}`).join('; ')}`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/reports/src/ui-state.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module UI state conventions
+ *
+ * How a captured UI state is written in a layer, using nothing but what the layer format already has. A **state** is a
+ * check in a part of kind `ui-state`: its `id` names the state, its `status` says how the capture went, a `screenshot`
+ * attachment is the picture, and the facts the producer declares about it (route, fixture, cohort, flags, the surfaces it
+ * covers) sit under the `atlas.ui-state` extension. A **profile** (viewport, color scheme, device) is the layer's
+ * `environment` and `parameters`, so a state captured at another viewport is another result, side by side. What is
+ * **expected** is a layer of kind `ui-plan` with the same ids and profiles, every check `not-run`.
+ *
+ * Nothing here decides a result: a status, a slot and a winner are what the report contract says they are. This module
+ * only reads the convention into a small optional row field ({@link UiStateFact}) so a viewer needs no second request to
+ * list a catalog. A producer that writes something else is still read; what cannot be read is left out, never rejected.
+ *
+ * @see docs/ui-catalog.md
+ */
+import type { Check } from '../../schema/src/layer.js';
+/** The part kind of captured states. */
+export declare const UI_STATE_KIND = "ui-state";
+/** The part kind of the expected set: states (and surfaces) that should exist, whether or not they were captured. */
+export declare const UI_PLAN_KIND = "ui-plan";
+/** The check extension that carries the facts a producer declares about a state. */
+export declare const UI_STATE_EXTENSION = "atlas.ui-state";
+/** Whether a part kind belongs to the UI catalog (`ui-state` or `ui-plan`). */
+export declare function isUiKind(kind: string): boolean;
+/** The picture of a captured state: a stored file (`bundleKey`), or an address (`uri`). Everything but `name` is optional. */
+export type UiScreenshot = {
+    readonly name: string;
+    readonly bundleKey?: string;
+    readonly uri?: string;
+    readonly contentType?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly bytes?: number;
+    readonly sha256?: string;
+    /** Why the producer left the bytes out (`too-large`, `policy`…): a picture that was never taken is told apart from one left out. */
+    readonly omitted?: string;
+};
+/** The facts a producer declares about a state, under the `atlas.ui-state` extension. All optional, all strings or lists of strings. */
+export type UiStateFacts = {
+    /** The address or screen the state is of (`/checkout/payment`). */
+    readonly route?: string;
+    /** The test data it was captured with. */
+    readonly fixture?: string;
+    /** The audience or account kind it shows (`new-customer`). */
+    readonly cohort?: string;
+    /** Feature flags that were on. */
+    readonly flags?: readonly string[];
+    /** The product surfaces (screens, components) this state covers, for coverage against an inventory. */
+    readonly covers?: readonly string[];
+    /** A grouping a person navigates by (`checkout`). */
+    readonly area?: string;
+    /** On a `ui-plan` check only: this entry is a surface of the product's inventory, not a state. Nothing is captured for it. */
+    readonly inventory?: boolean;
+};
+/** What a row of a `ui-state` or `ui-plan` part carries for the catalog. Rides in the report row, only for those kinds. */
+export type UiStateFact = UiStateFacts & {
+    /** The check's picture: its `screenshot` attachment, else its first image. */
+    readonly screenshot?: UiScreenshot;
+};
+/**
+ * The declared facts of a check, read from its `atlas.ui-state` extension. Strings are trimmed and bounded, lists are
+ * distinct and bounded, and anything of another shape is dropped; a check without the extension has no facts.
+ */
+export declare function uiStateFacts(check: Pick<Check, 'extensions'>): UiStateFacts;
+/**
+ * What a check of a part of `kind` carries for the catalog: its declared facts and, in a `ui-state` part, its picture.
+ * `undefined` for any other kind, and for a UI check that carries neither, so ordinary rows stay as small as they were.
+ */
+export declare function uiStateOf(kind: string, check: Pick<Check, 'extensions' | 'attachments'>): UiStateFact | undefined;

package/dist/reports/src/ui-state.js

@@ -0,0 +1,66 @@
+/** The part kind of captured states. */
+export const UI_STATE_KIND = 'ui-state';
+/** The part kind of the expected set: states (and surfaces) that should exist, whether or not they were captured. */
+export const UI_PLAN_KIND = 'ui-plan';
+/** The check extension that carries the facts a producer declares about a state. */
+export const UI_STATE_EXTENSION = 'atlas.ui-state';
+/** Whether a part kind belongs to the UI catalog (`ui-state` or `ui-plan`). */
+export function isUiKind(kind) {
+    return kind === UI_STATE_KIND || kind === UI_PLAN_KIND;
+}
+const MAX_TEXT = 512;
+const MAX_LIST = 64;
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim().slice(0, MAX_TEXT) : undefined;
+}
+function list(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [...new Set(value.map(text).filter((item) => item !== undefined))].slice(0, MAX_LIST);
+    return out.length ? out : undefined;
+}
+function screenshotOf(check) {
+    const images = (check.attachments ?? []).filter(item => item.role === 'screenshot' || (item.contentType ?? '').startsWith('image/'));
+    const picked = images.find(item => item.role === 'screenshot') ?? images[0];
+    if (!picked)
+        return undefined;
+    return {
+        name: picked.name,
+        ...(picked.bundleKey ? { bundleKey: picked.bundleKey } : {}),
+        ...(picked.uri ? { uri: picked.uri } : {}),
+        ...(picked.contentType ? { contentType: picked.contentType } : {}),
+        ...(picked.width !== undefined ? { width: picked.width } : {}),
+        ...(picked.height !== undefined ? { height: picked.height } : {}),
+        ...(picked.bytes !== undefined ? { bytes: picked.bytes } : {}),
+        ...(picked.sha256 ? { sha256: picked.sha256 } : {}),
+        ...(picked.omitted ? { omitted: picked.omitted } : {})
+    };
+}
+/**
+ * The declared facts of a check, read from its `atlas.ui-state` extension. Strings are trimmed and bounded, lists are
+ * distinct and bounded, and anything of another shape is dropped; a check without the extension has no facts.
+ */
+export function uiStateFacts(check) {
+    const raw = check.extensions?.[UI_STATE_EXTENSION];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return {};
+    const given = raw;
+    const route = text(given.route), fixture = text(given.fixture), cohort = text(given.cohort), area = text(given.area);
+    const flags = list(given.flags), covers = list(given.covers);
+    return {
+        ...(route ? { route } : {}), ...(fixture ? { fixture } : {}), ...(cohort ? { cohort } : {}), ...(area ? { area } : {}),
+        ...(flags ? { flags } : {}), ...(covers ? { covers } : {}),
+        ...(given.inventory === true ? { inventory: true } : {})
+    };
+}
+/**
+ * What a check of a part of `kind` carries for the catalog: its declared facts and, in a `ui-state` part, its picture.
+ * `undefined` for any other kind, and for a UI check that carries neither, so ordinary rows stay as small as they were.
+ */
+export function uiStateOf(kind, check) {
+    if (!isUiKind(kind))
+        return undefined;
+    const facts = uiStateFacts(check);
+    const screenshot = kind === UI_STATE_KIND ? screenshotOf(check) : undefined;
+    return screenshot || Object.keys(facts).length ? { ...facts, ...(screenshot ? { screenshot } : {}) } : undefined;
+}