waygraph 0.15.54 → 0.16.0

package/templates/scaffold/src/map/(external)/mailpit/_methods/open-message.method.block.ts

@@ -1,13 +1,15 @@
 // waygraph-ignore: empty-verify (confirmed by AssertEmailContentBlock right after it in mail-verify.flow.ts)
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { MailpitInbox, MailpitMessageOpen } from "../../../../states/demo.states.js";
-import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { MailpitInbox, MailpitMessageOpen } from "../_states.js";
+import { ExpectedRecipient } from "../_keys.js";
 import { MailpitSel } from "../_sel.js";
 
 /** Opens the newest message for the expected recipient (matched by email, not position). */
-export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOpen>({
+export const OpenMessageBlock = defineMethodBlock({
   name: "open-message",
   description: "Opens the newest message addressed to the expected recipient.",
+  from: MailpitInbox,
+  to: MailpitMessageOpen,
   requires: [ExpectedRecipient.key],
   instruction: {
     async act(page, _in, mem) {
@@ -25,6 +27,5 @@ export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOp
         timeout: 15_000,
       });
     },
-    resolve: () => checkpoint("MailpitMessageOpen"),
   },
 });

package/templates/scaffold/src/map/(external)/mailpit/_nav.block.ts

@@ -1,12 +1,12 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { MailpitInbox } from "../../../states/demo.states.js";
+import { MailpitInbox } from "./_states.js";
 
 // Cross-origin, so it lives under (external)/ and the URL is a function.
 const mailpitUrl = (): string => process.env.WAYGRAPH_MAIL_URL ?? "http://127.0.0.1:8025";
 
-export const NavMailpitInboxBlock = defineNavBlock<MailpitInbox>({
+export const NavMailpitInboxBlock = defineNavBlock({
   name: "nav-mailpit-inbox",
-  checkpoint: "MailpitInbox",
+  checkpoint: MailpitInbox,
   url: mailpitUrl,
   verify: [Trait.url({ pathname: "/" })],
 });

package/templates/scaffold/src/map/(external)/mailpit/_page.block.ts

@@ -1,14 +1,14 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { MailpitInbox } from "../../../states/demo.states.js";
+import { MailpitInbox } from "./_states.js";
 import { AssertEmailReceivedBlock } from "./_methods/assert-email-received.method.block.js";
 import { OpenMessageBlock } from "./_methods/open-message.method.block.js";
 import { AssertEmailContentBlock } from "./_methods/assert-email-content.method.block.js";
 import { ExtractEmailLinkBlock } from "./_methods/extract-email-link.method.block.js";
 
-export const MailpitInboxPageBlock = definePageBlock<MailpitInbox>({
+export const MailpitInboxPageBlock = definePageBlock({
   name: "page-mailpit-inbox",
   description: "Mailpit dev inbox hub - confirm arrival/content, open the expected message, read its link.",
-  checkpoint: "MailpitInbox",
+  checkpoint: MailpitInbox,
   verify: [Trait.url({ pathname: "/" })],
   methods: {
     assertEmailReceived: () => AssertEmailReceivedBlock,

package/templates/scaffold/src/map/(external)/mailpit/_states.ts

@@ -0,0 +1,9 @@
+import { checkpoint } from "waygraph";
+
+/** Mailpit inbox UI reached; message list visible. */
+export const MailpitInbox = checkpoint("MailpitInbox");
+export type MailpitInbox = typeof MailpitInbox;
+
+/** The message addressed to the expected recipient is open; preview iframe visible. */
+export const MailpitMessageOpen = checkpoint("MailpitMessageOpen");
+export type MailpitMessageOpen = typeof MailpitMessageOpen;

package/templates/scaffold/src/map/README.md

@@ -24,6 +24,13 @@ real URL. `waygraph map`/`waygraph check` fail loudly if a page folder's real UR
 matching its own name - that's the point of this layout: drift becomes a build failure, not a
 silent surprise months later.
 
+## A group that owns its states: a map package
+
+A folder with its own `_states.ts` (and `_keys.ts`), like `(external)/hoppscotch/`, is a self-contained map: its files
+import only `waygraph` and each other (`waygraph check` warns otherwise). `waygraph map pack hoppscotch` compiles it into
+`.waygraph/packages/hoppscotch` - publish that, `npm i` it in another project, and its Blocks show up there in `graph`,
+`auto`, the manifest and flows (`import { SetUrlBlock } from "waygraph-map-hoppscotch"`).
+
 ## Adding a page
 
 Copy an existing page folder, keep the four fixed names, update `_nav`/`_page`/`_sel` for the

package/templates/scaffold/src/states/README.md

@@ -3,7 +3,7 @@
 Checkpoint types and Mem keys - the typed vocabulary every Block in `src/map/` is written
 against. Nothing here drives the browser; this is pure data shape.
 
-- `*.states.ts` - `type X = Checkpoint<"X">` declarations. One per real app state
+- `*.states.ts` - Checkpoint values: `export const X = checkpoint("X"); export type X = typeof X;`. One per real app state
   (`LoginPage`, `LoggedIn`), never `Checkpoint<string>` (a wildcard - `waygraph check` warns
   on it; a Block should say exactly which states it moves between).
 - `*.mem-keys.ts` - `key<T>("...")` / `keyGroup<T>("...")` declarations. A Mem key stores a
@@ -13,3 +13,6 @@ against. Nothing here drives the browser; this is pure data shape.
 
 Add a new Checkpoint or Mem key here before writing the Block that needs it - Blocks import
 from this directory, this directory never imports from `src/map/`.
+
+A tool on another origin (`src/map/(external)/mailpit/`, `.../hoppscotch/`) keeps its own Checkpoints and keys in its
+folder (`_states.ts`, `_keys.ts`) instead, so the folder can be packed and reused: `waygraph map pack mailpit`.

package/templates/scaffold/src/states/demo.mem-keys.ts

@@ -1,32 +1,4 @@
-import { key, keyGroup } from "waygraph";
+import { keyGroup } from "waygraph";
 
 /** The catalog row `add-item` / `remove-item` act on; `waygraph auto` fills it from `instanceOptions`. */
 export const SelectedItem = keyGroup<{ id: string; name: string }>("demo.selectedItem");
-
-/** The link read out of the opened message - set by extract-email-link. */
-export const EmailLink = keyGroup<{ url: string }>("demo.emailLink");
-
-/** Matched by email, not inbox position, so one inbox can hold several recipients' mail. */
-export const ExpectedRecipient = keyGroup<{ email: string }>("demo.expectedRecipient");
-
-/** Substring the link's `href` must contain; mem varies per scenario, the Blocks do not. */
-export const ExpectedLinkPattern = key<string>("demo.expectedLinkPattern");
-
-/** Substring the open message's body must contain. */
-export const ExpectedEmailContent = key<string>("demo.expectedEmailContent");
-
-export const RequestMethod = key<string>("demo.requestMethod");
-export const RequestUrl = key<string>("demo.requestUrl");
-export const RequestHeaders = key<Record<string, string>>("demo.requestHeaders");
-export const RequestParams = key<Record<string, string>>("demo.requestParams");
-export const RequestBearerToken = key<string>("demo.requestBearerToken");
-/** Raw JSON text typed into the request body editor. */
-export const RequestBody = key<string>("demo.requestBody");
-export const ExpectedStatus = key<number>("demo.expectedStatus");
-/** Substring the response body must contain. */
-export const ExpectedResponseText = key<string>("demo.expectedResponseText");
-/** The raw response body, set by read-response-body. */
-export const ResponseBody = key<string>("demo.responseBody");
-/** Response headers (lower-cased names), set by read-response-headers. */
-export const ResponseHeaders = key<Record<string, string>>("demo.responseHeaders");
-export const ExpectedResponseHeader = keyGroup<{ name: string; value: string }>("demo.expectedResponseHeader");

package/templates/scaffold/src/states/demo.states.ts

@@ -1,23 +1,17 @@
-import type { Checkpoint } from "waygraph";
+import { checkpoint } from "waygraph";
 
-export type Home = Checkpoint<"Home">;
-export type HomeVerified = Checkpoint<"HomeVerified">;
-export type ItemInCart = Checkpoint<"ItemInCart">;
-export type CartEmpty = Checkpoint<"CartEmpty">;
-/** Anywhere an item can be added from: fresh on Home, or after the cart was emptied. */
-export type CanAddItem = Home | CartEmpty;
-
-// --- Mailpit (external tool surface, src/map/(external)/mailpit/) ---
-
-/** Mailpit inbox UI reached; message list visible. */
-export type MailpitInbox = Checkpoint<"MailpitInbox">;
+export const Home = checkpoint("Home");
+export type Home = typeof Home;
+export const HomeVerified = checkpoint("HomeVerified");
+export type HomeVerified = typeof HomeVerified;
+export const ItemInCart = checkpoint("ItemInCart");
+export type ItemInCart = typeof ItemInCart;
+export const CartEmpty = checkpoint("CartEmpty");
+export type CartEmpty = typeof CartEmpty;
 
-/** The message addressed to the expected recipient is open; preview iframe visible. */
-export type MailpitMessageOpen = Checkpoint<"MailpitMessageOpen">;
-
-// --- Hoppscotch (external API client, src/map/(external)/hoppscotch/) ---
-
-export type HoppscotchSettings = Checkpoint<"HoppscotchSettings">;
-export type HoppscotchRest = Checkpoint<"HoppscotchRest">;
+/** Anywhere an item can be added from: fresh on Home, or after the cart was emptied. */
+export const CanAddItem = [Home, CartEmpty] as const;
+export type CanAddItem = (typeof CanAddItem)[number];
 
-export type Docs = Checkpoint<"Docs">;
+export const Docs = checkpoint("Docs");
+export type Docs = typeof Docs;

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/verbose-log.js

@@ -1,16 +0,0 @@
-/**
- * One log format for every overlay surface (demo / auto / browser / pilot): `waygraph <surface>: ...`
- * with a `HH:MM:SS.mmm` prefix, same shape as `runner/demo-log.js`'s (demo stays on the JS copy since
- * it runs in the target project's own process; this one is for TS-side code — pilot/auto/browser —
- * that can't import a plain .js runner module). Silenced by WAYGRAPH_JSON=1, same convention as demo.
- */
-function ts() {
-    const d = new Date();
-    const p = (n) => String(n).padStart(2, "0");
-    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, "0")}`;
-}
-export function verboseLog(surface, msg) {
-    if (process.env.WAYGRAPH_JSON === "1")
-        return;
-    console.log(`[${ts()}] waygraph ${surface}: ${msg}`);
-}

package/dist/auto-session.d.ts

@@ -1,2 +0,0 @@
-export * from "./auto-session/helpers.js";
-export * from "./auto-session/session.js";

package/dist/auto-session.js

@@ -1,3 +0,0 @@
-// Barrel: auto-session lives in src/auto-session/ (see src/ARCHITECTURE.md). Kept so existing imports of "./auto-session.js" don't change.
-export * from "./auto-session/helpers.js";
-export * from "./auto-session/session.js";

package/dist/cli/discover.d.ts

@@ -1,40 +0,0 @@
-export declare function walkDir(dir: string, pattern: RegExp): string[];
-export declare function discoverFlows(projectDir: string): string[];
-export declare function extractFlowNames(filePath: string): string[];
-/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
-export declare function blockExportToLabel(exportId: string): string;
-/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
-export declare function parseBlockImports(filePath: string): string[];
-/** Every `page.goto("...")` string literal in a file, in source order. */
-export declare function extractGotos(filePath: string): string[];
-/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
-export declare function extractUrlTraits(filePath: string): string[];
-export declare function importModule(filePath: string): Promise<Record<string, unknown>>;
-/** Kept as a named alias - `run`/`validate` below were written against this name first. */
-export declare const importFlowFile: typeof importModule;
-export declare function isFlowLike(val: unknown): val is {
-    run: (...args: unknown[]) => Promise<unknown>;
-};
-export declare function discoverBlocks(projectDir: string): string[];
-export declare function isBlockLike(val: unknown): val is {
-    name: string;
-    instruction: {
-        act: unknown;
-    };
-};
-/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
-export declare function isNavBlockMarked(val: Record<string, unknown>): boolean;
-export declare const NAV_METHOD_CALLS: readonly ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
-/**
- * Matches a selector-taking Trait factory call whose first argument is a
- * literal string/template, not an identifier or property access - the exact
- * shape found repeatedly in hand-written assertion Blocks
- * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
- * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
- * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
- * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
- * blind spot on string concatenation/template-built selectors, not solved
- * here for the same "recipe before promotion" reason that check accepts its
- * own shared-helper blind spot.
- */
-export declare const INLINE_SELECTOR_CALL: RegExp;

package/dist/cli/discover.js

@@ -1,148 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-// ---------------------------------------------------------------------------
-// Filesystem
-// ---------------------------------------------------------------------------
-export function walkDir(dir, pattern) {
-    const results = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
-                continue;
-            results.push(...walkDir(full, pattern));
-        }
-        else if (pattern.test(entry.name)) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-export function discoverFlows(projectDir) {
-    return walkDir(projectDir, /\.flow\.ts$/);
-}
-// ---------------------------------------------------------------------------
-// Static analysis for `list`/`nav` (no import, regex only)
-// ---------------------------------------------------------------------------
-export function extractFlowNames(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const names = [];
-    const re = /export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*[=:]/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        const name = m[1];
-        if (name !== undefined)
-            names.push(name);
-    }
-    return names;
-}
-/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
-export function blockExportToLabel(exportId) {
-    const base = exportId.replace(/Block$/, "");
-    return base
-        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
-        .toLowerCase();
-}
-/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
-export function parseBlockImports(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const names = [];
-    const re = /import\s*\{([^}]*)\}\s*from\s*["'][^"']*\.block(?:\.js)?["']/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        for (const part of m[1].split(",")) {
-            const name = part.trim().split(/\s+as\s+/)[0]?.trim();
-            if (name)
-                names.push(name);
-        }
-    }
-    return names;
-}
-/** Every `page.goto("...")` string literal in a file, in source order. */
-export function extractGotos(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const results = [];
-    const re = /\.goto\(\s*["'`]([^"'`]*)["'`]/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        const url = m[1];
-        if (url !== undefined)
-            results.push(url);
-    }
-    return results;
-}
-/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
-export function extractUrlTraits(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const results = [];
-    const re = /Trait\.url\(\s*\{[^}]*pathname:\s*["'`]([^"'`]*)["'`]/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        const url = m[1];
-        if (url !== undefined)
-            results.push(url);
-    }
-    return results;
-}
-// ---------------------------------------------------------------------------
-// Dynamic import + validation
-// ---------------------------------------------------------------------------
-export async function importModule(filePath) {
-    const url = new URL(`file://${resolve(filePath)}`);
-    return (await import(url.href));
-}
-/** Kept as a named alias - `run`/`validate` below were written against this name first. */
-export const importFlowFile = importModule;
-export function isFlowLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    return typeof obj.run === "function";
-}
-// ---------------------------------------------------------------------------
-// `check` - secondary/complementary to the ActionPage @deprecated warning
-// (src/types.ts). That's the primary, always-on signal an editor shows the
-// instant a regular Block's act() calls a navigation method; this command
-// sweeps a whole project in one shot for contexts with no editor watching
-// (CI, an autonomous agent writing Block files without a language server).
-// See openspec/specs/nav-block-and-check/spec.md for the full rationale.
-// ---------------------------------------------------------------------------
-export function discoverBlocks(projectDir) {
-    return walkDir(projectDir, /\.block\.ts$/);
-}
-export function isBlockLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    if (typeof obj.name !== "string")
-        return false;
-    const instruction = obj.instruction;
-    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
-}
-/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
-export function isNavBlockMarked(val) {
-    return val.__waygraphKind === "nav";
-}
-export const NAV_METHOD_CALLS = ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
-/**
- * Matches a selector-taking Trait factory call whose first argument is a
- * literal string/template, not an identifier or property access - the exact
- * shape found repeatedly in hand-written assertion Blocks
- * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
- * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
- * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
- * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
- * blind spot on string concatenation/template-built selectors, not solved
- * here for the same "recipe before promotion" reason that check accepts its
- * own shared-helper blind spot.
- */
-export const INLINE_SELECTOR_CALL = /\b(?:Trait\.visible|Trait\.text|textEquals|visible)\(\s*["'`]/;

package/dist/commands/agent-dive.js

@@ -1,52 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { runAgentDive } from "./agent-dive-scaffold.js";
-import { resolve } from "node:path";
-import { existsSync, statSync } from "node:fs";
-export async function agentDiveCase(args) {
-    // Playwright analogue: npx playwright init-agents --loop <provider>
-    const rest = args.slice(1);
-    let loop = "claude";
-    let prompts = false;
-    let projectDir = process.cwd();
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === "--prompts") {
-            prompts = true;
-            continue;
-        }
-        if (a === "--loop" || a.startsWith("--loop=")) {
-            const v = a.startsWith("--loop=") ? a.slice("--loop=".length) : rest[++i];
-            if (!v || !["claude", "opencode", "cursor", "vscode"].includes(v)) {
-                console.error("waygraph agent-dive: --loop must be claude | opencode | cursor | vscode");
-                process.exit(1);
-            }
-            loop = v;
-            continue;
-        }
-        if (a === "--help" || a === "-h") {
-            console.log(`waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts] [project]
-
-Initialize coding-agent definitions for diving an app into waygraph Blocks
-(Playwright \`init-agents\` analogue).
-
-  --loop claude     write .claude/agents/*.md (default)
-  --loop opencode   write .opencode/prompts/*.md
-  --loop cursor     write .cursor/rules/waygraph-*.mdc
-  --loop vscode     write .github/agents/*.md
-  --prompts         also copy docs/waygraph-agents/*.md
-
-Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
-`);
-            process.exit(0);
-        }
-        if (!a.startsWith("-")) {
-            projectDir = resolve(a);
-        }
-    }
-    if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
-        console.error(`waygraph agent-dive: no such directory: ${projectDir}`);
-        process.exit(1);
-    }
-    runAgentDive({ loop, projectDir, prompts });
-    return;
-}