waygraph 0.12.42 → 0.12.44

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/highlights.d.ts

@@ -54,6 +54,11 @@ export type StubPhaseFixtures = {
     zoomOut?: boolean;
     /** Top demo banner title (the purple "waygraph demo" card). */
     title?: string;
+    /**
+     * Floating checklist dock side. `left` | `right`.
+     * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
+     */
+    todoPos?: "left" | "right";
 };
 /** One named highlight slot on a block (selector + caption). */
 export interface WaygraphHighlightStub extends FixtureDurationFields {
@@ -161,6 +166,11 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     title(text: string): void;
     /** Alias for {@link StubCtx.title}. */
     banner(text: string): void;
+    /**
+     * Floating checklist dock side (`left` | `right`). Authors control this in
+     * code; click / env / --todo-left|right are fallbacks.
+     */
+    todoPos(side: "left" | "right"): void;
     /** Batch-set rings + episode fixtures. */
     set(partial: {
         highlights?: HighlightStubPhase;
@@ -182,6 +192,7 @@ export type StubPhaseResult = {
     zoom?: number;
     zoomOut?: boolean;
     title?: string;
+    todoPos?: "left" | "right";
 };
 /**
  * One yap/slide in a multi-step demo caption sequence.
@@ -322,6 +333,8 @@ export type ResolvedHighlight = WaygraphHighlightStub;
  * Normalize checklist rows; apply todoIndex for sequential done/current.
  */
 export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number): WaygraphTodoItem[];
+/** Normalize checklist dock side. */
+export declare function normalizeTodoPos(raw: unknown): "left" | "right" | undefined;
 /**
  * Run an open stub lifecycle (preferred) or resolve a static slot map.
  * Returns rings + episode fixtures (todos / todoIndex / zoom).

package/dist/highlights.js

@@ -383,6 +383,17 @@ function mergeSlot(base, patch) {
         ...fx,
     };
 }
+/** Normalize checklist dock side. */
+export function normalizeTodoPos(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "left" || s === "l")
+        return "left";
+    if (s === "right" || s === "r")
+        return "right";
+    return undefined;
+}
 function createStubCtx(bag, opts) {
     return {
         out: opts.out,
@@ -412,6 +423,11 @@ function createStubCtx(bag, opts) {
         banner(text) {
             bag.title = String(text ?? "");
         },
+        todoPos(side) {
+            const p = normalizeTodoPos(side);
+            if (p)
+                bag.todoPos = p;
+        },
         set(partial) {
             if (partial.highlights)
                 bag.highlights = { ...partial.highlights };
@@ -426,6 +442,9 @@ function createStubCtx(bag, opts) {
                 bag.zoomOut = !!partial.zoomOut;
             if (partial.title !== undefined)
                 bag.title = String(partial.title ?? "");
+            const tp = normalizeTodoPos(partial.todoPos);
+            if (tp)
+                bag.todoPos = tp;
         },
     };
 }
@@ -565,6 +584,7 @@ export async function runStubPhase(block, phase, opts) {
         ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
         ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
+        ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
     };
 }
 /**

package/dist/index.d.ts

@@ -3,7 +3,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, 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, 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, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, } 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";
@@ -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

@@ -2,9 +2,10 @@ 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, 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, 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";
 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

@@ -1,7 +1,9 @@
 const RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
     "border:2.5px solid #7C3AED;border-radius:10px;box-shadow:0 0 0 4px rgba(124,58,237,.16);" +
-    "transition:opacity .3s ease,border-color .15s,box-shadow .15s;}" +
+    // Opacity only - tone color must snap (no gray/purple/yellow morph).
+    "transition:opacity .3s ease;}" +
     // Automation = gray; semantic tones for authored highlights.
+    "#wg-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}" +
     "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
     "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
     "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
@@ -9,7 +11,8 @@ const RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none
     "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}" +
     "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
     "white-space:nowrap;padding:4px 9px;border-radius:7px;background:#7C3AED;color:#fff;" +
-    "font:600 12px/1.2 system-ui,sans-serif;transition:opacity .3s ease,background .15s,color .15s;}" +
+    "font:600 12px/1.2 system-ui,sans-serif;transition:opacity .3s ease;}" +
+    "#wg-ring-label[data-tone=planned]{background:#7C3AED;color:#fff;}" +
     "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
     "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
     "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
@@ -146,6 +149,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.42",
+  "version": "0.12.44",
   "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.",
 );