waygraph 0.15.18 → 0.15.20

package/README.md

@@ -249,6 +249,40 @@ A Block's `requires: MemKey[]` gets checked by `preflight()` (built into `runGra
 before a tab even opens - a missing credential fails in milliseconds, not after several
 real browser actions already ran.
 
+### memStub - fake values for `requires`, opt-in per Flow
+
+Hand-supplying `--data '{...}'` every run gets old fast for a `requires` key that's
+genuinely arbitrary (a username, an email, a name) rather than something the run actually
+depends on. `registerMemStub(key, fake)` registers a generator for one `MemKey` (bring your
+own - Faker.js or anything else; waygraph takes no dependency on it); `withMemStub(flow)`
+opts that Flow into filling any `requires` key with no `--data` coverage from that registry
+instead of failing preflight. A key with no registration still fails exactly as before -
+this narrows the case that needs real input, it doesn't remove the guard:
+
+```typescript
+import { registerMemStub, withMemStub } from "waygraph";
+import { faker } from "@faker-js/faker";
+
+registerMemStub(LoginCreds.key, () => ({
+  username: faker.internet.userName(),
+  password: faker.internet.password(),
+}));
+
+export const demoLoginFlow = withMemStub(loginFlow);
+```
+```bash
+waygraph run demoLoginFlow                 # zero --data - fills from the registry
+waygraph run loginFlow --mem-stub          # same effect without a Flow-level wrapper -
+                                            # --mem-stub / WAYGRAPH_MEM_STUB=1 force it
+                                            # for one CLI call, opt-in or not
+```
+`--data` always wins for a key it actually covers - memStub only fills what's left over.
+Registered by `MemKey` *identity*, not by name (matching `MemPage`'s own store): two keys
+sharing a debug name never cross-contaminate. For a bare library `flow.run(mem)` call
+outside the CLI, call `seedMemStub(mem, flow)` yourself before `run()` when
+`flow.memStub` is true - `run()` never reads Flow flags itself, same as
+`resetSession`/`title`/every other `with*` wrapper.
+
 ### Engine config and pluggable browsers
 
 `new Engine({ headless, browserName, slowMo })` configures a browser the Engine launches
@@ -298,10 +332,26 @@ code, an autonomous agent authoring Blocks) - it warns, never fails the process.
 
 **`waygraph typecheck [project]`** runs `tsc --noEmit` then the same **bad-practice** scan
 (wildcard `Checkpoint<string>`, assert blocks missing type args, multi-`.fill()` Methods,
-fill+click in one Method). Practices warn only unless `tsc` fails; use `--no-practices` to
-skip the scan. Opt out per file: `// waygraph-ignore-practices` or
-`// waygraph-ignore: multi-input, combined-action`. Print full agent guidance:
-`waygraph --skill-convention`.
+fill+click in one Method, empty `verify` on a transition Block or `defineAssertBlock`).
+Practices warn only unless `tsc` fails; use `--no-practices` to skip the scan. Opt out per
+file: `// waygraph-ignore-practices` or `// waygraph-ignore: multi-input, combined-action,
+empty-verify`. Print full agent guidance: `waygraph --skill-convention`.
+
+**Empty verify is the one that matters most for codegen'd Blocks.** A framework can enforce
+that a check *exists* and stays structurally honest (typed, wired, right file) - it cannot
+author the semantic content of that check, since only someone who knows what "success" means
+for this specific app can write it. That's a correct place to draw the line, but it shifts
+all the risk onto whether anything catches a Block left with a placeholder `verify: []` by
+the time it ships - which would otherwise pass every static check, the orphan scan, and
+`tsc`, and run green in CI forever, because an empty array isn't a wrong check, it's the
+*absence* of one. `waygraph check`/`typecheck` now flag exactly that: a `defineMethodBlock`/
+`defineEffectBlock` whose `In`/`Out` Checkpoints actually differ (a real transition, not a
+self-loop like `fill-username`) with no `verify` key or a literal `verify: []`, and the same
+for `defineAssertBlock` (whose entire job is checking). Silence it deliberately, the same as
+any other practice warning, with `// waygraph-ignore: empty-verify` - e.g. when a downstream
+`defineAssertBlock` right after it in the `.flow.ts` is what actually confirms the transition
+(see `templates/scaffold`'s own `open-message.method.block.ts`, confirmed by
+`AssertEmailContentBlock` right after it, not by its own `verify`).
 
 ### Demo narration
 
@@ -998,25 +1048,22 @@ really a Nav/Page/Assert/Method from this package's own factories.
 |------|---------|
 | Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
 | Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
-| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx waygraph init my-app` |
 | Install coding-agent defs for diving an app into Blocks | `npx waygraph agent-dive --loop claude` (also `opencode` / `cursor` / `vscode`) |
 | Print a packaged agent skill to stdout | `npx waygraph --skill` (list) / `--skill-pilot` / `--skill-pilot-blind` / `--skill-convention` |
 | Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
-**Scaffold is not hidden inside waygraph alone** - the offline starter also ships as
-[`create-waygraph`](https://github.com/deviate-dv8/create-waygraph) on npm (same template
-as `waygraph init` since 0.7.5). Use whichever entry you already have:
-`npx create-waygraph my-app` when reading the GitHub Pages docs, or `npx waygraph init my-app`
-when the CLI is already installed. After either:
-
 ```bash
+npx waygraph init my-app
 cd my-app && npm install && npx playwright install chromium && npm test
 ```
 
 `try demo` is different: live saucedemo.com, step-through **Sign In -> Shop & Checkout ->
 blocked Viewer login**, then headless tests. Permanent full example:
-[`examples/saucedemo`](./examples/saucedemo). Offline empty scaffold: `init` /
-`create-waygraph`.
+[`examples/saucedemo`](./examples/saucedemo). Offline empty scaffold: `init`.
+
+**`create-waygraph` (npm) is deprecated** - it was the identical `init` template shipped as
+a second package for no real benefit. Use `npx waygraph init my-app` instead.
 
 ```bash
 # From this checkout, after npm run build:
@@ -1090,8 +1137,8 @@ suite - it forwards to the local `node_modules/.bin/playwright` (falling back to
 `npx playwright` if the project hasn't installed it locally yet), so `waygraph test` behaves
 exactly like `playwright test`, and anything after it (`--grep`, a spec path, `--headed`, …)
 passes straight through. `waygraph test ui` (or `waygraph test --ui`) launches Playwright's
-interactive UI Mode the same way. Scaffolded projects (`waygraph init`/`create-waygraph`)
-wire this up as `npm test` / `npm run test:ui`, and ship `trace: "retain-on-failure"` plus
+interactive UI Mode the same way. Scaffolded projects (`waygraph init`) wire this up as
+`npm test` / `npm run test:ui`, and ship `trace: "retain-on-failure"` plus
 the `html` reporter in `playwright.config.ts`, so a failing `waygraph test` already has a
 trace waiting - `waygraph test report` opens the HTML report, and
 `waygraph test show-trace <trace.zip>` opens one trace directly (both forward to Playwright's
@@ -1122,7 +1169,9 @@ Flows are files (0.10.5+):
 | Attach to existing session (graph only) | `waygraph pilot attach <sessionId>` |
 | Path-find | `waygraph auto --blocks LoginPage OrderComplete` |
 | Run `--cli` as a background session (legacy) | `waygraph auto --cli --detach` -> `{sessionId, socketPath}` |
-| Drive a detached session (no TTY) | `waygraph browser send <sessionId> "<pick>"` -> JSON state |
+| Drive a detached session (no TTY) | `waygraph browser send <sessionId> "<pick>"` -> JSON state (`<pick>` is a menu index or a Block name) |
+| Paint highlight rings (shorthand) | `waygraph browser highlight <sessionId> "#x\|Label\|tone; .y\|Label2"` |
+| Paint highlight rings (full JSON) | `waygraph browser highlight <sessionId> '{"rings":[{"selector":"#x","label":"X"}]}'` |
 | Read a detached session's state | `waygraph browser status <sessionId>` (no side effects) |
 | Reattach a terminal to a detached session | `waygraph browser attach <sessionId>` |
 | Read the live page (aria, small/default) | `waygraph auto dom <sessionId>` |
@@ -1161,7 +1210,8 @@ Long FR/AC checklists used to bury highlight rings. **Smart defaults are on:**
 
 Per-knob env also: `WAYGRAPH_TODO_COMPACT`, `WAYGRAPH_TODO_CAP` (default 5),
 `WAYGRAPH_TODO_EXPAND_CAP` (default 14). Author API: `ctx.todoDockUi({ ... })`.
-Pilot `auto highlight` accepts the same knobs as `todoUi` on the JSON body.
+`browser highlight` (same as `auto`/`pilot highlight` - identical command, see "auto vs
+browser vs pilot" above) accepts the same knobs as `todoUi` on the JSON body.
 
 Run `waygraph --help` (or any subcommand with no args) for the full flag reference kept
 in `src/cli.ts`'s own `usage()` - that's the source of truth for flags, this table is the
@@ -1321,7 +1371,7 @@ src/
   index.ts                           public barrel
 examples/saucedemo/         live Sauce Demo (Page + methods/ + Sel)
 templates/quickstart/       try demo / init template (mirrors sauce)
-templates/scaffold/         offline init/create-waygraph scaffold template
+templates/scaffold/         offline waygraph init scaffold template
 templates/agents/           waygraph agent-dive coding-agent definitions
 docs/                       GitHub Pages static HTML + docs/proposals/ RFCs
 openspec/                   spec-driven planning: specs/ (current), changes/ (in-flight),

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";