@unotest/protocol 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -68,6 +68,18 @@ declare const STEPS_FILE = "steps.jsonl";
 /** mtime-updated periodically by the runner; viewer treats run as
  *  `interrupted` after `> 30s` without mtime change (per design-v0). */
 declare const HEARTBEAT_FILE = "heartbeat";
+/** Per-day derived index: one JSON line per run, inside the day's shard
+ *  directory (`<runsRoot>/YYYY/MM/DD/_day.jsonl`). Derived from the run
+ *  manifests beside it — losing it costs a rebuild, never data. */
+declare const DAY_INDEX_FILE = "_day.jsonl";
+/** Directory of per-scenario derived indexes, at the runs root. Holds one
+ *  JSONL per scenario plus `_latest.json`. Named with a leading underscore
+ *  so it sorts away from `YYYY` shards and can never collide with one. */
+declare const SCENARIOS_INDEX_DIR = "_scenarios";
+/** One entry per scenario: its most recent run, status and failure
+ *  streak. Feeds the activity-bar badge and the "failing now" section,
+ *  neither of which may cost a history scan. */
+declare const SCENARIOS_LATEST_FILE = "_latest.json";
 /** Captured child-process stdout when run is spawned by viewer. */
 declare const STDOUT_FILE = "stdout.log";
 /** Captured child-process stderr when run is spawned by viewer. */
@@ -148,1043 +160,1192 @@ declare function makeRunId(name: string): string;
  *  random suffix appended by `makeRunId`. */
 declare function sanitizeRunIdSegment(name: string): string;
 
-/** Filesystem-unsafe characters in a collection name — see
- *  `FS_UNSAFE_NAME_RE` for the block-list rationale. Kept as a named
- *  re-export for the published surface. */
-declare const COLLECTION_NAME_FORBIDDEN_RE: RegExp;
-/** Validate a collection name. Returns `null` on success, or a
- *  human-readable reason string on failure. Shared by the viewer-server
- *  writer (authoritative) and any client form (pre-flight) so both sides
- *  agree on what's acceptable. Pure function — safe to bundle in the
- *  browser. */
-declare function validateCollectionName(name: string): string | null;
-/** Parsed YAML collection manifest from `unotest/e2e/_collections/*.yaml`.
- *  Per design-v0/decisions.md, Phase 1 keeps the manifest minimal — only
- *  `description` and `scenarios`. No `parallel`/`env`/`retry`/`timeout`
- *  fields until a real use-case appears. */
-interface CollectionMeta {
-    /** Filename stem (single source of truth — no `name:` field inside YAML). */
-    name: string;
-    /** Project-relative path to the `.yaml` file. */
-    path: string;
-    /** Optional one-line description from the YAML's top-level `description:`. */
-    description: string | null;
-    /** Scenario names referenced in the YAML's `scenarios:` array. Names are
-     *  scenario-meta `name` values (file stem relative to `e2e/`). Orphan
-     *  references (scenario file missing) are NOT filtered out — the viewer
-     *  surfaces them as red entries with «file not found» tooltip; running
-     *  a collection skips orphans with a warning, not blocks. */
-    scenarios: string[];
-}
+/** Epoch millis encoded in a runId, or null when the id does not follow
+ *  `makeRunId`'s shape. Callers must handle null rather than guess — an
+ *  id we cannot place has no shard. */
+declare function runIdStartedAt(runId: string): number | null;
+/** `YYYY/MM/DD` (UTC) for a timestamp. POSIX separators — these are
+ *  project-relative artifact paths, not OS paths. */
+declare function shardPathForTimestamp(ms: number): string;
+/** `YYYY/MM/DD` for a runId, or null when the id carries no timestamp. */
+declare function shardPathForRunId(runId: string): string | null;
+/** Project-relative directory of one run: `<runsRoot>/YYYY/MM/DD/<runId>`.
+ *  Null for an id we cannot place — callers decide whether that is a skip
+ *  or an error, but nobody may invent a location. */
+declare function runDirFor(runsRoot: string, runId: string): string | null;
+/** Thrown when a runId carries no usable timestamp and the caller cannot
+ *  proceed without one. Writers hit this only if they were handed an id
+ *  they did not make. */
+declare class UnplaceableRunIdError extends Error {
+    constructor(runId: string);
+}
+/** `runDirFor` for callers that own the id and therefore know it parses.
+ *  Throws instead of returning null so a writer can never quietly invent
+ *  a location and split one run across two layouts. */
+declare function requireRunDirFor(runsRoot: string, runId: string): string;
+/** Project-relative runs root for a target: `unotest/.runs<suffix>`. */
+declare function projectRunsRoot(suffix?: string): string;
+/** Project-relative directory of one run, shard included. The single
+ *  place that knows how a run id becomes a path — every writer and reader
+ *  goes through here, so the layout cannot drift between them. */
+declare function projectRunDirFor(runId: string, suffix?: string): string;
+/** Day directory: `<runsRoot>/YYYY/MM/DD`. */
+declare function shardDirFor(runsRoot: string, ms: number): string;
+/** Walk day-shard paths backwards from `fromMs`, newest first. Used by
+ *  listing (fill a page from the newest days) and by retention (drop days
+ *  older than the window) — both want days in order, neither wants to
+ *  readdir the whole tree. */
+declare function shardDaysDescending(runsRoot: string, fromMs: number, count: number): Generator<string>;
 
-/** Run a single scenario by its `name` (file stem under `e2e/`). */
-interface ScenarioRunRequest {
-    kind: "scenario";
-    /** Scenario `name` — file stem relative to `unotest/e2e/`. */
-    scenario: string;
-    /** Run with browser visible (web) / device window visible (mobile).
-     *  Adapter maps this to the runner's preferred env / arg. */
-    headed?: boolean;
-    /** Spawn with debugger enabled (breakpoints from
-     *  `unotest/.debugger.json` + inline override). */
-    debug?: boolean;
-    /** Inline breakpoint override as `"line:col"` strings. Only honored
-     *  when `debug=true`. */
-    breakpoints?: string[];
+/** Which kind of locator the in-page picker overlay should retarget to and
+ *  what DSL snippet to emit on pick. `locator` → an interactive element →
+ *  `click(<loc>)`; `text`/`visibility` → any named/interactive element →
+ *  `assertText`/`assertVisible`. See docs/recoder/plan.md. */
+type PickerMode = "locator" | "text" | "visibility";
+interface DbgCommandStep {
+    id: string;
+    cmd: "step";
 }
-/** Run a collection — the runner's CLI orchestrates scenarios inside.
- *  Viewer doesn't see the per-scenario subprocesses; it sees one direct
- *  child plus the artifacts each scenario writes to its own `.runs/`
- *  dir, linked to this parent via `parentRunId` in their manifests. */
-interface CollectionRunRequest {
-    kind: "collection";
-    /** Collection `name` — filename stem under `_collections/`. */
-    collection: string;
-    /** Forward to each child scenario. */
-    headed?: boolean;
-    /** Worker count for parallel scenario execution. Default `1`
-     *  (serial). The adapter passes it to the CLI; the runner enforces. */
-    workers?: number;
-    /** Stop on first failure. Default `false` (continue-on-fail). */
-    bail?: boolean;
+interface DbgCommandContinue {
+    id: string;
+    cmd: "continue";
 }
-/** Open a live AUTHORING-HOLD session (collaborative model, U1/U3): a
- *  headed shared browser + draft stay open with NO running test; the human
- *  and agent co-author the draft. Runs `unotest-web author <scenario>`. */
-interface AuthoringRunRequest {
-    kind: "authoring";
-    /** Scenario `name` — file stem relative to `unotest/e2e/`. A stub is
-     *  created if the file doesn't exist yet. */
-    scenario: string;
-    /** Authoring is visible by default — the human must see the live browser. */
-    headed?: boolean;
+interface DbgCommandPause {
+    id: string;
+    cmd: "pause";
 }
-/** Discriminated union of every run-shape the viewer can request. */
-type RunRequest = ScenarioRunRequest | CollectionRunRequest | AuthoringRunRequest;
-/** All `kind` literals — useful for switch-completeness checks and for
- *  adapter `supportedKinds` lists. */
-type RunKind = RunRequest["kind"];
-
-declare const RUN_MANIFEST_FILE = "manifest.json";
-interface RunManifest {
-    /** Format-version of this manifest. Bump only on breaking schema
-     *  changes — additive optional fields don't require it. Starts at 1. */
-    schemaVersion: 1;
-    /** Identifies which RunRequest variant produced this run. */
-    kind: RunKind;
-    /** Original (un-sanitized) `ref` from the request — scenario `name`
-     *  for `kind:"scenario"`, collection `name` for `kind:"collection"`.
-     *  The `runId` directory uses a sanitized form; this carries the
-     *  human-readable original. */
-    ref: string;
-    /** Run-id of the parent collection-run when this is a child scenario
-     *  spawned inside a collection. Absent for top-level scenario-runs
-     *  and for collection-runs themselves. */
-    parentRunId?: string;
-    /** Adapter `name` that produced this run (`"@unotest/web"`,
-     *  `"@unotest/mobile"`). Lets the viewer pick rendering details for
-     *  runner-specific bundle contents without runner branches in core
-     *  logic. */
-    adapter: string;
-    /** Wallclock at runner start. Distinct from the first event's `t`
-     *  (which may have leading delay for adapter setup). */
-    startedAt: number;
-    /** Opt-in artifact-capture flags as resolved from the runner's env at
-     *  start (`UNOTEST_CONSOLE` / `UNOTEST_NETWORK`). Recorded here so the
-     *  viewer can tell "capture was disabled" apart from "capture was on but
-     *  the run aborted before writing console.json / network.json" — a
-     *  distinction the mere presence of those files can't make. Optional: runs
-     *  produced before this field existed simply omit it, and the viewer falls
-     *  back to a file-presence heuristic. */
-    capture?: {
-        console: boolean;
-        network: boolean;
-    };
+interface DbgCommandSetBp {
+    id: string;
+    cmd: "set-bp";
+    line: number;
+    col: number;
 }
-
-/** Snapshot file holding entry + every helper source that was loaded. */
-declare const RUN_SOURCES_FILE = "sources.json";
-interface RunSources {
-    /** Project-root-relative posix path of the entry scenario file,
-     *  e.g. `unotest/e2e/foo.test.js`. Also a key in `files`. */
-    entry: string;
-    /** Project-root-relative posix path → full source text. Includes the
-     *  entry file and every helper file pulled in by the loader. */
-    files: Record<string, string>;
+interface DbgCommandClearBp {
+    id: string;
+    cmd: "clear-bp";
+    line: number;
+    col: number;
 }
-
-/** The argv/env builder for a specific runner CLI. Pure functions —
- *  no spawning, no fs access. The viewer owns the actual subprocess
- *  lifecycle; the adapter merely tells it WHAT to spawn. */
-interface IRunnerAdapter {
-    /** Human-readable identity for logs and error messages
-     *  (e.g. `"@unotest/web"`). NOT used for control flow — viewer
-     *  must not branch on this. */
-    readonly name: string;
-    /** Per-target artifact suffix — the single axis that scopes EVERY
-     *  per-target filesystem name (M-10): `""` for web (the first target
-     *  keeps the bare names), `"-mobile"` for mobile, `"-unity"` for a
-     *  future unity runner. Derived names (via `paths.ts` helpers):
-     *  scenario tree `e2e<suffix>`, run artifacts `.runs<suffix>`, debug
-     *  logs `.debug<suffix>`, breakpoints `.debugger<suffix>.json`, env
-     *  overlays `.env<suffix>`. The viewer scopes discovery/runs/
-     *  breakpoints by the active target's suffix so no folder name is
-     *  ever hardcoded in viewer source (OCP: a new target just declares
-     *  its suffix). */
-    readonly suffix: string;
-    /** Debug-toolbar capabilities the viewer gates its controls on (OCP — a
-     *  new target just declares what it supports; viewer never branches on the
-     *  runner name). See `DebugCapabilities`. */
-    readonly debug: DebugCapabilities;
-    /** Which `RunRequest.kind` values this adapter can handle. Viewer
-     *  rejects unsupported kinds with `UnsupportedRunKindError` before
-     *  building argv. */
-    readonly supportedKinds: ReadonlyArray<RunKind>;
-    /** Absolute path to the bin entry that should be spawned with the
-     *  current Node binary: `spawn(process.execPath, [resolveBin(), ...buildArgs(req)])`.
-     *  Throws if the runner package isn't installed reachably from the
-     *  viewer's project root. */
-    resolveBin(): string;
-    /** Argv to pass after the bin path. Pure — depends only on `req`.
-     *  Example for web: `["e2e", "smoke", "--debug", "--break", "10:4"]`. */
-    buildArgs(req: RunRequest): string[];
-    /** Environment overrides merged on top of `process.env` by the
-     *  caller. Pure — no `process.env` reads here. Example for web:
-     *  `{ UNOTEST_HEADED: "1" }`. Worker-isolation env
-     *  (`UNOTEST_WORKER_INDEX/COUNT`) is NOT the adapter's
-     *  responsibility — see `D-C4` in the collections plan. */
-    buildEnv(req: RunRequest): NodeJS.ProcessEnv;
-    /** Argv (after the bin path) that starts this runner's LONG-LIVED
-     *  app-under-test holder (M-12/M-16) — the process that prepares the
-     *  app (web: spawns the dev server; mobile: boots devices + installs
-     *  the build), emits `AppServerEvent` JSON lines on stdout, and tears
-     *  down what it owns when terminated. Absent → the runner has no
-     *  app-launch capability and the viewer hides the feature for this
-     *  target. Example: `["app-server"]`. */
-    appServerArgs?(): string[];
-    /** Path inputs the App panel renders for this target (M-17) — each
-     *  spec becomes an input + file-picker button whose value is saved
-     *  into the target's env file (`envKey`). The viewer stays
-     *  platform-blind: extensions/labels are vocab the adapter owns
-     *  (mobile iOS: `.app`; a future Android entry adds `.apk`). */
-    appServerPickers?(): readonly AppPathPickerSpec[];
-    /** Host-OS requirement for THIS runner. The viewer resolves it against
-     *  the server's real `process.platform` and gates the switcher: an
-     *  unsupported host shows `reason` and blocks activation (e.g. mobile is
-     *  macOS-only — iOS Simulator is Apple-licensed). Absent → runs on any
-     *  host (web). OCP: a new platform-bound runner just declares this; the
-     *  viewer never hardcodes which target needs which OS. */
-    readonly host?: HostRequirement;
-    /** Structured environment preflight ("doctor") — what must be installed/
-     *  configured for this runner to actually run here (mobile: Xcode +
-     *  simulators; web: Node + a system browser). Pure-ish but MAY shell out
-     *  to probe the host, hence async; the viewer invokes it on demand (a
-     *  "Check" button), never on every switch. Absent → nothing to verify
-     *  beyond the package being installed. The viewer renders the returned
-     *  list verbatim (severity + message + fix `detail`) — it owns no runner
-     *  vocab. */
-    doctor?(ctx: DoctorContext): Promise<DoctorCheck[]>;
+interface DbgCommandAbort {
+    id: string;
+    cmd: "abort";
 }
-/** Severity of a single {@link DoctorCheck}. `error` = the runner cannot
- *  run until fixed; `warning` = may work, review; `ok` = satisfied. */
-type CheckSeverity = "ok" | "warning" | "error";
-/** One environment-preflight result. The single shape both `@unotest/web`
- *  and `@unotest/mobile` already produce from their `runEnvironmentChecks`
- *  — lifted here so the viewer (and any future surface) consumes one type,
- *  not a per-runner copy. */
-interface DoctorCheck {
-    /** Short check id, e.g. `"xcode-cli"`, `"Node.js version"`. */
-    name: string;
-    severity: CheckSeverity;
-    /** One-line outcome, e.g. `"Xcode CLI tools at /Applications/…"`. */
-    message: string;
-    /** Human-readable remediation when not `ok` — a command or concrete
-     *  next step. Surfaced under the message in the UI. */
-    detail?: string;
+/** Start (or, if already active, re-mode) the in-page picker on the live
+ *  paused page. `execute=false` (default) is capture-only: clicks are
+ *  swallowed, never run — picks just record a locator/assertion.
+ *  `execute=true` turns the overlay into a Playwright-style recorder: real
+ *  clicks / typing / selects RUN on the page and are recorded as DSL actions
+ *  (`click`/`fill`/`press`/`selectOption`/`check`). In execute mode the
+ *  `text`/`visibility` modes still record an assertion without running the
+ *  click (swap mode to drop an assertion mid-flow). */
+interface DbgCommandPickerStart {
+    id: string;
+    cmd: "picker:start";
+    mode: PickerMode;
+    execute?: boolean;
 }
-/** What an adapter's {@link IRunnerAdapter.doctor} receives. Kept as an
- *  object so new context (e.g. a target's env file) can be added without
- *  touching every implementor's signature. */
-interface DoctorContext {
-    /** Absolute path to the project root (the dir containing `unotest/`) —
-     *  for project-aware checks (mobile reads `package.json` to hint RN/Expo). */
-    projectRoot: string;
+/** Tear down the picker overlay. */
+interface DbgCommandPickerStop {
+    id: string;
+    cmd: "picker:stop";
 }
-/** A runner's host-OS requirement. The viewer compares `platforms` against
- *  `process.platform`; a mismatch shows `reason` and blocks the switch. */
-interface HostRequirement {
-    /** `process.platform` values this runner can execute on, e.g. `["darwin"]`
-     *  for iOS. */
-    platforms: ReadonlyArray<NodeJS.Platform>;
-    /** Shown when the current host isn't in `platforms` — one sentence the
-     *  user reads in the switcher / setup panel. */
-    reason: string;
-}
-/** What a runner's debug session supports — drives which debug-toolbar
- *  controls the viewer shows. A target that lacks a capability gets the
- *  control hidden (no dead buttons). */
-interface DebugCapabilities {
-    /** In-page locator picker / recorder — click an element in the SHARED,
-     *  inspectable page to insert its locator/assertion (web). Runners that
-     *  drive an opaque device without a clickable DOM (mobile via WDA) set this
-     *  false → the viewer hides the picker cluster (Capture/Execute +
-     *  target/A/eye). NOTE: distinct from `attach` — the wheel + agent join
-     *  apply to mobile too. */
-    picker: boolean;
-    /** Collaborative attach: a second client (the MCP agent) can join the live
-     *  debug session and co-drive it, coordinated by the control wheel. True for
-     *  web (shared browser) AND mobile (shared device via WDA). The viewer shows
-     *  the wheel / "who's driving" badge when set. */
-    attach: boolean;
-    /** A failure-pause is resumable as a RETRY of the failed step (mobile D-17:
-     *  the user fixes the device/app state, Continue re-executes the same
-     *  statement). When false (web: resume past a failure means "skip & pretend
-     *  it passed"), the viewer hides Continue/Step on a failure-pause so the
-     *  only action is Stop. */
-    resumeFromFailure: boolean;
-}
-/** One path-input row in the viewer's App panel (M-17). */
-interface AppPathPickerSpec {
-    /** Env var the picked path is saved to (e.g. `"APP_PATH"`). Routed to
-     *  the target's env file by the viewer's variables API (M-11). */
-    envKey: string;
-    /** Selectable leaf extensions (lowercase, with dot). macOS `.app`
-     *  bundles are directories — the file browser treats a matching dir
-     *  as a selectable leaf. */
-    extensions: readonly string[];
-    /** Human label rendered above the input (e.g. `"iOS app bundle"`). */
-    label: string;
-}
-/** Thrown by the viewer when a `RunRequest.kind` isn't in the
- *  adapter's `supportedKinds`. The exception filter maps to HTTP 400
- *  with the kind name + adapter name in the message. */
-declare class UnsupportedRunKindError extends Error {
-    constructor(kind: RunKind, adapterName: string);
+/** On-demand: capture the current page outline (what the picker hit-tests
+ *  against) and write it to `picker-snapshot.txt`. Lets the viewer's Snapshot
+ *  tab show / refresh the snapshot without arming the picker. Cheap — runs
+ *  only when the user opens/refreshes the tab (the outline is expensive on
+ *  huge pages, so it is never captured on every pause). */
+interface DbgCommandSnapshot {
+    id: string;
+    cmd: "snapshot";
 }
-/** Thrown by the viewer when the configured runner package can't be
- *  located on disk. Message names the package + how to install. */
-declare class RunnerAdapterNotFoundError extends Error {
-    constructor(packageName: string, hint: string);
+/** The DSL line a recorded action / pick renders to. Mirrors the in-page
+ *  recorder's verbs. `locator` → bare locator; `assertText`/`assertVisible`
+ *  → assertions; the rest → Playwright-style actions. */
+type RecordedActionKind = "locator" | "assertText" | "assertVisible" | "click" | "fill" | "press" | "selectOption" | "check" | "uncheck";
+/** Agent-driven, ref-safe record (collaborative authoring). The agent picks
+ *  an element by `ref` (from a snapshot of the SHARED page) + an action; the
+ *  runner resolves `ref→locator` (`RefResolver`) and emits a `locator:picked`
+ *  event the viewer inserts — so the agent NEVER hand-writes a locator. Same
+ *  resolution/insertion pipeline as the human's in-page picker. */
+interface DbgCommandRecord {
+    id: string;
+    cmd: "record";
+    ref: string;
+    action: RecordedActionKind;
+    /** Typed/selected value for `fill` / `selectOption`. */
+    value?: string;
+    /** Key for `press` (e.g. "Enter", "Control+A"). */
+    key?: string;
+    /** Expected text for `assertText` (else the element's textContent is used). */
+    text?: string;
+    /** Where the viewer drops the line. Default `append` (agent records a flow). */
+    placement?: "cursor" | "append";
 }
-/** Thrown by the viewer when `unotest.config.*` doesn't declare a
- *  `runner:` field. Surfaces what packages exist so the user can
- *  pick. */
-declare class RunnerNotConfiguredError extends Error {
-    constructor(message: string);
+/** Collaborative control token (Slice 3). Sets who may act on the shared
+ *  page: `agent` lets the agent record; `human` (default) blocks the agent.
+ *  Written by the viewer (Take control button) or the agent (take_wheel). */
+interface DbgCommandWheel {
+    id: string;
+    cmd: "wheel";
+    owner: "agent" | "human";
 }
-
-/** Parsed scenario metadata from the mandatory header lines
- *  (per design-v0/decisions.md, "Test source format"):
- *
- *      // id-<kebab-slug>
- *      // <human title>
- *      // #<6-hex-color>
- *      function test_<...>() { ... }
- *
- *  All three lines are required; a file without a complete header is
- *  rejected by the discovery service as parse-error (no legacy fallback). */
-interface ScenarioMeta {
-    /** Slug from `// id-<slug>`. Stable test identity across rename. */
+/** Evaluate a DSL locator STRING against the live (paused or running) page and
+ *  report what it matches — count, the N a trailing .first()/.last()/.nth()
+ *  collapses, and per-match identity — via a `probe:result` event. The runner
+ *  parses `locator` with the SAME DSL parser the agent's `check_locator` uses,
+ *  so agent and human probe identically. READ-ONLY (never acts on the page),
+ *  so it is intentionally NOT wheel-gated: any client may probe at any time. */
+interface DbgCommandProbe {
     id: string;
-    /** Human-readable title from `// <text>`. */
-    title: string;
-    /** Color identifier from `// #RRGGBB`. Used only in tab headers as a
-     *  thin colored strip — NOT a status signal. */
-    color: string;
-    /** File stem relative to `unotest/e2e/`, dirs as slashes.
-     *  Examples: `smoke-welcome`, `auth/signin-flow`.
-     *  Source-of-truth identity for CLI invocations and tab keys. */
-    name: string;
-    /** Project-relative path to the source file. */
-    path: string;
+    cmd: "probe";
+    /** Locator exactly as written in a test, e.g.
+     *  getByRole('row').filter({hasText: 'Uma Quinn'}).first(). */
+    locator: string;
+    /** Cap on the number of match details returned (default 20). */
+    limit?: number;
 }
+type DbgCommand = DbgCommandStep | DbgCommandContinue | DbgCommandPause | DbgCommandSetBp | DbgCommandClearBp | DbgCommandAbort | DbgCommandPickerStart | DbgCommandPickerStop | DbgCommandSnapshot | DbgCommandRecord | DbgCommandWheel | DbgCommandProbe;
+type DbgCommandKind = DbgCommand["cmd"];
 
-/** Response of `GET /api/scenarios`. Folders are listed independently of
- *  the scenarios so an EMPTY directory under `unotest/e2e/` still renders
- *  in the tree (the folder list isn't inferred from scenario paths). */
-interface ScenariosPayload {
-    scenarios: ScenarioMeta[];
-    /** Directory paths relative to `unotest/e2e/`, posix-separated, any
-     *  depth (e.g. `auth`, `auth/signup`, `autopark`). Excludes reserved
-     *  subtrees (`_helpers`, `_collections`) and any `_`/`.`-prefixed dir. */
-    folders: string[];
+interface ProbeMatch {
+    /** 0-based position among the locator's matches. */
+    index: number;
+    role?: string;
+    name?: string;
+    /** Trimmed/clipped textContent of the element. */
+    text?: string;
+    testId?: string;
+    href?: string;
+    /** Currently visible? Non-waiting check (a match can exist but be off-screen). */
+    visible: boolean;
 }
-/** Filesystem-unsafe characters in a single path segment — see
- *  `FS_UNSAFE_NAME_RE` (it includes both path separators, so a valid
- *  segment is guaranteed to be ONE level). Kept as a named re-export for
- *  the published surface. */
-declare const SEGMENT_NAME_FORBIDDEN_RE: RegExp;
-/** Validate a single scenario-file stem or folder name. Returns `null` on
- *  success, else a human-readable reason. Shared by the viewer-server
- *  writer (authoritative) and the client form (pre-flight) so both agree.
- *  Pure — safe to bundle in the browser.
- *
- *  Rejects: empty, `.`/`..`, `.`-prefix (hidden), `_`-prefix (reserved for
- *  `_helpers`/`_collections`/templates), path separators + FS-unsafe
- *  punctuation + control chars. */
-declare function validateSegmentName(name: string): string | null;
-
-/** Session profile — the kind of process a tab spawns. Mirrored by the
- *  viewer's TerminalStore.TermKind. */
-type TerminalKind = "local" | "claude" | "codex";
-interface TerminalSpawnMessage {
-    type: "spawn";
-    id: string;
-    kind: TerminalKind;
-    cols: number;
-    rows: number;
+interface ProbePinned {
+    /** The terminal index op that collapsed a multi-match to a single element. */
+    op: "first" | "last" | "nth";
+    /** How many elements the chain matched BEFORE the terminal op — i.e. how many
+     *  the .first()/.last()/.nth() silently picked from. `ofCount > 1` flags an
+     *  index op hiding ambiguity. */
+    ofCount: number;
 }
-interface TerminalDataMessage {
-    type: "data";
-    id: string;
-    /** Raw bytes the user typed, forwarded to the PTY stdin. */
-    data: string;
+interface ProbeResult {
+    /** Human-readable chain echo. NOT a selector. */
+    chain: string;
+    /** Elements the full chain matches. */
+    count: number;
+    /** Present only when the chain ends in first/last/nth. */
+    pinned?: ProbePinned;
+    /** Details of up to the requested limit of matches. */
+    matches: ProbeMatch[];
+    /** True count before truncation (equal to `count`). */
+    totalCount: number;
+    truncated: boolean;
+    /** Actionable hints: nothing matched, hidden ambiguity, truncation, stale ref. */
+    warnings: string[];
 }
-interface TerminalResizeMessage {
-    type: "resize";
-    id: string;
-    cols: number;
-    rows: number;
+
+/** Terminal outcome reported by the runner via `run:finished`. */
+type RunOutcome = "completed" | "failed" | "aborted" | "interrupted";
+/** Scenario-level run-id. Format opaque to consumers; treat as string. */
+type RunId = string;
+/** Common fields on every event. */
+interface RunArtifactBase {
+    /** Wallclock timestamp (Date.now()) at emit. */
+    t: number;
 }
-interface TerminalCloseMessage {
-    type: "close";
-    id: string;
+interface RunStartedEvent extends RunArtifactBase {
+    kind: "run:started";
+    /** Same as the `<runId>` directory name; included for self-describing
+     *  events when reassembled out-of-band. */
+    runId: RunId;
+    /** Scenario `name` (file stem relative to `e2e/`). */
+    scenario: string;
 }
-type TerminalClientMessage = TerminalSpawnMessage | TerminalDataMessage | TerminalResizeMessage | TerminalCloseMessage;
-interface TerminalOutputMessage {
-    type: "output";
-    id: string;
-    /** Raw PTY stdout/stderr bytes to write to the xterm instance. */
-    data: string;
+interface StepStartedEvent extends RunArtifactBase {
+    kind: "step:started";
+    /** Project-root-relative posix path of the file this step lives in
+     *  (entry or a helper). Matches a key in the run's `sources.json`.
+     *  The viewer slices the source text by `line` from the snapshot. */
+    file: string;
+    /** Line number of the DSL call in the source file (1-indexed). */
+    line: number;
+    /** Column number (1-indexed since 0.11 — the DSL lexer's token
+     *  columns; earlier releases emitted 0-indexed columns for
+     *  word-initial statements). */
+    col: number;
 }
-interface TerminalExitMessage {
-    type: "exit";
-    id: string;
-    exitCode: number | null;
+interface StepOkEvent extends RunArtifactBase {
+    kind: "step:ok";
+    /** Wall-clock duration of the step that just finished. */
+    durationMs: number;
 }
-/** Spawn failure (e.g. `claude` not on PATH) reported to the tab so it can
- *  print a friendly line instead of silently dying. */
-interface TerminalErrorMessage {
-    type: "error";
-    id: string;
-    message: string;
+interface StepFailEvent extends RunArtifactBase {
+    kind: "step:fail";
+    /** Human-readable error message (single line preferred). */
+    error: string;
+    /** Error class name (e.g. `"AssertionError"`, `"LocatorError"`,
+     *  `"TimeoutError"`). Lets the viewer's `ErrorCard` show a typed
+     *  pill instead of a generic "Error" label. Optional because some
+     *  thrown errors lack a meaningful class name. */
+    errorName?: string;
+    /** Project-relative path to a Playwright trace zip, if captured. */
+    trace?: string;
 }
-type TerminalServerMessage = TerminalOutputMessage | TerminalExitMessage | TerminalErrorMessage;
-/** The `ws` adapter routes inbound messages by an `event` envelope; both
- *  directions use this single event name on `/ws/terminal`. */
-declare const TERMINAL_WS_EVENT = "terminal";
-
-type VariableCategory = "secret" | "app" | "runner";
-/** User-facing runner-config knobs documented in `unotest/.env`. Single source
- *  of truth for "is this name our config?" — drives the viewer's "Runner
- *  config" group and the add-variable dropdown.
- *
- *  NOT listed (so they never surface as user config): launcher-injected
- *  run-control vars (UNOTEST_RUN_ID, UNOTEST_PARENT_RUN_ID,
- *  UNOTEST_BUSY_SCENARIOS, UNOTEST_WORKER_*), session-log internals
- *  (UNOTEST_SESSION_LOG_*), and path bootstrap (UNOTEST_DIR,
- *  UNOTEST_PROJECT_ROOT, UNOTEST_CONFIG, UNOTEST_VIEWER_NO_OPEN). A user would
- *  never put those in `unotest/.env`. */
-declare const RUNNER_CONFIG_KEYS: ReadonlySet<string>;
-/** True when `name` is a key the runner consumes as its own configuration. */
-declare function isRunnerConfigKey(name: string): boolean;
-/** Group a variable for the viewer. Secrecy from the source file; runner-vs-app
- *  from the owned-key set. */
-declare function categorizeVariable(v: {
-    name: string;
-    source: "env" | "secrets";
-}): VariableCategory;
-/** An external scenario variable is referenced by a bare UPPER_SNAKE
- *  identifier (`APP_BASE_URL`). App / secret names must match this to be
- *  resolvable from a scenario; runner keys are validated against the set
- *  above instead. Convention only — no value inspection. */
-declare function isExternalVarName(name: string): boolean;
-
-/** Parse `KEY=VALUE` env-file CONTENT into a plain record. Pure — the
- *  caller does the fs read. Blank lines and `#` comments are skipped;
- *  balanced surrounding single/double quotes are stripped; keys not
- *  matching `[A-Za-z_][A-Za-z0-9_]*` are ignored. Shared by the web and
- *  mobile runners' layered env loaders (M-11) so both parse `.env` files
- *  identically. */
-declare function parseEnvContent(raw: string): Record<string, string>;
-/** Quote on write only when the value would otherwise be ambiguous (spaces,
- *  `#`, quotes, `=`, backslash, leading backtick, or newlines). Plain tokens
- *  stay unquoted. Mirrors the viewer env-dotenv serializer. */
-declare function serializeEnvValue(value: string): string;
-/** Active (non-commented) assignment keys present in env-file `content`.
- *  Used to detect duplicates / cross-file shadowing before an add. */
-declare function envKeys(content: string): Set<string>;
-/**
- * Insert `KEY=VALUE` into env-file `content`. With `sectionLabel`, the line
- * goes into the first `# --- <label> --- ` divider section — after the last
- * assignment there (or its description comments if it has no vars yet). The
- * label is matched as a whole word against DIVIDER lines only, so prose
- * comments are never mistaken for a section. No such section → it is created
- * at end-of-file. With no label the line is appended. Does NOT dedup — reject
- * duplicates before calling.
- */
-declare function insertEnvVar(content: string, key: string, value: string, sectionLabel?: string): string;
-/**
- * Remove the assignment line for `key`, leaving every comment and other line
- * untouched (we do not guess which comments "belong" to the key). Returns the
- * new content and whether anything was removed.
- */
-declare function removeEnvVar(content: string, key: string): {
-    content: string;
-    removed: boolean;
-};
-
-/** Which group the user is adding into. App/runner → `.env`, secret →
- *  `.secrets`. Mirrors VariableCategory as an INPUT (the user's choice). */
-type VariableKind = VariableCategory;
-interface AddVariablePlanInput {
-    name: string;
-    kind: VariableKind;
-    /** Current text of `unotest/.env` (`""` if absent). */
-    envContent: string;
-    /** Current text of `unotest/.secrets` (`""` if absent). */
-    secretsContent: string;
+interface ScreenshotEvent extends RunArtifactBase {
+    kind: "screenshot";
+    /** Project-relative path to the PNG (under `unotest/.runs/<runId>/screenshot/`). */
+    path: string;
+    /** Step identity for captures bound to a specific step (per-step
+     *  screenshots under `UNOTEST_STEP_SCREENSHOTS`). Same semantics as
+     *  `StepStartedEvent` — the viewer joins on `line:col`. Absent for
+     *  unbound captures (`screenshot()` DSL calls); consumers may fall
+     *  back to attributing those to the step in flight at emit time. */
+    file?: string;
+    line?: number;
+    col?: number;
 }
-type VariablePlanError = {
-    ok: false;
-    code: "duplicate" | "invalid-name" | "unknown-runner-key";
-    message: string;
-};
-type AddVariablePlan = {
-    ok: true;
-    target: "env" | "secrets";
-    sectionLabel?: string;
-    warnings: string[];
-} | VariablePlanError;
-/**
- * Decide where a new variable goes and what to warn about — or reject it.
- * Reject reasons: duplicate key in the target file; a non-UPPER_SNAKE app/
- * secret name (a scenario could never reference it); a runner key not in the
- * owned-config allowlist. Warnings (non-fatal): secret shadowing a same-named
- * `.env` var, or vice-versa.
- */
-declare function planAddVariable(input: AddVariablePlanInput): AddVariablePlan;
-/**
- * Warning to show after deleting `name` from the file: if the shell
- * environment still defines it with a DIFFERENT value, it will keep
- * resolving from there (set-if-absent means ambient wins). Comparing values
- * avoids a false positive when `.env` was merely flattened into process.env.
- */
-declare function deleteShadowWarning(name: string, fileValue: string | undefined, ambientValue: string | undefined): string[];
-
-/** A single editor diagnostic. Superset of the `@unotest/dsl`
- *  validator diagnostic: it unifies parse errors, the vocab validator,
- *  and the platform linter behind one shape, tagged by `source`/`rule`
- *  so consumers can theme or filter. Positions are 1-based; a parse
- *  error with no recoverable position falls back to `1:1`. */
-interface DslDiagnostic {
-    severity: "error" | "warning" | "info";
-    /** 1-based line. */
+/** Emitted ONCE after a failing run when the runner has finished writing
+ *  the D-16 failure bundle to disk. Viewer's inspector reads
+ *  `bundlePath` to fetch artifacts (screenshot, semantic DOM, network,
+ *  trace) via `/api/runs/<runId>/asset?path=...`. The bundle directory
+ *  is keyed by its own id (`<scenario>__<isoDate>__<stepIdx>`) under
+ *  `.unotest/failures/`, not under `unotest/.runs/`, because the
+ *  bundle layout pre-dates per-run dirs and is still consumed by the
+ *  agent-fix MCP tools. */
+interface FailureBundleWrittenEvent extends RunArtifactBase {
+    kind: "failure-bundle:written";
+    /** Project-relative path to the bundle directory. */
+    bundlePath: string;
+    /** Project-relative path to the screenshot PNG inside the bundle,
+     *  when tier-2 capture succeeded. */
+    screenshotPath?: string;
+    /** Page URL at the moment of failure (same value captured into the
+     *  bundle's `snapshot.json`/`outline.txt`), for the viewer's ErrorCard. */
+    url?: string;
+}
+interface RunFinishedEvent extends RunArtifactBase {
+    kind: "run:finished";
+    outcome: RunOutcome;
+}
+/** Debugger pause. Reason discriminates:
+ *   - `breakpoint` — executor halted before a statement whose `line:col` is
+ *     in `RunOptions.breakpoints`.
+ *   - `step` — `pauseRequested` flag was set by a `pause` debug command,
+ *     or the run was started in step-mode and just completed a statement.
+ *   - `failure` — executor caught an error and `pauseOnFailure` is true.
+ *
+ *  When the runner is hosting a debug session it also writes a parallel
+ *  `runtime.json` file with the same snapshot. The snapshot is included
+ *  inline here for replay / single-frame consumers that don't want to do a
+ *  separate fs read. */
+interface PausedEvent extends RunArtifactBase {
+    kind: "paused";
+    reason: "breakpoint" | "step" | "failure";
+    /** Project-root-relative posix path of the file the pause point lives
+     *  in (entry or a helper). Matches a key in the run's `sources.json`. */
+    file: string;
     line: number;
-    /** 1-based column. */
-    column: number;
-    /** 1-based end line, when the producer knows the span. */
-    endLine?: number;
-    /** 1-based end column, when the producer knows the span. */
-    endColumn?: number;
-    message: string;
-    /** Stable rule id, e.g. `"validator:unknown-function"`, `"validator:dsl"`,
-     *  a linter rule id, or `"parse"`. */
-    rule: string;
-    /** Which stage produced it — lets the UI group / colour by origin. */
-    source: "parse" | "validate" | "lint";
+    col: number;
+    /** Inline snapshot of the runtime state at the pause point. `vars` is
+     *  per-value JSON-stringified (LocatorValue → "<Locator role=... name=...>"
+     *  human-readable string) and per-var truncated to 4KB to keep the JSONL
+     *  line manageable. `callStack` is outermost→innermost user-function frames. */
+    snapshot?: {
+        vars: Record<string, string>;
+        callStack: {
+            fn: string;
+            file: string;
+            line: number;
+        }[];
+    };
 }
-/** Coarse grouping for a vocab entry — drives completion icons and
- *  ordering. `keyword` covers DSL control-flow / block words (`step`,
- *  `if`, `for`, …); `helper` covers project-defined `flow_*` / mock
- *  helpers surfaced from the workspace. */
-type DslVocabCategory = "action" | "assertion" | "selector" | "chain" | "navigation" | "read" | "wait" | "state" | "storage" | "multi-context" | "sandbox" | "diagnostic" | "escape-hatch" | "keyword" | "helper";
-/** One declared argument of a vocab entry — feeds signature help and
- *  the snippet placeholders in `insertText`. `kind` is the validator's
- *  arg-kind string (`"locatorLike"`, `"stringLike"`, `"number"`,
- *  `"any"`, …); the editor treats it as an opaque label. */
-interface DslVocabArg {
-    label: string;
-    kind: string;
-    required: boolean;
-    /** Literal members when `kind` is `"enum"` — the label alone loses
-     *  them, and consumers (typings generator, completion) need the
-     *  actual values. */
-    enumValues?: readonly string[];
+/** Emitted by the in-page locator picker / action recorder (debug-pause)
+ *  when the user picks an element or performs a recorded action. The runner
+ *  resolved the picked `ref` to a locator (`RefResolver`) and rendered the
+ *  DSL snippet. The viewer inserts `snippet` per `placement`.
+ *  See docs/recoder/plan.md. */
+interface LocatorPickedEvent extends RunArtifactBase {
+    kind: "locator:picked";
+    mode: PickerMode;
+    /** Ready-to-insert DSL line, e.g. a bare locator
+     *  `getByRole("button", {name: "Sign in"})` (locator mode), an assertion
+     *  (`assertText(…)`), or a recorded action (`click(…)`, `fill(…)`). */
+    snippet: string;
+    /** Where the viewer drops the snippet:
+     *  - `cursor` — at the editor's caret (deliberate picks; user-placed).
+     *  - `append` — after the previous recorded line (execute-mode action
+     *    recorder, preserving order). */
+    placement: "cursor" | "append";
+    /** `stable` (testId / role+name / label / …) or `fragile` (css/nth-only).
+     *  Lets the viewer flag brittle picks. */
+    stability: "stable" | "fragile";
 }
-/** A single autocomplete-able item: a vocab function, a DSL keyword, or
- *  a project helper. Serializable — crosses the REST boundary verbatim
- *  and is cached by the browser (the vocab is static per platform). */
-interface DslVocabEntry {
-    name: string;
-    category: DslVocabCategory;
-    args: DslVocabArg[];
-    /** True when the signature accepts extra positional args after the
-     *  declared ones (`shell(cmd, ...args)`, `dbQuery(sql, ...params)`). */
-    variadic?: boolean;
-    /** Return-kind string (`"void"`, `"string"`, `"locator"`, …). */
-    returns: string;
-    /** Snippet body with `${n:label}` placeholders, e.g.
-     *  `click(${1:locator})`. */
-    insertText: string;
-    /** Human-readable signature for hover / signature-help, e.g.
-     *  `getByRole(role, { name?, exact? })`. Richer than the bare arg
-     *  list — includes option-object shape. */
-    signature?: string;
-    /** Prose description (markdown) for hover and the completion info
-     *  panel. */
-    doc?: string;
-    /** Locator capability from the function contract. `"chainableLocator"`
-     *  entries can be chained off a locator (offered after `.`); any value
-     *  other than `"none"` produces a locator (so it fits a `locator`
-     *  argument slot). Absent for keywords / helpers that have no contract. */
-    locatorCapability?: "none" | "locator" | "chainableLocator";
-    /** Where the entry is defined in the USER's project — set for project
-     *  helpers (`flow_*` in `_helpers/`), absent for platform functions,
-     *  which have no source on disk there. Feeds go-to-definition.
-     *  `path` is project-relative posix; `line`/`column` are 1-based. */
-    source?: {
-        path: string;
-        line: number;
-        column: number;
+/** Emitted when execution resumes after a `paused` event. The `by` field
+ *  records which debug command unblocked it — purely informational; the
+ *  next `step:started` event carries the actual line/col. */
+interface ResumedEvent extends RunArtifactBase {
+    kind: "resumed";
+    by: "step" | "continue";
+}
+/** Emitted when the collaborative control token changes owner (Slice 3), so
+ *  the viewer can live-update the "who's driving" badge over WS. */
+interface WheelChangedEvent extends RunArtifactBase {
+    kind: "wheel:changed";
+    owner: "agent" | "human";
+}
+/** Emitted in response to a `probe` debug command: the result of evaluating a
+ *  locator string against the live page. `id` echoes the command's id so the
+ *  client that issued the probe can correlate the reply. READ-ONLY — producing
+ *  it never changed the page. */
+interface ProbeResultEvent extends RunArtifactBase {
+    kind: "probe:result";
+    /** Correlates with the issuing `DbgCommandProbe.id`. */
+    id: string;
+    result: ProbeResult;
+}
+/** A single MCP tool invocation by the agent, surfaced into the session's
+ *  event stream so the human sees — in the viewer's System console — what the
+ *  agent called and how it ended. Emitted ONLY while the MCP server is attached
+ *  to this run (own-browser calls have no session to attach to). Paired:
+ *  `tool:call` at invocation, `tool:result` at completion, correlated by
+ *  `callId`. Read-only telemetry — emitting it never touches the page. */
+interface ToolCallEvent extends RunArtifactBase {
+    kind: "tool:call";
+    /** Correlates with the matching `tool:result` (one MCP call). */
+    callId: string;
+    /** MCP tool name, e.g. "check_locator", "explore_step". */
+    tool: string;
+    /** Arguments as a secret-redacted, length-capped JSON string — NOT the raw
+     *  object. Capped upstream so the line stays a single atomic append. */
+    args: string;
+}
+interface ToolResultEvent extends RunArtifactBase {
+    kind: "tool:result";
+    /** Correlates with the issuing `ToolCallEvent.callId`. */
+    callId: string;
+    tool: string;
+    ok: boolean;
+    durationMs: number;
+    /** Secret-redacted, length-capped preview of the result text. */
+    preview: string;
+    /** Present only when `ok` is false. */
+    error?: {
+        class: string;
+        message: string;
     };
 }
-/** Per-request file context for {@link IDslLanguageService.validate}.
- *  The viewer owns workspace discovery, so it supplies the things the
- *  platform validator can't know on its own. */
-interface DslValidateContext {
-    /** Names of project helpers (`flow_*`, mocks) so their calls are not
-     *  flagged as unknown functions — mirrors how the lint runner
-     *  registers `unotest/e2e/_helpers/`. */
-    helperNames?: readonly string[];
-    /** Whether the source is a scenario or a helper definition file. */
-    fileKind?: "scenario" | "helper";
+/** Discriminated union of every JSONL event the scenario runner emits. */
+type RunArtifact = RunStartedEvent | StepStartedEvent | StepOkEvent | StepFailEvent | ScreenshotEvent | FailureBundleWrittenEvent | PausedEvent | ResumedEvent | LocatorPickedEvent | WheelChangedEvent | ProbeResultEvent | ToolCallEvent | ToolResultEvent | RunFinishedEvent;
+interface CollectionRunStartedEvent extends RunArtifactBase {
+    kind: "collection-run:started";
+    runId: RunId;
+    /** Collection `name` (filename stem). */
+    collection: string;
+    /** Scenario names that will be executed, in order. */
+    scenarios: string[];
 }
-/** The DSL language service a platform exposes to the viewer. Two
- *  concerns only: the static vocabulary (for completion / signature
- *  help) and full source validation (parse + vocab validator + linter,
- *  identical to the platform's own lint gate). */
-interface IDslLanguageService {
-    /** Static, serializable vocabulary for autocomplete and signature
-     *  help. Stable for the lifetime of the process — safe to cache. */
-    getVocab(): DslVocabEntry[];
-    /** Full diagnostics for one source string. Pure with respect to the
-     *  filesystem — all workspace knowledge arrives via `ctx`. */
-    validate(source: string, ctx?: DslValidateContext): DslDiagnostic[];
+interface CollectionScenarioStartedEvent extends RunArtifactBase {
+    kind: "collection-run:scenario-started";
+    /** The scenario-run-id created when this scenario started executing. */
+    scenarioRunId: RunId;
+    scenario: string;
 }
-
-/** A spawned runner process. Structural superset of the bits of a Node
- *  `ChildProcess` the viewer actually consumes — pid for the active-run
- *  snapshot, stdout/stderr for log capture, exit/error for finalize,
- *  kill for abort. Both `child_process` and Electron `utilityProcess`
- *  satisfy this via a thin adapter. */
-interface ILaunchedProcess {
-    /** OS process id, or -1 if the spawn failed to produce one. */
-    readonly pid: number;
-    /** Captured stdout stream, or null when not piped. */
-    readonly stdout: Readable | null;
-    /** Captured stderr stream, or null when not piped. */
-    readonly stderr: Readable | null;
-    /** Register the exit handler. Called once when the process exits. */
-    onExit(cb: (code: number | null, signal: NodeJS.Signals | null) => void): void;
-    /** Register the spawn-error handler (e.g. bin not found). */
-    onError(cb: (err: Error) => void): void;
-    /** Terminate the process. Default signal SIGTERM. */
-    kill(signal?: NodeJS.Signals): void;
+interface CollectionScenarioFinishedEvent extends RunArtifactBase {
+    kind: "collection-run:scenario-finished";
+    scenarioRunId: RunId;
+    scenario: string;
+    outcome: RunOutcome;
+}
+interface CollectionRunFinishedEvent extends RunArtifactBase {
+    kind: "collection-run:finished";
+    outcome: RunOutcome;
 }
-/** Everything the launcher needs to spawn one runner process. The caller
- *  (RunnerService) has already merged the environment and resolved the bin
- *  + argv from the `IRunnerAdapter`; the launcher only decides HOW to run
- *  it. Pure data — no behaviour. */
-interface LaunchSpec {
-    /** Absolute path to the JS bin entry — `IRunnerAdapter.resolveBin()`. */
-    bin: string;
-    /** Argv to pass after the bin — `IRunnerAdapter.buildArgs(req)`. */
-    args: string[];
-    /** Fully-merged environment for the child. */
-    env: NodeJS.ProcessEnv;
-    /** Working directory — the workspace project root. */
-    cwd: string;
+type CollectionRunArtifact = CollectionRunStartedEvent | CollectionScenarioStartedEvent | CollectionScenarioFinishedEvent | CollectionRunFinishedEvent;
+
+/** Run a single scenario by its `name` (file stem under `e2e/`). */
+interface ScenarioRunRequest {
+    kind: "scenario";
+    /** Scenario `name` — file stem relative to `unotest/e2e/`. */
+    scenario: string;
+    /** Run with browser visible (web) / device window visible (mobile).
+     *  Adapter maps this to the runner's preferred env / arg. */
+    headed?: boolean;
+    /** Spawn with debugger enabled (breakpoints from
+     *  `unotest/.debugger.json` + inline override). */
+    debug?: boolean;
+    /** Inline breakpoint override as `"line:col"` strings. Only honored
+     *  when `debug=true`. */
+    breakpoints?: string[];
 }
-/** Spawns the runner JS under a Node-capable runtime. Injected into the
- *  viewer's RunnerService so the spawn mechanism (system Node vs Electron
- *  utilityProcess) is a deployment choice, not baked into the service. */
-interface IProcessLauncher {
-    launch(spec: LaunchSpec): ILaunchedProcess;
+/** Run a collection — the runner's CLI orchestrates scenarios inside.
+ *  Viewer doesn't see the per-scenario subprocesses; it sees one direct
+ *  child plus the artifacts each scenario writes to its own `.runs/`
+ *  dir, linked to this parent via `parentRunId` in their manifests. */
+interface CollectionRunRequest {
+    kind: "collection";
+    /** Collection `name` — filename stem under `_collections/`. */
+    collection: string;
+    /** Forward to each child scenario. */
+    headed?: boolean;
+    /** Worker count for parallel scenario execution. Default `1`
+     *  (serial). The adapter passes it to the CLI; the runner enforces. */
+    workers?: number;
+    /** Stop on first failure. Default `false` (continue-on-fail). */
+    bail?: boolean;
+}
+/** Open a live AUTHORING-HOLD session (collaborative model, U1/U3): a
+ *  headed shared browser + draft stay open with NO running test; the human
+ *  and agent co-author the draft. Runs `unotest-web author <scenario>`. */
+interface AuthoringRunRequest {
+    kind: "authoring";
+    /** Scenario `name` — file stem relative to `unotest/e2e/`. A stub is
+     *  created if the file doesn't exist yet. */
+    scenario: string;
+    /** Authoring is visible by default — the human must see the live browser. */
+    headed?: boolean;
 }
+/** Discriminated union of every run-shape the viewer can request. */
+type RunRequest = ScenarioRunRequest | CollectionRunRequest | AuthoringRunRequest;
+/** All `kind` literals — useful for switch-completeness checks and for
+ *  adapter `supportedKinds` lists. */
+type RunKind = RunRequest["kind"];
 
-/** Contents of `unotest/.viewer.lock`. Written by viewer-server on
- *  startup, removed on graceful shutdown. Stale detection: `process.kill(
- *  pid, 0)` throws ESRCH if PID is dead → lockfile is stale, safe to
- *  overwrite. */
-interface LockFile {
-    /** PID of the viewer-server process. */
-    pid: number;
-    /** Full URL (with port) to reach the viewer. e.g. `http://localhost:5173`. */
-    url: string;
-    /** ISO 8601 timestamp of `pid` start. Used for tie-breaking and stale-age
-     *  heuristics if `kill(pid, 0)` is inconclusive. */
-    startedAt: string;
+/** Lifecycle stage as inferred by the server when listing runs. */
+type RunStatus = "running" | "passed" | "failed" | "aborted" | "interrupted";
+interface RunMeta {
+    runId: RunId;
+    kind: RunKind;
+    /** Scenario `name` (file stem under `e2e/`) for `kind:"scenario"`,
+     *  collection `name` (yaml stem) for `kind:"collection"`. */
+    ref: string;
+    /** Wallclock from the `run:started` event. */
+    startedAt: number;
+    /** Wallclock from the `run:finished` event, or null if still active. */
+    finishedAt: number | null;
+    /** Total wall-clock duration, or null if still running. */
+    durationMs: number | null;
+    /** Status derived from outcome / liveness — `running` while the run's
+     *  heartbeat is fresh and no `run:finished` has landed. */
+    status: RunStatus;
+    /** Terminal outcome from `run:finished`, or null if still running. */
+    outcome: RunOutcome | null;
+    /** Run-id of the parent collection-run when this is a child scenario
+     *  spawned inside one. Absent for top-level scenarios and for
+     *  collection-runs themselves. Populated by the writer from the
+     *  child's `manifest.json`. */
+    parentRunId?: string;
 }
 
-/** Helper file metadata. Helpers live in `unotest/e2e/_helpers/**` as
- *  `snake_case` functions (`signin_as`, `seed_user`, …). The runner
- *  auto-discovers them; no import system in scenarios. */
-interface HelperMeta {
-    /** File stem relative to `_helpers/`, dirs as slashes. */
+/** Bumped when a line's shape changes incompatibly. A file whose header
+ *  carries a different version is discarded and rebuilt rather than
+ *  half-parsed. */
+declare const RUN_INDEX_SCHEMA_VERSION = 2;
+/** How many past outcomes a scenario's rolling window keeps. Twelve is
+ *  enough to see a flake and small enough that the whole field of them
+ *  fits one JSON file. Exported so the fold and everything that renders
+ *  the window agree on one number. */
+declare const SCENARIO_RECENT_WINDOW = 12;
+/** First line of every index JSONL. */
+interface RunIndexHeader {
+    v: number;
+}
+/** One run, as stored in a day index. Identical to what the API returns,
+ *  deliberately: the index exists to avoid recomputing `RunMeta`, so
+ *  storing anything narrower would just force a second read. */
+type RunIndexEntry = RunMeta;
+/** Rolling per-scenario state. `failStreak`, `failingSince` and `recent`
+ *  are the only fields not derivable from a single run — they are folded
+ *  forward run by run, and a rebuild replays the scenario's history to
+ *  restore them. */
+interface ScenarioLatestEntry {
+    lastRunId: string;
+    lastStatus: RunStatus;
+    lastAt: number;
+    /** Wall-clock of the last run, or null if it never finished. */
+    lastDurationMs: number | null;
+    /** Up to {@link SCENARIO_RECENT_WINDOW} past outcomes, OLDEST FIRST.
+     *  Answers the one question a single last status cannot: does this
+     *  test flake. Kept here rather than fetched per scenario because the
+     *  overview needs it for every test at once, and a page request per
+     *  test would be one round trip per mouse movement. */
+    recent: RunStatus[];
+    /** Consecutive failing runs ending at `lastRunId`. Zero when the last
+     *  run passed. Distinguishes "just broke" from "broken for weeks", and
+     *  a value of 1 after green runs is the signature of a flake. */
+    failStreak: number;
+    /** Start of the current failing streak, or null when not failing. */
+    failingSince: number | null;
+}
+interface ScenariosLatest {
+    v: number;
+    scenarios: Record<string, ScenarioLatestEntry>;
+}
+/** Status values that count as a failure for streak purposes. `aborted`
+ *  is excluded: the user stopped it, the test did not fail. */
+declare function isFailingStatus(status: RunStatus): boolean;
+/** Fold one newer run into a scenario's rolling state. Pure so the live
+ *  path and the rebuild path cannot disagree about what a streak is. */
+declare function foldScenarioRun(prev: ScenarioLatestEntry | undefined, run: Pick<RunMeta, "runId" | "status" | "startedAt" | "durationMs">): ScenarioLatestEntry;
+/** Filename for a scenario's index. `encodeURIComponent` because scenario
+ *  refs carry `/` (`big-table/edit-dialog`) and must not become nested
+ *  directories — and because it is reversible, so the ref can be read
+ *  back off the filename without a side table. */
+declare function scenarioIndexFileName(ref: string): string;
+/** Inverse of `scenarioIndexFileName`. */
+declare function scenarioRefFromFileName(fileName: string): string | null;
+
+/** Blob root under the runs root. Leading underscore for the same reason
+ *  as `_scenarios`: derived, internal, and can never be mistaken for a
+ *  `YYYY` shard directory. */
+declare const BLOBS_DIR = "_blobs";
+/** Thrown rather than returning a path built from a malformed hash — a
+ *  writer that guessed here would scatter blobs outside the fanout. */
+declare class InvalidBlobHashError extends Error {
+    constructor(hash: string);
+}
+/** Project-relative path of one blob.
+ *
+ *  `generation` exists because a hardlink count is bounded — ext4 caps an
+ *  inode at 65000 links. A frame present in every run crosses that at
+ *  65k runs, well inside the six months we size for, and `link()` then
+ *  fails with EMLINK. Rather than silently degrading to full copies from
+ *  that point on, the store opens `<hash>~1`, `<hash>~2`, … Each
+ *  generation is an ordinary blob: same bytes, own inode, own link
+ *  budget, and garbage-collected by the same `st_nlink` rule. */
+declare function blobPathFor(runsRoot: string, hash: string, ext: string, generation?: number): string;
+/** The same path relative to the runs root, as POSIX segments. Callers
+ *  holding an OS-absolute root join these themselves rather than pasting
+ *  an absolute path into a POSIX string. */
+declare function blobRelSegmentsFor(hash: string, ext: string, generation?: number): string[];
+/** Convenience over `blobRelSegmentsFor` for POSIX contexts. */
+declare function blobRelPathFor(hash: string, ext: string, generation?: number): string;
+/** Blob root for a runs root — what the garbage collector walks. */
+declare function blobsRootFor(runsRoot: string): string;
+
+/** Filesystem-unsafe characters in a collection name — see
+ *  `FS_UNSAFE_NAME_RE` for the block-list rationale. Kept as a named
+ *  re-export for the published surface. */
+declare const COLLECTION_NAME_FORBIDDEN_RE: RegExp;
+/** Validate a collection name. Returns `null` on success, or a
+ *  human-readable reason string on failure. Shared by the viewer-server
+ *  writer (authoritative) and any client form (pre-flight) so both sides
+ *  agree on what's acceptable. Pure function — safe to bundle in the
+ *  browser. */
+declare function validateCollectionName(name: string): string | null;
+/** Parsed YAML collection manifest from `unotest/e2e/_collections/*.yaml`.
+ *  Per design-v0/decisions.md the manifest stays minimal — `description`,
+ *  `scenarios`, and (since workers-support) `workers`. No `env`/`retry`/
+ *  `timeout` fields until a real use-case appears. */
+interface CollectionMeta {
+    /** Filename stem (single source of truth — no `name:` field inside YAML). */
     name: string;
-    /** Project-relative path to the source file. */
+    /** Project-relative path to the `.yaml` file. */
     path: string;
+    /** Optional one-line description from the YAML's top-level `description:`. */
+    description: string | null;
+    /** Scenario names referenced in the YAML's `scenarios:` array. Names are
+     *  scenario-meta `name` values (file stem relative to `e2e/`). Orphan
+     *  references (scenario file missing) are NOT filtered out — the viewer
+     *  surfaces them as red entries with «file not found» tooltip; running
+     *  a collection skips orphans with a warning, not blocks. */
+    scenarios: string[];
+    /** Optional `workers:` from the YAML — how many scenarios of this
+     *  collection may run concurrently. Integer ≥ 1; `null` when the field
+     *  is absent (callers default to 1 = sequential). A CLI `--workers`
+     *  flag overrides this value for one run. */
+    workers: number | null;
 }
 
-/** Which kind of locator the in-page picker overlay should retarget to and
- *  what DSL snippet to emit on pick. `locator` → an interactive element →
- *  `click(<loc>)`; `text`/`visibility` → any named/interactive element →
- *  `assertText`/`assertVisible`. See docs/recoder/plan.md. */
-type PickerMode = "locator" | "text" | "visibility";
-interface DbgCommandStep {
-    id: string;
-    cmd: "step";
-}
-interface DbgCommandContinue {
-    id: string;
-    cmd: "continue";
+declare const RUN_MANIFEST_FILE = "manifest.json";
+interface RunManifest {
+    /** Format-version of this manifest. Bump only on breaking schema
+     *  changes — additive optional fields don't require it. Starts at 1. */
+    schemaVersion: 1;
+    /** Identifies which RunRequest variant produced this run. */
+    kind: RunKind;
+    /** Original (un-sanitized) `ref` from the request — scenario `name`
+     *  for `kind:"scenario"`, collection `name` for `kind:"collection"`.
+     *  The `runId` directory uses a sanitized form; this carries the
+     *  human-readable original. */
+    ref: string;
+    /** Run-id of the parent collection-run when this is a child scenario
+     *  spawned inside a collection. Absent for top-level scenario-runs
+     *  and for collection-runs themselves. */
+    parentRunId?: string;
+    /** Adapter `name` that produced this run (`"@unotest/web"`,
+     *  `"@unotest/mobile"`). Lets the viewer pick rendering details for
+     *  runner-specific bundle contents without runner branches in core
+     *  logic. */
+    adapter: string;
+    /** Wallclock at runner start. Distinct from the first event's `t`
+     *  (which may have leading delay for adapter setup). */
+    startedAt: number;
+    /** Opt-in artifact-capture flags as resolved from the runner's env at
+     *  start (`UNOTEST_CONSOLE` / `UNOTEST_NETWORK`). Recorded here so the
+     *  viewer can tell "capture was disabled" apart from "capture was on but
+     *  the run aborted before writing console.json / network.json" — a
+     *  distinction the mere presence of those files can't make. Optional: runs
+     *  produced before this field existed simply omit it, and the viewer falls
+     *  back to a file-presence heuristic. */
+    capture?: {
+        console: boolean;
+        network: boolean;
+    };
 }
-interface DbgCommandPause {
-    id: string;
-    cmd: "pause";
+
+/** Snapshot file holding entry + every helper source that was loaded. */
+declare const RUN_SOURCES_FILE = "sources.json";
+interface RunSources {
+    /** Project-root-relative posix path of the entry scenario file,
+     *  e.g. `unotest/e2e/foo.test.js`. Also a key in `files`. */
+    entry: string;
+    /** Project-root-relative posix path → full source text. Includes the
+     *  entry file and every helper file pulled in by the loader. */
+    files: Record<string, string>;
 }
-interface DbgCommandSetBp {
-    id: string;
-    cmd: "set-bp";
-    line: number;
-    col: number;
+
+/** The argv/env builder for a specific runner CLI. Pure functions —
+ *  no spawning, no fs access. The viewer owns the actual subprocess
+ *  lifecycle; the adapter merely tells it WHAT to spawn. */
+interface IRunnerAdapter {
+    /** Human-readable identity for logs and error messages
+     *  (e.g. `"@unotest/web"`). NOT used for control flow — viewer
+     *  must not branch on this. */
+    readonly name: string;
+    /** Per-target artifact suffix — the single axis that scopes EVERY
+     *  per-target filesystem name (M-10): `""` for web (the first target
+     *  keeps the bare names), `"-mobile"` for mobile, `"-unity"` for a
+     *  future unity runner. Derived names (via `paths.ts` helpers):
+     *  scenario tree `e2e<suffix>`, run artifacts `.runs<suffix>`, debug
+     *  logs `.debug<suffix>`, breakpoints `.debugger<suffix>.json`, env
+     *  overlays `.env<suffix>`. The viewer scopes discovery/runs/
+     *  breakpoints by the active target's suffix so no folder name is
+     *  ever hardcoded in viewer source (OCP: a new target just declares
+     *  its suffix). */
+    readonly suffix: string;
+    /** Debug-toolbar capabilities the viewer gates its controls on (OCP — a
+     *  new target just declares what it supports; viewer never branches on the
+     *  runner name). See `DebugCapabilities`. */
+    readonly debug: DebugCapabilities;
+    /** Which `RunRequest.kind` values this adapter can handle. Viewer
+     *  rejects unsupported kinds with `UnsupportedRunKindError` before
+     *  building argv. */
+    readonly supportedKinds: ReadonlyArray<RunKind>;
+    /** Absolute path to the bin entry that should be spawned with the
+     *  current Node binary: `spawn(process.execPath, [resolveBin(), ...buildArgs(req)])`.
+     *  Throws if the runner package isn't installed reachably from the
+     *  viewer's project root. */
+    resolveBin(): string;
+    /** Argv to pass after the bin path. Pure — depends only on `req`.
+     *  Example for web: `["e2e", "smoke", "--debug", "--break", "10:4"]`. */
+    buildArgs(req: RunRequest): string[];
+    /** Environment overrides merged on top of `process.env` by the
+     *  caller. Pure — no `process.env` reads here. Example for web:
+     *  `{ UNOTEST_HEADED: "1" }`. Worker-isolation env
+     *  (`UNOTEST_WORKER_INDEX/COUNT`) is NOT the adapter's
+     *  responsibility — see `D-C4` in the collections plan. */
+    buildEnv(req: RunRequest): NodeJS.ProcessEnv;
+    /** Argv (after the bin path) that starts this runner's LONG-LIVED
+     *  app-under-test holder (M-12/M-16) — the process that prepares the
+     *  app (web: spawns the dev server; mobile: boots devices + installs
+     *  the build), emits `AppServerEvent` JSON lines on stdout, and tears
+     *  down what it owns when terminated. Absent → the runner has no
+     *  app-launch capability and the viewer hides the feature for this
+     *  target. Example: `["app-server"]`. */
+    appServerArgs?(): string[];
+    /** Path inputs the App panel renders for this target (M-17) — each
+     *  spec becomes an input + file-picker button whose value is saved
+     *  into the target's env file (`envKey`). The viewer stays
+     *  platform-blind: extensions/labels are vocab the adapter owns
+     *  (mobile iOS: `.app`; a future Android entry adds `.apk`). */
+    appServerPickers?(): readonly AppPathPickerSpec[];
+    /** Host-OS requirement for THIS runner. The viewer resolves it against
+     *  the server's real `process.platform` and gates the switcher: an
+     *  unsupported host shows `reason` and blocks activation (e.g. mobile is
+     *  macOS-only — iOS Simulator is Apple-licensed). Absent → runs on any
+     *  host (web). OCP: a new platform-bound runner just declares this; the
+     *  viewer never hardcodes which target needs which OS. */
+    readonly host?: HostRequirement;
+    /** Structured environment preflight ("doctor") — what must be installed/
+     *  configured for this runner to actually run here (mobile: Xcode +
+     *  simulators; web: Node + a system browser). Pure-ish but MAY shell out
+     *  to probe the host, hence async; the viewer invokes it on demand (a
+     *  "Check" button), never on every switch. Absent → nothing to verify
+     *  beyond the package being installed. The viewer renders the returned
+     *  list verbatim (severity + message + fix `detail`) — it owns no runner
+     *  vocab. */
+    doctor?(ctx: DoctorContext): Promise<DoctorCheck[]>;
 }
-interface DbgCommandClearBp {
-    id: string;
-    cmd: "clear-bp";
-    line: number;
-    col: number;
+/** Severity of a single {@link DoctorCheck}. `error` = the runner cannot
+ *  run until fixed; `warning` = may work, review; `ok` = satisfied. */
+type CheckSeverity = "ok" | "warning" | "error";
+/** One environment-preflight result. The single shape both `@unotest/web`
+ *  and `@unotest/mobile` already produce from their `runEnvironmentChecks`
+ *  — lifted here so the viewer (and any future surface) consumes one type,
+ *  not a per-runner copy. */
+interface DoctorCheck {
+    /** Short check id, e.g. `"xcode-cli"`, `"Node.js version"`. */
+    name: string;
+    severity: CheckSeverity;
+    /** One-line outcome, e.g. `"Xcode CLI tools at /Applications/…"`. */
+    message: string;
+    /** Human-readable remediation when not `ok` — a command or concrete
+     *  next step. Surfaced under the message in the UI. */
+    detail?: string;
 }
-interface DbgCommandAbort {
-    id: string;
-    cmd: "abort";
+/** What an adapter's {@link IRunnerAdapter.doctor} receives. Kept as an
+ *  object so new context (e.g. a target's env file) can be added without
+ *  touching every implementor's signature. */
+interface DoctorContext {
+    /** Absolute path to the project root (the dir containing `unotest/`) —
+     *  for project-aware checks (mobile reads `package.json` to hint RN/Expo). */
+    projectRoot: string;
 }
-/** Start (or, if already active, re-mode) the in-page picker on the live
- *  paused page. `execute=false` (default) is capture-only: clicks are
- *  swallowed, never run — picks just record a locator/assertion.
- *  `execute=true` turns the overlay into a Playwright-style recorder: real
- *  clicks / typing / selects RUN on the page and are recorded as DSL actions
- *  (`click`/`fill`/`press`/`selectOption`/`check`). In execute mode the
- *  `text`/`visibility` modes still record an assertion without running the
- *  click (swap mode to drop an assertion mid-flow). */
-interface DbgCommandPickerStart {
-    id: string;
-    cmd: "picker:start";
-    mode: PickerMode;
-    execute?: boolean;
+/** A runner's host-OS requirement. The viewer compares `platforms` against
+ *  `process.platform`; a mismatch shows `reason` and blocks the switch. */
+interface HostRequirement {
+    /** `process.platform` values this runner can execute on, e.g. `["darwin"]`
+     *  for iOS. */
+    platforms: ReadonlyArray<NodeJS.Platform>;
+    /** Shown when the current host isn't in `platforms` — one sentence the
+     *  user reads in the switcher / setup panel. */
+    reason: string;
 }
-/** Tear down the picker overlay. */
-interface DbgCommandPickerStop {
-    id: string;
-    cmd: "picker:stop";
+/** What a runner's debug session supports — drives which debug-toolbar
+ *  controls the viewer shows. A target that lacks a capability gets the
+ *  control hidden (no dead buttons). */
+interface DebugCapabilities {
+    /** In-page locator picker / recorder — click an element in the SHARED,
+     *  inspectable page to insert its locator/assertion (web). Runners that
+     *  drive an opaque device without a clickable DOM (mobile via WDA) set this
+     *  false → the viewer hides the picker cluster (Capture/Execute +
+     *  target/A/eye). NOTE: distinct from `attach` — the wheel + agent join
+     *  apply to mobile too. */
+    picker: boolean;
+    /** Collaborative attach: a second client (the MCP agent) can join the live
+     *  debug session and co-drive it, coordinated by the control wheel. True for
+     *  web (shared browser) AND mobile (shared device via WDA). The viewer shows
+     *  the wheel / "who's driving" badge when set. */
+    attach: boolean;
+    /** A failure-pause is resumable as a RETRY of the failed step (mobile D-17:
+     *  the user fixes the device/app state, Continue re-executes the same
+     *  statement). When false (web: resume past a failure means "skip & pretend
+     *  it passed"), the viewer hides Continue/Step on a failure-pause so the
+     *  only action is Stop. */
+    resumeFromFailure: boolean;
 }
-/** On-demand: capture the current page outline (what the picker hit-tests
- *  against) and write it to `picker-snapshot.txt`. Lets the viewer's Snapshot
- *  tab show / refresh the snapshot without arming the picker. Cheap — runs
- *  only when the user opens/refreshes the tab (the outline is expensive on
- *  huge pages, so it is never captured on every pause). */
-interface DbgCommandSnapshot {
-    id: string;
-    cmd: "snapshot";
+/** One path-input row in the viewer's App panel (M-17). */
+interface AppPathPickerSpec {
+    /** Env var the picked path is saved to (e.g. `"APP_PATH"`). Routed to
+     *  the target's env file by the viewer's variables API (M-11). */
+    envKey: string;
+    /** Selectable leaf extensions (lowercase, with dot). macOS `.app`
+     *  bundles are directories — the file browser treats a matching dir
+     *  as a selectable leaf. */
+    extensions: readonly string[];
+    /** Human label rendered above the input (e.g. `"iOS app bundle"`). */
+    label: string;
 }
-/** The DSL line a recorded action / pick renders to. Mirrors the in-page
- *  recorder's verbs. `locator` → bare locator; `assertText`/`assertVisible`
- *  → assertions; the rest → Playwright-style actions. */
-type RecordedActionKind = "locator" | "assertText" | "assertVisible" | "click" | "fill" | "press" | "selectOption" | "check" | "uncheck";
-/** Agent-driven, ref-safe record (collaborative authoring). The agent picks
- *  an element by `ref` (from a snapshot of the SHARED page) + an action; the
- *  runner resolves `ref→locator` (`RefResolver`) and emits a `locator:picked`
- *  event the viewer inserts — so the agent NEVER hand-writes a locator. Same
- *  resolution/insertion pipeline as the human's in-page picker. */
-interface DbgCommandRecord {
-    id: string;
-    cmd: "record";
-    ref: string;
-    action: RecordedActionKind;
-    /** Typed/selected value for `fill` / `selectOption`. */
-    value?: string;
-    /** Key for `press` (e.g. "Enter", "Control+A"). */
-    key?: string;
-    /** Expected text for `assertText` (else the element's textContent is used). */
-    text?: string;
-    /** Where the viewer drops the line. Default `append` (agent records a flow). */
-    placement?: "cursor" | "append";
+/** Thrown by the viewer when a `RunRequest.kind` isn't in the
+ *  adapter's `supportedKinds`. The exception filter maps to HTTP 400
+ *  with the kind name + adapter name in the message. */
+declare class UnsupportedRunKindError extends Error {
+    constructor(kind: RunKind, adapterName: string);
 }
-/** Collaborative control token (Slice 3). Sets who may act on the shared
- *  page: `agent` lets the agent record; `human` (default) blocks the agent.
- *  Written by the viewer (Take control button) or the agent (take_wheel). */
-interface DbgCommandWheel {
-    id: string;
-    cmd: "wheel";
-    owner: "agent" | "human";
+/** Thrown by the viewer when the configured runner package can't be
+ *  located on disk. Message names the package + how to install. */
+declare class RunnerAdapterNotFoundError extends Error {
+    constructor(packageName: string, hint: string);
 }
-/** Evaluate a DSL locator STRING against the live (paused or running) page and
- *  report what it matches — count, the N a trailing .first()/.last()/.nth()
- *  collapses, and per-match identity — via a `probe:result` event. The runner
- *  parses `locator` with the SAME DSL parser the agent's `check_locator` uses,
- *  so agent and human probe identically. READ-ONLY (never acts on the page),
- *  so it is intentionally NOT wheel-gated: any client may probe at any time. */
-interface DbgCommandProbe {
-    id: string;
-    cmd: "probe";
-    /** Locator exactly as written in a test, e.g.
-     *  getByRole('row').filter({hasText: 'Uma Quinn'}).first(). */
-    locator: string;
-    /** Cap on the number of match details returned (default 20). */
-    limit?: number;
+/** Thrown by the viewer when `unotest.config.*` doesn't declare a
+ *  `runner:` field. Surfaces what packages exist so the user can
+ *  pick. */
+declare class RunnerNotConfiguredError extends Error {
+    constructor(message: string);
 }
-type DbgCommand = DbgCommandStep | DbgCommandContinue | DbgCommandPause | DbgCommandSetBp | DbgCommandClearBp | DbgCommandAbort | DbgCommandPickerStart | DbgCommandPickerStop | DbgCommandSnapshot | DbgCommandRecord | DbgCommandWheel | DbgCommandProbe;
-type DbgCommandKind = DbgCommand["cmd"];
 
-interface ProbeMatch {
-    /** 0-based position among the locator's matches. */
-    index: number;
-    role?: string;
-    name?: string;
-    /** Trimmed/clipped textContent of the element. */
-    text?: string;
-    testId?: string;
-    href?: string;
-    /** Currently visible? Non-waiting check (a match can exist but be off-screen). */
-    visible: boolean;
-}
-interface ProbePinned {
-    /** The terminal index op that collapsed a multi-match to a single element. */
-    op: "first" | "last" | "nth";
-    /** How many elements the chain matched BEFORE the terminal op — i.e. how many
-     *  the .first()/.last()/.nth() silently picked from. `ofCount > 1` flags an
-     *  index op hiding ambiguity. */
-    ofCount: number;
-}
-interface ProbeResult {
-    /** Human-readable chain echo. NOT a selector. */
-    chain: string;
-    /** Elements the full chain matches. */
-    count: number;
-    /** Present only when the chain ends in first/last/nth. */
-    pinned?: ProbePinned;
-    /** Details of up to the requested limit of matches. */
-    matches: ProbeMatch[];
-    /** True count before truncation (equal to `count`). */
-    totalCount: number;
-    truncated: boolean;
-    /** Actionable hints: nothing matched, hidden ambiguity, truncation, stale ref. */
-    warnings: string[];
+/** A test that is SUPPOSED to fail: the failure itself is the assertion.
+ *  Its last run being red is the healthy state — and its last run being
+ *  green is the broken one, because the thing it was guarding stopped
+ *  being broken without anyone noticing. */
+declare const EXPECT_FAIL_ANNOTATION = "expect-fail";
+interface ScenarioAnnotations {
+    expectFail: boolean;
+}
+/** True for a line that is an annotation rather than prose or code. Used
+ *  by the header parser to step over annotations while keeping the
+ *  header's "no loose comments" rule for everything else. */
+declare function isAnnotationLine(line: string): boolean;
+/** Read the markers out of a scenario's source. Scans the leading run of
+ *  comments and stops at the first line of code — an `// @expect-fail`
+ *  further down the file is a comment about a step, not about the test. */
+declare function parseScenarioAnnotations(source: string): ScenarioAnnotations;
+
+/** Parsed scenario metadata from the mandatory header lines
+ *  (per design-v0/decisions.md, "Test source format"):
+ *
+ *      // id-<kebab-slug>
+ *      // <human title>
+ *      // #<6-hex-color>
+ *      function test_<...>() { ... }
+ *
+ *  All three lines are required; a file without a complete header is
+ *  rejected by the discovery service as parse-error (no legacy fallback). */
+interface ScenarioMeta {
+    /** Slug from `// id-<slug>`. Stable test identity across rename. */
+    id: string;
+    /** Human-readable title from `// <text>`. */
+    title: string;
+    /** Color identifier from `// #RRGGBB`. Used only in tab headers as a
+     *  thin colored strip — NOT a status signal. */
+    color: string;
+    /** File stem relative to `unotest/e2e/`, dirs as slashes.
+     *  Examples: `smoke-welcome`, `auth/signin-flow`.
+     *  Source-of-truth identity for CLI invocations and tab keys. */
+    name: string;
+    /** Project-relative path to the source file. */
+    path: string;
+    /** The file carries `// @expect-fail` — a red run is this test's
+     *  healthy state, and a green one is the alarm. See
+     *  {@link ./scenario-annotations.ts}. */
+    expectFail: boolean;
 }
 
-/** Terminal outcome reported by the runner via `run:finished`. */
-type RunOutcome = "completed" | "failed" | "aborted" | "interrupted";
-/** Scenario-level run-id. Format opaque to consumers; treat as string. */
-type RunId = string;
-/** Common fields on every event. */
-interface RunArtifactBase {
-    /** Wallclock timestamp (Date.now()) at emit. */
-    t: number;
+/** Response of `GET /api/scenarios`. Folders are listed independently of
+ *  the scenarios so an EMPTY directory under `unotest/e2e/` still renders
+ *  in the tree (the folder list isn't inferred from scenario paths). */
+interface ScenariosPayload {
+    scenarios: ScenarioMeta[];
+    /** Directory paths relative to `unotest/e2e/`, posix-separated, any
+     *  depth (e.g. `auth`, `auth/signup`, `autopark`). Excludes reserved
+     *  subtrees (`_helpers`, `_collections`) and any `_`/`.`-prefixed dir. */
+    folders: string[];
 }
-interface RunStartedEvent extends RunArtifactBase {
-    kind: "run:started";
-    /** Same as the `<runId>` directory name; included for self-describing
-     *  events when reassembled out-of-band. */
-    runId: RunId;
-    /** Scenario `name` (file stem relative to `e2e/`). */
-    scenario: string;
+/** Filesystem-unsafe characters in a single path segment — see
+ *  `FS_UNSAFE_NAME_RE` (it includes both path separators, so a valid
+ *  segment is guaranteed to be ONE level). Kept as a named re-export for
+ *  the published surface. */
+declare const SEGMENT_NAME_FORBIDDEN_RE: RegExp;
+/** Validate a single scenario-file stem or folder name. Returns `null` on
+ *  success, else a human-readable reason. Shared by the viewer-server
+ *  writer (authoritative) and the client form (pre-flight) so both agree.
+ *  Pure — safe to bundle in the browser.
+ *
+ *  Rejects: empty, `.`/`..`, `.`-prefix (hidden), `_`-prefix (reserved for
+ *  `_helpers`/`_collections`/templates), path separators + FS-unsafe
+ *  punctuation + control chars. */
+declare function validateSegmentName(name: string): string | null;
+
+/** Session profile — the kind of process a tab spawns. Mirrored by the
+ *  viewer's TerminalStore.TermKind. */
+type TerminalKind = "local" | "claude" | "codex";
+interface TerminalSpawnMessage {
+    type: "spawn";
+    id: string;
+    kind: TerminalKind;
+    cols: number;
+    rows: number;
 }
-interface StepStartedEvent extends RunArtifactBase {
-    kind: "step:started";
-    /** Project-root-relative posix path of the file this step lives in
-     *  (entry or a helper). Matches a key in the run's `sources.json`.
-     *  The viewer slices the source text by `line` from the snapshot. */
-    file: string;
-    /** Line number of the DSL call in the source file (1-indexed). */
-    line: number;
-    /** Column number (1-indexed since 0.11 — the DSL lexer's token
-     *  columns; earlier releases emitted 0-indexed columns for
-     *  word-initial statements). */
-    col: number;
+interface TerminalDataMessage {
+    type: "data";
+    id: string;
+    /** Raw bytes the user typed, forwarded to the PTY stdin. */
+    data: string;
 }
-interface StepOkEvent extends RunArtifactBase {
-    kind: "step:ok";
-    /** Wall-clock duration of the step that just finished. */
-    durationMs: number;
+interface TerminalResizeMessage {
+    type: "resize";
+    id: string;
+    cols: number;
+    rows: number;
 }
-interface StepFailEvent extends RunArtifactBase {
-    kind: "step:fail";
-    /** Human-readable error message (single line preferred). */
-    error: string;
-    /** Error class name (e.g. `"AssertionError"`, `"LocatorError"`,
-     *  `"TimeoutError"`). Lets the viewer's `ErrorCard` show a typed
-     *  pill instead of a generic "Error" label. Optional because some
-     *  thrown errors lack a meaningful class name. */
-    errorName?: string;
-    /** Project-relative path to a Playwright trace zip, if captured. */
-    trace?: string;
+interface TerminalCloseMessage {
+    type: "close";
+    id: string;
 }
-interface ScreenshotEvent extends RunArtifactBase {
-    kind: "screenshot";
-    /** Project-relative path to the PNG (under `unotest/.runs/<runId>/screenshot/`). */
-    path: string;
-    /** Step identity for captures bound to a specific step (per-step
-     *  screenshots under `UNOTEST_STEP_SCREENSHOTS`). Same semantics as
-     *  `StepStartedEvent` — the viewer joins on `line:col`. Absent for
-     *  unbound captures (`screenshot()` DSL calls); consumers may fall
-     *  back to attributing those to the step in flight at emit time. */
-    file?: string;
-    line?: number;
-    col?: number;
+type TerminalClientMessage = TerminalSpawnMessage | TerminalDataMessage | TerminalResizeMessage | TerminalCloseMessage;
+interface TerminalOutputMessage {
+    type: "output";
+    id: string;
+    /** Raw PTY stdout/stderr bytes to write to the xterm instance. */
+    data: string;
 }
-/** Emitted ONCE after a failing run when the runner has finished writing
- *  the D-16 failure bundle to disk. Viewer's inspector reads
- *  `bundlePath` to fetch artifacts (screenshot, semantic DOM, network,
- *  trace) via `/api/runs/<runId>/asset?path=...`. The bundle directory
- *  is keyed by its own id (`<scenario>__<isoDate>__<stepIdx>`) under
- *  `.unotest/failures/`, not under `unotest/.runs/`, because the
- *  bundle layout pre-dates per-run dirs and is still consumed by the
- *  agent-fix MCP tools. */
-interface FailureBundleWrittenEvent extends RunArtifactBase {
-    kind: "failure-bundle:written";
-    /** Project-relative path to the bundle directory. */
-    bundlePath: string;
-    /** Project-relative path to the screenshot PNG inside the bundle,
-     *  when tier-2 capture succeeded. */
-    screenshotPath?: string;
-    /** Page URL at the moment of failure (same value captured into the
-     *  bundle's `snapshot.json`/`outline.txt`), for the viewer's ErrorCard. */
-    url?: string;
+interface TerminalExitMessage {
+    type: "exit";
+    id: string;
+    exitCode: number | null;
 }
-interface RunFinishedEvent extends RunArtifactBase {
-    kind: "run:finished";
-    outcome: RunOutcome;
+/** Spawn failure (e.g. `claude` not on PATH) reported to the tab so it can
+ *  print a friendly line instead of silently dying. */
+interface TerminalErrorMessage {
+    type: "error";
+    id: string;
+    message: string;
 }
-/** Debugger pause. Reason discriminates:
- *   - `breakpoint` — executor halted before a statement whose `line:col` is
- *     in `RunOptions.breakpoints`.
- *   - `step` — `pauseRequested` flag was set by a `pause` debug command,
- *     or the run was started in step-mode and just completed a statement.
- *   - `failure` — executor caught an error and `pauseOnFailure` is true.
+type TerminalServerMessage = TerminalOutputMessage | TerminalExitMessage | TerminalErrorMessage;
+/** The `ws` adapter routes inbound messages by an `event` envelope; both
+ *  directions use this single event name on `/ws/terminal`. */
+declare const TERMINAL_WS_EVENT = "terminal";
+
+type VariableCategory = "secret" | "app" | "runner";
+/** User-facing runner-config knobs documented in `unotest/.env`. Single source
+ *  of truth for "is this name our config?" — drives the viewer's "Runner
+ *  config" group and the add-variable dropdown.
  *
- *  When the runner is hosting a debug session it also writes a parallel
- *  `runtime.json` file with the same snapshot. The snapshot is included
- *  inline here for replay / single-frame consumers that don't want to do a
- *  separate fs read. */
-interface PausedEvent extends RunArtifactBase {
-    kind: "paused";
-    reason: "breakpoint" | "step" | "failure";
-    /** Project-root-relative posix path of the file the pause point lives
-     *  in (entry or a helper). Matches a key in the run's `sources.json`. */
-    file: string;
-    line: number;
-    col: number;
-    /** Inline snapshot of the runtime state at the pause point. `vars` is
-     *  per-value JSON-stringified (LocatorValue → "<Locator role=... name=...>"
-     *  human-readable string) and per-var truncated to 4KB to keep the JSONL
-     *  line manageable. `callStack` is outermost→innermost user-function frames. */
-    snapshot?: {
-        vars: Record<string, string>;
-        callStack: {
-            fn: string;
-            file: string;
-            line: number;
-        }[];
-    };
-}
-/** Emitted by the in-page locator picker / action recorder (debug-pause)
- *  when the user picks an element or performs a recorded action. The runner
- *  resolved the picked `ref` to a locator (`RefResolver`) and rendered the
- *  DSL snippet. The viewer inserts `snippet` per `placement`.
- *  See docs/recoder/plan.md. */
-interface LocatorPickedEvent extends RunArtifactBase {
-    kind: "locator:picked";
-    mode: PickerMode;
-    /** Ready-to-insert DSL line, e.g. a bare locator
-     *  `getByRole("button", {name: "Sign in"})` (locator mode), an assertion
-     *  (`assertText(…)`), or a recorded action (`click(…)`, `fill(…)`). */
-    snippet: string;
-    /** Where the viewer drops the snippet:
-     *  - `cursor` — at the editor's caret (deliberate picks; user-placed).
-     *  - `append` — after the previous recorded line (execute-mode action
-     *    recorder, preserving order). */
-    placement: "cursor" | "append";
-    /** `stable` (testId / role+name / label / …) or `fragile` (css/nth-only).
-     *  Lets the viewer flag brittle picks. */
-    stability: "stable" | "fragile";
+ *  NOT listed (so they never surface as user config): launcher-injected
+ *  run-control vars (UNOTEST_RUN_ID, UNOTEST_PARENT_RUN_ID,
+ *  UNOTEST_BUSY_SCENARIOS, UNOTEST_WORKER_*), session-log internals
+ *  (UNOTEST_SESSION_LOG_*), and path bootstrap (UNOTEST_DIR,
+ *  UNOTEST_PROJECT_ROOT, UNOTEST_CONFIG, UNOTEST_VIEWER_NO_OPEN). A user would
+ *  never put those in `unotest/.env`. */
+declare const RUNNER_CONFIG_KEYS: ReadonlySet<string>;
+/** True when `name` is a key the runner consumes as its own configuration. */
+declare function isRunnerConfigKey(name: string): boolean;
+/** Group a variable for the viewer. Secrecy from the source file; runner-vs-app
+ *  from the owned-key set. */
+declare function categorizeVariable(v: {
+    name: string;
+    source: "env" | "secrets";
+}): VariableCategory;
+/** An external scenario variable is referenced by a bare UPPER_SNAKE
+ *  identifier (`APP_BASE_URL`). App / secret names must match this to be
+ *  resolvable from a scenario; runner keys are validated against the set
+ *  above instead. Convention only — no value inspection. */
+declare function isExternalVarName(name: string): boolean;
+
+/** Parse `KEY=VALUE` env-file CONTENT into a plain record. Pure — the
+ *  caller does the fs read. Blank lines and `#` comments are skipped;
+ *  balanced surrounding single/double quotes are stripped; keys not
+ *  matching `[A-Za-z_][A-Za-z0-9_]*` are ignored. Shared by the web and
+ *  mobile runners' layered env loaders (M-11) so both parse `.env` files
+ *  identically. */
+declare function parseEnvContent(raw: string): Record<string, string>;
+/** Quote on write only when the value would otherwise be ambiguous (spaces,
+ *  `#`, quotes, `=`, backslash, leading backtick, or newlines). Plain tokens
+ *  stay unquoted. Mirrors the viewer env-dotenv serializer. */
+declare function serializeEnvValue(value: string): string;
+/** Active (non-commented) assignment keys present in env-file `content`.
+ *  Used to detect duplicates / cross-file shadowing before an add. */
+declare function envKeys(content: string): Set<string>;
+/**
+ * Insert `KEY=VALUE` into env-file `content`. With `sectionLabel`, the line
+ * goes into the first `# --- <label> --- ` divider section — after the last
+ * assignment there (or its description comments if it has no vars yet). The
+ * label is matched as a whole word against DIVIDER lines only, so prose
+ * comments are never mistaken for a section. No such section → it is created
+ * at end-of-file. With no label the line is appended. Does NOT dedup — reject
+ * duplicates before calling.
+ */
+declare function insertEnvVar(content: string, key: string, value: string, sectionLabel?: string): string;
+/**
+ * Remove the assignment line for `key`, leaving every comment and other line
+ * untouched (we do not guess which comments "belong" to the key). Returns the
+ * new content and whether anything was removed.
+ */
+declare function removeEnvVar(content: string, key: string): {
+    content: string;
+    removed: boolean;
+};
+
+/** Which group the user is adding into. App/runner → `.env`, secret →
+ *  `.secrets`. Mirrors VariableCategory as an INPUT (the user's choice). */
+type VariableKind = VariableCategory;
+interface AddVariablePlanInput {
+    name: string;
+    kind: VariableKind;
+    /** Current text of `unotest/.env` (`""` if absent). */
+    envContent: string;
+    /** Current text of `unotest/.secrets` (`""` if absent). */
+    secretsContent: string;
 }
-/** Emitted when execution resumes after a `paused` event. The `by` field
- *  records which debug command unblocked it — purely informational; the
- *  next `step:started` event carries the actual line/col. */
-interface ResumedEvent extends RunArtifactBase {
-    kind: "resumed";
-    by: "step" | "continue";
+type VariablePlanError = {
+    ok: false;
+    code: "duplicate" | "invalid-name" | "unknown-runner-key";
+    message: string;
+};
+type AddVariablePlan = {
+    ok: true;
+    target: "env" | "secrets";
+    sectionLabel?: string;
+    warnings: string[];
+} | VariablePlanError;
+/**
+ * Decide where a new variable goes and what to warn about — or reject it.
+ * Reject reasons: duplicate key in the target file; a non-UPPER_SNAKE app/
+ * secret name (a scenario could never reference it); a runner key not in the
+ * owned-config allowlist. Warnings (non-fatal): secret shadowing a same-named
+ * `.env` var, or vice-versa.
+ */
+declare function planAddVariable(input: AddVariablePlanInput): AddVariablePlan;
+/**
+ * Warning to show after deleting `name` from the file: if the shell
+ * environment still defines it with a DIFFERENT value, it will keep
+ * resolving from there (set-if-absent means ambient wins). Comparing values
+ * avoids a false positive when `.env` was merely flattened into process.env.
+ */
+declare function deleteShadowWarning(name: string, fileValue: string | undefined, ambientValue: string | undefined): string[];
+
+/** A single editor diagnostic. Superset of the `@unotest/dsl`
+ *  validator diagnostic: it unifies parse errors, the vocab validator,
+ *  and the platform linter behind one shape, tagged by `source`/`rule`
+ *  so consumers can theme or filter. Positions are 1-based; a parse
+ *  error with no recoverable position falls back to `1:1`. */
+interface DslDiagnostic {
+    severity: "error" | "warning" | "info";
+    /** 1-based line. */
+    line: number;
+    /** 1-based column. */
+    column: number;
+    /** 1-based end line, when the producer knows the span. */
+    endLine?: number;
+    /** 1-based end column, when the producer knows the span. */
+    endColumn?: number;
+    message: string;
+    /** Stable rule id, e.g. `"validator:unknown-function"`, `"validator:dsl"`,
+     *  a linter rule id, or `"parse"`. */
+    rule: string;
+    /** Which stage produced it — lets the UI group / colour by origin. */
+    source: "parse" | "validate" | "lint";
 }
-/** Emitted when the collaborative control token changes owner (Slice 3), so
- *  the viewer can live-update the "who's driving" badge over WS. */
-interface WheelChangedEvent extends RunArtifactBase {
-    kind: "wheel:changed";
-    owner: "agent" | "human";
+/** Coarse grouping for a vocab entry — drives completion icons and
+ *  ordering. `keyword` covers DSL control-flow / block words (`step`,
+ *  `if`, `for`, …); `helper` covers project-defined `flow_*` / mock
+ *  helpers surfaced from the workspace. */
+type DslVocabCategory = "action" | "assertion" | "selector" | "chain" | "navigation" | "read" | "wait" | "state" | "storage" | "multi-context" | "sandbox" | "diagnostic" | "escape-hatch" | "keyword" | "helper";
+/** One declared argument of a vocab entry — feeds signature help and
+ *  the snippet placeholders in `insertText`. `kind` is the validator's
+ *  arg-kind string (`"locatorLike"`, `"stringLike"`, `"number"`,
+ *  `"any"`, …); the editor treats it as an opaque label. */
+interface DslVocabArg {
+    label: string;
+    kind: string;
+    required: boolean;
+    /** Literal members when `kind` is `"enum"` — the label alone loses
+     *  them, and consumers (typings generator, completion) need the
+     *  actual values. */
+    enumValues?: readonly string[];
 }
-/** Emitted in response to a `probe` debug command: the result of evaluating a
- *  locator string against the live page. `id` echoes the command's id so the
- *  client that issued the probe can correlate the reply. READ-ONLY — producing
- *  it never changed the page. */
-interface ProbeResultEvent extends RunArtifactBase {
-    kind: "probe:result";
-    /** Correlates with the issuing `DbgCommandProbe.id`. */
-    id: string;
-    result: ProbeResult;
+/** A single autocomplete-able item: a vocab function, a DSL keyword, or
+ *  a project helper. Serializable — crosses the REST boundary verbatim
+ *  and is cached by the browser (the vocab is static per platform). */
+interface DslVocabEntry {
+    name: string;
+    category: DslVocabCategory;
+    args: DslVocabArg[];
+    /** True when the signature accepts extra positional args after the
+     *  declared ones (`shell(cmd, ...args)`, `dbQuery(sql, ...params)`). */
+    variadic?: boolean;
+    /** Return-kind string (`"void"`, `"string"`, `"locator"`, …). */
+    returns: string;
+    /** Snippet body with `${n:label}` placeholders, e.g.
+     *  `click(${1:locator})`. */
+    insertText: string;
+    /** Human-readable signature for hover / signature-help, e.g.
+     *  `getByRole(role, { name?, exact? })`. Richer than the bare arg
+     *  list — includes option-object shape. */
+    signature?: string;
+    /** Prose description (markdown) for hover and the completion info
+     *  panel. */
+    doc?: string;
+    /** Locator capability from the function contract. `"chainableLocator"`
+     *  entries can be chained off a locator (offered after `.`); any value
+     *  other than `"none"` produces a locator (so it fits a `locator`
+     *  argument slot). Absent for keywords / helpers that have no contract. */
+    locatorCapability?: "none" | "locator" | "chainableLocator";
+    /** Where the entry is defined in the USER's project — set for project
+     *  helpers (`flow_*` in `_helpers/`), absent for platform functions,
+     *  which have no source on disk there. Feeds go-to-definition.
+     *  `path` is project-relative posix; `line`/`column` are 1-based. */
+    source?: {
+        path: string;
+        line: number;
+        column: number;
+    };
 }
-/** A single MCP tool invocation by the agent, surfaced into the session's
- *  event stream so the human sees — in the viewer's System console — what the
- *  agent called and how it ended. Emitted ONLY while the MCP server is attached
- *  to this run (own-browser calls have no session to attach to). Paired:
- *  `tool:call` at invocation, `tool:result` at completion, correlated by
- *  `callId`. Read-only telemetry — emitting it never touches the page. */
-interface ToolCallEvent extends RunArtifactBase {
-    kind: "tool:call";
-    /** Correlates with the matching `tool:result` (one MCP call). */
-    callId: string;
-    /** MCP tool name, e.g. "check_locator", "explore_step". */
-    tool: string;
-    /** Arguments as a secret-redacted, length-capped JSON string — NOT the raw
-     *  object. Capped upstream so the line stays a single atomic append. */
-    args: string;
+/** Per-request file context for {@link IDslLanguageService.validate}.
+ *  The viewer owns workspace discovery, so it supplies the things the
+ *  platform validator can't know on its own. */
+interface DslValidateContext {
+    /** Names of project helpers (`flow_*`, mocks) so their calls are not
+     *  flagged as unknown functions — mirrors how the lint runner
+     *  registers `unotest/e2e/_helpers/`. */
+    helperNames?: readonly string[];
+    /** Whether the source is a scenario or a helper definition file. */
+    fileKind?: "scenario" | "helper";
 }
-interface ToolResultEvent extends RunArtifactBase {
-    kind: "tool:result";
-    /** Correlates with the issuing `ToolCallEvent.callId`. */
-    callId: string;
-    tool: string;
-    ok: boolean;
-    durationMs: number;
-    /** Secret-redacted, length-capped preview of the result text. */
-    preview: string;
-    /** Present only when `ok` is false. */
-    error?: {
-        class: string;
-        message: string;
-    };
+/** The DSL language service a platform exposes to the viewer. Two
+ *  concerns only: the static vocabulary (for completion / signature
+ *  help) and full source validation (parse + vocab validator + linter,
+ *  identical to the platform's own lint gate). */
+interface IDslLanguageService {
+    /** Static, serializable vocabulary for autocomplete and signature
+     *  help. Stable for the lifetime of the process — safe to cache. */
+    getVocab(): DslVocabEntry[];
+    /** Full diagnostics for one source string. Pure with respect to the
+     *  filesystem — all workspace knowledge arrives via `ctx`. */
+    validate(source: string, ctx?: DslValidateContext): DslDiagnostic[];
 }
-/** Discriminated union of every JSONL event the scenario runner emits. */
-type RunArtifact = RunStartedEvent | StepStartedEvent | StepOkEvent | StepFailEvent | ScreenshotEvent | FailureBundleWrittenEvent | PausedEvent | ResumedEvent | LocatorPickedEvent | WheelChangedEvent | ProbeResultEvent | ToolCallEvent | ToolResultEvent | RunFinishedEvent;
-interface CollectionRunStartedEvent extends RunArtifactBase {
-    kind: "collection-run:started";
-    runId: RunId;
-    /** Collection `name` (filename stem). */
-    collection: string;
-    /** Scenario names that will be executed, in order. */
-    scenarios: string[];
+
+/** A spawned runner process. Structural superset of the bits of a Node
+ *  `ChildProcess` the viewer actually consumes — pid for the active-run
+ *  snapshot, stdout/stderr for log capture, exit/error for finalize,
+ *  kill for abort. Both `child_process` and Electron `utilityProcess`
+ *  satisfy this via a thin adapter. */
+interface ILaunchedProcess {
+    /** OS process id, or -1 if the spawn failed to produce one. */
+    readonly pid: number;
+    /** Captured stdout stream, or null when not piped. */
+    readonly stdout: Readable | null;
+    /** Captured stderr stream, or null when not piped. */
+    readonly stderr: Readable | null;
+    /** Register the exit handler. Called once when the process exits. */
+    onExit(cb: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    /** Register the spawn-error handler (e.g. bin not found). */
+    onError(cb: (err: Error) => void): void;
+    /** Terminate the process. Default signal SIGTERM. */
+    kill(signal?: NodeJS.Signals): void;
 }
-interface CollectionScenarioStartedEvent extends RunArtifactBase {
-    kind: "collection-run:scenario-started";
-    /** The scenario-run-id created when this scenario started executing. */
-    scenarioRunId: RunId;
-    scenario: string;
+/** Everything the launcher needs to spawn one runner process. The caller
+ *  (RunnerService) has already merged the environment and resolved the bin
+ *  + argv from the `IRunnerAdapter`; the launcher only decides HOW to run
+ *  it. Pure data — no behaviour. */
+interface LaunchSpec {
+    /** Absolute path to the JS bin entry — `IRunnerAdapter.resolveBin()`. */
+    bin: string;
+    /** Argv to pass after the bin — `IRunnerAdapter.buildArgs(req)`. */
+    args: string[];
+    /** Fully-merged environment for the child. */
+    env: NodeJS.ProcessEnv;
+    /** Working directory — the workspace project root. */
+    cwd: string;
 }
-interface CollectionScenarioFinishedEvent extends RunArtifactBase {
-    kind: "collection-run:scenario-finished";
-    scenarioRunId: RunId;
-    scenario: string;
-    outcome: RunOutcome;
+/** Spawns the runner JS under a Node-capable runtime. Injected into the
+ *  viewer's RunnerService so the spawn mechanism (system Node vs Electron
+ *  utilityProcess) is a deployment choice, not baked into the service. */
+interface IProcessLauncher {
+    launch(spec: LaunchSpec): ILaunchedProcess;
 }
-interface CollectionRunFinishedEvent extends RunArtifactBase {
-    kind: "collection-run:finished";
-    outcome: RunOutcome;
+
+/** Contents of `unotest/.viewer.lock`. Written by viewer-server on
+ *  startup, removed on graceful shutdown. Stale detection: `process.kill(
+ *  pid, 0)` throws ESRCH if PID is dead → lockfile is stale, safe to
+ *  overwrite. */
+interface LockFile {
+    /** PID of the viewer-server process. */
+    pid: number;
+    /** Full URL (with port) to reach the viewer. e.g. `http://localhost:5173`. */
+    url: string;
+    /** ISO 8601 timestamp of `pid` start. Used for tie-breaking and stale-age
+     *  heuristics if `kill(pid, 0)` is inconclusive. */
+    startedAt: string;
 }
-type CollectionRunArtifact = CollectionRunStartedEvent | CollectionScenarioStartedEvent | CollectionScenarioFinishedEvent | CollectionRunFinishedEvent;
 
-/** Lifecycle stage as inferred by the server when listing runs. */
-type RunStatus = "running" | "passed" | "failed" | "aborted" | "interrupted";
-interface RunMeta {
-    runId: RunId;
-    kind: RunKind;
-    /** Scenario `name` (file stem under `e2e/`) for `kind:"scenario"`,
-     *  collection `name` (yaml stem) for `kind:"collection"`. */
-    ref: string;
-    /** Wallclock from the `run:started` event. */
-    startedAt: number;
-    /** Wallclock from the `run:finished` event, or null if still active. */
-    finishedAt: number | null;
-    /** Total wall-clock duration, or null if still running. */
-    durationMs: number | null;
-    /** Status derived from outcome / liveness — `running` while the run's
-     *  heartbeat is fresh and no `run:finished` has landed. */
-    status: RunStatus;
-    /** Terminal outcome from `run:finished`, or null if still running. */
-    outcome: RunOutcome | null;
-    /** Run-id of the parent collection-run when this is a child scenario
-     *  spawned inside one. Absent for top-level scenarios and for
-     *  collection-runs themselves. Populated by the writer from the
-     *  child's `manifest.json`. */
-    parentRunId?: string;
+/** Helper file metadata. Helpers live in `unotest/e2e/_helpers/**` as
+ *  `snake_case` functions (`signin_as`, `seed_user`, …). The runner
+ *  auto-discovers them; no import system in scenarios. */
+interface HelperMeta {
+    /** File stem relative to `_helpers/`, dirs as slashes. */
+    name: string;
+    /** Project-relative path to the source file. */
+    path: string;
 }
 
 interface FsScenariosChangedMessage {
@@ -1392,4 +1553,4 @@ interface RuntimeStateFile {
     updatedAt: number;
 }
 
-export { type AddVariablePlan, type AddVariablePlanInput, type AppPathPickerSpec, type AppServerEvent, type AuthoringRunRequest, type BreakpointEntry, type BreakpointsFile, COLLECTIONS_SUBDIR, COLLECTION_NAME_FORBIDDEN_RE, COMMANDS_FILE, type CheckSeverity, type CollectionMeta, type CollectionRunArtifact, type CollectionRunFinishedEvent, type CollectionRunRequest, type CollectionRunStartedEvent, type CollectionRunTab, type CollectionScenarioFinishedEvent, type CollectionScenarioStartedEvent, type CollectionTab, type DbgCommand, type DbgCommandAbort, type DbgCommandClearBp, type DbgCommandContinue, type DbgCommandKind, type DbgCommandPause, type DbgCommandPickerStart, type DbgCommandPickerStop, type DbgCommandProbe, type DbgCommandRecord, type DbgCommandSetBp, type DbgCommandSnapshot, type DbgCommandStep, type DbgCommandWheel, type DebugCapabilities, type DoctorCheck, type DoctorContext, type DslDiagnostic, type DslValidateContext, type DslVocabArg, type DslVocabCategory, type DslVocabEntry, E2E_SUBDIR, ENV_FILE, type EnvFile, type EnvUpdate, type EnvVar, type ErrorMessage, type FailureBundleWrittenEvent, type FsBreakpointsChangedMessage, type FsCollectionRunStepMessage, type FsCollectionsChangedMessage, type FsHelpersChangedMessage, type FsRunFinishedMessage, type FsRunStartedMessage, type FsRunStepMessage, type FsScenariosChangedMessage, HEARTBEAT_FILE, HELPERS_SUBDIR, type HelperMeta, type HelperTab, type HostRequirement, type IDslLanguageService, type ILaunchedProcess, type IProcessLauncher, type IRunnerAdapter, LOCK_FILE, LOG_FILE, type LaunchSpec, type LocatorPickedEvent, type LockFile, type LogLineMessage, type Matcher, PICKER_SNAPSHOT_FILE, type PausedEvent, type PickerMode, type ProbeMatch, type ProbePinned, type ProbeResult, type ProbeResultEvent, RUNNER_CONFIG_KEYS, RUNS_SUBDIR, RUNTIME_FILE, RUN_MANIFEST_FILE, RUN_SOURCES_FILE, type RecordedActionKind, type RegexLiteral, type ResumedEvent, type RunArtifact, type RunFinishedEvent, type RunId, type RunKind, type RunManifest, type RunMeta, type RunOutcome, type RunRequest, type RunSources, type RunStartedEvent, type RunStatus, RunnerAdapterNotFoundError, RunnerNotConfiguredError, type RuntimeState, type RuntimeStateFile, SECRETS_FILE, SEGMENT_NAME_FORBIDDEN_RE, SNAPSHOTS_SUBDIR, STDERR_FILE, STDOUT_FILE, STEPS_FILE, type ScenarioMeta, type ScenarioRunRequest, type ScenarioRunTab, type ScenarioTab, type ScenariosPayload, type ScreenshotEvent, type SnapshotTab, type StepFailEvent, type StepOkEvent, type StepStartedEvent, TERMINAL_RUNTIME_STATES, TERMINAL_WS_EVENT, type TabKind, type TabKindName, type TerminalClientMessage, type TerminalCloseMessage, type TerminalDataMessage, type TerminalErrorMessage, type TerminalExitMessage, type TerminalKind, type TerminalOutputMessage, type TerminalResizeMessage, type TerminalServerMessage, type TerminalSpawnMessage, type ToolCallEvent, type ToolResultEvent, UNOTEST_DIR, UnsupportedRunKindError, type VariableCategory, type VariableKind, type VariablePlanError, type WheelChangedEvent, type WsMessage, type WsMessageKind, activeEnvName, categorizeVariable, debugDirFor, debuggerFileFor, deleteShadowWarning, envFileFor, envKeys, envLayerFilesFor, insertEnvVar, isExternalVarName, isRegexLiteral, isRunnerConfigKey, isTerminalRuntimeState, makeRunId, parseAppServerEvent, parseEnvContent, planAddVariable, regexLiteral, removeEnvVar, runsDirFor, sanitizeRunIdSegment, secretsFileFor, secretsLayerFilesFor, serializeEnvValue, testDirFor, validateCollectionName, validateSegmentName };
+export { type AddVariablePlan, type AddVariablePlanInput, type AppPathPickerSpec, type AppServerEvent, type AuthoringRunRequest, BLOBS_DIR, type BreakpointEntry, type BreakpointsFile, COLLECTIONS_SUBDIR, COLLECTION_NAME_FORBIDDEN_RE, COMMANDS_FILE, type CheckSeverity, type CollectionMeta, type CollectionRunArtifact, type CollectionRunFinishedEvent, type CollectionRunRequest, type CollectionRunStartedEvent, type CollectionRunTab, type CollectionScenarioFinishedEvent, type CollectionScenarioStartedEvent, type CollectionTab, DAY_INDEX_FILE, type DbgCommand, type DbgCommandAbort, type DbgCommandClearBp, type DbgCommandContinue, type DbgCommandKind, type DbgCommandPause, type DbgCommandPickerStart, type DbgCommandPickerStop, type DbgCommandProbe, type DbgCommandRecord, type DbgCommandSetBp, type DbgCommandSnapshot, type DbgCommandStep, type DbgCommandWheel, type DebugCapabilities, type DoctorCheck, type DoctorContext, type DslDiagnostic, type DslValidateContext, type DslVocabArg, type DslVocabCategory, type DslVocabEntry, E2E_SUBDIR, ENV_FILE, EXPECT_FAIL_ANNOTATION, type EnvFile, type EnvUpdate, type EnvVar, type ErrorMessage, type FailureBundleWrittenEvent, type FsBreakpointsChangedMessage, type FsCollectionRunStepMessage, type FsCollectionsChangedMessage, type FsHelpersChangedMessage, type FsRunFinishedMessage, type FsRunStartedMessage, type FsRunStepMessage, type FsScenariosChangedMessage, HEARTBEAT_FILE, HELPERS_SUBDIR, type HelperMeta, type HelperTab, type HostRequirement, type IDslLanguageService, type ILaunchedProcess, type IProcessLauncher, type IRunnerAdapter, InvalidBlobHashError, LOCK_FILE, LOG_FILE, type LaunchSpec, type LocatorPickedEvent, type LockFile, type LogLineMessage, type Matcher, PICKER_SNAPSHOT_FILE, type PausedEvent, type PickerMode, type ProbeMatch, type ProbePinned, type ProbeResult, type ProbeResultEvent, RUNNER_CONFIG_KEYS, RUNS_SUBDIR, RUNTIME_FILE, RUN_INDEX_SCHEMA_VERSION, RUN_MANIFEST_FILE, RUN_SOURCES_FILE, type RecordedActionKind, type RegexLiteral, type ResumedEvent, type RunArtifact, type RunFinishedEvent, type RunId, type RunIndexEntry, type RunIndexHeader, type RunKind, type RunManifest, type RunMeta, type RunOutcome, type RunRequest, type RunSources, type RunStartedEvent, type RunStatus, RunnerAdapterNotFoundError, RunnerNotConfiguredError, type RuntimeState, type RuntimeStateFile, SCENARIOS_INDEX_DIR, SCENARIOS_LATEST_FILE, SCENARIO_RECENT_WINDOW, SECRETS_FILE, SEGMENT_NAME_FORBIDDEN_RE, SNAPSHOTS_SUBDIR, STDERR_FILE, STDOUT_FILE, STEPS_FILE, type ScenarioAnnotations, type ScenarioLatestEntry, type ScenarioMeta, type ScenarioRunRequest, type ScenarioRunTab, type ScenarioTab, type ScenariosLatest, type ScenariosPayload, type ScreenshotEvent, type SnapshotTab, type StepFailEvent, type StepOkEvent, type StepStartedEvent, TERMINAL_RUNTIME_STATES, TERMINAL_WS_EVENT, type TabKind, type TabKindName, type TerminalClientMessage, type TerminalCloseMessage, type TerminalDataMessage, type TerminalErrorMessage, type TerminalExitMessage, type TerminalKind, type TerminalOutputMessage, type TerminalResizeMessage, type TerminalServerMessage, type TerminalSpawnMessage, type ToolCallEvent, type ToolResultEvent, UNOTEST_DIR, UnplaceableRunIdError, UnsupportedRunKindError, type VariableCategory, type VariableKind, type VariablePlanError, type WheelChangedEvent, type WsMessage, type WsMessageKind, activeEnvName, blobPathFor, blobRelPathFor, blobRelSegmentsFor, blobsRootFor, categorizeVariable, debugDirFor, debuggerFileFor, deleteShadowWarning, envFileFor, envKeys, envLayerFilesFor, foldScenarioRun, insertEnvVar, isAnnotationLine, isExternalVarName, isFailingStatus, isRegexLiteral, isRunnerConfigKey, isTerminalRuntimeState, makeRunId, parseAppServerEvent, parseEnvContent, parseScenarioAnnotations, planAddVariable, projectRunDirFor, projectRunsRoot, regexLiteral, removeEnvVar, requireRunDirFor, runDirFor, runIdStartedAt, runsDirFor, sanitizeRunIdSegment, scenarioIndexFileName, scenarioRefFromFileName, secretsFileFor, secretsLayerFilesFor, serializeEnvValue, shardDaysDescending, shardDirFor, shardPathForRunId, shardPathForTimestamp, testDirFor, validateCollectionName, validateSegmentName };