@crvouga/atlas 0.10.2 → 0.12.0

package/docs/server.md

@@ -255,6 +255,7 @@ with `format=markdown` (or `Accept: text/markdown`), and takes the project prefi
 | Every test, a summary (by status, environment, producer, domain), insights (failing, flaky, slowest) and facets | `GET /api/reports/tests` |
 | Only some: `q` (all words), `status` (or `flaky`), `environment`, `producer`, `domain`, `spec`, `tag`, `run`; `sort`, `offset`, `limit` | `GET /api/reports/tests?status=failed&environment=ios` |
 | One test: every recorded result (status, duration, environment, branch, commit, CI run), newest first | `GET /api/reports/tests/history?key=<key>` |
+| Why Specs, domains and counts disagree: ambiguous spec paths, shared domains, gaps, a reconciliation of the totals | `GET /api/reports/tests/health` |
 | The runs that recorded the report (by CI run URL, else branch and commit) | `GET /api/reports/runs` |
 | Every test one run recorded | `GET /api/reports/runs/detail?key=<run key>` |
 
@@ -267,6 +268,13 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
   `stats` describes its recorded history: pass rate, flips, whether it is flaky and why (it passed and failed on the
   same commit, passed only after a retry, or its producer said so), durations (avg, p50, p95, min, max, last), runs
   and branches.
+- The **health** document explains the numbers instead of adding one. It keeps spec files, defined specs, specs with an
+  executed test, tests, outlines, examples and per-environment observations apart, and walks from the Specs total to
+  the Tests total. Two spec paths are one logical spec only when a mapping says so
+  (`?root=<from>><to>`, for example `?root=%3Especs/` to put `checkout/cart.feature` under `specs/`); similar paths
+  are reported as ambiguous and never merged, and a similar title is never an identity. Give a check the label
+  `outline` to say which scenario outline an example belongs to. A domain shared by nearly every spec is flagged, but
+  explicit domain metadata always stays authoritative. The document only reads: it changes no status.
 - The server keeps the newest 100 results of every test (progress reported as `running` is not history) and every run's last result per test, in memory, as layers
   arrive; it is rebuilt from the layers on restart. History never changes a result.
 - Without a published spec set, tests are grouped under the specs their layers recorded (`specs[]`: path, domain,
@@ -318,6 +326,8 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `DELETE /api/projects/{project}/store/{key}` | publish | Remove a scratch object. |
 | `GET /api/reports/tests` | read | Every test, with insights, facets and history statistics. |
 | `GET /api/projects/{project}/reports/tests` | read | Every test, with insights, facets and history statistics. |
+| `GET /api/reports/tests/health` | read | Why specs, domains and counts disagree. |
+| `GET /api/projects/{project}/reports/tests/health` | read | Why specs, domains and counts disagree. |
 | `GET /api/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/projects/{project}/reports/tests/history` | read | One test and every result recorded for it. |
 | `GET /api/reports/runs` | read | The runs that recorded the report. |

package/docs/ui.md

@@ -0,0 +1,142 @@
+# Viewer UI conventions
+
+Read this before changing the Atlas viewer or settings UI. React and Mantine are the design system.
+Use the installed version in `package.json` (currently 9.7.3) and its [official documentation](https://mantine.dev/).
+Look up unfamiliar interactions before writing them; component props and compound components usually solve them.
+
+## One setup
+
+- `packages/visualizer/src/ui/theme.tsx` owns the only theme and `AtlasThemeProvider`.
+- Both `src/main.tsx` (reports) and `src/admin/main.tsx` (settings) use that provider and Mantine's styles.
+- Keep Atlas's blue navigation, neutral surfaces, system typography, and light color scheme. Outcome colors
+  come from `statusColor`: green passed, red failed, orange flaky, blue running, gray unknown/unrun.
+  Always accompany color with text or a named status mark. Unknown evidence must never look passed.
+- The theme darkens the existing Mantine outcome scales and muted text to meet small-text contrast requirements. Use the default sizes, radii, font sizes, shadows and variants. Defaults belong in the theme, not in features.
+  The spacing vocabulary is Mantine's `xs`, `sm`, `md`, `lg`, `xl`.
+
+## Compose directly
+
+Use `AppShell` for persistent navigation, `Container size="xl"` for report pages (`md` for settings),
+`Stack` for vertical flow, `Group` for horizontal flow, and `SimpleGrid` for responsive metrics/forms.
+Page headers contain a `Title order={1}`, descriptive `Text c="dimmed"`, then the page's controls.
+Use `Title order={2}` for sections and `order={3}` for subsections; do not choose heading sizes per page.
+
+Use Mantine components directly. Do not add wrappers for ordinary buttons, inputs, cards, menus, or dialogs.
+Shared product compositions include `SpecHeader`, `ResultRow`, `StatusMark`, `Origin`, `Stage`, and `TestDetail`:
+they preserve evidence semantics, provenance, URL selection, or playback behavior.
+
+- Primary action: `Button variant="filled"`. Secondary: default `Button` (light). Quiet: `variant="subtle"`.
+  Destructive action: `color="red"`. Icon-only action: `ActionIcon` with an `aria-label`, usually a `Tooltip`.
+- Inputs: Mantine inputs with a visible `label`, `description` when needed, and `error` for validation.
+  Use `NativeSelect` for small native option lists; keep form values controlled. Settings validation and
+  authorization stay on the server; its optional JSON editor also validates with the shared schema.
+- Use `Menu` for navigation menus, `Popover` for view options, `Drawer` for sources/test details,
+  `Modal` for modal content, and `Spotlight` for search. Let Mantine own dismissal, focus and keyboard behavior.
+  When an action opens a drawer from a popover, close and disable the parent popover during the drawer's lifetime;
+  return focus to its persistent trigger. Do not fix overlapping focus traps by raising z-index values.
+- Use `Tabs` for view modes and `Accordion` for disclosure. URL-backed selections stay in the existing router.
+- Render typed router links with Mantine's `renderRoot={props => <Link {...props} ... />}`.
+  This keeps route/search type inference and native navigation semantics.
+- Use `Table` in `Table.ScrollContainer` for wide evidence, with column headers. Long lists must retain
+  `Bounded`/show-more controls. Do not fetch unopened results' recordings eagerly.
+- Loading: named `Loader`/`Skeleton` or explicit text with `role="status"`. Error: `Alert color="red"` and
+  a retry when possible. Empty: descriptive `Text` and a relevant action. Use built-in loading/disabled states.
+- Spec overview links use a centered `Group`: status, flexible title/folder, then outcome and time. Keep gaps
+  explicit with theme spacing; stack metadata on narrow screens instead of crowding the title.
+
+## Executable spec source
+
+`SourceText` is the common source reader for Gherkin, Quint, DMN/XML, Alloy, OpenSLO/YAML and statechart
+XML/JSON/YAML. Show it expanded near the top of document pages; preserve indentation, comments and the
+complete file. Do not replace source with a trimmed snapshot. Mantine `CodeHighlightTabs` supplies file
+labels, line numbers, horizontal scrolling and copying. The full file is expanded by default. Native
+collapse/expand controls can limit long files to 70vh; the Recorded results action jumps to the existing
+results section and moves keyboard focus there. Keep scenario selection,
+filters, traces, decision tables and model declaration links working alongside the source.
+
+`ui/highlight.ts` owns the one lazy Shiki adapter. It imports only the supported grammars and caches the
+engine. The shared source composition installs that adapter when source is displayed; the Mantine theme
+and component defaults still live only in `ui/theme.tsx`. Quint/Alloy grammar sources and licenses live in
+[`ui/grammars/README.md`](../packages/visualizer/src/ui/grammars/README.md). Unknown formats remain plain
+text, and parse failures must leave the source visible. Syntax highlighting never means a spec passed.
+
+## Icons and notation marks
+
+Use named imports from `@tabler/icons-react` for all UI glyphs. The icon package supplies SVG paths;
+Mantine still supplies every control and interaction. Use size 16 for compact inline glyphs and size 20
+for standalone actions, with `aria-hidden="true"` when the adjacent text or control names the action.
+Do not draw SVG icons, use Unicode glyphs as buttons, or add another icon library. Mantine's built-in
+icons are fine. Keep textual keyboard shortcuts and path separators as text.
+
+`SpecLogo` maps every `SpecKind` to a bundled SVG mark, used in navigation and page headers. Keep the
+visible notation label; marks are decorative. Sources, licenses and the DMN notation-mark choice are in
+[`spec-logos/README.md`](../packages/visualizer/src/components/spec-logos/README.md). Add a sourced SVG
+and update this mapping when adding a format. Brand artwork preserves upstream colors independently of
+Atlas's theme. SVG data plots and statechart arrow markers are geometry, not handcrafted UI icons.
+
+## Accessibility and responsive behavior
+
+The shell collapses its index below Mantine's `md` breakpoint; its named Burger toggles mobile navigation.
+Navigation closes after choosing a destination. Use responsive props and the theme's breakpoints; no custom
+media-query system. Let controls wrap, use one form column on mobile, and keep dialogs inside the viewport.
+Wide tables scroll inside their container. Native video/audio controls remain available.
+
+Preserve labels, status announcements, keyboard shortcuts, selected states, meaningful headings and focus
+restoration. Mantine respects reduced motion through the central theme. Avoid nested interactive controls.
+Never rely on color alone, remove focus outlines, or hide an important action only to make a layout fit.
+
+## Styling policy and exceptions
+
+Default custom CSS: zero. First try Mantine defaults, central defaults, variants, props, layout components,
+and theme tokens. Do not add Tailwind, Radix, another design system, CSS modules, custom token scales,
+inline styles, or `styles` objects for ordinary UI. Document a concrete functional limitation here before
+adding an exception; `scripts/ui-architecture.test.ts` checks these boundaries in the normal test suite.
+
+The central List Styles API adjustment makes item labels fill the available width, including Mantine's column wrappers;
+List has no full-width label prop. This keeps all report rows usable without feature styles.
+
+The narrowly scoped exceptions are:
+
+1. **Interactive statechart graph:** React Flow and ELK provide graph layout, pan/zoom, edges and minimap,
+   which Mantine does not supply. Graph nodes and controls use Mantine. `src/map/map.module.css` only covers
+   SVG strokes, graph handles, edge-label geometry and graph selection/dimming. The two edge-label transforms
+   and node dimensions are computed by the layout engine, not visual design tokens.
+2. **Captured evidence:** native video/audio and sandboxed iframes render recorded bytes. HTML snapshots use
+   the existing isolated shadow tree and intrinsic phone coordinates; their captured styles never style Atlas.
+   Recorded click markers and intrinsic image/video dimensions are evidence coordinates, not UI spacing.
+3. **Public compatibility APIs:** `solid-js` and `@tanstack/solid-query` remain dependencies of existing
+   report-library entry points. They render no Atlas screen. Do not import them into the viewer or add Solid UI.
+4. **Syntax rendering:** Shiki is the syntax engine behind Mantine's official code-highlight adapter,
+   not a second component system. Its token styles and escaped HTML are generated by the highlighter.
+   The supported Shiki line transformer supplies the existing Quint `line-N` navigation anchors.
+   No feature CSS, handcrafted code controls or custom syntax color theme is introduced.
+5. **Consumer test fixture:** `examples/todo/app` is the app Atlas tests and records, not an Atlas screen.
+   Its intentionally separate implementation and selectors are test inputs; the overhaul does not restyle it.
+
+## Inventory and migration boundary
+
+| Area | Screens/interactions | Mantine composition |
+| --- | --- | --- |
+| Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
+| Project home | Tests/runs tabs, metrics, search, status/environment/domain filters, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, Button, Accordion |
+| Test detail | Current outcomes, statistics, duration graph, history, artifacts, recording | Drawer, Table, Badge, Alert, Stage |
+| Specs | All six existing kinds, overview/index, Gherkin rules/scenarios/examples, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Table, CodeHighlightTabs, ResultRow |
+| Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
+| Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
+| Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |
+| Search/help | Ranked and semantic search, shortcut help, recording shortcuts | Spotlight, Modal, Kbd |
+| Administration | Token access, storage backends/write destination, live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
+
+The hash routes (`/`, `/chart/$chartId`, `/specs/$kind`), query contracts, project scoping, streaming,
+report APIs and data adapters remain the migration boundary. `/admin` still serves an independent document:
+it lazily bundles the shared React settings entry once, so API-only servers do not need a prebuilt viewer.
+
+## Checks
+
+Run `bunx tsc --noEmit -p packages/visualizer`,
+`bun test --cwd packages/visualizer --preload ./tests/preload.ts tests`,
+`bun test scripts/ui-architecture.test.ts`, `bun run client:build`, then `bun run docs` and `bun run docs:check`.
+Before pushing, run the full repository checks from `AGENTS.md`, including package build and consumer smoke
+when dependencies change. DOM tests use the same `AtlasThemeProvider` with Mantine's supported `env="test"`.
+Use semantic/product selectors, not Mantine's private class names. Inspect real desktop and narrow layouts,
+menus, dialogs, complex evidence and settings in the browser; do not describe a DOM test as a visual audit.

package/docs/workspaces.md

@@ -0,0 +1,130 @@
+# Atlas in agent IDEs
+
+This guide is for developing **this repository** in Superset, super.engineering or Orca. A consumer
+project should install Atlas from npm and follow [integrating](integrating.md) instead.
+
+## Start from any terminal
+
+Install the Bun version named by `packageManager` in [package.json](../package.json), then run these
+commands from the repository root. Setup requires no tokens, copied `.env`, Docker or external services.
+
+```sh
+bun run workspace:setup
+bun run workspace:run
+```
+
+Open the `Atlas server ready:` URL printed in the Run terminal. It serves the real API and hot-reloading
+viewer together; `/admin` opens settings. A fresh node starts empty. Publish real results to the printed
+`ATLAS_STORE` address using the existing [report commands](reference/reports.md).
+
+For UI work with populated specs, statecharts, failures and recordings, run the separate examples target:
+
+```sh
+bun run workspace:preview
+```
+
+This viewer uses `examples/todo/specs` and the existing example-evidence adapter. It does not seed or
+alter the real server's data. It has no server administration interface. Existing example run files are
+shown when present; setup does not run browsers, model checkers or generate recordings. To create fresh
+example recordings, use the existing `example:run` command and [statechart guide](statecharts.md).
+
+## Shared commands
+
+| Command | Behavior |
+| --- | --- |
+| `bun run workspace:setup` | Check the pinned Bun and install with `--frozen-lockfile`; safe to repeat. |
+| `bun run workspace:run` | Run the real node and viewer; repeat the frozen install before starting. |
+| `bun run workspace:preview` | Run the populated examples viewer; repeat the same setup first. |
+| `bun run workspace:status` | Print live URLs, mode and readiness as JSON; omit private control credentials. |
+| `bun run workspace:stop` | Stop both targets owned by this checkout; retain all reports. |
+| `bun run workspace:stop server` | Stop only the API/viewer target. `preview` selects only examples. |
+| `bun run workspace:check` | Run documentation, types, tests, package/client builds and consumer smoke. |
+
+`run` and `preview` stay in the foreground so the IDE owns their lifetime and displays their output.
+Ctrl+C or an IDE Stop closes the owned server and its child process. Teardown uses a random private
+control capability stored in `.atlas-workspace/`; it never kills a PID from a file or uses `pkill`.
+If the owned development child does not finish after five seconds, only that child is terminated.
+Stopping an unrelated IDE, agent, checkout or application is outside these scripts' scope.
+
+## Workspace isolation and ports
+
+The API/viewer tries port 5180, and examples try 5181. If that default is busy, the OS supplies a free
+port. Read `workspace:status` instead of assuming a URL. An explicit `--port`, `ATLAS_PORT`, or `PORT`
+(in that priority order) is strict: conflicts fail and never connect publishers to a different node.
+`--port 0` requests a free port explicitly.
+
+```sh
+bun run workspace:run --port 5280
+bun run workspace:status
+```
+
+Everything binds to `127.0.0.1`. For remote workspaces, use the IDE's port forwarding. Reports and server
+settings stay in this checkout's `.atlas-data/`; live runtime leases stay in `.atlas-workspace/`.
+Keep both directories private to each worktree. Do not share `node_modules`, `.atlas-data/`,
+`.atlas-workspace/` or caches across checkouts with different dependencies. Frozen installs use Bun's
+download cache without linking one worktree's dependency tree to another.
+
+Two simultaneous starts cannot claim the same target's runtime lease. A hard kill may leave metadata:
+run `workspace:stop` before restarting. It removes a stale lease only when its owner PID is gone; if the
+PID is still alive but the control endpoint cannot authenticate, investigate that owner rather than
+assuming it is safe to stop. No reports or settings are deleted by teardown.
+
+## Superset
+
+[`.superset/config.json`](https://github.com/crvouga/atlas/blob/main/.superset/config.json) wires workspace creation to setup, the Run button
+to the real node/viewer, and teardown to stop. Superset discovers listening ports; the conventional
+ports are labelled in [ports.json](https://github.com/crvouga/atlas/blob/main/.superset/ports.json). Automatically chosen ports still appear
+in its port panel. Use the examples command in a second terminal when needed. Personal lifecycle
+overrides belong in ignored `.superset/config.local.json`.
+
+Superset's Run command resolves from the main repository's configuration. Commit the configuration
+and scripts together before expecting another workspace's Run button to discover them. See the
+[official lifecycle guide](https://docs.superset.sh/setup-teardown-scripts) and
+[port management](https://docs.superset.sh/ports).
+
+## super.engineering
+
+[`.super.engineering/config.json`](https://github.com/crvouga/atlas/blob/main/.super.engineering/config.json) defines **Atlas** (default),
+**Viewer examples** and **Checks** in the Run controls. Each server target's Stop command affects only
+that target; deletion stops both. Shared commands expose **Atlas URLs**, **Check Atlas** and a
+**Review Atlas UI** prompt. The prompt uses the current agent's configured provider and does not
+launch a team or change model settings.
+
+Use the documented CLI to inspect or invoke the same definitions:
+
+```sh
+sc project scripts check --json
+sc project scripts run Atlas --json
+sc project scripts status --json
+sc project scripts stop Atlas --json
+```
+
+Edit shared script configuration with `sc project scripts set ... --scope repo`, and shared commands
+with `sc commands ... --scope shared`. Preserve other entries and unknown configuration keys. See
+[project config and scripts](https://super.engineering/docs/project-config-and-scripts/).
+
+## Orca
+
+[`orca.yaml`](https://github.com/crvouga/atlas/blob/main/orca.yaml) uses the supported `scripts.setup` and `scripts.archive` hooks. Agents
+wait for setup. The first default tab is reserved for the agent; the second starts Atlas. Tab commands
+may start alongside setup, so Run repeats the frozen install before importing application dependencies.
+Orca's normal shared-script trust and setup-policy settings still apply. No `scripts.run` key is
+invented: Orca starts the app through the terminal template.
+
+Keep **Shared + Local** or **Shared only** enabled for repository hooks, and approve the shared config
+in Orca when it offers its trust prompt. These are user-owned controls. For existing workspaces,
+run the shared Bun commands in a terminal; default tabs are created for new workspaces. See the
+[official `orca.yaml` reference](https://www.onorca.dev/docs/model/orca-yaml).
+
+## Agent workflow
+
+Read `AGENTS.md`, then use `workspace:status` to discover this checkout's live app. Run the server for
+API, settings, upload and streaming changes; use examples for populated UI review. Read [UI conventions](ui.md)
+before changing screens. Keep report/schema/permission contracts intact, and report what the browser and
+checks actually verified. Do not launch other agents, change IDE permissions or install global IDE tooling
+as a side effect of setup. `workspace:check` is an on-demand verification target, never a creation hook.
+
+The lifecycle regression suite (`bun test scripts/workspace.test.ts`) checks fresh directories with spaces,
+repeatable setup, strict ports, separate stores, authenticated ownership and independent shutdown.
+Real IDE boot verification additionally needs that IDE installed and available; a passing configuration
+test alone does not prove the IDE started a new workspace.