@crvouga/atlas 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 0.4.0 (2026-10-14)
+
+### Features
+
+- compose evidence by environment (#6) ([030f86b](https://github.com/crvouga/atlas/commit/030f86b1680851e3744cc977dc1c2a44e91f9926))
+
 ## 0.3.0 (2026-10-13)
 
 ### Features

package/README.md

@@ -114,12 +114,25 @@ visualizer updates when a run finishes.
 
 ```sh
 bun run atlas:run   # example:clients, then example:run: every chart of the example, in showcase mode
-bun run atlas:viz   # the example's specs, chart runs, Gherkin features, and Quint model
+bun run atlas:viz   # the example's specs, chart runs, and layered reports
 ```
 
 Each config writes its own run and the visualizer shows one run at a time: the latest is the
 single-browser run, and the run across clients is the one before it in the run picker.
 
+`bun run viz:dev` opens the full coffee example with a layered report, without waiting
+for a run. Gherkin, Quint, DMN, Alloy and OpenSLO documents sit beside the charts. The same scenarios
+are filled by separate layers across desktop web, mobile web, iOS and Android, and across versions,
+branches and backends (this machine, shared reports, and a device lab). A layer that repeated one
+scenario leaves the others as the last layer that ran them. One feature is left with no results.
+**Sources** in the header switches any of those off. The chart runs stay on the statechart map.
+
+`bun run atlas:viz` opens the todo example the same way. The Gherkin, Quint, DMN, Alloy and OpenSLO
+tabs already show five layers, so each environment is visible before a run. `example:run` adds one
+desktop web layer for the scenarios and traces it actually ran. That layer replaces only those
+desktop web results. The other environments stay. `ATLAS_REPORTS_MODULE` replaces this example API
+with a host's reports.
+
 A showcase run ends with:
 
 ```
@@ -128,7 +141,7 @@ Transitions 14/14 passed, 0 failed, 0 not reached
 Manifest: examples/todo/atlas-runs/<run-id>/manifest.json
 ```
 
-`example:run` then runs the Gherkin features in a browser and the Quint model. `atlas:viz` shows those results on the scenario and trace rows.
+`example:run` then runs the Gherkin features in a browser and the Quint model, and publishes that desktop web layer beside the ones already in the report.
 
 `bun test examples` runs [`model.test.ts`](examples/todo/model.test.ts): the same charts and journeys
 against `TodoModel`, a plain class, through `functionDriver` and `describeAtlas`. Only the driver

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

@@ -1,5 +1,6 @@
 import type { Clock } from './clock.js';
 import type { ActiveRun, LayerEvidence, LayerHeader } from './evidence-types.js';
+import type { LayerParameters } from './layer-types.js';
 import type { ObjectStore } from './object-store.js';
 /** What a running spec suite announces under `active/` in the local store. */
 export type LiveRunRecord = {
@@ -7,7 +8,12 @@ export type LiveRunRecord = {
     readonly bucket: string;
     readonly startedAtMs: number;
     readonly plannedChecks?: number;
+    /** The client this suite is checking. A different client does not replace it. */
+    readonly environment?: string;
+    readonly parameters?: LayerParameters;
 };
+/** A run announcement with the fields the live layer can trust. Null when it cannot be a run. */
+export declare function liveRunRecord(value: unknown): LiveRunRecord | null;
 /** How the host reaches the results a spec run has written so far. */
 export type LiveSource = {
     /** The bucket the run writes each finished test into, or null when it cannot be read. */

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

@@ -1,11 +1,40 @@
 import { eachLimited } from './completion-order.js';
+import { environmentOf } from './evidence-view.js';
 import { sourceId } from './keys.js';
+import { normalizeEnvironment } from './layer-axes.js';
 import { layerEvidence } from './layer-merge.js';
 import { readUtf8 } from './object-io.js';
 import { SPEC_RUN_ID } from './publish.js';
 import { testPrefix } from './recording-keys.js';
 import { sourcePart } from './source-part.js';
 import { suiteStatus } from './status.js';
+function readParameters(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const parameters = {};
+    for (const [key, item] of Object.entries(value))
+        if (typeof item === 'string' && item)
+            parameters[key] = item;
+    return parameters;
+}
+/** A run announcement with the fields the live layer can trust. Null when it cannot be a run. */
+export function liveRunRecord(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const run = value;
+    if (!run.packageDir || !run.bucket || typeof run.startedAtMs !== 'number')
+        return null;
+    const parameters = readParameters(run.parameters);
+    const environment = typeof run.environment === 'string' ? normalizeEnvironment(run.environment) : null;
+    return {
+        packageDir: run.packageDir,
+        bucket: run.bucket,
+        startedAtMs: run.startedAtMs,
+        ...(typeof run.plannedChecks === 'number' ? { plannedChecks: run.plannedChecks } : {}),
+        ...(environment ? { environment } : {}),
+        ...(Object.keys(parameters).length > 0 ? { parameters } : {}),
+    };
+}
 /** A finished run stays visible this long while its layer is being collected. */
 const LINGER_MS = 30_000;
 const REPORT = '/report.json';
@@ -46,8 +75,9 @@ export function createLiveEvidence(args) {
             }
         });
         const tests = [...state.metas.values()].sort((a, b) => (a.testId < b.testId ? -1 : a.testId > b.testId ? 1 : 0));
-        const record = { source, packageDir: state.run.packageDir, bucket: state.run.bucket, status: suiteStatus(tests), updatedAtMs: args.clock.now(), tests };
-        const summary = { id: liveLayerId(source), producer: source, recordedAtMs: record.updatedAtMs, sha: origin.sha, branch: origin.branch, runUrl: null, parameters: {}, specs: [], parts: [sourcePart(origin.sha ?? '', record)], source: record, recording: null };
+        const environment = normalizeEnvironment(state.run.environment ?? state.run.parameters?.environment);
+        const record = { source, packageDir: state.run.packageDir, bucket: state.run.bucket, status: suiteStatus(tests), updatedAtMs: args.clock.now(), ...(environment ? { environment } : {}), ...(state.run.parameters ? { parameters: state.run.parameters } : {}), tests };
+        const summary = { id: liveLayerId(source), producer: source, recordedAtMs: record.updatedAtMs, sha: origin.sha, branch: origin.branch, runUrl: null, ...(environment ? { environment } : {}), parameters: state.run.parameters ?? {}, specs: [], parts: [sourcePart(origin.sha ?? '', record)], source: record, recording: null };
         const evidence = layerEvidence(summary, args.backend);
         const layer = { ...evidence.layer, live: true, recording: { type: 'live', source }, execution: `live:${state.run.startedAtMs}:${tests.length}` };
         state.evidence = { ...evidence, layer };
@@ -98,7 +128,9 @@ export function createLiveEvidence(args) {
                         /* keep what was read while it ran */
                     }
                 }
-                const archived = collected.some(layer => layer.producer === source && !layer.live && layer.recordedAtMs >= state.run.startedAtMs);
+                const declared = normalizeEnvironment(state.run.environment ?? state.run.parameters?.environment) ?? 'unspecified';
+                // A collected layer of another client is a different result, so this suite stays up.
+                const archived = collected.some(layer => layer.producer === source && !layer.live && layer.recordedAtMs >= state.run.startedAtMs && environmentOf(layer) === declared);
                 if (archived || now - state.goneAt > LINGER_MS)
                     tracked.delete(source);
             }

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

@@ -30,6 +30,8 @@ export type LayerHeader = {
     readonly recordedAtMs: number;
     readonly sha: string | null;
     readonly branch: string | null;
+    /** The client this layer checked. Null when the layer did not say. */
+    readonly environment: string | null;
     readonly runUrl: string | null;
     readonly parameters: LayerParameters;
     readonly freshness?: 'unknown' | 'modified';

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

@@ -42,15 +42,26 @@ export type EvidenceView = {
     readonly total: SpecSummary;
 };
 export declare function evidenceView(combined: CombinedEvidence): EvidenceView;
-/** Sources left out of the combined report. Everything else, including layers that arrive later, contributes. */
+/**
+ * Sources left out of the combined report. An empty list means every layer
+ * on that axis contributes, including layers that arrive later.
+ */
 export type SourceSelection = {
     readonly backends: readonly string[];
     readonly branches: readonly string[];
+    readonly versions: readonly string[];
+    readonly environments: readonly string[];
     readonly layers: readonly string[];
 };
 export declare const ALL_SOURCES: SourceSelection;
+/** A saved selection from before versions and environments were axes still means "exclude nothing new". */
+export declare function sourceSelection(excluded: Partial<SourceSelection> | null | undefined): SourceSelection;
 export declare function branchOf(layer: LayerHeader): string;
-export declare function contributes(layer: LayerHeader, excluded: SourceSelection): boolean;
+/** The commit a layer checked, or `unknown` when the layer did not record one. */
+export declare function versionOf(layer: Pick<LayerHeader, 'sha'>): string;
+/** The client a layer checked, or `unspecified` when it did not say. */
+export declare function environmentOf(layer: Pick<LayerHeader, 'environment'>): string;
+export declare function contributes(layer: LayerHeader, excluded: Partial<SourceSelection>): boolean;
 export type SourceFacet = {
     readonly id: string;
     readonly layers: number;
@@ -59,6 +70,8 @@ export type SourceFacet = {
 export declare function sourceFacets(layers: readonly LayerHeader[]): {
     backends: SourceFacet[];
     branches: SourceFacet[];
+    versions: SourceFacet[];
+    environments: SourceFacet[];
 };
 export type HistoryEntry = {
     readonly layer: LayerHeader;

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

@@ -79,12 +79,35 @@ export function evidenceView(combined) {
     }
     return { specs, unassigned: checkSlots(combined.unassigned), total: addSummaries([...specs.values()].map(entry => entry.summary)) };
 }
-export const ALL_SOURCES = { backends: [], branches: [], layers: [] };
+export const ALL_SOURCES = { backends: [], branches: [], versions: [], environments: [], layers: [] };
+/** A saved selection from before versions and environments were axes still means "exclude nothing new". */
+export function sourceSelection(excluded) {
+    return {
+        backends: excluded?.backends ?? [],
+        branches: excluded?.branches ?? [],
+        versions: excluded?.versions ?? [],
+        environments: excluded?.environments ?? [],
+        layers: excluded?.layers ?? [],
+    };
+}
 export function branchOf(layer) {
     return layer.branch ?? 'Unknown branch';
 }
+/** The commit a layer checked, or `unknown` when the layer did not record one. */
+export function versionOf(layer) {
+    return layer.sha ?? 'unknown';
+}
+/** The client a layer checked, or `unspecified` when it did not say. */
+export function environmentOf(layer) {
+    return layer.environment || 'unspecified';
+}
 export function contributes(layer, excluded) {
-    return !excluded.backends.includes(layer.backend) && !excluded.branches.includes(branchOf(layer)) && !excluded.layers.includes(layer.id);
+    const selection = sourceSelection(excluded);
+    return !selection.backends.includes(layer.backend)
+        && !selection.branches.includes(branchOf(layer))
+        && !selection.versions.includes(versionOf(layer))
+        && !selection.environments.includes(environmentOf(layer))
+        && !selection.layers.includes(layer.id);
 }
 function facets(layers, id) {
     const found = new Map();
@@ -97,7 +120,12 @@ function facets(layers, id) {
     return [...found].map(([key, facet]) => ({ id: key, ...facet })).sort((a, b) => b.latestAtMs - a.latestAtMs || (a.id < b.id ? -1 : 1));
 }
 export function sourceFacets(layers) {
-    return { backends: facets(layers, layer => layer.backend), branches: facets(layers, branchOf) };
+    return {
+        backends: facets(layers, layer => layer.backend),
+        branches: facets(layers, branchOf),
+        versions: facets(layers, versionOf),
+        environments: facets(layers, environmentOf),
+    };
 }
 /** Every layer's own record of one check, newest first. A superseded result stays readable here. */
 export function checkHistory(layers, path, id) {

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

@@ -0,0 +1,18 @@
+import type { LayerParameters, LayerSummary } from './layer-types.js';
+/**
+ * Clients a product is checked on. 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"];
+/** A stable environment id. Blank means the layer did not say, so older layers still compose. */
+export declare function normalizeEnvironment(value: string | null | undefined): string | null;
+/**
+ * Environment is its own axis. A layer may name it on the field or as a
+ * parameter; the parameter is then not also a free choice.
+ */
+export declare function layerPlace(summary: Pick<LayerSummary, 'environment' | 'parameters'>): {
+    environment: string | null;
+    parameters: LayerParameters;
+};
+/** How an environment id reads in the report. */
+export declare function environmentLabel(id: string | null | undefined): string;

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

@@ -0,0 +1,51 @@
+/**
+ * Clients a product is checked on. 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',
+};
+/** A stable environment id. Blank means the layer did not say, so older layers still compose. */
+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;
+}
+/**
+ * Environment is its own axis. A layer may name it on the field or as a
+ * parameter; the parameter is then not also a free choice.
+ */
+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',
+};
+/** How an environment id reads in the report. */
+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.js

@@ -31,7 +31,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)));

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

@@ -29,7 +29,7 @@ export type CombinedEvidence = {
     }[];
     readonly unassigned: EvidenceResult[];
 };
-/** One linear pass. Latest completed result wins only its own check/parameter slot. */
+/** One linear pass. The newest completed result wins only its own check, environment and parameter slot. */
 export declare function combineEvidence(outline: ReportOutline, layers: readonly LayerEvidence[]): CombinedEvidence;
 export declare function slotKey(path: string, id: string): string;
 /** Suppress the mutable address of an execution already archived as an immutable layer. */

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

@@ -1,3 +1,4 @@
+import { layerPlace } from './layer-axes.js';
 /** Advisory identity, never a cryptographic integrity check. */
 export function textFingerprint(text) {
     let a = 2166136261, b = 5381;
@@ -30,6 +31,7 @@ export function outcomeCounts(rows) {
 }
 /** A layer as the explorer reads it: its origin, and each check as one row. */
 export function layerEvidence(summary, backend) {
+    const place = layerPlace(summary);
     const source = summary.source;
     const tests = new Map(source?.tests.map(test => [`${source.source}/${test.testId}`, test]) ?? []);
     const rows = summary.parts.flatMap(part => part.checks.map(check => {
@@ -58,8 +60,9 @@ export function layerEvidence(summary, backend) {
         recordedAtMs: summary.recordedAtMs,
         sha: summary.sha,
         branch: summary.branch,
+        environment: place.environment,
         runUrl: summary.runUrl,
-        parameters: summary.parameters,
+        parameters: place.parameters,
         recording: recording === null ? null : recording.type === 'layer' ? { type: 'layer', layer: summary.id } : recording,
         live: false,
         counts: outcomeCounts(rows),
@@ -106,7 +109,7 @@ function replaces(next, prior) {
         return RANK[next.row.status] > RANK[prior.row.status];
     return next.layer.id > prior.layer.id;
 }
-/** One linear pass. Latest completed result wins only its own check/parameter slot. */
+/** One linear pass. The newest completed result wins only its own check, environment and parameter slot. */
 export function combineEvidence(outline, layers) {
     const specs = new Map(outline.specs.map(spec => [specPath(spec.path), { spec, results: [] }]));
     const changed = new Set(outline.changedFiles.map(specPath));
@@ -115,9 +118,11 @@ export function combineEvidence(outline, layers) {
         const scope = layer.packageDir;
         const related = outline.changedFiles.some(file => scope ? file.startsWith(`${scope}/`) : !specPath(file).startsWith('specs/'));
         for (const row of rows) {
-            const parameters = { ...layer.parameters, ...row.variant };
+            // Environment and the layer's other choices split the slot. A harness
+            // seed does not: a focused rerun replaces the check it repeated.
+            const parameters = layer.parameters;
             const path = row.specPath ?? '';
-            const key = JSON.stringify([layer.producer, row.kind, path, row.id, parameterKey(parameters)]);
+            const key = JSON.stringify([layer.producer, row.kind, path, row.id, layer.environment ?? '', parameterKey(parameters)]);
             const result = { key, slot: slotKey(path, row.id), layer, row, parameters, warning: warning(layer, path, specs.get(path)?.spec, outline, fingerprints[path], related || changed.has(path)) };
             const prior = winners.get(key);
             if (!prior || replaces(result, prior))

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

@@ -1,4 +1,5 @@
 import { writeBundle } from './bundle.js';
+import { normalizeEnvironment } from './layer-axes.js';
 import { readCommit, readFrameCss } from './read.js';
 import { readInventory } from './spec-inventory.js';
 import { sourceParts } from './source-part.js';
@@ -25,8 +26,10 @@ export async function archiveSourceLayer(store, args, source, tests, bundle) {
     const index = await writeBundle(store, entries(), 'layers/blobs/');
     for (const [key, value] of Object.entries(bundle ?? {}))
         index[layerPath(key)] = value;
+    const environment = normalizeEnvironment(args.environment ?? args.parameters?.environment);
     return publishLayerBundle(store, {
         ...(args.freshness ? { freshness: args.freshness } : {}), producer: source.source, recordedAtMs, sha: args.sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null,
+        ...(environment ? { environment } : {}),
         parameters: args.parameters ?? {}, specs: inventory?.entries ?? [], parts: sourceParts(args.sha, source), source, recording: { type: 'layer' },
     }, index);
 }

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

@@ -9,6 +9,8 @@ export type LayerSummary = {
     readonly producer: string;
     readonly sha: string | null;
     readonly branch: string | null;
+    /** The client this layer checked, when it said. Normalized when the layer is read. */
+    readonly environment?: string | null;
     readonly runUrl: string | null;
     readonly parameters: LayerParameters;
     readonly specs: readonly SpecEntry[];

package/dist/reports/src/layers-route.js

@@ -1,7 +1,7 @@
 import { Hono } from 'hono';
 import { createBundleReader } from './bundle.js';
 import { eachLimited } from './completion-order.js';
-import { createLiveEvidence } from './evidence-live.js';
+import { createLiveEvidence, liveRunRecord } from './evidence-live.js';
 import { isFramePath, isKeySegment } from './keys.js';
 import { catalogEntries, catalogLayers } from './layer-catalog.js';
 import { layerEvidence } from './layer-merge.js';
@@ -130,10 +130,7 @@ export function createLayersApp(deps) {
                 const raw = await readUtf8(local, key);
                 if (raw === null)
                     return null;
-                const run = JSON.parse(raw);
-                if (!run.packageDir || !run.bucket || typeof run.startedAtMs !== 'number')
-                    return null;
-                return { packageDir: run.packageDir, bucket: run.bucket, startedAtMs: run.startedAtMs, ...(typeof run.plannedChecks === 'number' ? { plannedChecks: run.plannedChecks } : {}) };
+                return liveRunRecord(JSON.parse(raw));
             }
             catch {
                 return null;

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

@@ -30,6 +30,10 @@ export type SourceRecord = {
     readonly bucket: string;
     readonly status: ReportTestStatus;
     readonly updatedAtMs: number;
+    /** The client this source checked, when the run said. */
+    readonly environment?: string;
+    /** Recorded choices other than the client, such as an example or a device size. */
+    readonly parameters?: Readonly<Record<string, string>>;
     /** Each test's meta, test-runner outcomes already applied. */
     readonly tests: readonly RunReportMeta[];
 };

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

@@ -24,6 +24,8 @@ export type PublishSourceArgs = {
     /** Execution completion time, separate from a virtual timeline clock. */
     readonly recordedAtMs?: number;
     readonly freshness?: 'unknown' | 'modified';
+    /** The client this run checked: desktop web, mobile web, iOS, Android, or another recorded name. */
+    readonly environment?: string;
     readonly parameters?: LayerParameters;
     readonly sha: string;
     readonly packageDir: string;

package/dist/reports/src/publish.js

@@ -1,4 +1,5 @@
 import { archiveSourceLayer } from './layer-source.js';
+import { normalizeEnvironment } from './layer-axes.js';
 import { performancePart } from './performance-part.js';
 import { applyJunitOutcomes, parseJunit, } from './junit.js';
 import { testFrameKey, testPrefix, testReportKey, } from './recording-keys.js';
@@ -113,12 +114,15 @@ export async function publishSource(store, args) {
             await writeUtf8(store, `${contentPrefix}${report.meta.testId}/report.json`, JSON.stringify(report), JSON_TYPE);
         });
     }
+    const environment = normalizeEnvironment(args.environment ?? args.parameters?.environment);
     const record = {
         source,
         packageDir: args.packageDir,
         bucket: args.bucket,
         status,
         updatedAtMs: args.recordedAtMs ?? metas.reduce((latest, meta) => Math.max(latest, meta.endedAtMs), 0),
+        ...(environment ? { environment } : {}),
+        ...(args.parameters && Object.keys(args.parameters).length > 0 ? { parameters: args.parameters } : {}),
         tests: metas,
         ...(await sourceEvidence(args.local, args.sha, source, tests)),
     };

package/dist/reports/src/report-parts.js

@@ -1,3 +1,4 @@
+import { normalizeEnvironment } from './layer-axes.js';
 import { publishLayer } from './layer-store.js';
 import { readCommit } from './read.js';
 import { readInventory } from './spec-inventory.js';
@@ -68,8 +69,10 @@ export async function publishPart(store, part) {
     await writeUtf8(store, `${partsPrefix(part.sha)}${part.id}/${part.recordedAtMs}-${hash}.json`, json, 'application/json');
     await recordExplorerVersion(store, part.sha);
     const commit = await readCommit(store, part.sha);
+    const environment = normalizeEnvironment(part.parameters?.environment);
     await publishLayer(store, {
         ...(part.freshness ? { freshness: part.freshness } : {}), producer: part.id, recordedAtMs: part.recordedAtMs, sha: part.sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null,
+        ...(environment ? { environment } : {}),
         parameters: part.parameters ?? {}, specs: (await readInventory(store, part.sha))?.entries ?? [], parts: [part], source: null, recording: null,
     }, (async function* () { })());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Atlas: executable statecharts. Spec a product's flows as statecharts, run them against the real app with any driver, and browse what happened.",
   "license": "MIT",
   "type": "module",
@@ -107,7 +107,7 @@
     "test": "bun test && bun test --cwd packages/visualizer --preload ./tests/preload.ts tests",
     "type-check": "for dir in packages/* scripts examples/todo; do tsc --noEmit -p \"$dir\" || exit 1; done",
     "schemas": "bun packages/schema/scripts/emit-json-schemas.ts",
-    "viz:dev": "cd packages/visualizer && INIT_CWD=\"$OLDPWD\" bun --bun vite --configLoader runner",
+    "viz:dev": "bun packages/visualizer/bin/atlas-visualizer.mjs dev --specs \"$(pwd)/packages/visualizer/fixtures/full/specs\" --runs \"$(pwd)/packages/visualizer/fixtures/full/runs\"",
     "viz:build": "cd packages/visualizer && INIT_CWD=\"$OLDPWD\" bun --bun vite build --configLoader runner",
     "viz:publish-data": "bun packages/visualizer/scripts/publish-data.ts",
     "viz:fixtures": "bun packages/visualizer/scripts/make-fixtures.ts",

package/packages/reports/README.md

@@ -10,11 +10,11 @@ The Atlas visualizer shows each kind of spec in its own tab, with every spec's r
 
 ## Combining evidence
 
-Current specs define the outline. `combineEvidence` fills it with the newest completed result for each producer, check and parameter set, across backends, branches and commits. Equal-time conflicts favor failure. Unfinished runs do not erase completed outcomes. Missing specs stay visible and removed specs retain their evidence outside the outline. `evidenceView` groups those results by check: the outcomes, the recorded timings that qualify them, and a summary per spec. A timing over its allowance never fails a check. `checkHistory` returns every layer's own record of one check, so a superseded result stays readable. Leaving a backend, a branch or one layer out (`contributes`) is how earlier outcomes are inspected.
+Current specs define the outline. A layer is one focused recording: the checks it actually ran, on one environment, from one version and branch, in one store. `combineEvidence` fills the outline from every layer. The newest completed result wins only its own producer, check, environment and parameter set. Desktop web, mobile web, iOS and Android of the same check all stay visible, and any other recorded environment does too. A layer that ran one scenario leaves every other scenario as the newest layer that did run it, so the report fills without one suite that runs everything. Equal-time conflicts favor failure. Unfinished runs do not erase completed outcomes. Missing specs stay visible and removed specs retain their evidence outside the outline. `evidenceView` groups those results by check: the outcomes, the recorded timings that qualify them, and a summary per spec. A timing over its allowance never fails a check. `checkHistory` returns every layer's own record of one check, so a superseded result stays readable. Leaving a backend, an environment, a branch, a version or one layer out (`contributes`) is how earlier outcomes are inspected.
 
 ## Backends
 
-`createReportsApp` combines layers from several stores. `localStore` is the backend `local` ("This machine"), `store` is `shared` ("Shared reports"), and `backends` adds any number of further named stores, such as another team's bucket or a device lab. Every layer says which backend it came from. An unavailable backend is named in the page's notices and leaves the others usable; `GET /evidence?retry=1` asks it again without waiting.
+`createReportsApp` combines layers from several stores. `localStore` is the backend `local` ("This machine"), `store` is `shared` ("Shared reports"), and `backends` adds any number of further named stores. A backend is any `ObjectStore`: the local disk, a shared bucket, S3, or a device lab. Every layer says which backend, version, branch and environment it came from. An unavailable backend is named in the page's notices and leaves the others usable; `GET /evidence?retry=1` asks it again without waiting.
 
 | Route | Returns |
 | --- | --- |
@@ -40,6 +40,8 @@ Freshness warnings preserve the recorded outcome. Changed spec fingerprints or r
 
 Configure `ATLAS_REPORTS_MODULE` with a host composition module exporting `reportsDevFetch(request, repoRoot)`. Atlas's Vite middleware serves it at `/api/reports`, alongside specs and chart runs. `INIT_CWD` identifies the consuming repository. Credentials stay in that server module.
 
+When that module is unset and the open specs are the coffee example or the todo example, the visualizer dev server serves an in-memory layered report for those documents instead. Any other spec set is left alone. The todo example's own module serves that same layered report and adds the desktop web layer `example:run` writes.
+
 For a separately hosted reports API, set `VITE_ATLAS_REPORTS_URL` when building the visualizer. Otherwise a built site reads `data/evidence/`, populated with `exportEvidence`. Atlas still browses specs if evidence is absent.
 
 ## Verification

package/packages/reports/STORAGE.md

@@ -7,7 +7,7 @@ storage and time ports from its caller.
 
 `layers/index/<inverted-time>-<digest>.json` discovers immutable manifests at `layers/manifests/<digest>.json`. Each records producer, origin, parameters, checks, spec fingerprints and a recording bundle. The manifest is written after its blobs and the index last. Distinct results at the same timestamp retain separate identities. Compressed blobs under `layers/blobs/` are addressed by content and reused across runs; ordinary source publication shares its bundle directly with its layer without recompressing snapshots.
 
-Git commits are provenance and exact historical recording addresses, never a report partition. `combineEvidence` chooses completed results per check and parameters, retaining gaps from older layers. `publishSource` accepts `parameters`, and standalone parts may include them too. Inventory must be published before results for fingerprint comparison to be available.
+Git commits are provenance and exact historical recording addresses, never a report partition. `combineEvidence` chooses the newest completed result per check, environment and parameters, and keeps every other cell. An environment is the client that was checked (`desktop-web`, `mobile-web`, `ios`, `android`, or any other recorded name). The same check on two environments contributes twice. A layer that checks one scenario fills only that scenario. `publishSource` accepts `environment` and `parameters`, and a part may name its environment in `parameters.environment`. Inventory must be published before results for fingerprint comparison to be available.
 
 ## Commit inventory
 

package/packages/visualizer/README.md

@@ -38,8 +38,8 @@ atlas-visualizer dev --specs ./specs --runs ./atlas-runs
 | `--port <n>`, `--host <host>` | `dev`: where to listen (default `localhost:5180`, or the next free port).                   |
 
 Relative paths resolve against the directory the command was run from. Without flags the
-environment is read: `ATLAS_SPECS_ROOT`, `ATLAS_RUNS_ROOT` (relative to `INIT_CWD` when your package
-manager sets it to where you ran the command, or the current directory) and `ATLAS_FIXTURE`. With nothing configured and no
+environment is read: `ATLAS_SPECS_ROOT` and `ATLAS_RUNS_ROOT` (relative to `INIT_CWD` when your package
+manager sets it to where you ran the command, or the current directory). With nothing configured and no
 `specs/` directory, the `full` example is shown.
 
 Editing a spec file or a run publishing a snapshot updates the open page in about a second, without a reload,
@@ -62,8 +62,7 @@ sets how often the site checks for new runs (default 60 s, plus when the tab reg
 ### Inside this repository
 
 ```sh
-bun run viz:dev                          # ATLAS_SPECS_ROOT / ATLAS_RUNS_ROOT, or the example
-ATLAS_FIXTURE=partial bun run viz:dev    # one of the fixtures
+bun run viz:dev                          # the full coffee example, charts and layered report
 bun test packages/visualizer/src packages/visualizer/vite   # parsing, composition, statuses, every fixture
 bun run viz:fixtures                     # regenerate the fixtures (needs ImageMagick, cwebp, ffmpeg)
 ```
@@ -149,7 +148,9 @@ MIT
 
 Beside the statechart map, every other kind of spec has its own tab: Gherkin features, Quint models, DMN decision tables, Alloy structures and OpenSLO objectives. A tab appears when the specs folder has files of its kind. The index lists every spec with what was recorded for it, and filters to those with results, those failing, or those with none. A spec page shows each scenario, trace or check with its outcome; opening one shows the recorded steps, the error, the timings, every other run of the same check, and its recording.
 
-Results come from the Atlas reports API (`/api/reports` in dev, `VITE_ATLAS_REPORTS_URL` when hosted elsewhere) or from a static `data/evidence` export. They combine across backends, branches and runs; **Sources** in the header switches any of them off. While a spec suite is running, the header says so and each finished test appears within a couple of seconds. See [Atlas reports](../reports/README.md) for the API and host configuration.
+Results come from the Atlas reports API (`/api/reports` in dev, `VITE_ATLAS_REPORTS_URL` when hosted elsewhere) or from a static `data/evidence` export. They combine across backends, branches, versions, environments and layers; **Sources** in the header switches any of them off. While a spec suite is running, the header says so and each finished test appears within a couple of seconds. See [Atlas reports](../reports/README.md) for the API and host configuration.
+
+The coffee example ships those documents and a layered report. `bun run viz:dev` opens that full example, and the same report is the fallback when a working directory has no `specs/` and `ATLAS_REPORTS_MODULE` is unset. `atlas:viz` serves the same kind of report for the todo example, and adds the desktop web layer `example:run` writes. Each built-in report is five layers: an older desktop web run, a mobile web branch, Android from a device lab, a focused iOS run, and a newer desktop web run that repeated one scenario. The same check stays visible on each environment. A feature with no layer stays empty.
 
 The header title is the product's name, taken from `atlas.yaml`'s `title` up to its first dash or colon, or "Atlas".
 

package/packages/visualizer/example/specs/coffee/ordering/cart.qnt

@@ -0,0 +1,7 @@
+# Cart
+module cart {
+  var items: int
+  var paid: bool
+  action add = items' = items + 1
+  action pay = paid' = true
+}

package/packages/visualizer/example/specs/coffee/ordering/checkout.openslo.yaml

@@ -0,0 +1,10 @@
+# Checkout latency
+apiVersion: openslo/v1
+kind: SLO
+metadata:
+  name: checkout-latency
+spec:
+  description: Checkout answers within a second.
+  objectives:
+    - displayName: Checkout latency
+      target: 0.99

package/packages/visualizer/example/specs/coffee/ordering/drink-price.dmn

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/">
+  <decision id="drink-price" name="Drink price">
+    <decisionTable id="Drink price" hitPolicy="UNIQUE">
+      <input label="Size">
+        <inputExpression typeRef="string"><text>size</text></inputExpression>
+      </input>
+      <input label="Milk">
+        <inputExpression typeRef="string"><text>milk</text></inputExpression>
+      </input>
+      <output label="Price" name="price" />
+      <rule>
+        <inputEntry><text>"Small"</text></inputEntry>
+        <inputEntry><text>"None"</text></inputEntry>
+        <outputEntry><text>3</text></outputEntry>
+      </rule>
+      <rule>
+        <inputEntry><text>"Large"</text></inputEntry>
+        <inputEntry><text>"Oat"</text></inputEntry>
+        <outputEntry><text>5</text></outputEntry>
+      </rule>
+    </decisionTable>
+  </decision>
+</definitions>