waygraph 0.16.1 → 0.16.4

package/dist/runner/plan/find.js

@@ -32,11 +32,11 @@ export async function findBlock(projectDir, ref) {
     if (byRuntimeName.length === 1)
         return byRuntimeName[0];
     if (byRuntimeName.length > 1) {
-        throw new Error("waygraph chain: \"" + ref + "\" matches " + byRuntimeName.length + " Blocks by name - " +
+        throw new Error("waygraph run --blocks: \"" + ref + "\" matches " + byRuntimeName.length + " Blocks by name - " +
             byRuntimeName.map((b) => b.exportName + " (" + b.file + ")").join(", ") +
             ". Use the export name to disambiguate.");
     }
-    throw new Error("waygraph chain: no Block named \"" + ref + "\" found under " + projectDir);
+    throw new Error("waygraph run --blocks: no Block named \"" + ref + "\" found under " + projectDir);
 }
 /**
  * Finds an already-defined Flow by its export name (e.g. loginFlow) among

package/dist/runner/plan/plan.js

@@ -24,7 +24,7 @@ async function findBareFlow(projectDir, spec) {
 function parseSegments(spec) {
     const segments = parseChainSpec(spec);
     if (segments.length === 0)
-        throw new Error("waygraph chain: empty spec - give at least one block name");
+        throw new Error("waygraph run --blocks: empty spec - give at least one block name");
     return segments;
 }
 async function resolveSegment(projectDir, seg, mem, options) {

package/dist/runner/plan/seed-mem.js

@@ -4,7 +4,7 @@ const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
 function seedMemFromRequires(mem, requires, json, label, stubActive) {
     if (requires.length === 0) {
         if (json !== undefined) {
-            throw new Error("waygraph chain: \"" + label + "\" takes no input (empty requires) but got a payload: " + json);
+            throw new Error("waygraph run --blocks: \"" + label + "\" takes no input (empty requires) but got a payload: " + json);
         }
         return;
     }
@@ -22,7 +22,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
             haveParsed = true;
         }
         catch (err) {
-            throw new Error("waygraph chain: \"" + label + "\" payload is not valid JSON - " + String(err));
+            throw new Error("waygraph run --blocks: \"" + label + "\" payload is not valid JSON - " + String(err));
         }
     }
     if (!haveParsed) {
@@ -30,7 +30,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
         // this flow; when it is, fall through with an empty object so the
         // per-key loop below gets a chance to fill each one from the registry.
         if (!stubActive) {
-            throw new Error("waygraph chain: \"" + label + "\" requires " + requires.map((k) => k.name).join(", ") +
+            throw new Error("waygraph run --blocks: \"" + label + "\" requires " + requires.map((k) => k.name).join(", ") +
                 " - give a JSON payload (inline blockName({...}) or --data '{...}'), or enable --mem-stub" +
                 " with registerMemStub for these keys");
         }
@@ -54,7 +54,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
         return;
     }
     if (!isRecord(parsed)) {
-        throw new Error("waygraph chain: \"" + label + "\" requires " + requires.length + " keys (" +
+        throw new Error("waygraph run --blocks: \"" + label + "\" requires " + requires.length + " keys (" +
             requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name");
     }
     const payload = parsed;
@@ -72,7 +72,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
         stillMissing.push(k);
     }
     if (stillMissing.length > 0) {
-        throw new Error("waygraph chain: \"" + label + "\" payload is missing required key(s): " +
+        throw new Error("waygraph run --blocks: \"" + label + "\" payload is missing required key(s): " +
             stillMissing.map((k) => "\"" + k.name + "\"").join(", "));
     }
 }

package/dist/runner/plan/spec.js

@@ -8,7 +8,7 @@ export function parseChainSpec(spec) {
         .map((s) => {
         const m = /^([A-Za-z_$][\w-]*)\s*(?:\(([\s\S]*)\))?$/.exec(s);
         if (!m) {
-            throw new Error("waygraph chain: could not parse segment \"" + s + "\" - expected \"blockName\" or \"blockName({...json...})\"");
+            throw new Error("waygraph run --blocks: could not parse segment \"" + s + "\" - expected \"blockName\" or \"blockName({...json...})\"");
         }
         const ref = m[1];
         const json = m[2] ? m[2].trim() : undefined;

package/dist/runner/runner.d.ts

@@ -1,4 +1,3 @@
-import "../runtime/run-log.js";
 export declare function play(projectDir: string, spec: string): Promise<void>;
 /** The process entry the CLI's bootstrap calls: one run (and one run log) per invocation. */
 export declare function startRunner(): void;

package/dist/runner/runner.js

@@ -2,9 +2,10 @@
 // Playwright is used) with the project dir and the spec ("cartFlow", "loginFlow then add-item"). Every mode plays the
 // same steps through the same engine; the mode decides what happens around each step.
 import { MemPage } from "../engine/mem/mem.js";
-import { beginRun, endRun } from "../engine/run/events.js";
+import { inRun } from "../engine/run/events.js";
 import { withWebServer } from "../runtime/webserver.js";
-import "../runtime/run-log.js";
+import { installRunLog } from "../runtime/run-log.js";
+import { loadReadBlocks } from "../manifest/read-blocks.js";
 import { planSteps } from "./plan/plan.js";
 import { readOptions, slowMoFor } from "./options.js";
 import { openSession } from "./session.js";
@@ -16,6 +17,7 @@ import { reportMode } from "./modes/report.js";
 export async function play(projectDir, spec) {
     const options = readOptions();
     const mem = new MemPage();
+    await loadReadBlocks(projectDir);
     const { steps, flows } = await planSteps(projectDir, spec, mem, options);
     if (options.mode === "branches")
         return playBranches(flows, mem, options);
@@ -52,12 +54,10 @@ function finish(outcome) {
 }
 /** The process entry the CLI's bootstrap calls: one run (and one run log) per invocation. */
 export function startRunner() {
+    installRunLog();
     const projectDir = process.argv[2] ?? process.cwd();
     const spec = process.argv[3] ?? "";
-    const opened = beginRun(spec);
-    withWebServer(projectDir, () => play(projectDir, spec))
-        .then(() => endRun(opened, {}), (err) => {
-        endRun(opened, { error: err });
+    inRun(spec, () => withWebServer(projectDir, () => play(projectDir, spec))).catch((err) => {
         console.error(err && err.stack ? err.stack : String(err));
         process.exitCode = 1;
     });

package/dist/runtime/full-launch.d.ts

@@ -1 +1,2 @@
-export {};
+/** How an Engine launches its own browser: the selected config (--config), the Chromium override, the extensions. Called by the package entry. */
+export declare function installFullLaunch(): void;

package/dist/runtime/full-launch.js

@@ -4,31 +4,33 @@ import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "./
 import { resolveExtensions } from "./extensions.js";
 import { loadWaygraphConfig } from "./waygraph-config.js";
 import { envString } from "../engine/env.js";
-// An Engine's own browser follows the selected config (--config), the Chromium override and the configured extensions.
-setOwnContextLauncher(async (engineConfig) => {
-    // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with.
-    const chosen = envString("WAYGRAPH_CONFIG") ? await loadWaygraphConfig(process.cwd()) : undefined;
-    const config = chosen
-        ? {
-            ...engineConfig,
-            ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
-            ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
-        }
-        : engineConfig;
-    const browserName = config?.browserName ?? "chromium";
-    const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-    const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
-    return launchContext({
-        launcher: resolveLauncher(browserName, config),
-        launch: {
-            headless: config?.headless ?? true,
-            ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-            ...(executablePath ? { executablePath } : {}),
-        },
-        context: {
-            ...(baseURL ? { baseURL } : {}),
-            ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
-        },
-        extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+/** How an Engine launches its own browser: the selected config (--config), the Chromium override, the extensions. Called by the package entry. */
+export function installFullLaunch() {
+    setOwnContextLauncher(async (engineConfig) => {
+        // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with.
+        const chosen = envString("WAYGRAPH_CONFIG") ? await loadWaygraphConfig(process.cwd()) : undefined;
+        const config = chosen
+            ? {
+                ...engineConfig,
+                ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
+                ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
+            }
+            : engineConfig;
+        const browserName = config?.browserName ?? "chromium";
+        const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
+        const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
+        return launchContext({
+            launcher: resolveLauncher(browserName, config),
+            launch: {
+                headless: config?.headless ?? true,
+                ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+                ...(executablePath ? { executablePath } : {}),
+            },
+            context: {
+                ...(baseURL ? { baseURL } : {}),
+                ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+            },
+            extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+        });
     });
-});
+}

package/dist/runtime/run-log.d.ts

@@ -1,2 +1,4 @@
+/** Starts writing run events to the run log. Called by the package entry and the runner; a second call does nothing. */
+export declare function installRunLog(): void;
 /** The folder run logs go to for a project unless the config or the environment says otherwise. */
 export declare function defaultRunLogDir(projectDir: string): string;

package/dist/runtime/run-log.js

@@ -4,13 +4,20 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { onRunEvent } from "../engine/run/events.js";
 import { envString } from "../engine/env.js";
-onRunEvent((event) => {
-    const dir = envString("WAYGRAPH_RUN_LOG");
-    if (!dir || dir === "0")
+let installed = false;
+/** Starts writing run events to the run log. Called by the package entry and the runner; a second call does nothing. */
+export function installRunLog() {
+    if (installed)
         return;
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, `${event.runId}.jsonl`), JSON.stringify(event) + "\n");
-});
+    installed = true;
+    onRunEvent((event) => {
+        const dir = envString("WAYGRAPH_RUN_LOG");
+        if (!dir || dir === "0")
+            return;
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, `${event.runId}.jsonl`), JSON.stringify(event) + "\n");
+    });
+}
 /** The folder run logs go to for a project unless the config or the environment says otherwise. */
 export function defaultRunLogDir(projectDir) {
     return join(projectDir, ".waygraph", "runs");

package/examples/saucedemo/README.md

@@ -13,7 +13,7 @@ the **reference** for waygraph consumer conventions:
 - `defineApiBlock` - a real backend/HTTP check as one step in the same Flow as
   a UI step, with its own live network-activity panel during a demo - see
   `apiDemoFlow` (`src/flows/api-demo.flow.ts`)
-- `ctx.caption()` (bottom subtitle-bar) + `ctx.titlePos()` (banner
+- `ctx.ui.caption()` (bottom subtitle-bar) + `ctx.ui.titlePos()` (banner
   left/center/right) - also on `checkoutFlow`
 
 **GitHub Pages walkthrough:**
@@ -48,7 +48,7 @@ npx playwright install chromium
 | **Device showcase** (mobile/tablet + portrait/landscape; narration in `src/stubs/device-showcase.ts`) | `npm run demo:device` |
 | Device showcase + `.webm` | `npm run demo:video` |
 | **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
-| **Owner checkout** (inline `{ ff: true }`, `ctx.caption()`, banner position) | `npm run demo:checkout` |
+| **Owner checkout** (inline `{ ff: true }`, `ctx.ui.caption()`, banner position) | `npm run demo:checkout` |
 | **FE + BE in one Flow** (`defineApiBlock`, live network panel) | `npm run demo:api` |
 | Record (headless `.webm`) | `npm run record` |
 | List flows | `npm run flows` |

package/examples/saucedemo/src/blocks/SITE-MAP.md

@@ -9,6 +9,7 @@ src/blocks/
   saucedemo-web/                      # URL /
     NAV.md
     nav-login.block.ts                # Page  definePageBlock url:/
+    header.read.block.ts              # Read  defineReadBlock (beta, every page: title, cart count)
     methods/
       fill-username.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
       fill-password.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
@@ -18,6 +19,7 @@ src/blocks/
       login.sel.ts                    # LoginSel (not a Block)
     inventory/                        # URL /inventory.html
       inventory.page.block.ts       # Page definePageBlock
+      inventory.read.block.ts       # Read defineReadBlock (beta: products, prices, in cart, sort)
       NAV.md
       nav-item-detail.block.ts        # Nav  defineMemNavBlock (instance row)
       methods/
@@ -36,6 +38,7 @@ src/blocks/
       NAV.md
       cart.sel.ts                     # CartSel (not a Block)
       nav-cart.block.ts               # Nav click header cart
+      cart.read.block.ts              # Read defineReadBlock (beta: the cart's lines)
       nav-checkout-info.block.ts
     checkout-step-one/                # URL /checkout-step-one.html
       NAV.md

package/examples/saucedemo/src/blocks/saucedemo-web/cart/cart.read.block.ts

@@ -0,0 +1,26 @@
+import { defineReadBlock } from "waygraph/beta";
+import { CartPage } from "../../../states/checkout.states.js";
+import { Cart } from "../../../states/checkout.reads.js";
+
+/**
+ * Kind: Read (beta)
+ * Helper: defineReadBlock
+ * Route: saucedemo-web/cart/  (= /cart.html)
+ *
+ * The cart's lines: name, quantity and price.
+ */
+export const CartReadBlock = defineReadBlock({
+  name: "read-cart",
+  description: "Each line in the cart: name, quantity, price.",
+  from: CartPage,
+  instruction: {
+    read: (ctx) =>
+      Cart({
+        lines: ctx.page.list(".cart_item", (row) => ({
+          name: row.text(".inventory_item_name"),
+          qty: row.number(".cart_quantity"),
+          price: row.number(".inventory_item_price"),
+        })),
+      }),
+  },
+});

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts

@@ -1,4 +1,4 @@
-import { defineMethodBlock, Trait, narrate } from "waygraph";
+import { defineMethodBlock, Trait } from "waygraph";
 import {
   CheckoutOverviewPage,
   OrderComplete,
@@ -21,9 +21,7 @@ export const FinishOrderBlock = defineMethodBlock({
   instruction: {
     async act(page) {
       const finishButton = page.locator(CheckoutOverviewSel.finishBtn);
-      await narrate(finishButton, "Placing the order", () =>
-        finishButton.click(),
-      );
+      await finishButton.click();
     },
     verify: [
       Trait.text(
@@ -31,35 +29,5 @@ export const FinishOrderBlock = defineMethodBlock({
         "Thank you for your order!",
       ),
     ],
-    // Shown AFTER act (order already placed) - selectors must match the
-    // completion page, not #finish on the overview.
-    slides: [
-      {
-        caption: "Checkout is a short pipeline",
-        detail: "Cart -> info -> overview -> done. You just placed the order.",
-        tag: "YAP",
-        tone: "info",
-        duration: true,
-      },
-      {
-        caption: "Completion page is the durable proof",
-        detail:
-          "tone: success - the thank-you header is what verify asserts on.",
-        tag: "YAP",
-        tone: "success",
-        selector: CheckoutOverviewSel.completeHeader,
-        duration: 2500,
-        fastMode: 700,
-      },
-      {
-        caption: "Episode continues after this yap",
-        detail: "Next step rings the same banner, then you move on.",
-        tag: "YAP",
-        tone: "planned",
-        selector: CheckoutOverviewSel.completeHeader,
-        duration: true,
-        fastMode: 500,
-      },
-    ],
   },
 });

package/examples/saucedemo/src/blocks/saucedemo-web/header.read.block.ts

@@ -0,0 +1,25 @@
+import { defineReadBlock } from "waygraph/beta";
+import { Header } from "../../states/checkout.reads.js";
+import { InventorySel } from "./inventory/methods/inventory-items.js";
+
+/**
+ * Kind: Read (beta)
+ * Helper: defineReadBlock
+ * Route: saucedemo-web/  (every signed-in page)
+ *
+ * The header every page shares: the page title and how many items are in the cart (0 when the badge is not shown).
+ */
+export const HeaderReadBlock = defineReadBlock({
+  name: "read-header",
+  description: "The page title and the cart count.",
+  instruction: {
+    read: (ctx) =>
+      Header({
+        title: ctx.page.text(".title"),
+        cartCount: ctx.page.fn(async (page) => {
+          const badge = page.locator(InventorySel.cartBadge);
+          return (await badge.count()) ? Number(await badge.first().innerText()) : 0;
+        }),
+      }),
+  },
+});

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/inventory.read.block.ts

@@ -0,0 +1,28 @@
+import { defineReadBlock } from "waygraph/beta";
+import { ItemInCart, LoggedIn } from "../../../states/checkout.states.js";
+import { Catalog } from "../../../states/checkout.reads.js";
+import { InventorySel } from "./methods/inventory-items.js";
+
+/**
+ * Kind: Read (beta)
+ * Helper: defineReadBlock
+ * Route: saucedemo-web/inventory/  (= /inventory.html)
+ *
+ * The catalogue as data: every product with its price and whether it is in the cart, and the sort order.
+ */
+export const InventoryReadBlock = defineReadBlock({
+  name: "read-inventory",
+  description: "Every product, its price and whether it is in the cart; the sort order.",
+  from: [LoggedIn, ItemInCart],
+  instruction: {
+    read: (ctx) =>
+      Catalog({
+        items: ctx.page.list(InventorySel.card, (row) => ({
+          name: row.text(InventorySel.name),
+          price: row.number(".inventory_item_price"),
+          inCart: row.visible(InventorySel.removeBtnPrefix),
+        })),
+        sort: ctx.page.value(".product_sort_container"),
+      }),
+  },
+});

package/examples/saucedemo/src/flows/api-demo.flow.ts

@@ -32,7 +32,7 @@ export const apiDemoEpisode = engine
   .start()
   .method(
     CheckBackendHealth.stubBefore((ctx) => {
-      ctx.title("Checking backend health · real HTTP request, no browser");
+      ctx.ui.title("Checking backend health · real HTTP request, no browser");
     }),
   )
   .end();

package/examples/saucedemo/src/flows/cart-bulk.flow.ts

@@ -10,7 +10,7 @@ export const cartBulkEpisode = engine
   .start()
   .method(
     AddAllToCartBlock.stubBefore((ctx) =>
-      ctx.title("Cart bulk add/remove all"),
+      ctx.ui.title("Cart bulk add/remove all"),
     ),
   )
   .method(RemoveAllFromCartBlock)

package/examples/saucedemo/src/flows/cart-continue.flow.ts

@@ -7,7 +7,7 @@ export const cartContinueFlow = engine
   .map()
   .start()
   .gotoPage(
-    NavCartBlock.stubBefore((ctx) => ctx.title("Cart then continue shopping")),
+    NavCartBlock.stubBefore((ctx) => ctx.ui.title("Cart then continue shopping")),
   )
   .gotoPage(NavContinueShoppingBlock)
   .end();

package/examples/saucedemo/src/flows/catalog-logout.flow.ts

@@ -9,7 +9,7 @@ export const catalogLogoutFlow = engine
   .start()
   .gotoPage(
     NavItemDetailBlock.stubBefore((ctx) =>
-      ctx.title("Catalog browse then logout"),
+      ctx.ui.title("Catalog browse then logout"),
     ),
   )
   .gotoPage(NavBackToInventoryBlock)

package/examples/saucedemo/src/flows/checkout-then-browse-again.flow.ts

@@ -12,6 +12,7 @@ import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/met
 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 { orderPlacedYap, placingOrder } from "../stubs/finish-order.js";
 import { NavBackToProductsBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-products.block.js";
 
 /** Full checkout, then the "Back Home" click-based Nav Block returns to the catalogue. */
@@ -20,7 +21,7 @@ export const checkoutThenBrowseAgainFlow = engine
   .start()
   .gotoPage(
     NavLoginBlock.stubBefore((ctx) =>
-      ctx.title(
+      ctx.ui.title(
         "Owner: Checkout, then click Back Home (click-based NavBlock demo)",
       ),
     ),
@@ -35,6 +36,6 @@ export const checkoutThenBrowseAgainFlow = engine
   .method(FillLastNameBlock)
   .method(FillPostalCodeBlock)
   .method(SubmitCheckoutInfoBlock)
-  .method(FinishOrderBlock)
+  .method(FinishOrderBlock.stubBefore(placingOrder).stubAfter(orderPlacedYap))
   .gotoPage(NavBackToProductsBlock)
   .end();

package/examples/saucedemo/src/flows/checkout.flow.ts

@@ -12,6 +12,7 @@ import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/met
 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 { orderPlacedYap, placingOrder } from "../stubs/finish-order.js";
 import { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
 
 export const checkoutFlow = engine
@@ -20,7 +21,7 @@ export const checkoutFlow = engine
   .gotoPage(NavLoginBlock, { ff: true })
   .method(
     FillUsernameBlock.stubBefore((ctx) => {
-      ctx.ring("username", {
+      ctx.ui.ring("username", {
         selector: LoginSel.username,
         label: "Demo user",
         detail:
@@ -34,7 +35,7 @@ export const checkoutFlow = engine
   )
   .method(
     FillPasswordBlock.stubBefore((ctx) => {
-      ctx.ring("password", {
+      ctx.ui.ring("password", {
         selector: LoginSel.password,
         label: "Password",
         detail: "Filled from Mem credentials.",
@@ -46,7 +47,7 @@ export const checkoutFlow = engine
   )
   .method(
     SubmitLoginForFlow.stubBefore((ctx) => {
-      ctx.ring("submit", {
+      ctx.ui.ring("submit", {
         selector: LoginSel.loginButton,
         label: "Sign in",
         tag: "GATE",
@@ -58,27 +59,27 @@ export const checkoutFlow = engine
     }),
     { ff: true },
   )
-  .method(AddToCartBlock.stubBefore((ctx) => ctx.title("Owner: Full Checkout")))
+  .method(AddToCartBlock.stubBefore((ctx) => ctx.ui.title("Owner: Full Checkout")))
   .gotoPage(NavCartBlock)
   .gotoPage(NavCheckoutInfoBlock)
   .method(
     FillFirstNameBlock.stubBefore((ctx) => {
-      ctx.caption("Enter the first name on the order");
-      ctx.titlePos("left");
+      ctx.ui.caption("Enter the first name on the order");
+      ctx.ui.titlePos("left");
     }),
   )
   .method(
     FillLastNameBlock.stubBefore((ctx) => {
-      ctx.caption("Enter the last name on the order");
-      ctx.titlePos("center");
+      ctx.ui.caption("Enter the last name on the order");
+      ctx.ui.titlePos("center");
     }),
   )
   .method(
     FillPostalCodeBlock.stubBefore((ctx) => {
-      ctx.caption("Enter a postal code to calculate shipping");
-      ctx.titlePos("right");
+      ctx.ui.caption("Enter a postal code to calculate shipping");
+      ctx.ui.titlePos("right");
     }),
   )
-  .method(SubmitCheckoutInfoBlock.stubBefore((ctx) => ctx.hideCaption()))
-  .method(FinishOrderBlock)
+  .method(SubmitCheckoutInfoBlock.stubBefore((ctx) => ctx.ui.hideCaption()))
+  .method(FinishOrderBlock.stubBefore(placingOrder).stubAfter(orderPlacedYap))
   .end();

package/examples/saucedemo/src/flows/login.flow.ts

@@ -9,7 +9,7 @@ import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login
 export const loginFlow = engine
   .map({ memStub: true })
   .start()
-  .gotoPage(NavLoginBlock.stubBefore((ctx) => ctx.title("Sign In")))
+  .gotoPage(NavLoginBlock.stubBefore((ctx) => ctx.ui.title("Sign In")))
   .method(FillUsernameBlock)
   .method(FillPasswordBlock)
   .method(SubmitLoginForFlow)

package/examples/saucedemo/src/flows/shop.flow.ts

@@ -8,17 +8,18 @@ import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/met
 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 { orderPlacedYap, placingOrder } from "../stubs/finish-order.js";
 
 /** Add the selected item, check out and place the order. Starts signed in (run it after loginFlow). */
 export const shopFlow = engine
   .map({ memStub: true })
   .start()
-  .method(AddToCartBlock.stubBefore((ctx) => ctx.title("Shop & Checkout")))
+  .method(AddToCartBlock.stubBefore((ctx) => ctx.ui.title("Shop & Checkout")))
   .gotoPage(NavCartBlock)
   .gotoPage(NavCheckoutInfoBlock)
   .method(FillFirstNameBlock)
   .method(FillLastNameBlock)
   .method(FillPostalCodeBlock)
   .method(SubmitCheckoutInfoBlock)
-  .method(FinishOrderBlock)
+  .method(FinishOrderBlock.stubBefore(placingOrder).stubAfter(orderPlacedYap))
   .end();

package/examples/saucedemo/src/flows/stub-on-error.flow.ts

@@ -19,7 +19,7 @@ export const stubOnErrorFlow = engine
   .start()
   .gotoPage(
     NavLoginBlock.stubBefore((ctx) =>
-      ctx.title("stubOnError: locked_out fail rings"),
+      ctx.ui.title("stubOnError: locked_out fail rings"),
     ),
   )
   .method(FillUsernameBlock)

package/examples/saucedemo/src/flows/viewer-blocked.flow.ts

@@ -19,7 +19,7 @@ export const viewerBlockedFlow = engine
   .start()
   .gotoPage(
     NavLoginBlock.stubBefore((ctx) =>
-      ctx.title("Viewer: Blocked Login Attempt"),
+      ctx.ui.title("Viewer: Blocked Login Attempt"),
     ),
   )
   .method(FillUsernameBlock)

package/examples/saucedemo/src/states/checkout.reads.ts

@@ -0,0 +1,9 @@
+import { reads } from "waygraph/beta";
+
+// What the store's pages show, by namespace: the Read Blocks fill these, `pilot read` returns them as JSON.
+export const Catalog = reads("catalog")<{
+  items: { name: string; price: number; inCart: boolean }[];
+  sort: string;
+}>();
+export const Cart = reads("cart")<{ lines: { name: string; qty: number; price: number }[] }>();
+export const Header = reads("header")<{ title: string; cartCount: number }>();