@crvouga/atlas 0.4.0 → 0.5.0

package/dist/schema/src/server-config.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @module Server configuration schema
+ *
+ * The schema of `atlas.server.json`, the file that configures `atlas serve` and `atlas dev`: where to listen, which
+ * folder and further backends hold the data, which bearer tokens may read, publish or administer, and limits. Every
+ * field has a default, so an empty file is a working server. Unlike the report format, unknown keys are an error, so
+ * a typo is reported instead of ignored. Flags and environment variables override the file.
+ *
+ * @see docs/deploying.md
+ * @see docs/server.md
+ */
+import { z } from 'zod/v4';
+/** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
+export declare const ServerRoleSchema: z.ZodEnum<{
+    read: "read";
+    publish: "publish";
+    admin: "admin";
+}>;
+/** One of the roles of `ServerRoleSchema`. */
+export type ServerRole = z.infer<typeof ServerRoleSchema>;
+/**
+ * A further store the server reads together with its data folder, and optionally writes to: an id, a label and a
+ * location URL.
+ */
+export declare const ServerBackendSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    write: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * A bearer token: a name for logs, a role, and the token itself or the name of the environment variable that holds it
+ * (exactly one of the two).
+ */
+export declare const ServerTokenSchema: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        read: "read";
+        publish: "publish";
+        admin: "admin";
+    }>;
+    token: z.ZodOptional<z.ZodString>;
+    tokenEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The whole `atlas.server.json`: listening address, data folder, backends and write target, authentication, the
+ * viewer to serve, which layers take part in the report, refresh and heartbeat intervals, request limits and logging.
+ */
+export declare const ServerConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    data: z.ZodDefault<z.ZodString>;
+    backends: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+        write: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    write: z.ZodOptional<z.ZodString>;
+    auth: z.ZodDefault<z.ZodObject<{
+        tokens: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            role: z.ZodEnum<{
+                read: "read";
+                publish: "publish";
+                admin: "admin";
+            }>;
+            token: z.ZodOptional<z.ZodString>;
+            tokenEnv: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        anonymousRead: z.ZodDefault<z.ZodBoolean>;
+        insecure: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    site: z.ZodOptional<z.ZodString>;
+    outlineBranch: z.ZodOptional<z.ZodString>;
+    include: z.ZodDefault<z.ZodObject<{
+        branches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignoreModified: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    refreshSeconds: z.ZodDefault<z.ZodNumber>;
+    limits: z.ZodDefault<z.ZodObject<{
+        maxObjectMiB: z.ZodDefault<z.ZodNumber>;
+        maxJsonMiB: z.ZodDefault<z.ZodNumber>;
+        maxStreams: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    heartbeatSeconds: z.ZodDefault<z.ZodNumber>;
+    log: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+/** A server configuration after parsing, with every default applied. */
+export type ServerConfig = z.output<typeof ServerConfigSchema>;
+/** A server configuration as written, before defaults are applied. */
+export type ServerConfigInput = z.input<typeof ServerConfigSchema>;

package/dist/schema/src/server-config.js

@@ -0,0 +1,73 @@
+/**
+ * @module Server configuration schema
+ *
+ * The schema of `atlas.server.json`, the file that configures `atlas serve` and `atlas dev`: where to listen, which
+ * folder and further backends hold the data, which bearer tokens may read, publish or administer, and limits. Every
+ * field has a default, so an empty file is a working server. Unlike the report format, unknown keys are an error, so
+ * a typo is reported instead of ignored. Flags and environment variables override the file.
+ *
+ * @see docs/deploying.md
+ * @see docs/server.md
+ */
+import { z } from 'zod/v4';
+/** What a bearer token may do: `read` (look), `publish` (also upload) or `admin` (also remove scratch objects). */
+export const ServerRoleSchema = z.enum(['read', 'publish', 'admin']);
+/**
+ * A further store the server reads together with its data folder, and optionally writes to: an id, a label and a
+ * location URL.
+ */
+export const ServerBackendSchema = z.strictObject({
+    id: z.string().regex(/^[a-z0-9-]+$/).describe('Lowercase letters, digits and hyphens. Names where a result came from'),
+    label: z.string().optional(),
+    url: z.string().min(1).describe('A folder, s3://bucket/prefix, r2://, gs://, or another Atlas server (https://…)'),
+    write: z.boolean().optional().describe('Uploads go here instead of the data folder. At most one backend is the write target')
+});
+/**
+ * A bearer token: a name for logs, a role, and the token itself or the name of the environment variable that holds it
+ * (exactly one of the two).
+ */
+export const ServerTokenSchema = z
+    .strictObject({
+    name: z.string().min(1).describe('Shown in logs, never the token itself'),
+    role: ServerRoleSchema.describe('`read` may look. `publish` may also upload. `admin` may also remove scratch objects'),
+    token: z.string().min(12).optional().describe('The token. Prefer `tokenEnv`, so the file holds no secret'),
+    tokenEnv: z.string().optional().describe('The name of the environment variable that holds the token')
+})
+    .refine((value) => (value.token === undefined) !== (value.tokenEnv === undefined), { message: 'Give exactly one of token or tokenEnv' });
+/**
+ * The whole `atlas.server.json`: listening address, data folder, backends and write target, authentication, the
+ * viewer to serve, which layers take part in the report, refresh and heartbeat intervals, request limits and logging.
+ */
+export const ServerConfigSchema = z.strictObject({
+    $schema: z.string().optional(),
+    host: z.string().default('127.0.0.1').describe('Where to listen. 127.0.0.1 keeps it on this machine; 0.0.0.0 is every interface and needs tokens (or `auth.insecure`)'),
+    port: z.number().int().min(0).max(65535).default(8080),
+    data: z.string().default('./atlas-data').describe('The folder that is the default backend and the default write target: layers, specs and runs live here'),
+    backends: z.array(ServerBackendSchema).default([]).describe('Further backends, read together with the data folder: S3, another server, a device lab'),
+    write: z.string().optional().describe('The id of the backend uploads go to. Default: the data folder'),
+    auth: z
+        .strictObject({
+        tokens: z.array(ServerTokenSchema).default([]),
+        anonymousRead: z.boolean().default(false).describe('Let anyone look without a token. Uploading still needs one'),
+        insecure: z.boolean().default(false).describe('Allow listening on every interface with no tokens at all')
+    })
+        .default({ tokens: [], anonymousRead: false, insecure: false }),
+    site: z.string().optional().describe('The built viewer. Default: the one shipped with Atlas, built on first start'),
+    outlineBranch: z.string().optional().describe('Which branch\'s specs the report is laid over. Default main, then master, then the newest'),
+    include: z
+        .strictObject({
+        branches: z.array(z.string()).optional().describe('Only layers recorded on these branches take part'),
+        ignoreModified: z.boolean().optional().describe('Leave out layers from modified checkouts and unknown origins')
+    })
+        .default({}),
+    refreshSeconds: z.number().min(1).default(10).describe('How often the backends are looked at for layers written by something other than this server'),
+    limits: z
+        .strictObject({
+        maxObjectMiB: z.number().positive().default(256).describe('The largest object an upload may be'),
+        maxJsonMiB: z.number().positive().default(32).describe('The largest JSON body (a manifest, a checks request)'),
+        maxStreams: z.number().int().positive().default(500).describe('Viewers that may be connected for live updates at once')
+    })
+        .default({ maxObjectMiB: 256, maxJsonMiB: 32, maxStreams: 500 }),
+    heartbeatSeconds: z.number().min(1).default(15).describe('How often a live connection is touched, so proxies keep it open'),
+    log: z.boolean().default(true).describe('One JSON line per request')
+});

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

@@ -1,17 +1,42 @@
+/**
+ * @module Statechart spec schemas
+ *
+ * Zod schemas for the files in a specs directory: the `meta` a chart's states carry, XState-style machine configs,
+ * `journeys.yaml`, the optional product map `atlas.yaml`, `<chart>.layout.json` and `specs/index.json`, plus the
+ * filename patterns that identify statechart files. They describe what a person writes, so readers validate each
+ * piece on its own and report problems rather than rejecting the whole spec (the visualizer's `parse/spec.ts` does).
+ * The pure subset of statecharts that Atlas executes is documented in `docs/statecharts.md`.
+ *
+ * @see docs/statecharts.md
+ */
 import { z } from 'zod/v4';
+/**
+ * Version of the spec file formats, currently 1. `LayoutFileSchema` and `SpecIndexSchema` accept only `schemaVersion:
+ * 1`.
+ */
 export declare const SPEC_SCHEMA_VERSION = 1;
+/**
+ * A state's link to its design: an image (URL or spec-relative path), and optionally where the design lives, such as
+ * a Figma frame.
+ */
 export declare const DesignLinkSchema: z.ZodObject<{
     image: z.ZodString;
     url: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `DesignLinkSchema` value. */
 export type DesignLink = z.infer<typeof DesignLinkSchema>;
+/** One Given/When/Then line of a business contract: the keyword, its text, and an optional data table or doc string. */
 export declare const ContractStepSchema: z.ZodObject<{
     keyword: z.ZodString;
     text: z.ZodString;
     table: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
     docString: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * A business rule copied from its authoritative `source` as exact Given/When/Then steps, carried in a state's
+ * `meta.contracts`.
+ */
 export declare const BusinessContractSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -24,6 +49,7 @@ export declare const BusinessContractSchema: z.ZodObject<{
         docString: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** A parsed `BusinessContractSchema` value. */
 export type BusinessContract = z.infer<typeof BusinessContractSchema>;
 /**
  * Every field a state's `meta` may carry. Each one is optional on its own: the visualizer keeps
@@ -72,6 +98,7 @@ export declare const StateMetaShape: {
     }>>>;
     readonly timeEvents: z.ZodRecord<z.ZodString, z.ZodString>;
 };
+/** `StateMetaShape` with every field optional: the `meta` of a state or of a whole chart. */
 export declare const StateMetaSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     snapshot: z.ZodOptional<z.ZodString>;
@@ -115,12 +142,20 @@ export declare const StateMetaSchema: z.ZodObject<{
     }>>>>;
     timeEvents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
+/** A parsed `StateMetaSchema` value. */
 export type StateMeta = z.infer<typeof StateMetaSchema>;
+/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`. */
 export declare const TransitionTargetSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     target: z.ZodString;
 }, z.core.$strip>]>;
+/** Kinds of state in the composed map: `atomic`, `compound`, `parallel`, `final`. */
 export declare const STATE_TYPES: readonly ["atomic", "compound", "parallel", "final"];
+/** One of `STATE_TYPES`. */
 export type StateType = (typeof STATE_TYPES)[number];
+/**
+ * TypeScript shape of one state of a machine config, matching `StateNodeSchema`: optional `id`, `initial`, `type`
+ * (`parallel` or `final`), `meta`, nested `states` and `on` transitions.
+ */
 export type StateNodeConfig = {
     id?: string | undefined;
     initial?: string | undefined;
@@ -129,7 +164,16 @@ export type StateNodeConfig = {
     states?: Record<string, StateNodeConfig> | undefined;
     on?: Record<string, z.infer<typeof TransitionTargetSchema>> | undefined;
 };
+/**
+ * One state of an XState machine config, recursively, restricted to what Atlas reads: nesting, `parallel` and `final`
+ * types, event transitions and `meta`. Guards, actions and the rest of XState are rejected by `atlas lint`, not by
+ * this schema. Emitted as `state-node.schema.json`.
+ */
 export declare const StateNodeSchema: z.ZodType<StateNodeConfig>;
+/**
+ * A whole chart: its `id`, optional `initial`, `type` and `meta`, and its `states`. The states are `unknown` here;
+ * validate each with `StateNodeSchema`.
+ */
 export declare const MachineSchema: z.ZodObject<{
     id: z.ZodString;
     initial: z.ZodOptional<z.ZodString>;
@@ -181,6 +225,11 @@ export declare const MachineSchema: z.ZodObject<{
     }, z.core.$strip>>;
     states: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
+/**
+ * One curated journey in `journeys.yaml`: the business events replayed in order from the initial state, the states it
+ * must end in, and an optional owner and tour flag. `atlas lint` replays every journey, and `atlas run` runs each as
+ * its own path.
+ */
 export declare const JourneySchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     events: z.ZodArray<z.ZodString>;
@@ -188,10 +237,19 @@ export declare const JourneySchema: z.ZodObject<{
     owner: z.ZodOptional<z.ZodString>;
     tour: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/** A parsed `JourneySchema` value. */
 export type JourneyConfig = z.infer<typeof JourneySchema>;
+/**
+ * `journeys.yaml`: a `journeys` map from journey name to journey. The entries are `unknown` here; validate each with
+ * `JourneySchema`.
+ */
 export declare const JourneysFileSchema: z.ZodObject<{
     journeys: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
+/**
+ * A product area declared in `atlas.yaml`: its id, display name, description, owner and the spec-relative directories
+ * whose charts belong to it.
+ */
 export declare const AtlasContextSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
@@ -199,6 +257,10 @@ export declare const AtlasContextSchema: z.ZodObject<{
     owner: z.ZodOptional<z.ZodString>;
     directories: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * A hand-off declared in `atlas.yaml` between two product areas: the ids of the area it `from` and `to`, and the
+ * event that passes control.
+ */
 export declare const AtlasHandOffSchema: z.ZodObject<{
     from: z.ZodString;
     to: z.ZodString;
@@ -229,6 +291,7 @@ export declare const LayoutFileSchema: z.ZodObject<{
         height: z.ZodNumber;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+/** A parsed `LayoutFileSchema` value. */
 export type LayoutFile = z.infer<typeof LayoutFileSchema>;
 /**
  * `specs/index.json`: the statechart files under the specs root, so a static host can serve the
@@ -240,6 +303,12 @@ export declare const SpecIndexSchema: z.ZodObject<{
     ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     files: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/** A parsed `SpecIndexSchema` value. */
 export type SpecIndex = z.infer<typeof SpecIndexSchema>;
+/**
+ * Patterns for the paths of statechart spec files: `atlas.yaml`, `machine.yaml|json` and `*.machine.yaml|json`,
+ * `*.scxml`, `journeys.yaml`, `known-issues.md`, `open-questions.md` and `*.layout.json`, in any directory.
+ */
 export declare const STATECHART_FILE_PATTERNS: RegExp[];
+/** Whether a spec-relative path (using `/`) matches `STATECHART_FILE_PATTERNS`. */
 export declare function isStatechartFile(path: string): boolean;

package/dist/schema/src/spec.js

@@ -1,17 +1,41 @@
+/**
+ * @module Statechart spec schemas
+ *
+ * Zod schemas for the files in a specs directory: the `meta` a chart's states carry, XState-style machine configs,
+ * `journeys.yaml`, the optional product map `atlas.yaml`, `<chart>.layout.json` and `specs/index.json`, plus the
+ * filename patterns that identify statechart files. They describe what a person writes, so readers validate each
+ * piece on its own and report problems rather than rejecting the whole spec (the visualizer's `parse/spec.ts` does).
+ * The pure subset of statecharts that Atlas executes is documented in `docs/statecharts.md`.
+ *
+ * @see docs/statecharts.md
+ */
 import { z } from 'zod/v4';
 import { ConfidenceSchema, EventKindSchema } from './common.js';
+/**
+ * Version of the spec file formats, currently 1. `LayoutFileSchema` and `SpecIndexSchema` accept only `schemaVersion:
+ * 1`.
+ */
 export const SPEC_SCHEMA_VERSION = 1;
+/**
+ * A state's link to its design: an image (URL or spec-relative path), and optionally where the design lives, such as
+ * a Figma frame.
+ */
 export const DesignLinkSchema = z.object({
     image: z.string().min(1).describe('URL or spec-relative path of a design frame'),
     url: z.string().optional().describe('Where the design lives, for example a Figma frame link'),
     label: z.string().optional()
 });
+/** One Given/When/Then line of a business contract: the keyword, its text, and an optional data table or doc string. */
 export const ContractStepSchema = z.object({
     keyword: z.string().min(1),
     text: z.string(),
     table: z.array(z.array(z.string())).optional(),
     docString: z.string().optional()
 });
+/**
+ * A business rule copied from its authoritative `source` as exact Given/When/Then steps, carried in a state's
+ * `meta.contracts`.
+ */
 export const BusinessContractSchema = z.object({
     id: z.string().min(1),
     name: z.string().min(1),
@@ -47,12 +71,20 @@ export const StateMetaShape = {
         .record(z.string(), z.string())
         .describe('Chart-level: time events and the span each one jumps, for example "5 minutes"')
 };
+/** `StateMetaShape` with every field optional: the `meta` of a state or of a whole chart. */
 export const StateMetaSchema = z.object(StateMetaShape).partial();
+/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`. */
 export const TransitionTargetSchema = z.union([
     z.string().min(1),
     z.object({ target: z.string().min(1) })
 ]);
+/** Kinds of state in the composed map: `atomic`, `compound`, `parallel`, `final`. */
 export const STATE_TYPES = ['atomic', 'compound', 'parallel', 'final'];
+/**
+ * One state of an XState machine config, recursively, restricted to what Atlas reads: nesting, `parallel` and `final`
+ * types, event transitions and `meta`. Guards, actions and the rest of XState are rejected by `atlas lint`, not by
+ * this schema. Emitted as `state-node.schema.json`.
+ */
 export const StateNodeSchema = z.lazy(() => z.object({
     id: z.string().optional(),
     initial: z.string().optional(),
@@ -61,6 +93,10 @@ export const StateNodeSchema = z.lazy(() => z.object({
     states: z.record(z.string(), StateNodeSchema).optional(),
     on: z.record(z.string(), TransitionTargetSchema).optional()
 }));
+/**
+ * A whole chart: its `id`, optional `initial`, `type` and `meta`, and its `states`. The states are `unknown` here;
+ * validate each with `StateNodeSchema`.
+ */
 export const MachineSchema = z.object({
     id: z.string().min(1),
     initial: z.string().optional(),
@@ -68,6 +104,11 @@ export const MachineSchema = z.object({
     meta: StateMetaSchema.optional(),
     states: z.record(z.string(), z.unknown())
 });
+/**
+ * One curated journey in `journeys.yaml`: the business events replayed in order from the initial state, the states it
+ * must end in, and an optional owner and tour flag. `atlas lint` replays every journey, and `atlas run` runs each as
+ * its own path.
+ */
 export const JourneySchema = z.object({
     description: z.string().optional(),
     events: z.array(z.string()),
@@ -75,9 +116,17 @@ export const JourneySchema = z.object({
     owner: z.string().optional(),
     tour: z.boolean().optional().describe('Include in the guided tour')
 });
+/**
+ * `journeys.yaml`: a `journeys` map from journey name to journey. The entries are `unknown` here; validate each with
+ * `JourneySchema`.
+ */
 export const JourneysFileSchema = z.object({
     journeys: z.record(z.string(), z.unknown())
 });
+/**
+ * A product area declared in `atlas.yaml`: its id, display name, description, owner and the spec-relative directories
+ * whose charts belong to it.
+ */
 export const AtlasContextSchema = z.object({
     id: z.string().min(1),
     name: z.string().optional(),
@@ -85,6 +134,10 @@ export const AtlasContextSchema = z.object({
     owner: z.string().optional(),
     directories: z.array(z.string()).optional().describe('Spec-relative directories holding its charts')
 });
+/**
+ * A hand-off declared in `atlas.yaml` between two product areas: the ids of the area it `from` and `to`, and the
+ * event that passes control.
+ */
 export const AtlasHandOffSchema = z.object({
     from: z.string().min(1),
     to: z.string().min(1),
@@ -119,6 +172,10 @@ export const SpecIndexSchema = z.object({
     ref: z.string().nullable().optional(),
     files: z.array(z.string())
 });
+/**
+ * Patterns for the paths of statechart spec files: `atlas.yaml`, `machine.yaml|json` and `*.machine.yaml|json`,
+ * `*.scxml`, `journeys.yaml`, `known-issues.md`, `open-questions.md` and `*.layout.json`, in any directory.
+ */
 export const STATECHART_FILE_PATTERNS = [
     /(^|\/)atlas\.ya?ml$/,
     /(^|\/)([\w.-]+\.)?machine\.(ya?ml|json)$/,
@@ -128,6 +185,7 @@ export const STATECHART_FILE_PATTERNS = [
     /(^|\/)open-questions\.md$/,
     /(^|\/)[\w.-]+\.layout\.json$/
 ];
+/** Whether a spec-relative path (using `/`) matches `STATECHART_FILE_PATTERNS`. */
 export function isStatechartFile(path) {
     return STATECHART_FILE_PATTERNS.some((pattern) => pattern.test(path));
 }

package/dist/server/src/app.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module The Atlas server application
+ *
+ * `createAtlasServer` is the whole of a project's Atlas as one `fetch` handler: the API results are uploaded to, the live
+ * report every viewer is shown, the gate, the server-sent event stream, the specs and runs the viewer reads, the viewer
+ * itself, and the server's own description (`/api/openapi.json`, `/llms.txt`). What it knows lives in its backends (by
+ * default a folder on its own disk), so replacing it loses nothing. Every error leaves as an RFC 9457 problem document; every
+ * route is described in `openapi.ts` (a test holds the two together).
+ *
+ * @see docs/server.md
+ */
+import { type BackendInput } from '../../reports/src/compose.js';
+import type { LayerHeader } from '../../reports/src/evidence-types.js';
+import { ReportIndex } from '../../reports/src/report-index.js';
+import type { ResolvedToken } from './config.js';
+import { EventHub } from './events.js';
+/** What the server is built from: its `backends` (read together) and which one takes uploads (`write`), `tokens`, the built `site`, the report's filters (`include`, `outlineBranch`), `limits`, timings, `log`, and `now` for tests. */
+export type AtlasServerOptions = {
+    /** Every backend, read together. */
+    readonly backends: readonly BackendInput[];
+    /** The id of the backend uploads go to. */
+    readonly write: string;
+    readonly tokens?: readonly ResolvedToken[];
+    readonly anonymousRead?: boolean;
+    /** The built viewer. Without it, only the API is served. */
+    readonly site?: string;
+    readonly outlineBranch?: string;
+    readonly include?: (layer: LayerHeader) => boolean;
+    readonly refreshMs?: number;
+    readonly limits?: {
+        readonly maxObjectMiB?: number;
+        readonly maxJsonMiB?: number;
+        readonly maxStreams?: number;
+    };
+    readonly heartbeatMs?: number;
+    readonly log?: (line: Record<string, unknown>) => void;
+    readonly now?: () => number;
+    readonly version?: string;
+    /** Extra runtime configuration written into the page. */
+    readonly page?: Record<string, unknown>;
+};
+/** A running server application: `fetch` (serve requests), `index` (the live report), `events` (the viewers), `routes` (what it answers), `ready` (the first pass over the backends is done) and `close`. */
+export type AtlasServer = {
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly index: ReportIndex;
+    readonly events: EventHub;
+    /** The routes the server answers, as registered: what the OpenAPI document must describe (a test holds the two together). */
+    readonly routes: readonly {
+        readonly method: string;
+        readonly path: string;
+    }[];
+    /** Resolves when the first pass over the backends is done. */
+    readonly ready: Promise<void>;
+    /** Stop refreshing and end every live connection. */
+    close(): void;
+};
+/**
+ * The whole of a project's Atlas on one process: the API that results are uploaded to, the live report every
+ * viewer is shown, and the viewer itself. All of it is under one host, `/api` for the API and `/` for the page.
+ * What it knows lives in its backends (by default a folder on its own disk), so replacing it loses nothing.
+ */
+export declare function createAtlasServer(options: AtlasServerOptions): AtlasServer;