waygraph 0.13.2 → 0.13.4

package/dist/cli.js

@@ -1355,7 +1355,7 @@ async function installOverlay(page, title) {
               cursor.innerHTML = MOUSE_SVG;
             }
           };
-          const ensureChip = (preset, touch, remain) => {
+          const ensureChip = (preset, touch, remain, orientation) => {
             let badge = document.getElementById("wg-device-badge");
             if (preset === "desktop" && !touch) {
               if (badge) {
@@ -1375,10 +1375,17 @@ async function installOverlay(page, title) {
             }
             badge.dataset.preset = preset;
             badge.dataset.touch = touch ? "1" : "0";
+            const orient =
+              orientation === "landscape" || orientation === "portrait"
+                ? orientation
+                : "";
+            if (orient) badge.dataset.orientation = orient;
             const chipLabel =
               preset === "desktop" && !touch
                 ? "desktop"
-                : preset + (remain ? " · remain" : "");
+                : preset +
+                  (orient ? " \u00b7 " + (orient === "landscape" ? "land" : "port") : "") +
+                  (remain ? " \u00b7 remain" : "");
             badge.innerHTML =
               '<span class="wg-dev-icon">' +
               (ICONS[preset] || ICONS.desktop) +
@@ -1388,7 +1395,7 @@ async function installOverlay(page, title) {
             void badge.offsetWidth;
             badge.classList.add("wg-in");
           };
-          const showToast = (preset, touch, title, sub) => {
+          const showToast = (preset, touch, title, sub, orientation) => {
             let toast = document.getElementById("wg-device-toast");
             if (toast && toast._wgTimer) {
               clearTimeout(toast._wgTimer);
@@ -1422,7 +1429,7 @@ async function installOverlay(page, title) {
                 const t = document.getElementById("wg-device-toast");
                 if (t) t.remove();
                 if (preset !== "desktop" || touch) {
-                  ensureChip(preset, touch, true);
+                  ensureChip(preset, touch, true, orientation);
                 }
               }, 380);
             }, 2200);
@@ -1443,6 +1450,7 @@ async function installOverlay(page, title) {
                 false,
                 "Back to desktop",
                 vp.width + "\u00d7" + vp.height + " \u00b7 mouse",
+                "landscape",
               );
               setTimeout(() => {
                 const badge = document.getElementById("wg-device-badge");
@@ -1455,6 +1463,7 @@ async function installOverlay(page, title) {
               if (toast) toast.remove();
             }
             window.__wgDevicePreset = "desktop";
+            window.__wgDeviceOrientation = "landscape";
             return;
           }
 
@@ -1462,27 +1471,46 @@ async function installOverlay(page, title) {
           const preset = device.preset || "desktop";
           const touch = !!device.touchMode;
           const remain = payload.remain !== false && sync !== "clear";
+          const vp = device.viewport || {};
+          const orient =
+            device.orientation === "landscape" || device.orientation === "portrait"
+              ? device.orientation
+              : vp.height > vp.width
+                ? "portrait"
+                : "landscape";
           const prev = window.__wgDevicePreset || "";
-          const changed = prev !== preset || (touch && prev === "desktop");
+          const prevOrient = window.__wgDeviceOrientation || "";
+          const presetChanged = prev !== preset || (touch && prev === "desktop");
+          const orientChanged = prevOrient !== "" && prevOrient !== orient;
+          const changed = presetChanged || orientChanged || prev === "";
           setCursor(touch);
           window.__wgDevicePreset = preset;
+          window.__wgDeviceOrientation = orient;
 
           const announce =
             payload.announce === true ||
             (payload.announce !== false && (sync === "set" || sync === "clear") && changed);
 
-          const vp = device.viewport || {};
           const size =
-            (vp.width || "?") + "\u00d7" + (vp.height || "?") + (touch ? " \u00b7 touch" : "");
-          const titles = {
+            (vp.width || "?") +
+            "\u00d7" +
+            (vp.height || "?") +
+            " \u00b7 " +
+            orient +
+            (touch ? " \u00b7 touch" : "");
+          let titleText = {
             mobile: "Now in mobile mode",
             tablet: "Now in tablet mode",
             desktop: "Now in desktop mode",
-          };
+          }[preset] || "Device updated";
+          if (orientChanged && !presetChanged) {
+            titleText =
+              orient === "landscape" ? "Rotated to landscape" : "Rotated to portrait";
+          }
           if (announce) {
-            showToast(preset, touch, titles[preset] || "Device updated", size);
+            showToast(preset, touch, titleText, size, orient);
           } else {
-            ensureChip(preset, touch, remain);
+            ensureChip(preset, touch, remain, orient);
           }
         };
       },
@@ -2914,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");
@@ -2945,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 &&
@@ -2952,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;
@@ -2960,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 {
@@ -2973,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/dist/highlights.d.ts

@@ -127,6 +127,8 @@ export type StubPhaseFixtures = {
     viewport?: DeviceViewport;
     /** Touch theater + Playwright touchscreen when true. */
     touch?: boolean;
+    /** Portrait / landscape (swaps preset width/height). */
+    orientation?: DeviceOrientation;
 };
 /** Named viewport presets (0.13+). */
 export type DevicePreset = "mobile" | "tablet" | "desktop";
@@ -149,14 +151,26 @@ export type DeviceState = {
     hasTouch: boolean;
     /** Demo gesture theater: finger cursor, tap/hold timing, prefer touchscreen. */
     touchMode: boolean;
+    /** Viewport orientation (0.13.3+). Default derived from width/height. */
+    orientation?: DeviceOrientation;
 };
-/** Built-in preset sizes (CSS pixels). */
+/** Portrait (tall) or landscape (wide). */
+export type DeviceOrientation = "portrait" | "landscape";
+/** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
 export declare const DEVICE_PRESETS: Record<DevicePreset, Omit<DeviceState, "touchMode"> & {
     touchMode?: boolean;
 }>;
 export declare function normalizeDevicePreset(raw: unknown): DevicePreset | undefined;
+export declare function normalizeDeviceOrientation(raw: unknown): DeviceOrientation | undefined;
+/** Infer orientation from box (square counts as landscape). */
+export declare function orientationFromViewport(vp: DeviceViewport): DeviceOrientation;
+/**
+ * Swap width/height so the viewport matches the requested orientation.
+ * Preserves deviceScaleFactor. No-op when already oriented.
+ */
+export declare function applyOrientation(state: DeviceState, orientation: DeviceOrientation): DeviceState;
 /** Resolve a preset name or partial state into a full DeviceState. */
-export declare function resolveDeviceState(input: DevicePreset | DeviceState | DeviceViewport | undefined, touchOverride?: boolean): DeviceState | undefined;
+export declare function resolveDeviceState(input: DevicePreset | DeviceState | DeviceViewport | undefined, touchOverride?: boolean, orientationOverride?: DeviceOrientation): DeviceState | undefined;
 /**
  * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
  * - clear: hideDevice / clearDevice / device("desktop") with clear intent
@@ -307,6 +321,15 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     viewport(box: DeviceViewport): void;
     /** Enable / disable touch theater + touchscreen gestures. */
     touch(on?: boolean): void;
+    /**
+     * Rotate viewport to portrait or landscape (0.13.3+).
+     * Keeps current preset; swaps width/height. Toast + lerp like device().
+     */
+    orientation(o: DeviceOrientation): void;
+    /** Alias for {@link StubCtx.orientation}("landscape"). */
+    landscape(): void;
+    /** Alias for {@link StubCtx.orientation}("portrait"). */
+    portrait(): void;
     /**
      * Reset to desktop viewport and clear touch mode. Omit device on a later
      * block = **keep**; only hideDevice / clearDevice / device("desktop") clears.

package/dist/highlights.js

@@ -12,7 +12,7 @@
  * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
-/** Built-in preset sizes (CSS pixels). */
+/** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
 export const DEVICE_PRESETS = {
     mobile: {
         preset: "mobile",
@@ -20,6 +20,7 @@ export const DEVICE_PRESETS = {
         isMobile: true,
         hasTouch: true,
         touchMode: true,
+        orientation: "portrait",
     },
     tablet: {
         preset: "tablet",
@@ -27,6 +28,7 @@ export const DEVICE_PRESETS = {
         isMobile: true,
         hasTouch: true,
         touchMode: true,
+        orientation: "portrait",
     },
     desktop: {
         preset: "desktop",
@@ -34,6 +36,7 @@ export const DEVICE_PRESETS = {
         isMobile: false,
         hasTouch: false,
         touchMode: false,
+        orientation: "landscape",
     },
 };
 export function normalizeDevicePreset(raw) {
@@ -48,67 +51,118 @@ export function normalizeDevicePreset(raw) {
         return "desktop";
     return undefined;
 }
+export function normalizeDeviceOrientation(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "portrait" || s === "port" || s === "tall" || s === "p")
+        return "portrait";
+    if (s === "landscape" || s === "land" || s === "wide" || s === "l")
+        return "landscape";
+    return undefined;
+}
+/** Infer orientation from box (square counts as landscape). */
+export function orientationFromViewport(vp) {
+    return vp.height > vp.width ? "portrait" : "landscape";
+}
+/**
+ * Swap width/height so the viewport matches the requested orientation.
+ * Preserves deviceScaleFactor. No-op when already oriented.
+ */
+export function applyOrientation(state, orientation) {
+    const vp = { ...state.viewport };
+    const current = orientationFromViewport(vp);
+    if (current !== orientation) {
+        const w = vp.width;
+        vp.width = vp.height;
+        vp.height = w;
+    }
+    return { ...state, viewport: vp, orientation };
+}
 /** Resolve a preset name or partial state into a full DeviceState. */
-export function resolveDeviceState(input, touchOverride) {
+export function resolveDeviceState(input, touchOverride, orientationOverride) {
     if (input === undefined)
         return undefined;
+    let resolved;
     if (typeof input === "string") {
         const p = normalizeDevicePreset(input);
         if (!p)
             return undefined;
         const base = DEVICE_PRESETS[p];
         const touchMode = touchOverride !== undefined ? !!touchOverride : !!base.touchMode;
-        return {
+        resolved = {
             preset: base.preset,
             viewport: { ...base.viewport },
             isMobile: base.isMobile,
             hasTouch: base.hasTouch || touchMode,
             touchMode,
+            orientation: base.orientation || orientationFromViewport(base.viewport),
         };
     }
-    if ("width" in input && "height" in input && !("preset" in input)) {
+    else if ("width" in input && "height" in input && !("preset" in input)) {
         const vp = input;
         const touchMode = touchOverride !== undefined ? !!touchOverride : true;
-        return {
+        const box = {
+            width: Math.max(200, Math.floor(vp.width)),
+            height: Math.max(200, Math.floor(vp.height)),
+            ...(vp.deviceScaleFactor !== undefined
+                ? { deviceScaleFactor: vp.deviceScaleFactor }
+                : { deviceScaleFactor: 2 }),
+        };
+        resolved = {
             preset: "mobile",
-            viewport: {
-                width: Math.max(200, Math.floor(vp.width)),
-                height: Math.max(200, Math.floor(vp.height)),
-                ...(vp.deviceScaleFactor !== undefined
-                    ? { deviceScaleFactor: vp.deviceScaleFactor }
-                    : { deviceScaleFactor: 2 }),
-            },
+            viewport: box,
             isMobile: true,
             hasTouch: true,
             touchMode,
+            orientation: orientationFromViewport(box),
         };
     }
-    const d = input;
-    const preset = normalizeDevicePreset(d.preset) || "desktop";
-    const base = DEVICE_PRESETS[preset];
-    const touchMode = touchOverride !== undefined
-        ? !!touchOverride
-        : d.touchMode !== undefined
-            ? !!d.touchMode
-            : !!base.touchMode;
-    const viewport = d.viewport
-        ? {
-            width: Math.max(200, Math.floor(d.viewport.width)),
-            height: Math.max(200, Math.floor(d.viewport.height)),
-            ...(d.viewport.deviceScaleFactor !== undefined
-                ? { deviceScaleFactor: d.viewport.deviceScaleFactor }
-                : base.viewport.deviceScaleFactor !== undefined
-                    ? { deviceScaleFactor: base.viewport.deviceScaleFactor }
-                    : {}),
-        }
-        : { ...base.viewport };
-    return {
-        preset,
-        viewport,
-        isMobile: d.isMobile !== undefined ? !!d.isMobile : base.isMobile,
-        hasTouch: d.hasTouch !== undefined ? !!d.hasTouch : base.hasTouch || touchMode,
-        touchMode,
-    };
+    else {
+        const d = input;
+        const preset = normalizeDevicePreset(d.preset) || "desktop";
+        const base = DEVICE_PRESETS[preset];
+        const touchMode = touchOverride !== undefined
+            ? !!touchOverride
+            : d.touchMode !== undefined
+                ? !!d.touchMode
+                : !!base.touchMode;
+        const viewport = d.viewport
+            ? {
+                width: Math.max(200, Math.floor(d.viewport.width)),
+                height: Math.max(200, Math.floor(d.viewport.height)),
+                ...(d.viewport.deviceScaleFactor !== undefined
+                    ? { deviceScaleFactor: d.viewport.deviceScaleFactor }
+                    : base.viewport.deviceScaleFactor !== undefined
+                        ? { deviceScaleFactor: base.viewport.deviceScaleFactor }
+                        : {}),
+            }
+            : { ...base.viewport };
+        resolved = {
+            preset,
+            viewport,
+            isMobile: d.isMobile !== undefined ? !!d.isMobile : base.isMobile,
+            hasTouch: d.hasTouch !== undefined ? !!d.hasTouch : base.hasTouch || touchMode,
+            touchMode,
+            orientation: normalizeDeviceOrientation(d.orientation) ||
+                orientationFromViewport(viewport),
+        };
+    }
+    if (!resolved)
+        return undefined;
+    const want = orientationOverride ||
+        (typeof input === "object" && input && "orientation" in input
+            ? normalizeDeviceOrientation(input.orientation)
+            : undefined);
+    if (want)
+        return applyOrientation(resolved, want);
+    if (!resolved.orientation) {
+        resolved = {
+            ...resolved,
+            orientation: orientationFromViewport(resolved.viewport),
+        };
+    }
+    return resolved;
 }
 /**
  * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
@@ -734,7 +788,7 @@ function createStubCtx(bag, opts) {
         device(preset) {
             bag.deviceTouched = true;
             bag.hideDevice = false;
-            const resolved = resolveDeviceState(preset, bag.touchOverride);
+            const resolved = resolveDeviceState(preset, bag.touchOverride, bag.orientationOverride);
             if (resolved) {
                 bag.device = resolved;
                 if (resolved.preset === "desktop" && !resolved.touchMode) {
@@ -745,7 +799,7 @@ function createStubCtx(bag, opts) {
         viewport(box) {
             bag.deviceTouched = true;
             bag.hideDevice = false;
-            const resolved = resolveDeviceState(box, bag.touchOverride);
+            const resolved = resolveDeviceState(box, bag.touchOverride, bag.orientationOverride);
             if (resolved)
                 bag.device = resolved;
         },
@@ -765,22 +819,43 @@ function createStubCtx(bag, opts) {
                     bag.hideDevice = false;
             }
             else if (enabled) {
-                const base = resolveDeviceState("desktop", true);
+                const base = resolveDeviceState("desktop", true, bag.orientationOverride);
                 if (base)
                     bag.device = { ...base, touchMode: true, hasTouch: true };
             }
         },
+        orientation(o) {
+            const want = normalizeDeviceOrientation(o);
+            if (!want)
+                return;
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            bag.orientationOverride = want;
+            const base = bag.device ||
+                resolveDeviceState("mobile", bag.touchOverride) ||
+                resolveDeviceState("mobile");
+            if (base)
+                bag.device = applyOrientation(base, want);
+        },
+        landscape() {
+            this.orientation("landscape");
+        },
+        portrait() {
+            this.orientation("portrait");
+        },
         hideDevice() {
             bag.deviceTouched = true;
             bag.hideDevice = true;
             bag.device = resolveDeviceState("desktop", false);
             bag.touchOverride = false;
+            bag.orientationOverride = undefined;
         },
         clearDevice() {
             bag.deviceTouched = true;
             bag.hideDevice = true;
             bag.device = resolveDeviceState("desktop", false);
             bag.touchOverride = false;
+            bag.orientationOverride = undefined;
         },
         zoom(n) {
             if (Number.isFinite(n) && n > 0)
@@ -834,10 +909,23 @@ function createStubCtx(bag, opts) {
                 bag.deviceTouched = true;
                 bag.touchOverride = !!partial.touch;
             }
+            if (partial.orientation !== undefined) {
+                const want = normalizeDeviceOrientation(partial.orientation);
+                if (want) {
+                    bag.deviceTouched = true;
+                    bag.hideDevice = false;
+                    bag.orientationOverride = want;
+                    const base = bag.device ||
+                        resolveDeviceState("mobile", bag.touchOverride) ||
+                        resolveDeviceState("mobile");
+                    if (base)
+                        bag.device = applyOrientation(base, want);
+                }
+            }
             if (partial.device !== undefined) {
                 bag.deviceTouched = true;
                 bag.hideDevice = false;
-                const resolved = resolveDeviceState(partial.device, bag.touchOverride);
+                const resolved = resolveDeviceState(partial.device, bag.touchOverride, bag.orientationOverride);
                 if (resolved) {
                     bag.device = resolved;
                     if (resolved.preset === "desktop" && !resolved.touchMode)
@@ -847,7 +935,7 @@ function createStubCtx(bag, opts) {
             if (partial.viewport !== undefined) {
                 bag.deviceTouched = true;
                 bag.hideDevice = false;
-                const resolved = resolveDeviceState(partial.viewport, bag.touchOverride);
+                const resolved = resolveDeviceState(partial.viewport, bag.touchOverride, bag.orientationOverride);
                 if (resolved)
                     bag.device = resolved;
             }

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export { connect, checkpoint } from "./types.js";
 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, 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, } from "./highlights.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 { 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/dist/index.js

@@ -2,7 +2,7 @@ export { connect, checkpoint } from "./types.js";
 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, 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 { 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 { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.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-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/scripts/demo-orientation-gestures-video.mjs

@@ -0,0 +1,262 @@
+/**
+ * Record a .webm of: portrait/landscape + click / tap / hold theater.
+ * Square capture so orientation changes are obvious in the video frame.
+ *
+ * From examples/saucedemo:
+ *   node scripts/demo-orientation-gestures-video.mjs
+ */
+import { chromium } from "playwright";
+import { mkdirSync, copyFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const outDir = join(__dirname, "../.tmp/device-demo");
+mkdirSync(outDir, { recursive: true });
+
+const CAPTURE = { width: 1080, height: 1080 };
+
+const PRESETS = {
+  mobilePortrait: { w: 390, h: 844, preset: "mobile", orient: "portrait", touch: true },
+  mobileLandscape: { w: 844, h: 390, preset: "mobile", orient: "landscape", touch: true },
+  tabletPortrait: { w: 768, h: 1024, preset: "tablet", orient: "portrait", touch: true },
+  tabletLandscape: { w: 1024, h: 768, preset: "tablet", orient: "landscape", touch: true },
+  desktop: { w: 1280, h: 720, preset: "desktop", orient: "landscape", touch: false },
+};
+
+const CSS = `
+html,body{margin:0;background:#0b1220;}
+#wg-stage{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;
+background:radial-gradient(ellipse at 50% 30%,#1a1030 0%,#0b1220 70%);}
+#wg-frame{position:relative;background:#fff;overflow:hidden;box-shadow:0 20px 60px rgba(0,0,0,.55);
+border:3px solid #2a1650;border-radius:18px;transition:width .5s cubic-bezier(.22,1,.36,1),
+height .5s cubic-bezier(.22,1,.36,1),border-radius .4s ease;}
+#wg-frame iframe{border:0;width:100%;height:100%;display:block;}
+#wg-device-toast{position:fixed;z-index:2147483647;top:18px;right:18px;
+display:flex;align-items:center;gap:10px;min-width:220px;max-width:340px;
+padding:12px 14px;border-radius:14px;background:rgba(20,10,40,.96);color:#f0e8ff;
+border:1px solid rgba(124,58,237,.55);box-shadow:0 10px 28px rgba(0,0,0,.45);
+font:600 13px/1.35 system-ui,sans-serif;pointer-events:none;
+opacity:0;transform:translateX(18px);transition:opacity .35s ease,transform .45s cubic-bezier(.22,1,.36,1);}
+#wg-device-toast.wg-in{opacity:1;transform:translateX(0);}
+#wg-device-toast[data-preset=mobile]{border-color:#3B82F6;}
+#wg-device-toast[data-preset=tablet]{border-color:#22C55E;}
+#wg-device-toast[data-preset=desktop]{border-color:#9CA3AF;}
+#wg-device-toast .wg-dev-icon{width:36px;height:36px;border-radius:10px;display:flex;
+align-items:center;justify-content:center;background:rgba(124,58,237,.28);}
+#wg-device-toast .wg-dev-title{font:800 13px/1.2 system-ui,sans-serif;color:#fff;}
+#wg-device-toast .wg-dev-sub{margin-top:3px;font:600 11px/1.3 system-ui,sans-serif;color:#c9a6ff;}
+#wg-gesture-banner{position:fixed;z-index:2147483646;left:18px;bottom:18px;
+padding:10px 14px;border-radius:12px;background:rgba(20,10,40,.94);color:#fff;
+font:700 13px/1.3 system-ui,sans-serif;border:1px solid rgba(124,58,237,.45);}
+#wg-cursor{position:fixed;z-index:2147483647;width:28px;height:28px;pointer-events:none;
+left:0;top:0;opacity:0;margin:0;transition:transform .55s cubic-bezier(.22,1,.36,1),opacity .2s;}
+#wg-click-pulse{position:fixed;z-index:2147483647;width:18px;height:18px;margin-left:-9px;
+margin-top:-9px;border-radius:50%;pointer-events:none;opacity:0;border:2px solid #7C3AED;
+background:rgba(124,58,237,.3);}
+#wg-click-pulse.wg-pulse{animation:wg-pulse .55s ease-out;}
+#wg-click-pulse[data-hold=1]{border-color:#EAB308;background:rgba(234,179,8,.35);
+width:28px;height:28px;margin-left:-14px;margin-top:-14px;}
+@keyframes wg-pulse{0%{opacity:.95;transform:scale(.35);}100%{opacity:0;transform:scale(2.6);}}
+`;
+
+const ICONS = {
+  mobile:
+    '<svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="#fff" stroke-width="1.8"><rect x="7" y="2.5" width="10" height="19" rx="2.2"/><circle cx="12" cy="18.2" r="1.1" fill="#fff" stroke="none"/></svg>',
+  tablet:
+    '<svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="#fff" stroke-width="1.8"><rect x="3.5" y="4" width="17" height="16" rx="2"/><circle cx="12" cy="17.2" r="1" fill="#fff" stroke="none"/></svg>',
+  desktop:
+    '<svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="#fff" stroke-width="1.8"><rect x="2.5" y="3.5" width="19" height="12.5" rx="1.5"/><path d="M8 20h8M12 16v4"/></svg>',
+};
+
+const MOUSE =
+  "<svg viewBox='0 0 32 32' width='24' height='24'><path fill='#0C0C1A' stroke='#fff' stroke-width='1.4' d='M6 3.5l1.4 22.5 5.8-5.4 4.2 9.4 3.6-1.6-4.2-9.2H26z'/></svg>";
+const FINGER =
+  "<svg viewBox='0 0 32 32' width='28' height='28'><ellipse cx='16' cy='22' rx='7' ry='8' fill='#0C0C1A' stroke='#fff' stroke-width='1.4'/><rect x='12' y='6' width='8' height='16' rx='4' fill='#0C0C1A' stroke='#fff' stroke-width='1.4'/></svg>";
+
+const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH || undefined;
+
+const browser = await chromium.launch({
+  headless: false,
+  ...(executablePath ? { executablePath } : {}),
+});
+const context = await browser.newContext({
+  hasTouch: true,
+  viewport: CAPTURE,
+  recordVideo: { dir: outDir, size: CAPTURE },
+  deviceScaleFactor: 1,
+});
+const page = await context.newPage();
+
+await page.setContent(`<!doctype html><html><head><style>${CSS}</style></head>
+<body>
+<div id="wg-stage"><div id="wg-frame" style="width:390px;height:844px">
+<iframe id="wg-app" src="https://www.saucedemo.com/"></iframe>
+</div></div>
+<div id="wg-gesture-banner">waygraph · orientation + gestures</div>
+<div id="wg-cursor">${FINGER}</div>
+<div id="wg-click-pulse"></div>
+</body></html>`);
+
+await page.waitForTimeout(2500);
+
+async function toast(title, sub, preset) {
+  await page.evaluate(
+    ({ title, sub, preset, icons }) => {
+      let t = document.getElementById("wg-device-toast");
+      if (!t) {
+        t = document.createElement("div");
+        t.id = "wg-device-toast";
+        document.body.appendChild(t);
+      }
+      t.dataset.preset = preset;
+      t.innerHTML =
+        '<span class="wg-dev-icon">' +
+        icons[preset] +
+        '</span><span><div class="wg-dev-title">' +
+        title +
+        '</div><div class="wg-dev-sub">' +
+        sub +
+        "</div></span>";
+      t.classList.remove("wg-in");
+      void t.offsetWidth;
+      t.classList.add("wg-in");
+    },
+    { title, sub, preset, icons: ICONS },
+  );
+}
+
+async function setFrame(key) {
+  const p = PRESETS[key];
+  const title =
+    key.includes("Landscape") || p.orient === "landscape"
+      ? p.preset === "desktop"
+        ? "Back to desktop"
+        : "Rotated to landscape"
+      : key.includes("Portrait") || p.orient === "portrait"
+        ? p.preset === "mobile" && key === "mobilePortrait"
+          ? "Now in mobile mode"
+          : "Rotated to portrait"
+        : "Device updated";
+  // First switch: mobile portrait uses "Now in mobile"
+  const t =
+    key === "mobilePortrait"
+      ? "Now in mobile mode"
+      : key === "desktop"
+        ? "Back to desktop"
+        : key.includes("Landscape")
+          ? "Rotated to landscape"
+          : key.includes("Portrait")
+            ? key.startsWith("tablet")
+              ? "Now in tablet mode"
+              : "Rotated to portrait"
+            : title;
+
+  await page.evaluate(
+    ({ w, h, touch, finger, mouse }) => {
+      const frame = document.getElementById("wg-frame");
+      frame.style.width = w + "px";
+      frame.style.height = h + "px";
+      frame.style.borderRadius = touch ? (w < h ? "28px" : "18px") : "10px";
+      const c = document.getElementById("wg-cursor");
+      c.innerHTML = touch ? finger : mouse;
+    },
+    { w: p.w, h: p.h, touch: p.touch, finger: FINGER, mouse: MOUSE },
+  );
+  await toast(t, `${p.w}×${p.h} · ${p.orient}${p.touch ? " · touch" : " · mouse"}`, p.preset);
+  await page.waitForTimeout(900);
+}
+
+async function banner(text) {
+  await page.evaluate((text) => {
+    const b = document.getElementById("wg-gesture-banner");
+    if (b) b.textContent = text;
+  }, text);
+}
+
+async function gestureAt(kind) {
+  // Aim at center of the device frame (login button-ish on saucedemo).
+  const box = await page.locator("#wg-frame").boundingBox();
+  if (!box) return;
+  const x = box.x + box.width * 0.5;
+  const y = box.y + box.height * 0.58;
+  await banner(
+    kind === "click"
+      ? "Gesture: CLICK (mouse)"
+      : kind === "tap"
+        ? "Gesture: TAP (touch)"
+        : "Gesture: HOLD (long-press)",
+  );
+  await page.evaluate(
+    ({ x, y, kind, ms }) => {
+      const c = document.getElementById("wg-cursor");
+      c.style.setProperty("--wg-cursor-ms", ms + "ms");
+      c.style.opacity = "1";
+      c.style.transform = `translate(${x - 8}px,${y - 8}px)`;
+    },
+    { x, y, kind, ms: 550 },
+  );
+  await page.waitForTimeout(600);
+  await page.evaluate(
+    ({ x, y, kind }) => {
+      const p = document.getElementById("wg-click-pulse");
+      p.style.left = x + "px";
+      p.style.top = y + "px";
+      p.dataset.hold = kind === "hold" ? "1" : "0";
+      p.classList.remove("wg-pulse");
+      void p.offsetWidth;
+      p.classList.add("wg-pulse");
+    },
+    { x, y, kind },
+  );
+  await page.waitForTimeout(kind === "hold" ? 900 : 550);
+}
+
+// Sequence: portrait -> landscape (shows in square video) + gestures
+await setFrame("mobilePortrait");
+await page.waitForTimeout(1200);
+await gestureAt("tap");
+await page.waitForTimeout(700);
+
+await setFrame("mobileLandscape");
+await page.waitForTimeout(1400);
+await gestureAt("hold");
+await page.waitForTimeout(700);
+
+await setFrame("tabletPortrait");
+await page.waitForTimeout(1200);
+await gestureAt("tap");
+await page.waitForTimeout(600);
+
+await setFrame("tabletLandscape");
+await page.waitForTimeout(1400);
+await gestureAt("click");
+await page.waitForTimeout(800);
+
+await setFrame("desktop");
+await page.waitForTimeout(1500);
+
+await banner("waygraph · orientation + gestures · done");
+await page.waitForTimeout(1000);
+
+const vid = page.video();
+await context.close();
+await browser.close();
+
+let saved = null;
+if (vid) {
+  const raw = await vid.path();
+  saved = join(outDir, "orientation-gestures.webm");
+  try {
+    copyFileSync(raw, saved);
+  } catch {
+    saved = raw;
+  }
+}
+console.log("ORIENTATION_GESTURES_VIDEO", saved || outDir);
+console.log(
+  "files",
+  readdirSync(outDir)
+    .filter((f) => f.endsWith(".webm"))
+    .join(", "),
+);

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.2",
+  "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",
+);