@crvouga/atlas 0.3.0 → 0.5.0

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

@@ -1,23 +1,50 @@
 /**
- * Overlay test-runner outcomes (JUnit XML) onto a report bundle. A harness run
- * only sees failures raised inside its own steps; assertions in the test body
- * surface through the runner's report instead.
+ * @module JUnit XML parsing
+ *
+ * Reads the `<testcase>` elements of a JUnit XML document without an XML library, and overlays test-runner
+ * outcomes (JUnit XML) onto a report bundle. A harness run only sees failures raised inside its own steps;
+ * assertions in the test body surface through the runner's report instead. Parsing is tolerant by design
+ * (nested suites, self-closing elements, CDATA) and never drops a case silently, because a result that goes
+ * missing reads as a pass. `ingest.ts` turns the cases into checks.
  */
 import type { HtmlReportBundle } from './recording-bundle.js';
+/** One `<testcase>` as read, with the suite it is in. */
 export type JunitCase = {
+    /** The case's `file` attribute, else its suite's, else empty. */
     readonly file: string;
+    /** The `classname` attribute, which many runners use for the suite or the file. */
+    readonly classname: string;
+    /** The `name` of the `<testsuite>` the case is in. */
+    readonly suite: string;
+    /** Seconds, when the runner emits it. */
+    readonly time: number | null;
     readonly name: string;
     /** 1-based line of the test declaration, when the runner emits it. */
     readonly line: number | null;
+    /** `failed` when the case has a `<failure>` or an `<error>`, `skipped` when it has `<skipped>`, otherwise `passed`. */
     readonly status: 'passed' | 'failed' | 'skipped';
+    /** The failure's text (else its `message`, else `failed`), or null when the case did not fail. */
     readonly failure: string | null;
+    /** The case's `<system-out>`, when it has one. */
+    readonly stdout?: string;
+    /** The case's `<system-err>`, when it has one. */
+    readonly stderr?: string;
+    /** The case's `<properties>`, then its suite's: names a runner chose to record. */
+    readonly properties?: Readonly<Record<string, string>>;
 };
-/** Parse the `<testcase>` elements of a JUnit XML document. */
+/** Parses every `<testcase>` of a JUnit XML document, in document order, whatever the nesting of its suites. Returns `[]` for text with none; never throws. */
 export declare function parseJunit(xml: string): JunitCase[];
 /**
  * The test case whose declaration precedes `sourceLine` in the same file and
- * is the nearest one (bodies follow declarations).
+ * is the nearest one (bodies follow declarations). Files match when equal or when one path ends with the other
+ * (after normalising backslashes). With one case in the file, or no line, the first case in the file is used.
+ * Null when no case is in the file, or none declared at or before the line.
  */
 export declare function matchJunitCase(cases: readonly JunitCase[], sourceFile: string, sourceLine: number | undefined): JunitCase | null;
-/** Apply runner outcomes / titles to every test with a known source file. */
+/**
+ * Applies runner outcomes and titles to every test of a bundle that has a known source file and a matching case:
+ * the test takes the case's name as title, its failure as error (a harness error is kept), and fails if either the
+ * runner or the harness failed. The bundle fails if any test does. Tests without a match are returned unchanged;
+ * the input is not mutated.
+ */
 export declare function applyJunitOutcomes(bundle: HtmlReportBundle, cases: readonly JunitCase[]): HtmlReportBundle;

package/dist/reports/src/junit.js

@@ -1,7 +1,11 @@
 /**
- * Overlay test-runner outcomes (JUnit XML) onto a report bundle. A harness run
- * only sees failures raised inside its own steps; assertions in the test body
- * surface through the runner's report instead.
+ * @module JUnit XML parsing
+ *
+ * Reads the `<testcase>` elements of a JUnit XML document without an XML library, and overlays test-runner
+ * outcomes (JUnit XML) onto a report bundle. A harness run only sees failures raised inside its own steps;
+ * assertions in the test body surface through the runner's report instead. Parsing is tolerant by design
+ * (nested suites, self-closing elements, CDATA) and never drops a case silently, because a result that goes
+ * missing reads as a pass. `ingest.ts` turns the cases into checks.
  */
 const ENTITIES = {
     '&lt;': '<',
@@ -21,24 +25,49 @@ function attr(tag, name) {
     return m === null ? null : decodeXml(m[1] ?? '');
 }
 function failureText(body) {
-    const m = /<failure\b([^>]*)(?:\/>|>([\s\S]*?)<\/failure>)/.exec(body);
+    // `<failure>` is an assertion that did not hold, `<error>` an unexpected exception: both are a check that failed.
+    const m = /<(failure|error)\b([^>]*)(?:\/>|>([\s\S]*?)<\/\1>)/.exec(body);
     if (m === null)
         return null;
-    const message = attr(m[1] ?? '', 'message');
-    const inner = (m[2] ?? '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1');
+    const message = attr(m[2] ?? '', 'message');
+    const inner = (m[3] ?? '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1');
     const text = decodeXml(inner).trim();
     return text.length > 0 ? text : (message ?? 'failed');
 }
-function parseCase(tag, inner, suiteFile) {
+function streamText(body, name) {
+    const found = new RegExp(`<${name}\\b[^>]*>([\\s\\S]*?)</${name}>`).exec(body);
+    if (!found)
+        return undefined;
+    const text = decodeXml((found[1] ?? '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1')).trim();
+    return text.length ? text : undefined;
+}
+function propertiesOf(body) {
+    const out = {};
+    for (const match of body.matchAll(/<property\b([^>]*?)\/?>/g)) {
+        const name = attr(match[1] ?? '', 'name');
+        const value = attr(match[1] ?? '', 'value');
+        if (name)
+            out[name] = value ?? '';
+    }
+    return out;
+}
+function parseCase(tag, inner, suiteFile, suiteName, suiteProperties = {}) {
     const lineRaw = attr(tag, 'line');
     const line = lineRaw === null ? null : Number(lineRaw);
     const failure = failureText(inner);
+    const time = Number(attr(tag, 'time'));
     return {
         file: attr(tag, 'file') ?? suiteFile,
+        classname: attr(tag, 'classname') ?? '',
+        suite: suiteName,
+        time: attr(tag, 'time') !== null && Number.isFinite(time) ? time : null,
         name: attr(tag, 'name') ?? '',
         line: line !== null && Number.isFinite(line) ? line : null,
         status: caseStatus(failure, inner),
         failure,
+        ...(streamText(inner, 'system-out') ? { stdout: streamText(inner, 'system-out') } : {}),
+        ...(streamText(inner, 'system-err') ? { stderr: streamText(inner, 'system-err') } : {}),
+        ...(Object.keys({ ...suiteProperties, ...propertiesOf(inner) }).length ? { properties: { ...suiteProperties, ...propertiesOf(inner) } } : {}),
     };
 }
 function caseStatus(failure, inner) {
@@ -48,22 +77,52 @@ function caseStatus(failure, inner) {
         return 'skipped';
     return 'passed';
 }
-function parseSuite(tag, body, out) {
-    const suiteFile = attr(tag, 'file') ?? '';
-    const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
-    for (let c = caseRe.exec(body); c; c = caseRe.exec(body)) {
-        out.push(parseCase(c[1] ?? '', c[2] ?? '', suiteFile));
-    }
-}
-/** Parse the `<testcase>` elements of a JUnit XML document. */
-export function parseJunit(xml) {
+/**
+ * Every `<testcase>` of the document, whatever the nesting of its suites: a suite inside a suite, a case after
+ * an inner suite, an empty self-closing suite. Each case is read with the suite it is in, and that suite's own
+ * `<properties>`. A case is never skipped silently, because a result that goes missing reads as a pass.
+ */
+function allCases(xml) {
     const cases = [];
-    const suiteRe = /<testsuite\b([^>]*)>([\s\S]*?)<\/testsuite>/g;
-    for (let suite = suiteRe.exec(xml); suite; suite = suiteRe.exec(xml)) {
-        parseSuite(suite[1] ?? '', suite[2] ?? '', cases);
+    const stack = [];
+    const tags = /<(\/?)(testsuite|testcase|properties)\b([^>]*?)(\/?)>/g;
+    for (let tag = tags.exec(xml); tag; tag = tags.exec(xml)) {
+        const [, closing, name, attributes = '', selfClosing] = tag;
+        if (name === 'testsuite') {
+            if (closing) {
+                stack.pop();
+                continue;
+            }
+            const suite = { file: attr(attributes, 'file') ?? '', name: attr(attributes, 'name') ?? '', properties: {} };
+            if (!selfClosing)
+                stack.push(suite);
+        }
+        else if (name === 'testcase' && !closing) {
+            let inner = '';
+            if (!selfClosing) {
+                const end = xml.indexOf('</testcase>', tags.lastIndex);
+                if (end < 0)
+                    continue;
+                inner = xml.slice(tags.lastIndex, end);
+                tags.lastIndex = end + '</testcase>'.length;
+            }
+            const suite = stack.at(-1);
+            cases.push(parseCase(attributes, inner, suite?.file ?? '', suite?.name ?? '', Object.assign({}, ...stack.map(item => item.properties))));
+        }
+        else if (name === 'properties' && !closing && !selfClosing && stack.length) {
+            const end = xml.indexOf('</properties>', tags.lastIndex);
+            if (end < 0)
+                continue;
+            Object.assign(stack.at(-1).properties, propertiesOf(xml.slice(tags.lastIndex, end)));
+            tags.lastIndex = end + '</properties>'.length;
+        }
     }
     return cases;
 }
+/** Parses every `<testcase>` of a JUnit XML document, in document order, whatever the nesting of its suites. Returns `[]` for text with none; never throws. */
+export function parseJunit(xml) {
+    return allCases(xml);
+}
 function sameFile(a, b) {
     const na = a.replace(/\\/g, '/');
     const nb = b.replace(/\\/g, '/');
@@ -71,7 +130,9 @@ function sameFile(a, b) {
 }
 /**
  * The test case whose declaration precedes `sourceLine` in the same file and
- * is the nearest one (bodies follow declarations).
+ * is the nearest one (bodies follow declarations). Files match when equal or when one path ends with the other
+ * (after normalising backslashes). With one case in the file, or no line, the first case in the file is used.
+ * Null when no case is in the file, or none declared at or before the line.
  */
 export function matchJunitCase(cases, sourceFile, sourceLine) {
     const inFile = cases.filter((c) => sameFile(c.file, sourceFile));
@@ -105,7 +166,12 @@ function overlayTest(test, c) {
         },
     };
 }
-/** Apply runner outcomes / titles to every test with a known source file. */
+/**
+ * Applies runner outcomes and titles to every test of a bundle that has a known source file and a matching case:
+ * the test takes the case's name as title, its failure as error (a harness error is kept), and fails if either the
+ * runner or the harness failed. The bundle fails if any test does. Tests without a match are returned unchanged;
+ * the input is not mutated.
+ */
 export function applyJunitOutcomes(bundle, cases) {
     const tests = bundle.tests.map((test) => {
         const { sourceFile, sourceLine } = test.report.meta;

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

@@ -1,16 +1,36 @@
 import type { FlatFrame } from './frames.js';
 import type { Route } from './hash.js';
 import type { ReportData } from './types.js';
+/** What {@link onReportKeyDown} may ask the host to do, and what it reads from it. */
 export type KeyNavHandlers = {
+    /** Opens or closes the shortcut help. */
     toggleHelp: () => void;
+    /** Whether the help is open. */
     showHelp: () => boolean;
+    /** Whether the command palette is open; while it is, no other shortcut acts. */
     showPalette: () => boolean;
     togglePalette: () => void;
+    /** Stops frame playback. */
     stopPlay: () => void;
+    /** Goes to a route (writes the URL hash). */
     navigate: (route: Route) => void;
+    /** Selects a frame, optionally of a given client (`node`). */
     goFrame: (frame: FlatFrame | null, node?: string) => void;
     togglePlay: () => void;
+    /** Sets a URL param on the current route; the empty string removes it. */
     setParam: (key: string, value: string) => void;
+    /** The current route. */
     route: () => Route;
 };
+/**
+ * Handles one `keydown` for the viewer. Keys: Cmd/Ctrl+K palette; `?` help; Escape closes help or the palette,
+ * else stops playback and returns to the list. On a test page: Left/Right/Home/End scrub frames, Space plays,
+ * Up/Down jump between steps, `n`/`N` between failures, `[`/`]` to the previous/next test (keeping the list's
+ * params), `1`-`9` pick a client, and, when the frame has a UI snapshot, `m` single/multi view, `a` aside, `p`
+ * press targets, `f` cycles zoom (fit, 50, 75, 100).
+ *
+ * Cmd/Ctrl+K and Escape-closing-the-palette work anywhere. Every other key is ignored while the palette is open and
+ * while focus is in an input, textarea, select, button, link or editable element; the test-page keys also need the
+ * route to be a test that is in `data`.
+ */
 export declare function onReportKeyDown(e: KeyboardEvent, data: ReportData, h: KeyNavHandlers): void;

package/dist/reports/src/keyboard.js

@@ -85,6 +85,17 @@ function viewKeys(e, ctx) {
             ctx.h.goFrame(ctx.sel, ids[n - 1] ?? '');
     }
 }
+/**
+ * Handles one `keydown` for the viewer. Keys: Cmd/Ctrl+K palette; `?` help; Escape closes help or the palette,
+ * else stops playback and returns to the list. On a test page: Left/Right/Home/End scrub frames, Space plays,
+ * Up/Down jump between steps, `n`/`N` between failures, `[`/`]` to the previous/next test (keeping the list's
+ * params), `1`-`9` pick a client, and, when the frame has a UI snapshot, `m` single/multi view, `a` aside, `p`
+ * press targets, `f` cycles zoom (fit, 50, 75, 100).
+ *
+ * Cmd/Ctrl+K and Escape-closing-the-palette work anywhere. Every other key is ignored while the palette is open and
+ * while focus is in an input, textarea, select, button, link or editable element; the test-page keys also need the
+ * route to be a test that is in `data`.
+ */
 export function onReportKeyDown(e, data, h) {
     if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
         e.preventDefault();

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

@@ -1,6 +1,9 @@
 /**
- * Object-store key layout of the shared reports store. Historical recording addresses use
- * the full commit sha. Immutable report layers combine across those addresses:
+ * @module Commit-keyed object-store key layout
+ *
+ * Builds and validates the keys of the commit-addressed layout of the shared reports store. Historical recording
+ * addresses use the full commit sha. Immutable report layers (`layers/…`, see `docs/report-contract.md`) combine
+ * across those addresses:
  *
  *   index/<13-digit inverted start ms>-<sha>.json   one per published commit;
  *                                                   sorted keys = newest first
@@ -15,38 +18,53 @@
  * A source is one report bucket of one package (`libs-chess--part-2`).
  * Writers put a source's tests first and its `sources/` record last, so a
  * reader that sees the record can read every test it names.
+ *
+ * Every builder validates its inputs (a full 40-hex sha, path-safe segments) and throws on a bad one, so a key
+ * made here can never climb out of its prefix.
  */
 /**
  * Where the reports live in their bucket. Every reader and writer scopes its
  * store to it, so the keys below are relative to it.
  */
 export declare const REPORTS_ROOT_PREFIX = "spec-reports";
+/** The prefix of the per-commit catalog entries, `index/`. */
 export declare const COMMITS_INDEX_PREFIX = "index/";
+/** Whether the value is a full 40-digit lowercase hex commit sha (an abbreviated sha is not). */
 export declare function isCommitSha(value: string): boolean;
 /** One path segment the harness could have written (never `.` or `..`). */
 export declare function isKeySegment(value: string): boolean;
 /** A frame file relative to its test (`frames/f-0001.state.json`). */
 export declare function isFramePath(value: string): boolean;
-/** `libs/chess` + `part-2` → `libs-chess--part-2`. */
+/** The id of a source (one report bucket of one package): `libs/chess` + `part-2` → `libs-chess--part-2`. Throws `not a report source` when the result is not a safe key segment. */
 export declare function sourceId(packageDir: string, bucket: string): string;
+/** The catalog key of a commit, `index/<13-digit inverted start ms>-<sha>.json`: the time is inverted so a listing is newest first. Negative times count as 0. Throws for a sha that is not 40 hex digits. */
 export declare function commitIndexKey(sha: string, startedAtMs: number): string;
 /** The sha an index key names, or null for anything else. */
 export declare function shaOfIndexKey(key: string): string | null;
+/** The folder of everything recorded for a commit, `commits/<sha>/`. Throws for a sha that is not 40 hex digits. */
 export declare function commitPrefix(sha: string): string;
+/** The key of the commit's run record, `commits/<sha>/commit.json`. */
 export declare function commitKey(sha: string): string;
+/** The key of the stylesheet the commit's snapshots render with, `commits/<sha>/frame.css`. */
 export declare function frameCssKey(sha: string): string;
+/** The folder of a commit's source records, `commits/<sha>/sources/`. */
 export declare function sourcesPrefix(sha: string): string;
+/** The key of one source's record, `commits/<sha>/sources/<source>.json`; written last, after the source's tests. Throws `not a source` for an unsafe name. */
 export declare function sourceKey(sha: string, source: string): string;
 /** The source a `sources/` key names, or null for anything else. */
 export declare function sourceOfKey(sha: string, key: string): string | null;
+/** The folder of one recorded test, `commits/<sha>/tests/<source>/<testId>/`. Throws for an unsafe source or test id. */
 export declare function remoteTestPrefix(sha: string, source: string, testId: string): string;
+/** The key of a recorded test's report, `<test folder>/report.json`. */
 export declare function remoteTestReportKey(sha: string, source: string, testId: string): string;
+/** The key of a file a recorded test captured (a frame, a snapshot), inside its folder. A leading `/` is dropped; throws `not a frame file` for a path with an unsafe segment (`..`, empty or odd characters). */
 export declare function remoteTestFileKey(sha: string, source: string, testId: string, file: string): string;
 /**
  * The id a viewer shows for a test of a source (`libs-chess--part-2/monkey`):
  * unique across the commit, since two packages may both name a test `monkey`.
  */
 export declare function viewerTestId(source: string, testId: string): string;
+/** The inverse of {@link viewerTestId}: splits at the first `/`; null when either side is not a safe key segment. */
 export declare function splitViewerTestId(id: string): {
     readonly source: string;
     readonly testId: string;

package/dist/reports/src/keys.js

@@ -1,6 +1,9 @@
 /**
- * Object-store key layout of the shared reports store. Historical recording addresses use
- * the full commit sha. Immutable report layers combine across those addresses:
+ * @module Commit-keyed object-store key layout
+ *
+ * Builds and validates the keys of the commit-addressed layout of the shared reports store. Historical recording
+ * addresses use the full commit sha. Immutable report layers (`layers/…`, see `docs/report-contract.md`) combine
+ * across those addresses:
  *
  *   index/<13-digit inverted start ms>-<sha>.json   one per published commit;
  *                                                   sorted keys = newest first
@@ -15,6 +18,9 @@
  * A source is one report bucket of one package (`libs-chess--part-2`).
  * Writers put a source's tests first and its `sources/` record last, so a
  * reader that sees the record can read every test it names.
+ *
+ * Every builder validates its inputs (a full 40-hex sha, path-safe segments) and throws on a bad one, so a key
+ * made here can never climb out of its prefix.
  */
 /**
  * Where the reports live in their bucket. Every reader and writer scopes its
@@ -26,7 +32,9 @@ const SHA = /^[0-9a-f]{40}$/;
 const SEGMENT = /^[a-zA-Z0-9._-]+$/;
 /** Inverted start times sort newest first while there are 13-digit ms. */
 const INVERT_FROM = 9_999_999_999_999;
+/** The prefix of the per-commit catalog entries, `index/`. */
 export const COMMITS_INDEX_PREFIX = 'index/';
+/** Whether the value is a full 40-digit lowercase hex commit sha (an abbreviated sha is not). */
 export function isCommitSha(value) {
     return SHA.test(value);
 }
@@ -44,13 +52,14 @@ function assertSha(sha) {
         throw new Error(`report key needs a full 40-hex commit sha, got "${sha}"`);
     }
 }
-/** `libs/chess` + `part-2` → `libs-chess--part-2`. */
+/** The id of a source (one report bucket of one package): `libs/chess` + `part-2` → `libs-chess--part-2`. Throws `not a report source` when the result is not a safe key segment. */
 export function sourceId(packageDir, bucket) {
     const id = `${packageDir.replaceAll('/', '-')}--${bucket}`;
     if (!isKeySegment(id))
         throw new Error(`not a report source: "${id}"`);
     return id;
 }
+/** The catalog key of a commit, `index/<13-digit inverted start ms>-<sha>.json`: the time is inverted so a listing is newest first. Negative times count as 0. Throws for a sha that is not 40 hex digits. */
 export function commitIndexKey(sha, startedAtMs) {
     assertSha(sha);
     const inverted = String(INVERT_FROM - Math.max(0, Math.floor(startedAtMs)));
@@ -61,19 +70,24 @@ export function shaOfIndexKey(key) {
     const m = /^index\/\d{13}-([0-9a-f]{40})\.json$/.exec(key);
     return m === null ? null : (m[1] ?? null);
 }
+/** The folder of everything recorded for a commit, `commits/<sha>/`. Throws for a sha that is not 40 hex digits. */
 export function commitPrefix(sha) {
     assertSha(sha);
     return `commits/${sha}/`;
 }
+/** The key of the commit's run record, `commits/<sha>/commit.json`. */
 export function commitKey(sha) {
     return `${commitPrefix(sha)}commit.json`;
 }
+/** The key of the stylesheet the commit's snapshots render with, `commits/<sha>/frame.css`. */
 export function frameCssKey(sha) {
     return `${commitPrefix(sha)}frame.css`;
 }
+/** The folder of a commit's source records, `commits/<sha>/sources/`. */
 export function sourcesPrefix(sha) {
     return `${commitPrefix(sha)}sources/`;
 }
+/** The key of one source's record, `commits/<sha>/sources/<source>.json`; written last, after the source's tests. Throws `not a source` for an unsafe name. */
 export function sourceKey(sha, source) {
     if (!isKeySegment(source))
         throw new Error(`not a source: "${source}"`);
@@ -87,6 +101,7 @@ export function sourceOfKey(sha, key) {
     const source = key.slice(head.length, -'.json'.length);
     return isKeySegment(source) ? source : null;
 }
+/** The folder of one recorded test, `commits/<sha>/tests/<source>/<testId>/`. Throws for an unsafe source or test id. */
 export function remoteTestPrefix(sha, source, testId) {
     if (!isKeySegment(source))
         throw new Error(`not a source: "${source}"`);
@@ -94,9 +109,11 @@ export function remoteTestPrefix(sha, source, testId) {
         throw new Error(`not a test id: "${testId}"`);
     return `${commitPrefix(sha)}tests/${source}/${testId}/`;
 }
+/** The key of a recorded test's report, `<test folder>/report.json`. */
 export function remoteTestReportKey(sha, source, testId) {
     return `${remoteTestPrefix(sha, source, testId)}report.json`;
 }
+/** The key of a file a recorded test captured (a frame, a snapshot), inside its folder. A leading `/` is dropped; throws `not a frame file` for a path with an unsafe segment (`..`, empty or odd characters). */
 export function remoteTestFileKey(sha, source, testId, file) {
     const rel = file.replace(/^\/+/, '');
     if (!isFramePath(rel))
@@ -110,6 +127,7 @@ export function remoteTestFileKey(sha, source, testId, file) {
 export function viewerTestId(source, testId) {
     return `${source}/${testId}`;
 }
+/** The inverse of {@link viewerTestId}: splits at the first `/`; null when either side is not a safe key segment. */
 export function splitViewerTestId(id) {
     const slash = id.indexOf('/');
     if (slash < 0)

package/dist/reports/src/layer-axes.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module Environment axis of a layer
+ *
+ * Owns how a layer's `environment` (the client that was checked: `ios`, `desktop-web`, ...) is normalised to a stable
+ * slug, read from either the `environment` field or an `environment` parameter, and shown to people. The environment
+ * is part of the slot a check fills, so two spellings of one client must normalise to one id or their results would
+ * never replace each other; an unrecognised name is kept as its own slug rather than rejected.
+ *
+ * @see docs/report-contract.md
+ */
+import type { LayerParameters, LayerSummary } from './layer-types.js';
+/**
+ * The environments Atlas names and labels out of the box. Any other recorded name is kept, so a new
+ * client layers beside these instead of being dropped or renamed away.
+ */
+export declare const REPORT_ENVIRONMENTS: readonly ["desktop-web", "mobile-web", "ios", "android"];
+/**
+ * Turns any spelling of a client name into a stable lowercase slug, or `null` when none was given.
+ *
+ * Trims, lowercases, turns whitespace and underscores into `-`, drops every other character outside `a-z0-9-`,
+ * collapses repeated `-`, then maps known aliases (`iPhone` and `iPad` to `ios`, `mobile browser` to `mobile-web`,
+ * `desktop` to `desktop-web`). A name with no alias is returned as its slug. `null`, `undefined` and a value that
+ * slugs to nothing return `null`, which means "the layer did not say", so older layers still compose.
+ *
+ * @example
+ * normalizeEnvironment('Desktop Web'); // 'desktop-web'
+ * normalizeEnvironment('iPhone'); // 'ios'
+ * normalizeEnvironment('Smart TV'); // 'smart-tv'
+ * normalizeEnvironment('  '); // null
+ */
+export declare function normalizeEnvironment(value: string | null | undefined): string | null;
+/**
+ * Splits a layer into the two slot axes it fills: its normalised environment and its remaining parameters.
+ *
+ * The environment is the layer's `environment` field, or when that is `null` or absent the `environment` parameter
+ * (an empty-string field does not fall back to the parameter). The `environment` parameter is always removed from
+ * the returned `parameters`, so it is never both an environment and a free choice that splits the slot twice.
+ */
+export declare function layerPlace(summary: Pick<LayerSummary, 'environment' | 'parameters'>): {
+    environment: string | null;
+    parameters: LayerParameters;
+};
+/**
+ * The human label of an environment id: `Desktop web`, `Mobile web`, `iOS`, `Android` for the known ids,
+ * `Unspecified` for a missing one, and otherwise the id with its first word capitalised and `-` shown as a space
+ * (`smart-tv` reads `Smart tv`).
+ */
+export declare function environmentLabel(id: string | null | undefined): string;

package/dist/reports/src/layer-axes.js

@@ -0,0 +1,71 @@
+/**
+ * The environments Atlas names and labels out of the box. Any other recorded name is kept, so a new
+ * client layers beside these instead of being dropped or renamed away.
+ */
+export const REPORT_ENVIRONMENTS = ['desktop-web', 'mobile-web', 'ios', 'android'];
+const ALIASES = {
+    desktop: 'desktop-web',
+    'desktop-web': 'desktop-web',
+    'desktop-browser': 'desktop-web',
+    'web-desktop': 'desktop-web',
+    'mobile-web': 'mobile-web',
+    'mobile-browser': 'mobile-web',
+    'web-mobile': 'mobile-web',
+    ios: 'ios',
+    iphone: 'ios',
+    ipad: 'ios',
+    android: 'android',
+};
+/**
+ * Turns any spelling of a client name into a stable lowercase slug, or `null` when none was given.
+ *
+ * Trims, lowercases, turns whitespace and underscores into `-`, drops every other character outside `a-z0-9-`,
+ * collapses repeated `-`, then maps known aliases (`iPhone` and `iPad` to `ios`, `mobile browser` to `mobile-web`,
+ * `desktop` to `desktop-web`). A name with no alias is returned as its slug. `null`, `undefined` and a value that
+ * slugs to nothing return `null`, which means "the layer did not say", so older layers still compose.
+ *
+ * @example
+ * normalizeEnvironment('Desktop Web'); // 'desktop-web'
+ * normalizeEnvironment('iPhone'); // 'ios'
+ * normalizeEnvironment('Smart TV'); // 'smart-tv'
+ * normalizeEnvironment('  '); // null
+ */
+export function normalizeEnvironment(value) {
+    if (value == null)
+        return null;
+    const slug = value.trim().toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+    if (!slug)
+        return null;
+    return ALIASES[slug] ?? slug;
+}
+/**
+ * Splits a layer into the two slot axes it fills: its normalised environment and its remaining parameters.
+ *
+ * The environment is the layer's `environment` field, or when that is `null` or absent the `environment` parameter
+ * (an empty-string field does not fall back to the parameter). The `environment` parameter is always removed from
+ * the returned `parameters`, so it is never both an environment and a free choice that splits the slot twice.
+ */
+export function layerPlace(summary) {
+    const { environment: named, ...rest } = summary.parameters;
+    return { environment: normalizeEnvironment(summary.environment ?? named), parameters: rest };
+}
+const LABELS = {
+    'desktop-web': 'Desktop web',
+    'mobile-web': 'Mobile web',
+    ios: 'iOS',
+    android: 'Android',
+};
+/**
+ * The human label of an environment id: `Desktop web`, `Mobile web`, `iOS`, `Android` for the known ids,
+ * `Unspecified` for a missing one, and otherwise the id with its first word capitalised and `-` shown as a space
+ * (`smart-tv` reads `Smart tv`).
+ */
+export function environmentLabel(id) {
+    if (!id)
+        return 'Unspecified';
+    const known = LABELS[id];
+    if (known)
+        return known;
+    const [first, ...rest] = id.split('-');
+    return [first.charAt(0).toUpperCase() + first.slice(1), ...rest].join(' ');
+}

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

@@ -1,5 +1,32 @@
+/**
+ * @module Layer catalog of one backend
+ *
+ * Lists what one backend holds as catalog entries (immutable layers under `layers/index/`, and commit-keyed
+ * recordings written before layers existed) and turns one entry into the layer summaries it stands for. It only
+ * reads: opening Atlas never rewrites a store. Whether a backend can be read at all, and how entries from several
+ * backends combine, is decided by the callers (`compose.ts`, `layers-route.ts`).
+ *
+ * @see docs/report-contract.md
+ */
 import type { ObjectStore } from './object-store.js';
 import type { LayerSummary } from './layer-types.js';
-/** Read existing recordings in place; opening Atlas never rewrites the evidence store. */
+/**
+ * Lists one backend's catalog entries as opaque strings to pass to `catalogLayers`.
+ *
+ * An entry is `layer:<key>` for each key under `layers/index/` (listed newest first, in the store's own key order),
+ * followed by `commit:<sha>` for every 40-hex commit named by a key under `versions/` or `index/` (a store written
+ * before layers existed, sorted by sha). Only lists keys; reads no layer. A store that cannot be listed throws.
+ * Existing recordings are read in place and never rewritten.
+ */
 export declare function catalogEntries(store: ObjectStore): Promise<readonly string[]>;
+/**
+ * Reads the layer summaries one catalog entry from `catalogEntries` stands for.
+ *
+ * A `layer:` entry yields exactly one summary (the layer the catalog entry names, without its bundle) and throws
+ * when the entry is not JSON, names no layer, the layer is missing, or the layer cannot be parsed, so the caller can
+ * report it as a notice instead of counting it as a pass. A `commit:` entry yields the older commit-keyed
+ * recordings of that sha: one summary per stored part (`part-<sha>-<id>`) and one per stored source
+ * (`source-<sha>-<id>`); a part whose checks a source already carries, and that has no parameters, is dropped so the
+ * same evidence is not counted twice. Those ids are mutable addresses, not content digests.
+ */
 export declare function catalogLayers(store: ObjectStore, entry: string): Promise<readonly LayerSummary[]>;

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

@@ -7,12 +7,29 @@ import { readStoredSource } from './source-content.js';
 import { sourceParts } from './source-part.js';
 import { LAYER_INDEX, readLayer, layerSummary } from './layer-store.js';
 import { eachLimited } from './completion-order.js';
-/** Read existing recordings in place; opening Atlas never rewrites the evidence store. */
+/**
+ * Lists one backend's catalog entries as opaque strings to pass to `catalogLayers`.
+ *
+ * An entry is `layer:<key>` for each key under `layers/index/` (listed newest first, in the store's own key order),
+ * followed by `commit:<sha>` for every 40-hex commit named by a key under `versions/` or `index/` (a store written
+ * before layers existed, sorted by sha). Only lists keys; reads no layer. A store that cannot be listed throws.
+ * Existing recordings are read in place and never rewritten.
+ */
 export async function catalogEntries(store) {
     const [layers, versions, commits] = await Promise.all([store.listKeys(LAYER_INDEX), store.listKeys('versions/'), store.listKeys('index/')]);
     const shas = new Set([...versions, ...commits].flatMap(key => /([0-9a-f]{40})\.json$/.exec(key)?.[1] ?? []));
     return [...layers.map(key => `layer:${key}`), ...[...shas].sort().map(sha => `commit:${sha}`)];
 }
+/**
+ * Reads the layer summaries one catalog entry from `catalogEntries` stands for.
+ *
+ * A `layer:` entry yields exactly one summary (the layer the catalog entry names, without its bundle) and throws
+ * when the entry is not JSON, names no layer, the layer is missing, or the layer cannot be parsed, so the caller can
+ * report it as a notice instead of counting it as a pass. A `commit:` entry yields the older commit-keyed
+ * recordings of that sha: one summary per stored part (`part-<sha>-<id>`) and one per stored source
+ * (`source-<sha>-<id>`); a part whose checks a source already carries, and that has no parameters, is dropped so the
+ * same evidence is not counted twice. Those ids are mutable addresses, not content digests.
+ */
 export async function catalogLayers(store, entry) {
     if (entry.startsWith('layer:')) {
         const raw = await readUtf8(store, entry.slice(6));
@@ -31,7 +48,7 @@ export async function catalogLayers(store, entry) {
         const stored = await readStoredSource(store, sha, sourceId);
         if (!stored)
             return;
-        layers.push({ id: `source-${sha}-${sourceId}`, producer: sourceId, recordedAtMs: Math.max(commit?.startedAtMs ?? 0, stored.record.updatedAtMs), sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null, parameters: {}, specs, parts: sourceParts(sha, stored.record), source: stored.record, recording: { type: 'commit', sha, source: sourceId } });
+        layers.push({ ...(stored.record.environment ? { environment: stored.record.environment } : {}), id: `source-${sha}-${sourceId}`, producer: sourceId, recordedAtMs: Math.max(commit?.startedAtMs ?? 0, stored.record.updatedAtMs), sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null, parameters: stored.record.parameters ?? {}, specs, parts: sourceParts(sha, stored.record), source: stored.record, recording: { type: 'commit', sha, source: sourceId } });
     });
     const signature = (part) => JSON.stringify([part.id, part.kind, part.checks]);
     const sourceEvidence = new Set(layers.filter(layer => layer.source).flatMap(layer => layer.parts.map(signature)));