waygraph 0.15.2 → 0.15.3

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

@@ -1,4 +1,4 @@
-import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, narrate, type StubCtx } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
 
@@ -8,6 +8,7 @@ import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
  * Route: saucedemo-web/checkout-step-two/methods/  (= /checkout-step-two.html)
  *
  * Places the order on the overview page - form/finish click, not a NavBlock.
+ * Stubs use open ctx lifecycles (preferred) - not static slot maps.
  */
 export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
@@ -19,23 +20,23 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     },
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
-    stubBefore: {
-      finish: {
+    stubBefore: (ctx: StubCtx) => {
+      ctx.ring("finish", {
         selector: CheckoutOverviewSel.finishBtn,
         label: "Finish",
         detail: "tone: warning (yellow) - place order",
         tone: "warning",
         weight: "bold",
-      },
+      });
     },
-    stubAfter: {
-      thanks: {
+    stubAfter: (ctx: StubCtx) => {
+      ctx.ring("thanks", {
         selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
         detail: "tone: success (green) - thank you!",
         tone: "success",
         duration: true,
-      },
+      });
     },
     // Shown AFTER act (order already placed) - selectors must match the
     // completion page, not #finish on the overview.

package/examples/saucedemo/src/blocks/saucedemo-web/methods/fill-password.method.block.ts

@@ -22,16 +22,14 @@ export const FillPasswordBlock = defineMethodBlock<LoginPage, LoginPage>({
     },
     resolve: () => checkpoint("LoginPage"),
     stubBefore: (ctx: StubCtx) => {
-      ctx.highlights({
-        password: {
-          selector: LoginSel.password,
-          label: "Password",
-          detail: "tone: planned (purple)",
-          todo: "login-pass",
-          tone: "planned",
-          focus: true,
-          zoom: 1.4,
-        },
+      ctx.ring("password", {
+        selector: LoginSel.password,
+        label: "Password",
+        detail: "tone: planned (purple)",
+        todo: "login-pass",
+        tone: "planned",
+        focus: true,
+        zoom: 1.4,
       });
     },
     stubAfter: (ctx: StubCtx) => {

package/examples/saucedemo/src/blocks/saucedemo-web/methods/fill-username.method.block.ts

@@ -40,16 +40,17 @@ export const FillUsernameBlock = defineMethodBlock<LoginPage, LoginPage>({
         { title: "Device showcase", index: 0 },
       );
       ctx.zoom(1.35);
-      ctx.highlights({
-        username: {
-          selector: LoginSel.username,
-          label: "Username",
-          detail: "tone: info (blue)",
-          todo: "login-user",
-          tone: "info",
-          focus: true,
-          zoom: 1.4,
-        },
+      const fromMem = ctx.mem?.get(LoginCreds.key)?.username;
+      ctx.ring("username", {
+        selector: LoginSel.username,
+        label: "Username",
+        detail: fromMem
+          ? `tone: info (blue) - mem ${fromMem}`
+          : "tone: info (blue)",
+        tone: "info",
+        todo: "login-user",
+        focus: true,
+        zoom: 1.4,
       });
     },
     stubAfter: (ctx: StubCtx) => {

package/examples/saucedemo/src/blocks/saucedemo-web/methods/submit-login-for-flow.ts

@@ -1,4 +1,4 @@
-import type { DefinedBlock } from "waygraph";
+import type { MethodBlock } from "waygraph";
 import type { LoginPage, LoggedIn } from "../../../states/checkout.states.js";
 import { SubmitLoginBlock } from "./submit-login.method.block.js";
 
@@ -7,7 +7,8 @@ import { SubmitLoginBlock } from "./submit-login.method.block.js";
  * Helper: typed alias over SubmitLoginBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
- * DefinedBlock cast so linear Flows can chain .withVerify on Out=LoggedIn;
- * runtime still branches on bad credentials via SubmitLoginBlock.
+ * MethodBlock cast so map().method() keeps the factory brand while Flows can
+ * treat Out as LoggedIn; runtime still branches on bad credentials via
+ * SubmitLoginBlock.
  */
-export const SubmitLoginForFlow = SubmitLoginBlock as unknown as DefinedBlock<LoginPage, LoggedIn>;
+export const SubmitLoginForFlow = SubmitLoginBlock as unknown as MethodBlock<LoginPage, LoggedIn>;

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

@@ -1,13 +1,8 @@
-import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
-import type {
-  LoggedIn,
-  ItemInCart,
-  CartPage,
-  CheckoutInfoPage,
-  CheckoutOverviewPage,
-  OrderComplete,
-} from "../states/checkout.states.js";
-import { FfOwnerAuthBlock } from "../blocks/saucedemo-web/ff-owner-auth.block.js";
+import { Engine, 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";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
@@ -16,98 +11,67 @@ 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 { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
 
 const engine = new Engine({ headless: false, slowMo: 250 });
 
-// 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<
-      LoggedIn,
-      ItemInCart,
-      CartPage,
-      CheckoutInfoPage,
-      CheckoutInfoPage,
-      CheckoutInfoPage,
-      CheckoutInfoPage,
-      CheckoutOverviewPage,
-      OrderComplete
-    >([
-      start,
-      FfOwnerAuthBlock,
-      AddToCartBlock,
-      NavCartBlock,
-      NavCheckoutInfoBlock,
-      FillFirstNameBlock,
-      FillLastNameBlock,
-      FillPostalCodeBlock,
-      SubmitCheckoutInfoBlock,
-      FinishOrderBlock,
-      end,
-    ]),
-    "Owner: Full Checkout",
-  ),
-  {
-    "ff-owner-auth": {
-      stubAfter: {
-        inventory: {
-          label: "Signed in (fast-forward)",
-          detail: "Auth collapsed via FFCompose - interesting work starts here.",
-          tag: "AC",
-          duration: true,
-        },
-      },
-    },
-    // Kept for --ff-expand (inners become separate steps again: nav-login,
-    // fill-username, fill-password, submit-login).
-    "fill-username": {
-      stubBefore: {
-        username: {
+/**
+ * Owner checkout via map() + .ffStart/.ffEnd (no separate FfOwnerAuthBlock,
+ * no HighlightFixtureMap). Auth collapses to one blitz step; post-login
+ * blocks keep their own ctx stubBefore/stubAfter. Call-site decorate example
+ * on fill-username when --ff-expand shows inners again.
+ */
+export const checkoutFlow = withTitle(
+  engine
+    .map()
+    .start()
+    .ffStart("ff-owner-auth")
+    .gotoPage(NavLoginBlock)
+    .method(
+      FillUsernameBlock.stubBefore((ctx) => {
+        ctx.ring("username", {
+          selector: LoginSel.username,
           label: "Demo user",
-          detail: "standard_user from Mem - library block stays neutral.",
+          detail: "standard_user from Mem - library block stays neutral underneath",
           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 },
-      },
-    },
-    "add-to-cart": {
-      stubAfter: {
-        badge: {
-          label: "Cart now has the item",
-          detail: "Badge updates after Add to cart.",
-          tag: "AC",
-          duration: true,
-        },
-      },
-    },
-    "finish-order": {
-      stubAfter: {
-        thanks: {
-          label: "Order placed",
-          detail: "Completion header is the durable proof.",
+          focus: true,
+        });
+      }),
+    )
+    .method(
+      FillPasswordBlock.stubBefore((ctx) => {
+        ctx.ring("password", {
+          selector: LoginSel.password,
+          label: "Password",
+          detail: "Filled from Mem credentials.",
+          duration: 1500,
+          focus: true,
+        });
+      }),
+    )
+    .method(
+      SubmitLoginForFlow.stubBefore((ctx) => {
+        ctx.ring("submit", {
+          selector: LoginSel.loginButton,
+          label: "Sign in",
           tag: "GATE",
-          duration: 2500,
-          fastMode: 700,
-        },
-      },
-    },
-  },
+          duration: true,
+          fastMode: 500,
+          focus: true,
+          weight: "bold",
+        });
+      }),
+    )
+    .ffEnd()
+    .method(AddToCartBlock)
+    .gotoPage(NavCartBlock)
+    .gotoPage(NavCheckoutInfoBlock)
+    .method(FillFirstNameBlock)
+    .method(FillLastNameBlock)
+    .method(FillPostalCodeBlock)
+    .method(SubmitCheckoutInfoBlock)
+    .method(FinishOrderBlock)
+    .end(),
+  "Owner: Full Checkout",
 );

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

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle } from "waygraph";
+import { Engine, 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";
@@ -8,7 +8,16 @@ const engine = new Engine();
 
 // The step-mode overlay prepends "Episode N: " itself - the title here is
 // just the label, not the full heading.
+// map() + ctx stubs on the Method blocks (see fill-username / fill-password /
+// submit-login) - no HighlightFixtureMap.
 export const loginFlow = withTitle(
-  engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginForFlow, end]),
+  engine
+    .map()
+    .start()
+    .gotoPage(NavLoginBlock)
+    .method(FillUsernameBlock)
+    .method(FillPasswordBlock)
+    .method(SubmitLoginForFlow)
+    .end(),
   "Sign In",
 );

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

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle } from "waygraph";
+import { Engine, 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";
@@ -13,17 +13,17 @@ const engine = new Engine();
 // Episode-2 half of chainFlow(loginFlow, shopFlow) - assumes already LoggedIn
 // (AddToCartBlock's In is the Checkpoint<string> wildcard).
 export const shopFlow = withTitle(
-  engine.defineFlow([
-    start,
-    AddToCartBlock,
-    NavCartBlock,
-    NavCheckoutInfoBlock,
-    FillFirstNameBlock,
-    FillLastNameBlock,
-    FillPostalCodeBlock,
-    SubmitCheckoutInfoBlock,
-    FinishOrderBlock,
-    end,
-  ]),
+  engine
+    .map()
+    .start()
+    .method(AddToCartBlock)
+    .gotoPage(NavCartBlock)
+    .gotoPage(NavCheckoutInfoBlock)
+    .method(FillFirstNameBlock)
+    .method(FillLastNameBlock)
+    .method(FillPostalCodeBlock)
+    .method(SubmitCheckoutInfoBlock)
+    .method(FinishOrderBlock)
+    .end(),
   "Shop & Checkout",
 );

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

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
+import { Engine, withTitle, withSessionReset, withExpectedFailure } 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";
@@ -25,7 +25,14 @@ const engine = new Engine();
 export const viewerBlockedFlow = withExpectedFailure(
   withTitle(
     withSessionReset(
-      engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]),
+      engine
+        .map()
+        .start()
+        .gotoPage(NavLoginBlock)
+        .method(FillUsernameBlock)
+        .method(FillPasswordBlock)
+        .method(SubmitLoginBlock)
+        .end(),
     ),
     "Viewer: Blocked Login Attempt",
   ),

package/package.json

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

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

@@ -1,4 +1,4 @@
-import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, narrate, type StubCtx } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
 
@@ -8,6 +8,7 @@ import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
  * Route: saucedemo-web/checkout-step-two/methods/  (= /checkout-step-two.html)
  *
  * Places the order on the overview page - form/finish click, not a NavBlock.
+ * Stubs use open ctx lifecycles (preferred) - not static slot maps.
  */
 export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
@@ -19,23 +20,23 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     },
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
-    stubBefore: {
-      finish: {
+    stubBefore: (ctx: StubCtx) => {
+      ctx.ring("finish", {
         selector: CheckoutOverviewSel.finishBtn,
         label: "Finish",
         detail: "tone: warning (yellow) - place order",
         tone: "warning",
         weight: "bold",
-      },
+      });
     },
-    stubAfter: {
-      thanks: {
+    stubAfter: (ctx: StubCtx) => {
+      ctx.ring("thanks", {
         selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
         detail: "tone: success (green) - thank you!",
         tone: "success",
         duration: true,
-      },
+      });
     },
     // Shown AFTER act (order already placed) - selectors must match the
     // completion page, not #finish on the overview.

package/templates/quickstart/src/blocks/saucedemo-web/methods/fill-password.method.block.ts

@@ -22,16 +22,14 @@ export const FillPasswordBlock = defineMethodBlock<LoginPage, LoginPage>({
     },
     resolve: () => checkpoint("LoginPage"),
     stubBefore: (ctx: StubCtx) => {
-      ctx.highlights({
-        password: {
-          selector: LoginSel.password,
-          label: "Password",
-          detail: "tone: planned (purple)",
-          todo: "login-pass",
-          tone: "planned",
-          focus: true,
-          zoom: 1.4,
-        },
+      ctx.ring("password", {
+        selector: LoginSel.password,
+        label: "Password",
+        detail: "tone: planned (purple)",
+        todo: "login-pass",
+        tone: "planned",
+        focus: true,
+        zoom: 1.4,
       });
     },
     stubAfter: (ctx: StubCtx) => {

package/templates/quickstart/src/blocks/saucedemo-web/methods/fill-username.method.block.ts

@@ -40,16 +40,17 @@ export const FillUsernameBlock = defineMethodBlock<LoginPage, LoginPage>({
         { title: "Device showcase", index: 0 },
       );
       ctx.zoom(1.35);
-      ctx.highlights({
-        username: {
-          selector: LoginSel.username,
-          label: "Username",
-          detail: "tone: info (blue)",
-          todo: "login-user",
-          tone: "info",
-          focus: true,
-          zoom: 1.4,
-        },
+      const fromMem = ctx.mem?.get(LoginCreds.key)?.username;
+      ctx.ring("username", {
+        selector: LoginSel.username,
+        label: "Username",
+        detail: fromMem
+          ? `tone: info (blue) - mem ${fromMem}`
+          : "tone: info (blue)",
+        tone: "info",
+        todo: "login-user",
+        focus: true,
+        zoom: 1.4,
       });
     },
     stubAfter: (ctx: StubCtx) => {

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-login-for-flow.ts

@@ -1,4 +1,4 @@
-import type { DefinedBlock } from "waygraph";
+import type { MethodBlock } from "waygraph";
 import type { LoginPage, LoggedIn } from "../../../states/checkout.states.js";
 import { SubmitLoginBlock } from "./submit-login.method.block.js";
 
@@ -7,7 +7,8 @@ import { SubmitLoginBlock } from "./submit-login.method.block.js";
  * Helper: typed alias over SubmitLoginBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
- * DefinedBlock cast so linear Flows can chain .withVerify on Out=LoggedIn;
- * runtime still branches on bad credentials via SubmitLoginBlock.
+ * MethodBlock cast so map().method() keeps the factory brand while Flows can
+ * treat Out as LoggedIn; runtime still branches on bad credentials via
+ * SubmitLoginBlock.
  */
-export const SubmitLoginForFlow = SubmitLoginBlock as unknown as DefinedBlock<LoginPage, LoggedIn>;
+export const SubmitLoginForFlow = SubmitLoginBlock as unknown as MethodBlock<LoginPage, LoggedIn>;