@crvouga/atlas 1.20.0 → 1.22.0

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

@@ -0,0 +1,104 @@
+/**
+ * @module UI catalog comparison
+ *
+ * What changed in the UI catalog between two commits, or between two profiles, without claiming more than the evidence
+ * supports. Pure functions of {@link UiCatalog} documents (and of the layers they came from), safe in a browser; nothing here
+ * changes a status, a slot or a winner.
+ *
+ * - **Two commits.** The catalog of a commit is the catalog of the layers recorded at that commit ({@link uiCatalogAtCommit}).
+ *   A state is paired with itself in the same profile. A layer replaces the older one of its slot, so the effective report no
+ *   longer holds an earlier commit's captures: compare from the layers themselves ({@link readBackendLayers}), which keep them.
+ * - **Two profiles.** Within one catalog, each state's cell in one profile is set beside its cell in another
+ *   ({@link diffUiProfiles}): desktop against mobile, light against dark.
+ * - **Pictures are compared by content.** Two captures have the same picture when their stored bytes have the same SHA-256.
+ *   A different hash means different bytes, which is not a measure of how different the pixels are. When a side has no
+ *   content hash (a picture given only by address, or left out), whether it changed is `unverified`, never "unchanged".
+ * - **A state only one side has** is `added` or `removed`. It may be new or renamed, or the other side's shard may not have
+ *   run, and the comparison cannot tell which: it is not called a regression.
+ * - **A capture that did not pass is not a picture.** A cell that failed, is being taken or was skipped on a side is a change of
+ *   `coverage`, never compared by picture.
+ *
+ * @see docs/ui-catalog.md
+ */
+import type { LayerEvidence } from './evidence-types.js';
+import { type UiCatalog, type UiCatalogOptions, type UiCell, type UiImage, type UiProfile } from './ui-catalog.js';
+/** The `schemaVersion` of the comparison document. */
+export declare const UI_DIFF_VERSION = 1;
+/**
+ * How one pair of cells stands. `added`: only the after side has the cell. `removed`: only the before side has it.
+ * `coverage`: both have it and it stands differently (captured against failed, for example). `picture`: both captured and
+ * the bytes differ. `unverified`: both captured, but a side has no content hash, so whether the picture changed is unknown.
+ * `unchanged`: the same coverage and, when captured, the same bytes.
+ */
+export type UiCellChange = 'added' | 'removed' | 'coverage' | 'picture' | 'unverified' | 'unchanged';
+/** The values of {@link UiCellChange}, in the order a review reads them. */
+export declare const UI_CELL_CHANGES: readonly ["coverage", "picture", "unverified", "added", "removed", "unchanged"];
+/** One state in one profile on each side. */
+export type UiDiffEntry = {
+    /** The state's id. */
+    readonly id: string;
+    /** Its title, from the after side when it has the state. */
+    readonly title: string;
+    /** The profile both sides are in (a comparison of commits), or null when the two sides are different profiles. */
+    readonly profile: UiProfile | null;
+    readonly before: UiCell | null;
+    readonly after: UiCell | null;
+    readonly change: UiCellChange;
+};
+/** A comparison, as `atlas ui-catalog diff --format json` prints it and the viewer shows it. */
+export type UiCatalogDiff = {
+    readonly schemaVersion: typeof UI_DIFF_VERSION;
+    /** How many entries are in each {@link UiCellChange}. */
+    readonly summary: Readonly<Record<UiCellChange, number>> & {
+        readonly total: number;
+    };
+    /** Every pair, ordered by state id and then profile label. */
+    readonly entries: readonly UiDiffEntry[];
+};
+/**
+ * What identifies a picture's content: its recorded SHA-256, else the hash in a content-addressed bundle key
+ * (`attachments/<sha256>`), else `null`. A picture given only by address, or left out, has no identity here: its content is
+ * not Atlas's to vouch for.
+ */
+export declare function pictureIdentity(image: UiImage | null | undefined): string | null;
+/**
+ * Sets the catalog of an earlier commit (`before`) against a later one (`after`): each state in each profile is paired with
+ * itself. A cell that is only a plan (`missing`) on one side is a change of coverage like any other. The order of the
+ * states in either catalog does not matter.
+ */
+export declare function diffUiCatalogs(before: UiCatalog, after: UiCatalog): UiCatalogDiff;
+/**
+ * Sets one profile of a catalog (`from`, a {@link UiProfile.key}) against another (`to`): each state's cell in `from` beside its
+ * cell in `to`. A state that has a cell in only one of them is `added` or `removed`. Throws when the two are the same profile,
+ * because that compares a catalog with itself.
+ */
+export declare function diffUiProfiles(catalog: UiCatalog, from: string, to: string): UiCatalogDiff;
+/** The entries of a comparison that changed, or all of them. A change the comparison cannot verify is a change worth looking at, so it is kept. */
+export declare function changedUiEntries(diff: UiCatalogDiff): readonly UiDiffEntry[];
+/** A commit that has layers of the catalog's producers. */
+export type UiCommit = {
+    readonly sha: string;
+    /** The branch of the newest layer recorded at the commit, or null. */
+    readonly branch: string | null;
+    /** When the newest layer at the commit was recorded, epoch milliseconds. */
+    readonly recordedAtMs: number;
+    /** How many layers were recorded at the commit. */
+    readonly layers: number;
+};
+/**
+ * The commits layers were recorded at, newest first. A layer with no commit is left out: it cannot be compared by commit.
+ * Layers recorded from a checkout with uncommitted changes (`freshness` `modified`) are not the commit's own result and are
+ * left out too, as the gate does by default for comparisons.
+ */
+export declare function uiCatalogCommits(layers: readonly Pick<LayerEvidence['layer'], 'sha' | 'branch' | 'recordedAtMs' | 'freshness'>[]): UiCommit[];
+/**
+ * The layers recorded at one commit (`sha` is the whole commit id, or a prefix of at least 7 hexadecimal digits that names
+ * exactly one commit among `layers`). Throws when a prefix names none, or more than one, so a comparison never silently uses
+ * the wrong commit.
+ */
+export declare function layersAtCommit(layers: readonly LayerEvidence[], sha: string): LayerEvidence[];
+/**
+ * The UI catalog as it was recorded at one commit: only the layers recorded there take part. A state the commit's layers do
+ * not hold is absent, not failed. See {@link layersAtCommit} for how `sha` is matched.
+ */
+export declare function uiCatalogAtCommit(layers: readonly LayerEvidence[], sha: string, options?: UiCatalogOptions): UiCatalog;

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

@@ -0,0 +1,130 @@
+import { uiCatalog } from './ui-catalog.js';
+/** The `schemaVersion` of the comparison document. */
+export const UI_DIFF_VERSION = 1;
+/** The values of {@link UiCellChange}, in the order a review reads them. */
+export const UI_CELL_CHANGES = ['coverage', 'picture', 'unverified', 'added', 'removed', 'unchanged'];
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const SHA256 = /^[0-9a-f]{64}$/;
+/**
+ * What identifies a picture's content: its recorded SHA-256, else the hash in a content-addressed bundle key
+ * (`attachments/<sha256>`), else `null`. A picture given only by address, or left out, has no identity here: its content is
+ * not Atlas's to vouch for.
+ */
+export function pictureIdentity(image) {
+    if (!image || image.omitted)
+        return null;
+    const hash = image.sha256?.toLowerCase();
+    if (hash && SHA256.test(hash))
+        return hash;
+    const keyed = /^attachments\/([0-9a-fA-F]{64})$/.exec(image.bundleKey ?? '')?.[1];
+    return keyed ? keyed.toLowerCase() : null;
+}
+function changeOf(before, after) {
+    if (!before)
+        return 'added';
+    if (!after)
+        return 'removed';
+    if (before.coverage !== after.coverage)
+        return 'coverage';
+    if (before.coverage !== 'captured')
+        return 'unchanged';
+    const a = pictureIdentity(before.capture?.image), b = pictureIdentity(after.capture?.image);
+    if (a === null || b === null)
+        return 'unverified';
+    return a === b ? 'unchanged' : 'picture';
+}
+function summarize(entries) {
+    const counts = { coverage: 0, picture: 0, unverified: 0, added: 0, removed: 0, unchanged: 0 };
+    for (const entry of entries)
+        counts[entry.change] += 1;
+    return { ...counts, total: entries.length };
+}
+function ordered(entries) {
+    entries.sort((a, b) => compare(a.id, b.id) || compare(a.profile?.label ?? '', b.profile?.label ?? '') || compare(a.before?.profile.label ?? '', b.before?.profile.label ?? ''));
+    return { schemaVersion: UI_DIFF_VERSION, summary: summarize(entries), entries };
+}
+/**
+ * Sets the catalog of an earlier commit (`before`) against a later one (`after`): each state in each profile is paired with
+ * itself. A cell that is only a plan (`missing`) on one side is a change of coverage like any other. The order of the
+ * states in either catalog does not matter.
+ */
+export function diffUiCatalogs(before, after) {
+    const cells = (catalog) => new Map(catalog.states.flatMap(state => state.cells.map(cell => [`${state.id}\u0000${cell.profile.key}`, { state, cell }])));
+    const left = cells(before), right = cells(after);
+    const entries = [];
+    for (const key of new Set([...left.keys(), ...right.keys()])) {
+        const a = left.get(key), b = right.get(key);
+        const first = (b ?? a);
+        entries.push({ id: first.state.id, title: first.state.title, profile: first.cell.profile, before: a?.cell ?? null, after: b?.cell ?? null, change: changeOf(a?.cell ?? null, b?.cell ?? null) });
+    }
+    return ordered(entries);
+}
+/**
+ * Sets one profile of a catalog (`from`, a {@link UiProfile.key}) against another (`to`): each state's cell in `from` beside its
+ * cell in `to`. A state that has a cell in only one of them is `added` or `removed`. Throws when the two are the same profile,
+ * because that compares a catalog with itself.
+ */
+export function diffUiProfiles(catalog, from, to) {
+    if (from === to)
+        throw new Error('diffUiProfiles: choose two different profiles');
+    const entries = [];
+    for (const state of catalog.states) {
+        const a = state.cells.find(cell => cell.profile.key === from) ?? null;
+        const b = state.cells.find(cell => cell.profile.key === to) ?? null;
+        if (!a && !b)
+            continue;
+        entries.push({ id: state.id, title: state.title, profile: null, before: a, after: b, change: changeOf(a, b) });
+    }
+    return ordered(entries);
+}
+/** The entries of a comparison that changed, or all of them. A change the comparison cannot verify is a change worth looking at, so it is kept. */
+export function changedUiEntries(diff) {
+    return diff.entries.filter(entry => entry.change !== 'unchanged');
+}
+/**
+ * The commits layers were recorded at, newest first. A layer with no commit is left out: it cannot be compared by commit.
+ * Layers recorded from a checkout with uncommitted changes (`freshness` `modified`) are not the commit's own result and are
+ * left out too, as the gate does by default for comparisons.
+ */
+export function uiCatalogCommits(layers) {
+    const commits = new Map();
+    for (const layer of layers) {
+        if (!layer.sha || layer.freshness === 'modified')
+            continue;
+        const held = commits.get(layer.sha);
+        if (!held)
+            commits.set(layer.sha, { sha: layer.sha, branch: layer.branch, recordedAtMs: layer.recordedAtMs, layers: 1 });
+        else {
+            held.layers += 1;
+            if (layer.recordedAtMs > held.recordedAtMs) {
+                held.recordedAtMs = layer.recordedAtMs;
+                held.branch = layer.branch;
+            }
+        }
+    }
+    return [...commits.values()].sort((a, b) => b.recordedAtMs - a.recordedAtMs || compare(a.sha, b.sha));
+}
+/**
+ * The layers recorded at one commit (`sha` is the whole commit id, or a prefix of at least 7 hexadecimal digits that names
+ * exactly one commit among `layers`). Throws when a prefix names none, or more than one, so a comparison never silently uses
+ * the wrong commit.
+ */
+export function layersAtCommit(layers, sha) {
+    const wanted = sha.toLowerCase();
+    if (!/^[0-9a-f]{7,64}$/.test(wanted))
+        throw new Error(`"${sha}" is not a commit: give at least 7 hexadecimal digits of its id`);
+    const shas = new Set(layers.flatMap(entry => (entry.layer.sha && entry.layer.freshness !== 'modified' && entry.layer.sha.toLowerCase().startsWith(wanted) ? [entry.layer.sha.toLowerCase()] : [])));
+    if (shas.size === 0)
+        throw new Error(`No layer was recorded at commit ${sha}`);
+    if (shas.size > 1)
+        throw new Error(`"${sha}" names more than one commit (${[...shas].map(name => name.slice(0, 12)).join(', ')}): give more digits`);
+    const [only] = shas;
+    return layers.filter(entry => entry.layer.sha?.toLowerCase() === only && entry.layer.freshness !== 'modified');
+}
+/**
+ * The UI catalog as it was recorded at one commit: only the layers recorded there take part. A state the commit's layers do
+ * not hold is absent, not failed. See {@link layersAtCommit} for how `sha` is matched.
+ */
+export function uiCatalogAtCommit(layers, sha, options = {}) {
+    return uiCatalog(layersAtCommit(layers, sha), options);
+}

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

@@ -0,0 +1,147 @@
+/**
+ * @module UI catalog entries for critics
+ *
+ * The UI catalog seen as a flat, orderable list that a separate process can iterate: one **entry** per captured state in
+ * one profile that has a stored picture, with the hash of that picture and the critiques already made of it. A critic
+ * lists entries a page at a time with a stable cursor, asks only for those that changed since a report version it holds,
+ * asks only for those a given critic has not judged at the picture they have now, and fetches the picture itself by the
+ * `image.path` (served by the same safe attachment path as every other file). Nothing here is stored: entries are a function of the
+ * report, so the same layers in any order give the same list, and a missed event is covered by the next read.
+ *
+ * Critiques are opinions, never results: they ride along as evidence of an entry and change nothing about whether a
+ * report passes.
+ *
+ * @see docs/critics.md#reading-the-catalog
+ * @see docs/ui-catalog.md
+ */
+import type { Critique, CritiqueMark } from '../../schema/src/critique.js';
+import type { EvidenceStatus } from './explorer-types.js';
+import type { LayerEvidence } from './evidence-types.js';
+import { type UiOrigin, type UiProfile } from './ui-catalog.js';
+/** The `schemaVersion` of the entries document. */
+export declare const CATALOG_ENTRIES_VERSION = 1;
+/** The state kind of an entry whose producers declared none. It is unknown, not `screen`. */
+export declare const UNKNOWN_STATE_KIND = "unknown";
+/** The picture an entry was captured as: the hash critiques are anchored to, and where its stored bytes are. */
+export type EntryImage = {
+    /** SHA-256 of the exact stored bytes, lowercase hex. */
+    readonly sha256: string;
+    /** Where the bytes are, relative to the reports API root: `/layers/<layer>/blobs/attachments/<sha256>`. */
+    readonly path: string;
+    readonly contentType?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly bytes?: number;
+};
+/** A critique already made of an entry (any critic), and whether it judged the picture the entry has now. */
+export type EntryCritique = {
+    readonly layer: string;
+    readonly producer: string;
+    readonly recordedAtMs: number;
+    /** The check's own status: whether the critic ran, never what it thought. */
+    readonly status: EvidenceStatus;
+    /** `current`: it judged this picture. `earlier-image`: the picture changed since, so the entry counts as not yet judged by that critic. */
+    readonly currency: 'current' | 'earlier-image';
+    readonly critique: Critique;
+};
+/** A person's accept or dismiss of a critic's opinion about an entry that wins its slot, and whether it was made about the picture the entry has now. */
+export type EntryMark = {
+    readonly layer: string;
+    /** `critic.review.<reviewer>`. */
+    readonly producer: string;
+    readonly recordedAtMs: number;
+    /** `current`: made about this picture. `earlier-image`: the picture changed since, so the mark is shown as about an earlier picture and counts for nothing now. */
+    readonly currency: 'current' | 'earlier-image';
+    readonly mark: CritiqueMark;
+};
+/** One captured state in one profile, ready to be judged. */
+export type CatalogEntry = {
+    /** Stable identity, unique in the catalog: the state id, then `@` and the profile when it has one. */
+    readonly key: string;
+    readonly stateId: string;
+    readonly title: string;
+    readonly route: string | null;
+    readonly area: string | null;
+    /** The kind of UI state (`screen`, `overlay`, `loading`, `error`, `empty`…), or `unknown`. */
+    readonly state: string;
+    readonly profile: UiProfile;
+    readonly image: EntryImage;
+    /** The layer, backend and provenance of the capture. */
+    readonly origin: UiOrigin;
+    /** Critiques of this entry that win their slot, newest first. */
+    readonly critiques: readonly EntryCritique[];
+    /** Reviewers' marks (accept or dismiss) of those critiques that win their slot, newest first. Evidence: they never decide a result. */
+    readonly marks: readonly EntryMark[];
+};
+/** The entries of a report, and how many captured cells could not be offered for judging. */
+export type CatalogEntrySet = {
+    readonly entries: readonly CatalogEntry[];
+    /** Captured cells without a stored picture of a known hash (given only by address, left out, or not yet archived). They are not entries. */
+    readonly unjudgeable: number;
+};
+/**
+ * The key of the entry for a state in a profile. The state id alone when the profile says nothing; else
+ * `id@environment;name=value;…` with the parameters sorted and every part percent-encoded, so two profiles never share a key.
+ */
+export declare function catalogEntryKey(stateId: string, profile: Pick<UiProfile, 'environment' | 'parameters'>): string;
+/**
+ * The entries of some layers, in key order. Only a `captured` cell with a picture stored in its layer (`image.path`) and a
+ * known hash is an entry. Critiques are matched to entries by `subject.entryKey`, take the winner of each of their slots by
+ * the report contract, and are marked `earlier-image` when they judged other bytes.
+ */
+export declare function catalogEntries(layers: readonly LayerEvidence[]): CatalogEntrySet;
+/** Whether an entry has a current critique with a verdict from the critic (and, when given, its version). A failed critique is not a judgement: the next run retries it. */
+export declare function isJudgedBy(entry: Pick<CatalogEntry, 'critiques'>, critic: {
+    readonly name: string;
+    readonly version?: string;
+}): boolean;
+/** What a critic narrows the entries by. Every field is optional; nothing asked is everything. Values within a field are alternatives, fields combine with AND. */
+export type CatalogEntriesQuery = {
+    /** Words (all of them) found in the key, title, route or area. */
+    readonly q?: string;
+    readonly area?: readonly string[];
+    /** Profile keys, as `UiProfile.key`. */
+    readonly profile?: readonly string[];
+    /** State kinds: `screen`, `overlay`, `loading`… */
+    readonly state?: readonly string[];
+    readonly route?: readonly string[];
+    /** Only entries with no current critique with a verdict from this critic (`name`, or `name@version`). */
+    readonly unjudgedBy?: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    /** Only entries added or changed since this report version. A version the server does not remember is answered with everything. */
+    readonly since?: string;
+    /** Resume after the entry this cursor names. Opaque: take it from the previous page. */
+    readonly cursor?: string;
+    /** Entries per page. Default 100, at most 1000. */
+    readonly limit?: number;
+};
+/** The most entries one page holds. */
+export declare const MAX_ENTRIES_LIMIT = 1000;
+/** Reads a query from URL search parameters; the comma-separated lists, `q`, `unjudgedBy=name@version`, `since`, `cursor` and `limit`. A `limit` that is not a whole number is left out. */
+export declare function parseCatalogEntriesQuery(params: URLSearchParams): CatalogEntriesQuery;
+/** A query as URL search parameters, the form {@link parseCatalogEntriesQuery} reads back. */
+export declare function catalogEntriesParams(query: CatalogEntriesQuery): URLSearchParams;
+/** The opaque cursor after an entry. */
+export declare function encodeEntryCursor(key: string): string;
+/** The key a cursor names, or `null` when it is not a cursor this reader made. */
+export declare function decodeEntryCursor(cursor: string): string | null;
+/** One page of entries and where to resume. */
+export type CatalogEntryPage = {
+    /** The page, in key order. */
+    readonly entries: readonly CatalogEntry[];
+    /** Entries that match the query (all pages). */
+    readonly total: number;
+    /** The `cursor` of the next page, absent on the last. */
+    readonly nextCursor?: string;
+};
+/**
+ * One page of the entries that match a query, in key order. The order is by key and the cursor names the last key of a page, so
+ * a critic that iterates sees each entry exactly once however the catalog grows meanwhile (a new entry that sorts before the
+ * cursor is found by the next `since` read). `changed` is the set of layer ids that changed since `query.since`
+ * (`ReportIndex.changedSince`): `null` means the version was not remembered, and then everything matches.
+ *
+ * @throws Error when `query.cursor` is not a cursor.
+ */
+export declare function pageCatalogEntries(all: readonly CatalogEntry[], query: CatalogEntriesQuery, changed?: ReadonlySet<string> | null): CatalogEntryPage;

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

@@ -0,0 +1,190 @@
+import { CRITIQUE_PART_KIND } from '../../schema/src/critique.js';
+import { combineEvidence } from './layer-merge.js';
+import { uiCatalog } from './ui-catalog.js';
+/** The `schemaVersion` of the entries document. */
+export const CATALOG_ENTRIES_VERSION = 1;
+/** The state kind of an entry whose producers declared none. It is unknown, not `screen`. */
+export const UNKNOWN_STATE_KIND = 'unknown';
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * The key of the entry for a state in a profile. The state id alone when the profile says nothing; else
+ * `id@environment;name=value;…` with the parameters sorted and every part percent-encoded, so two profiles never share a key.
+ */
+export function catalogEntryKey(stateId, profile) {
+    const parameters = Object.entries(profile.parameters).sort(([a], [b]) => compare(a, b)).map(([name, text]) => `${encodeURIComponent(name)}=${encodeURIComponent(text)}`);
+    if (!profile.environment && !parameters.length)
+        return stateId;
+    return `${stateId}@${[encodeURIComponent(profile.environment ?? ''), ...parameters].join(';')}`;
+}
+function hashOf(image) {
+    if (image.sha256 && /^[0-9a-f]{64}$/i.test(image.sha256))
+        return image.sha256.toLowerCase();
+    return /(?:^|\/)([0-9a-f]{64})$/i.exec(image.bundleKey ?? '')?.[1]?.toLowerCase();
+}
+/**
+ * The entries of some layers, in key order. Only a `captured` cell with a picture stored in its layer (`image.path`) and a
+ * known hash is an entry. Critiques are matched to entries by `subject.entryKey`, take the winner of each of their slots by
+ * the report contract, and are marked `earlier-image` when they judged other bytes.
+ */
+export function catalogEntries(layers) {
+    const catalog = uiCatalog(layers);
+    const opinions = [];
+    for (const entry of layers) {
+        const rows = entry.rows.filter(row => row.kind === CRITIQUE_PART_KIND && (row.critique !== undefined || row.critiqueMark !== undefined));
+        if (rows.length)
+            opinions.push({ ...entry, rows });
+    }
+    const byEntry = new Map();
+    const marksByEntry = new Map();
+    for (const result of combineEvidence({ specs: [], sha: null, changedFiles: [] }, opinions).unassigned) {
+        const mark = result.row.critiqueMark;
+        if (mark) {
+            const marked = marksByEntry.get(mark.subject.entryKey) ?? [];
+            marked.push({ layer: result.layer, mark });
+            marksByEntry.set(mark.subject.entryKey, marked);
+        }
+        const critique = result.row.critique;
+        if (!critique)
+            continue;
+        const list = byEntry.get(critique.subject.entryKey) ?? [];
+        list.push({ layer: result.layer, status: result.row.status, critique });
+        byEntry.set(critique.subject.entryKey, list);
+    }
+    const entries = [];
+    let unjudgeable = 0;
+    for (const state of catalog.states) {
+        for (const cell of state.cells) {
+            if (cell.coverage !== 'captured' || !cell.capture)
+                continue;
+            const image = cell.capture.image;
+            const sha256 = image ? hashOf(image) : undefined;
+            if (!image || !image.path || !sha256) {
+                unjudgeable += 1;
+                continue;
+            }
+            const key = catalogEntryKey(state.id, cell.profile);
+            const critiques = (byEntry.get(key) ?? [])
+                .map(found => ({
+                layer: found.layer.id, producer: found.layer.producer, recordedAtMs: found.layer.recordedAtMs, status: found.status,
+                currency: found.critique.subject.imageSha256 === sha256 ? 'current' : 'earlier-image', critique: found.critique
+            }))
+                .sort((a, b) => b.recordedAtMs - a.recordedAtMs || compare(a.layer, b.layer));
+            const marks = (marksByEntry.get(key) ?? [])
+                .map(found => ({ layer: found.layer.id, producer: found.layer.producer, recordedAtMs: found.layer.recordedAtMs, currency: found.mark.subject.imageSha256 === sha256 ? 'current' : 'earlier-image', mark: found.mark }))
+                .sort((a, b) => b.recordedAtMs - a.recordedAtMs || compare(a.layer, b.layer));
+            entries.push({
+                key, stateId: state.id, title: state.title, route: state.route, area: state.area, state: state.kind ?? UNKNOWN_STATE_KIND, profile: cell.profile,
+                image: { sha256, path: image.path, ...(image.contentType ? { contentType: image.contentType } : {}), ...(image.width !== undefined ? { width: image.width } : {}), ...(image.height !== undefined ? { height: image.height } : {}), ...(image.bytes !== undefined ? { bytes: image.bytes } : {}) },
+                origin: cell.capture.origin, critiques, marks
+            });
+        }
+    }
+    entries.sort((a, b) => compare(a.key, b.key));
+    return { entries, unjudgeable };
+}
+/** Whether an entry has a current critique with a verdict from the critic (and, when given, its version). A failed critique is not a judgement: the next run retries it. */
+export function isJudgedBy(entry, critic) {
+    return entry.critiques.some(found => found.currency === 'current' && found.critique.critic.name === critic.name && (critic.version === undefined || found.critique.critic.version === critic.version) && found.critique.verdict !== undefined && !found.critique.failure);
+}
+const LIST_FIELDS = ['area', 'profile', 'state', 'route'];
+const DEFAULT_LIMIT = 100;
+/** The most entries one page holds. */
+export const MAX_ENTRIES_LIMIT = 1000;
+/** Reads a query from URL search parameters; the comma-separated lists, `q`, `unjudgedBy=name@version`, `since`, `cursor` and `limit`. A `limit` that is not a whole number is left out. */
+export function parseCatalogEntriesQuery(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(item => item.split(',')).map(item => item.trim()).filter(Boolean);
+        if (values.length)
+            query[name] = values;
+    }
+    const by = params.get('unjudgedBy')?.trim();
+    if (by) {
+        const at = by.lastIndexOf('@');
+        query.unjudgedBy = at > 0 ? { name: by.slice(0, at), version: by.slice(at + 1) } : { name: by };
+    }
+    const since = params.get('since')?.trim();
+    if (since)
+        query.since = since;
+    const cursor = params.get('cursor')?.trim();
+    if (cursor)
+        query.cursor = cursor;
+    const limit = params.get('limit');
+    if (limit !== null && /^\d+$/.test(limit))
+        query.limit = Number(limit);
+    return query;
+}
+/** A query as URL search parameters, the form {@link parseCatalogEntriesQuery} reads back. */
+export function catalogEntriesParams(query) {
+    const params = new URLSearchParams();
+    if (query.q)
+        params.set('q', query.q);
+    for (const name of LIST_FIELDS)
+        if (query[name]?.length)
+            params.set(name, query[name].join(','));
+    if (query.unjudgedBy)
+        params.set('unjudgedBy', query.unjudgedBy.version === undefined ? query.unjudgedBy.name : `${query.unjudgedBy.name}@${query.unjudgedBy.version}`);
+    if (query.since)
+        params.set('since', query.since);
+    if (query.cursor)
+        params.set('cursor', query.cursor);
+    if (query.limit !== undefined)
+        params.set('limit', String(query.limit));
+    return params;
+}
+/** The opaque cursor after an entry. */
+export function encodeEntryCursor(key) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(key))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+/** The key a cursor names, or `null` when it is not a cursor this reader made. */
+export function decodeEntryCursor(cursor) {
+    if (!/^[A-Za-z0-9_-]+$/.test(cursor))
+        return null;
+    try {
+        const binary = atob(cursor.replaceAll('-', '+').replaceAll('_', '/'));
+        const key = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(binary, char => char.charCodeAt(0)));
+        return key !== '' && encodeEntryCursor(key) === cursor ? key : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One page of the entries that match a query, in key order. The order is by key and the cursor names the last key of a page, so
+ * a critic that iterates sees each entry exactly once however the catalog grows meanwhile (a new entry that sorts before the
+ * cursor is found by the next `since` read). `changed` is the set of layer ids that changed since `query.since`
+ * (`ReportIndex.changedSince`): `null` means the version was not remembered, and then everything matches.
+ *
+ * @throws Error when `query.cursor` is not a cursor.
+ */
+export function pageCatalogEntries(all, query, changed = null) {
+    const terms = (query.q ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    const any = (wanted, has) => !wanted?.length || wanted.some(has);
+    const after = query.cursor === undefined ? null : decodeEntryCursor(query.cursor);
+    if (query.cursor !== undefined && after === null)
+        throw new Error('The cursor is not one this server made; start again without it.');
+    const limit = Math.min(MAX_ENTRIES_LIMIT, Math.max(1, query.limit ?? DEFAULT_LIMIT));
+    const matching = all.filter(entry => {
+        if (terms.length) {
+            const text = [entry.key, entry.title, entry.route, entry.area].filter(Boolean).join(' ').toLowerCase();
+            if (!terms.every(term => text.includes(term)))
+                return false;
+        }
+        if (!any(query.area, value => entry.area === value) || !any(query.profile, value => entry.profile.key === value) || !any(query.state, value => entry.state === value) || !any(query.route, value => entry.route === value))
+            return false;
+        if (query.unjudgedBy && isJudgedBy(entry, query.unjudgedBy))
+            return false;
+        if (query.since !== undefined && changed !== null && !changed.has(entry.origin.layer))
+            return false;
+        return true;
+    });
+    const rest = after === null ? matching : matching.filter(entry => entry.key > after);
+    const page = rest.slice(0, limit);
+    return { entries: page, total: matching.length, ...(rest.length > page.length ? { nextCursor: encodeEntryCursor(page[page.length - 1].key) } : {}) };
+}

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

@@ -0,0 +1,82 @@
+/**
+ * @module UI catalog single-file export
+ *
+ * The UI catalog as one HTML file that needs no server, no network and no build: open it from a disk, attach it to a ticket,
+ * host it anywhere that serves a file. Pictures are embedded as `data:` addresses, the manifest is embedded as JSON
+ * (`<script type="application/json" id="ui-catalog">`), and a few lines of script filter the states; with scripts off, every
+ * state is simply shown. It shows what the viewer's catalog shows, but it does not stream: it is the catalog at the moment it
+ * was made, and says when.
+ *
+ * Hosting platforms cap the size of one file, which is the reason a catalog is also a store and a viewer. The export keeps to a
+ * budget ({@link gatherUiPictures}): pictures past it are listed as left out with the reason, never silently dropped, and the
+ * manifest stays complete.
+ *
+ * Everything in the page is data from a test run. Text is escaped; only PNG, JPEG, GIF and WebP bytes whose first bytes say so
+ * are embedded (never SVG, never what a layer merely claims); a page address is linked only when it is `http` or `https`; the
+ * page carries a Content-Security-Policy that allows no network request at all.
+ *
+ * @see docs/ui-catalog.md
+ */
+import { type UiCapture, type UiCatalog } from './ui-catalog.js';
+/** A picture ready to embed. */
+export type UiExportPicture = {
+    readonly contentType: string;
+    readonly data: Uint8Array;
+};
+/** What {@link uiCatalogHtml} may be given besides the catalog. */
+export type UiExportOptions = {
+    /** The page's title. Default `UI catalog`. */
+    readonly title?: string;
+    /** The pictures to embed, by {@link uiPictureKey}. A cell whose key is not here shows why it has no picture. */
+    readonly pictures?: ReadonlyMap<string, UiExportPicture>;
+    /** Why a picture that could not be embedded is not here, by {@link uiPictureKey}: shown in its place. */
+    readonly left?: ReadonlyMap<string, string>;
+    /** When the export was made, epoch milliseconds. It is stated on the page so nobody mistakes it for a live view. Default: now. */
+    readonly generatedAtMs?: number;
+};
+/** The key of a capture's picture in {@link UiExportOptions.pictures}: its layer and its bundle key, or `null` when the picture is not stored in a layer. */
+export declare function uiPictureKey(capture: Pick<UiCapture, 'origin' | 'image'> | null | undefined): string | null;
+/** One picture an export may embed. */
+export type UiPictureWant = {
+    readonly key: string;
+    readonly layer: string;
+    readonly backend: string;
+    readonly bundleKey: string;
+    readonly bytes?: number;
+};
+/**
+ * The pictures of a catalog an export would embed, once each, in the order the page shows them. Only a cell that was captured, or
+ * that failed (a picture of what the page showed), and whose picture is stored in a layer, has one.
+ */
+export declare function uiPicturesWanted(catalog: UiCatalog): UiPictureWant[];
+/** The media type a picture's first bytes say it has (`image/png`, `image/jpeg`, `image/gif`, `image/webp`), or `null` for anything else, SVG included. */
+export declare function sniffImage(data: Uint8Array): string | null;
+/** What {@link gatherUiPictures} found. */
+export type UiPicturesGathered = {
+    readonly pictures: ReadonlyMap<string, UiExportPicture>;
+    /** Why each picture that is not in `pictures` is not. */
+    readonly left: ReadonlyMap<string, string>;
+    /** Bytes embedded. */
+    readonly bytes: number;
+};
+/**
+ * Reads the pictures an export wants through `read` (which returns the stored bytes of a picture, or `null` when the store
+ * no longer holds it) and keeps those that fit in `maxBytes` in total. A picture that is not stored, is not a PNG, JPEG, GIF or
+ * WebP, cannot be read, or would pass the budget is recorded in `left` with the reason; the pictures are taken in the page's
+ * order, so which are left out is deterministic. A `read` that throws is a picture left out, never a failed export.
+ */
+export declare function gatherUiPictures(wanted: readonly UiPictureWant[], read: (want: UiPictureWant) => Promise<Uint8Array | null>, options: {
+    readonly maxBytes: number;
+}): Promise<UiPicturesGathered>;
+/**
+ * The whole catalog as one self-contained HTML document. See the module description for what it contains and how it treats
+ * the data in it. Deterministic for the same catalog, pictures and `generatedAtMs`.
+ *
+ * @example
+ * ```ts
+ * const wanted = uiPicturesWanted(catalog);
+ * const { pictures, left } = await gatherUiPictures(wanted, want => readPicture(want), { maxBytes: 32 * 1024 * 1024 });
+ * await writeFile('catalog.html', uiCatalogHtml(catalog, { pictures, left }));
+ * ```
+ */
+export declare function uiCatalogHtml(catalog: UiCatalog, options?: UiExportOptions): string;