@crvouga/atlas 0.4.0 → 0.5.0

package/dist/schema/src/manifest.d.ts

@@ -1,7 +1,25 @@
+/**
+ * @module Statechart run manifest schemas
+ *
+ * Zod schemas for `runs/<run-id>/manifest.json`, the file `atlas run` writes for one run of a statechart spec: run
+ * info, the map of states and edges, one record per state, transition, path, journey and seed, the timeline and
+ * business events observed, and coverage. The envelope keeps each section `unknown` so a reader can validate every
+ * record on its own and keep the ones that parse (the visualizer's `parse/manifest.ts` does). Within a
+ * `schemaVersion` only optional fields are added. A run is published into the layered report with `atlas report
+ * publish --manifest`.
+ *
+ * @see docs/statecharts.md
+ * @see docs/report-contract.md
+ */
 import { z } from 'zod/v4';
 /** Manifest schema versions this package describes. Readers accept these and try newer ones. */
 export declare const MANIFEST_SCHEMA_VERSIONS: readonly [1];
+/**
+ * The newest manifest `schemaVersion` this package describes. The visualizer reads a manifest without a version as
+ * this one, and reads a newer one as far as it understands it.
+ */
 export declare const LATEST_MANIFEST_SCHEMA_VERSION = 1;
+/** Whether a screenshot or clip a run promised is `ready`, still `processing` or `failed`. Absent means ready. */
 export declare const MEDIA_STATES: readonly ["ready", "processing", "failed"];
 /**
  * Proposed: the runner marks media it has promised but not finished writing, so a viewer can
@@ -12,7 +30,16 @@ export declare const MediaStateSchema: z.ZodEnum<{
     ready: "ready";
     processing: "processing";
 }>;
+/**
+ * Kinds of `TimelineEntry` a driver records during a transition: `tap`, `type`, `system` (a call to or from another
+ * system), `screen` (the screen changed), `toast`, `note`, `time` (a clock jump), `notification`. A reader shows a
+ * kind it does not know as a `note`.
+ */
 export declare const TIMELINE_KINDS: readonly ["tap", "type", "system", "screen", "toast", "note", "time", "notification"];
+/**
+ * A call between the product and another system during a transition, recorded on a `system` timeline entry: source,
+ * endpoint, event type, payload and response. The HTTP driver records these.
+ */
 export declare const SystemCallSchema: z.ZodObject<{
     source: z.ZodOptional<z.ZodString>;
     endpoint: z.ZodOptional<z.ZodString>;
@@ -41,6 +68,10 @@ export declare const NotificationSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     body: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * One moment in a transition's timeline: what happened (`kind`, `label`), when (`atMs` from the start of the clip)
+ * and the details that go with the kind. The timeline becomes the captions of the transition's clip.
+ */
 export declare const TimelineEntrySchema: z.ZodObject<{
     atMs: z.ZodNumber;
     kind: z.ZodEnum<{
@@ -85,6 +116,7 @@ export declare const TimelineEntrySchema: z.ZodObject<{
     }, z.core.$strip>>;
     client: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `TimelineEntrySchema` value. */
 export type TimelineEntry = z.infer<typeof TimelineEntrySchema>;
 /** A CloudEvents 1.0 event (JSON format), as an event source observed it. */
 export declare const CloudEventSchema: z.ZodObject<{
@@ -97,7 +129,12 @@ export declare const CloudEventSchema: z.ZodObject<{
     datacontenttype: z.ZodOptional<z.ZodString>;
     data: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$loose>;
+/** A parsed `CloudEventSchema` value. */
 export type CloudEvent = z.infer<typeof CloudEventSchema>;
+/**
+ * The business events a state expects (from `meta.events`) against what event sources observed while the step ran:
+ * `expected`, `observed`, `missing`, and `noSignal` for those with no observable signal mapped.
+ */
 export declare const BusinessEventsSchema: z.ZodObject<{
     expected: z.ZodArray<z.ZodString>;
     observed: z.ZodArray<z.ZodString>;
@@ -114,14 +151,24 @@ export declare const BusinessEventsSchema: z.ZodObject<{
         data: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>>>;
 }, z.core.$strip>;
+/** A parsed `BusinessEventsSchema` value. */
 export type BusinessEvents = z.infer<typeof BusinessEventsSchema>;
+/**
+ * The result of one item of a state's `meta.checks`: its text, whether it held, and what was expected and seen when
+ * it did not. A failed check fails the state.
+ */
 export declare const CheckResultSchema: z.ZodObject<{
     check: z.ZodString;
     passed: z.ZodBoolean;
     expected: z.ZodOptional<z.ZodString>;
     actual: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `CheckResultSchema` value. */
 export type CheckResult = z.infer<typeof CheckResultSchema>;
+/**
+ * What a state's recogniser saw: whether the state matched, and each signal with what was expected (visible or
+ * hidden) and whether it was visible.
+ */
 export declare const RecognizerSchema: z.ZodObject<{
     matched: z.ZodBoolean;
     signals: z.ZodArray<z.ZodObject<{
@@ -130,6 +177,11 @@ export declare const RecognizerSchema: z.ZodObject<{
         visible: z.ZodBoolean;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * The `run` section of a manifest: identity, timing and provenance of the run (id, start and finish, commit, branch,
+ * environment, mode), the spec version and directory, how far it has got, and how the plan was split, scoped, reused
+ * or merged.
+ */
 export declare const RunInfoSchema: z.ZodObject<{
     id: z.ZodString;
     startedAt: z.ZodString;
@@ -167,7 +219,12 @@ export declare const RunInfoSchema: z.ZodObject<{
     }, z.core.$strip>>;
     mergedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/** A parsed `RunInfoSchema` value. */
 export type RunInfo = z.infer<typeof RunInfoSchema>;
+/**
+ * A chart that took part in the run: its id, spec file and description, the state of its parent that invokes it, and,
+ * for each of its final states, the hand-off event its parent receives.
+ */
 export declare const ManifestChartSchema: z.ZodObject<{
     id: z.ZodString;
     file: z.ZodString;
@@ -175,6 +232,10 @@ export declare const ManifestChartSchema: z.ZodObject<{
     parentState: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     handOffs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * A state in the map of the composed product: id, parent state, chart, type, initial child, and whether it is inside
+ * the scope of the run.
+ */
 export declare const MapNodeSchema: z.ZodObject<{
     id: z.ZodString;
     parent: z.ZodNullable<z.ZodString>;
@@ -188,6 +249,10 @@ export declare const MapNodeSchema: z.ZodObject<{
     initial: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     inScope: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * A transition in the map: its id (see `transitionId`), source and target state names (the target is empty when the
+ * event leads nowhere), the event, who sends it, and whether it is inside the scope of the run.
+ */
 export declare const MapEdgeSchema: z.ZodObject<{
     id: z.ZodString;
     source: z.ZodString;
@@ -201,6 +266,11 @@ export declare const MapEdgeSchema: z.ZodObject<{
     }>>;
     inScope: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * The result for one state: what the spec says about it (description, snapshot, confidence, sources, expected
+ * events), whether the run reached it, its screenshots, what the recogniser saw, the business events and
+ * `meta.checks` results, and the paths that reached it.
+ */
 export declare const StateRecordSchema: z.ZodObject<{
     name: z.ZodString;
     chart: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -280,7 +350,12 @@ export declare const StateRecordSchema: z.ZodObject<{
     reachedBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
     notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/** A parsed `StateRecordSchema` value. */
 export type StateRecord = z.infer<typeof StateRecordSchema>;
+/**
+ * A video of one transition: `video` and `poster` as paths relative to the run directory, its duration, and which
+ * client's screen it shows.
+ */
 export declare const ClipSchema: z.ZodObject<{
     video: z.ZodString;
     poster: z.ZodOptional<z.ZodString>;
@@ -293,7 +368,13 @@ export declare const ClipSchema: z.ZodObject<{
         processing: "processing";
     }>>;
 }, z.core.$strip>;
+/** A parsed `ClipSchema` value. */
 export type Clip = z.infer<typeof ClipSchema>;
+/**
+ * The result for one transition (an event leaving a state): source, target, event, who sends it, how the
+ * implementation makes it happen, its status, clip and timeline, why it was not reached, and the paths that took it.
+ * Keyed in a manifest by its id (see `transitionId`).
+ */
 export declare const TransitionRecordSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     source: z.ZodString;
@@ -329,7 +410,9 @@ export declare const TransitionRecordSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     reachedBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/** A parsed `TransitionRecordSchema` value. */
 export type TransitionRecord = z.infer<typeof TransitionRecordSchema>;
+/** One step of a path: the event, the transition it takes and its outcome, with the reason when it was not reached. */
 export declare const PathStepSchema: z.ZodObject<{
     transition: z.ZodOptional<z.ZodString>;
     event: z.ZodString;
@@ -341,6 +424,11 @@ export declare const PathStepSchema: z.ZodObject<{
     }>>;
     reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * The result for one planned path: a curated `journey` or a `generated` path covering transitions. It holds the
+ * status, every attempt (a failed first attempt is retried once unless retries are off), the steps and where it
+ * stopped, and the identity (`key`), start states and seed that let results from different runs compose.
+ */
 export declare const PathRecordSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -377,6 +465,7 @@ export declare const PathRecordSchema: z.ZodObject<{
     setupMs: z.ZodOptional<z.ZodNumber>;
     reusedFrom: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `PathRecordSchema` value. */
 export type PathRecord = z.infer<typeof PathRecordSchema>;
 /** A journey's result, composed from the paths it is cut into (one per seeded stretch). */
 export declare const JourneyRecordSchema: z.ZodObject<{
@@ -391,6 +480,7 @@ export declare const JourneyRecordSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString>;
     stoppedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
+/** A parsed `JourneyRecordSchema` value. */
 export type JourneyRecord = z.infer<typeof JourneyRecordSchema>;
 /** A configuration the implementation can put the system in directly, and what checks it. */
 export declare const SeedRecordSchema: z.ZodObject<{
@@ -403,6 +493,7 @@ export declare const SeedRecordSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString>;
     verifiedBy: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `SeedRecordSchema` value. */
 export type SeedRecord = z.infer<typeof SeedRecordSchema>;
 /** Other formats the run wrote, relative to the manifest: JUnit XML, CTRF JSON, Mermaid. */
 export declare const ReportsSchema: z.ZodObject<{
@@ -410,6 +501,10 @@ export declare const ReportsSchema: z.ZodObject<{
     ctrf: z.ZodOptional<z.ZodString>;
     mermaid: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * Result of the privacy scan of a run: whether it passed and what it found. Media of a run whose scan did not pass
+ * are not uploaded with `--upload-run`.
+ */
 export declare const PrivacySchema: z.ZodObject<{
     passed: z.ZodBoolean;
     findings: z.ZodArray<z.ZodString>;

package/dist/schema/src/manifest.js

@@ -1,15 +1,42 @@
+/**
+ * @module Statechart run manifest schemas
+ *
+ * Zod schemas for `runs/<run-id>/manifest.json`, the file `atlas run` writes for one run of a statechart spec: run
+ * info, the map of states and edges, one record per state, transition, path, journey and seed, the timeline and
+ * business events observed, and coverage. The envelope keeps each section `unknown` so a reader can validate every
+ * record on its own and keep the ones that parse (the visualizer's `parse/manifest.ts` does). Within a
+ * `schemaVersion` only optional fields are added. A run is published into the layered report with `atlas report
+ * publish --manifest`.
+ *
+ * @see docs/statecharts.md
+ * @see docs/report-contract.md
+ */
 import { z } from 'zod/v4';
 import { CountSchema, EventKindSchema, ImageSchema, RunStatusSchema } from './common.js';
 /** Manifest schema versions this package describes. Readers accept these and try newer ones. */
 export const MANIFEST_SCHEMA_VERSIONS = [1];
+/**
+ * The newest manifest `schemaVersion` this package describes. The visualizer reads a manifest without a version as
+ * this one, and reads a newer one as far as it understands it.
+ */
 export const LATEST_MANIFEST_SCHEMA_VERSION = 1;
+/** Whether a screenshot or clip a run promised is `ready`, still `processing` or `failed`. Absent means ready. */
 export const MEDIA_STATES = ['ready', 'processing', 'failed'];
 /**
  * Proposed: the runner marks media it has promised but not finished writing, so a viewer can
  * show "still processing" instead of a broken image. Absent means ready.
  */
 export const MediaStateSchema = z.enum(MEDIA_STATES);
+/**
+ * Kinds of `TimelineEntry` a driver records during a transition: `tap`, `type`, `system` (a call to or from another
+ * system), `screen` (the screen changed), `toast`, `note`, `time` (a clock jump), `notification`. A reader shows a
+ * kind it does not know as a `note`.
+ */
 export const TIMELINE_KINDS = ['tap', 'type', 'system', 'screen', 'toast', 'note', 'time', 'notification'];
+/**
+ * A call between the product and another system during a transition, recorded on a `system` timeline entry: source,
+ * endpoint, event type, payload and response. The HTTP driver records these.
+ */
 export const SystemCallSchema = z.object({
     source: z.string().optional(),
     endpoint: z.string().optional(),
@@ -30,6 +57,10 @@ export const NotificationSchema = z.object({
     title: z.string().optional(),
     body: z.string().optional()
 });
+/**
+ * One moment in a transition's timeline: what happened (`kind`, `label`), when (`atMs` from the start of the clip)
+ * and the details that go with the kind. The timeline becomes the captions of the transition's clip.
+ */
 export const TimelineEntrySchema = z.object({
     atMs: z.number().nonnegative().describe('Milliseconds from the start of the clip'),
     kind: z.enum(TIMELINE_KINDS),
@@ -55,6 +86,10 @@ export const CloudEventSchema = z
     data: z.unknown().optional()
 })
     .passthrough();
+/**
+ * The business events a state expects (from `meta.events`) against what event sources observed while the step ran:
+ * `expected`, `observed`, `missing`, and `noSignal` for those with no observable signal mapped.
+ */
 export const BusinessEventsSchema = z.object({
     expected: z.array(z.string()),
     observed: z.array(z.string()),
@@ -62,16 +97,29 @@ export const BusinessEventsSchema = z.object({
     noSignal: z.array(z.string()).describe('No observable signal is mapped yet'),
     events: z.array(CloudEventSchema).optional().describe('The CloudEvents observed during the step')
 });
+/**
+ * The result of one item of a state's `meta.checks`: its text, whether it held, and what was expected and seen when
+ * it did not. A failed check fails the state.
+ */
 export const CheckResultSchema = z.object({
     check: z.string(),
     passed: z.boolean(),
     expected: z.string().optional(),
     actual: z.string().optional()
 });
+/**
+ * What a state's recogniser saw: whether the state matched, and each signal with what was expected (visible or
+ * hidden) and whether it was visible.
+ */
 export const RecognizerSchema = z.object({
     matched: z.boolean(),
     signals: z.array(z.object({ signal: z.string(), expected: z.string(), visible: z.boolean() }))
 });
+/**
+ * The `run` section of a manifest: identity, timing and provenance of the run (id, start and finish, commit, branch,
+ * environment, mode), the spec version and directory, how far it has got, and how the plan was split, scoped, reused
+ * or merged.
+ */
 export const RunInfoSchema = z.object({
     id: z.string().min(1),
     startedAt: z.string(),
@@ -98,6 +146,10 @@ export const RunInfoSchema = z.object({
     reused: z.object({ from: z.string(), paths: z.number().int().nonnegative() }).optional().describe('Passed paths kept from an earlier run instead of running again'),
     mergedFrom: z.array(z.string()).optional().describe('The runs this run was composed from')
 });
+/**
+ * A chart that took part in the run: its id, spec file and description, the state of its parent that invokes it, and,
+ * for each of its final states, the hand-off event its parent receives.
+ */
 export const ManifestChartSchema = z.object({
     id: z.string().min(1),
     file: z.string(),
@@ -105,6 +157,10 @@ export const ManifestChartSchema = z.object({
     parentState: z.string().nullable().optional(),
     handOffs: z.record(z.string(), z.string()).optional()
 });
+/**
+ * A state in the map of the composed product: id, parent state, chart, type, initial child, and whether it is inside
+ * the scope of the run.
+ */
 export const MapNodeSchema = z.object({
     id: z.string().min(1),
     parent: z.string().nullable(),
@@ -113,6 +169,10 @@ export const MapNodeSchema = z.object({
     initial: z.string().nullable().optional(),
     inScope: z.boolean().optional()
 });
+/**
+ * A transition in the map: its id (see `transitionId`), source and target state names (the target is empty when the
+ * event leads nowhere), the event, who sends it, and whether it is inside the scope of the run.
+ */
 export const MapEdgeSchema = z.object({
     id: z.string().min(1),
     source: z.string(),
@@ -121,6 +181,11 @@ export const MapEdgeSchema = z.object({
     kind: EventKindSchema,
     inScope: z.boolean().optional()
 });
+/**
+ * The result for one state: what the spec says about it (description, snapshot, confidence, sources, expected
+ * events), whether the run reached it, its screenshots, what the recogniser saw, the business events and
+ * `meta.checks` results, and the paths that reached it.
+ */
 export const StateRecordSchema = z.object({
     name: z.string(),
     chart: z.string().nullable().optional(),
@@ -143,6 +208,10 @@ export const StateRecordSchema = z.object({
     reachedBy: z.array(z.string()).optional(),
     notes: z.array(z.string()).optional()
 });
+/**
+ * A video of one transition: `video` and `poster` as paths relative to the run directory, its duration, and which
+ * client's screen it shows.
+ */
 export const ClipSchema = z.object({
     video: z.string().min(1),
     poster: z.string().optional(),
@@ -151,6 +220,11 @@ export const ClipSchema = z.object({
     client: z.string().optional().describe('The client whose screen was recorded'),
     state: MediaStateSchema.optional()
 });
+/**
+ * The result for one transition (an event leaving a state): source, target, event, who sends it, how the
+ * implementation makes it happen, its status, clip and timeline, why it was not reached, and the paths that took it.
+ * Keyed in a manifest by its id (see `transitionId`).
+ */
 export const TransitionRecordSchema = z.object({
     id: z.string().optional(),
     source: z.string(),
@@ -165,12 +239,18 @@ export const TransitionRecordSchema = z.object({
     reason: z.string().nullable().optional(),
     reachedBy: z.array(z.string()).optional()
 });
+/** One step of a path: the event, the transition it takes and its outcome, with the reason when it was not reached. */
 export const PathStepSchema = z.object({
     transition: z.string().optional(),
     event: z.string(),
     status: RunStatusSchema.optional(),
     reason: z.string().nullable().optional()
 });
+/**
+ * The result for one planned path: a curated `journey` or a `generated` path covering transitions. It holds the
+ * status, every attempt (a failed first attempt is retried once unless retries are off), the steps and where it
+ * stopped, and the identity (`key`), start states and seed that let results from different runs compose.
+ */
 export const PathRecordSchema = z.object({
     id: z.string().min(1),
     name: z.string(),
@@ -222,6 +302,10 @@ export const ReportsSchema = z.object({
     ctrf: z.string().optional(),
     mermaid: z.string().optional()
 });
+/**
+ * Result of the privacy scan of a run: whether it passed and what it found. Media of a run whose scan did not pass
+ * are not uploaded with `--upload-run`.
+ */
 export const PrivacySchema = z.object({
     passed: z.boolean(),
     findings: z.array(z.string())

package/dist/schema/src/report-sources.d.ts

@@ -1,4 +1,19 @@
+/**
+ * @module Report sources and change notices
+ *
+ * The files and events the viewer uses to find runs. `ReportSourcesSchema` validates the sources file named by
+ * `ATLAS_SOURCES_FILE`, which lists extra places to read runs from (a directory, or another host over HTTP).
+ * `AtlasChangeSchema` is the payload of the `atlas:change` event that tells a live viewer that specs or runs changed.
+ * Both are read by the visualizer; the server sends the change notice.
+ *
+ * @see docs/report-backends.md
+ */
 import { z } from 'zod/v4';
+/**
+ * A source reached over HTTP: `type` `http` or `api`, a base URL without credentials, an optional events URL for live
+ * updates, a polling interval in milliseconds (1 000 to 3 600 000) and a `live` flag. The id `workspace` is reserved
+ * for the local runs directory.
+ */
 export declare const RemoteReportSourceSchema: z.ZodObject<{
     type: z.ZodEnum<{
         http: "http";
@@ -11,12 +26,17 @@ export declare const RemoteReportSourceSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
 }, z.core.$strip>;
+/**
+ * A source that is a directory of runs on the machine running the viewer. A relative `runs` path is resolved against
+ * the sources file.
+ */
 export declare const DirectoryReportSourceSchema: z.ZodObject<{
     type: z.ZodLiteral<"directory">;
     runs: z.ZodString;
     id: z.ZodString;
     label: z.ZodString;
 }, z.core.$strip>;
+/** One source: a directory or a remote host. */
 export declare const ReportSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"directory">;
     runs: z.ZodString;
@@ -34,8 +54,11 @@ export declare const ReportSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
 }, z.core.$strip>]>;
+/** A parsed `ReportSourceSchema` value. */
 export type ReportSource = z.infer<typeof ReportSourceSchema>;
+/** A parsed `RemoteReportSourceSchema` value. */
 export type RemoteReportSource = z.infer<typeof RemoteReportSourceSchema>;
+/** The sources file, `{ "schemaVersion": 1, "sources": [...] }`. Source ids must be unique. */
 export declare const ReportSourcesSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     sources: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
@@ -56,6 +79,10 @@ export declare const ReportSourcesSchema: z.ZodObject<{
         label: z.ZodString;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
+/**
+ * The payload of the `atlas:change` event: which `scope` changed (`specs` or `runs`), the files and run ids concerned
+ * (empty lists when not known), and the source that changed. Unknown payloads are ignored by the viewer.
+ */
 export declare const AtlasChangeSchema: z.ZodObject<{
     scope: z.ZodEnum<{
         specs: "specs";
@@ -65,4 +92,5 @@ export declare const AtlasChangeSchema: z.ZodObject<{
     runIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
     sourceId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `AtlasChangeSchema` value. */
 export type AtlasChange = z.infer<typeof AtlasChangeSchema>;

package/dist/schema/src/report-sources.js

@@ -1,3 +1,13 @@
+/**
+ * @module Report sources and change notices
+ *
+ * The files and events the viewer uses to find runs. `ReportSourcesSchema` validates the sources file named by
+ * `ATLAS_SOURCES_FILE`, which lists extra places to read runs from (a directory, or another host over HTTP).
+ * `AtlasChangeSchema` is the payload of the `atlas:change` event that tells a live viewer that specs or runs changed.
+ * Both are read by the visualizer; the server sends the change notice.
+ *
+ * @see docs/report-backends.md
+ */
 import { z } from 'zod/v4';
 const SourceIdentity = {
     id: z
@@ -18,6 +28,11 @@ const HttpLocation = z
         return false;
     }
 }, 'Use an HTTP URL without credentials.');
+/**
+ * A source reached over HTTP: `type` `http` or `api`, a base URL without credentials, an optional events URL for live
+ * updates, a polling interval in milliseconds (1 000 to 3 600 000) and a `live` flag. The id `workspace` is reserved
+ * for the local runs directory.
+ */
 export const RemoteReportSourceSchema = z.object({
     ...SourceIdentity,
     type: z.enum(['http', 'api']),
@@ -26,12 +41,18 @@ export const RemoteReportSourceSchema = z.object({
     pollMs: z.number().int().min(1000).max(3_600_000).optional(),
     live: z.boolean().optional()
 });
+/**
+ * A source that is a directory of runs on the machine running the viewer. A relative `runs` path is resolved against
+ * the sources file.
+ */
 export const DirectoryReportSourceSchema = z.object({
     ...SourceIdentity,
     type: z.literal('directory'),
     runs: z.string().min(1)
 });
+/** One source: a directory or a remote host. */
 export const ReportSourceSchema = z.union([DirectoryReportSourceSchema, RemoteReportSourceSchema]);
+/** The sources file, `{ "schemaVersion": 1, "sources": [...] }`. Source ids must be unique. */
 export const ReportSourcesSchema = z
     .object({
     schemaVersion: z.literal(1),
@@ -45,6 +66,10 @@ export const ReportSourcesSchema = z
         ids.add(source.id);
     });
 });
+/**
+ * The payload of the `atlas:change` event: which `scope` changed (`specs` or `runs`), the files and run ids concerned
+ * (empty lists when not known), and the source that changed. Unknown payloads are ignored by the viewer.
+ */
 export const AtlasChangeSchema = z.object({
     scope: z.enum(['specs', 'runs']),
     files: z.array(z.string()).default([]),

package/dist/schema/src/runs-index.d.ts

@@ -1,5 +1,20 @@
+/**
+ * @module Runs index
+ *
+ * `runs/index.json`, the list of statechart runs a host serves, newest first, and the summary the viewer keeps for
+ * each. The index lists runs as `unknown` so a reader can validate each summary on its own and drop the ones that do
+ * not parse.
+ *
+ * @see docs/statecharts.md
+ */
 import { z } from 'zod/v4';
+/** Whether a run is still being written (`running`) or finished (`complete`). */
 export declare const RUN_PROGRESS: readonly ["running", "complete"];
+/**
+ * One run in the index: its id, start, mode, commit, branch, duration and spec version, whether it is `running` or
+ * complete, the planned and completed path counts of a running run, whether its manifest exists yet, and the state,
+ * transition and journey tallies.
+ */
 export declare const RunSummarySchema: z.ZodObject<{
     id: z.ZodString;
     startedAt: z.ZodString;
@@ -43,6 +58,7 @@ export declare const RunSummarySchema: z.ZodObject<{
         notReached: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** A parsed `RunSummarySchema` value. */
 export type RunSummary = z.infer<typeof RunSummarySchema>;
 /** `runs/index.json`: the runs a host serves, newest first. */
 export declare const RunsIndexSchema: z.ZodObject<{

package/dist/schema/src/runs-index.js

@@ -1,7 +1,22 @@
+/**
+ * @module Runs index
+ *
+ * `runs/index.json`, the list of statechart runs a host serves, newest first, and the summary the viewer keeps for
+ * each. The index lists runs as `unknown` so a reader can validate each summary on its own and drop the ones that do
+ * not parse.
+ *
+ * @see docs/statecharts.md
+ */
 import { z } from 'zod/v4';
 import { CountSchema } from './common.js';
 import { RunInfoSchema } from './manifest.js';
+/** Whether a run is still being written (`running`) or finished (`complete`). */
 export const RUN_PROGRESS = ['running', 'complete'];
+/**
+ * One run in the index: its id, start, mode, commit, branch, duration and spec version, whether it is `running` or
+ * complete, the planned and completed path counts of a running run, whether its manifest exists yet, and the state,
+ * transition and journey tallies.
+ */
 export const RunSummarySchema = z.object({
     id: z.string().min(1),
     startedAt: z.string(),