waygraph 0.15.51 → 0.15.53

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

@@ -4,17 +4,7 @@ import type { MailpitInbox, MailpitMessageOpen } from "../../../../states/demo.s
 import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";
 import { MailpitSel } from "../_sel.js";
 
-/**
- * Kind: Method
- * Helper: defineMethodBlock
- * Route: demo-external/mailpit/_methods/
- *
- * Opens the newest inbox row addressed to the mem-set recipient (not bare
- * inbox position - a prior run's leftover mail for a different recipient
- * would otherwise pick the wrong row). UI click only, no mail-catcher REST
- * API - the row itself is a real link (`page.waitForURL` sees the client-side
- * route change the same as any other in-page navigation).
- */
+/** Opens the newest message for the expected recipient (matched by email, not position). */
 export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOpen>({
   name: "open-message",
   description: "Opens the newest message addressed to the expected recipient.",

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

@@ -1,15 +1,7 @@
 import { defineNavBlock, Trait } from "waygraph";
 import type { MailpitInbox } from "../../../states/demo.states.js";
 
-/**
- * Kind: Nav
- * Helper: defineNavBlock
- * Route: (external)/mailpit/  (cross-origin - a real Mailpit web UI, not this app)
- *
- * Cross-origin tooling lives under (external)/, never (app_base)/ - this is
- * a dev-inbox screen, not part of the app under test. `WAYGRAPH_MAIL_URL`
- * defaults to Mailpit's own usual local port.
- */
+// 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>({

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

@@ -5,17 +5,6 @@ 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";
 
-/**
- * Kind: Page
- * Helper: definePageBlock
- * Route: (external)/mailpit/  (= http://127.0.0.1:8025/ by default)
- *
- * Hub for the Mailpit dev-inbox screen. Arrival-only (no url/click) -
- * nav-mailpit-inbox owns the goto. Methods: confirm the email arrived, open
- * it, confirm its content, then read its link - all mem-driven (recipient,
- * link pattern, expected content), so this one page's methods serve any
- * number of different email scenarios, not just one.
- */
 export const MailpitInboxPageBlock = definePageBlock<MailpitInbox>({
   name: "page-mailpit-inbox",
   description: "Mailpit dev inbox hub - confirm arrival/content, open the expected message, read its link.",

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

@@ -1,31 +1,32 @@
 import { key, keyGroup } from "waygraph";
 
-/**
- * Which catalog row `add-item` / `remove-item` act on.
- * `waygraph auto` fills this via Effect `instanceOptions` (one menu row per live button).
- */
+/** 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");
 
-/**
- * The recipient open-message looks for in the inbox. Mailpit lists newest
- * first, but `.first()` alone picks the wrong row once more than one
- * recipient's mail is sitting in the same inbox - match by mem, not position.
- */
+/** 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 - lets the same extract-email-link
- * Block serve any number of different email templates/scenarios in one
- * project without a new Block per scenario. Only the mem values change per
- * run, not the Blocks.
- */
+/** Substring the link's `href` must contain; mem varies per scenario, the Blocks do not. */
 export const ExpectedLinkPattern = key<string>("demo.expectedLinkPattern");
 
-/**
- * The substring the open message's body must contain - same reuse reasoning
- * as ExpectedLinkPattern: one Block, many scenarios, driven by mem.
- */
+/** 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.mem-stubs.ts

@@ -0,0 +1,4 @@
+import { registerMemStub } from "waygraph";
+import { SelectedItem } from "./demo.mem-keys.js";
+
+registerMemStub(SelectedItem.key, () => ({ id: "alpha", name: "Alpha" }));

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

@@ -15,5 +15,9 @@ export type MailpitInbox = Checkpoint<"MailpitInbox">;
 /** The message addressed to the expected recipient is open; preview iframe visible. */
 export type MailpitMessageOpen = Checkpoint<"MailpitMessageOpen">;
 
-/** Reached via src/map/(app_base)/docs/ - see openspec/changes/waygraph-map. */
+// --- Hoppscotch (external API client, src/map/(external)/hoppscotch/) ---
+
+export type HoppscotchSettings = Checkpoint<"HoppscotchSettings">;
+export type HoppscotchRest = Checkpoint<"HoppscotchRest">;
+
 export type Docs = Checkpoint<"Docs">;

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

@@ -1,17 +1,16 @@
 import { test, expect } from "@playwright/test";
-import { MemPage, checkpoint } from "waygraph";
-import { exampleFlow } from "../src/flows/example.flow.js";
-import { shopFlow } from "../src/flows/shop.flow.js";
-import { SelectedItem } from "../src/states/demo.mem-keys.js";
+import { MemPage, checkpoint, seedMemStub } from "waygraph";
+import { homeHelloFlow } from "../src/flows/home/hello.flow.js";
+import { homeCartFlow } from "../src/flows/home/cart.flow.js";
 
 test("example flow reaches Docs (home -> assert -> sibling docs/ page)", async ({ context }) => {
-  const result = await exampleFlow.run(context, new MemPage());
+  const result = await homeHelloFlow.run(context, new MemPage());
   expect(result).toEqual(checkpoint("Docs"));
 });
 
 test("shop flow adds then clears (Effect + Method)", async ({ context }) => {
   const mem = new MemPage();
-  mem.set(SelectedItem.key, { id: "alpha", name: "Alpha" });
-  const result = await shopFlow.run(context, mem);
+  seedMemStub(mem, homeCartFlow);
+  const result = await homeCartFlow.run(context, mem);
   expect(result).toEqual(checkpoint("CartEmpty"));
 });

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

@@ -0,0 +1,97 @@
+import { test, expect } from "@playwright/test";
+import { createServer, type Server } from "node:http";
+import { MemPage, checkpoint } from "waygraph";
+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";
+
+// The API under test: no CORS headers, so only the extension can reach it from hoppscotch.io.
+let server: Server;
+let apiUrl: string;
+
+test.beforeAll(async () => {
+  server = createServer((req, res) => {
+    let body = "";
+    req.on("data", (chunk) => (body += chunk));
+    req.on("end", () => {
+      res.statusCode = req.method === "POST" ? 201 : 200;
+      res.setHeader("content-type", "application/json");
+      res.setHeader("x-request-id", "req-42");
+      res.end(JSON.stringify({ method: req.method, url: req.url, token: req.headers["x-token"], auth: req.headers.authorization, body }));
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  apiUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}/items`;
+});
+
+test.afterAll(() => server.close());
+
+test.skip(!config.extensions?.includes("hoppscotch"), 'add extensions: ["hoppscotch"] to config/waygraph.config.ts to run these');
+test.setTimeout(120_000);
+
+test("GET returns 200", async () => {
+  const mem = new MemPage();
+  mem.set(RequestUrl, apiUrl);
+  mem.set(ExpectedStatus, 200);
+  expect(await hoppscotchGetFlow.run(mem, {})).toEqual(checkpoint("HoppscotchRest"));
+});
+
+test("POST sends the header and JSON body, returns 201", async () => {
+  const mem = new MemPage();
+  mem.set(RequestMethod, "POST");
+  mem.set(RequestUrl, apiUrl);
+  mem.set(RequestHeaders, { "x-token": "abc123" });
+  mem.set(RequestBody, '{"name":"waygraph"}');
+  mem.set(ExpectedStatus, 201);
+  mem.set(ExpectedResponseText, '"token":"abc123"');
+  expect(await hoppscotchPostFlow.run(mem, {})).toEqual(checkpoint("HoppscotchRest"));
+});
+
+test("a wrong expected status fails the flow, naming assert-status", async () => {
+  const mem = new MemPage();
+  mem.set(RequestUrl, apiUrl);
+  mem.set(ExpectedStatus, 404);
+  await expect(hoppscotchGetFlow.run(mem, {})).rejects.toThrow(/assert-status/);
+});
+
+test("a response body without the expected text fails the flow, naming assert-response-body", async () => {
+  const mem = new MemPage();
+  mem.set(RequestMethod, "POST");
+  mem.set(RequestUrl, apiUrl);
+  mem.set(RequestHeaders, { "x-token": "abc123" });
+  mem.set(RequestBody, '{"name":"waygraph"}');
+  mem.set(ExpectedStatus, 201);
+  mem.set(ExpectedResponseText, '"token":"nope"');
+  await expect(hoppscotchPostFlow.run(mem, {})).rejects.toThrow(/assert-response-body/);
+});
+
+const authMem = (headerValue: string): MemPage => {
+  const mem = new MemPage();
+  mem.set(RequestUrl, apiUrl);
+  mem.set(RequestParams, { q: "waygraph" });
+  mem.set(RequestBearerToken, "tok-9");
+  mem.set(ExpectedStatus, 200);
+  mem.set(ExpectedResponseText, '"url":"/items?q=waygraph","auth":"Bearer tok-9"');
+  mem.set(ExpectedResponseHeader({ name: "X-Request-Id", value: headerValue }));
+  return mem;
+};
+
+test("query params and a bearer token reach the API; a response header is checked", async () => {
+  expect(await hoppscotchAuthFlow.run(authMem("req-42"), {})).toEqual(checkpoint("HoppscotchRest"));
+});
+
+test("a wrong response header value fails the flow, naming assert-response-header", async () => {
+  await expect(hoppscotchAuthFlow.run(authMem("other"), {})).rejects.toThrow(/assert-response-header/);
+});

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

@@ -2,21 +2,12 @@ import { test, expect } from "@playwright/test";
 import { spawnSync } from "node:child_process";
 import net from "node:net";
 import { MemPage, checkpoint } from "waygraph";
-import { mailVerifyFlow } from "../src/flows/mail-verify.flow.js";
+import { emailVerificationFlow } from "../src/flows/(user-stories)/email-verification.flow.js";
 import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/states/demo.mem-keys.js";
 import { HOME_URL } from "../src/map/(app_base)/home/_sel.js";
 
-/**
- * This scaffold has no real backend, so these tests play the role of "the
- * app sent a verification email" themselves: spin up a real, throwaway
- * Mailpit container, send a real SMTP message, then run mailVerifyFlow for
- * real - a real cross-origin browser hop into Mailpit's own web UI and
- * back, no mail-catcher REST API anywhere. Covers the happy path, both
- * failure paths its QA-facing asserts exist for (no email arrived, wrong
- * content), and - the actual point of making the mail-reading Blocks
- * mem-driven - a second, entirely different email scenario running through
- * the exact same four Blocks with zero new code.
- */
+// Plays "the app sent a verification email": starts a throwaway Mailpit container, sends a real SMTP message,
+// then runs emailVerificationFlow against it, including the no-email and wrong-content failure paths.
 
 function runMailpit(): { containerId: string; smtpPort: number; httpPort: number } {
   const run = spawnSync("docker", ["run", "--rm", "-d", "-p", "0:1025", "-p", "0:8025", "axllent/mailpit"], {
@@ -89,7 +80,7 @@ async function withMailpit<T>(fn: (opts: { httpPort: number; smtpPort: number })
 
 const VERIFICATION_CONTENT = "Please confirm your email address to finish setting up your account.";
 
-test("mailVerifyFlow: confirms arrival, confirms content, reads the real link, navigates to it", async ({
+test("emailVerificationFlow: confirms arrival, confirms content, reads the real link, navigates to it", async ({
   context,
 }) => {
   test.skip(!dockerAvailable(), "Docker not reachable in this environment");
@@ -109,7 +100,7 @@ test("mailVerifyFlow: confirms arrival, confirms content, reads the real link, n
     mem.set(ExpectedRecipient({ email: recipient }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
-    const result = await mailVerifyFlow.run(context, mem);
+    const result = await emailVerificationFlow.run(context, mem);
     expect(result).toEqual(checkpoint("HomeVerified"));
   });
 });
@@ -139,7 +130,7 @@ test("the same four mail-reading Blocks handle a second, unrelated email scenari
     mem.set(ExpectedRecipient({ email: recipient }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, resetContent);
-    const result = await mailVerifyFlow.run(context, mem);
+    const result = await emailVerificationFlow.run(context, mem);
     expect(result).toEqual(checkpoint("HomeVerified"));
   });
 });
@@ -158,7 +149,7 @@ test("assert-email-received fails loud, naming itself, when no email ever arrive
     // 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
     // exact "failed after \"assert-email-received\"" alone.
-    await expect(mailVerifyFlow.run(context, mem)).rejects.toThrow(
+    await expect(emailVerificationFlow.run(context, mem)).rejects.toThrow(
       /trait "email-received" failed after ".*assert-email-received"/,
     );
   });
@@ -184,7 +175,7 @@ test("assert-email-content fails loud, naming itself, when the email's copy does
     mem.set(ExpectedRecipient({ email: recipient }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
-    await expect(mailVerifyFlow.run(context, mem)).rejects.toThrow(
+    await expect(emailVerificationFlow.run(context, mem)).rejects.toThrow(
       /trait "body-contains-expected-text" failed after ".*assert-email-content"/,
     );
   });

package/templates/scaffold/tsconfig.json

@@ -10,5 +10,5 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts"]
+  "include": ["config/**/*.ts", "src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts"]
 }

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

@@ -17,6 +17,9 @@ against a live site, use `--skill-pilot-blind`.
 2. **Navigation only inside Nav.** `page.goto` / NavBlock `click` live in
    `defineNavBlock` / `defineNavClickBlock` only. Method/Effect `act` uses ActionPage
    (no goto) even when the app changes URL as a side effect of a button click.
+   A Nav for a page that only exists after something else (every in-app page after sign-in)
+   declares `from: [...]` with the Checkpoints it is valid from (a `SIGNED_IN` list in
+   `src/states/`); without it, routing jumps there from anywhere, skipping sign-in.
 3. **Selectors in `*Sel`, never inline.** DOM strings live in a `*Sel` next to the page - `_sel.ts`
    in the Map layout (one per page folder, next to `_nav`/`_page`/`_methods`), `<name>.sel.ts` in a
    freeform layout (one per concern) - never a fresh file-naming convention per project (`_sel.ts`,
@@ -39,7 +42,7 @@ against a live site, use `--skill-pilot-blind`.
 5. **`requires` = externally supplied.** A key an earlier Block in the same chain produces
    is never listed under `requires` - preflight checks the whole chain up front. For a
    genuinely arbitrary key (a username, an email) that a demo/dev run shouldn't need
-   hand-supplied every time, `registerMemStub(key, fake)` + `withMemStub(flow)` (or
+   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/`
@@ -63,6 +66,41 @@ against a live site, use `--skill-pilot-blind`.
    when a *different* Block right after it in the `.flow.ts` is what actually confirms the
    transition (e.g. an `AssertXBlock`) - `// waygraph-ignore: empty-verify`.
 
+## 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 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.
+- **`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(...)`.
+- **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(...)`.
+- **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>`.
+  The engine a config exports, and every engine in a flow, follows the selected config.
+- **A browser dialog (`confirm`, `beforeunload`) is answered with `withDialog(block, { accept, into })`**, not inside the
+  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.
+- **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`,
+  `send-request`, `assert-status`, `read-response-body`, `assert-response-body`.
+- **Updating an older project:** `npm install waygraph@latest`, then `waygraph upgrade` (dry run) to see new
+  and differing scaffold files; copy the paths you want with `--apply`. `waygraph upgrade --skills` refreshes these skills.
+
 ## Block kinds (file convention)
 
 | Kind | File | Helper | `page.goto`? |
@@ -113,8 +151,7 @@ src/map/
 - `(group)` parentheses and leading-underscore segments (`_methods/`, `_page…`) are
   **not** URL segments. `waygraph map` excludes them when checking folder-vs-URL.
 - A bare non-underscore folder always means a real child Checkpoint/URL segment.
-- Prefer `map()` over a hand-assembled `defineFlow([start, ...])` when wiring Map Blocks -
-  it rejects Blocks that didn't come from a real factory (no silent teleporting).
+- `map()` rejects Blocks that didn't come from a real factory (no silent teleporting).
 
 Mail / external tools: under `*-external/<tool>/` or `map/(external)/<tool>/`, never under
 the site's `*-web/` tree. Browser-driven (DOM / iframe Traits), not the catcher's REST API.

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

@@ -104,13 +104,12 @@ thing that differs from demo is *who* triggers the paint:
 
 | Mode | Who paints | How |
 |------|------------|-----|
-| `waygraph demo` | Engine, automatically | Block `stubBefore` / `stubAfter` / `withHighlightFixtures` run each step |
+| `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 |
 
-Block-authored `stubBefore` / `withHighlightFixtures` still exist on Blocks in Pilot —
-they show up in `auto trace` as metadata — but they do **not** auto-draw. You re-express
-the same intent with `auto highlight` (copy selectors/labels from the Block stubs or from
-`auto dom`). Paint, then `auto send` the real Block. Clear when done.
+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
+from `auto dom`). Paint, then `auto send` the real Block. Clear when done.
 
 ```
 # Headful watch session (rings visible to a human audience):

package/dist/browser-path.d.ts

@@ -1,5 +0,0 @@
-/**
- * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
- * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
- */
-export declare function chromiumExecutablePath(): string | undefined;

package/dist/browser-path.js

@@ -1,18 +0,0 @@
-import { existsSync } from "node:fs";
-let warned = false;
-/**
- * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
- * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
- */
-export function chromiumExecutablePath() {
-    const path = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
-    if (!path)
-        return undefined;
-    if (existsSync(path))
-        return path;
-    if (!warned) {
-        warned = true;
-        console.error(`waygraph: CHROME_PATH/CHROMIUM_PATH "${path}" does not exist - using Playwright's bundled Chromium`);
-    }
-    return undefined;
-}

package/dist/runner/overlay-present.d.ts

@@ -1,8 +0,0 @@
-import type { Page } from "@playwright/test";
-import type { StubPhaseResult } from "../highlights/types.js";
-
-export interface SessionOverlay {
-  present(tag: string, phase: Partial<StubPhaseResult>): Promise<void>;
-  restore(): Promise<void>;
-}
-export function createSessionOverlay(page: Page, surface: string): SessionOverlay;

package/dist/runner/overlay-present.js

@@ -1,57 +0,0 @@
-// Presents a resolved stub phase ("waygraph overlay fixtures": ctx.todos / device / title / banner ...) on a LIVE page
-// for the session surfaces (auto / browser / pilot). Same OverlayStage + same in-page installers + same verbose log
-// lines as `waygraph demo`, so an overlay fixture behaves identically on every surface. Rings are painted separately
-// (pilot holds them; demo cycles them) - that is the only intended difference.
-import { installOverlay } from "./overlay-install.js";
-import { createOverlayStage } from "./overlay-stage.js";
-import { demoLog, logStubPhaseFixtures, logTodoDockFull, setDemoLogSurface, summarizeDevice } from "./demo-log.js";
-import { logBannerDom, probeBanner } from "./banner-log.js";
-import { probeTodoDocksOnPage } from "./todo-dock.js";
-
-export function createSessionOverlay(page, surface) {
-  setDemoLogSurface(surface);
-  const stage = createOverlayStage(page, { todoDockRef: { current: undefined }, deviceRef: { current: undefined } });
-  let title = undefined;
-  let painted = false;
-
-  const paintChrome = async (phaseParallel) => {
-    await installOverlay(page, title, stage.state.lastBannerUi);
-    await stage.syncAllTodoDocks({ parallel: !!phaseParallel });
-  };
-
-  return {
-    stage,
-    /** Apply one phase (tag = before | after | error | highlight) and log the resulting overlay state. */
-    async present(tag, phase) {
-      setDemoLogSurface(surface);
-      logStubPhaseFixtures(tag, phase);
-      await stage.pushTodoDockUi(phase.todoDockUi);
-      const { appliedTodo, appliedDevice } = await stage.applyPhase(phase, { reapplyDeviceOnKeep: true });
-      if (phase.title && String(phase.title).trim()) title = String(phase.title).trim();
-      const wantsChrome = !!(title || stage.state.lastTodoDock || phase.todoSync === "set");
-      if (wantsChrome) {
-        painted = true;
-        await paintChrome(phase.todoParallel);
-      }
-      logTodoDockFull(stage.state.lastTodoDock, "  " + tag);
-      demoLog("  " + tag + " device=" + summarizeDevice(stage.state.lastDevice) + " deviceSync=" + appliedDevice.sync);
-      demoLog("  " + tag + " todoSync=" + appliedTodo.sync);
-      const docks = await probeTodoDocksOnPage(page);
-      if (!docks.length && stage.state.lastTodoDock && appliedTodo.sync !== "clear") {
-        demoLog("  WARN " + tag + ": todos authored but dock-dom empty (not painted?)");
-      }
-      for (const d of docks) {
-        demoLog(
-          "  " + tag + " dock-dom " + d.key + "@" + d.pos + " " + d.left + "," + d.top + " " + d.w + "x" + d.h +
-            (d.onScreen ? "" : " OFFSCREEN") + " n=" + d.n + (d.current ? ' cur="' + d.current + '"' : ""),
-        );
-      }
-      if (title || painted) logBannerDom(tag, await probeBanner(page));
-    },
-    /** A navigation wipes the overlay DOM: rebuild what was authored (same job as the demo's post-navigation restore). */
-    async restore() {
-      if (!painted) return;
-      await paintChrome(false);
-    },
-  };
-}

package/dist/ui/components/banner.d.ts

@@ -1,2 +0,0 @@
-/** Top-left demo banner (`#wg-banner`). */
-export declare function bannerCss(): string;

package/dist/ui/components/banner.js

@@ -1,10 +0,0 @@
-import { ACCENT_SOFT, SURFACE } from "../tokens.js";
-/** Top-left demo banner (`#wg-banner`). */
-export function bannerCss() {
-    return ("#wg-banner{position:fixed;z-index:2147483647;top:14px;left:14px;" +
-        `background:${SURFACE};color:#fff;border-radius:12px;padding:10px 16px;` +
-        "font:14px/1.4 system-ui,sans-serif;box-shadow:0 8px 20px rgba(0,0,0,.3);" +
-        "border:1px solid rgba(124,58,237,.4);}" +
-        `#wg-banner .wg-banner-tag{display:block;font-size:10px;font-weight:700;color:${ACCENT_SOFT};` +
-        "letter-spacing:.05em;text-transform:uppercase;margin-bottom:2px;}");
-}

package/dist/ui/components/cursor.d.ts

@@ -1,2 +0,0 @@
-/** Travelling mouse cursor + click ripple (`#wg-cursor`, `#wg-click-pulse`). */
-export declare function cursorCss(): string;

package/dist/ui/components/cursor.js

@@ -1,19 +0,0 @@
-import { TONES } from "../tokens.js";
-/** Travelling mouse cursor + click ripple (`#wg-cursor`, `#wg-click-pulse`). */
-export function cursorCss() {
-    const p = TONES.planned;
-    const pulseTones = ["auto", "info", "warning", "danger", "success"]
-        .map((n) => `#wg-click-pulse[data-tone=${n}]{border-color:${TONES[n].ring};background:${TONES[n].pulse};}`)
-        .join("");
-    return ("#wg-cursor{position:fixed;z-index:2147483647;width:24px;height:24px;pointer-events:none;" +
-        "left:0;top:0;opacity:0;margin:0;" +
-        // Travel time is JS-driven via --wg-cursor-ms (a hardcoded duration would make speed a no-op).
-        "transition:transform var(--wg-cursor-ms,600ms) cubic-bezier(.22,1,.36,1),opacity .2s ease;" +
-        "filter:drop-shadow(0 2px 4px rgba(12,12,26,.4));}" +
-        "#wg-click-pulse{position:fixed;z-index:2147483647;width:14px;height:14px;" +
-        "margin-left:-7px;margin-top:-7px;border-radius:50%;pointer-events:none;opacity:0;" +
-        `border:2px solid ${p.ring};background:${p.pulse};}` +
-        pulseTones +
-        "#wg-click-pulse.wg-pulse{animation:wg-pulse .5s ease-out;}" +
-        "@keyframes wg-pulse{0%{opacity:.9;transform:scale(.4);}100%{opacity:0;transform:scale(2.4);}}");
-}

package/templates/scaffold/playwright.config.ts

@@ -1,12 +0,0 @@
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  testDir: "./tests",
-  fullyParallel: true,
-  reporter: [["list"], ["html", { open: "never" }]],
-  use: {
-    // Demo pages open via file:// - no server. Filled in by `waygraph init`.
-    baseURL: "__APP_BASE_URL__",
-    trace: "retain-on-failure",
-  },
-});

package/templates/scaffold/src/flows/example.flow.ts

@@ -1,29 +0,0 @@
-import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
-import { NavHomeBlock } from "../map/(app_base)/home/_nav.block.js";
-import { AssertHelloBlock } from "../map/(app_base)/home/_methods/assert-hello.method.block.js";
-import { NavDocsBlock } from "../map/(app_base)/docs/_nav.block.js";
-// Page hubs registered for auto/docs grouping (arrival-only after nav).
-import "../map/(app_base)/home/_page.block.js";
-import "../map/(app_base)/docs/_page.block.js";
-
-const engine = new Engine();
-
-/** Smoke: nav + assert (no mem), then nav to the sibling docs/ page. Green offline. */
-export const exampleFlow = withHighlightFixtures(
-  withTitle(
-    engine.defineFlow([start, NavHomeBlock, AssertHelloBlock, NavDocsBlock, end]),
-    "Scaffold: Hello Waygraph",
-  ),
-  {
-    "assert-hello": {
-      stubAfter: {
-        title: {
-          label: "AC · Hello visible",
-          detail: "Replace this fixture copy with your ticket lines.",
-          tag: "AC",
-          duration: true,
-        },
-      },
-    },
-  },
-);