waygraph 0.7.6 → 0.7.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deviate-DV8
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -1772,6 +1772,16 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         i = episodeStartIndex - 1;
         continue;
       }
+      // withExpectedFailure episode (e.g. locked_out_user) - throwing here is
+      // the demo working, not a broken run.
+      if (r.expectedFailureReason) {
+        if (process.env.WAYGRAPH_JSON !== "1") {
+          console.log(
+            "waygraph: expected failure on " + r.block.name + " - " + r.expectedFailureReason,
+          );
+        }
+        break;
+      }
       throw err;
     }
     await page
@@ -1829,6 +1839,21 @@ async function runJsonReportMode(engine, start, end, context, page, mem, resolve
       const outcome = await stepFlow.run(context, mem, { page, closeOnFinish: false });
       steps.push({ name: r.block.name, checkpoint: outcome.result, ms: Date.now() - startedAt });
     } catch (err) {
+      if (r.expectedFailureReason) {
+        steps.push({
+          name: r.block.name,
+          expectedFailure: true,
+          error: err && err.message ? err.message : String(err),
+          ms: Date.now() - startedAt,
+        });
+        return {
+          ok: true,
+          expectedFailure: true,
+          failedAt: r.block.name,
+          reason: r.expectedFailureReason,
+          steps,
+        };
+      }
       let screenshot = null;
       try {
         screenshot = join(tmpdir(), "waygraph-chain-failure-" + Date.now() + ".png");
@@ -1850,6 +1875,26 @@ async function runJsonReportMode(engine, start, end, context, page, mem, resolve
   return { ok: true, result: steps.length > 0 ? steps[steps.length - 1].checkpoint : null, steps };
 }
 
+function isExpectedChainFailure(chainFlows, err) {
+  if (!chainFlows || chainFlows.length === 0) return false;
+  const last = chainFlows[chainFlows.length - 1];
+  if (!last?.expectedFailureReason) return false;
+  const msg = err && err.message ? err.message : String(err);
+  return msg.includes("viewer-login") || msg.includes("reached-inventory-or-genuinely-blocked");
+}
+
+async function runChainedFlows(chainFlow, chainFlows, context, mem, page) {
+  try {
+    const outcome = await chainFlow(...chainFlows).run(context, mem, { page, closeOnFinish: false });
+    return outcome?.result !== undefined ? outcome.result : outcome;
+  } catch (err) {
+    if (isExpectedChainFailure(chainFlows, err)) {
+      return { __expectedFailure: true, message: err && err.message ? err.message : String(err) };
+    }
+    throw err;
+  }
+}
+
 async function main() {
   const projectDir = process.argv[2];
   const spec = process.argv[3];
@@ -1863,6 +1908,7 @@ async function main() {
   // reaches stdout.
   const jsonReport = process.env.WAYGRAPH_JSON === "1";
   let resolved = [];
+  let chainFlows = null;
   // A bare identifier (no "(", no "then") might name an existing Flow
   // that's already wired up (e.g. loginFlow) - try that FIRST so pointing
   // at real, already-built flows needs no chain-spec typing at all. Falls
@@ -1871,11 +1917,16 @@ async function main() {
   if (bareRef) {
     const flow = await findFlow(projectDir, bareRef);
     if (flow && typeof flow.blocks === "function") {
-      resolved = flow.blocks().map((bi) => ({
+      const blockInfos = flow.blocks();
+      resolved = blockInfos.map((bi, idx) => ({
         block: bi.block,
         exportName: bi.name,
-        expectedFailureReason: flow.expectedFailureReason,
+        expectedFailureReason:
+          flow.expectedFailureReason && idx === blockInfos.length - 1
+            ? flow.expectedFailureReason
+            : undefined,
       }));
+      chainFlows = [flow];
       if (!jsonReport) {
         console.log(
           "waygraph: running existing flow \\"" + bareRef + "\\" - " +
@@ -1960,13 +2011,15 @@ async function main() {
         resetSession: bi.resetSessionBefore === true,
         episodeNumber: meta.episodeNumber,
         episodeTitle: meta.episodeTitle,
-        expectedFailureReason: meta.expectedFailureReason,
+        expectedFailureReason:
+          meta.expectedFailureReason && remainingInFlow === 1 ? meta.expectedFailureReason : undefined,
         seedMem: isFirstOfSegment ? meta.seedMem : undefined,
       };
       remainingInFlow -= 1;
       isFirstOfSegment = false;
       return entry;
     });
+    chainFlows = flows;
     if (!jsonReport) {
       console.log(
         "waygraph: chaining " + resolved.map((r) => r.block.name).join(" -> ") +
@@ -2072,15 +2125,19 @@ async function main() {
         if (!report.ok) process.exitCode = 1;
         return;
       } else {
-        const blocks = resolved.map((r) => r.block);
-        const chained = blocks.reduce((a, b) => connect(a, b));
-        const flow = engine.defineFlow([start, chained, end]);
         const page = await context.newPage();
         pageForVideo = page;
         if (baseURL) {
           await page.goto(baseURL).catch(() => {});
         }
-        result = await flow.run(context, mem, { page, closeOnFinish: false });
+        if (chainFlows && chainFlows.length > 0) {
+          result = await runChainedFlows(chainFlow, chainFlows, context, mem, page);
+        } else {
+          const blocks = resolved.map((r) => r.block);
+          const chained = blocks.reduce((a, b) => connect(a, b));
+          const flow = engine.defineFlow([start, chained, end]);
+          result = await flow.run(context, mem, { page, closeOnFinish: false });
+        }
       }
     } finally {
       await context.close();
@@ -2094,13 +2151,29 @@ async function main() {
       await browser.close();
     }
   } else {
-    const blocks = resolved.map((r) => r.block);
-    const chained = blocks.reduce((a, b) => connect(a, b));
-    const flow = engine.defineFlow([start, chained, end]);
-    const recordVideo = videoDir ? { dir: videoDir } : undefined;
-    result = await flow.run(mem, recordVideo ? { recordVideo } : undefined);
+    if (chainFlows && chainFlows.length > 0) {
+      try {
+        result = await chainFlow(...chainFlows).run(mem);
+      } catch (err) {
+        if (isExpectedChainFailure(chainFlows, err)) {
+          result = { __expectedFailure: true, message: err && err.message ? err.message : String(err) };
+        } else {
+          throw err;
+        }
+      }
+    } else {
+      const blocks = resolved.map((r) => r.block);
+      const chained = blocks.reduce((a, b) => connect(a, b));
+      const flow = engine.defineFlow([start, chained, end]);
+      const recordVideo = videoDir ? { dir: videoDir } : undefined;
+      result = await flow.run(mem, recordVideo ? { recordVideo } : undefined);
+    }
+  }
+  if (result && result.__expectedFailure) {
+    console.log("waygraph: chain finished (expected failure on last episode) -- " + result.message);
+  } else {
+    console.log("waygraph: chain finished -- " + JSON.stringify(result));
   }
-  console.log("waygraph: chain finished -- " + JSON.stringify(result));
 }
 
 main().catch((err) => {
@@ -2234,6 +2307,8 @@ async function ensureDirPrereqs(dir, label) {
         return `${label}: no package.json in ${dir}`;
     }
     if (status.missing === "waygraph" || status.missing === "playwright-test" || status.missing === "unknown") {
+        // Copied quickstart must not keep a workspace-tainted lockfile (breaks temp-dir npm install).
+        rmSync(join(dir, "package-lock.json"), { force: true });
         console.log(`${label}: installing dependencies in ${dir} ...`);
         const installCode = await runInherited("npm", ["install"], dir);
         if (installCode !== 0) {
@@ -2258,7 +2333,7 @@ async function ensureDirPrereqs(dir, label) {
         return null;
     return status.detail ?? "prerequisites still aren't ready after attempting to install them.";
 }
-const TRY_DEMO_CHAIN = 'loginFlow({"username":"standard_user","password":"secret_sauce"}) then viewerBlockedFlow({"username":"locked_out_user","password":"secret_sauce"})';
+const TRY_DEMO_CHAIN = 'shopFlow({"username":"standard_user","password":"secret_sauce"}) then viewerBlockedFlow({"username":"locked_out_user","password":"secret_sauce"})';
 /**
  * Point a copied quickstart at this checkout's waygraph build (not npm registry).
  * Uses `npm pack` into destDir - a file: symlink to the dev tree can double-load
@@ -2287,6 +2362,10 @@ async function wireQuickstartToPackageRoot(destDir) {
 async function runTryDemo() {
     const destDir = mkdtempSync(join(tmpdir(), "waygraph-try-demo-"));
     cpSync(join(packageRoot(), "templates", "quickstart"), destDir, { recursive: true });
+    // Never copy dev node_modules / test output into the temp demo (Playwright double-load).
+    rmSync(join(destDir, "node_modules"), { recursive: true, force: true });
+    rmSync(join(destDir, "test-results"), { recursive: true, force: true });
+    rmSync(join(destDir, "package-lock.json"), { force: true });
     try {
         await wireQuickstartToPackageRoot(destDir);
     }
@@ -2301,12 +2380,20 @@ async function runTryDemo() {
         process.exitCode = 1;
         return;
     }
+    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
+    // Default: headed stepper, manual Next. --video records that session (not headless rush).
     process.env.WAYGRAPH_HEADED ??= "1";
     process.env.WAYGRAPH_STEP ??= "1";
-    // Manual Next by default - onboarding should not race ahead on autoplay.
     process.env.WAYGRAPH_AUTOPLAY ??= "0";
-    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
-    console.log("waygraph try demo: step-through chainFlow (Episode 1: Sign In -> Episode 2: Viewer blocked login) - click Next for each step ...");
+    // Explicit --no-step --video = unattended headless .webm only.
+    if (process.env.WAYGRAPH_VIDEO && process.env.WAYGRAPH_STEP === "0") {
+        process.env.WAYGRAPH_AUTOPLAY ??= "1";
+    }
+    const videoTo = process.env.WAYGRAPH_VIDEO;
+    console.log(videoTo
+        ? "waygraph try demo: step-through + record (Episode 1: Shop & Checkout -> Episode 2: blocked login) - click Next; video -> " +
+            (videoTo === "1" ? ".waygraph-videos/" : videoTo)
+        : "waygraph try demo: step-through (Episode 1: Shop & Checkout -> Episode 2: blocked login) - click Next for each step ...");
     await runChain(destDir, TRY_DEMO_CHAIN);
     if (process.exitCode)
         return;
@@ -2317,13 +2404,13 @@ async function runTryDemo() {
         return;
     }
     const testFile = join(destDir, "tests", "chain-flow.spec.ts");
-    const loginFlowFile = join(destDir, "src", "flows", "login.flow.ts");
+    const shopFlowFile = join(destDir, "src", "flows", "shop.flow.ts");
     const viewerBlockedFlowFile = join(destDir, "src", "flows", "viewer-blocked.flow.ts");
     console.log("\nwaygraph try demo: done.\n\n" +
         "Temp project (does not touch your cwd - lives under the OS temp dir):\n" +
         `  ${destDir}\n\n` +
         "Episodes you just watched (same Flow objects the test imports):\n" +
-        `  ${loginFlowFile}\n` +
+        `  ${shopFlowFile}\n` +
         `  ${viewerBlockedFlowFile}\n\n` +
         "Headless chainFlow test (automated - no clicking):\n" +
         `  ${testFile}\n\n` +
@@ -2551,11 +2638,14 @@ function parseRunFlags(argv) {
             }
             out.title = v;
         }
-        else if (a === "--video") {
-            out.video = "";
-        }
-        else if (a.startsWith("--video=")) {
-            out.video = a.slice("--video=".length);
+        else if (a === "--video" || a.startsWith("--video=")) {
+            const v = a.includes("=") ? a.slice("--video=".length) : argv[++i];
+            if (v === undefined || (v.startsWith("-") && !a.includes("="))) {
+                out.video = "";
+            }
+            else {
+                out.video = v;
+            }
         }
         else {
             out.positionals.push(a);
@@ -2629,6 +2719,11 @@ function applyDemoDefaults(projectDir) {
     if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {
         process.env.WAYGRAPH_HEADED = "1";
     }
+    if (process.env.WAYGRAPH_VIDEO &&
+        process.env.WAYGRAPH_STEP === "0" &&
+        process.env.WAYGRAPH_AUTOPLAY === undefined) {
+        process.env.WAYGRAPH_AUTOPLAY = "1";
+    }
     if (!process.env.WAYGRAPH_BASE_URL) {
         const resolved = resolveBaseUrl(projectDir);
         if (resolved)

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "waygraph",
-  "version": "0.7.6",
+  "version": "0.7.9",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
+  "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

package/templates/quickstart/node_modules/.package-lock.json

@@ -4,7 +4,8 @@
   "requires": true,
   "packages": {
     "../..": {
-      "version": "0.7.5",
+      "version": "0.7.7",
+      "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"
       },
@@ -20,10 +21,120 @@
         "@playwright/test": "^1.40.0"
       }
     },
+    "../../../../projects_waygraph/node_modules/@playwright/test": {
+      "version": "1.63.0",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.63.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "../../node_modules/@esbuild/linux-x64": {
+      "version": "0.28.2",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "../../node_modules/@playwright/test": {
+      "resolved": "../../../../projects_waygraph/node_modules/@playwright/test",
+      "link": true
+    },
+    "../../node_modules/@types/node": {
+      "version": "26.4.0",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.3.0"
+      }
+    },
+    "../../node_modules/esbuild": {
+      "version": "0.28.2",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.2",
+        "@esbuild/android-arm": "0.28.2",
+        "@esbuild/android-arm64": "0.28.2",
+        "@esbuild/android-x64": "0.28.2",
+        "@esbuild/darwin-arm64": "0.28.2",
+        "@esbuild/darwin-x64": "0.28.2",
+        "@esbuild/freebsd-arm64": "0.28.2",
+        "@esbuild/freebsd-x64": "0.28.2",
+        "@esbuild/linux-arm": "0.28.2",
+        "@esbuild/linux-arm64": "0.28.2",
+        "@esbuild/linux-ia32": "0.28.2",
+        "@esbuild/linux-loong64": "0.28.2",
+        "@esbuild/linux-mips64el": "0.28.2",
+        "@esbuild/linux-ppc64": "0.28.2",
+        "@esbuild/linux-riscv64": "0.28.2",
+        "@esbuild/linux-s390x": "0.28.2",
+        "@esbuild/linux-x64": "0.28.2",
+        "@esbuild/netbsd-arm64": "0.28.2",
+        "@esbuild/netbsd-x64": "0.28.2",
+        "@esbuild/openbsd-arm64": "0.28.2",
+        "@esbuild/openbsd-x64": "0.28.2",
+        "@esbuild/openharmony-arm64": "0.28.2",
+        "@esbuild/sunos-x64": "0.28.2",
+        "@esbuild/win32-arm64": "0.28.2",
+        "@esbuild/win32-ia32": "0.28.2",
+        "@esbuild/win32-x64": "0.28.2"
+      }
+    },
+    "../../node_modules/tsx": {
+      "version": "4.23.13",
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "../../node_modules/typescript": {
+      "version": "5.9.3",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "../../node_modules/undici-types": {
+      "version": "8.3.0",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@playwright/test": {
       "version": "1.63.0",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.63.0.tgz",
-      "integrity": "sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
@@ -38,8 +149,6 @@
     },
     "node_modules/@types/node": {
       "version": "26.6.1",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.1.tgz",
-      "integrity": "sha512-VqGJBMCtdhqkBUCcBLvywI0NJ+KLuVzgNnlBUNFOQjqVxzo2lxLUNg1DSey8+u2u6ktswSAxg+s68QLzWHNOuA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -48,8 +157,6 @@
     },
     "node_modules/playwright": {
       "version": "1.63.0",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.63.0.tgz",
-      "integrity": "sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
@@ -64,8 +171,6 @@
     },
     "node_modules/playwright-core": {
       "version": "1.63.0",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.63.0.tgz",
-      "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
@@ -77,8 +182,6 @@
     },
     "node_modules/typescript": {
       "version": "5.9.3",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
-      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
@@ -91,8 +194,6 @@
     },
     "node_modules/undici-types": {
       "version": "8.9.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
-      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
       "dev": true,
       "license": "MIT"
     },

package/templates/quickstart/package.json

@@ -2,17 +2,17 @@
   "name": "waygraph-quickstart",
   "private": true,
   "type": "module",
-  "description": "Self-contained saucedemo quickstart - 2-episode chainFlow demo (Sign In + blocked Viewer login).",
+  "description": "Self-contained saucedemo quickstart - Episode 1 Shop & Checkout, Episode 2 blocked login.",
   "scripts": {
     "test": "playwright test",
-    "demo": "waygraph chain \"loginFlow({\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}) then viewerBlockedFlow({\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"})\" . --step --no-autoplay",
-    "record": "waygraph chain \"loginFlow({\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}) then viewerBlockedFlow({\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"})\" . --video --no-step"
+    "demo": "waygraph chain \"shopFlow({\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}) then viewerBlockedFlow({\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"})\" . --step --no-autoplay",
+    "record": "waygraph chain \"shopFlow({\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}) then viewerBlockedFlow({\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"})\" . --video --no-step"
   },
   "waygraph": {
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.7.6"
+    "waygraph": "^0.7.7"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/quickstart/src/blocks/actions/add-to-cart.action.block.ts

@@ -0,0 +1,15 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { LoggedIn, ItemInCart } from "../../states/checkout.states.js";
+
+export const AddToCartBlock = defineBlock<LoggedIn, ItemInCart>({
+  name: "add-to-cart",
+  description: "Adds the Sauce Labs Backpack and confirms the cart badge shows 1 item.",
+  instruction: {
+    async act(page) {
+      await page.locator("#add-to-cart-sauce-labs-backpack").click();
+    },
+    resolve: () => checkpoint("ItemInCart"),
+    verify: [Trait.text(".shopping_cart_badge", "1")],
+    highlights: () => [{ selector: ".shopping_cart_badge", label: "remember this: cart now has 1 item" }],
+  },
+});

package/templates/quickstart/src/blocks/actions/finish-order.action.block.ts

@@ -0,0 +1,16 @@
+import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
+import type { CheckoutOverviewPage, OrderComplete } from "../../states/checkout.states.js";
+
+export const FinishOrderBlock = defineBlock<CheckoutOverviewPage, OrderComplete>({
+  name: "finish-order",
+  description: "Places the order and confirms the completion page.",
+  instruction: {
+    async act(page) {
+      const finishButton = page.locator("#finish");
+      await narrate(finishButton, "Placing the order", () => finishButton.click());
+    },
+    resolve: () => checkpoint("OrderComplete"),
+    verify: [Trait.text(".complete-header", "Thank you for your order!")],
+    highlights: () => [{ selector: ".complete-header", label: "remember this: order confirmed" }],
+  },
+});

package/templates/quickstart/src/blocks/actions/submit-checkout-info.action.block.ts

@@ -0,0 +1,17 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../states/checkout.states.js";
+
+export const SubmitCheckoutInfoBlock = defineBlock<CheckoutInfoPage, CheckoutOverviewPage>({
+  name: "submit-checkout-info",
+  description: "Fills shipping info and continues to the order overview.",
+  instruction: {
+    async act(page) {
+      await page.locator("#first-name").fill("Ada");
+      await page.locator("#last-name").fill("Lovelace");
+      await page.locator("#postal-code").fill("1000");
+      await page.locator("#continue").click();
+    },
+    resolve: () => checkpoint("CheckoutOverviewPage"),
+    verify: [Trait.url({ pathname: "/checkout-step-two.html" })],
+  },
+});

package/templates/quickstart/src/blocks/nav-cart.block.ts

@@ -0,0 +1,10 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { CartPage } from "../states/checkout.states.js";
+
+export const NavCartBlock = defineNavBlock<CartPage>({
+  name: "nav-cart",
+  description: "Clicks the cart link in the header.",
+  checkpoint: "CartPage",
+  click: ".shopping_cart_link",
+  verify: [Trait.url({ pathname: "/cart.html" })],
+});

package/templates/quickstart/src/blocks/nav-checkout-info.block.ts

@@ -0,0 +1,10 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { CheckoutInfoPage } from "../states/checkout.states.js";
+
+export const NavCheckoutInfoBlock = defineNavBlock<CheckoutInfoPage>({
+  name: "nav-checkout-info",
+  description: "Clicks Checkout on the cart page.",
+  checkpoint: "CheckoutInfoPage",
+  click: "#checkout",
+  verify: [Trait.url({ pathname: "/checkout-step-one.html" })],
+});

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

@@ -4,7 +4,7 @@ import { SubmitLoginActionBlock } from "../blocks/actions/submit-login.action.bl
 
 const engine = new Engine();
 
-// Episode 1 - the step overlay shows "Episode 1: Sign In".
+// Optional standalone sign-in only (try demo uses shopFlow as Episode 1).
 export const loginFlow = withTitle(
   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
   "Sign In",

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

@@ -0,0 +1,26 @@
+import { Engine, start, end, withTitle } from "waygraph";
+import { NavLoginBlock } from "../blocks/nav-login.block.js";
+import { SubmitLoginActionBlock } from "../blocks/actions/submit-login.action.block.js";
+import { AddToCartBlock } from "../blocks/actions/add-to-cart.action.block.js";
+import { NavCartBlock } from "../blocks/nav-cart.block.js";
+import { NavCheckoutInfoBlock } from "../blocks/nav-checkout-info.block.js";
+import { SubmitCheckoutInfoBlock } from "../blocks/actions/submit-checkout-info.action.block.js";
+import { FinishOrderBlock } from "../blocks/actions/finish-order.action.block.js";
+
+const engine = new Engine();
+
+// Episode 1 - sign in, shop, checkout, place order.
+export const shopFlow = withTitle(
+  engine.defineFlow([
+    start,
+    NavLoginBlock,
+    SubmitLoginActionBlock,
+    AddToCartBlock,
+    NavCartBlock,
+    NavCheckoutInfoBlock,
+    SubmitCheckoutInfoBlock,
+    FinishOrderBlock,
+    end,
+  ]),
+  "Shop & Checkout",
+);

package/templates/quickstart/src/states/checkout.states.ts

@@ -2,3 +2,8 @@ import type { Checkpoint } from "waygraph";
 
 export type LoginPage = Checkpoint<"LoginPage">;
 export type LoggedIn = Checkpoint<"LoggedIn">;
+export type ItemInCart = Checkpoint<"ItemInCart">;
+export type CartPage = Checkpoint<"CartPage">;
+export type CheckoutInfoPage = Checkpoint<"CheckoutInfoPage">;
+export type CheckoutOverviewPage = Checkpoint<"CheckoutOverviewPage">;
+export type OrderComplete = Checkpoint<"OrderComplete">;

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

@@ -1,39 +1,44 @@
 import { test, expect } from "@playwright/test";
 import { MemPage, checkpoint, chainFlow } from "waygraph";
-import { loginFlow } from "../src/flows/login.flow.js";
+import { shopFlow } from "../src/flows/shop.flow.js";
 import { viewerBlockedFlow } from "../src/flows/viewer-blocked.flow.js";
 import { LoginCreds, ViewerCreds } from "../src/states/checkout.mem-keys.js";
 
-test("chainFlow: Episode 1 signs in, Episode 2 blocked login genuinely fails", async () => {
+test("chainFlow: Episode 1 shops through checkout, Episode 2 blocked login genuinely fails", async () => {
   const mem = new MemPage();
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
   mem.set(ViewerCreds({ username: "locked_out_user", password: "secret_sauce" }));
 
-  const combined = chainFlow(loginFlow, viewerBlockedFlow);
+  const combined = chainFlow(shopFlow, viewerBlockedFlow);
 
   await expect(combined.run(mem)).rejects.toThrow(/viewer-login/);
 });
 
-test("episode 1 alone: standard_user reaches inventory", async () => {
+test("episode 1 alone: standard_user completes checkout", async () => {
   const mem = new MemPage();
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
 
-  const result = await loginFlow.run(mem);
+  const result = await shopFlow.run(mem);
 
-  expect(result).toEqual(checkpoint("LoggedIn"));
+  expect(result).toEqual(checkpoint("OrderComplete"));
 });
 
 test("chainFlow blocks() lists the flattened episode chain in order", () => {
-  expect(loginFlow.title).toBe("Sign In");
+  expect(shopFlow.title).toBe("Shop & Checkout");
   expect(viewerBlockedFlow.title).toBe("Viewer: Blocked Login Attempt");
 
-  const blocks = chainFlow(loginFlow, viewerBlockedFlow).blocks();
+  const blocks = chainFlow(shopFlow, viewerBlockedFlow).blocks();
   expect(blocks.map((b) => b.name)).toEqual([
     "nav-login",
     "submit-login",
+    "add-to-cart",
+    "nav-cart",
+    "nav-checkout-info",
+    "submit-checkout-info",
+    "finish-order",
     "nav-login",
     "viewer-login",
   ]);
   expect(blocks[0]!.resetSessionBefore).toBeUndefined();
-  expect(blocks[2]!.resetSessionBefore).toBe(true);
+  expect(blocks[7]!.resetSessionBefore).toBe(true);
 });