waygraph 0.13.3 → 0.13.5

package/dist/highlights.d.ts

@@ -88,6 +88,22 @@ export type TodoDockState = {
     groups: WaygraphTodoGroup[];
     pos?: "left" | "right";
 };
+/** Options for compact {@link StubCtx.todos}(`id`, items, opts). */
+export type WaygraphTodosOpts = {
+    /** Dock heading. */
+    title?: string;
+    /** Current item index (0-based). */
+    index?: number;
+    /** `sequential` | `checklist` | `bullets`. */
+    style?: TodoListStyle;
+    /** Dock side. */
+    pos?: "left" | "right";
+    /**
+     * Keep other docks with different ids (multi-todo). Default false —
+     * one checklist at a time (setting todos replaces the previous dock).
+     */
+    parallel?: boolean;
+};
 /** Episode-level fixtures authored inside stubBefore/After/OnError(ctx). */
 export type StubPhaseFixtures = {
     todos?: readonly WaygraphTodoInput[];
@@ -242,16 +258,24 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      * for authored stub queues; set false to keep cursor hidden).
      */
     cursor?: boolean;
+    /**
+     * Optional link to a todo item id. When set, Method fill/click advances that
+     * todo row instead of relying on stub array index (avoids password/submit/username
+     * alphabetical reorder bugs).
+     */
+    todo?: string;
+    /** Slot key from stubBefore/After map (e.g. "username") - set by resolver. */
+    slotId?: string;
     /**
      * Pointer feel when touchMode is on (0.13+):
      * - `tap` - short press via touchscreen (default in touch mode)
      * - `hold` - long-press (~600ms) then release
      * - `click` - mouse click even in touch mode
      */
-    gesture?: "tap" | "hold" | "click";
+    gesture?: "tap" | "hold" | "click" | "swipe";
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "zoomOut" | "focus" | "followMouse" | "follow" | "color" | "cursor"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "zoomOut" | "focus" | "followMouse" | "follow" | "color" | "cursor" | "todo" | "gesture"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 /**
  * Open stub lifecycle context. Authors set rings + episode fixtures freely —
@@ -283,8 +307,14 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     highlights(slots: HighlightStubPhase): void;
     /** Set / overwrite one named ring. */
     ring(id: string, stub: WaygraphHighlightStub): void;
-    /** Episode checklist (demo panel). Single list; use {@link StubCtx.todoGroups} for FR/AC packs. */
+    /**
+     * Floating checklist. Prefer the compact form:
+     *   ctx.todos("login", ["Enter email", "Enter password"], { title: "Sign in", index: 0 })
+     * Legacy: ctx.todos([...]); ctx.todoId(...); ctx.todoIndex(...); …
+     * Default = one dock (setting todos replaces). Pass `{ parallel: true }` to keep others.
+     */
     todos(items: readonly WaygraphTodoInput[]): void;
+    todos(id: string, items: readonly WaygraphTodoInput[], opts?: WaygraphTodosOpts): void;
     /** Current checklist index (bump for sequential plans). */
     todoIndex(n: number): void;
     /** Heading above the single {@link StubCtx.todos} list. */
@@ -392,6 +422,8 @@ export type StubPhaseResult = {
     zoomOut?: boolean;
     title?: string;
     todoPos?: "left" | "right";
+    /** When true, keep other docks (multi-todo). Default false = replace. */
+    todoParallel?: boolean;
 };
 /**
  * One yap/slide in a multi-step demo caption sequence.

package/dist/highlights.js

@@ -475,12 +475,19 @@ function pickFxFields(base, patch) {
     const focus = patch?.focus !== undefined ? patch.focus : base?.focus;
     const color = patch?.color !== undefined ? patch.color : base?.color;
     const cursor = patch?.cursor !== undefined ? patch.cursor : base?.cursor;
+    const todo = patch?.todo !== undefined ? patch.todo : base?.todo;
+    const gesture = patch?.gesture !== undefined ? patch.gesture : base?.gesture;
     if (focus !== undefined)
         out.focus = !!focus;
     if (color !== undefined && String(color).trim())
         out.color = String(color).trim();
     if (cursor !== undefined)
         out.cursor = !!cursor;
+    if (todo !== undefined && String(todo).trim())
+        out.todo = String(todo).trim();
+    if (gesture === "tap" || gesture === "hold" || gesture === "click" || gesture === "swipe") {
+        out.gesture = gesture;
+    }
     return out;
 }
 function mergeSlot(base, patch) {
@@ -634,9 +641,7 @@ export function buildTodoDock(opts) {
     if (!items.length)
         return undefined;
     const group = { style, items };
-    if (opts.todoTitle && String(opts.todoTitle).trim()) {
-        group.title = String(opts.todoTitle).trim();
-    }
+    // Title once on the dock - not also on the lone group (avoids duplicate headings).
     const dock = { style, groups: [group] };
     if (opts.todoTitle && String(opts.todoTitle).trim()) {
         dock.title = String(opts.todoTitle).trim();
@@ -738,13 +743,38 @@ function createStubCtx(bag, opts) {
         ring(id, stub) {
             bag.highlights = { ...bag.highlights, [id]: stub };
         },
-        todos(items) {
+        todos(a, b, c) {
             bag.todoTouched = true;
             bag.hideTodos = false;
-            bag.todos = items;
             delete bag.todoGroups;
-            // Empty list = explicit clear (same as hideTodos).
-            if (!items || !items.length)
+            if (typeof a === "string") {
+                const id = String(a).trim();
+                if (id)
+                    bag.todoId = id;
+                else
+                    delete bag.todoId;
+                const items = (Array.isArray(b) ? b : []);
+                bag.todos = items;
+                const opts = (c && typeof c === "object" ? c : {});
+                if (opts.title != null)
+                    bag.todoTitle = String(opts.title);
+                if (opts.index != null)
+                    bag.todoIndex = Number(opts.index);
+                const st = normalizeTodoStyle(opts.style);
+                if (st)
+                    bag.todoStyle = st;
+                const pos = normalizeTodoPos(opts.pos);
+                if (pos)
+                    bag.todoPos = pos;
+                bag.todoParallel = opts.parallel === true;
+                if (!items.length)
+                    bag.hideTodos = true;
+                return;
+            }
+            bag.todos = a;
+            // Legacy list-only form: leave parallel unset (CLI treats as replace).
+            delete bag.todoParallel;
+            if (!a || !a.length)
                 bag.hideTodos = true;
         },
         todoIndex(n) {
@@ -977,19 +1007,26 @@ function applyDefaultZoomOut(slots, defaultZoomOut) {
     return slots.map((h) => h.zoomOut !== undefined ? h : { ...h, zoomOut: defaultZoomOut });
 }
 function mergePhaseMaps(phaseMap, fixturePhase) {
-    const slotIds = new Set([...Object.keys(phaseMap), ...Object.keys(fixturePhase || {})]);
-    const ordered = [...slotIds].sort((a, b) => {
-        const na = Number(a);
-        const nb = Number(b);
-        if (!Number.isNaN(na) && !Number.isNaN(nb))
-            return na - nb;
-        return a.localeCompare(b);
-    });
+    const phaseKeys = Object.keys(phaseMap);
+    const fixtureKeys = Object.keys(fixturePhase || {});
+    const allKeys = [...new Set([...phaseKeys, ...fixtureKeys])];
+    const allNumeric = allKeys.length > 0 && allKeys.every((k) => Number.isFinite(Number(k)) && String(Number(k)) === k);
+    // Numeric stub ids (legacy "0","1") sort by number. Named stubs keep author
+    // insertion order - localeCompare used to reorder password/submit/username
+    // and advance the wrong todo index on fill.
+    const ordered = allNumeric
+        ? [...allKeys].sort((a, b) => Number(a) - Number(b))
+        : [...phaseKeys, ...fixtureKeys.filter((k) => !phaseKeys.includes(k))];
     const resolved = [];
     for (const id of ordered) {
         const merged = mergeSlot(phaseMap[id], fixturePhase?.[id]);
-        if (merged)
-            resolved.push(merged);
+        if (merged) {
+            resolved.push({
+                ...merged,
+                slotId: id,
+                ...(merged.todo ? { todo: merged.todo } : {}),
+            });
+        }
     }
     return resolved;
 }
@@ -1138,6 +1175,7 @@ export async function runStubPhase(block, phase, opts) {
         ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
         ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
+        ...(bag.todoParallel === true ? { todoParallel: true } : {}),
     };
 }
 /**

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/examples/saucedemo/README.md

@@ -39,6 +39,8 @@ npx playwright install chromium
 | Coverage JSON + min gate (10%) | `npm run traverse:coverage` |
 | Shop demo stepper | `npm run demo:step` |
 | Shop demo autoplay | `npm run demo:autoplay` |
+| **Device showcase** (mobile/tablet + portrait/landscape) | `npm run demo:device` |
+| Device showcase + `.webm` | `npm run demo:device:video` |
 | **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
 | Cart bulk stepper | `npm run demo:bulk:step` |
 | List flows | `npm run flows` |

package/examples/saucedemo/package.json

@@ -25,6 +25,8 @@
     "prove:add-to-cart-menu": "node scripts/prove-add-to-cart-menu.mjs",
     "prove": "npm run prove:login-branch && npm run prove:graph && npm run prove:add-to-cart-menu && npm test",
     "record": "waygraph run --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --video --no-step",
+    "demo:device": "waygraph demo --blocks deviceShowcaseFlow --auto-next --title \"Device showcase\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
+    "demo:device:video": "waygraph demo --blocks deviceShowcaseFlow --auto-play-video --title \"Device showcase\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\" --video ./.tmp/device-showcase",
     "demo:bulk": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
     "demo:bulk:auto-next": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-next --title \"Cart bulk demo\"",
     "demo:bulk:video": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-play-video --title \"Cart bulk demo\"",

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

@@ -17,40 +17,48 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
   stubBefore: (ctx: StubCtx) => {
-    ctx.title("Open cart");
-    ctx.todoId("saucedemo-cart");
-    ctx.todos([
-      { id: "cart-find", text: "Find the product" },
-      { id: "cart-add", text: "Add to cart" },
-      { id: "cart-open", text: "Open cart" },
-    ]);
-    ctx.todoIndex(2);
+    ctx.title("Open cart · landscape");
+    ctx.landscape();
+    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", done: true },
+        { id: "cart-add", text: "Add to cart", done: true },
+        { id: "cart-open", text: "Open cart" },
+      ],
+      { title: "Device showcase", index: 5 },
+    );
     ctx.zoom(1.4);
     ctx.zoomOut(false);
     ctx.highlights({
       cart: {
         selector: ".shopping_cart_link",
         label: "Cart",
-        detail: "Zoom cart chrome",
+        detail: "Open cart",
         focus: true,
         color: "#c9a6ff",
-        zoom: 1.55,
         zoomOut: false,
         followMouse: false,
         weight: "bold",
+        gesture: "tap",
       },
     });
   },
   stubAfter: (ctx: StubCtx) => {
-    ctx.banner("Your cart");
-    ctx.zoomOut(false);
+    ctx.banner("Your cart · desktop");
+    ctx.clearDevice();
+    ctx.hideTodos();
+    ctx.zoomOut(true);
     ctx.ring("items", {
       selector: InventorySel.cartItem,
       label: "Cart items",
       detail: "Product landed in cart",
       focus: true,
       color: "#86efac",
-      zoom: 1.4,
+      zoomOut: true,
       followMouse: false,
       duration: true,
     });

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -36,16 +36,21 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     ],
     // Demo: zoom product -> add (stay zoomed), then badge after act.
     stubBefore: (ctx: StubCtx) => {
-      ctx.title("Pick a product");
-      // Back to desktop after mobile login (explicit clear - not omit/remain).
-      ctx.clearDevice();
-      ctx.todoId("saucedemo-cart");
-      ctx.todos([
-        { id: "cart-find", text: "Find the product" },
-        { id: "cart-add", text: "Add to cart" },
-        { id: "cart-open", text: "Open cart" },
-      ]);
-      ctx.todoIndex(0);
+      ctx.title("Pick a product · tablet");
+      ctx.device("tablet");
+      ctx.portrait();
+      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.zoom(1.35);
       ctx.zoomOut(false);
       ctx.highlights({
@@ -71,13 +76,18 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     },
     stubAfter: (ctx: StubCtx) => {
       ctx.banner("In the cart");
-      ctx.todoId("saucedemo-cart");
-      ctx.todos([
-        { id: "cart-find", text: "Find the product" },
-        { id: "cart-add", text: "Add to cart" },
-        { id: "cart-open", text: "Open cart" },
-      ]);
-      ctx.todoIndex(1);
+      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", done: true },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 4 },
+      );
       ctx.zoomOut(false);
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
@@ -85,7 +95,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         detail: "Item count updated",
         focus: true,
         color: "#86efac",
-        zoom: 1.6,
         zoomOut: false,
         duration: true,
       });

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

@@ -50,21 +50,27 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     // Open lifecycle: banner title, todos, Screen Studio camera zoom,
     // sequential highlight queue (appear / dwell / fade), focus + color.
     stubBefore: (ctx: StubCtx) => {
-      ctx.title("Signing in");
-      // 0.13+: mobile viewport + touch theater; omit on later blocks = remain.
+      ctx.title("Signing in · mobile");
       ctx.device("mobile");
-      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.portrait();
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username" },
+          { id: "login-pass", text: "Enter password" },
+          { id: "login-submit", text: "Tap Login" },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 0 },
+      );
       ctx.zoom(1.35);
       ctx.highlights({
         username: {
           selector: "#user-name",
           label: "Username",
+          todo: "login-user",
           focus: true,
           color: "#c9a6ff",
           zoom: 1.4,
@@ -72,6 +78,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         password: {
           selector: "#password",
           label: "Password",
+          todo: "login-pass",
           focus: true,
           color: "#c9a6ff",
           zoom: 1.4,
@@ -79,6 +86,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         submit: {
           selector: "#login-button",
           label: "Login",
+          todo: "login-submit",
           focus: true,
           color: "#86efac",
           zoom: 1.55,
@@ -88,17 +96,17 @@ 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"]',
           label: "Login error banner",
@@ -109,15 +117,20 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         });
         return;
       }
-      ctx.banner("Inventory");
-      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.banner("Inventory · landscape");
+      ctx.landscape();
+      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",

package/examples/saucedemo/src/flows/device-showcase.flow.ts

@@ -0,0 +1,28 @@
+import { Engine, start, end, withTitle } from "waygraph";
+import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.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";
+
+const engine = new Engine();
+
+/**
+ * Short device/orientation showcase (0.13.3+):
+ *   login mobile portrait -> land on inventory landscape ->
+ *   add-to-cart tablet portrait -> open cart tablet landscape -> desktop
+ *
+ * Run:
+ *   npm run demo:device
+ *   npm run demo:device:video
+ */
+export const deviceShowcaseFlow = withTitle(
+  engine.defineFlow([
+    start,
+    NavLoginBlock,
+    SubmitLoginForFlow,
+    AddToCartBlock,
+    NavCartBlock,
+    end,
+  ]),
+  "Device showcase",
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "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/cart/nav-cart.block.ts

@@ -1,4 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
+import type { StubCtx } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
 import { InventorySel } from "../inventory/methods/inventory-items.js";
 
@@ -15,8 +16,10 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
-  stubBefore: (ctx) => {
-    ctx.title("Open cart");
+  stubBefore: (ctx: StubCtx) => {
+    ctx.title("Open cart · landscape");
+    // Device showcase: rotate tablet to landscape before the cart tap.
+    ctx.landscape();
     ctx.todoId("saucedemo-cart");
     ctx.todos([
       { id: "cart-find", text: "Find the product" },
@@ -37,11 +40,14 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
         zoomOut: false,
         followMouse: false,
         weight: "bold",
+        gesture: "tap",
       },
     });
   },
-  stubAfter: (ctx) => {
-    ctx.banner("Your cart");
+  stubAfter: (ctx: StubCtx) => {
+    ctx.banner("Your cart · desktop");
+    // Showcase finale: back to desktop.
+    ctx.clearDevice();
     ctx.zoomOut(false);
     ctx.ring("items", {
       selector: InventorySel.cartItem,

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -1,4 +1,5 @@
 import { defineEffectBlock, checkpoint, type Checkpoint, type WaygraphInstanceOption } from "waygraph";
+import type { StubCtx } from "waygraph";
 import type { ItemInCart } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectAddableItems, InventorySel } from "./inventory-items.js";
@@ -34,10 +35,11 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       },
     ],
     // Demo: zoom product -> add (stay zoomed), then badge after act.
-    stubBefore: (ctx) => {
-      ctx.title("Pick a product");
-      // Back to desktop after mobile login (explicit clear - not omit/remain).
-      ctx.clearDevice();
+    stubBefore: (ctx: StubCtx) => {
+      ctx.title("Pick a product · tablet");
+      // Device showcase: tablet portrait (toast + lerp from mobile landscape).
+      ctx.device("tablet");
+      ctx.portrait();
       ctx.todoId("saucedemo-cart");
       ctx.todos([
         { id: "cart-find", text: "Find the product" },
@@ -68,7 +70,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       });
     },
-    stubAfter: (ctx) => {
+    stubAfter: (ctx: StubCtx) => {
       ctx.banner("In the cart");
       ctx.todoId("saucedemo-cart");
       ctx.todos([

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

@@ -50,9 +50,10 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     // Open lifecycle: banner title, todos, Screen Studio camera zoom,
     // sequential highlight queue (appear / dwell / fade), focus + color.
     stubBefore: (ctx: StubCtx) => {
-      ctx.title("Signing in");
-      // 0.13+: mobile viewport + touch theater; omit on later blocks = remain.
+      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" },
@@ -109,7 +110,9 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         });
         return;
       }
-      ctx.banner("Inventory");
+      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" },