waygraph 0.12.41 → 0.12.43

package/dist/engine.d.ts

@@ -292,15 +292,15 @@ export declare function withBlockPace<In extends Checkpoint<string>, Out extends
  * {@link withTitle}.
  *
  * By itself this changes nothing about how the Flow runs - it still throws
- * exactly as it would otherwise. It's a hint a step-through overlay
- * (waygraph's `chain --step`) reads when that throw happens, to show an
- * informational "this is the point" panel instead of one indistinguishable
- * from a genuine break - the distinction a demo author needs so a viewer
- * (or the author, mid-build) can tell "the app just did what it's supposed
- * to" apart from "something in this demo is actually broken."
+ * Marks a Flow whose last step is an intentional product failure (demo overlay).
+ * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
+ * - the last block **throws**, or
+ * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
+ *   after submit-login branched instead of throwing).
+ * Headless `run()` is unchanged - branching success returns the checkpoint.
  * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, blockedLoginCheck, end]),
- *   "locked_out_user can never reach /inventory.html - this is the block working as intended.",
+ *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
+ *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
  * );
  */
 export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;

package/dist/engine.js

@@ -405,15 +405,15 @@ export function withBlockPace(block, pace) {
  * {@link withTitle}.
  *
  * By itself this changes nothing about how the Flow runs - it still throws
- * exactly as it would otherwise. It's a hint a step-through overlay
- * (waygraph's `chain --step`) reads when that throw happens, to show an
- * informational "this is the point" panel instead of one indistinguishable
- * from a genuine break - the distinction a demo author needs so a viewer
- * (or the author, mid-build) can tell "the app just did what it's supposed
- * to" apart from "something in this demo is actually broken."
+ * Marks a Flow whose last step is an intentional product failure (demo overlay).
+ * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
+ * - the last block **throws**, or
+ * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
+ *   after submit-login branched instead of throwing).
+ * Headless `run()` is unchanged - branching success returns the checkpoint.
  * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, blockedLoginCheck, end]),
- *   "locked_out_user can never reach /inventory.html - this is the block working as intended.",
+ *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
+ *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
  * );
  */
 export function withExpectedFailure(flow, reason) {

package/dist/index.d.ts

@@ -16,3 +16,5 @@ export { runTraverse } from "./traverse-run.js";
 export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse-run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
 export type { TraverseCoverageReport } from "./traverse-coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
+export type { WgModalKind, WgBeaconRow } from "./overlay-beacon.js";

package/dist/index.js

@@ -8,3 +8,4 @@ export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp,
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";

package/dist/overlay-beacon.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Blind-agent / Playwright checks for waygraph overlay modals.
+ *
+ * Every live modal root must carry:
+ *   data-wg-ui="1"
+ *   data-wg-modal="panel|banner|auto-panel"
+ *   data-wg-ready="1" when painted and readable
+ *
+ * Agents: do not claim the stepper works unless
+ *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
+ */
+import type { Page } from "@playwright/test";
+export declare const WG_UI_SEL = "[data-wg-ui=\"1\"]";
+export declare const WG_READY_PANEL_SEL = "[data-wg-modal=\"panel\"][data-wg-ready=\"1\"]";
+export declare const WG_READY_AUTO_SEL = "[data-wg-modal=\"auto-panel\"][data-wg-ready=\"1\"]";
+export declare const WG_READY_BANNER_SEL = "[data-wg-modal=\"banner\"][data-wg-ready=\"1\"]";
+export type WgModalKind = "panel" | "banner" | "auto-panel";
+export type WgBeaconRow = {
+    id: string | null;
+    modal: string | null;
+    ready: boolean;
+    phase: string | null;
+    step: string | null;
+    block: string | null;
+    collapsed: boolean;
+    opacity: string;
+    textLen: number;
+    w: number;
+    h: number;
+    visible: boolean;
+};
+/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
+export declare function readWgOverlayBeaconInPage(): WgBeaconRow[];
+export declare function readWgOverlayBeacon(page: Page): Promise<WgBeaconRow[]>;
+/**
+ * Hard gate: a blank / missing / opacity-0 modal fails.
+ * Use after demo/auto paints its first overlay.
+ */
+export declare function assertWgOverlayReady(page: Page, opts?: {
+    modal?: WgModalKind;
+    minTextLen?: number;
+    /** When true, collapsed mini chrome is allowed (still needs visible box + text). */
+    allowCollapsed?: boolean;
+}): Promise<WgBeaconRow>;

package/dist/overlay-beacon.js

@@ -0,0 +1,85 @@
+/**
+ * Blind-agent / Playwright checks for waygraph overlay modals.
+ *
+ * Every live modal root must carry:
+ *   data-wg-ui="1"
+ *   data-wg-modal="panel|banner|auto-panel"
+ *   data-wg-ready="1" when painted and readable
+ *
+ * Agents: do not claim the stepper works unless
+ *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
+ */
+export const WG_UI_SEL = '[data-wg-ui="1"]';
+export const WG_READY_PANEL_SEL = '[data-wg-modal="panel"][data-wg-ready="1"]';
+export const WG_READY_AUTO_SEL = '[data-wg-modal="auto-panel"][data-wg-ready="1"]';
+export const WG_READY_BANNER_SEL = '[data-wg-modal="banner"][data-wg-ready="1"]';
+/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
+export function readWgOverlayBeaconInPage() {
+    const w = globalThis;
+    if (typeof w.__wgOverlayBeacon === "function")
+        return w.__wgOverlayBeacon();
+    return Array.from(document.querySelectorAll(WG_UI_SEL)).map((el) => {
+        const r = el.getBoundingClientRect();
+        const st = getComputedStyle(el);
+        return {
+            id: el.id || null,
+            modal: el.getAttribute("data-wg-modal"),
+            ready: el.getAttribute("data-wg-ready") === "1",
+            phase: el.getAttribute("data-wg-phase"),
+            step: el.getAttribute("data-wg-step"),
+            block: el.getAttribute("data-wg-block"),
+            collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+            opacity: st.opacity,
+            textLen: (el.textContent || "").trim().length,
+            w: Math.round(r.width),
+            h: Math.round(r.height),
+            visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+        };
+    });
+}
+export async function readWgOverlayBeacon(page) {
+    return page.evaluate(() => {
+        const w = window;
+        if (typeof w.__wgOverlayBeacon === "function") {
+            return w.__wgOverlayBeacon();
+        }
+        return Array.from(document.querySelectorAll('[data-wg-ui="1"]')).map((el) => {
+            const r = el.getBoundingClientRect();
+            const st = getComputedStyle(el);
+            return {
+                id: el.id || null,
+                modal: el.getAttribute("data-wg-modal"),
+                ready: el.getAttribute("data-wg-ready") === "1",
+                phase: el.getAttribute("data-wg-phase"),
+                step: el.getAttribute("data-wg-step"),
+                block: el.getAttribute("data-wg-block"),
+                collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+                opacity: st.opacity,
+                textLen: (el.textContent || "").trim().length,
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+                visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+            };
+        });
+    });
+}
+/**
+ * Hard gate: a blank / missing / opacity-0 modal fails.
+ * Use after demo/auto paints its first overlay.
+ */
+export async function assertWgOverlayReady(page, opts) {
+    const modal = opts?.modal ?? "panel";
+    const minText = opts?.minTextLen ?? 12;
+    const rows = await readWgOverlayBeacon(page);
+    const hit = rows.find((r) => r.modal === modal &&
+        r.ready &&
+        r.visible &&
+        r.textLen >= minText &&
+        (opts?.allowCollapsed || !r.collapsed || r.textLen >= minText));
+    if (!hit) {
+        throw new Error(`waygraph overlay NOT ready (modal=${modal}, minTextLen=${minText}). ` +
+            `beacons=${JSON.stringify(rows)}. ` +
+            `Do not claim stepper/modal works.`);
+    }
+    return hit;
+}

package/dist/step-overlay.d.ts

@@ -18,5 +18,20 @@ declare global {
         __wgHideRing?: () => void;
         __wgPendingNavClickLabel?: string;
         __wgWirePanelChrome?: (panel: HTMLElement, storageKey: string, chromeTitle?: string) => void;
+        __wgStampModal?: (el: Element, kind: string, meta?: Record<string, unknown>) => void;
+        __wgOverlayBeacon?: () => Array<{
+            id: string | null;
+            modal: string | null;
+            ready: boolean;
+            phase: string | null;
+            step: string | null;
+            block: string | null;
+            collapsed: boolean;
+            opacity: string;
+            textLen: number;
+            w: number;
+            h: number;
+            visible: boolean;
+        }>;
     }
 }

package/dist/step-overlay.js

@@ -146,6 +146,17 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             banner.innerHTML =
                 "<span class='wg-banner-tag'>waygraph auto</span><span>" + title + "</span>";
             document.documentElement.appendChild(banner);
+            banner.setAttribute("data-wg-ui", "1");
+            banner.setAttribute("data-wg-modal", "banner");
+            banner.setAttribute("data-wg-ready", "1");
+        }
+        else {
+            const existing = document.getElementById("wg-banner");
+            if (existing) {
+                existing.setAttribute("data-wg-ui", "1");
+                existing.setAttribute("data-wg-modal", "banner");
+                existing.setAttribute("data-wg-ready", "1");
+            }
         }
         if (showBanner && !document.title.startsWith("[waygraph] ")) {
             document.title = "[waygraph] " + document.title;

package/examples/saucedemo/package-lock.json

@@ -17,7 +17,7 @@
       }
     },
     "../..": {
-      "version": "0.12.24",
+      "version": "0.12.43",
       "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"

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

@@ -78,6 +78,22 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       });
     },
     stubAfter: (ctx) => {
+      // Fail branch lands on LoginPage with Epic sadface - do not ring the
+      // inventory shelf. Success (LoggedIn) hands off to shopFlow.
+      if (ctx.out && ctx.out.__state === "LoginPage") {
+        ctx.title("Login blocked");
+        ctx.todos(["Enter username", "Enter password", "Click Login"]);
+        ctx.todoIndex(2);
+        ctx.ring("error", {
+          selector: '[data-test="error"]',
+          label: "Login error banner",
+          tone: "danger",
+          focus: true,
+          color: "#f87171",
+          duration: true,
+        });
+        return;
+      }
       ctx.banner("Inventory");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(2);

package/examples/saucedemo/src/flows/viewer-blocked.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle, withSessionReset } from "waygraph";
+import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
 import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
@@ -16,10 +16,14 @@ const engine = new Engine();
 // genuinely fresh cookies/storage, or the previous user's session would
 // still be live and this login attempt wouldn't mean anything.
 //
-// submit-login now branches: observe sees no /inventory.html navigation,
-// resolve -> LoginPage, verify confirms the error banner - the flow completes
-// at LoginPage (not a thrown verify on a fake LoggedIn resolve).
-export const viewerBlockedFlow = withTitle(
-  withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
-  "Viewer: Blocked Login Attempt",
+// submit-login branches: observe sees no /inventory.html navigation,
+// resolve -> LoginPage, verify confirms the error banner. Demo still wraps
+// withExpectedFailure so step 9/9 shows stubOnError rings + amber
+// "expected outcome" panel (branching no longer throws).
+export const viewerBlockedFlow = withExpectedFailure(
+  withTitle(
+    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    "Viewer: Blocked Login Attempt",
+  ),
+  "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.41",
+  "version": "0.12.43",
   "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/methods/submit-login.method.block.ts

@@ -78,6 +78,22 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       });
     },
     stubAfter: (ctx) => {
+      // Fail branch lands on LoginPage with Epic sadface - do not ring the
+      // inventory shelf. Success (LoggedIn) hands off to shopFlow.
+      if (ctx.out && ctx.out.__state === "LoginPage") {
+        ctx.title("Login blocked");
+        ctx.todos(["Enter username", "Enter password", "Click Login"]);
+        ctx.todoIndex(2);
+        ctx.ring("error", {
+          selector: '[data-test="error"]',
+          label: "Login error banner",
+          tone: "danger",
+          focus: true,
+          color: "#f87171",
+          duration: true,
+        });
+        return;
+      }
       ctx.banner("Inventory");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(2);

package/templates/quickstart/src/flows/viewer-blocked.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle, withSessionReset } from "waygraph";
+import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
 import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
@@ -16,10 +16,14 @@ const engine = new Engine();
 // genuinely fresh cookies/storage, or the previous user's session would
 // still be live and this login attempt wouldn't mean anything.
 //
-// submit-login now branches: observe sees no /inventory.html navigation,
-// resolve -> LoginPage, verify confirms the error banner - the flow completes
-// at LoginPage (not a thrown verify on a fake LoggedIn resolve).
-export const viewerBlockedFlow = withTitle(
-  withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
-  "Viewer: Blocked Login Attempt",
+// submit-login branches: observe sees no /inventory.html navigation,
+// resolve -> LoginPage, verify confirms the error banner. Demo still wraps
+// withExpectedFailure so step 9/9 shows stubOnError rings + amber
+// "expected outcome" panel (branching no longer throws).
+export const viewerBlockedFlow = withExpectedFailure(
+  withTitle(
+    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    "Viewer: Blocked Login Attempt",
+  ),
+  "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
 );