waygraph 0.15.21 → 0.15.23

package/dist/runner/teardown.js

@@ -0,0 +1,195 @@
+// Moved verbatim from the former CHAIN_RUNNER_SCRIPT template string in cli.ts (see src/ARCHITECTURE.md).
+// Runs inside the target project's own waygraph copy - keep it dependency-light and self-contained.
+import { installOverlay } from "./overlay-install.js";
+import { applyDeviceToPage } from "./device-stage.js";
+import { showRing } from "./rings.js";
+import { formatHighlightCaption } from "../highlights.js";
+
+/**
+ * Patches Locator.prototype.fill (via any real locator's own prototype
+ * chain - Playwright doesn't export the class directly) so every fill(),
+ * regardless of how the Block built that locator (page.locator, chained
+ * .getByLabel off a scoped form locator, etc.), highlights the real target
+ * first, then types it out character by character instead of snapping the
+ * whole value in - "when something is written from mem, it should
+ * highlight then slowly input." One-time patch (idempotent - guarded so a
+ * multi-step chain doesn't re-wrap an already-wrapped fill).
+ */
+/**
+ * Called once the gate resolves - manual click OR autoplay timeout, both
+ * covered from here rather than duplicating this in the in-page click
+ * handler - right before the Block's own act() actually starts. Dan: "i
+ * want the button, step is running thing. so i wont be able to interrupt
+ * the playwright automation" - the "Run this step" button used to sit
+ * there still looking clickable for the entire multi-second duration a
+ * real act()/observe() takes, inviting a confusing extra click (harmless -
+ * __wgNext no-ops once already consumed - but looked live when it wasn't).
+ * Disables the button and mem-key textareas, and swaps whichever gate
+ * text was showing (manual button or "Auto-advancing...") to "Running...".
+ * ALWAYS collapses the panel while act() runs - leaving it expanded was a
+ * real bug: #wg-panel sits at z-index max with pointer-events:auto, so
+ * Playwright's login/add-to-cart clicks hit the stepper instead of the app
+ * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
+ * edge click on Login then produced Sauce Demo's Epic sadface, verify
+ * still passed on the error banner, and the next block blew up. Collapse
+ * also matches Dan's "step is running / can't interrupt" ask. (_opts kept
+ * for call-site compat; autoCollapsePanel is now unconditional.)
+ */
+export async function markStepRunning(page, _opts) {
+  await page
+    .evaluate(() => {
+      const runBtn = document.getElementById("wg-run");
+      if (runBtn) {
+        runBtn.disabled = true;
+        runBtn.textContent = "Running \u25B6";
+      }
+      const autoEl = document.getElementById("wg-gate-auto");
+      if (autoEl) autoEl.textContent = "Running...";
+      document.querySelectorAll("#wg-panel textarea[data-key]").forEach((ta) => {
+        ta.disabled = true;
+      });
+      const panel = document.getElementById("wg-panel");
+      if (panel) {
+        panel.classList.add("wg-collapsed");
+        panel.setAttribute("data-wg-collapsed", "1");
+        panel.setAttribute("data-wg-phase", "running");
+        if (typeof window.__wgStampModal === "function") {
+          window.__wgStampModal(panel, "panel", {
+            phase: "running",
+            ready: true,
+          });
+        }
+        const toggle = panel.querySelector("[data-wg-toggle]");
+        if (toggle) toggle.textContent = "Show";
+        const titleEl = panel.querySelector(".wg-chrome-title");
+        const label = panel.dataset.wgStepLabel;
+        if (titleEl && label) titleEl.textContent = label;
+        const miniNext = panel.querySelector("[data-wg-mini-next]");
+        if (miniNext) {
+          miniNext.disabled = true;
+          miniNext.classList.remove("wg-mini-next-show");
+        }
+      }
+    })
+    .catch(() => {});
+}
+
+
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+export async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
+  const needs =
+    (await page
+      .evaluate(() => !window.__wgSyncTodos || !document.getElementById("wg-ring"))
+      .catch(() => true)) || false;
+  if (!needs) {
+    // Overlay survived (SPA / no full document wipe) - still refresh dock
+    // if Node has a carry and the DOM lost .wg-todo-dock.
+    const hasDock = await page
+      .evaluate(() => !!document.querySelector(".wg-todo-dock, #wg-todo-dock"))
+      .catch(() => false);
+    if (hasDock || !todoDockRef || !todoDockRef.current) return;
+  }
+  await installOverlay(page);
+  const dock = todoDockRef && todoDockRef.current;
+  if (dock) {
+    await page
+      .evaluate((d) => {
+        if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "set", dock: d });
+      }, dock)
+      .catch(() => {});
+  }
+  if (deviceRef && deviceRef.current) {
+    await applyDeviceToPage(page, deviceRef.current, "set").catch(() => {});
+  }
+  // Re-show first matching stubBefore ring if selector still exists (sidebar
+  // nav targets often survive the route change).
+  const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+  for (const h of stubs) {
+    if (!h || !h.selector) continue;
+    const box = await page
+      .evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        if (r.width < 2 || r.height < 2) return null;
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+      }, h.selector)
+      .catch(() => null);
+    if (box) {
+      await showRing(page, box, formatHighlightCaption(h), h.tone || "planned", {
+        size: h.size,
+        weight: h.weight,
+        selector: h.selector,
+        focus: !!h.focus,
+      }).catch(() => {});
+      break;
+    }
+  }
+}
+
+
+/**
+ * Removes every overlay element (panel, ring, ring-label, cursor,
+ * click-pulse, banner) and stops the live resize/scroll ring tracker, once
+ * the whole chain is genuinely done - "I want to see the same page just
+ * like the demo opened for the first time," not the last step's panel and
+ * highlight ring stuck over the real app forever. installOverlay only ever
+ * ADDS these elements back on demand (idempotent, per-page-load) - nothing
+ * re-creates them once torn down here unless another Block/fill/click runs.
+ */
+export async function teardownOverlay(page) {
+  await page
+    .evaluate(() => {
+      if (window.__wgRingTrack) {
+        window.removeEventListener("resize", window.__wgRingTrack);
+        window.removeEventListener("scroll", window.__wgRingTrack, true);
+        window.__wgRingTrack = null;
+      }
+      window.__wgNarrateOwnsRing = false;
+      for (const id of [
+        "wg-panel",
+        "wg-ring",
+        "wg-ring-label",
+        "wg-cursor",
+        "wg-click-pulse",
+        "wg-banner",
+        "wg-todo-dock",
+        "wg-device-shell",
+        "wg-device-toast",
+        "wg-device-badge",
+      ]) {
+        const el = document.getElementById(id);
+        if (el) el.remove();
+      }
+      document.querySelectorAll(".wg-todo-dock").forEach((el) => el.remove());
+      document.documentElement.classList.remove("wg-video-device-stage");
+    })
+    .catch(() => {});
+}
+
+
+/**
+ * Clears cookies + storage and re-navigates to a known-fresh page. Shared by
+ * the per-block session-reset check below and by the error panel's own
+ * "Retry Episode" button - a retry needs the exact same clean slate a normal
+ * episode boundary gets, not just re-running the failed block against
+ * whatever broken/half-navigated state it left the page in.
+ */
+export async function resetPageState(context, page, baseURL) {
+  await context.clearCookies().catch(() => {});
+  await page
+    .evaluate(() => {
+      try {
+        localStorage.clear();
+        sessionStorage.clear();
+      } catch {
+        /* storage blocked (e.g. about:blank) - nothing to clear anyway */
+      }
+    })
+    .catch(() => {});
+  await page.goto(baseURL || "about:blank").catch(() => {});
+}

package/dist/runner/todo-dock.js

@@ -0,0 +1,142 @@
+// Moved verbatim from the former CHAIN_RUNNER_SCRIPT template string in cli.ts (see src/ARCHITECTURE.md).
+// Runs inside the target project's own waygraph copy - keep it dependency-light and self-contained.
+import { join } from "node:path";
+import { advanceTodoDock } from "../highlights.js";
+import { demoLog } from "./demo-log.js";
+
+function todosHtmlFromInfo(info, escFn) {
+  const list = info.todos || [];
+  if (!list.length) return "";
+  return (
+    "<ul id=\"wg-todos\">" +
+    list
+      .map((t) => {
+        const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+        const mark = t.done ? "\u2713" : t.current ? "\u2192" : "\u25CB";
+        return (
+          "<li class=\"" +
+          cls +
+          "\"><span class=\"wg-todo-mark\">" +
+          mark +
+          "</span><span>" +
+          escFn(t.text || "") +
+          "</span></li>"
+        );
+      })
+      .join("") +
+    "</ul>"
+  );
+}
+
+
+/** Flatten dock items in order (sequential groups). */
+function flattenTodoDockItems(dock) {
+  const items = [];
+  if (!dock || !dock.groups) return items;
+  for (const g of dock.groups) {
+    for (const t of g.items || []) items.push(t);
+  }
+  return items;
+}
+
+
+/**
+ * Resolve which todo index a matched stub should advance to.
+ * Prefer stub.todo / stub.slotId / stub.id against item.id; never jump backward.
+ */
+function resolveTodoAdvanceIndex(dock, stub, stubIndex) {
+  const items = flattenTodoDockItems(dock);
+  if (!items.length) return stubIndex;
+  const curIdx = items.findIndex((t) => t.current);
+  let idx = stubIndex;
+  const key = stub && (stub.todo || stub.slotId || stub.id);
+  if (key) {
+    const k = String(key).trim().toLowerCase();
+    let found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === k);
+    if (found < 0) {
+      // username -> login-user, password -> login-pass, submit -> login-submit
+      const aliases = {
+        username: ["login-user", "user", "email"],
+        password: ["login-pass", "pass"],
+        submit: ["login-submit", "login", "tap-login"],
+        user: ["login-user", "username"],
+        pass: ["login-pass", "password"],
+      };
+      const alts = aliases[k] || [];
+      for (const a of alts) {
+        found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === a);
+        if (found >= 0) break;
+      }
+    }
+    if (found < 0) {
+      found = items.findIndex(
+        (t) =>
+          (t.id && String(t.id).toLowerCase().includes(k)) ||
+          (t.text && String(t.text).toLowerCase().includes(k)),
+      );
+    }
+    if (found >= 0) idx = found;
+  }
+  // Monotonic: never retreat the walkthrough.
+  if (curIdx >= 0 && idx < curIdx) idx = curIdx;
+  return idx;
+}
+
+
+/** Advance sequential todo dock to stubIndex and push to the page (Method act). */
+export async function syncTodoDockAdvance(page, todoDockRef, stubIndex, stub) {
+  if (!todoDockRef || stubIndex < 0) return;
+  const prev = todoDockRef.current;
+  if (!prev) return;
+  const idx = resolveTodoAdvanceIndex(prev, stub || null, stubIndex);
+  const advanced = advanceTodoDock(prev, idx);
+  todoDockRef.current = advanced;
+  demoLog(
+    "  todo advance -> idx=" +
+      idx +
+      (stub && (stub.slotId || stub.todo)
+        ? " slot=" + (stub.todo || stub.slotId)
+        : " stub#" + stubIndex) +
+      ' current="' +
+      String(
+        (flattenTodoDockItems(advanced).find((t) => t.current) || {}).text || "",
+      ).slice(0, 40) +
+      '"',
+  );
+  await page
+    .evaluate((dock) => {
+      if (window.__wgSyncTodos) {
+        window.__wgSyncTodos({ sync: "set", dock });
+      }
+    }, advanced)
+    .catch(() => {});
+}
+
+export async function probeTodoDocksOnPage(page) {
+  return page
+    .evaluate(() => {
+      const docks = [...document.querySelectorAll(".wg-todo-dock, #wg-todo-dock")];
+      return docks.map((el) => {
+        const r = el.getBoundingClientRect();
+        const items = el.querySelectorAll("li");
+        let current = "";
+        items.forEach((li) => {
+          if (li.classList.contains("wg-todo-current")) {
+            current = (li.textContent || "").replace(/s+/g, " ").trim().slice(0, 48);
+          }
+        });
+        return {
+          key: el.getAttribute("data-wg-todo-key") || el.id || "?",
+          pos: el.dataset.pos || "?",
+          top: Math.round(r.top),
+          left: Math.round(r.left),
+          w: Math.round(r.width),
+          h: Math.round(r.height),
+          onScreen: r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth,
+          n: items.length,
+          current,
+        };
+      });
+    })
+    .catch(() => []);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.21",
+  "version": "0.15.23",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -10,6 +10,9 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./runner": {
+      "default": "./dist/runner/index.js"
     }
   },
   "bin": {
@@ -34,15 +37,16 @@
     "url": "git+https://github.com/deviate-dv8/waygraph.git"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-runner.mjs",
     "typecheck": "node bin/waygraph typecheck .",
-    "test": "npm run test:unit && playwright test",
+    "test": "npm run check:structure && npm run test:unit && playwright test",
     "test:ui": "playwright test --ui",
     "test:unit": "node --import tsx/esm --test tests/unit/*.spec.ts",
     "docs:preview": "python3 -m http.server 4173 --directory docs",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",
     "example:saucedemo:test": "npm --prefix examples/saucedemo test",
-    "example:saucedemo:auto": "npm --prefix examples/saucedemo run auto"
+    "example:saucedemo:auto": "npm --prefix examples/saucedemo run auto",
+    "check:structure": "node scripts/check-structure.mjs"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"