@crvouga/atlas 0.4.0 → 0.5.0

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;

package/dist/reports/src/frames.js

@@ -20,6 +20,7 @@ function carriedUiBlobs(test) {
     carryCache.set(test.report.steps, out);
     return out;
 }
+/** 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 function flattenFrames(steps, out = [], depth = 0) {
     for (const step of steps) {
         for (const frame of step.frames) {
@@ -29,6 +30,7 @@ export function flattenFrames(steps, out = [], depth = 0) {
     }
     return out;
 }
+/** Flattens a step tree depth first into rows that know their depth and parent. Appends to `out`. */
 export function flattenSteps(steps, out = [], depth = 0, parent = null) {
     for (const step of steps) {
         const row = { step, depth, parent, index: out.length };
@@ -37,6 +39,7 @@ export function flattenSteps(steps, out = [], depth = 0, parent = null) {
     }
     return out;
 }
+/** The first frame of `step`, or failing that of its first descendant that has one; null when none of them has a frame. */
 export function firstFrameFor(step, frames) {
     for (const f of frames) {
         if (f.step === step)
@@ -49,6 +52,7 @@ export function firstFrameFor(step, frames) {
     }
     return 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 function lastFrameBefore(step, frames) {
     let best = null;
     for (const f of frames) {
@@ -57,6 +61,7 @@ export function lastFrameBefore(step, frames) {
     }
     return best;
 }
+/** All frames of a test in capture-time order (ties keep step order), each numbered by its position. Cached per report. */
 export function testFrames(test) {
     const cached = frameCache.get(test.report.steps);
     if (cached)
@@ -98,7 +103,12 @@ function allUiActorIds(test) {
     actorOrderCache.set(test.report.steps, ordered);
     return ordered;
 }
-/** 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 function orderedUiBlobs(frame, test) {
     const blobs = uiBlobs(frame);
     const byNode = new Map();
@@ -126,6 +136,7 @@ export function orderedUiBlobs(frame, test) {
     }
     return ordered;
 }
+/** 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 function selectedFrame(frames, route) {
     const n = Number.parseInt(route.params['frame'] || '', 10);
     if (Number.isFinite(n) && n >= 1 && n <= frames.length) {
@@ -137,7 +148,7 @@ export function selectedFrame(frames, route) {
     }
     return frames[frames.length - 1] ?? 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 function capturedFiles(report) {
     const files = new Set();
     const visit = (steps) => {
@@ -158,15 +169,19 @@ export function capturedFiles(report) {
     }
     return [...files];
 }
+/** Whether a snapshot is a rendered user interface (`html` or `png`), as opposed to data such as JSON or text. */
 export function isUi(b) {
     return b.media === 'html' || b.media === 'png';
 }
+/** The UI snapshots (html or png) of a frame; empty for no frame. */
 export function uiBlobs(frame) {
     return frame ? frame.frame.snapshots.filter(isUi) : [];
 }
+/** All snapshots of a frame of any media; empty for no frame. */
 export function stageBlobs(frame) {
     return frame ? [...frame.frame.snapshots] : [];
 }
+/** Whether a frame has at least one UI snapshot. */
 export function frameHasUi(frame) {
     return uiBlobs(frame).length > 0;
 }
@@ -176,7 +191,7 @@ const PREFETCH_MEDIA = new Set([
     'json',
     'text',
 ]);
-/** 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 function frameFilesNear(frames, index, radius) {
     const files = [];
     const seen = new Set();
@@ -192,6 +207,7 @@ export function frameFilesNear(frames, index, radius) {
     }
     return files;
 }
+/** 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 function actorIds(frame, test) {
     const ids = [];
     const seen = {};
@@ -213,6 +229,7 @@ export function actorIds(frame, test) {
     }
     return ids;
 }
+/** 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 function selectedNode(frame, route, test) {
     const ids = actorIds(frame, test);
     const param = route.params['node'];
@@ -223,10 +240,12 @@ export function selectedNode(frame, route, test) {
     }
     return ids[0] ?? null;
 }
+/** The text of a blob the test holds as text, or null when it is missing or held as bytes. */
 export function blobText(test, blob) {
     const b = test.blobs[blob.file];
     return b && typeof b.text === 'string' ? b.text : null;
 }
+/** A `data:` URL for a blob the test holds as base64 bytes, or null when it is missing or held as text. */
 export function blobDataUrl(test, blob) {
     const b = test.blobs[blob.file];
     if (!b?.base64)

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

@@ -1,17 +1,35 @@
+/**
+ * @module URL hash routes of the reports viewer
+ *
+ * The explorer keeps its state in the URL hash (`#/test/<id>?view=single&zoom=fit`) so a link reproduces a view.
+ * This module parses a hash into a {@link Route} and builds it back; it is pure and never throws on a missing
+ * value, but `parseHash` throws `URIError` on a malformed percent-escape. Unknown params are carried untouched.
+ */
+/** The query part of a hash: decoded keys and values. Empty values are dropped when a hash is built. */
 export type RouteParams = Readonly<Record<string, string>>;
+/** The list of reports or tests (`#/`). */
 export type ListRoute = {
     readonly view: 'list';
     readonly params: RouteParams;
 };
+/** One recorded test (`#/test/<id>`). */
 export type TestRoute = {
     readonly view: 'test';
+    /** The test's id, decoded; it may contain slashes (`libs/chess/monkey`). */
     readonly testId: string;
     readonly params: RouteParams;
 };
+/** Where the viewer is: the list, or one test. Anything that is not `#/test/<id>` is the list. */
 export type Route = ListRoute | TestRoute;
+/** Parses a `location.hash` (with or without the leading `#` and `/`) into a {@link Route}; an unrecognized path is the list. */
 export declare function parseHash(hash: string): Route;
+/** Builds the hash for a route (`#/` or `#/test/<encoded id>`) with its non-empty params encoded; the inverse of {@link parseHash}. */
 export declare function buildHash(route: Route): string;
+/** `single` when the `view` param says so, otherwise `multi`. */
 export declare function viewMode(route: Route): 'single' | 'multi';
+/** The `zoom` param, or `fit` when it is absent. */
 export declare function zoomMode(route: Route): string;
+/** Whether the side panel is shown: true unless `aside=0`. */
 export declare function showAside(route: Route): boolean;
+/** Whether press targets are drawn on frames: true unless `press=0`. */
 export declare function showPress(route: Route): boolean;