waygraph 0.15.54 → 0.16.1

package/templates/scaffold/tests/hoppscotch.spec.ts

@@ -5,17 +5,7 @@ import config from "../config/waygraph.config.js";
 import { hoppscotchGetFlow } from "../src/flows/(external)/hoppscotch/get.flow.js";
 import { hoppscotchAuthFlow } from "../src/flows/(external)/hoppscotch/auth.flow.js";
 import { hoppscotchPostFlow } from "../src/flows/(external)/hoppscotch/post.flow.js";
-import {
-  ExpectedResponseHeader,
-  ExpectedResponseText,
-  ExpectedStatus,
-  RequestBearerToken,
-  RequestBody,
-  RequestHeaders,
-  RequestMethod,
-  RequestParams,
-  RequestUrl,
-} from "../src/states/demo.mem-keys.js";
+import { ExpectedResponseHeader, ExpectedResponseText, ExpectedStatus, RequestBearerToken, RequestBody, RequestHeaders, RequestMethod, RequestParams, RequestUrl } from "../src/map/(external)/hoppscotch/_keys.js";
 
 // The API under test: no CORS headers, so only the extension can reach it from hoppscotch.io.
 let server: Server;

package/templates/scaffold/tests/mail-verify.spec.ts

@@ -3,7 +3,7 @@ import { spawnSync } from "node:child_process";
 import net from "node:net";
 import { MemPage, checkpoint } from "waygraph";
 import { emailVerificationFlow } from "../src/flows/(user-stories)/email-verification.flow.js";
-import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/states/demo.mem-keys.js";
+import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/map/(external)/mailpit/_keys.js";
 import { HOME_URL } from "../src/map/(app_base)/home/_sel.js";
 
 // Plays "the app sent a verification email": starts a throwaway Mailpit container, sends a real SMTP message,
@@ -144,7 +144,7 @@ test("assert-email-received fails loud, naming itself, when no email ever arrive
     mem.set(ExpectedRecipient({ email: "nobody-sent-this-one@example.com" }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
-    // A defineFlow chain's verify-failure error names the whole path taken so
+    // A flow's verify-failure error names the whole path taken so
     // far (each composed Block's own name accumulates through connect()),
     // not just the leaf Block - real, useful QA context, not a bug - so this
     // matches the accumulated name ending at assert-email-received, not an

package/templates/skills/waygraph-blind-pilot.skill.md

@@ -52,12 +52,8 @@ Session control works as `browser …` or `auto …` with the same `<sessionId>`
   Block file can simply vanish from the graph with no error printed anywhere obvious - if a
   Block you just wrote doesn't show up after `browser reload`, check `waygraph graph`'s own
   `skipped` list and the file's syntax directly, don't assume it just needs more time.
-- **`defineAssertBlock` needs no `<In, Out>` generic to type-check** (`checkpoint: "X"` alone
-  is enough for TypeScript to infer it) - but older/naive static-graph discovery logic may
-  rely on parsing an explicit generic from source text. If a freshly-written
-  `defineAssertBlock` Block is missing from `waygraph graph`'s edges (silently, no error),
-  check whether this package's own `graph.ts` has the matching-marker fix for it, or add an
-  explicit generic type argument as a workaround.
+- **Pass Checkpoint values** (`checkpoint: X`, `from: X, to: Y`) so a freshly-written Block shows up in the graph from its
+  runtime route. The graph reads routes at runtime, never from source text.
 - **A `<p>`/text-based selector often needs scoping**, not just a class name - a sibling
   "chat list item" and "message preview" frequently share the exact same CSS classes in real
   apps, distinguished only by DOM position (first vs second child of a specific wrapper).

package/templates/skills/waygraph-convention.skill.md

@@ -45,13 +45,15 @@ against a live site, use `--skill-pilot-blind`.
    hand-supplied every time, `registerMemStub(key, fake)` + `memStub: true` on the flow (or
    `--mem-stub`) fills it from a registry instead - a key with no registration still fails
    preflight exactly as before, so this narrows what needs real input, never removes the guard.
-6. **Keep Checkpoints typed.** Block helpers take concrete Checkpoint types from `src/states/`
-   (e.g. `defineMethodBlock<LoginPage, LoggedIn>`). A Block's **output** must never be
-   `Checkpoint<string>` — `waygraph check` / `waygraph typecheck` warn. When a Block runs from a
-   few known states, name them as a union in `src/states/` (`type CanAddItem = Home | CartEmpty`);
-   a `Checkpoint<string>` **input** is only for a Block that's genuinely reachable from anywhere.
-   Same for `defineAssertBlock({…})` without an explicit type arg — use
-   `defineAssertBlock<YourCheckpoint>({…})`.
+   Put those `registerMemStub` calls in a `*.mem-stubs.ts` file (`src/states/demo.mem-stubs.ts`): live sessions (`auto`,
+   `pilot`, `traverse`) load every one and use them as the default for a Block's `requires`.
+6. **Checkpoints are values.** Declare each once in `src/states/`: `export const Home = checkpoint("Home");
+   export type Home = typeof Home;` (a union: `export const CanAddItem = [Home, CartEmpty] as const`). Blocks take
+   the values, never tag strings or `<In, Out>` type arguments: `defineNavBlock({ checkpoint: Home, … })`,
+   `defineAssertBlock({ checkpoint: ItemInCart, … })`, `defineMethodBlock({ from: CanAddItem, to: ItemInCart, … })`
+   (leave `from` out for "from anywhere"; `resolve` is implied when `to` is one Checkpoint). The Block then carries its
+   route at runtime, so `waygraph graph`, `auto` and the manifest read it exactly. Older projects:
+   `waygraph upgrade --codemod checkpoints`.
 7. **One input/action per Method Block.** No block that `.fill()`s two fields or `.fill()` + `.click()` in one
    `act()` — split like saucedemo login (`fill-username`, `fill-password`, `submit-login`). Opt out per file:
    `// waygraph-ignore: multi-input` or `// waygraph-ignore-practices`.
@@ -69,22 +71,23 @@ against a live site, use `--skill-pilot-blind`.
 ## Flows, stubs and config (the scaffold's shape)
 
 - **Build flows with `map()`** (`engine.map({ memStub }).start().gotoPage(Nav).method(B, { pace }).assert(A).end()`;
-  `.gotoExternal` for another origin), never a raw `defineFlow([start, ...])`. Flow settings (`memStub`, `expectedFailure`, `demoPace`, `sessionReset`) go in `map({ … })` before the chain
-  and `.end()` takes nothing. The flow's title is `ctx.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**,
-  not `chainFlow` / `withSessionReset`. No `withMemStub(withTitle(...))` wrappers.
+  `.gotoExternal` for another origin); it is the only way to build one. Flow settings (`memStub`, `expectedFailure`, `demoPace`, `sessionReset`) go in `map({ … })` before the chain
+  and `.end()` takes nothing. The flow's title is `ctx.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**.
+  `defineFlow`, `chainFlow` and the `with*` flow wrappers were removed in 0.16.0; `waygraph upgrade --codemod flows` converts them.
 - **`src/flows/` holds use cases and mirrors the front end's endpoints**: a folder per page (`flows/auth/login/`) with one
   file per scenario named for its outcome (`success.flow.ts`, `wrong-password.flow.ts`, `empty-fields.flow.ts`), and
   `(user-stories)/` (any `(group)`) for flows that cross pages. Export names are `<page><Outcome>Flow`. Not one file per
   Block chain, not a flat folder of unrelated flows.
 - **Blocks carry no stubs; the flow does.** Demo highlights are ctx stubs chained on the Block where the flow uses it:
   `AddItemBlock.stubAfter((ctx) => { ctx.ring("cart", { selector: DemoSel.cartCount, label: "AC · item in cart" }); })`.
-  Not a static `withHighlightFixtures({ "add-item": { stubAfter: {...} } })` map, and not an inline
-  `instruction: { stubAfter() {} }`. A Block used twice gets one `const AddShown = AddItemBlock.stubAfter(...)`.
+  That chained function is the only form: a Block's definition (its options or `instruction`) takes no stub, and a stub
+  is never a slot map. A Block used twice gets one `const AddShown = AddItemBlock.stubAfter(...)`. A stub that throws
+  fails its step in the demo, named.
 - **Reading a value into `mem` happens in `act`** (`mem.set(Key, value)`), like Mailpit's `extract-email-link`.
   `observe` is only for a Block that branches (it feeds `resolve`); an empty `act(){}` plus an `observe` that
   writes `mem` is a misuse.
 - **Demo pace is a map option or config, never a wrapper.** `.method(SetBearerTokenBlock, { pace: "blitz" })` speeds one step,
-  `map({ demoPace: "fast" })` a flow, `demo: { pace, typingMs, slowMo }` in the config the whole project. Not `withBlockPace(...)`.
+  `map({ demoPace: "fast" })` a flow, `demo: { pace, typingMs, slowMo }` in the config the whole project.
 - **Per-environment values** (a different `baseUrl` for staging) come from `.env` files read in the config function:
   `defineConfig(({ env }) => ({ baseUrl: env.BASE_URL }))`; `--env staging` loads `.env.staging`. Never edit the config to switch.
 - **More than one config** (staging, another app) is another file, `config/waygraph.<name>.config.ts`, chosen with `--config <name>`.
@@ -93,7 +96,7 @@ against a live site, use `--skill-pilot-blind`.
   Block's `act`; the click Block stays a plain click.
 - **Project settings live in `config/waygraph.config.ts`** (`defineConfig({ baseUrl, testDir, webServer,
   extensions, playwright: {...} })`). The config file also exports `engine = new Engine(config)`; flows `import { engine } from "../../config/waygraph.config.js"`; a project needs no
-  `playwright.config.ts` - `waygraph test` builds one from it. A leftover `playwright.config.*` is deprecated.
+  `playwright.config.ts` - `waygraph test` builds one from it (a project's own `playwright.config.*` is not read).
 - **Another origin the test needs is a Map external** under `src/map/(external)/<tool>/`. For REST API
   tests, `(external)/hoppscotch` (list `extensions: ["hoppscotch"]` in the config) drives hoppscotch.io's client
   with the extension, so requests skip CORS: `set-method`, `set-url`, `set-headers`, `set-json-body`,
@@ -110,6 +113,7 @@ against a live site, use `--skill-pilot-blind`.
 | Effect | `*.effect.block.ts` in `methods/` / `_methods/` | `defineEffectBlock` | No |
 | Method | `*.method.block.ts` in `methods/` / `_methods/` | `defineMethodBlock` | No |
 | Assert | with Method/Effect peers | `defineAssertBlock` | No |
+| API | `*.api.block.ts` in `methods/` | `defineApiBlock({ from, to, call })` (a real HTTP request; `map().method(...)`) | No |
 
 Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM
 (or mem) for labeled rows.
@@ -165,9 +169,14 @@ npx waygraph check --no-practices .   # skip bad-practice scan only
 npx waygraph map .            # exit 1 if src/map/ folder path != real static url
 npx waygraph validate .       # every .flow.ts loads
 npx waygraph graph .          # nodes/edges/skipped/orphans - counts should make sense
+npx waygraph manifest .       # JSON of every Block (kind, from/to, requires), Flow and Checkpoint
+npx waygraph map pack <group> # a src/map/ group with its own _states.ts/_keys.ts -> installable package
 npm run typecheck             # when the consumer has it
 ```
 
+Every `run`/`demo`/`test` also writes `.waygraph/runs/<runId>.jsonl` (step start/end/error, artifacts): read the
+newest one to see which Block failed and with what error, instead of re-running.
+
 `waygraph check` should report zero nav warnings. Orphan Blocks (not in any `.flow.ts`)
 are still runnable in Pilot's live menu - orphan status only blocks
 `auto --blocks <From> <To>` pathfinding.

package/templates/skills/waygraph-pilot.skill.md

@@ -50,6 +50,11 @@ waygraph auto highlight <sessionId> '<json>'  # paint rings/todos on the live pa
 just what's reachable from here - use it to plan several steps ahead before you start
 sending picks.
 
+A Block's `requires` are filled from `--data '{...}'` first, then from the project's mem stubs: the session loads
+every `*.mem-stubs.ts` and uses each `registerMemStub` fake as that key's default. A start URL that can't be opened
+(server down, DNS) fails `browser start` / `pilot start` with the reason; it never starts a blank session silently.
+An unknown flag is an error, not a project path.
+
 ## Bad practices (`waygraph check` / `waygraph typecheck`)
 
 Run `waygraph typecheck .` (or `npm run typecheck`) — runs `tsc --noEmit` then bad-practice warnings.
@@ -58,8 +63,6 @@ Use `--no-practices` on either command to skip the practice scan.
 
 Patterns warned (does not fail `check`; fails `typecheck` only when `tsc` fails):
 
-- **`Checkpoint<string>` as a Block's output** — e.g. `defineMethodBlock<…, Checkpoint<string>>` instead of a project Checkpoint type from `src/states/` (a wildcard *input* means "reachable from anywhere" and is allowed).
-- **`defineAssertBlock({…})` without an explicit type arg** — use `defineAssertBlock<YourCheckpoint>({…})` so `defineFlow` typing stays honest.
 - **Multiple `.fill()` in one Method** — split into one Block per input (fill-username, fill-password, …).
 - **`.fill()` + `.click()` in one Method** — split fill and submit into separate Blocks.
 
@@ -105,7 +108,7 @@ thing that differs from demo is *who* triggers the paint:
 | Mode | Who paints | How |
 |------|------------|-----|
 | `waygraph demo` | Engine, automatically | ctx stubs chained in the flow run each step |
-| Pilot / `auto --detach` | **You (the agent)** | `waygraph auto highlight <sessionId> '<json>'` before (or between) sends |
+| Pilot / `browser start` session | **You (the agent)** | `waygraph auto highlight <sessionId> '<json>'` before (or between) sends |
 
 The ctx stubs a flow chains onto Blocks show up in Pilot's `auto trace` as metadata, but they do **not**
 auto-draw. You re-express the same intent with `auto highlight` (copy selectors/labels from the flow's stubs or
@@ -133,7 +136,7 @@ waygraph auto highlight <sessionId> '{"clear":true}'
 Supported fields (demo parity):
 - `rings[]`: `selector`, `label`, `detail`, `tag`, `tone`, `size`, `weight`, `color`, `zoom`, `zoomOut`, `focus`
 - `todos` / `todoIndex` / `todoTitle` / `todoPos` (`right` default | `left`)
-- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see docs/REFERENCE.md "Todo dock UI")
+- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see docs/reference/cli.md "Todo dock UI")
 - `zoom` / `zoomSelector` / `zoomOut` - scroll + zoom badge (not CSS page scale)
 - `device`: `mobile` | `tablet` | `desktop` (Playwright viewport)
 - `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 30000)

package/dist/auto-session/session.d.ts

@@ -1,193 +0,0 @@
-import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
-import type { PilotHighlightFixtures } from "../pilot-overlay.js";
-/**
- * Non-interactive explore session: same graph/library/mem/browser setup
- * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
- * blocking `readline` loop. Headless by default (matching
- * `runAutoExplore`'s own `cli` branch), optionally visible via
- * `AutoSessionInit.headless: false` - this type only ever backs the `--cli`
- * picker, never the headful page-embedded panel, headless or not.
- */
-export declare class AutoSession {
-    private readonly projectDir;
-    private readonly inject;
-    private readonly blocksSelect;
-    private graph;
-    private library;
-    private readonly mem;
-    private readonly engine;
-    private readonly closeBrowser;
-    private readonly context;
-    private page;
-    private readonly startUrl;
-    private readonly sessionId;
-    private here;
-    private lastRunNote;
-    private readonly trace;
-    private readonly consoleLog;
-    private readonly knownInteractionSelectors;
-    private readonly headless;
-    private lastOverlayInfo;
-    private constructor();
-    static start(init: AutoSessionInit): Promise<AutoSession>;
-    /** Pure getter - returns a copy, not the live array. */
-    getTrace(): TraceStep[];
-    private pushTrace;
-    /** Pure getter - returns a copy, not the live array. */
-    getConsoleLog(): ConsoleLogEntry[];
-    private pushConsoleLog;
-    private currentMenu;
-    /** Paint the overlay on about:blank / immediately after session start (headful browser). */
-    private bootstrapOverlay;
-    /** Re-apply cached overlay state after navigation (init script restores shell only). */
-    private repaintOverlayAfterNavigation;
-    /**
-     * Flags same-origin `<a href>` paths and visible buttons with no NavBlock
-     * URL / Block selector in the loaded library — read via `auto console`.
-     * Deduped per page load so repeated status/send calls stay quiet.
-     */
-    private warnUnmappedInteractions;
-    /** Pure getter - no Block runs, no mem/page mutation. */
-    currentSnapshot(): Promise<SessionSnapshot>;
-    /**
-     * Pure getter - reads the live page's structure at the requested fidelity.
-     * No Block runs, no mem/page mutation. `selector` scopes either mode to one
-     * element's subtree; it is a modifier, not a third mode.
-     */
-    inspectDom(opts: InspectDomOptions): Promise<InspectDomResult>;
-    /**
-     * Pure getter - reads the live page's client-side state: localStorage,
-     * sessionStorage, and registered service workers (scope/active URL/state).
-     * Real, direct follow-up to `auto console`'s own gap: a site doing web
-     * push (this target has a real `NOTIFICATION_VAPID` config, confirmed via
-     * `auto dom` earlier) keeps push-subscription/auth state in these places,
-     * not in the rendered DOM `inspectDom` reads.
-     */
-    inspectStorage(): Promise<StorageSnapshot>;
-    /**
-     * Runs one already-resolved Block entry for real - the shared core both
-     * `applyPick` (resolved via a live-menu index) and `applyPath` (resolved
-     * directly by name, bypassing live-menu-visibility entirely - see
-     * `applyPath`'s own comment for why) call. `expectedTo` is only used as a
-     * fallback when a Block's own `resolve()` doesn't set `__state` - same
-     * behavior `applyPick` always had, just factored out, not changed.
-     */
-    /** Paint + log a Block's authored waygraph overlay fixtures (same as demo does), best-effort. */
-    private paintStubPhase;
-    private runNamedBlock;
-    /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
-    applyPick(raw: string): Promise<ApplyPickResult>;
-    /**
-     * Re-discovers the project's Block library and graph from disk, using the
-     * exact same call `start()` itself makes - not a duplicated read - and
-     * replaces `this.library`/`this.graph` in place. Leaves the live page,
-     * mem, browser/context, and current Checkpoint (`here`) untouched, so a
-     * Block written to disk mid-session becomes pickable via a later
-     * `applyPick` without restarting the session. See
-     * openspec/changes/waygraph-blind-pilot/design.md.
-     */
-    reloadLibrary(): Promise<void>;
-    /**
-     * Forces `here` to be re-detected from the real live page, discarding
-     * whatever was cached - the fix for a real, confirmed gap: `here` is only
-     * ever updated by an action this class itself ran (`applyPick`/`applyPath`
-     * set it to a Block's own resolved Checkpoint; `rawClick`/`rawType`/
-     * `rawGoto` reset it to `null` because *they* just changed the page). If a
-     * human co-driving the same visible session clicks/types/navigates
-     * directly - a real scenario for a headful Pilot session someone is
-     * watching, not hypothetical - none of that goes through this class at
-     * all, so `here` silently goes stale: `currentMenu()`'s own lazy check
-     * (`if (this.here === null)`, just above) only re-detects when `here` is
-     * already unknown, never to confirm a *known* value is still correct.
-     * This does not crash the session (the process/socket/page all stay
-     * alive) but subsequent `send`/`reach` calls would act on a menu built
-     * from the wrong Checkpoint until something forces re-detection - this
-     * method is that: unconditionally re-run the same `detectHere` logic the
-     * lazy path already uses, regardless of what `here` currently holds.
-     */
-    resync(): Promise<ApplyPickResult>;
-    /**
-     * Raw interaction primitives for a page no Block covers yet (Blind Pilot -
-     * see openspec/changes/waygraph-blind-pilot). Unlike `applyPick`, the
-     * resulting Checkpoint isn't known ahead of time from a Block's own
-     * `resolve()`, so each of these invalidates the cached `here` (forcing
-     * `currentMenu()`'s existing lazy `detectHere` call to run again) rather
-     * than assuming the page didn't move anywhere a Block now recognizes.
-     * A selector matching nothing is a reported failure, not a silent no-op.
-     */
-    rawClick(selector: string): Promise<ApplyPickResult>;
-    rawType(selector: string, text: string): Promise<ApplyPickResult>;
-    /**
-     * Presses a real key on a real focused element - a real gap found live:
-     * many real inline-edit inputs (no visible Save button at all) commit on
-     * Enter, not on blur/click-elsewhere. `key` is a Playwright key name
-     * (e.g. "Enter", "Escape", "Tab") - same vocabulary as
-     * `page.keyboard.press`, which this wraps.
-     */
-    rawPress(selector: string, key: string): Promise<ApplyPickResult>;
-    rawGoto(url: string): Promise<ApplyPickResult>;
-    /**
-     * Fills a real `<input type="file">` - a built-in stub kind
-     * ("image"/"pdf"/"video", see `stubFilePath`) or a caller-supplied
-     * `filePath` for anything else ("whatever", per the real request this
-     * responds to). Same raw-primitive shape as click/type/goto: works with
-     * zero Blocks, invalidates `here` since the app may react to the upload.
-     */
-    rawUpload(selector: string, stub: StubFileKind | {
-        filePath: string;
-    }): Promise<ApplyPickResult>;
-    /**
-     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
-     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
-     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
-     */
-    applyHighlight(fixtures: PilotHighlightFixtures): Promise<{
-        ok: true;
-        painted: number;
-        missing: string[];
-        snapshot: SessionSnapshot;
-    } | {
-        ok: false;
-        error: string;
-    }>;
-    /**
-     * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
-     * of an agent hand-picking one index at a time across many separate
-     * `applyPick` round trips - real, reported pain for any non-trivial task
-     * on a rich graph ("the entire prompts of the day" driving one step per
-     * call).
-     *
-     * Two other designs were tried and rejected by direct reproduction against
-     * live saucedemo.com before this one, both undone by the same root cause:
-     * a `from: "*"` edge (e.g. "Checkout", only clickable once you're actually
-     * on the cart page with items) looks globally reachable to
-     * `findBlockPath`'s static-graph BFS, which has no live-page access and
-     * can't know the edge's real precondition isn't showing yet. Computing the
-     * whole route once upfront names a premature wildcard step immediately;
-     * scoring each live menu option by its static-graph distance to the
-     * target (greedy best-first) doesn't fix it either - a harmless self-loop
-     * Method can score just as well as real progress once wildcard "shortcuts"
-     * are baked into every distance calculation, and the session gets stuck
-     * repeating it.
-     *
-     * The fix that actually works: stop trying to be clever about live-menu
-     * visibility per step, and reuse `auto --blocks <From> <To>`'s own already
-     * -proven approach instead - compute the path ONCE (via
-     * `findBlockPathDetailed`, the same BFS `findBlockPath`/`runChainAuto`
-     * already use, extended to also return each hop's specific edge - see its
-     * own doc comment for why that extra detail is load-bearing, not cosmetic),
-     * then run each Block in it directly via `runNamedBlock`, trusting the
-     * graph the same way `runChain`'s own flow execution already does, not
-     * gated on live-menu visibility at all. The one real difference from
-     * `runChainAuto`: this runs against the session's own already-live
-     * page/context/mem, not a freshly spawned browser - the whole point of
-     * staying in one session. A step whose real precondition genuinely isn't
-     * met still fails loud, naming that step, exactly the way a mis-ordered
-     * `runChain` spec would - and a step that runs without throwing but lands
-     * somewhere other than what its own edge promised (a real, observed case,
-     * not hypothetical - see this method's own test suite) fails loud too,
-     * rather than reporting false success.
-     */
-    applyPath(targetCheckpoint: string): Promise<ApplyPathResult>;
-    close(): Promise<void>;
-}