waygraph 0.13.1 → 0.13.3

package/dist/cli.js

@@ -532,17 +532,43 @@ const RING_CSS =
   "#wg-todo-dock[data-pos=right]{transform:translateX(calc(100vw - 100% - 28px));}" +
   "#wg-todo-dock[data-pos=left]{transform:translateX(0);}" +
   "#wg-todo-dock #wg-todos{list-style:none;margin:0;padding:0;background:transparent;border:none;}" +
-  // Device / touch badge (0.13+) - shows preset + remain|desktop reset.
+  // Device toast + chip (0.13.2+) - icon toast on fixture change, then compact chip.
+  "#wg-device-toast{position:fixed;z-index:2147483647;top:14px;right:14px;" +
+  "display:flex;align-items:center;gap:10px;min-width:200px;max-width:min(92vw,320px);" +
+  "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,.4);" +
+  "font:600 13px/1.35 system-ui,sans-serif;pointer-events:none;" +
+  "opacity:0;transform:translateX(18px) scale(.96);" +
+  "transition:opacity .35s ease,transform .45s cubic-bezier(.22,1,.36,1);}" +
+  "#wg-device-toast.wg-in{opacity:1;transform:translateX(0) scale(1);}" +
+  "#wg-device-toast.wg-out{opacity:0;transform:translateX(12px) scale(.98);}" +
+  "#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{flex:0 0 auto;width:36px;height:36px;border-radius:10px;" +
+  "display:flex;align-items:center;justify-content:center;background:rgba(124,58,237,.28);}" +
+  "#wg-device-toast[data-preset=mobile] .wg-dev-icon{background:rgba(59,130,246,.28);}" +
+  "#wg-device-toast[data-preset=tablet] .wg-dev-icon{background:rgba(34,197,94,.28);}" +
+  "#wg-device-toast[data-preset=desktop] .wg-dev-icon{background:rgba(156,163,175,.28);}" +
+  "#wg-device-toast .wg-dev-icon svg{width:22px;height:22px;display:block;}" +
+  "#wg-device-toast .wg-dev-copy{flex:1 1 auto;min-width:0;}" +
+  "#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;letter-spacing:.02em;}" +
   "#wg-device-badge{position:fixed;z-index:2147483646;top:14px;right:14px;" +
-  "padding:6px 10px;border-radius:999px;background:rgba(20,10,40,.92);color:#f0e8ff;" +
+  "display:inline-flex;align-items:center;gap:6px;padding:6px 10px 6px 8px;" +
+  "border-radius:999px;background:rgba(20,10,40,.92);color:#f0e8ff;" +
   "border:1px solid rgba(124,58,237,.5);font:700 11px/1.2 system-ui,sans-serif;" +
   "letter-spacing:.04em;text-transform:uppercase;pointer-events:none;" +
-  "box-shadow:0 4px 14px rgba(0,0,0,.3);opacity:0;transition:opacity .25s ease;}" +
-  "#wg-device-badge.wg-in{opacity:1;}" +
+  "box-shadow:0 4px 14px rgba(0,0,0,.3);opacity:0;transform:translateY(-4px);" +
+  "transition:opacity .3s ease,transform .35s cubic-bezier(.22,1,.36,1);}" +
+  "#wg-device-badge.wg-in{opacity:1;transform:translateY(0);}" +
   "#wg-device-badge[data-preset=mobile]{border-color:#3B82F6;}" +
   "#wg-device-badge[data-preset=tablet]{border-color:#22C55E;}" +
   "#wg-device-badge[data-preset=desktop]{border-color:#9CA3AF;}" +
-  "#wg-device-badge[data-touch=1]::after{content:' · touch';opacity:.85;}" +
+  "#wg-device-badge .wg-dev-icon{width:16px;height:16px;display:flex;align-items:center;justify-content:center;}" +
+  "#wg-device-badge .wg-dev-icon svg{width:14px;height:14px;display:block;}" +
+  "#wg-device-badge .wg-dev-label{white-space:nowrap;}" +
   "#wg-cursor[data-touch=1]{width:28px;height:28px;}" +
   "#wg-todos{list-style:none;margin:0 0 12px;padding:8px 10px;background:#0f0620;border-radius:8px;" +
   "border:1px solid #3a2a60;}" +
@@ -1287,15 +1313,14 @@ async function installOverlay(page, title) {
             window.__wgStampModal(dock, "todos", { ready: true });
           }
         };
-        // Device / touch badge (0.13+) - mirror todo sync keep/set/clear.
-        // Payload: { sync, device?, remain? }
+        // Device toast + chip (0.13.2+) - announce on set/clear; quiet chip on keep.
+        // Payload: { sync, device?, remain?, announce? }
         window.__wgSyncDevice = (payload) => {
           const sync =
             payload && (payload.sync === "clear" || payload.sync === "keep" || payload.sync === "set")
               ? payload.sync
               : "keep";
           const device = payload && payload.device ? payload.device : null;
-          let badge = document.getElementById("wg-device-badge");
           const cursor = document.getElementById("wg-cursor");
           const MOUSE_SVG =
             "<svg viewBox='0 0 32 32' width='24' height='24'>" +
@@ -1306,43 +1331,186 @@ async function installOverlay(page, title) {
             "<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>";
-          if (sync === "keep" && !device) return;
-          if (sync === "clear" || (device && device.preset === "desktop" && !device.touchMode)) {
-            if (badge) badge.remove();
-            if (cursor) {
+          const ICONS = {
+            mobile:
+              '<svg viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">' +
+              '<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" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">' +
+              '<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" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">' +
+              '<rect x="2.5" y="3.5" width="19" height="12.5" rx="1.5"/>' +
+              '<path d="M8 20h8M12 16v4"/></svg>',
+          };
+          const setCursor = (touch) => {
+            if (!cursor) return;
+            if (touch) {
+              cursor.setAttribute("data-touch", "1");
+              cursor.innerHTML = FINGER_SVG;
+            } else {
               cursor.removeAttribute("data-touch");
               cursor.innerHTML = MOUSE_SVG;
             }
-            if (sync === "clear" && !device) return;
-            // clear with desktop device: still hide badge (back to main)
-            if (device && device.preset === "desktop" && !device.touchMode) return;
+          };
+          const ensureChip = (preset, touch, remain, orientation) => {
+            let badge = document.getElementById("wg-device-badge");
+            if (preset === "desktop" && !touch) {
+              if (badge) {
+                badge.classList.remove("wg-in");
+                setTimeout(() => {
+                  const b = document.getElementById("wg-device-badge");
+                  if (b) b.remove();
+                }, 320);
+              }
+              return;
+            }
+            if (!badge) {
+              badge = document.createElement("div");
+              badge.id = "wg-device-badge";
+              badge.setAttribute("data-wg-ui", "1");
+              document.documentElement.appendChild(badge);
+            }
+            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 +
+                  (orient ? " \u00b7 " + (orient === "landscape" ? "land" : "port") : "") +
+                  (remain ? " \u00b7 remain" : "");
+            badge.innerHTML =
+              '<span class="wg-dev-icon">' +
+              (ICONS[preset] || ICONS.desktop) +
+              '</span><span class="wg-dev-label">' +
+              chipLabel +
+              "</span>";
+            void badge.offsetWidth;
+            badge.classList.add("wg-in");
+          };
+          const showToast = (preset, touch, title, sub, orientation) => {
+            let toast = document.getElementById("wg-device-toast");
+            if (toast && toast._wgTimer) {
+              clearTimeout(toast._wgTimer);
+              toast._wgTimer = null;
+            }
+            if (!toast) {
+              toast = document.createElement("div");
+              toast.id = "wg-device-toast";
+              toast.setAttribute("data-wg-ui", "1");
+              document.documentElement.appendChild(toast);
+            }
+            // Hide chip while toast is up (same corner).
+            const badge = document.getElementById("wg-device-badge");
+            if (badge) badge.classList.remove("wg-in");
+            toast.dataset.preset = preset;
+            toast.innerHTML =
+              '<span class="wg-dev-icon">' +
+              (ICONS[preset] || ICONS.desktop) +
+              '</span><span class="wg-dev-copy"><div class="wg-dev-title">' +
+              title +
+              '</div><div class="wg-dev-sub">' +
+              sub +
+              "</div></span>";
+            toast.classList.remove("wg-out");
+            void toast.offsetWidth;
+            toast.classList.add("wg-in");
+            toast._wgTimer = setTimeout(() => {
+              toast.classList.add("wg-out");
+              toast.classList.remove("wg-in");
+              setTimeout(() => {
+                const t = document.getElementById("wg-device-toast");
+                if (t) t.remove();
+                if (preset !== "desktop" || touch) {
+                  ensureChip(preset, touch, true, orientation);
+                }
+              }, 380);
+            }, 2200);
+          };
+
+          if (sync === "keep" && !device) return;
+
+          const isDesktopClear =
+            sync === "clear" ||
+            (device && device.preset === "desktop" && !device.touchMode);
+          if (isDesktopClear) {
+            setCursor(false);
+            const announce = payload.announce !== false && sync !== "keep";
+            if (announce) {
+              const vp = device && device.viewport ? device.viewport : { width: 1280, height: 720 };
+              showToast(
+                "desktop",
+                false,
+                "Back to desktop",
+                vp.width + "\u00d7" + vp.height + " \u00b7 mouse",
+                "landscape",
+              );
+              setTimeout(() => {
+                const badge = document.getElementById("wg-device-badge");
+                if (badge) badge.remove();
+              }, 2600);
+            } else {
+              const badge = document.getElementById("wg-device-badge");
+              if (badge) badge.remove();
+              const toast = document.getElementById("wg-device-toast");
+              if (toast) toast.remove();
+            }
+            window.__wgDevicePreset = "desktop";
+            window.__wgDeviceOrientation = "landscape";
+            return;
           }
+
           if (!device) return;
           const preset = device.preset || "desktop";
           const touch = !!device.touchMode;
           const remain = payload.remain !== false && sync !== "clear";
-          if (!badge) {
-            badge = document.createElement("div");
-            badge.id = "wg-device-badge";
-            badge.setAttribute("data-wg-ui", "1");
-            document.documentElement.appendChild(badge);
+          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 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 size =
+            (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";
           }
-          badge.dataset.preset = preset;
-          badge.dataset.touch = touch ? "1" : "0";
-          const label =
-            preset === "desktop" && !touch
-              ? "desktop"
-              : preset + (remain ? " · remain" : " · set");
-          badge.textContent = label;
-          badge.classList.add("wg-in");
-          if (cursor) {
-            if (touch) {
-              cursor.setAttribute("data-touch", "1");
-              cursor.innerHTML = FINGER_SVG;
-            } else {
-              cursor.removeAttribute("data-touch");
-              cursor.innerHTML = MOUSE_SVG;
-            }
+          if (announce) {
+            showToast(preset, touch, titleText, size, orient);
+          } else {
+            ensureChip(preset, touch, remain, orient);
           }
         };
       },
@@ -2776,8 +2944,7 @@ async function clickPulseAt(page, x, y, tone) {
 
 /**
  * Apply authored device fixture to the live page (0.13+).
- * Uses the real setViewportSize (step mode noops block-authored calls).
- * sync keep with no device = no-op; clear / desktop = restore main feel.
+ * Seamless viewport lerp + toast on set/clear (quiet chip recreate on keep).
  */
 async function applyDeviceToPage(page, device, sync) {
   const mode = sync || (device ? "set" : "keep");
@@ -2795,14 +2962,46 @@ async function applyDeviceToPage(page, device, sync) {
     typeof page.__wgRealSetViewportSize === "function"
       ? page.__wgRealSetViewportSize
       : page.setViewportSize.bind(page);
+  const target = {
+    width: Math.max(200, Math.floor(d.viewport.width)),
+    height: Math.max(200, Math.floor(d.viewport.height)),
+  };
+  let from = null;
   try {
-    await realSet({
-      width: d.viewport.width,
-      height: d.viewport.height,
-    });
+    from = page.viewportSize();
   } catch {
-    /* maximized / null viewport hosts may reject - badge still updates */
+    from = null;
   }
+  const announce = mode === "set" || mode === "clear";
+  const shouldAnimate =
+    announce &&
+    from &&
+    from.width > 0 &&
+    from.height > 0 &&
+    (from.width !== target.width || from.height !== target.height);
+
+  try {
+    if (shouldAnimate) {
+      const steps = 14;
+      const ms = Number(process.env.WAYGRAPH_DEVICE_TRANSITION_MS || 520);
+      const stepMs = Math.max(12, Math.floor(ms / steps));
+      for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const e = t * t * (3 - 2 * t); // smoothstep
+        await realSet({
+          width: Math.round(from.width + (target.width - from.width) * e),
+          height: Math.round(from.height + (target.height - from.height) * e),
+        });
+        if (i < steps) await new Promise((r) => setTimeout(r, stepMs));
+      }
+    } else {
+      await realSet(target);
+    }
+  } catch {
+    /* maximized / null viewport hosts may reject - toast still updates */
+  }
+
+  // Fire toast near the end of the lerp so it reads as one seamless beat.
   await page
     .evaluate(
       (payload) => {
@@ -2812,6 +3011,7 @@ async function applyDeviceToPage(page, device, sync) {
         sync: mode,
         device: d,
         remain: mode === "keep" || mode === "set",
+        announce,
       },
     )
     .catch(() => {});

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/scripts/demo-device-presets.mjs

@@ -0,0 +1,188 @@
+/**
+ * Headed visual demo: mobile -> tablet -> desktop with toast + seamless lerp.
+ * Usage (from examples/saucedemo): WG_DEVICE_HOLD_MS=5000 node scripts/demo-device-presets.mjs
+ */
+import { chromium } from "playwright";
+import { mkdirSync } 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 PRESETS = {
+  mobile: {
+    preset: "mobile",
+    viewport: { width: 390, height: 844 },
+    touchMode: true,
+    title: "Now in mobile mode",
+  },
+  tablet: {
+    preset: "tablet",
+    viewport: { width: 768, height: 1024 },
+    touchMode: true,
+    title: "Now in tablet mode",
+  },
+  desktop: {
+    preset: "desktop",
+    viewport: { width: 1280, height: 720 },
+    touchMode: false,
+    title: "Back to desktop",
+  },
+};
+
+const CSS = `
+#wg-device-toast{position:fixed;z-index:2147483647;top:14px;right:14px;
+display:flex;align-items:center;gap:10px;min-width:200px;max-width:min(92vw,320px);
+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,.4);
+font:600 13px/1.35 system-ui,sans-serif;pointer-events:none;
+opacity:0;transform:translateX(18px) scale(.96);
+transition:opacity .35s ease,transform .45s cubic-bezier(.22,1,.36,1);}
+#wg-device-toast.wg-in{opacity:1;transform:translateX(0) scale(1);}
+#wg-device-toast.wg-out{opacity:0;transform:translateX(12px) scale(.98);}
+#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{flex:0 0 auto;width:36px;height:36px;border-radius:10px;
+display:flex;align-items:center;justify-content:center;background:rgba(124,58,237,.28);}
+#wg-device-toast[data-preset=mobile] .wg-dev-icon{background:rgba(59,130,246,.28);}
+#wg-device-toast[data-preset=tablet] .wg-dev-icon{background:rgba(34,197,94,.28);}
+#wg-device-toast[data-preset=desktop] .wg-dev-icon{background:rgba(156,163,175,.28);}
+#wg-device-toast .wg-dev-icon svg{width:22px;height:22px;display:block;}
+#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-device-badge{position:fixed;z-index:2147483646;top:14px;right:14px;
+display:inline-flex;align-items:center;gap:6px;padding:6px 10px 6px 8px;
+border-radius:999px;background:rgba(20,10,40,.92);color:#f0e8ff;
+border:1px solid rgba(124,58,237,.5);font:700 11px/1.2 system-ui,sans-serif;
+letter-spacing:.04em;text-transform:uppercase;pointer-events:none;
+box-shadow:0 4px 14px rgba(0,0,0,.3);opacity:0;transition:opacity .3s ease;}
+#wg-device-badge.wg-in{opacity:1;}
+#wg-device-badge[data-preset=mobile]{border-color:#3B82F6;}
+#wg-device-badge[data-preset=tablet]{border-color:#22C55E;}
+#wg-device-badge .wg-dev-icon svg{width:14px;height:14px;display:block;}
+`;
+
+const ICONS = {
+  mobile:
+    '<svg viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><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" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><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" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="3.5" width="19" height="12.5" rx="1.5"/><path d="M8 20h8M12 16v4"/></svg>',
+};
+
+async function lerpViewport(page, to, ms = 520) {
+  const from = page.viewportSize() || { width: 1280, height: 720 };
+  const steps = 14;
+  const stepMs = Math.max(12, Math.floor(ms / steps));
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps;
+    const e = t * t * (3 - 2 * t);
+    await page.setViewportSize({
+      width: Math.round(from.width + (to.width - from.width) * e),
+      height: Math.round(from.height + (to.height - from.height) * e),
+    });
+    if (i < steps) await page.waitForTimeout(stepMs);
+  }
+}
+
+async function applyPreset(page, key) {
+  const d = PRESETS[key];
+  await lerpViewport(page, d.viewport, 520);
+  await page.evaluate(
+    ({ d, css, icons, key }) => {
+      let style = document.getElementById("wg-device-demo-style");
+      if (!style) {
+        style = document.createElement("style");
+        style.id = "wg-device-demo-style";
+        style.textContent = css;
+        document.documentElement.appendChild(style);
+      }
+      let toast = document.getElementById("wg-device-toast");
+      if (toast && toast._wgTimer) clearTimeout(toast._wgTimer);
+      if (!toast) {
+        toast = document.createElement("div");
+        toast.id = "wg-device-toast";
+        document.documentElement.appendChild(toast);
+      }
+      const badge = document.getElementById("wg-device-badge");
+      if (badge) badge.classList.remove("wg-in");
+      toast.dataset.preset = d.preset;
+      const sub =
+        d.viewport.width +
+        "\u00d7" +
+        d.viewport.height +
+        (d.touchMode ? " \u00b7 touch" : " \u00b7 mouse");
+      toast.innerHTML =
+        '<span class="wg-dev-icon">' +
+        icons[d.preset] +
+        '</span><span class="wg-dev-copy"><div class="wg-dev-title">' +
+        d.title +
+        '</div><div class="wg-dev-sub">' +
+        sub +
+        "</div></span>";
+      toast.classList.remove("wg-out");
+      void toast.offsetWidth;
+      toast.classList.add("wg-in");
+      toast._wgTimer = setTimeout(() => {
+        toast.classList.add("wg-out");
+        toast.classList.remove("wg-in");
+        setTimeout(() => {
+          if (d.preset === "desktop" && !d.touchMode) {
+            const b = document.getElementById("wg-device-badge");
+            if (b) b.remove();
+            return;
+          }
+          let chip = document.getElementById("wg-device-badge");
+          if (!chip) {
+            chip = document.createElement("div");
+            chip.id = "wg-device-badge";
+            document.documentElement.appendChild(chip);
+          }
+          chip.dataset.preset = d.preset;
+          chip.innerHTML =
+            '<span class="wg-dev-icon">' +
+            icons[d.preset] +
+            '</span><span>' +
+            d.preset +
+            " \u00b7 remain</span>";
+          chip.classList.add("wg-in");
+        }, 380);
+      }, 2200);
+    },
+    { d, css: CSS, icons: ICONS, key },
+  );
+}
+
+const holdMs = Number(process.env.WG_DEVICE_HOLD_MS || 4500);
+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: { width: 1280, height: 720 },
+});
+const page = await context.newPage();
+await page.goto("https://www.saucedemo.com/", { waitUntil: "domcontentloaded" });
+
+const shots = [];
+for (const key of ["mobile", "tablet", "desktop"]) {
+  console.log("device demo:", key);
+  await applyPreset(page, key);
+  await page.waitForTimeout(900);
+  const shot = join(outDir, `device-${key}.png`);
+  await page.screenshot({ path: shot, fullPage: false });
+  shots.push(shot);
+  console.log("  shot:", shot);
+  await page.waitForTimeout(holdMs);
+}
+
+console.log("DEVICE_DEMO_DONE", JSON.stringify(shots));
+await page.waitForTimeout(1500);
+await browser.close();

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/inventory/inventory.page.block.ts

@@ -1,4 +1,5 @@
 import { definePageBlock, Trait } from "waygraph";
+import type { StubCtx } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 import { AddToCartBlock } from "./methods/add-to-cart.effect.block.js";
 import { RemoveFromCartBlock } from "./methods/remove-from-cart.effect.block.js";
@@ -27,6 +28,11 @@ export const InventoryPageBlock = definePageBlock<LoggedIn>({
     Trait.url({ pathname: "/inventory.html" }),
     Trait.visible(InventorySel.list),
   ],
+  // Showcase responsive dashboard: tablet after mobile login (toast + lerp).
+  stubBefore: (ctx: StubCtx) => {
+    ctx.title("Inventory · tablet");
+    ctx.device("tablet");
+  },
   methods: {
     addToCart: () => AddToCartBlock,
     removeFromCart: () => RemoveFromCartBlock,

package/package.json

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

package/templates/quickstart/src/blocks/saucedemo-web/inventory/inventory.page.block.ts

@@ -1,4 +1,5 @@
 import { definePageBlock, Trait } from "waygraph";
+import type { StubCtx } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 import { AddToCartBlock } from "./methods/add-to-cart.effect.block.js";
 import { RemoveFromCartBlock } from "./methods/remove-from-cart.effect.block.js";
@@ -27,6 +28,11 @@ export const InventoryPageBlock = definePageBlock<LoggedIn>({
     Trait.url({ pathname: "/inventory.html" }),
     Trait.visible(InventorySel.list),
   ],
+  // Showcase responsive dashboard: tablet after mobile login (toast + lerp).
+  stubBefore: (ctx: StubCtx) => {
+    ctx.title("Inventory · tablet");
+    ctx.device("tablet");
+  },
   methods: {
     addToCart: () => AddToCartBlock,
     removeFromCart: () => RemoveFromCartBlock,