waygraph 0.15.51 → 0.15.52

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/hoppscotch-get.flow.js";
+import { hoppscotchAuthFlow } from "../src/flows/hoppscotch-auth.flow.js";
+import { hoppscotchPostFlow } from "../src/flows/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

@@ -6,17 +6,8 @@ import { mailVerifyFlow } from "../src/flows/mail-verify.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 mailVerifyFlow 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"], {

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,33 @@ 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()`** (`.start().gotoPage(Nav).method(B).assert(A).end({ ... })`; `.gotoExternal` for another origin),
+  not a raw `defineFlow([start, ...])` array. Flow settings go in `.end`'s options:
+  `.end({ title: "Shop", memStub: true, sessionReset: true })`. Never `withMemStub(withTitle(withSessionReset(...)))`.
+  (`defineFlow(blocks, options)` takes the same options.)
+- **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.
+- **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.
+- **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: {...} })`). Flows import it and build the Engine from it (`new Engine(config)`); 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`.
+
 ## Block kinds (file convention)
 
 | Kind | File | Helper | `page.goto`? |
@@ -113,8 +143,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",
-  },
-});