waygraph 0.13.3 → 0.13.4

package/dist/cli.js

@@ -2942,9 +2942,73 @@ async function clickPulseAt(page, x, y, tone) {
     .catch(() => {});
 }
 
+/**
+ * Fit + center the OS browser window on the device viewport so mobile/tablet
+ * is not stuck top-left inside a maximized frame (Dan 0.13.4).
+ * Desktop clear restores maximized.
+ */
+async function fitWindowToDeviceViewport(page, viewport, opts) {
+  const maximize = !!(opts && opts.maximize);
+  let client;
+  try {
+    client = await page.context().newCDPSession(page);
+    const { windowId } = await client.send("Browser.getWindowForTarget");
+    if (maximize) {
+      await client.send("Browser.setWindowBounds", {
+        windowId,
+        bounds: { windowState: "maximized" },
+      });
+      return;
+    }
+    if (!viewport || !viewport.width || !viewport.height) return;
+    const metrics = await page
+      .evaluate(() => {
+        const chromeW = Math.max(0, (window.outerWidth || 0) - (window.innerWidth || 0));
+        const chromeH = Math.max(0, (window.outerHeight || 0) - (window.innerHeight || 0));
+        return {
+          chromeW: Number.isFinite(chromeW) ? chromeW : 0,
+          // First paint after maximize often reports 0 chrome - use a floor.
+          chromeH: chromeH > 20 ? chromeH : 88,
+          screenW: window.screen.availWidth || 1920,
+          screenH: window.screen.availHeight || 1080,
+        };
+      })
+      .catch(() => ({ chromeW: 0, chromeH: 88, screenW: 1920, screenH: 1080 }));
+    // Leave maximized before setting pixel bounds (Chromium ignores size while max).
+    await client.send("Browser.setWindowBounds", {
+      windowId,
+      bounds: { windowState: "normal" },
+    });
+    const winW = Math.min(
+      metrics.screenW,
+      Math.max(320, Math.floor(viewport.width + metrics.chromeW)),
+    );
+    const winH = Math.min(
+      metrics.screenH,
+      Math.max(320, Math.floor(viewport.height + metrics.chromeH)),
+    );
+    const left = Math.max(0, Math.floor((metrics.screenW - winW) / 2));
+    const top = Math.max(0, Math.floor((metrics.screenH - winH) / 2));
+    await client.send("Browser.setWindowBounds", {
+      windowId,
+      bounds: {
+        windowState: "normal",
+        left,
+        top,
+        width: winW,
+        height: winH,
+      },
+    });
+  } catch {
+    /* headless / no window - ignore */
+  } finally {
+    if (client) await client.detach().catch(() => {});
+  }
+}
+
 /**
  * Apply authored device fixture to the live page (0.13+).
- * Seamless viewport lerp + toast on set/clear (quiet chip recreate on keep).
+ * Seamless viewport lerp + centered window + toast on set/clear.
  */
 async function applyDeviceToPage(page, device, sync) {
   const mode = sync || (device ? "set" : "keep");
@@ -2973,6 +3037,8 @@ async function applyDeviceToPage(page, device, sync) {
     from = null;
   }
   const announce = mode === "set" || mode === "clear";
+  const toDesktop =
+    mode === "clear" || (d.preset === "desktop" && !d.touchMode);
   const shouldAnimate =
     announce &&
     from &&
@@ -2980,6 +3046,14 @@ async function applyDeviceToPage(page, device, sync) {
     from.height > 0 &&
     (from.width !== target.width || from.height !== target.height);
 
+  // Unmaximize + center early so the lerp does not sit in the corner of a
+  // maximized frame. Desktop clear maximizes at the end instead.
+  if (!toDesktop) {
+    await fitWindowToDeviceViewport(page, from && from.width ? from : target, {
+      maximize: false,
+    });
+  }
+
   try {
     if (shouldAnimate) {
       const steps = 14;
@@ -2988,10 +3062,14 @@ async function applyDeviceToPage(page, device, sync) {
       for (let i = 1; i <= steps; i++) {
         const t = i / steps;
         const e = t * t * (3 - 2 * t); // smoothstep
-        await realSet({
+        const mid = {
           width: Math.round(from.width + (target.width - from.width) * e),
           height: Math.round(from.height + (target.height - from.height) * e),
-        });
+        };
+        await realSet(mid);
+        if (!toDesktop && (i === 1 || i === steps || i % 3 === 0)) {
+          await fitWindowToDeviceViewport(page, mid, { maximize: false });
+        }
         if (i < steps) await new Promise((r) => setTimeout(r, stepMs));
       }
     } else {
@@ -3001,6 +3079,12 @@ async function applyDeviceToPage(page, device, sync) {
     /* maximized / null viewport hosts may reject - toast still updates */
   }
 
+  if (toDesktop) {
+    await fitWindowToDeviceViewport(page, target, { maximize: true });
+  } else {
+    await fitWindowToDeviceViewport(page, target, { maximize: false });
+  }
+
   // Fire toast near the end of the lerp so it reads as one seamless beat.
   await page
     .evaluate(

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-next --video ./.tmp/device-showcase --title \"Device showcase\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
     "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,7 +17,9 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
   stubBefore: (ctx: StubCtx) => {
-    ctx.title("Open cart");
+    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" },
@@ -38,11 +40,14 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
         zoomOut: false,
         followMouse: false,
         weight: "bold",
+        gesture: "tap",
       },
     });
   },
   stubAfter: (ctx: StubCtx) => {
-    ctx.banner("Your cart");
+    ctx.banner("Your cart · desktop");
+    // Showcase finale: back to desktop.
+    ctx.clearDevice();
     ctx.zoomOut(false);
     ctx.ring("items", {
       selector: InventorySel.cartItem,

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

@@ -36,9 +36,10 @@ 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.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" },

package/examples/saucedemo/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" },

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.4",
   "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" },

package/templates/quickstart/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",
+);