waygraph 0.15.51 → 0.15.52

package/dist/runner/inpage/core.js

@@ -72,7 +72,14 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ring.style.width = width + "px";
           ring.style.height = height + "px";
           ring.style.opacity = "1";
-          ringLabel.textContent = label || "";
+          if (labelId === "wg-ring-label") {
+            // The demo ring's caption is drawn from data-label (CSS ::after), not DOM text, so the page's own
+            // text selectors (getByText, text=...) never match waygraph's overlay twice.
+            ringLabel.dataset.label = label || "";
+            ringLabel.textContent = "";
+          } else {
+            ringLabel.textContent = label || "";
+          }
           ringLabel.style.opacity = "1";
           const lw = ringLabel.offsetWidth;
           const lh = ringLabel.offsetHeight;
@@ -104,12 +111,6 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ringLabel.style.top = labelTop + "px";
           return [ring, ringLabel];
         };
-        window.__wgHideRingAt = (ringId, labelId) => {
-          const ring = __wgById(ringId);
-          const label = __wgById(labelId);
-          if (ring) ring.style.opacity = "0";
-          if (label) label.style.opacity = "0";
-        };
         window.__wgEnsureRingEl("wg-ring", "wg-ring-label");
         if (!__wgById("wg-cursor")) {
           const cursor = document.createElement("div");

package/dist/runner/main.js

@@ -10,7 +10,8 @@ import { connect } from "../types.js";
 import { MemPage } from "../mem-page.js";
 import { Engine, start, end, chainFlow, isFastForwardBlock, branchRoutes, runBranchRegression } from "../core.js";
 import { withWebServer } from "../webserver.js";
-import { chromiumExecutablePath } from "../browser-path.js";
+import { resolveVideoDir } from "../video-dir.js";
+import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../browser.js";
 
 async function runMain() {
   const projectDir = process.argv[2];
@@ -252,7 +253,7 @@ async function runMain() {
   const videoEnv = process.env.WAYGRAPH_VIDEO;
   let videoDir = null;
   if (videoEnv) {
-    videoDir = videoEnv === "1" ? join(projectDir, ".waygraph-videos") : videoEnv;
+    videoDir = videoEnv === "1" ? await resolveVideoDir(projectDir) : videoEnv;
     mkdirSync(videoDir, { recursive: true });
   }
   /** Fixed 16:9 capture for --video (demo QA and headless run). Step+video no longer maximizes. */
@@ -290,12 +291,6 @@ async function runMain() {
     const executablePath = chromiumExecutablePath();
     // Maximized for interactive step, and for fixed video viewport so the
     // locked record size can actually fit (otherwise .webm gets grey pad).
-    const browser = await chromium.launch({
-      headless: !headed,
-      slowMo,
-      args: step || fixedVideoViewport ? ["--start-maximized"] : [],
-      ...(executablePath ? { executablePath } : {}),
-    });
     const contextOpts = fixedVideoViewport
       ? {
           baseURL,
@@ -313,7 +308,17 @@ async function runMain() {
         ? { dir: videoDir, size: fixedVideoViewport }
         : { dir: videoDir };
     }
-    const context = await browser.newContext(contextOpts);
+    const { context, close: closeBrowser } = await launchContext({
+      launcher: chromium,
+      launch: {
+        headless: !headed,
+        slowMo,
+        args: step || fixedVideoViewport ? ["--start-maximized"] : [],
+        ...(executablePath ? { executablePath } : {}),
+      },
+      context: contextOpts,
+      extensions: extensionPathsFromEnv(),
+    });
     let pageForVideo = null;
     try {
       if (step) {
@@ -369,7 +374,7 @@ async function runMain() {
       if (savedVideo) {
         console.log("waygraph: video saved to " + savedVideo);
       }
-      await browser.close();
+      await closeBrowser();
     }
   } else {
     if (chainFlows && chainFlows.length > 0) {
@@ -421,6 +426,9 @@ async function runAllBranchesMode(chainFlows, mem, baseURL, headed, engine) {
     process.exitCode = 1;
     return;
   }
+  if (extensionPathsFromEnv().length > 0) {
+    console.warn("waygraph run --all-branches: extensions are not loaded (branches run in cloned contexts)");
+  }
   const { chromium } = await import("@playwright/test");
   const browser = await chromium.launch({ headless: !headed });
   const cloneSession = process.env.WAYGRAPH_SHARED_SESSION !== "1";

package/dist/runner/rings.js

@@ -381,55 +381,6 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
 }
 
 
-/**
- * Paint a NAMED ring instance (ui/css/ring.css's shared `.wg-ring-el`/`.wg-ring-el-label`) at a
- * known viewport box - the primitive both the demo/auto singleton (`showRing`, always "wg-ring")
- * and Pilot's several simultaneous fixture rings (their own ids) paint through, so there is one
- * ring-rendering implementation, not two. No collision/follow/focus - those are `#wg-ring`'s own
- * extras (see `showRing`/`inpage/core.js`'s `__wgPositionRing`), meaningless for an independent
- * fixture ring that isn't "the current action."
- */
-export async function showRingAt(page, ringId, labelId, box, label, tone, style) {
-  const size = normalizeHighlightSize(style && style.size);
-  const weight = normalizeHighlightWeight(style && style.weight);
-  const color = style && style.color ? String(style.color) : "";
-  await page
-    .evaluate(
-      ({ ringId, labelId, box, label, tone, size, weight, color }) => {
-        if (window.__wgPaintRingAt) {
-          window.__wgPaintRingAt(ringId, labelId, box, label, tone, { size, weight, color });
-        }
-      },
-      { ringId, labelId, box, label, tone: tone || "planned", size, weight, color },
-    )
-    .catch(() => {});
-}
-
-/** Hide (not remove) a named ring instance painted via {@link showRingAt}. */
-export async function hideRingAt(page, ringId, labelId) {
-  await page
-    .evaluate(
-      ({ ringId, labelId }) => {
-        if (window.__wgHideRingAt) window.__wgHideRingAt(ringId, labelId);
-      },
-      { ringId, labelId },
-    )
-    .catch(() => {});
-}
-
-/** Remove a named ring instance entirely (Pilot's fixture rings are short-lived, not reused). */
-export async function removeRingAt(page, ringId, labelId) {
-  await page
-    .evaluate(
-      ({ ringId, labelId }) => {
-        __wgById(ringId)?.remove();
-        __wgById(labelId)?.remove();
-      },
-      { ringId, labelId },
-    )
-    .catch(() => {});
-}
-
 export async function showRing(page, box, label, tone, style) {
   const size = normalizeHighlightSize(style && style.size);
   const weight = normalizeHighlightWeight(style && style.weight);

package/dist/session/auto-explore-run.js

@@ -5,9 +5,9 @@ import { Engine, start, end, locate } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { installDemoChrome, instrumentInteractionHighlighting } from "./step-overlay.js";
-import { resolveBaseUrl } from "../config.js";
+import { configuredExtensions, resolveBaseUrl } from "../config.js";
 import { withWebServer } from "../webserver.js";
-import { chromiumExecutablePath } from "../browser-path.js";
+import { chromiumExecutablePath, launchContext } from "../browser.js";
 /** See `../config.js`'s own `resolveBaseUrl` - re-exported so existing importers of this module
  * don't need to change their import path. */
 export { resolveBaseUrl };
@@ -587,13 +587,17 @@ async function runAutoExploreCore(projectDir, options = {}) {
         launchOpts.slowMo = 250;
     if (executablePath)
         launchOpts.executablePath = executablePath;
-    const browser = await chromium.launch(launchOpts);
     const contextOpts = cli
         ? { viewport: { width: 1280, height: 720 } }
         : { viewport: null };
     if (baseURL)
         contextOpts.baseURL = baseURL;
-    const context = await browser.newContext(contextOpts);
+    const { close: closeBrowser, context } = await launchContext({
+        launcher: chromium,
+        launch: launchOpts,
+        context: contextOpts,
+        extensions: await configuredExtensions(projectDir),
+    });
     let page = await context.newPage();
     if (startUrl) {
         await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
@@ -692,6 +696,6 @@ async function runAutoExploreCore(projectDir, options = {}) {
     finally {
         cliRl?.close();
         await context.close();
-        await browser.close();
+        await closeBrowser();
     }
 }

package/dist/session/auto-explore.js

@@ -169,7 +169,7 @@ export function exploreChoices(graph, here) {
     const out = [];
     for (const edge of graph.edges) {
         if (here === null) {
-            if (edge.kind !== "nav")
+            if (edge.kind !== "nav" || edge.from !== "*")
                 continue;
         }
         else if (edge.from !== here && edge.from !== "*") {
@@ -283,8 +283,9 @@ export async function buildExploreMenu(page, graph, library, here) {
             continue;
         if (here === null) {
             // Bootstrap only: URL deep-links as "Start here". Click-nav needs a live
-            // control so it cannot seed an unknown page.
-            if (!isUrlNav(entry))
+            // control so it cannot seed an unknown page, and a Nav with `from` needs
+            // that state first (e.g. signed in) so it cannot start one either.
+            if (!isUrlNav(entry) || edge.from !== "*")
                 continue;
             push(navigate, edge);
             continue;
@@ -295,7 +296,8 @@ export async function buildExploreMenu(page, graph, library, here) {
         // Graph still marks NavBlocks from:"*" for pathfinding/traverse; auto menu
         // only offers click-nav whose control is visible on this page (navRunnable).
         // Otherwise LoginForm lists every app route + mailpit as if legal moves.
-        if (isUrlNav(entry))
+        // A url Nav that declares `from` is only an edge from those pages, so it IS a real move here.
+        if (isUrlNav(entry) && edge.from === "*")
             continue;
         if (isBackEdge(edge) && (edge.from === here || edge.from === "*")) {
             push(back, edge);

package/dist/session/step-overlay.js

@@ -86,7 +86,9 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             ring.style.width = box.width + pad * 2 + "px";
             ring.style.height = box.height + pad * 2 + "px";
             ring.style.opacity = "1";
-            ringLabel.textContent = label;
+            // Drawn from data-label (CSS ::after), not DOM text, so the page's own text selectors never match it.
+            ringLabel.dataset.label = label;
+            ringLabel.textContent = "";
             ringLabel.style.left = box.x + "px";
             ringLabel.style.top = box.y + box.height + 8 + "px";
             ringLabel.style.opacity = "1";

package/dist/traverse/run.js

@@ -5,7 +5,7 @@ import { defaultMemValueForKey } from "../session/auto-explore-run.js";
 import { resolveBaseUrl } from "../config.js";
 import { EdgeLeaseCoordinator } from "./lease.js";
 import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./coverage.js";
-import { chromiumExecutablePath } from "../browser-path.js";
+import { chromiumExecutablePath } from "../browser.js";
 function seedMem(library, mem, dataJson) {
     const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     let envParsed = {};
@@ -253,6 +253,8 @@ export async function runTraverse(projectDir, options = {}) {
     const allEdgeKeys = collectGraphEdgeKeys(graph.edges);
     const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    if (process.env.WAYGRAPH_EXTENSIONS)
+        console.error("waygraph traverse: extensions are not loaded (workers use plain contexts)");
     const { chromium } = await import("@playwright/test");
     const executablePath = chromiumExecutablePath();
     const launchOpts = {

package/dist/ui/components/ring.js

@@ -20,6 +20,7 @@ export function ringCss() {
         "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
         `max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:${p.labelBg};color:${p.labelFg};` +
         "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
+        "#wg-ring-label::after{content:attr(data-label);}" +
         toneRules("#wg-ring-label", (t) => `background:${t.labelBg};color:${t.labelFg};`) +
         // Gray = a real Playwright-driven instruction: mark it with a robot.
         `#wg-ring-label[data-tone=auto]::before{${ROBOT}}` +

package/dist/ui/overlay.css

@@ -86,6 +86,7 @@
   font: 600 12px/1.35 var(--wg-font); transition: opacity .3s ease;
   overflow: hidden; text-overflow: ellipsis; white-space: nowrap; box-shadow: 0 2px 8px rgba(0,0,0,.25);
 }
+#wg-ring-label::after { content: attr(data-label); }
 .wg-ring-el-label[data-tone=planned] { --wg-tone-bg: var(--wg-tone-planned-bg); --wg-tone-fg: var(--wg-tone-planned-fg); }
 .wg-ring-el-label[data-tone=auto]    { --wg-tone-bg: var(--wg-tone-auto-bg);    --wg-tone-fg: var(--wg-tone-auto-fg); }
 .wg-ring-el-label[data-tone=info]    { --wg-tone-bg: var(--wg-tone-info-bg);    --wg-tone-fg: var(--wg-tone-info-fg); }

package/dist/ui/shadow.d.ts

@@ -7,7 +7,7 @@
  * lookups check the shadow root first and fall back to the light DOM (the device stage shell and
  * host-page markers such as `[data-wg-zoomed]` intentionally stay in the light DOM).
  */
-import type { BrowserContext, Page } from "@playwright/test";
+import type { Page } from "@playwright/test";
 /**
  * `overlaySheet` is the ONE real-CSS bundle (`ui/stylesheet.ts` -> `dist/ui/overlay.css`, built on
  * Open Props - see `src/ui/css/README.md`) every surface shares; passed in from Node since in-page
@@ -16,5 +16,3 @@ import type { BrowserContext, Page } from "@playwright/test";
 export declare function installShadowRoot(overlaySheet?: string): void;
 /** Idempotent; call before any overlay install on a page. Installs the shared stylesheet bundle. */
 export declare function ensureShadowRoot(page: Page): Promise<void>;
-/** Also define the helpers on every future document (pilot overlay persists across navigations). */
-export declare function installShadowRootEverywhere(context: BrowserContext): Promise<void>;

package/dist/ui/shadow.js

@@ -44,7 +44,3 @@ export function installShadowRoot(overlaySheet) {
 export async function ensureShadowRoot(page) {
     await page.evaluate(installShadowRoot, getOverlaySheet()).catch(() => { });
 }
-/** Also define the helpers on every future document (pilot overlay persists across navigations). */
-export async function installShadowRootEverywhere(context) {
-    await context.addInitScript(installShadowRoot, getOverlaySheet());
-}

package/dist/ui/tokens.d.ts

@@ -18,14 +18,3 @@ export interface Tone {
 export declare const TONES: Record<ToneName, Tone>;
 /** Dark surface shared by panels, banner, docks, HUD chips. */
 export declare const SURFACE = "rgba(20,10,40,.94)";
-export declare const ACCENT = "#7C3AED";
-/** Secondary accent used on the dark surface (section titles, kinds). */
-export declare const ACCENT_SOFT = "#c9a6ff";
-/** Stacking order: one scale instead of magic numbers. */
-export declare const Z: {
-    readonly top: 2147483647;
-    readonly ring: 2147483646;
-    readonly fx: 2147483645;
-    readonly focus: 2147483644;
-    readonly dock: 2147483000;
-};

package/dist/ui/tokens.js

@@ -14,8 +14,3 @@ export const TONES = {
 };
 /** Dark surface shared by panels, banner, docks, HUD chips. */
 export const SURFACE = "rgba(20,10,40,.94)";
-export const ACCENT = "#7C3AED";
-/** Secondary accent used on the dark surface (section titles, kinds). */
-export const ACCENT_SOFT = "#c9a6ff";
-/** Stacking order: one scale instead of magic numbers. */
-export const Z = { top: 2147483647, ring: 2147483646, fx: 2147483645, focus: 2147483644, dock: 2147483000 };

package/dist/video-dir.d.ts

@@ -0,0 +1,8 @@
+/** The user's Downloads folder, or undefined when there is none (a server, a container). */
+export declare function downloadsDir(): string | undefined;
+/**
+ * Where `--video` recordings go: `WAYGRAPH_VIDEO_DIR`, else `video.dir` from the config (absolute, `~/…`, or relative to
+ * the project), else `<Downloads>/waygraph-videos/<project>`. With no usable Downloads folder, or on CI, it is
+ * `<project>/.waygraph-videos`. An explicit `--video <dir>` never reaches this.
+ */
+export declare function resolveVideoDir(projectDir: string): Promise<string>;

package/dist/video-dir.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { loadWaygraphConfig } from "./config.js";
+/** The user's Downloads folder, or undefined when there is none (a server, a container). */
+export function downloadsDir() {
+    const home = homedir();
+    let dir = process.env.XDG_DOWNLOAD_DIR;
+    if (!dir && process.platform === "linux") {
+        try {
+            const line = readFileSync(join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "user-dirs.dirs"), "utf-8")
+                .split("\n")
+                .find((l) => l.startsWith("XDG_DOWNLOAD_DIR="));
+            dir = line?.slice("XDG_DOWNLOAD_DIR=".length).replace(/^"|"$/g, "").replace("$HOME", home);
+        }
+        catch {
+            /* no user-dirs file: use the conventional name */
+        }
+    }
+    dir ??= join(home, "Downloads");
+    return existsSync(dir) ? dir : undefined;
+}
+const expandHome = (p) => (p === "~" || p.startsWith("~/") ? join(homedir(), p.slice(1)) : p);
+/** True if a file can be created in `dir` (macOS asks permission for Downloads the first time; a denial surfaces here). */
+function writable(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, `.waygraph-probe-${process.pid}`);
+        writeFileSync(probe, "");
+        rmSync(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `--video` recordings go: `WAYGRAPH_VIDEO_DIR`, else `video.dir` from the config (absolute, `~/…`, or relative to
+ * the project), else `<Downloads>/waygraph-videos/<project>`. With no usable Downloads folder, or on CI, it is
+ * `<project>/.waygraph-videos`. An explicit `--video <dir>` never reaches this.
+ */
+export async function resolveVideoDir(projectDir) {
+    const fallback = join(projectDir, ".waygraph-videos");
+    const configured = process.env.WAYGRAPH_VIDEO_DIR || (await loadWaygraphConfig(projectDir))?.video?.dir;
+    if (configured) {
+        const dir = isAbsolute(expandHome(configured)) ? expandHome(configured) : resolve(projectDir, configured);
+        if (writable(dir))
+            return dir;
+        console.error(`waygraph: cannot write videos to ${dir} - using ${fallback}`);
+        return fallback;
+    }
+    const downloads = process.env.CI ? undefined : downloadsDir();
+    if (!downloads)
+        return fallback;
+    const dir = join(downloads, "waygraph-videos", basename(resolve(projectDir)));
+    if (writable(dir))
+        return dir;
+    console.error(`waygraph: cannot write to ${downloads} (denied?) - saving videos in ${fallback}`);
+    return fallback;
+}

package/dist/webserver.js

@@ -1,9 +1,10 @@
-// Starts/stops a project's own playwright.config `webServer` around `waygraph run`/`demo`/`auto`,
+// Starts/stops a project's `webServer` (waygraph.config, or a legacy playwright.config) around `waygraph run`/`demo`/`auto`,
 // the same block `waygraph test` already honors.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
+import { loadWaygraphConfig } from "./config.js";
 const CONFIG_FILES = [
     "playwright.config.ts",
     "playwright.config.mts",
@@ -12,6 +13,9 @@ const CONFIG_FILES = [
     "playwright.config.cjs",
 ];
 async function loadWebServerConfigs(projectDir) {
+    const fromWaygraph = (await loadWaygraphConfig(projectDir))?.webServer;
+    if (fromWaygraph)
+        return Array.isArray(fromWaygraph) ? fromWaygraph : [fromWaygraph];
     for (const name of CONFIG_FILES) {
         const p = join(projectDir, name);
         if (!existsSync(p))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.51",
+  "version": "0.15.52",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/scaffold/README.md

@@ -25,8 +25,10 @@ one Block per action, flows in `src/flows/`.
 ## Point it at your real app
 
 Change each `_nav.block.ts`'s `url` from the local `file://` path to a real one, and set a real
-`baseUrl` if your Nav Blocks use relative paths (`waygraph.config.ts`, a `.env`, or
-`package.json`'s `"waygraph"` field - see the main docs' "Project config" section). Keep each
+`baseUrl` if your Nav Blocks use relative paths (`config/waygraph.config.ts`, a `.env`, or
+`package.json`'s `"waygraph"` field - see the main docs' "Project config" section). That file also
+holds the test settings (`testDir`, `webServer`, `playwright: { workers, timeout, ... }`), so the
+project needs no `playwright.config.ts`. Keep each
 `src/map/` folder matching the URL it represents (`waygraph map` enforces this).
 
 Docs: https://deviate-dv8.github.io/waygraph/

package/templates/scaffold/STRUCTURE.md

@@ -7,6 +7,8 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 ```text
 .
 ├── package.json
+├── .agents/skills/                    # waygraph skills for coding agents
+├── config/waygraph.config.ts          # baseUrl, tests, extensions, webServer - no playwright.config
 ├── src/
 │   ├── map/
 │   │   ├── (app_base)/                # your app (opened via file:// here)
@@ -22,7 +24,8 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 │   │   │   │       ├── assert-hello.method.block.ts   # + stubs + YAP slide
 │   │   │   │       └── assert-item-added.method.block.ts
 │   │   │   └── docs/                  # a second page, same shape
-│   │   └── (external)/mailpit/        # a different origin (mail catcher)
+│   │   ├── (external)/mailpit/        # a different origin (mail catcher)
+│   │   └── (external)/hoppscotch/     # API client, REST client, needs the hoppscotch extension
 │   ├── states/                        # Checkpoint types + mem keys
 │   └── flows/                         # example / shop / mail-verify
 └── tests/example.spec.ts
@@ -39,7 +42,7 @@ page folder uses, so any agent or teammate knows where to look without asking.
 | Add an action on a page | one file in that page's `_methods/` |
 | Verify a state (button disabled, error shown) | `defineAssertBlock` + `Trait.disabled` / `Trait.enabled` |
 | Wire steps together | `src/flows/*.flow.ts` |
-| Give a flow fake data | `registerMemStub(key, fake)` + `withMemStub(flow)` (docs: docs/REFERENCE.md, "memStub") |
+| Give a flow fake data | `registerMemStub(key, fake)` + `memStub: true` in the flow's options (docs: docs/REFERENCE.md, "memStub") |
 | Explore by hand | `npm run auto` (headed) or `npm run auto:cli` |
 | Check your work | `npm run check`, `npm run graph`, `waygraph map` |
 

package/templates/scaffold/config/waygraph.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "waygraph";
+
+export default defineConfig(({ env }) => ({
+  // Where the app under test lives. BASE_URL comes from .env / .env.<mode>:  waygraph test --env staging
+  baseUrl: env.BASE_URL ?? "__APP_BASE_URL__",
+
+  // ── waygraph: uncomment what you need ─────────────────────────────────────────────────────────
+  // extensions: ["hoppscotch"],             // browser extensions to load (a waygraph feature, not Playwright's)
+  // video: {                                // recordings made with `waygraph run|demo --video`
+  //   dir: "~/Downloads/waygraph-videos",   //   where they are saved (default: Downloads/waygraph-videos/<project>)
+  //   viewport: "1920x1080",                //   recording size: demo defaults to 1920x1080, run to 1280x720
+  // },
+  // slowMo: 250,                            // ms to pause before each browser action, so a run is watchable
+  // headed: true,                           // show the browser window (demo and auto already do)
+  // demo: { autoNext: true, fast: false },  // advance demo steps without clicking Next; blitz fast-forward steps
+  // webServer: { command: "npm start", port: 3000 },   // started around test / run / demo / auto
+
+  // ── test runner (Playwright) ──────────────────────────────────────────────────────────────────
+  // testDir: "tests",
+  // playwright: {                           // any Playwright test option, merged over waygraph's defaults
+  //   workers: 1,
+  //   retries: 1,
+  //   timeout: 60_000,
+  //   use: { video: "on", trace: "on", screenshot: "only-on-failure", viewport: { width: 1280, height: 720 } },
+  // },
+}));

package/templates/scaffold/package.json

@@ -21,7 +21,7 @@
     "run:shop": "waygraph run --blocks shopFlow"
   },
   "dependencies": {
-    "waygraph": "^0.12.20"
+    "waygraph": "latest"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

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

@@ -7,12 +7,12 @@ all point at an export here by name (`waygraph run --blocks shopFlow`).
   `.branch()`) over hand-composing raw Blocks - it checks each step's Block kind at runtime and
   the Checkpoint chain at compile time, so a wrong step is a build/test failure, not a
   mid-run surprise.
-- `withTitle`/`withHighlightFixtures`/`withSessionReset`/etc. are non-destructive wrappers -
-  `someFlow.withTitle("...")` doesn't mutate `someFlow`, it returns a new one. Compose them
-  around the finished `.end()` result, not inside the Map chain itself.
+- Flow settings go in `.end({ title, memStub, sessionReset })`. No nested `withTitle(withMemStub(...))`.
+- Demo highlights are ctx stubs chained on the Block where the flow uses it:
+  `AddItemBlock.stubAfter((ctx) => { ctx.ring("cart", { selector, label }); })`.
 - One flow, one scenario. A flow that needs a genuinely different starting session
-  (re-entering the login page mid-chain) wraps that segment in `withSessionReset`, rather than
-  hand-clearing cookies inside a Block.
+  (re-entering the login page mid-chain) sets `sessionReset: true`, rather than hand-clearing
+  cookies inside a Block.
 
 New flow → new file here, named for the scenario (`checkout.flow.ts`), not for the Blocks it
 happens to use.

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

@@ -1,4 +1,6 @@
-import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
+import { Engine } from "waygraph";
+import config from "../../config/waygraph.config.js";
+import { DemoSel } from "../map/(app_base)/home/_sel.js";
 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";
@@ -6,24 +8,36 @@ import { NavDocsBlock } from "../map/(app_base)/docs/_nav.block.js";
 import "../map/(app_base)/home/_page.block.js";
 import "../map/(app_base)/docs/_page.block.js";
 
-const engine = new Engine();
+const engine = new Engine(config);
 
 /** 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: {
+export const exampleFlow = engine
+  .map()
+  .start()
+  .gotoPage(
+    NavHomeBlock.stubAfter((ctx) => {
+      ctx.ring("title", { selector: DemoSel.title, label: "Home heading", duration: true });
+    }).stubOnError((ctx) => {
+      ctx.ring("title", { selector: DemoSel.title, label: "Home heading at failure" });
+    }),
+  )
+  .assert(
+    AssertHelloBlock.stubBefore((ctx) => {
+      ctx.ring("title", { selector: DemoSel.title, label: "Heading about to check" });
+    })
+      .stubAfter((ctx) => {
+        ctx.ring("title", {
+          selector: DemoSel.title,
           label: "AC · Hello visible",
-          detail: "Replace this fixture copy with your ticket lines.",
+          detail: "Replace this copy with your ticket lines.",
           tag: "AC",
           duration: true,
-        },
-      },
-    },
-  },
-);
+        });
+        ctx.ring("sub", { selector: DemoSel.sub, label: "Subcopy", duration: 1500 });
+      })
+      .stubOnError((ctx) => {
+        ctx.ring("title", { selector: DemoSel.title, label: "Heading at failure", tag: "FAIL" });
+      }),
+  )
+  .gotoPage(NavDocsBlock)
+  .end({ title: "Scaffold: Hello Waygraph" });

package/templates/scaffold/src/flows/hoppscotch-auth.flow.ts

@@ -0,0 +1,35 @@
+import { Engine } from "waygraph";
+import config from "../../config/waygraph.config.js";
+import { NavHoppscotchSettingsBlock } from "../map/(external)/hoppscotch/settings/_nav.block.js";
+import { PickExtensionInterceptorBlock } from "../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
+import { NavHoppscotchRestBlock } from "../map/(external)/hoppscotch/_nav.block.js";
+import { SetQueryParamsBlock } from "../map/(external)/hoppscotch/_methods/set-query-params.method.block.js";
+import { SetUrlBlock } from "../map/(external)/hoppscotch/_methods/set-url.method.block.js";
+import { SetBearerTokenBlock } from "../map/(external)/hoppscotch/_methods/set-bearer-token.method.block.js";
+import { SendRequestBlock } from "../map/(external)/hoppscotch/_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
+import { ReadResponseHeadersBlock } from "../map/(external)/hoppscotch/_methods/read-response-headers.method.block.js";
+import { AssertResponseHeaderBlock } from "../map/(external)/hoppscotch/_methods/assert-response-header.method.block.js";
+import { ReadResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/read-response-body.method.block.js";
+import { AssertResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/assert-response-body.method.block.js";
+import "../map/(external)/hoppscotch/_page.block.js";
+
+const engine = new Engine(config);
+
+/** GET with query params and a bearer token, check the status, that the API received them, and a response header. Needs `extensions: ["hoppscotch"]`. */
+export const hoppscotchAuthFlow = engine
+  .map()
+  .start()
+  .gotoExternal(NavHoppscotchSettingsBlock)
+  .method(PickExtensionInterceptorBlock)
+  .gotoExternal(NavHoppscotchRestBlock)
+  .method(SetUrlBlock)
+  .method(SetQueryParamsBlock)
+  .method(SetBearerTokenBlock)
+  .method(SendRequestBlock)
+  .assert(AssertStatusBlock)
+  .method(ReadResponseBodyBlock)
+  .assert(AssertResponseBodyBlock)
+  .method(ReadResponseHeadersBlock)
+  .assert(AssertResponseHeaderBlock)
+  .end({ title: "Scaffold: Hoppscotch GET with query params and bearer token" });