waygraph 0.13.7 → 0.15.0

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -1,6 +1,6 @@
 import { defineMethodBlock, checkpoint, Trait, type StubCtx } from "waygraph";
 import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
-import { LoginCreds } from "../../../states/checkout.mem-keys.js";
+import { LoginSel } from "./login.sel.js";
 
 type LoginObserve = "success" | "failure";
 
@@ -9,30 +9,26 @@ type LoginObserve = "success" | "failure";
  * Helper: defineMethodBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
- * Fills credentials and submits - never page.goto (nav-login Page hub owns that).
+ * Clicks Login only - never page.goto (nav-login Page hub owns that), never
+ * fills fields (fill-username.method.block.ts / fill-password.method.block.ts
+ * already did that). One Block, one action: submit.
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
- * stubBefore/stubAfter drive the floating todo dock (Method fill/click advances
- * todoIndex mid-act; stubAfter marks complete / fail).
  */
-export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>({
+export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
-  description: "Logs a user in when credentials are valid; stays on LoginPage when auth fails.",
-  requires: [LoginCreds.key],
+  description: "Submits the login form; stays on LoginPage when auth fails.",
   instruction: {
-    async act(page, _input, mem) {
-      const { username, password } = mem.get(LoginCreds.key);
-      await page.locator("#user-name").fill(username);
-      await page.locator("#password").fill(password);
+    async act(page) {
       // noWaitAfter: observe owns the inventory URL wait. Default click
       // navigation-wait can hang under waygraph auto's demo cursor patch.
-      await page.locator("#login-button").click({ noWaitAfter: true });
+      await page.locator(LoginSel.loginButton).click({ noWaitAfter: true });
     },
     async observe(page): Promise<LoginObserve> {
       // Race inventory nav vs error banner - locked_out / wrong password show
       // Epic sadface immediately; do not burn the full inventory timeout.
       const inventory = page.waitForURL(/\/inventory\.html/, { timeout: 8_000 }).then(() => "success" as const);
       const errorBanner = page
-        .locator('[data-test="error"]')
+        .locator(LoginSel.errorBanner)
         .first()
         .waitFor({ state: "visible", timeout: 8_000 })
         .then(() => "failure" as const);
@@ -46,40 +42,13 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     verify: (out) =>
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
-        : [Trait.visible('[data-test="error"]')],
-    // Open lifecycle: banner title, todos, Screen Studio camera zoom,
-    // sequential highlight queue (appear / dwell / fade), focus + color.
+        : [Trait.visible(LoginSel.errorBanner)],
     stubBefore: (ctx: StubCtx) => {
-      ctx.title("Signing in · mobile");
-      // 0.13.3: mobile portrait + touch; tap Login.
-      ctx.device("mobile");
-      ctx.portrait();
-      ctx.todoId("saucedemo-login");
-      ctx.todos([
-        { id: "login-user", text: "Enter username" },
-        { id: "login-pass", text: "Enter password" },
-        { id: "login-submit", text: "Tap Login" },
-      ]);
-      ctx.todoIndex(0);
-      ctx.zoom(1.35);
       ctx.highlights({
-        username: {
-          selector: "#user-name",
-          label: "Username",
-          focus: true,
-          color: "#c9a6ff",
-          zoom: 1.4,
-        },
-        password: {
-          selector: "#password",
-          label: "Password",
-          focus: true,
-          color: "#c9a6ff",
-          zoom: 1.4,
-        },
         submit: {
-          selector: "#login-button",
+          selector: LoginSel.loginButton,
           label: "Login",
+          todo: "login-submit",
           focus: true,
           color: "#86efac",
           zoom: 1.55,
@@ -89,19 +58,19 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       });
     },
     stubAfter: (ctx: StubCtx) => {
-      // Fail branch lands on LoginPage with Epic sadface - do not ring the
-      // inventory shelf. Success (LoggedIn) hands off to shopFlow.
       if (ctx.out && ctx.out.__state === "LoginPage") {
         ctx.title("Login blocked");
-        ctx.todoId("saucedemo-login");
-        ctx.todos([
-          { id: "login-user", text: "Enter username", done: true },
-          { id: "login-pass", text: "Enter password", done: true },
-          { id: "login-submit", text: "Click Login", done: true },
-        ]);
-        ctx.todoStyle("checklist");
+        ctx.todos(
+          "saucedemo",
+          [
+            { id: "login-user", text: "Enter username", done: true },
+            { id: "login-pass", text: "Enter password", done: true },
+            { id: "login-submit", text: "Click Login", done: true },
+          ],
+          { title: "Sign in", style: "checklist" },
+        );
         ctx.ring("error", {
-          selector: '[data-test="error"]',
+          selector: LoginSel.errorBanner,
           label: "Login error banner",
           tone: "danger",
           focus: true,
@@ -111,16 +80,19 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         return;
       }
       ctx.banner("Inventory · landscape");
-      // Rotate mobile to landscape on the product shelf (toast + lerp).
       ctx.landscape();
-      ctx.todoId("saucedemo-login");
-      ctx.todos([
-        { id: "login-user", text: "Enter username" },
-        { id: "login-pass", text: "Enter password" },
-        { id: "login-submit", text: "Click Login" },
-      ]);
-      ctx.todoIndex(2);
-      // Landed on inventory - hand off to shopFlow for product -> cart zoom.
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Tap Login", done: true },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 3 },
+      );
       ctx.ring("shelf", {
         selector: ".inventory_list",
         label: "Product shelf",
@@ -134,7 +106,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     stubOnError: (ctx: StubCtx) => {
       ctx.title("Login failed");
       ctx.ring("error", {
-        selector: '[data-test="error"]',
+        selector: LoginSel.errorBanner,
         label: "Login error banner",
         tone: "danger",
         focus: true,

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-logout.method.block.ts

@@ -1,5 +1,6 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
+import { LoginSel } from "./login.sel.js";
 
 /**
  * Kind: Method
@@ -13,10 +14,10 @@ export const SubmitLogoutBlock = defineMethodBlock<LoggedIn, LoginPage>({
   description: "Opens the burger menu and logs out.",
   instruction: {
     async act(page) {
-      await page.locator("#react-burger-menu-btn").click();
-      await page.locator("#logout_sidebar_link").click();
+      await page.locator(LoginSel.burgerMenuButton).click();
+      await page.locator(LoginSel.logoutLink).click();
     },
     resolve: () => checkpoint("LoginPage"),
-    verify: [Trait.visible("#login-button")],
+    verify: [Trait.visible(LoginSel.loginButton)],
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/nav-login.block.ts

@@ -1,23 +1,31 @@
 import { definePageBlock, Trait } from "waygraph";
 import type { LoginPage } from "../../states/checkout.states.js";
-import { SubmitLoginActionBlock } from "./methods/submit-login.method.block.js";
+import { FillUsernameBlock } from "./methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "./methods/fill-password.method.block.js";
+import { SubmitLoginBlock } from "./methods/submit-login.method.block.js";
+import { LoginSel } from "./methods/login.sel.js";
 
 /**
  * Kind: Page
  * Helper: definePageBlock
  * Route: saucedemo-web/  (= /)
  *
- * Login screen hub. Deep-link via url; method submit-login hangs off this
- * page (stubBefore/stubAfter todos live on the Method). Name stays
- * `nav-login` so existing flows / chain specs keep working.
+ * Login screen hub. Deep-link via url; fill-username / fill-password /
+ * submit-login hang off this page as three atomic Methods - fill-* are
+ * self-loops (LoginPage -> LoginPage), submit-login owns the one real
+ * transition (LoginPage -> LoggedIn|LoginPage). No single Block both fills
+ * and submits. Name stays `nav-login` so existing flows / chain specs keep
+ * working.
  */
 export const NavLoginBlock = definePageBlock<LoginPage>({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",
   checkpoint: "LoginPage",
   url: "/",
-  verify: [Trait.visible("#login-button")],
+  verify: [Trait.visible(LoginSel.loginButton)],
   methods: {
-    submitLogin: () => SubmitLoginActionBlock,
+    fillUsername: () => FillUsernameBlock,
+    fillPassword: () => FillPasswordBlock,
+    submitLogin: () => SubmitLoginBlock,
   },
 });

package/templates/quickstart/src/flows/checkout-then-browse-again.flow.ts

@@ -9,10 +9,15 @@ import type {
   OrderComplete,
 } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 import { NavBackToProductsBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-products.block.js";
@@ -23,21 +28,31 @@ const engine = new Engine({ headless: false, slowMo: 250 });
 // (proves OrderComplete -> LoggedIn without a goto teleport).
 export const checkoutThenBrowseAgainFlow = withTitle(
   engine.defineFlow<
+    LoginPage,
+    LoginPage,
     LoginPage,
     LoggedIn,
     ItemInCart,
     CartPage,
     CheckoutInfoPage,
+    CheckoutInfoPage,
+    CheckoutInfoPage,
+    CheckoutInfoPage,
     CheckoutOverviewPage,
     OrderComplete,
     LoggedIn
   >([
     start,
     NavLoginBlock,
+    FillUsernameBlock,
+    FillPasswordBlock,
     SubmitLoginForFlow,
     AddToCartBlock,
     NavCartBlock,
     NavCheckoutInfoBlock,
+    FillFirstNameBlock,
+    FillLastNameBlock,
+    FillPostalCodeBlock,
     SubmitCheckoutInfoBlock,
     FinishOrderBlock,
     NavBackToProductsBlock,

package/templates/quickstart/src/flows/checkout.flow.ts

@@ -11,12 +11,23 @@ import { FfOwnerAuthBlock } from "../blocks/saucedemo-web/ff-owner-auth.block.js
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
 const engine = new Engine({ headless: false, slowMo: 250 });
 
-// Auth is one FFCompose step so demo pacing skips login; --ff-expand for inners.
+// Atomic nav/action per real URL after auth - the shape `waygraph auto` discovers.
+// Auth is one FFCompose step (ff-owner-auth) so demo pacing skips login yap;
+// use --ff-expand (or loginFlow) when you need per-step auth narration.
+//
+// Demo narration showcase (waygraph 0.11+ / FFCompose 0.12):
+// - FF opaque: one gate for auth; stubs on interesting post-login blocks
+// - Block stubs: add-to-cart / finish-order stubAfter
+// - Flow fixtures: ticket-style captions
+// - Slides on finish-order: multi-step yap with Next between slides
 export const checkoutFlow = withHighlightFixtures(
   withTitle(
     engine.defineFlow<
@@ -24,6 +35,9 @@ export const checkoutFlow = withHighlightFixtures(
       ItemInCart,
       CartPage,
       CheckoutInfoPage,
+      CheckoutInfoPage,
+      CheckoutInfoPage,
+      CheckoutInfoPage,
       CheckoutOverviewPage,
       OrderComplete
     >([
@@ -32,6 +46,9 @@ export const checkoutFlow = withHighlightFixtures(
       AddToCartBlock,
       NavCartBlock,
       NavCheckoutInfoBlock,
+      FillFirstNameBlock,
+      FillLastNameBlock,
+      FillPostalCodeBlock,
       SubmitCheckoutInfoBlock,
       FinishOrderBlock,
       end,
@@ -49,7 +66,9 @@ export const checkoutFlow = withHighlightFixtures(
         },
       },
     },
-    "submit-login": {
+    // Kept for --ff-expand (inners become separate steps again: nav-login,
+    // fill-username, fill-password, submit-login).
+    "fill-username": {
       stubBefore: {
         username: {
           label: "Demo user",
@@ -57,7 +76,15 @@ export const checkoutFlow = withHighlightFixtures(
           tag: "AC",
           duration: true,
         },
+      },
+    },
+    "fill-password": {
+      stubBefore: {
         password: { label: "Password", detail: "Filled from Mem credentials.", duration: 1500 },
+      },
+    },
+    "submit-login": {
+      stubBefore: {
         submit: { label: "Sign in", tag: "GATE", duration: true, fastMode: 500 },
       },
     },

package/templates/quickstart/src/flows/device-showcase.flow.ts

@@ -1,5 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
@@ -19,6 +21,8 @@ export const deviceShowcaseFlow = withTitle(
   engine.defineFlow([
     start,
     NavLoginBlock,
+    FillUsernameBlock,
+    FillPasswordBlock,
     SubmitLoginForFlow,
     AddToCartBlock,
     NavCartBlock,

package/templates/quickstart/src/flows/login.flow.ts

@@ -1,5 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 
 const engine = new Engine();
@@ -7,6 +9,6 @@ const engine = new Engine();
 // The step-mode overlay prepends "Episode N: " itself - the title here is
 // just the label, not the full heading.
 export const loginFlow = withTitle(
-  engine.defineFlow([start, NavLoginBlock, SubmitLoginForFlow, end]),
+  engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginForFlow, end]),
   "Sign In",
 );

package/templates/quickstart/src/flows/shop.flow.ts

@@ -2,6 +2,9 @@ import { Engine, start, end, withTitle } from "waygraph";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
@@ -15,6 +18,9 @@ export const shopFlow = withTitle(
     AddToCartBlock,
     NavCartBlock,
     NavCheckoutInfoBlock,
+    FillFirstNameBlock,
+    FillLastNameBlock,
+    FillPostalCodeBlock,
     SubmitCheckoutInfoBlock,
     FinishOrderBlock,
     end,

package/templates/quickstart/src/flows/smoke.flow.ts

@@ -1,6 +1,8 @@
 import { Engine, start, end } from "waygraph";
 import type { LoginPage, LoggedIn, ItemInCart } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 
@@ -10,17 +12,21 @@ const engine = new Engine();
 // it doesn't need the same DOM confirmation the real checkout.flow.ts wants.
 // Same Blocks, same act/resolve, zero duplication - only verify differs.
 // .withVerify([]) reads from the Block itself, discoverable by typing
-// "NavLoginBlock."/"SubmitLoginActionBlock." in an editor - not a free function
+// "NavLoginBlock."/"SubmitLoginForFlow." in an editor - not a free function
 // you have to already know exists.
 //
-// Explicit <LoginPage, LoggedIn, ItemInCart> here - AddToCartBlock's In is now
-// the wildcard Checkpoint<string> (it's reused as shopFlow's own entry block
-// too), and inferring B/C/D purely from three chained .withVerify([]) calls in
-// one array trips TS's overload resolution into unifying the wrong Out type
-// partway through; pinning the type args sidesteps it rather than fighting it.
-export const smokeFlow = engine.defineFlow<LoginPage, LoggedIn, ItemInCart>([
+// Explicit <LoginPage, LoginPage, LoginPage, LoggedIn, ItemInCart> here -
+// AddToCartBlock's In is now the wildcard Checkpoint<string> (it's reused as
+// shopFlow's own entry block too), and inferring the chain purely from
+// several chained .withVerify([]) calls in one array trips TS's overload
+// resolution into unifying the wrong Out type partway through; pinning the
+// type args sidesteps it rather than fighting it. The two middle `LoginPage`
+// entries are fill-username / fill-password (self-loop Methods).
+export const smokeFlow = engine.defineFlow<LoginPage, LoginPage, LoginPage, LoggedIn, ItemInCart>([
   start,
   NavLoginBlock.withVerify([]),
+  FillUsernameBlock,
+  FillPasswordBlock,
   SubmitLoginForFlow.withVerify([]),
   AddToCartBlock.withVerify([]),
   end,

package/templates/quickstart/src/flows/viewer-blocked.flow.ts

@@ -1,6 +1,8 @@
 import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
+import { SubmitLoginBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
 const engine = new Engine();
 
@@ -22,7 +24,9 @@ const engine = new Engine();
 // "expected outcome" panel (branching no longer throws).
 export const viewerBlockedFlow = withExpectedFailure(
   withTitle(
-    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    withSessionReset(
+      engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]),
+    ),
     "Viewer: Blocked Login Attempt",
   ),
   "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",

package/templates/quickstart/tests/chain-flow.spec.ts

@@ -38,16 +38,23 @@ test("chainFlow blocks() lists the flattened episode chain in order", () => {
   const blocks = chainFlow(loginFlow, shopFlow, viewerBlockedFlow).blocks();
   expect(blocks.map((b) => b.name)).toEqual([
     "nav-login",
+    "fill-username",
+    "fill-password",
     "submit-login",
     "add-to-cart",
     "nav-cart",
     "nav-checkout-info",
+    "fill-first-name",
+    "fill-last-name",
+    "fill-postal-code",
     "submit-checkout-info",
     "finish-order",
     "nav-login",
+    "fill-username",
+    "fill-password",
     "submit-login",
   ]);
-  expect(blocks.every((b, i) => (i === 7 ? b.resetSessionBefore === true : !b.resetSessionBefore))).toBe(
+  expect(blocks.every((b, i) => (i === 12 ? b.resetSessionBefore === true : !b.resetSessionBefore))).toBe(
     true,
   );
 });

package/templates/scaffold/STRUCTURE.md

@@ -25,9 +25,16 @@ Docs: [docs/scaffold.html](../../docs/scaffold.html)
 │   ├── states/
 │   │   ├── demo.states.ts
 │   │   └── demo.mem-keys.ts  # SelectedItem for Effect / auto
-│   └── flows/
-│       ├── example.flow.ts   # nav + assert (smoke)
-│       └── shop.flow.ts      # nav + add-item + clear (Effect path)
+│   ├── flows/
+│   │   ├── example.flow.ts   # nav + assert (smoke)
+│   │   ├── shop.flow.ts      # nav + add-item + clear (Effect path)
+│   │   └── routes-demo.flow.ts  # Home (manual mode) -> Docs (Map convention)
+│   └── routes/                       # Waygraph Map convention - see README.md
+│       └── (external)/
+│           └── docs/
+│               ├── docs.sel.ts
+│               ├── nav.block.ts      # fixed name - every page-slug folder's Nav
+│               └── page.block.ts     # fixed name - every page-slug folder's arrival hub
 ├── scripts/
 │   ├── fixture-server.mjs    # serves home.html on :4177
 │   └── with-fixture.mjs      # start server + run waygraph auto/demo/run
@@ -59,3 +66,16 @@ npm run auto:cli    # same menus in the terminal
 ```
 
 After `nav-home`, Effect blocks expose one menu row per visible Add/Remove button.
+
+## Two authoring modes
+
+`src/blocks/` (`demo-web/`, `demo-external/`) is **manual mode** - freeform, developer-chosen
+file layout, the default this whole scaffold otherwise uses.
+
+`src/routes/` is the **Waygraph Map** convention - `(group)/<page-slug>/page.block.ts` +
+`nav.block.ts` + `methods/*.block.ts`, one Checkpoint per folder, `(group)` purely
+organizational (parens, Next.js route-group style - never part of the Checkpoint tag). Same
+Block helpers, same execution - only where files live and what they're named changes. A
+project can adopt it folder by folder; `routes-demo.flow.ts` proves both modes compose in one
+flow (`nav-home` from `blocks/`, `nav-docs` from `routes/`). See the main package's own
+`README.md` "Waygraph Map" section and `openspec/changes/waygraph-map/`.

package/templates/scaffold/scripts/fixture-server.mjs

@@ -8,7 +8,15 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, dirname, extname, normalize } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../src/blocks/demo-web");
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../src/map/(app_base)");
+// Each fixture HTML file lives beside its own _page.block.ts under the
+// Waygraph Map convention now (home/home.html, docs/docs.html) - no longer
+// a single flat directory, so this maps the request filename to its own
+// page's subfolder instead of assuming one shared ROOT holds every file.
+const FILE_DIRS = {
+  "home.html": "home",
+  "docs.html": "docs",
+};
 const PORT = Number(process.env.WAYGRAPH_FIXTURE_PORT || 4177);
 const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
 
@@ -23,7 +31,8 @@ const TYPES = {
 const server = createServer((req, res) => {
   const raw = (req.url || "/").split("?")[0] || "/";
   const rel = raw === "/" ? "home.html" : raw.replace(/^\//, "");
-  const full = normalize(join(ROOT, rel));
+  const subdir = FILE_DIRS[rel];
+  const full = subdir ? normalize(join(ROOT, subdir, rel)) : normalize(join(ROOT, rel));
   if (!full.startsWith(ROOT) || !existsSync(full)) {
     res.writeHead(404, { "content-type": "text/plain" });
     res.end("not found");

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

@@ -1,15 +1,17 @@
 import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
-import { NavHomeBlock } from "../blocks/demo-web/nav-home.block.js";
-import { AssertHelloBlock } from "../blocks/demo-web/methods/assert-hello.method.block.js";
-// Page hub registered for auto/docs grouping (arrival-only after nav).
-import "../blocks/demo-web/home.page.block.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";
+// 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). Green offline. */
+/** Smoke: nav + assert (no mem), then nav to the sibling docs/ page. Green offline. */
 export const exampleFlow = withHighlightFixtures(
   withTitle(
-    engine.defineFlow([start, NavHomeBlock, AssertHelloBlock, end]),
+    engine.defineFlow([start, NavHomeBlock, AssertHelloBlock, NavDocsBlock, end]),
     "Scaffold: Hello Waygraph",
   ),
   {