waygraph 0.12.47 → 0.13.0

package/dist/cli.js

@@ -230,6 +230,8 @@ import {
   applyTodoPhase,
   advanceTodoDock,
   completeSequentialTodoDock,
+  applyDevicePhase,
+  resolveDeviceState,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -530,6 +532,18 @@ 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.
+  "#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;" +
+  "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;}" +
+  "#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-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;}" +
   "#wg-todos li{display:flex;gap:8px;align-items:flex-start;margin:0 0 6px;font:600 12.5px/1.35 system-ui,sans-serif;}" +
@@ -1252,6 +1266,64 @@ 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? }
+        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'>" +
+            "<path fill='#0C0C1A' stroke='#fff' stroke-width='1.4' stroke-linejoin='round' " +
+            "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 =
+            "<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>";
+          if (sync === "keep" && !device) return;
+          if (sync === "clear" || (device && device.preset === "desktop" && !device.touchMode)) {
+            if (badge) badge.remove();
+            if (cursor) {
+              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;
+          }
+          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);
+          }
+          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;
+            }
+          }
+        };
       },
       { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay },
     )
@@ -1725,6 +1797,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   const defaultHoldMs = opts && opts.defaultHoldMs != null ? opts.defaultHoldMs : null;
   const pace = opts && opts.pace !== undefined ? opts.pace : undefined;
   let dock = opts && opts.todoDock;
+  const advanceTodos = !(opts && opts.advanceTodos === false);
   // Push stubAfter/before dock before the first ring so Method after-panels
   // show the updated checklist immediately (not only after the ring cycle).
   if (dock) {
@@ -1751,7 +1824,10 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           size: h.size,
           weight: h.weight,
         });
-        if (dock) {
+        // Do NOT advanceTodoDock by ring index after stubAfter already set
+        // progress - that reset current back to 0 and the next block looked
+        // blank. Mid-act Method advance still uses syncTodoDockAdvance.
+        if (dock && advanceTodos) {
           dock = advanceTodoDock(dock, i);
           if (opts && opts.todoDockRef) opts.todoDockRef.current = dock;
           await page
@@ -1759,7 +1835,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
               if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "set", dock: d });
             }, dock)
             .catch(() => {});
-        } else if ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length)) {
+        } else if (!dock && ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length))) {
           const rows =
             opts && opts.todos && opts.todos.length
               ? opts.todos
@@ -1863,7 +1939,14 @@ async function renderAfterStep(page, info) {
     todoDock: info.todoDock,
     todos: info.todos,
     todoSync: info.todoSync,
+    todoDockRef: info.todoDockRef,
+    // stubAfter already authored progress - do not re-index by ring 0..n
+    advanceTodos: false,
   });
+  // After-ring advances may have moved the dock - surface latest for caller.
+  if (info.todoDockRef && info.todoDockRef.current) {
+    info.todoDock = info.todoDockRef.current;
+  }
   const afterPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
@@ -2670,6 +2753,49 @@ async function clickPulseAt(page, x, y, tone) {
     .catch(() => {});
 }
 
+/**
+ * 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.
+ */
+async function applyDeviceToPage(page, device, sync) {
+  const mode = sync || (device ? "set" : "keep");
+  if (mode === "keep" && !device) return;
+  const d =
+    device ||
+    resolveDeviceState("desktop", false) || {
+      preset: "desktop",
+      viewport: { width: 1280, height: 720, deviceScaleFactor: 1 },
+      isMobile: false,
+      hasTouch: false,
+      touchMode: false,
+    };
+  const realSet =
+    typeof page.__wgRealSetViewportSize === "function"
+      ? page.__wgRealSetViewportSize
+      : page.setViewportSize.bind(page);
+  try {
+    await realSet({
+      width: d.viewport.width,
+      height: d.viewport.height,
+    });
+  } catch {
+    /* maximized / null viewport hosts may reject - badge still updates */
+  }
+  await page
+    .evaluate(
+      (payload) => {
+        if (window.__wgSyncDevice) window.__wgSyncDevice(payload);
+      },
+      {
+        sync: mode,
+        device: d,
+        remain: mode === "keep" || mode === "set",
+      },
+    )
+    .catch(() => {});
+}
+
 /**
  * True if the engine's own narrate() (waygraph's public export, for a Block
  * author explicitly captioning one action) JUST positioned the ring for
@@ -2686,7 +2812,7 @@ async function wasJustNarrated(page) {
     .catch(() => false);
 }
 
-function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef) {
+function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef, deviceRef) {
   // Playwright's own slowMo ALREADY pauses after every single low-level
   // action it dispatches - and pressSequentially() fires one such action
   // PER CHARACTER. Also giving pressSequentially its own fixed delay
@@ -2850,7 +2976,36 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
         // mock click visually completes before the real one fires.
         await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 500));
       }
-      const result = await originalClick.call(this, options);
+      // Touch theater (0.13+): prefer Locator.tap / long-press when device
+      // touchMode is on (context launched with hasTouch). gesture on stub
+      // wins: tap | hold | click.
+      let result;
+      const stubsForGesture = (stubBeforeRef && stubBeforeRef.current) || [];
+      let gesture = "click";
+      try {
+        const idx = await matchStubIndexForLocator(page, this, stubsForGesture);
+        const stub = idx >= 0 ? stubsForGesture[idx] : null;
+        if (stub && stub.gesture) gesture = stub.gesture;
+        else if (deviceRef && deviceRef.current && deviceRef.current.touchMode) gesture = "tap";
+      } catch {
+        if (deviceRef && deviceRef.current && deviceRef.current.touchMode) gesture = "tap";
+      }
+      if (gesture === "tap" || gesture === "hold") {
+        try {
+          if (gesture === "hold") {
+            result = await this.tap({
+              ...(options || {}),
+              delay: skipTheater() ? 0 : 600,
+            });
+          } else {
+            result = await this.tap(options);
+          }
+        } catch {
+          result = await originalClick.call(this, options);
+        }
+      } else {
+        result = await originalClick.call(this, options);
+      }
       await new Promise((res) => setTimeout(res, clickPostPop()));
       await hideRing(page);
       return result;
@@ -2960,7 +3115,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   const stubBeforeRef = { current: [] };
   /** Live todo dock for Method fill/click advance (same carry as lastTodoDock). */
   const todoDockRef = { current: undefined };
-  instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef);
+  /** Live device fixture for touch theater (same carry as lastDevice). */
+  const deviceRef = { current: undefined };
+  instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef, deviceRef);
   // Force the panel checkbox from this process's flags/env at run start.
   // installOverlay only seeds localStorage when the key is null (so mid-run
   // checkbox clicks survive navigations). Without this, a prior --autoplay
@@ -2991,7 +3148,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   // setViewportSize entirely for the duration of step mode. Blocks that
   // call it don't need it to actually do anything here - their own
   // selectors/layouts still work fine at whatever size the real window
-  // already is.
+  // already is. Authored ctx.device() still uses __wgRealSetViewportSize.
+  page.__wgRealSetViewportSize = page.setViewportSize.bind(page);
   page.setViewportSize = async () => {};
   let resolveNext = null;
   // Render-to-gate race: a slide/step panel's Next button is wired to
@@ -3089,6 +3247,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   let result;
   /** Carry floating todo dock across steps (empty stubBefore must not wipe). */
   let lastTodoDock = undefined;
+  /** Carry device / touch fixture across steps (omit = keep, like todos). */
+  let lastDevice = undefined;
   for (let i = 0; i < resolved.length; i++) {
     const r = resolved[i];
     // The block breadcrumb is scoped to THIS step's own episode, not the
@@ -3182,6 +3342,15 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     });
     lastTodoDock = appliedBefore.dock;
     todoDockRef.current = lastTodoDock;
+    const appliedDeviceBefore = applyDevicePhase(lastDevice, {
+      deviceSync: stubBeforePhase.deviceSync,
+      device: stubBeforePhase.device,
+    });
+    lastDevice = appliedDeviceBefore.device;
+    deviceRef.current = lastDevice;
+    if (appliedDeviceBefore.sync !== "keep" || lastDevice) {
+      await applyDeviceToPage(page, lastDevice, appliedDeviceBefore.sync);
+    }
     const stubBeforeTodos =
       (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
       stubBeforePhase.todos ||
@@ -3339,6 +3508,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       })
       .catch(() => {});
     result = stepOutcome.result;
+    // Mid-act Method fill/click advances live on todoDockRef - fold that
+    // back into lastTodoDock before stubAfter / next-block keep, or the
+    // next step reverts to the pre-act (blank / index-0) checklist.
+    if (todoDockRef.current) lastTodoDock = todoDockRef.current;
     // withExpectedFailure last block that SUCCEEDS on the intentional fail
     // branch (e.g. submit-login -> LoginPage + error banner). Still show
     // stubOnError rings + amber "expected outcome" panel - branching no
@@ -3403,6 +3576,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     let afterOverlayTitle = overlayTitle;
     let afterTodoPos = overlayTodoPos;
     let appliedAfter = { dock: lastTodoDock, sync: "keep" };
+    let appliedDeviceAfter = { device: lastDevice, sync: "keep" };
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
       const afterPhase = await runStubPhase(r.block, "stubAfter", {
         out: result,
@@ -3416,6 +3590,15 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       });
       lastTodoDock = appliedAfter.dock;
       todoDockRef.current = lastTodoDock;
+      appliedDeviceAfter = applyDevicePhase(lastDevice, {
+        deviceSync: afterPhase.deviceSync,
+        device: afterPhase.device,
+      });
+      lastDevice = appliedDeviceAfter.device;
+      deviceRef.current = lastDevice;
+      if (appliedDeviceAfter.sync !== "keep" || (appliedDeviceAfter.sync === "set" && lastDevice)) {
+        await applyDeviceToPage(page, lastDevice, appliedDeviceAfter.sync);
+      }
       stubAfterTodos =
         (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
         afterPhase.todos ||
@@ -3467,6 +3650,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       todoDock: lastTodoDock,
       todoSync: appliedAfter.sync,
       todoId: lastTodoDock && lastTodoDock.id,
+      todoDockRef,
       forceCollapsed:
         !!process.env.WAYGRAPH_VIDEO ||
         process.env.WAYGRAPH_MINI === "1" ||
@@ -3474,6 +3658,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           ? true
           : undefined,
     });
+    // Ring cycle / stubAfter may have advanced the dock - persist for next block.
+    if (todoDockRef.current) lastTodoDock = todoDockRef.current;
     await gate();
   }
   await teardownOverlay(page);
@@ -3862,10 +4048,11 @@ async function main() {
           // Lock DPR so --video-viewport 800x450 stays 800x450 in the .webm
           // (HiDPI hosts otherwise scale recordVideo to e.g. 1920x1080).
           deviceScaleFactor: 1,
+          hasTouch: true,
         }
       : step
-        ? { baseURL, viewport: null }
-        : { baseURL, viewport: { width: 1280, height: 720 } };
+        ? { baseURL, viewport: null, hasTouch: true }
+        : { baseURL, viewport: { width: 1280, height: 720 }, hasTouch: true };
     if (videoDir) {
       contextOpts.recordVideo = fixedVideoViewport
         ? { dir: videoDir, size: fixedVideoViewport }

package/dist/highlights.d.ts

@@ -117,6 +117,57 @@ export type StubPhaseFixtures = {
      * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
      */
     todoPos?: "left" | "right";
+    /**
+     * Viewport preset: `mobile` | `tablet` | `desktop` (default / clear).
+     * Omit on later blocks = **keep** (same persist pattern as todos).
+     */
+    device?: DevicePreset | DeviceState;
+    /** Explicit pixel viewport (wins over preset width/height when both set). */
+    viewport?: DeviceViewport;
+    /** Touch theater + Playwright touchscreen when true. */
+    touch?: boolean;
+};
+/** Named viewport presets (0.13+). */
+export type DevicePreset = "mobile" | "tablet" | "desktop";
+/** Explicit viewport box. */
+export type DeviceViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+/**
+ * Carried device fixture (todo-dock shaped persist).
+ * Omit on a later step = keep; hideDevice/clearDevice/desktop = clear to desktop.
+ */
+export type DeviceState = {
+    preset: DevicePreset;
+    viewport: DeviceViewport;
+    /** Playwright-ish: treat as mobile layout. */
+    isMobile: boolean;
+    /** Context needs hasTouch for touchscreen.tap (demo launches with hasTouch). */
+    hasTouch: boolean;
+    /** Demo gesture theater: finger cursor, tap/hold timing, prefer touchscreen. */
+    touchMode: boolean;
+};
+/** Built-in preset sizes (CSS pixels). */
+export declare const DEVICE_PRESETS: Record<DevicePreset, Omit<DeviceState, "touchMode"> & {
+    touchMode?: boolean;
+}>;
+export declare function normalizeDevicePreset(raw: unknown): DevicePreset | undefined;
+/** Resolve a preset name or partial state into a full DeviceState. */
+export declare function resolveDeviceState(input: DevicePreset | DeviceState | DeviceViewport | undefined, touchOverride?: boolean): DeviceState | undefined;
+/**
+ * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
+ * - clear: hideDevice / clearDevice / device("desktop") with clear intent
+ * - set: author set device/viewport/touch this phase
+ * - keep: omit - preserve previous (whole episode remain)
+ */
+export declare function applyDevicePhase(prev: DeviceState | undefined, phase: {
+    deviceSync?: "set" | "clear" | "keep";
+    device?: DeviceState;
+}): {
+    device: DeviceState | undefined;
+    sync: "set" | "clear" | "keep";
 };
 /** One named highlight slot on a block (selector + caption). */
 export interface WaygraphHighlightStub extends FixtureDurationFields {
@@ -176,6 +227,13 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      * for authored stub queues; set false to keep cursor hidden).
      */
     cursor?: boolean;
+    /**
+     * Pointer feel when touchMode is on (0.13+):
+     * - `tap` - short press via touchscreen (default in touch mode)
+     * - `hold` - long-press (~600ms) then release
+     * - `click` - mouse click even in touch mode
+     */
+    gesture?: "tap" | "hold" | "click";
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
 export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "zoomOut" | "focus" | "followMouse" | "follow" | "color" | "cursor"> & FixtureDurationFields;
@@ -238,6 +296,23 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     hideTodos(): void;
     /** Alias for {@link StubCtx.hideTodos}. */
     clearTodos(): void;
+    /**
+     * Viewport / device fixture (0.13+). `mobile` | `tablet` | `desktop`.
+     * Omit on later blocks = **keep** (same persist as todos). Use
+     * {@link StubCtx.hideDevice} / {@link StubCtx.clearDevice} to return to desktop.
+     */
+    device(preset: DevicePreset | DeviceState): void;
+    /** Explicit CSS-pixel viewport (implies mobile-ish unless desktop-sized). */
+    viewport(box: DeviceViewport): void;
+    /** Enable / disable touch theater + touchscreen gestures. */
+    touch(on?: boolean): void;
+    /**
+     * Reset to desktop viewport and clear touch mode. Omit device on a later
+     * block = **keep**; only hideDevice / clearDevice / device("desktop") clears.
+     */
+    hideDevice(): void;
+    /** Alias for {@link StubCtx.hideDevice}. */
+    clearDevice(): void;
     /** Default camera zoom for rings without their own zoom. */
     zoom(n: number): void;
     /**
@@ -280,6 +355,15 @@ export type StubPhaseResult = {
      * - `keep` - author omitted todos; demo must leave previous dock alone
      */
     todoSync?: "set" | "clear" | "keep";
+    /** Resolved device after this phase (undefined when keep with no prior). */
+    device?: DeviceState;
+    /**
+     * Device intent (mirror todoSync):
+     * - `set` - apply {@link device}
+     * - `clear` - reset to desktop (hideDevice / clearDevice / device desktop)
+     * - `keep` - author omitted device; demo must leave previous alone
+     */
+    deviceSync?: "set" | "clear" | "keep";
     zoom?: number;
     zoomOut?: boolean;
     title?: string;

package/dist/highlights.js

@@ -12,6 +12,123 @@
  * 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). */
+export const DEVICE_PRESETS = {
+    mobile: {
+        preset: "mobile",
+        viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
+        isMobile: true,
+        hasTouch: true,
+        touchMode: true,
+    },
+    tablet: {
+        preset: "tablet",
+        viewport: { width: 768, height: 1024, deviceScaleFactor: 2 },
+        isMobile: true,
+        hasTouch: true,
+        touchMode: true,
+    },
+    desktop: {
+        preset: "desktop",
+        viewport: { width: 1280, height: 720, deviceScaleFactor: 1 },
+        isMobile: false,
+        hasTouch: false,
+        touchMode: false,
+    },
+};
+export function normalizeDevicePreset(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "mobile" || s === "phone" || s === "m")
+        return "mobile";
+    if (s === "tablet" || s === "pad" || s === "t")
+        return "tablet";
+    if (s === "desktop" || s === "desk" || s === "d" || s === "main")
+        return "desktop";
+    return undefined;
+}
+/** Resolve a preset name or partial state into a full DeviceState. */
+export function resolveDeviceState(input, touchOverride) {
+    if (input === undefined)
+        return undefined;
+    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 {
+            preset: base.preset,
+            viewport: { ...base.viewport },
+            isMobile: base.isMobile,
+            hasTouch: base.hasTouch || touchMode,
+            touchMode,
+        };
+    }
+    if ("width" in input && "height" in input && !("preset" in input)) {
+        const vp = input;
+        const touchMode = touchOverride !== undefined ? !!touchOverride : true;
+        return {
+            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 }),
+            },
+            isMobile: true,
+            hasTouch: true,
+            touchMode,
+        };
+    }
+    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,
+    };
+}
+/**
+ * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
+ * - clear: hideDevice / clearDevice / device("desktop") with clear intent
+ * - set: author set device/viewport/touch this phase
+ * - keep: omit - preserve previous (whole episode remain)
+ */
+export function applyDevicePhase(prev, phase) {
+    const sync = phase.deviceSync ||
+        (phase.device ? "set" : "keep");
+    if (sync === "clear") {
+        return { device: resolveDeviceState("desktop", false), sync: "clear" };
+    }
+    if (sync === "set") {
+        if (phase.device)
+            return { device: phase.device, sync: "set" };
+        return { device: resolveDeviceState("desktop", false), sync: "clear" };
+    }
+    return { device: prev, sync: "keep" };
+}
 /** Apply Flow defaults under per-slot authored values (slot wins when set). */
 export function applyHighlightStyleDefaults(slot, defaults) {
     const tone = slot.tone !== undefined && slot.tone !== ""
@@ -600,6 +717,57 @@ function createStubCtx(bag, opts) {
             bag.todos = [];
             delete bag.todoGroups;
         },
+        device(preset) {
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            const resolved = resolveDeviceState(preset, bag.touchOverride);
+            if (resolved) {
+                bag.device = resolved;
+                if (resolved.preset === "desktop" && !resolved.touchMode) {
+                    bag.hideDevice = true;
+                }
+            }
+        },
+        viewport(box) {
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            const resolved = resolveDeviceState(box, bag.touchOverride);
+            if (resolved)
+                bag.device = resolved;
+        },
+        touch(on) {
+            bag.deviceTouched = true;
+            const enabled = on === undefined ? true : !!on;
+            bag.touchOverride = enabled;
+            if (enabled)
+                bag.hideDevice = false;
+            if (bag.device) {
+                bag.device = {
+                    ...bag.device,
+                    touchMode: enabled,
+                    hasTouch: bag.device.hasTouch || enabled,
+                };
+                if (enabled)
+                    bag.hideDevice = false;
+            }
+            else if (enabled) {
+                const base = resolveDeviceState("desktop", true);
+                if (base)
+                    bag.device = { ...base, touchMode: true, hasTouch: true };
+            }
+        },
+        hideDevice() {
+            bag.deviceTouched = true;
+            bag.hideDevice = true;
+            bag.device = resolveDeviceState("desktop", false);
+            bag.touchOverride = false;
+        },
+        clearDevice() {
+            bag.deviceTouched = true;
+            bag.hideDevice = true;
+            bag.device = resolveDeviceState("desktop", false);
+            bag.touchOverride = false;
+        },
         zoom(n) {
             if (Number.isFinite(n) && n > 0)
                 bag.zoom = n;
@@ -648,6 +816,27 @@ function createStubCtx(bag, opts) {
                 bag.hideTodos = !partial.todoGroups || !partial.todoGroups.length;
                 bag.todoGroups = partial.todoGroups;
             }
+            if (partial.touch !== undefined) {
+                bag.deviceTouched = true;
+                bag.touchOverride = !!partial.touch;
+            }
+            if (partial.device !== undefined) {
+                bag.deviceTouched = true;
+                bag.hideDevice = false;
+                const resolved = resolveDeviceState(partial.device, bag.touchOverride);
+                if (resolved) {
+                    bag.device = resolved;
+                    if (resolved.preset === "desktop" && !resolved.touchMode)
+                        bag.hideDevice = true;
+                }
+            }
+            if (partial.viewport !== undefined) {
+                bag.deviceTouched = true;
+                bag.hideDevice = false;
+                const resolved = resolveDeviceState(partial.viewport, bag.touchOverride);
+                if (resolved)
+                    bag.device = resolved;
+            }
             if (partial.zoom !== undefined && Number.isFinite(partial.zoom) && partial.zoom > 0) {
                 bag.zoom = partial.zoom;
             }
@@ -812,12 +1001,37 @@ export async function runStubPhase(block, phase, opts) {
             : bag.todoTouched && !todoDock
                 ? "clear"
                 : "keep";
+    let deviceState;
+    if (bag.hideDevice) {
+        deviceState = resolveDeviceState("desktop", false);
+    }
+    else if (bag.device) {
+        deviceState = bag.touchOverride !== undefined
+            ? {
+                ...bag.device,
+                touchMode: bag.touchOverride,
+                hasTouch: bag.device.hasTouch || bag.touchOverride,
+            }
+            : bag.device;
+    }
+    else if (bag.touchOverride !== undefined) {
+        deviceState = resolveDeviceState("desktop", bag.touchOverride);
+    }
+    const deviceSync = bag.hideDevice
+        ? "clear"
+        : bag.deviceTouched && deviceState
+            ? "set"
+            : bag.deviceTouched && !deviceState
+                ? "clear"
+                : "keep";
     return {
         highlights,
         todos,
         todoSync,
+        deviceSync,
         ...(bag.todoIndex !== undefined ? { todoIndex: bag.todoIndex } : {}),
         ...(todoDock ? { todoDock } : {}),
+        ...(deviceState ? { device: deviceState } : {}),
         ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
         ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),

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, 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, } 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, 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 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, 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, 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/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -37,6 +37,8 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     // Demo: zoom product -> add (stay zoomed), then badge after act.
     stubBefore: (ctx: StubCtx) => {
       ctx.title("Pick a product");
+      // Back to desktop after mobile login (explicit clear - not omit/remain).
+      ctx.clearDevice();
       ctx.todoId("saucedemo-cart");
       ctx.todos([
         { id: "cart-find", text: "Find the product" },

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

@@ -51,11 +51,13 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     // 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.device("mobile");
       ctx.todoId("saucedemo-login");
       ctx.todos([
         { id: "login-user", text: "Enter username" },
         { id: "login-pass", text: "Enter password" },
-        { id: "login-submit", text: "Click Login" },
+        { id: "login-submit", text: "Tap Login" },
       ]);
       ctx.todoIndex(0);
       ctx.zoom(1.35);
@@ -81,6 +83,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
           color: "#86efac",
           zoom: 1.55,
           weight: "bold",
+          gesture: "tap",
         },
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.47",
+  "version": "0.13.0",
   "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/methods/add-to-cart.effect.block.ts

@@ -36,6 +36,8 @@ 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();
       ctx.todoId("saucedemo-cart");
       ctx.todos([
         { id: "cart-find", text: "Find the product" },

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

@@ -51,11 +51,13 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     // 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.device("mobile");
       ctx.todoId("saucedemo-login");
       ctx.todos([
         { id: "login-user", text: "Enter username" },
         { id: "login-pass", text: "Enter password" },
-        { id: "login-submit", text: "Click Login" },
+        { id: "login-submit", text: "Tap Login" },
       ]);
       ctx.todoIndex(0);
       ctx.zoom(1.35);
@@ -81,6 +83,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
           color: "#86efac",
           zoom: 1.55,
           weight: "bold",
+          gesture: "tap",
         },
       });
     },