waygraph 0.15.19 → 0.15.21

package/dist/auto-session.d.ts

@@ -31,8 +31,17 @@ export type ParsedPick = PickResult | {
 /**
  * Same number/`q`/range rules `cliPick` already applies, but returning a
  * result instead of looping to re-prompt - one request gets one answer.
+ * Also accepts a Block name (exact, case-sensitive) as a shorthand for its
+ * menu index - `send <id> "submit-login"` instead of hunting the number.
+ * Ambiguous (the same Block name appearing more than once in one menu)
+ * refuses rather than guessing which occurrence was meant - a pick runs a
+ * real browser action, not something to silently get wrong.
  */
-export declare function parsePick(raw: string, menuLength: number): ParsedPick;
+export declare function parsePick(raw: string, menu: {
+    readonly flat: readonly {
+        readonly block: string;
+    }[];
+}): ParsedPick;
 export interface DomSnapshot {
     mode: "aria" | "full";
     selector?: string;

package/dist/auto-session.js

@@ -37,18 +37,38 @@ export function buildSessionSnapshot(menu, library, here, lastRunNote) {
 /**
  * Same number/`q`/range rules `cliPick` already applies, but returning a
  * result instead of looping to re-prompt - one request gets one answer.
+ * Also accepts a Block name (exact, case-sensitive) as a shorthand for its
+ * menu index - `send <id> "submit-login"` instead of hunting the number.
+ * Ambiguous (the same Block name appearing more than once in one menu)
+ * refuses rather than guessing which occurrence was meant - a pick runs a
+ * real browser action, not something to silently get wrong.
  */
-export function parsePick(raw, menuLength) {
-    const ans = raw.trim().toLowerCase();
-    if (ans === "q" || ans === "quit")
+export function parsePick(raw, menu) {
+    const ans = raw.trim();
+    const lower = ans.toLowerCase();
+    if (lower === "q" || lower === "quit")
         return { type: "quit" };
-    const n = Number(ans);
-    if (Number.isInteger(n) && n >= 1 && n <= menuLength) {
+    const n = Number(lower);
+    if (Number.isInteger(n) && n >= 1 && n <= menu.flat.length) {
         return { type: "pick", index: n - 1 };
     }
+    const matches = [];
+    menu.flat.forEach((edge, i) => {
+        if (edge.block === ans)
+            matches.push(i);
+    });
+    if (matches.length === 1) {
+        return { type: "pick", index: matches[0] };
+    }
+    if (matches.length > 1) {
+        return {
+            type: "invalid",
+            reason: `"${raw}" matches ${matches.length} menu entries - use the numeric index instead of the Block name`,
+        };
+    }
     return {
         type: "invalid",
-        reason: `"${raw}" is not a valid pick - enter a number from 1 to ${menuLength}, or "q" to quit`,
+        reason: `"${raw}" is not a valid pick - enter a number from 1 to ${menu.flat.length}, a Block name, or "q" to quit`,
     };
 }
 const FULL_MODE_DEFAULT_DEPTH = 12;
@@ -499,7 +519,7 @@ export class AutoSession {
     /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
     async applyPick(raw) {
         const menu = await this.currentMenu();
-        const pick = parsePick(raw, menu.flat.length);
+        const pick = parsePick(raw, menu);
         if (pick.type === "invalid")
             return { ok: false, error: pick.reason };
         if (pick.type === "quit") {

package/dist/cli.js

@@ -31,6 +31,7 @@ import { runAgentDive, printSkillIndex, readSkillMarkdown, SKILL_FLAG_MAP, } fro
 import { runTraverse } from "./traverse-run.js";
 import { parseMinEdgeCoverage } from "./traverse-coverage.js";
 import { isFileSelectToken, parseBlocksSelect, } from "./blocks-select.js";
+import { parseHighlightShorthand } from "./highlight-shorthand.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -242,6 +243,7 @@ import {
   resolveDeviceState,
   resolveTodoDockUi,
   WAYGRAPH_RING_CSS,
+  getMemStub,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -341,7 +343,7 @@ function parseChainSpec(spec) {
     });
 }
 
-function seedMemFromRequires(mem, requires, json, label) {
+function seedMemFromRequires(mem, requires, json, label, stubActive) {
   if (requires.length === 0) {
     if (json !== undefined) {
       throw new Error(
@@ -353,21 +355,34 @@ function seedMemFromRequires(mem, requires, json, label) {
   if (json === undefined) {
     // --data / WAYGRAPH_DATA supplies the same payload shape as blockName({...}).
     const fromEnv = process.env.WAYGRAPH_DATA;
-    if (fromEnv && fromEnv.trim()) {
-      json = fromEnv;
-    } else {
+    if (fromEnv && fromEnv.trim()) json = fromEnv;
+  }
+
+  let parsed;
+  let haveParsed = false;
+  if (json !== undefined) {
+    try {
+      parsed = JSON.parse(json);
+      haveParsed = true;
+    } catch (err) {
+      throw new Error("waygraph chain: \\"" + label + "\\" payload is not valid JSON - " + String(err));
+    }
+  }
+
+  if (!haveParsed) {
+    // No payload at all - only a hard failure when memStub isn't active for
+    // this flow; when it is, fall through with an empty object so the
+    // per-key loop below gets a chance to fill each one from the registry.
+    if (!stubActive) {
       throw new Error(
         "waygraph chain: \\"" + label + "\\" requires " + requires.map((k) => k.name).join(", ") +
-          " - give a JSON payload (inline blockName({...}) or --data '{...}')",
+          " - give a JSON payload (inline blockName({...}) or --data '{...}'), or enable --mem-stub" +
+          " with registerMemStub for these keys",
       );
     }
+    parsed = {};
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(json);
-  } catch (err) {
-    throw new Error("waygraph chain: \\"" + label + "\\" payload is not valid JSON - " + String(err));
-  }
+
   // Keyed-by-name when every require name is a top-level key (preferred for
   // --data and for {"saucedemo.credentials":{...}} even with one require).
   if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
@@ -377,26 +392,42 @@ function seedMemFromRequires(mem, requires, json, label) {
       return;
     }
   }
-  if (requires.length === 1) {
+  // Single-key shorthand: the whole payload IS that one key's value - only
+  // when a real payload was actually given (the stub-only "{}" fallback
+  // above must fall through to per-key stub resolution instead).
+  if (haveParsed && requires.length === 1) {
     mem.set(requires[0], parsed);
     return;
   }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+  if (haveParsed && (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))) {
     throw new Error(
       "waygraph chain: \\"" + label + "\\" requires " + requires.length + " keys (" +
         requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name",
     );
   }
+  const stillMissing = [];
   for (const k of requires) {
-    if (!(k.name in parsed)) {
-      throw new Error("waygraph chain: \\"" + label + "\\" payload is missing required key \\"" + k.name + "\\"");
+    if (k.name in parsed) {
+      mem.set(k, parsed[k.name]);
+      continue;
+    }
+    const fake = stubActive ? getMemStub(k) : undefined;
+    if (fake) {
+      mem.set(k, fake());
+      continue;
     }
-    mem.set(k, parsed[k.name]);
+    stillMissing.push(k);
+  }
+  if (stillMissing.length > 0) {
+    throw new Error(
+      "waygraph chain: \\"" + label + "\\" payload is missing required key(s): " +
+        stillMissing.map((k) => "\\"" + k.name + "\\"").join(", "),
+    );
   }
 }
 
-function seedMemForBlock(mem, resolved, json) {
-  seedMemFromRequires(mem, resolved.block.requires ?? [], json, resolved.exportName);
+function seedMemForBlock(mem, resolved, json, stubActive) {
+  seedMemFromRequires(mem, resolved.block.requires ?? [], json, resolved.exportName, stubActive);
 }
 
 /**
@@ -406,14 +437,14 @@ function seedMemForBlock(mem, resolved, json) {
  * name) and seeds them all from one JSON payload, same keyed-by-name shape
  * as a multi-key Block payload already uses.
  */
-function seedMemForFlow(mem, flowBlocks, json, label) {
+function seedMemForFlow(mem, flowBlocks, json, label, stubActive) {
   const seen = new Map();
   for (const bi of flowBlocks) {
     for (const k of bi.block.requires ?? []) {
       if (!seen.has(k.name)) seen.set(k.name, k);
     }
   }
-  seedMemFromRequires(mem, Array.from(seen.values()), json, label);
+  seedMemFromRequires(mem, Array.from(seen.values()), json, label, stubActive);
 }
 
 // ---------------------------------------------------------------------------
@@ -5898,7 +5929,8 @@ async function main() {
       // Same --data / WAYGRAPH_DATA seeding as the multi-segment path.
       // Without this, \`waygraph run shop.flow.ts --data '{...}'\` (and bare
       // export names) hit preflight with an empty MemPage.
-      const seedMem = () => seedMemForFlow(mem, blockInfos, undefined, bareRef);
+      const stubActive = flow.memStub === true || process.env.WAYGRAPH_MEM_STUB === "1";
+      const seedMem = () => seedMemForFlow(mem, blockInfos, undefined, bareRef, stubActive);
       resolved = blockInfos.map((bi, idx) => ({
         block: bi.block,
         exportName: bi.name,
@@ -5969,6 +6001,7 @@ async function main() {
       if (flow && typeof flow.blocks === "function") {
         flows.push(flow);
         episodeCounter += 1;
+        const stubActive = flow.memStub === true || process.env.WAYGRAPH_MEM_STUB === "1";
         flowMeta.push({
           episodeNumber: episodeCounter,
           episodeTitle: flow.title || seg.ref,
@@ -5976,18 +6009,21 @@ async function main() {
           highlightFixtures: flow.highlightFixtures,
           demoPace: flow.demoPace,
           highlightStyle: flow.highlightStyle,
-          seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref),
+          seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref, stubActive),
         });
       } else {
         const r = await findBlock(projectDir, seg.ref);
         flows.push(wrapEngine.defineFlow([start, r.block, end]));
+        // A bare Block segment (no Flow, no withMemStub to opt in) only gets
+        // memStub via the global --mem-stub/WAYGRAPH_MEM_STUB override.
+        const stubActive = process.env.WAYGRAPH_MEM_STUB === "1";
         flowMeta.push({
           episodeNumber: undefined,
           episodeTitle: undefined,
           highlightFixtures: undefined,
           demoPace: undefined,
           highlightStyle: undefined,
-          seedMem: () => seedMemForBlock(mem, r, seg.json),
+          seedMem: () => seedMemForBlock(mem, r, seg.json, stubActive),
         });
       }
     }
@@ -6889,6 +6925,9 @@ function parseRunFlags(argv) {
             out.data = t.value;
             i = t.nextI;
         }
+        else if (a === "--mem-stub") {
+            out.memStub = true;
+        }
         else if (a === "--video" || a.startsWith("--video=")) {
             if (a.startsWith("--video=")) {
                 out.video = a.slice("--video=".length);
@@ -7016,6 +7055,9 @@ function applyRunFlags(flags, opts) {
     if (flags.data !== undefined) {
         process.env.WAYGRAPH_DATA = flags.data;
     }
+    if (flags.memStub) {
+        process.env.WAYGRAPH_MEM_STUB = "1";
+    }
     if (flags.fast) {
         process.env.WAYGRAPH_DEMO_FAST = "1";
     }
@@ -7233,7 +7275,12 @@ Primary (less is more):
                  --cli --detach --non-headless  Detached session with a real visible browser
                                            (same --non-headless flag run/demo already use)
   waygraph auto send <sessionId> "<pick>"  Send one pick to a --detach session, print
-                                           the resulting state as JSON (no TTY needed)
+                                           the resulting state as JSON (no TTY needed).
+                                           <pick> is a 1-based menu index, a Block name
+                                           (exact match; ambiguous names refuse rather than
+                                           guess), or "q"/"quit". Same command as
+                                           browser send <sessionId> "<pick>" (prefer that
+                                           prefix for a --detach/persistent session).
                  --timeout <ms>            Override the 15s default wait for this one call -
                                            a single Block can legitimately run a slow real
                                            interaction (e.g. a multi-step mouse drag)
@@ -7297,6 +7344,15 @@ Primary (less is more):
                                            label,tone?,size?,weight?}], todos[], todoIndex?,
                                            todoTitle?, holdMs? (0=until next), clear:true.
                                            Missing selectors listed in response, not fatal.
+                                           Same command as browser highlight <sessionId>
+                                           '<json>' (prefer that prefix for a --detach/
+                                           persistent session).
+                 <selector>|<label>[|<tone>]   Shorthand for 1-3 rings, no JSON braces/quotes
+                                           to escape - rings separated by ";", e.g.
+                                           "#x|Login button|warning; .err|Error banner|danger".
+                                           Covers selector/label/tone only; anything else
+                                           (size/weight/zoom/focus/todos/...) needs the JSON
+                                           form above.
   waygraph browser                         Show browser subcommands
   waygraph browser start                   Open a new session (headful by default, about:blank)
                  --inject preset|path            Merge an external Block library (e.g. saucedemo)
@@ -7316,6 +7372,10 @@ Primary (less is more):
                                            layer; use browser/pilot for agent-driven sessions.
   waygraph demo  [--blocks <flow|file|spec>]  Watch with step overlay (QA path)
                  --data '{...}'            Mem seed JSON (or inline flow({...}))
+                 --mem-stub                Fill any requires key --data didn't cover from
+                                           registerMemStub's registry (needs the key
+                                           registered, or the flow's own withMemStub - a
+                                           key with neither still fails preflight)
                  --auto-next               Auto-advance steps (alias: --autoplay)
                  --fast                    Shorter auto-next / Next gates (keeps smooth cursor)
                  --full                    Classic wrap-all block chips (default: carousel)
@@ -7332,6 +7392,7 @@ Primary (less is more):
                  --title / --base-url
   waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)
                  --data '{...}'
+                 --mem-stub                Same as demo's --mem-stub
                  --non-headless            Show browser
                  --video [dir]             Record .webm
                  --video-viewport WxH       Recording size (default run: 1280x720)
@@ -7460,7 +7521,7 @@ async function main() {
                     "  waygraph run src/flows/shop.flow.ts\n" +
                     "  waygraph run --blocks shopFlow\n" +
                     "  waygraph list   # file → export map\n" +
-                    "  Flags: --blocks --data --non-headless --video [dir] --step/--no-step");
+                    "  Flags: --blocks --data --mem-stub --non-headless --video [dir] --step/--no-step");
                 process.exit(1);
             }
             const proj = flags.blocks
@@ -7779,7 +7840,7 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                 console.error("waygraph demo: missing flow/spec — e.g.\n" +
                     "  waygraph demo src/flows/shop.flow.ts\n" +
                     "  waygraph demo --blocks shopFlow\n" +
-                    "  Flags: --blocks --data --auto-next --fast --full --mini --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
+                    "  Flags: --blocks --data --mem-stub --auto-next --fast --full --mini --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
                 process.exit(1);
             }
             const proj = flags.blocks
@@ -8223,19 +8284,25 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                 if (sub === "highlight") {
                     const raw = args[3];
                     if (raw === undefined) {
-                        console.error('waygraph auto highlight: usage: waygraph auto highlight <sessionId> \'{"rings":[{"selector":"#x","label":"X"}]}\'');
+                        console.error(`waygraph ${command} highlight: usage:\n` +
+                            `  waygraph ${command} highlight <sessionId> '{"rings":[{"selector":"#x","label":"X"}]}'\n` +
+                            `  waygraph ${command} highlight <sessionId> "#x|X" (shorthand: <selector>|<label>[|<tone>], rings separated by ";")`);
                         process.exit(1);
                     }
                     let fixtures;
                     try {
                         fixtures = JSON.parse(raw);
                     }
-                    catch {
-                        console.error("waygraph auto highlight: body must be valid JSON");
-                        process.exit(1);
+                    catch (jsonErr) {
+                        const shorthand = parseHighlightShorthand(raw);
+                        if (shorthand.type === "error") {
+                            console.error(`waygraph ${command} highlight: body is neither valid JSON (${jsonErr instanceof Error ? jsonErr.message : String(jsonErr)}) nor valid shorthand (${shorthand.reason})`);
+                            process.exit(1);
+                        }
+                        fixtures = shorthand.fixtures;
                     }
                     if (fixtures.op !== undefined && fixtures.op !== "highlight") {
-                        console.error('waygraph auto highlight: do not set "op" (or set it to "highlight")');
+                        console.error(`waygraph ${command} highlight: do not set "op" (or set it to "highlight")`);
                         process.exit(1);
                     }
                     const { op: _ignore, ...rest } = fixtures;

package/dist/engine.d.ts

@@ -251,6 +251,15 @@ export interface Flow<Out extends Checkpoint<string>> {
      * Per-slot stub/fixture values win. `run()` ignores.
      */
     readonly highlightStyle?: import("./highlights.js").HighlightStyleDefaults;
+    /**
+     * Set once this Flow has been wrapped in {@link withMemStub} - opts into
+     * auto-filling `requires` keys with registered fake values
+     * (`registerMemStub`, `src/mem-stub.ts`) instead of failing preflight when
+     * the caller didn't supply them. `run()` never reads this - the CLI's own
+     * `--data`/`--mem-stub` seeding, or a bare-library caller's own explicit
+     * `seedMemStub(mem, flow)` call, is what actually fills mem before `run()`.
+     */
+    readonly memStub?: boolean;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -318,6 +327,17 @@ export declare function withSessionReset<Out extends Checkpoint<string>>(flow: F
  * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
  */
 export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
+/**
+ * Opts this Flow into memStub: `requires` keys the caller didn't supply get
+ * filled from `registerMemStub`'s registry (`src/mem-stub.ts`) instead of
+ * failing preflight, for any key that has a registered fake generator - a
+ * required key with no registration still fails exactly as before.
+ * Non-destructive, same pattern as {@link withTitle}. `run()` never reads
+ * this itself - the CLI's `--data`/`--mem-stub` seeding, or a bare-library
+ * caller's own explicit `seedMemStub(mem, flow)` call, does the filling.
+ * @example const demoLogin = withMemStub(loginFlow);
+ */
+export declare function withMemStub<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
 /**
  * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
  * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;

package/dist/engine.js

@@ -401,6 +401,24 @@ export function withTitle(flow, title) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
     };
 }
+/**
+ * Opts this Flow into memStub: `requires` keys the caller didn't supply get
+ * filled from `registerMemStub`'s registry (`src/mem-stub.ts`) instead of
+ * failing preflight, for any key that has a registered fake generator - a
+ * required key with no registration still fails exactly as before.
+ * Non-destructive, same pattern as {@link withTitle}. `run()` never reads
+ * this itself - the CLI's `--data`/`--mem-stub` seeding, or a bare-library
+ * caller's own explicit `seedMemStub(mem, flow)` call, does the filling.
+ * @example const demoLogin = withMemStub(loginFlow);
+ */
+export function withMemStub(flow) {
+    return {
+        ...flow,
+        memStub: true,
+        withBlockVerify: (block, verify) => withMemStub(flow.withBlockVerify(block, verify)),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withMemStub(flow.modBlockVerify(block, nameOrIndex, newCheck)),
+    };
+}
 /**
  * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
  * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;

package/dist/highlight-shorthand.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Compact alternative to full-JSON `browser highlight` payloads, for the
+ * common case (a couple of rings, each just selector + label + maybe tone).
+ * Full JSON stays fully supported for anything needing size/weight/zoom/
+ * focus/detail/tag/todos - this only ever covers a subset.
+ *
+ * Grammar: `<selector>|<label>[|<tone>]` rings joined by `;`.
+ *   "#submit|Login button|warning; .error|Error banner|danger"
+ *
+ * `;` and `|` were picked because neither is valid inside a CSS/Playwright
+ * selector or an ordinary label - unlike `,`/`:`, which real selectors use
+ * constantly (`:nth-child(2)`, `:not(.x)`, `[href*="mailto:"]`, compound
+ * `a, b` lists). A selector/label containing a literal `;` or `|` needs the
+ * full-JSON form instead - documented, not silently mishandled.
+ */
+import type { PilotHighlightFixtures } from "./pilot-overlay.js";
+export type ParsedHighlightShorthand = {
+    type: "ok";
+    fixtures: PilotHighlightFixtures;
+} | {
+    type: "error";
+    reason: string;
+};
+export declare function parseHighlightShorthand(raw: string): ParsedHighlightShorthand;

package/dist/highlight-shorthand.js

@@ -0,0 +1,30 @@
+export function parseHighlightShorthand(raw) {
+    const tokens = raw
+        .split(";")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        return { type: "error", reason: "empty highlight shorthand - give at least one <selector>|<label> ring" };
+    }
+    const rings = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        const parts = token.split("|").map((p) => p.trim());
+        if (parts.length < 2 || parts.length > 3) {
+            return {
+                type: "error",
+                reason: `ring ${i + 1} ("${token}") must be <selector>|<label> or <selector>|<label>|<tone> ` +
+                    `- got ${parts.length} part(s) separated by "|"`,
+            };
+        }
+        const [selector, label, tone] = parts;
+        if (!selector) {
+            return { type: "error", reason: `ring ${i + 1} ("${token}") has an empty selector` };
+        }
+        if (!label) {
+            return { type: "error", reason: `ring ${i + 1} ("${token}") has an empty label` };
+        }
+        rings.push(tone ? { selector, label, tone } : { selector, label });
+    }
+    return { type: "ok", fixtures: { rings } };
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInstanceOption } from "./types.js";
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
+export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";

package/dist/index.js

@@ -1,7 +1,8 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
+export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";

package/dist/mem-stub.d.ts

@@ -0,0 +1,41 @@
+/**
+ * memStub: a registry of caller-supplied FAKE VALUES for required MemKeys, so
+ * a Flow can run/demo without hand-seeding every credential/name/email every
+ * time. Bring your own generator (Faker.js or anything else) - waygraph takes
+ * no dependency on one, it only stores and invokes an opaque `() => T`.
+ *
+ * "Stub" here is unrelated to the other two meanings already in this
+ * codebase: `stubBefore`/`stubAfter`/`stubOnError` (demo narration fixtures,
+ * see highlights.ts's `runStubPhase`) and `upload`'s `stub: "image"|"pdf"|
+ * "video"` (a placeholder file). This is a third, separate "stub."
+ *
+ * Opt-in only, per Flow (`withMemStub`, engine.ts) or per-run (`--mem-stub` /
+ * WAYGRAPH_MEM_STUB=1) - a required key with no registered generator still
+ * fails preflight exactly as before. Registered per MemKey *instance*
+ * (identity, not `.name`), matching MemPage's own store - two keys sharing a
+ * debug name must never cross-contaminate here either.
+ */
+import type { MemKey } from "./mem-page.js";
+import type { MemPage } from "./mem-page.js";
+import type { Flow } from "./engine.js";
+/**
+ * Registers a fake-value generator for one required MemKey.
+ * @example registerMemStub(LoginCreds.key, () => ({
+ *   username: faker.internet.userName(),
+ *   password: faker.internet.password(),
+ * }));
+ */
+export declare function registerMemStub<T>(key: MemKey<T>, fake: () => T): void;
+/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub}/{@link withMemStub} instead. */
+export declare function getMemStub<T>(key: MemKey<T>): (() => T) | undefined;
+/**
+ * For a bare library `flow.run(mem, ...)` call outside the CLI (which has its
+ * own `--mem-stub`-aware seeding) - call this yourself before `run()` when
+ * `flow.memStub` is true, the same way external tooling already reads
+ * `flow.resetSession`/`flow.title`/etc. (`run()` itself never reads Flow
+ * flags - see the `with*` helpers in engine.ts).
+ * @example
+ * if (flow.memStub) seedMemStub(mem, flow);
+ * await flow.run(mem, config);
+ */
+export declare function seedMemStub(mem: MemPage, flow: Flow<any>): void;

package/dist/mem-stub.js

@@ -0,0 +1,36 @@
+const registry = new Map();
+/**
+ * Registers a fake-value generator for one required MemKey.
+ * @example registerMemStub(LoginCreds.key, () => ({
+ *   username: faker.internet.userName(),
+ *   password: faker.internet.password(),
+ * }));
+ */
+export function registerMemStub(key, fake) {
+    registry.set(key, fake);
+}
+/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub}/{@link withMemStub} instead. */
+export function getMemStub(key) {
+    return registry.get(key);
+}
+/**
+ * For a bare library `flow.run(mem, ...)` call outside the CLI (which has its
+ * own `--mem-stub`-aware seeding) - call this yourself before `run()` when
+ * `flow.memStub` is true, the same way external tooling already reads
+ * `flow.resetSession`/`flow.title`/etc. (`run()` itself never reads Flow
+ * flags - see the `with*` helpers in engine.ts).
+ * @example
+ * if (flow.memStub) seedMemStub(mem, flow);
+ * await flow.run(mem, config);
+ */
+export function seedMemStub(mem, flow) {
+    for (const bi of flow.blocks()) {
+        for (const k of bi.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            const fake = registry.get(k);
+            if (fake)
+                mem.set(k, fake());
+        }
+    }
+}

package/examples/saucedemo/.waygraph-auto/11c497cd.log

@@ -0,0 +1,44 @@
+waygraph auto: skip src/blocks/saucedemo-web/cart/nav-cart.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/cart/nav-checkout-info.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/ff-owner-auth.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory/inventory.page.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory/methods/add-all-to-cart.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory/methods/remove-all-from-cart.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory/methods/remove-from-cart.effect.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory/nav-item-detail.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory-item/nav-back-to-products.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/inventory-item/nav-continue-shopping.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/methods/fill-password.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/methods/fill-username.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/methods/submit-login.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/methods/submit-logout.method.block.ts: Requiring @playwright/test second time, 
+waygraph auto: skip src/blocks/saucedemo-web/nav-login.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/cart/nav-cart.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/cart/nav-checkout-info.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/ff-owner-auth.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory/inventory.page.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory/methods/add-all-to-cart.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory/methods/remove-all-from-cart.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory/methods/remove-from-cart.effect.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory/nav-item-detail.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory-item/nav-back-to-products.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/inventory-item/nav-continue-shopping.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/methods/fill-password.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/methods/fill-username.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/methods/submit-login.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/methods/submit-logout.method.block.ts: Requiring @playwright/test second time, 
+waygraph graph: skip src/blocks/saucedemo-web/nav-login.block.ts: Requiring @playwright/test second time,