@crvouga/atlas 0.3.0 → 0.5.0

package/dist/reports/src/explorer-types.d.ts

@@ -1,50 +1,87 @@
-/** Commit-scoped definitions and independently produced evidence. */
+/**
+ * @module Explorer data types
+ *
+ * The plain shapes the reports explorer shares between the store readers, the API routes and the viewer: a spec
+ * entry, a commit's spec inventory, the four result statuses, measurements, checks and parts. They are types only
+ * and carry no behaviour. The vocabulary matches the layer document (`docs/report-contract.md`): `status` is the
+ * closed set of four, everything else about a check is open.
+ */
+/** Commit-scoped definitions and independently produced evidence. One spec of the outline a report is laid over. */
 export type SpecEntry = {
+    /** `specs/<path inside the specs directory>`. The `specPath` a check uses to say which spec it belongs to. */
     readonly path: string;
+    /** Groups specs in the viewer (by default the project's folder name). */
     readonly domain: string;
+    /** The notation: `gherkin`, `quint`, `dmn`, `alloy`, `openslo`, a file extension, or `document`. An open vocabulary. */
     readonly kind: string;
     readonly title: string;
+    /** A fingerprint of the spec's text, so a reader can warn when a spec changed since a layer recorded it. Opaque. */
     readonly fingerprint?: string;
 };
+/** The specs of one commit. */
 export type SpecInventory = {
+    /** The 40-hex-digit commit. */
     readonly sha: string;
     readonly entries: readonly SpecEntry[];
 };
+/** The four result statuses. The only closed vocabulary in the format: `not-run` is never a pass and `running` is not done. */
 export type EvidenceStatus = 'passed' | 'failed' | 'running' | 'not-run';
+/** A number a check recorded. Exceeding `limit` is shown and never fails the check by itself. */
 export type EvidenceMeasurement = {
     readonly name: string;
     readonly value: number;
+    /** The unit of `value` and `limit`, such as `ms`. */
     readonly unit: string;
+    /** The allowance for `value`, in the same unit, when there is one. */
     readonly limit?: number;
 };
-export type EvidenceCheck = {
+/** What a check may carry beyond its outcome. All optional and open: see docs/extending.md. */
+export type EvidenceExtras = Partial<Pick<import('../../schema/src/layer.js').Check, 'tags' | 'labels' | 'links' | 'steps' | 'attachments' | 'annotations' | 'attempts' | 'extensions'>>;
+/** One check of a part, as recorded. */
+export type EvidenceCheck = EvidenceExtras & {
+    /** Stable across runs; the newer result replaces the older one only if both used the same id. */
     readonly id: string;
     readonly title: string;
     readonly status: EvidenceStatus;
+    /** Why the check has this status, for a person. */
     readonly detail: string;
+    /** The spec the check belongs to, as `specs/<path>`. */
     readonly specPath?: string;
     readonly measurements: readonly EvidenceMeasurement[];
+    /** How long the check took, when the producer measured it. */
+    readonly durationMs?: number;
 };
 /** `kind` is an open producer key; new parts need no protocol change. */
-export type ReportPart = {
+export type ReportPart = EvidenceExtras & {
+    /** `modified`: recorded from a checkout with uncommitted changes; `unknown`: origin not captured. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** String choices that make a result its own slot (a device, a seed). */
     readonly parameters?: Readonly<Record<string, string>>;
+    /** The commit the part was recorded at. */
     readonly sha: string;
+    /** The part's id; when the part is published it is the `producer` of the layer made from it. */
     readonly id: string;
+    /** Open category (`behavior`, `performance`, ...); part of the slot. */
     readonly kind: string;
     readonly title: string;
+    /** When the checks ran, epoch milliseconds. */
     readonly recordedAtMs: number;
     readonly checks: readonly EvidenceCheck[];
 };
+/** The part of a {@link ReportPart} that a spec run's evidence file carries: its `kind`, `title` and `checks`. */
 export type ReportPartOutput = Pick<ReportPart, 'kind' | 'title' | 'checks'>;
+/** What the explorer shows for one commit: its specs (or null when none were recorded) and the parts recorded against it. */
 export type ExplorerData = {
     readonly inventory: SpecInventory | null;
     readonly parts: readonly ReportPart[];
+    /** A message to show instead of data, when something could not be read. */
     readonly notice?: string;
 };
+/** The checkout a workspace reads from. */
 export type WorkspaceVersion = {
     readonly sha: string;
     readonly branch: string;
+    /** True when the checkout has uncommitted changes. */
     readonly dirty: boolean;
 };
 /** Only composition roots provide checkout content; it is never CI evidence. */

package/dist/reports/src/explorer-types.js

@@ -0,0 +1,8 @@
+/**
+ * @module Explorer data types
+ *
+ * The plain shapes the reports explorer shares between the store readers, the API routes and the viewer: a spec
+ * entry, a commit's spec inventory, the four result statuses, measurements, checks and parts. They are types only
+ * and carry no behaviour. The vocabulary matches the layer document (`docs/report-contract.md`): `status` is the
+ * closed set of four, everything else about a check is open.
+ */

package/dist/reports/src/explorer-versions.d.ts

@@ -1,4 +1,12 @@
 import type { ObjectStore } from './object-store.js';
-/** A per-version marker lets an independent producer appear without a spec run. */
+/**
+ * Writes the marker `versions/<sha>.json` (`{"sha": "<sha>"}`) so an independent producer's commit appears without
+ * a spec run. Writing it again is harmless. Throws `Invalid commit` when `sha` is not a 40-hex-digit commit.
+ */
 export declare function recordExplorerVersion(store: ObjectStore, sha: string): Promise<void>;
+/**
+ * Lists the commits that have a marker, in key order. Keys under `versions/` that are not `<40 hex>.json` are
+ * ignored. A marker that is missing at read time or whose content does not name its own sha is not skipped:
+ * it throws `Invalid explorer version`, so corrupt data fails visibly.
+ */
 export declare function listExplorerVersions(store: ObjectStore): Promise<readonly string[]>;

package/dist/reports/src/explorer-versions.js

@@ -1,11 +1,28 @@
+/**
+ * @module Explorer version markers
+ *
+ * Marker files `versions/<sha>.json` that list which commits a store has anything recorded for, so the explorer can
+ * show a commit that has parts or specs but no spec run. A store layout older than layers; the markers are small,
+ * immutable and idempotent to write, and are read in place by newer readers.
+ *
+ * @see docs/report-contract.md (stores written before layers existed)
+ */
 import { readUtf8, writeUtf8 } from './object-io.js';
 import { isCommitSha } from './keys.js';
-/** A per-version marker lets an independent producer appear without a spec run. */
+/**
+ * Writes the marker `versions/<sha>.json` (`{"sha": "<sha>"}`) so an independent producer's commit appears without
+ * a spec run. Writing it again is harmless. Throws `Invalid commit` when `sha` is not a 40-hex-digit commit.
+ */
 export async function recordExplorerVersion(store, sha) {
     if (!isCommitSha(sha))
         throw new Error('Invalid commit');
     await writeUtf8(store, `versions/${sha}.json`, JSON.stringify({ sha }), 'application/json');
 }
+/**
+ * Lists the commits that have a marker, in key order. Keys under `versions/` that are not `<40 hex>.json` are
+ * ignored. A marker that is missing at read time or whose content does not name its own sha is not skipped:
+ * it throws `Invalid explorer version`, so corrupt data fails visibly.
+ */
 export async function listExplorerVersions(store) {
     const versions = [];
     for (const key of await store.listKeys('versions/')) {

package/dist/reports/src/export-evidence.d.ts

@@ -1,6 +1,21 @@
 import type { ObjectStore } from './object-store.js';
+/**
+ * Maps a report API path (with its query) to the file an export stores it under, for example `/evidence?cursor=x`
+ * to `evidence/pages/x.json` and `/` to `index.json`. Files a layer carries (`/blobs/`, `/files/`, `frame.css`,
+ * `report.json`) keep their path so their type stays known by name; everything else gets `.json` appended. Pure.
+ */
 export declare function evidenceFile(path: string): string;
-/** Export the combined report, preserving layer provenance and lazy recording addresses. */
+/**
+ * Exports the combined report, preserving layer provenance and lazy recording addresses.
+ *
+ * `args.fetch` answers report API paths (`/outline`, `/evidence?cursor=`, ...), for example the reports app's own
+ * `request`. Every response is stored in `args.target` under {@link evidenceFile}, each path once. A 404 or 503 for
+ * a path is recorded in `missing` and skipped; any other failure throws, as does a layer catalog that repeats a
+ * page. Live runs are left out and each execution is exported once. Nothing in `target` is deleted.
+ *
+ * @returns `revisions` (distinct commits among the exported layers), `layers` (layers exported) and `missing`
+ * (paths that were not there).
+ */
 export declare function exportEvidence(args: {
     fetch: (path: string) => Promise<Response>;
     target: ObjectStore;

package/dist/reports/src/export-evidence.js

@@ -1,21 +1,55 @@
+/**
+ * @module Static export of a report
+ *
+ * Copies what a running reports API serves (outline, spec texts, layer pages, rows, per-result evidence, recorded
+ * files) into an {@link ObjectStore}, one file per URL, so the viewer can be hosted statically. {@link evidenceFile}
+ * is the single mapping from an API path to the exported file name; the exporter writes with it and a static host
+ * must read with it. Only collected layers are exported (a static site has no running suite).
+ */
 import { eachLimited } from './completion-order.js';
+import { bundleKeysOf } from './evidence-detail.js';
 import { recordingPaths } from './evidence-types.js';
 import { distinctHeaders } from './layer-merge.js';
 import { writeUtf8 } from './object-io.js';
 import { capturedFiles } from './frames.js';
+/**
+ * Maps a report API path (with its query) to the file an export stores it under, for example `/evidence?cursor=x`
+ * to `evidence/pages/x.json` and `/` to `index.json`. Files a layer carries (`/blobs/`, `/files/`, `frame.css`,
+ * `report.json`) keep their path so their type stays known by name; everything else gets `.json` appended. Pure.
+ */
 export function evidenceFile(path) {
     const url = new URL(path || '/', 'http://atlas');
     if (url.pathname === '/')
         return 'index.json';
     if (url.pathname === '/evidence' && url.searchParams.has('cursor'))
         return `evidence/pages/${encodeURIComponent(url.searchParams.get('cursor'))}.json`;
+    // One result's evidence: a file per result, named by its check (and kind), beside its layer's own.
+    const detail = /^\/evidence\/detail\/([^/]+)\/([^/]+)$/.exec(url.pathname);
+    if (detail) {
+        const check = url.searchParams.get('check');
+        const kind = url.searchParams.get('kind');
+        return `evidence/detail/${detail[1]}/${detail[2]}${check === null ? '' : `/${encodeURIComponent(check)}${kind ? `~${encodeURIComponent(kind)}` : ''}`}.json`;
+    }
+    // A file a layer carries: kept as it is, with its type known by its name.
+    if (url.pathname.includes('/blobs/'))
+        return url.pathname.slice(1);
     if (url.pathname.endsWith('/spec'))
         return `${url.pathname.slice(1, -5)}/specs/${encodeURIComponent(url.searchParams.get('path') ?? '')}.txt`;
     if (url.pathname.includes('/files/') || url.pathname.endsWith('/frame.css') || url.pathname.endsWith('/report.json'))
         return url.pathname.slice(1);
     return `${url.pathname.slice(1)}.json`;
 }
-/** Export the combined report, preserving layer provenance and lazy recording addresses. */
+/**
+ * Exports the combined report, preserving layer provenance and lazy recording addresses.
+ *
+ * `args.fetch` answers report API paths (`/outline`, `/evidence?cursor=`, ...), for example the reports app's own
+ * `request`. Every response is stored in `args.target` under {@link evidenceFile}, each path once. A 404 or 503 for
+ * a path is recorded in `missing` and skipped; any other failure throws, as does a layer catalog that repeats a
+ * page. Live runs are left out and each execution is exported once. Nothing in `target` is deleted.
+ *
+ * @returns `revisions` (distinct commits among the exported layers), `layers` (layers exported) and `missing`
+ * (paths that were not there).
+ */
 export async function exportEvidence(args) {
     const missing = [];
     const copied = new Map();
@@ -67,6 +101,23 @@ export async function exportEvidence(args) {
             if (layer.sha)
                 revisions.add(layer.sha);
             const rowsText = await copy(`/evidence/rows/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}`);
+            // Evidence a result carries: what it says, and every file it points to.
+            if (rowsText) {
+                const withEvidence = JSON.parse(rowsText).rows.filter(row => row.evidence);
+                const copyDetail = async (path) => {
+                    const text = await copy(path);
+                    if (!text)
+                        return;
+                    const read = JSON.parse(text);
+                    const keys = new Set([...bundleKeysOf('check' in read ? read.check : {}), ...bundleKeysOf(read.run)]);
+                    await eachLimited([...keys], 4, key => copy(`/layers/${encodeURIComponent(layer.id)}/blobs/${key.split('/').map(encodeURIComponent).join('/')}`).then(() => { }));
+                };
+                const base = `/evidence/detail/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}`;
+                if (layer.evidence)
+                    await copyDetail(base);
+                for (const row of withEvidence)
+                    await copyDetail(`${base}?check=${encodeURIComponent(row.id)}&kind=${encodeURIComponent(row.kind)}`);
+            }
             const recording = layer.recording;
             if (!rowsText || !recording)
                 return;

package/dist/reports/src/fetcher.d.ts

@@ -1,9 +1,13 @@
 /**
- * Cacheable reads of a reports API. Commit pages, sources, stylesheets and
+ * @module Cacheable reads of a commit-keyed reports API
+ *
+ * The client side of the older, commit-addressed reports API (`/<sha>/explorer`, `/<sha>/spec`,
+ * `/<sha>/sources`, `/<sha>/tests/<source>/<testId>`, ...). Commit pages, sources, stylesheets and
  * test timelines go through TanStack Query. Frame files also land in
  * `ReportCache` (IndexedDB on the wall, a map in tests) so a scrub reads
  * bytes the browser already kept, without putting multi-megabyte HTML into
- * the query document.
+ * the query document. A 503 from the API means reports are not available and throws {@link ReportsUnavailable};
+ * a 404 for a spec, test or frame is answered as `null` (or an empty stylesheet), not an error.
  */
 import type { ExplorerData } from './explorer-types.js';
 import type { CommitPage, SourceRecord } from './protocol.js';
@@ -11,17 +15,24 @@ import type { HtmlReportBlob } from './recording-bundle.js';
 import type { RunReport } from './report-types.js';
 import type { HttpClient } from './http.js';
 import { QueryClient } from '@tanstack/solid-query';
+/** Thrown when the reports API answers 503: no reports store is configured or reachable. Its message is `reports_unavailable`. */
 export declare class ReportsUnavailable extends Error {
     constructor();
 }
 /** String store the query persister and frame files share. */
 export type ReportCache = {
+    /** The saved value, or null when there is none. */
     get(key: string): Promise<string | null>;
+    /** Saves a value, replacing any under the key. */
     set(key: string, value: string): Promise<void>;
+    /** Forgets a key; a missing key is not an error. */
     remove(key: string): Promise<void>;
 };
+/** A {@link ReportCache} held in a `Map`, lost on reload. For tests and hosts without persistent storage. */
 export declare function memoryReportCache(): ReportCache;
+/** Creates the TanStack `QueryClient` the fetcher expects: results stay fresh 5 minutes, are kept 1 day, and are neither retried nor refetched on window focus. */
 export declare function reportQueryClient(): QueryClient;
+/** The TanStack query keys of each read, so a host can invalidate or persist them. Every key starts with `reports`. */
 export declare const reportQueryKey: {
     commits: readonly ["reports", "commits"];
     explorer: (sha: string) => readonly ["reports", "explorer", string];
@@ -31,20 +42,33 @@ export declare const reportQueryKey: {
     test: (sha: string, source: string, testId: string) => readonly ["reports", "test", string, string, string];
     blob: (sha: string, source: string, testId: string, file: string) => readonly ["reports", "blob", string, string, string, string];
 };
+/** The reads the explorer makes. Rejections are `ReportsUnavailable` (503) or an `Error` naming the HTTP status. */
 export type ReportFetcher = {
+    /** The specs and parts recorded for a commit. Never served from a stale query (always refetched). */
     explorer(sha: string): Promise<ExplorerData>;
+    /** The text of one spec of a commit, or null when it is not there. */
     spec(sha: string, path: string): Promise<string | null>;
+    /** One page of commits; pass the previous page's `cursor`, or null for the first page. */
     commits(cursor: string | null): Promise<CommitPage>;
+    /** The spec-run sources of a commit. */
     sources(sha: string): Promise<readonly SourceRecord[]>;
+    /** The stylesheet snapshots of a commit render with; empty when there is none. */
     frameCss(sha: string): Promise<string>;
+    /** One recorded test's report, or null when it is not there. */
     test(sha: string, source: string, testId: string): Promise<RunReport | null>;
+    /** One captured file of a test, or null when it is missing (a missing file is retried on the next call). Resolved from the `ReportCache` before the network. */
     blob(sha: string, source: string, testId: string, file: string): Promise<HtmlReportBlob | null>;
 };
+/** What {@link createHttpReportFetcher} needs. */
 export type ReportFetcherArgs = {
+    /** The HTTP client used for every request. */
     readonly http: HttpClient;
+    /** The URL prefix of the reports API, prepended to each path with no added slash (for example `/api/reports`). */
     readonly apiBase: string;
+    /** The query cache; see {@link reportQueryClient}. */
     readonly client: QueryClient;
+    /** Where captured frame files are kept between visits. */
     readonly cache: ReportCache;
 };
-/** Query-cached reads. Frame files resolve from `cache` before the network. */
+/** Creates a {@link ReportFetcher} over HTTP with query-cached reads. Frame files resolve from `cache` before the network. */
 export declare function createHttpReportFetcher(args: ReportFetcherArgs): ReportFetcher;

package/dist/reports/src/fetcher.js

@@ -1,19 +1,25 @@
 /**
- * Cacheable reads of a reports API. Commit pages, sources, stylesheets and
+ * @module Cacheable reads of a commit-keyed reports API
+ *
+ * The client side of the older, commit-addressed reports API (`/<sha>/explorer`, `/<sha>/spec`,
+ * `/<sha>/sources`, `/<sha>/tests/<source>/<testId>`, ...). Commit pages, sources, stylesheets and
  * test timelines go through TanStack Query. Frame files also land in
  * `ReportCache` (IndexedDB on the wall, a map in tests) so a scrub reads
  * bytes the browser already kept, without putting multi-megabyte HTML into
- * the query document.
+ * the query document. A 503 from the API means reports are not available and throws {@link ReportsUnavailable};
+ * a 404 for a spec, test or frame is answered as `null` (or an empty stylesheet), not an error.
  */
 import { QueryClient } from '@tanstack/solid-query';
 const MINUTE = 60_000;
 const DAY = 24 * 60 * MINUTE;
+/** Thrown when the reports API answers 503: no reports store is configured or reachable. Its message is `reports_unavailable`. */
 export class ReportsUnavailable extends Error {
     constructor() {
         super('reports_unavailable');
         this.name = 'ReportsUnavailable';
     }
 }
+/** A {@link ReportCache} held in a `Map`, lost on reload. For tests and hosts without persistent storage. */
 export function memoryReportCache() {
     const map = new Map();
     return {
@@ -28,6 +34,7 @@ export function memoryReportCache() {
         },
     };
 }
+/** Creates the TanStack `QueryClient` the fetcher expects: results stay fresh 5 minutes, are kept 1 day, and are neither retried nor refetched on window focus. */
 export function reportQueryClient() {
     return new QueryClient({
         defaultOptions: {
@@ -40,6 +47,7 @@ export function reportQueryClient() {
         },
     });
 }
+/** The TanStack query keys of each read, so a host can invalidate or persist them. Every key starts with `reports`. */
 export const reportQueryKey = {
     commits: ['reports', 'commits'],
     explorer: (sha) => ['reports', 'explorer', sha],
@@ -142,7 +150,7 @@ function blobPath(sha, source, testId, file) {
         .join('/');
     return `/${sha}/tests/${encodeURIComponent(source)}/${encodeURIComponent(testId)}/files/${encoded}`;
 }
-/** Query-cached reads. Frame files resolve from `cache` before the network. */
+/** Creates a {@link ReportFetcher} over HTTP with query-cached reads. Frame files resolve from `cache` before the network. */
 export function createHttpReportFetcher(args) {
     const { http, apiBase, client } = args;
     return {

package/dist/reports/src/format-date.d.ts

@@ -1 +1,7 @@
+/**
+ * @module Date formatting
+ *
+ * Formats epoch-millisecond timestamps for display in the viewer's locale.
+ */
+/** Formats epoch milliseconds as a local date and time (`toLocaleString`); an empty string for 0 or missing, and the number as text if it cannot be formatted. */
 export declare function fmtDate(ms: number): string;

package/dist/reports/src/format-date.js

@@ -1,3 +1,9 @@
+/**
+ * @module Date formatting
+ *
+ * Formats epoch-millisecond timestamps for display in the viewer's locale.
+ */
+/** Formats epoch milliseconds as a local date and time (`toLocaleString`); an empty string for 0 or missing, and the number as text if it cannot be formatted. */
 export function fmtDate(ms) {
     if (!ms)
         return '';

package/dist/reports/src/format.d.ts

@@ -1,7 +1,16 @@
+/**
+ * @module Display formatting for recorded tests
+ *
+ * Small pure formatters the viewer uses to show durations, file names, action lines and captured blobs. Nothing
+ * here reads a store or the network; missing or unreadable input becomes a placeholder, never an exception.
+ */
 import type { HtmlReportTest } from './recording-bundle.js';
 import type { ReportSnapshotBlob } from './report-types.js';
+/** Formats milliseconds compactly (`850ms`, `1.5s`, `2m 5s`); `—` for null, undefined or a non-finite number. */
 export declare function fmtMs(ms: number | null | undefined): string;
+/** The last `/`-separated segment of a path; empty for no path. */
 export declare function fileName(path: string | undefined): string;
+/** The group label for a test's source file: its base name, or `Other` when it has none. */
 export declare function fileLabel(sourceFile: string | undefined): string;
 /** Compact `arg, arg` for an action line. Empty when the step recorded none. */
 export declare function formatArgs(args: readonly unknown[] | undefined): string;
@@ -11,6 +20,13 @@ export declare function actionLabel(step: {
     readonly args?: readonly unknown[] | undefined;
     readonly title: string;
 }): string;
+/**
+ * The text to show for a captured blob: binary blobs become a `(binary name, ~N bytes)` placeholder, JSON is
+ * pretty-printed (left as is if it does not parse), anything else is shown as stored, and `(missing)` when the
+ * test does not hold the blob's file.
+ */
 export declare function formatBlobBody(test: HtmlReportTest, blob: ReportSnapshotBlob): string;
+/** The heading line of a blob: `name · nodeId · media`, without the node when it has none. */
 export declare function blobHeading(blob: ReportSnapshotBlob): string;
+/** A `data:` URL for a blob stored as base64 bytes, or null when the test holds no such bytes (text blobs have none). */
 export declare function downloadUrl(test: HtmlReportTest, blob: ReportSnapshotBlob): string | null;

package/dist/reports/src/format.js

@@ -1,4 +1,5 @@
 import { blobDataUrl, blobText } from './frames.js';
+/** Formats milliseconds compactly (`850ms`, `1.5s`, `2m 5s`); `—` for null, undefined or a non-finite number. */
 export function fmtMs(ms) {
     if (ms === null || ms === undefined || !Number.isFinite(ms))
         return '—';
@@ -8,9 +9,11 @@ export function fmtMs(ms) {
         return `${(ms / 1000).toFixed(1)}s`;
     return `${Math.floor(ms / 60000)}m ${Math.round((ms % 60000) / 1000)}s`;
 }
+/** The last `/`-separated segment of a path; empty for no path. */
 export function fileName(path) {
     return path ? (path.split('/').pop() ?? '') : '';
 }
+/** The group label for a test's source file: its base name, or `Other` when it has none. */
 export function fileLabel(sourceFile) {
     return sourceFile ? fileName(sourceFile) : 'Other';
 }
@@ -44,6 +47,11 @@ export function actionLabel(step) {
         return step.title;
     return `${step.action}(${formatArgs(step.args)})`;
 }
+/**
+ * The text to show for a captured blob: binary blobs become a `(binary name, ~N bytes)` placeholder, JSON is
+ * pretty-printed (left as is if it does not parse), anything else is shown as stored, and `(missing)` when the
+ * test does not hold the blob's file.
+ */
 export function formatBlobBody(test, blob) {
     if (blob.media === 'bytes') {
         const bin = test.blobs[blob.file];
@@ -63,9 +71,11 @@ export function formatBlobBody(test, blob) {
     }
     return text;
 }
+/** The heading line of a blob: `name · nodeId · media`, without the node when it has none. */
 export function blobHeading(blob) {
     return `${blob.name}${blob.nodeId ? ` · ${blob.nodeId}` : ''} · ${blob.media}`;
 }
+/** A `data:` URL for a blob stored as base64 bytes, or null when the test holds no such bytes (text blobs have none). */
 export function downloadUrl(test, blob) {
     return blobDataUrl(test, blob);
 }

package/dist/reports/src/frames.d.ts

@@ -1,12 +1,24 @@
+/**
+ * @module Frames of a recorded test
+ *
+ * Pure helpers over a recorded test's step tree: flattening it into time-ordered frames (captured snapshots),
+ * choosing the frame and actor a route selects, stepping to neighbouring frames or failures, and listing the files
+ * a report names. Results of `testFrames` and the per-actor orderings are cached per test, keyed by the identity of
+ * `test.report.steps`, so treat a loaded report as immutable. Nothing here reads a store.
+ */
 import type { HtmlReportTest } from './recording-bundle.js';
 import type { ReportFrame, ReportSnapshotBlob, ReportStep, RunReport } from './report-types.js';
 import type { Route } from './hash.js';
+/** A frame placed in its step, in the flattened timeline. */
 export type FlatFrame = {
     step: ReportStep;
     frame: ReportFrame;
+    /** How deeply the step is nested (0 for a top-level step). */
     depth: number;
+    /** Position in the flattened list this frame came from; `testFrames` renumbers it by capture time. Route `frame=N` is `index + 1`. */
     index: number;
 };
+/** A UI snapshot slot for one client (actor) of a frame. */
 export type OrderedUiBlob = {
     readonly nodeId: string;
     /** This frame's snapshot, or the client's latest earlier one when stale. */
@@ -14,31 +26,52 @@ export type OrderedUiBlob = {
     /** True when `blob` is carried forward from an earlier frame. */
     readonly stale: boolean;
 };
+/** A step placed in the flattened (depth-first) step list. */
 export type FlatStep = {
     step: ReportStep;
     depth: number;
+    /** The enclosing step, or null for a top-level step. */
     parent: FlatStep | null;
     index: number;
 };
+/** Flattens the frames of a step tree depth first (a step's own frames, then its children's), in step order, not capture-time order. Appends to `out`. */
 export declare function flattenFrames(steps: readonly ReportStep[], out?: FlatFrame[], depth?: number): FlatFrame[];
+/** Flattens a step tree depth first into rows that know their depth and parent. Appends to `out`. */
 export declare function flattenSteps(steps: readonly ReportStep[], out?: FlatStep[], depth?: number, parent?: FlatStep | null): FlatStep[];
+/** The first frame of `step`, or failing that of its first descendant that has one; null when none of them has a frame. */
 export declare function firstFrameFor(step: ReportStep, frames: readonly FlatFrame[]): FlatFrame | null;
+/** The last frame (in list order, which should be capture-time order) captured at or before the step ended; null when none was. */
 export declare function lastFrameBefore(step: ReportStep, frames: readonly FlatFrame[]): FlatFrame | null;
+/** All frames of a test in capture-time order (ties keep step order), each numbered by its position. Cached per report. */
 export declare function testFrames(test: HtmlReportTest): FlatFrame[];
-/** Return UI snapshots in one stable actor order, including empty slots. */
+/**
+ * Returns a frame's UI snapshots (html or png) in one stable actor order, including empty slots, so each client
+ * stays in the same column from frame to frame. The order is the report's `meta.actorIds`, then any other client in
+ * the order first seen. A client with no snapshot at this frame carries its latest earlier one (`stale: true`), or
+ * `null` blob if it has none yet. Snapshots with no `nodeId` follow, named `snapshot-N`.
+ */
 export declare function orderedUiBlobs(frame: FlatFrame | null, test: HtmlReportTest): OrderedUiBlob[];
+/** The frame a route selects: the 1-based `frame` param when in range, otherwise the first frame of a failed step, otherwise the last frame; null with no frames. */
 export declare function selectedFrame(frames: readonly FlatFrame[], route: Route): FlatFrame | null;
-/** Every file a report names: step snapshots, and files attached to the test as a whole. */
+/** Every distinct file a report names, relative to the test's folder: step snapshots, and files attached to the test as a whole (artifacts with their poster and captions). Used to know what to copy or prefetch. */
 export declare function capturedFiles(report: Pick<RunReport, 'steps' | 'artifacts'>): string[];
+/** Whether a snapshot is a rendered user interface (`html` or `png`), as opposed to data such as JSON or text. */
 export declare function isUi(b: ReportSnapshotBlob): boolean;
+/** The UI snapshots (html or png) of a frame; empty for no frame. */
 export declare function uiBlobs(frame: FlatFrame | null): ReportSnapshotBlob[];
+/** All snapshots of a frame of any media; empty for no frame. */
 export declare function stageBlobs(frame: FlatFrame | null): ReportSnapshotBlob[];
+/** Whether a frame has at least one UI snapshot. */
 export declare function frameHasUi(frame: FlatFrame | null): boolean;
-/** Frame files around `index` (the visible one, plus neighbors) to fetch ahead. */
+/** The distinct html, png, json and text files of the frames within `radius` of `index` (the visible one plus neighbors, clamped to the list), to fetch ahead. */
 export declare function frameFilesNear(frames: readonly FlatFrame[], index: number, radius: number): readonly string[];
+/** The clients (actors) to show for a frame: those with a UI snapshot, else those with any snapshot, else the report's declared `meta.actorIds`. */
 export declare function actorIds(frame: FlatFrame | null, test: HtmlReportTest): string[];
+/** The client a route selects: the `node` param when it is one of the frame's actors, else the frame's step actor, else the first actor; null with none. */
 export declare function selectedNode(frame: FlatFrame | null, route: Route, test: HtmlReportTest): string | null;
+/** The text of a blob the test holds as text, or null when it is missing or held as bytes. */
 export declare function blobText(test: HtmlReportTest, blob: ReportSnapshotBlob): string | null;
+/** A `data:` URL for a blob the test holds as base64 bytes, or null when it is missing or held as text. */
 export declare function blobDataUrl(test: HtmlReportTest, blob: ReportSnapshotBlob): string | null;
 /** Whether any frame of `step` (not its children) shows a press target. */
 export declare function stepHasPress(step: ReportStep): boolean;