@crvouga/atlas 0.4.0 → 0.6.0

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;

package/dist/reports/src/hash.js

@@ -1,3 +1,11 @@
+/**
+ * @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.
+ */
+/** Parses a `location.hash` (with or without the leading `#` and `/`) into a {@link Route}; an unrecognized path is the list. */
 export function parseHash(hash) {
     const raw = hash.replace(/^#\/?/, '');
     const q = raw.split('?');
@@ -18,6 +26,7 @@ export function parseHash(hash) {
     }
     return { view: 'list', params };
 }
+/** Builds the hash for a route (`#/` or `#/test/<encoded id>`) with its non-empty params encoded; the inverse of {@link parseHash}. */
 export function buildHash(route) {
     const qs = Object.keys(route.params)
         .filter((k) => {
@@ -29,15 +38,19 @@ export function buildHash(route) {
     const path = route.view === 'test' ? `/test/${encodeURIComponent(route.testId)}` : '/';
     return `#${path}${qs ? `?${qs}` : ''}`;
 }
+/** `single` when the `view` param says so, otherwise `multi`. */
 export function viewMode(route) {
     return route.params['view'] === 'single' ? 'single' : 'multi';
 }
+/** The `zoom` param, or `fit` when it is absent. */
 export function zoomMode(route) {
     return route.params['zoom'] || 'fit';
 }
+/** Whether the side panel is shown: true unless `aside=0`. */
 export function showAside(route) {
     return route.params['aside'] !== '0';
 }
+/** Whether press targets are drawn on frames: true unless `press=0`. */
 export function showPress(route) {
     return route.params['press'] !== '0';
 }

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

@@ -0,0 +1,29 @@
+import type { BackendInput } from './compose.js';
+/** Options of {@link reportsHost}. */
+export type ReportsHostOptions = {
+    /** The specs directory, relative to the project. Its files are the outline every layer fills. */
+    readonly specs: string;
+    /**
+     * Where layers are: a directory, an `s3://` URL, or any backend. Several stores are one report: layers
+     * from all of them are laid over the same specs. Default: `ATLAS_STORE`.
+     */
+    readonly stores?: readonly (string | BackendInput)[];
+    /** Groups the specs in the viewer. Default: the repository folder's name, or `product`. */
+    readonly domain?: string;
+};
+/**
+ * The reports half of the viewer, for a project's own stores. Export it from the module that
+ * `ATLAS_REPORTS_MODULE` names:
+ *
+ * ```ts
+ * import { reportsHost } from '@crvouga/atlas/reports/host';
+ * export const reportsDevFetch = reportsHost({ specs: './specs', stores: ['./atlas-reports'] });
+ * ```
+ *
+ * The returned function takes the incoming `Request` and the repository root (relative store paths and `specs`
+ * resolve against it); a path starting `/api/reports` has that prefix removed before routing. The app is built
+ * on first use and rebuilt if the root changes. A store given as a string is opened with `openStore` and gets an
+ * id derived from its location; a failure while answering (for example a wrong `specs` path) is a 500 whose JSON
+ * body names the `specs` directory and the store ids.
+ */
+export declare function reportsHost(options: ReportsHostOptions): (request: Request, repoRoot: string) => Promise<Response>;

package/dist/reports/src/host.js

@@ -0,0 +1,64 @@
+/**
+ * @module Reports host for a project's own stores
+ *
+ * Mounts the reports API (outline of a specs directory, layers from one or more stores) as a plain
+ * `(request, repoRoot) => Response` function, for a dev server or a project's own server to call at
+ * `/api/reports`. It owns opening the stores and lazily building the app once per repository root; the report
+ * logic itself is in `reports-route.ts` and `compose.ts`. Node/Bun only. It forwards only the method, URL and
+ * headers of a request (not the body), so it serves reads.
+ *
+ * @see docs/dogfooding.md
+ */
+import path from 'node:path';
+import { openStore, storeId, storeSpecs } from './store-url.js';
+import { loadDirectoryOutline } from './directory-outline.js';
+import { createReportsApp } from './reports-route.js';
+const PREFIX = '/api/reports';
+/**
+ * The reports half of the viewer, for a project's own stores. Export it from the module that
+ * `ATLAS_REPORTS_MODULE` names:
+ *
+ * ```ts
+ * import { reportsHost } from '@crvouga/atlas/reports/host';
+ * export const reportsDevFetch = reportsHost({ specs: './specs', stores: ['./atlas-reports'] });
+ * ```
+ *
+ * The returned function takes the incoming `Request` and the repository root (relative store paths and `specs`
+ * resolve against it); a path starting `/api/reports` has that prefix removed before routing. The app is built
+ * on first use and rebuilt if the root changes. A store given as a string is opened with `openStore` and gets an
+ * id derived from its location; a failure while answering (for example a wrong `specs` path) is a 500 whose JSON
+ * body names the `specs` directory and the store ids.
+ */
+export function reportsHost(options) {
+    let app;
+    let root = '';
+    return async (request, repoRoot) => {
+        if (!app || root !== repoRoot) {
+            root = repoRoot;
+            // Ids given by the caller are kept; the ones derived from the store step around them.
+            const given = options.stores ?? storeSpecs([], process.env);
+            const used = new Set(given.flatMap((store) => (typeof store === 'string' ? [] : [store.id])));
+            const backends = given.map((store) => {
+                if (typeof store !== 'string')
+                    return store;
+                const opened = openStore(store, { base: repoRoot, env: process.env });
+                const id = storeId(opened.location, used);
+                used.add(id);
+                return { id, label: opened.location.kind === 'directory' ? path.basename(opened.location.directory) : opened.label, store: opened.store };
+            });
+            const specs = path.resolve(repoRoot, options.specs);
+            app = createReportsApp({
+                store: null,
+                backends: backends.map(backend => ({ ...backend, label: backend.label ?? backend.id })),
+                clock: { now: Date.now },
+                timers: { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: handle => clearTimeout(handle), setInterval: (fn, ms) => setInterval(fn, ms), clearInterval: handle => clearInterval(handle) },
+                outline: () => loadDirectoryOutline(specs, { repoRoot, domain: options.domain ?? (path.basename(repoRoot) || 'product') })
+            });
+            // A wrong path says which one, instead of a bare "Internal Server Error".
+            app.onError((error, c) => c.json({ error: error instanceof Error ? error.message : String(error), specs, stores: backends.map(backend => backend.id) }, 500));
+        }
+        const url = new URL(request.url);
+        const pathname = url.pathname === PREFIX || url.pathname.startsWith(`${PREFIX}/`) ? url.pathname.slice(PREFIX.length) || '/' : url.pathname;
+        return app.request(new Request(`http://reports${pathname}${url.search}`, { method: request.method, headers: request.headers }));
+    };
+}

package/dist/reports/src/html-frame.d.ts

@@ -1,13 +1,12 @@
 import type { FlatFrame } from './frames.js';
-/**
- * A self-contained HTML document for a frame that has no UI snapshot: a
- * Quint step's model state, or any spec step that only recorded text.
- * Painted in the same phone surface as a real snapshot.
- */
 type Section = {
     readonly heading: string;
     readonly body: string;
 };
-/** HTML document of one frame's model or recorded state. */
+/**
+ * The HTML document of one frame's model or recorded state: the step's kind and timings, its title, its error,
+ * its `detail` (shown as a name/value table when every line reads `name = value`, otherwise as preformatted text)
+ * and then one block per extra `sections` entry. Everything from the recording is escaped.
+ */
 export declare function stateFrameHtml(frame: FlatFrame, sections: readonly Section[]): string;
 export {};

package/dist/reports/src/html-frame.js

@@ -1,3 +1,10 @@
+/**
+ * @module HTML cards for frames without a UI snapshot
+ *
+ * Builds a self-contained HTML document for a frame that has no UI snapshot: a Quint step's model state, or any
+ * spec step that only recorded text. It is painted in the same phone surface as a real snapshot. All text taken
+ * from the recording is HTML-escaped and the document carries only its own inline style, no script.
+ */
 import { fmtMs } from './format.js';
 const CARD_CSS = [
     'html,body{margin:0;background:#f4f1ea;color:#1c1915;',
@@ -53,7 +60,11 @@ function sectionBlocks(sections) {
         .map((section) => `<h2>${escapeHtml(section.heading)}</h2><pre>${escapeHtml(section.body)}</pre>`)
         .join('');
 }
-/** HTML document of one frame's model or recorded state. */
+/**
+ * The HTML document of one frame's model or recorded state: the step's kind and timings, its title, its error,
+ * its `detail` (shown as a name/value table when every line reads `name = value`, otherwise as preformatted text)
+ * and then one block per extra `sections` entry. Everything from the recording is escaped.
+ */
 export function stateFrameHtml(frame, sections) {
     const step = frame.step;
     const error = step.error === undefined