waygraph 0.16.1 → 0.16.4

package/README.md

@@ -100,6 +100,7 @@ names) still works and is fine for small projects, but the Map is where the tool
 | See the whole graph | `waygraph graph` |
 | Lint your Blocks and folders | `waygraph check` / `waygraph typecheck` / `waygraph map` |
 | Open a persistent browser for an agent | `waygraph browser start` |
+| Read what the page shows, as JSON (beta: Read Blocks) | `waygraph pilot read <id> [path]` |
 | Highlight things on the live page | `waygraph browser highlight <id> "#login\|Login button\|warning"` |
 | Set up coding-agent skills | `waygraph agent-dive --loop claude` |
 
@@ -124,4 +125,15 @@ npm run typecheck && npm test        # unit + Playwright suites
 Working on waygraph: [`AGENTS.md`](./AGENTS.md) (the rules, how to verify) and
 [`src/ARCHITECTURE.md`](./src/ARCHITECTURE.md) (where the code starts).
 
+## Status: alpha
+
+> [!WARNING]
+> Waygraph is an alpha build. Its syntax may still change in major ways between releases, and a release can remove
+> API (each removal is listed in [what was removed](./docs/deprecated.md); `waygraph upgrade --codemod` converts most
+> of it). For now we recommend staying on 0.16.0:
+>
+> ```bash
+> npm install --save-exact waygraph@0.16.0
+> ```
+
 MIT

package/dist/analysis/practices-check.d.ts

@@ -1,4 +1,4 @@
-export type PracticeKind = "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
+export type PracticeKind = "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file" | "hand-written-ui";
 export interface PracticeWarning {
     kind: PracticeKind;
     file: string;

package/dist/analysis/practices-check.js

@@ -46,6 +46,15 @@ const XPATH_LOCATOR = /\.locator\(\s*["'`](?:xpath=)?\/\//;
  *  scoped to simple, single-token selectors (id/class/attr/tag) so this doesn't fire on the
  *  legitimate multi-part selectors `.sel.ts` files themselves are made of. */
 const INLINE_SIMPLE_SELECTOR = /(?:\.locator|\bclick|\burl)\s*[:(]\s*["'`](#|\.)[\w-]+["'`]/;
+/**
+ * Hand-written UI in a test project - real, recurring pattern: an LLM wanting a caption, a highlight or a banner builds
+ * its own DOM in the page or restyles / reaches into waygraph's overlay, instead of using `ctx.ui`. It changes the page
+ * under test and breaks whenever the overlay changes.
+ */
+const OVERLAY_INTERNALS = /\b__wg[A-Za-z]|["'`][^"'`\n]*(?:#wg-|\.wg-|wg-root)/;
+const DOM_BUILD = /\bdocument\.createElement\(|\.innerHTML\s*=|\binsertAdjacentHTML\(|\baddStyleTag\(|\.style\.cssText|\.style\.[a-zA-Z]+\s*=(?!=)/;
+/** Shared narration (`src/stubs/*.ts`) is checked for hand-written UI too, next to Block and flow files. */
+const STUB_FILE = /[\\/]stubs[\\/][^\\/]+\.ts$/;
 const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
 const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
 /** Whole-file opt-out: `// waygraph-ignore-practices` */
@@ -55,6 +64,13 @@ const IGNORE_KINDS = /waygraph-ignore:\s*([^\n*]+)/;
 function walkBlockAndFlowFiles(projectDir, walkDir) {
     return walkDir(projectDir, SCAN_GLOB);
 }
+function handWrittenUi(src) {
+    if (OVERLAY_INTERNALS.test(src))
+        return "reaches into waygraph's overlay (#wg-*, .wg-*, window.__wg*)";
+    if (DOM_BUILD.test(src))
+        return "builds or restyles page DOM (createElement / innerHTML / addStyleTag / .style)";
+    return undefined;
+}
 function ignoredKindsForFile(src) {
     if (IGNORE_ALL.test(src))
         return "all";
@@ -143,6 +159,9 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
                 });
             }
         }
+        const ui = isIgnored("hand-written-ui", ignore) ? undefined : handWrittenUi(src);
+        if (ui)
+            warnings.push(handWrittenUiWarning(rel, ui));
         if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
             warnings.push({
                 kind: "empty-verify",
@@ -152,8 +171,23 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
             });
         }
     }
+    for (const file of walkDir(projectDir, /\.ts$/).filter((f) => STUB_FILE.test(f) && !SCAN_GLOB.test(f))) {
+        const src = readFileSync(file, "utf-8");
+        const ui = isIgnored("hand-written-ui", ignoredKindsForFile(src)) ? undefined : handWrittenUi(src);
+        if (ui)
+            warnings.push(handWrittenUiWarning(relative(projectDir, file).replace(/\\/g, "/"), ui));
+    }
     return warnings;
 }
+function handWrittenUiWarning(file, what) {
+    return {
+        kind: "hand-written-ui",
+        file,
+        detail: `${what} - narration goes through ctx.ui (ring, caption, title, todos, slides, device, zoom, network tab), ` +
+            "and a test never changes the page it tests. Missing something in ctx.ui? Ask for it in waygraph instead of " +
+            "overriding; opt out with // waygraph-ignore: hand-written-ui",
+    };
+}
 export function practiceKindLabel(kind) {
     switch (kind) {
         case "multi-input":
@@ -166,6 +200,8 @@ export function practiceKindLabel(kind) {
             return "regex/XPath selector where a plain one would do";
         case "inline-selector-should-use-sel-file":
             return "inline selector — a _sel.ts/*.sel.ts file already exists here";
+        case "hand-written-ui":
+            return "hand-written UI — use ctx.ui, don't build or override the overlay";
         default: {
             const _exhaustive = kind;
             return _exhaustive;

package/dist/beta.d.ts

@@ -0,0 +1,6 @@
+export { reads, ReadKey } from "./engine/read/read-key.js";
+export type { ReadNamespace, ReadSpec, ReadFieldsOf } from "./engine/read/read-key.js";
+export type { Reader, ReadCtx, RowCtx } from "./engine/read/readers.js";
+export { ReadPage } from "./engine/read/read-page.js";
+export { defineReadBlock, readCheckpoint } from "./engine/read/read-block.js";
+export type { ReadBlock, ReadBlockOptions, CheckpointRead } from "./engine/read/read-block.js";

package/dist/beta.js

@@ -0,0 +1,5 @@
+// The `waygraph/beta` entry: features whose shape may still change before they move into `waygraph`. Import them from
+// "waygraph/beta"; a beta release can rename or reshape them.
+export { reads, ReadKey } from "./engine/read/read-key.js";
+export { ReadPage } from "./engine/read/read-page.js";
+export { defineReadBlock, readCheckpoint } from "./engine/read/read-block.js";

package/dist/cli/commands/codemod-flows.js

@@ -103,7 +103,7 @@ function indentOf(node) {
     return " ".repeat(statement.getIndentationLevel() * 2);
 }
 function titleStub(block, title, indent) {
-    return `${block}.stubBefore((ctx) => {\n${indent}    ctx.title(${title});\n${indent}  })`;
+    return `${block}.stubBefore((ctx) => {\n${indent}    ctx.ui.title(${title});\n${indent}  })`;
 }
 function chain(head, steps, indent) {
     return [head, ...steps, ".end()"].join(`\n${indent}  `);
@@ -172,7 +172,7 @@ function rewrite(call, kindOf, needsMap) {
         if (name === "withTitle") {
             const first = mapCall && firstStepOf(mapCall);
             if (!first)
-                return `withTitle(${flow.getText().split("\n")[0]}, …): name the flow with ctx.title(…) in a stub on its first step`;
+                return `withTitle(${flow.getText().split("\n")[0]}, …): name the flow with ctx.ui.title(…) in a stub on its first step`;
             addTitle(first, args[1].getText());
         }
         else if (mapCall) {

package/dist/cli/commands/codemod-stubs.js

@@ -4,7 +4,10 @@
 // aliases (`banner`, `bannerPos`, `clearDevice`, `clearTodos`, `landscape`, `portrait`, `todoDockFull`) become the
 // names they stood for. A stub written as a slot map (`{ email: { selector, label } }`) becomes a function of
 // `ctx.ring` calls, and a stub set in a `define*Block({ ... })` (options or instruction) moves out to a chained
-// `.stubBefore(...)` on the Block. Works on the TypeScript AST (ts-morph).
+// `.stubBefore(...)` on the Block; a Block's `slides` become `ctx.slides(...)` in its chained `.stubAfter(...)`;
+// `ctx.highlights({ a: ring })` becomes one `ctx.ring("a", ring)` per ring; `narrate(locator, caption, action)` in an
+// `act` becomes the action, reported so the caption can move to a stubBefore ring. Last, everything a stub paints moves
+// under `ctx.ui` (`ctx.ring(...)` -> `ctx.ui.ring(...)`). Works on the TypeScript AST (ts-morph).
 import { Node, SyntaxKind } from "ts-morph";
 const RENAMED = {
     banner: (a) => `title(${a.join(", ")})`,
@@ -127,7 +130,7 @@ function convertSlotMaps(sf) {
     }
     return changed;
 }
-/** `defineXBlock({ ..., stubBefore: fn })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn)`. */
+/** `defineXBlock({ ..., stubBefore: fn, slides })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn).stubAfter(slides)`. */
 function hoistDefinitionStubs(sf) {
     let changed = false;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
@@ -141,9 +144,17 @@ function hoistDefinitionStubs(sf) {
         if (Node.isPropertyAssignment(instruction) && Node.isObjectLiteralExpression(instruction.getInitializer()))
             holders.push(instruction.getInitializer());
         const chained = [];
+        let slides;
         for (const holder of holders) {
             for (const prop of holder.getProperties()) {
                 const name = Node.isPropertyAssignment(prop) || Node.isMethodDeclaration(prop) ? prop.getName() : "";
+                if (name === "slides" && Node.isPropertyAssignment(prop)) {
+                    const init = prop.getInitializerOrThrow();
+                    // `slides: (out) => [...]` read the Checkpoint the step reached; in stubAfter that is ctx.out.
+                    slides = Node.isArrowFunction(init) || Node.isFunctionExpression(init) ? `(${init.getText()})(ctx.out!)` : init.getText();
+                    prop.remove();
+                    continue;
+                }
                 if (!PHASES.has(name))
                     continue;
                 let fn;
@@ -157,6 +168,15 @@ function hoistDefinitionStubs(sf) {
                 prop.remove();
             }
         }
+        if (slides !== undefined) {
+            const after = chained.findIndex((c) => c.startsWith(".stubAfter("));
+            if (after < 0)
+                chained.push(`.stubAfter((ctx) => ctx.slides(${slides}))`);
+            else {
+                const fn = chained[after].slice(".stubAfter(".length, -1);
+                chained[after] = `.stubAfter(async (ctx) => {\n  await (${fn})(ctx);\n  ctx.slides(${slides});\n})`;
+            }
+        }
         if (chained.length) {
             call.replaceWithText(call.getText() + chained.join(""));
             changed = true;
@@ -164,6 +184,110 @@ function hoistDefinitionStubs(sf) {
     }
     return changed;
 }
+/** `ctx.highlights({ a: ring, b: ring })` -> `ctx.ring("a", ring); ctx.ring("b", ring);`, one call at a time. */
+function convertHighlights(sf, problems) {
+    let changed = false;
+    const skipped = new Set();
+    for (;;) {
+        // Raw text replacement forgets the file's nodes, so look the next call up again each time.
+        const statement = sf.getDescendantsOfKind(SyntaxKind.ExpressionStatement).find((st) => {
+            const c = ctxCall(st);
+            return c && c.method === "highlights" && !skipped.has(st.getStart()) && isStubCtx(c.call, c.receiver);
+        });
+        if (!statement)
+            return changed;
+        const c = ctxCall(statement);
+        const map = c.call.getArguments()[0];
+        if (!Node.isObjectLiteralExpression(map)) {
+            problems.push({ line: c.call.getStartLineNumber(), reason: "ctx.highlights(...) was removed and its argument is not an object literal: call ctx.ring(id, ring) for each ring" });
+            skipped.add(statement.getStart());
+            continue;
+        }
+        // Each ring keeps its own lines, moved to the statement's indent (replaceWithText would re-indent them).
+        const column = (n) => n.getStart() - n.getStartLinePos();
+        const indent = " ".repeat(column(statement));
+        const rings = map.getProperties().flatMap((p) => {
+            if (!Node.isPropertyAssignment(p))
+                return [];
+            const from = column(p);
+            const value = p.getInitializerOrThrow().getText().split("\n").map((l, n) => (n === 0 ? l : indent + l.slice(Math.min(from, l.search(/\S|$/))))).join("\n");
+            return [`${c.receiver}.ring(${JSON.stringify(p.getName().replace(/^["']|["']$/g, ""))}, ${value});`];
+        });
+        sf.replaceText([statement.getStart(), statement.getEnd()], rings.join("\n" + indent));
+        changed = true;
+    }
+}
+/**
+ * `narrate(locator, caption, () => action)` in an `act` -> just the action. The caption was narration inside the
+ * Block; it belongs in a `stubBefore` ring where the flow uses the Block, which the codemod can't place, so it is
+ * reported.
+ */
+function unwrapNarrate(sf, problems) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten() || call.getExpression().getText() !== "narrate" || call.getArguments().length !== 3)
+            continue;
+        const [, captionNode, action] = call.getArguments();
+        const caption = captionNode.getText();
+        const line = call.getStartLineNumber();
+        let body = `(${action.getText()})()`;
+        if (Node.isArrowFunction(action) && !Node.isBlock(action.getBody()))
+            body = action.getBody().getText();
+        call.replaceWithText(body);
+        problems.push({ line, reason: `narrate(...) was removed; its caption ${caption} is gone: ring the element in a stubBefore where the flow uses this Block` });
+        changed = true;
+    }
+    if (changed) {
+        for (const decl of sf.getImportDeclarations()) {
+            const spec = decl.getNamedImports().find((n) => n.getName() === "narrate");
+            if (!spec)
+                continue;
+            spec.remove();
+            if (decl.getNamedImports().length === 0 && !decl.getDefaultImport() && !decl.getNamespaceImport())
+                decl.remove();
+        }
+    }
+    return changed;
+}
+/** Everything a stub paints, which 0.16.3 moved under `ctx.ui`. */
+const UI_METHODS = new Set(["ring", "todos", "todoIndex", "todoGroups", "hideTodos", "device", "viewport", "touch", "orientation", "hideDevice", "zoom", "zoomOut", "title", "titlePos", "bannerUi", "caption", "hideCaption", "slides", "hideBanner", "showNetworkTab", "hideNetworkTab", "todoDockUi"]);
+/** Whether `name` at `node` is a stub's ctx: the nearest enclosing function with a parameter of that name is a stub. */
+function isStubCtxName(node, name) {
+    for (const fn of node.getAncestors()) {
+        if (!(Node.isArrowFunction(fn) || Node.isFunctionExpression(fn) || Node.isFunctionDeclaration(fn) || Node.isMethodDeclaration(fn)))
+            continue;
+        const param = fn.getParameters().find((p) => p.getName() === name);
+        if (!param)
+            continue;
+        if (/StubCtx/.test(param.getType().getText(param)))
+            return true;
+        const parent = fn.getParent();
+        const callee = Node.isCallExpression(parent) ? parent.getExpression() : undefined;
+        if (Node.isPropertyAccessExpression(callee) && /^stub(Before|After|OnError)$/.test(callee.getName()))
+            return true;
+        if (Node.isPropertyAssignment(parent) && /^stub(Before|After|OnError)$/.test(parent.getName()))
+            return true;
+        // `((ctx) => ...)(ctx)`, as the slides merge writes it: called at once with an outer stub's ctx.
+        const call = Node.isParenthesizedExpression(parent) ? parent.getParent() : undefined;
+        const arg = Node.isCallExpression(call) ? call.getArguments()[0] : undefined;
+        return arg !== undefined && Node.isIdentifier(arg) && isStubCtxName(call, arg.getText());
+    }
+    return false;
+}
+/** `ctx.ring(...)` -> `ctx.ui.ring(...)`, everywhere a stub's ctx paints (idempotent: `ctx.ui.ring` is left alone). */
+function moveToUi(sf) {
+    let changed = false;
+    for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression).reverse()) {
+        if (access.wasForgotten() || !UI_METHODS.has(access.getName()))
+            continue;
+        const receiver = access.getExpression();
+        if (!Node.isIdentifier(receiver) || !isStubCtxName(access, receiver.getText()))
+            continue;
+        access.replaceWithText(`${receiver.getText()}.ui.${access.getName()}`);
+        changed = true;
+    }
+    return changed;
+}
 /** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
 export function convertStubs(project) {
     const changed = [];
@@ -171,6 +295,10 @@ export function convertStubs(project) {
     for (const sf of project.getSourceFiles()) {
         const left = [];
         let touched = hoistDefinitionStubs(sf);
+        if (unwrapNarrate(sf, left))
+            touched = true;
+        if (convertHighlights(sf, left))
+            touched = true;
         if (convertSlotMaps(sf))
             touched = true;
         for (const block of sf.getDescendantsOfKind(SyntaxKind.Block).reverse()) {
@@ -179,6 +307,8 @@ export function convertStubs(project) {
             if (convertStatements(block.getStatements(), left))
                 touched = true;
         }
+        if (moveToUi(sf))
+            touched = true;
         if (touched)
             changed.push(sf);
         problems.push(...left.map((p) => ({ file: sf.getFilePath(), ...p })));

package/dist/cli/commands/pilot.js

@@ -9,6 +9,7 @@ import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
 import { parseCommand } from "../args.js";
 import { applyRunFlags, parseRunFlags } from "../flags.js";
 import { printBrowserSessionsList } from "../usage.js";
+import { isSessionOp } from "./session-ops.js";
 /** Runs a `pilot` subcommand; false when it is a session op for session-ops.ts. */
 export async function pilotCase(args) {
     if (args[1] === "sessions") {
@@ -76,26 +77,12 @@ export async function pilotCase(args) {
         }
         return true;
     }
-    if (args[1] !== "send" &&
-        args[1] !== "status" &&
-        args[1] !== "dom" &&
-        args[1] !== "trace" &&
-        args[1] !== "console" &&
-        args[1] !== "storage" &&
-        args[1] !== "upload" &&
-        args[1] !== "click" &&
-        args[1] !== "type" &&
-        args[1] !== "press" &&
-        args[1] !== "goto" &&
-        args[1] !== "reload" &&
-        args[1] !== "reach" &&
-        args[1] !== "resync" &&
-        args[1] !== "highlight") {
+    if (!isSessionOp("pilot", args[1])) {
         console.error("waygraph pilot: usage:\n" +
             "  waygraph pilot start [--inject …] [--goto <url>] [--headless] [--cli] [--base-url <url>] [project]\n" +
             "  waygraph pilot sessions [project]   # list live browser sessions\n" +
             "  waygraph pilot attach <sessionId>   # graph + snapshot for an existing session\n" +
-            "  waygraph pilot send|status|attach|highlight|… <sessionId> …  (controls browser — same as browser/auto)");
+            "  waygraph pilot send|status|read|attach|highlight|… <sessionId> …  (controls browser — same as browser/auto)");
         process.exit(1);
     }
     return false;

package/dist/cli/commands/session-ops.js

@@ -5,6 +5,8 @@ import { parseHighlightShorthand } from "../../demo/narration/shorthand.js";
 import { resolveSessionMeta } from "../../live/auto-session/files.js";
 import { requestSession, runAttachLoop } from "../../live/auto-session/ipc.js";
 import { parseCommand } from "../args.js";
+import { subscribeSession } from "../../live/auto-session/feed.js";
+import { SESSION_OPS } from "../../live/auto-session/protocol.js";
 const SEND_OPTIONS = {
     timeout: { type: "string", value: "<ms>", help: "How long one Block may run (default 15000)" },
 };
@@ -13,7 +15,8 @@ const DOM_OPTIONS = {
     selector: { type: "string", value: "<css>", help: "Only this element's subtree" },
     depth: { type: "string", value: "N", help: "Levels to read" },
 };
-const OPS = new Set(["send", "status", "attach", "dom", "trace", "console", "storage", "upload", "click", "type", "press", "goto", "reload", "reach", "resync", "highlight"]);
+/** The protocol's ops, as CLI subcommands: `subscribe` is `watch`; `attach` is the CLI's own interactive loop. */
+const OPS = new Set([...SESSION_OPS.filter((op) => op !== "subscribe"), "watch", "attach"]);
 /** Whether `sub` is a session op (`attach` is pilot's own subcommand, not an op, under `pilot`). */
 export function isSessionOp(command, sub) {
     return sub !== undefined && OPS.has(sub) && !(sub === "attach" && command === "pilot");
@@ -113,6 +116,28 @@ export async function sessionOpCase(args, command) {
             process.exitCode = 1;
         return;
     }
+    if (sub === "hello") {
+        const res = await requestSession(proj, sessionId, { op: "hello" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "watch") {
+        // One JSON line per run event (steps, reads) and per new snapshot, until Ctrl-C or the session ends.
+        const feed = await subscribeSession(proj, sessionId, (message) => console.log(JSON.stringify(message)));
+        process.once("SIGINT", () => feed.close());
+        await feed.closed;
+        return;
+    }
+    if (sub === "read") {
+        const path = args[3];
+        const res = await requestSession(proj, sessionId, path ? { op: "read", path } : { op: "read" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (sub === "storage") {
         const res = await requestSession(proj, sessionId, { op: "storage" });
         console.log(JSON.stringify(res));

package/dist/cli/flags.d.ts

@@ -110,7 +110,7 @@ export declare const RUN_OPTIONS: {
     };
     readonly "todo-left": {
         readonly type: "boolean";
-        readonly help: "Floating checklist dock on the left (also ctx.todos(id, items, { pos }))";
+        readonly help: "Floating checklist dock on the left (also ctx.ui.todos(id, items, { pos }))";
         readonly for: readonly ["demo"];
     };
     readonly "todo-right": {

package/dist/cli/flags.js

@@ -18,7 +18,7 @@ export const RUN_OPTIONS = {
     "fast": { type: "boolean", help: "Shorter auto-next / Next gates (keeps the smooth cursor)", for: ["demo"] },
     "full": { type: "boolean", help: "Classic wrap-all block chips (default: carousel)", for: ["demo"] },
     "mini": { type: "boolean", help: "Force the compact mini panel (Hide pill + Next)", for: ["demo"] },
-    "todo-left": { type: "boolean", help: "Floating checklist dock on the left (also ctx.todos(id, items, { pos }))", for: ["demo"] },
+    "todo-left": { type: "boolean", help: "Floating checklist dock on the left (also ctx.ui.todos(id, items, { pos }))", for: ["demo"] },
     "todo-right": { type: "boolean", help: "Floating checklist dock on the right", for: ["demo"] },
     "todo-full": { type: "boolean", help: "Full checklist: no compact / collision / behind-ring", for: ["demo"] },
     "todo-smart": { type: "boolean", help: "Compact + collision + behind-ring (the default)", for: ["demo"] },

package/dist/cli/run-chain.js

@@ -92,12 +92,12 @@ export async function runChainAuto(projectDir, fromTag, toTag) {
     const graph = await discoverGraph(projectDir);
     const path = findBlockPath(graph, fromTag, toTag);
     if (!path) {
-        console.error(`waygraph chain auto: no Block path from "${fromTag}" to "${toTag}" in the discovered graph`);
+        console.error(`waygraph auto --blocks: no Block path from "${fromTag}" to "${toTag}" in the discovered graph`);
         process.exitCode = 1;
         return;
     }
     const spec = path.join(" then ");
-    console.error(`waygraph chain auto: ${fromTag} -> ${toTag} via ${spec}`);
+    console.error(`waygraph auto --blocks: ${fromTag} -> ${toTag} via ${spec}`);
     if (!envString("WAYGRAPH_BASE_URL")) {
         const resolved = await resolveBaseUrl(projectDir);
         if (resolved)

package/dist/cli/usage.js

@@ -66,6 +66,12 @@ Primary (less is more):
                                            does nothing observable in the DOM) that inspectDom
                                            alone can't explain, since it only reads what actually
                                            rendered, not what the page/network actually said
+  waygraph auto watch <sessionId>          Live feed, one JSON line each: every run event (steps,
+                                           step:read) and the snapshot after each change. Ctrl-C ends
+  waygraph auto hello <sessionId>          The session protocol version, waygraph version, where it is
+  waygraph auto read <sessionId> [path]    (beta) What the page shows, as JSON, from the project's
+                                           Read Blocks (*.read.block.ts); [path] narrows it, e.g.
+                                           post.comments. Read it before reaching for dom
   waygraph auto storage <sessionId>        Read localStorage/sessionStorage plus registered
                                            service workers (scope/active URL/state) - client-
                                            side state (push-subscription/auth tokens etc.) that

package/dist/cli/util.js

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 // ---------------------------------------------------------------------------
 // `try` - a bundled, self-contained showcase. No .flow.ts to write, no
 // scenario to design - copies a small real Flow (nav/action Blocks, Trait
-// verify, narrate()) into the target project and runs it in step mode
+// verify, ctx stubs) into the target project and runs it in step mode
 // against a public demo site, so a curious dev sees the real overlay/panel
 // experience in under a minute, then gets pointed at the plain waygraph
 // source that produced it.

package/dist/demo/narration/demo-pace.d.ts

@@ -29,7 +29,7 @@ export declare function formatDemoPaceBadge(pace: DemoPace, baseAutoplayMs?: num
  */
 export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: number): string;
 /**
- * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * Resolve min dwell ms for any fixture (a stub ring or a yap slide),
  * or `null` when duration is unset (caller keeps its default timing).
  *
  * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`

package/dist/demo/narration/demo-pace.js

@@ -150,7 +150,7 @@ export function formatDemoPaceLabel(pace, baseAutoplayMs = 1800) {
     return `pace normal (1x, ~${gate}ms gates)`;
 }
 /**
- * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * Resolve min dwell ms for any fixture (a stub ring or a yap slide),
  * or `null` when duration is unset (caller keeps its default timing).
  *
  * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`

package/dist/demo/narration/merge.d.ts

@@ -4,7 +4,7 @@ import type { SomeBlock } from "../../engine/block/block.js";
 import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
 export declare function applyDefaultZoom(slots: ResolvedHighlight[], defaultZoom?: number): ResolvedHighlight[];
 export declare function applyDefaultZoomOut(slots: ResolvedHighlight[], defaultZoomOut?: boolean): ResolvedHighlight[];
-/** A stub phase's slot map as an ordered list of resolved highlights. */
+/** A stub phase's rings (by id, as ctx.ring set them) as an ordered list of resolved highlights. */
 export declare function resolvePhaseMap(phaseMap: HighlightStubPhase): ResolvedHighlight[];
 /** The stub a Block's flow chained for this phase, if any. */
 export declare function readStubRaw(block: SomeBlock, phase: HighlightStubPhaseName): StubLifecycleFn<Checkpoint<string>> | undefined;

package/dist/demo/narration/merge.js

@@ -40,7 +40,7 @@ export function applyDefaultZoomOut(slots, defaultZoomOut) {
         return slots;
     return slots.map((h) => h.zoomOut !== undefined ? h : { ...h, zoomOut: defaultZoomOut });
 }
-/** A stub phase's slot map as an ordered list of resolved highlights. */
+/** A stub phase's rings (by id, as ctx.ring set them) as an ordered list of resolved highlights. */
 export function resolvePhaseMap(phaseMap) {
     const phaseKeys = Object.keys(phaseMap);
     const allNumeric = phaseKeys.length > 0 && phaseKeys.every((k) => Number.isFinite(Number(k)) && String(Number(k)) === k);

package/dist/demo/narration/narration.d.ts

@@ -1,10 +1,10 @@
 import type { HighlightStubPhaseName, StubPhaseResult } from "../../engine/stub/stub.js";
-import type { ResolvedHighlight, WaygraphSlide } from "../../engine/stub/ring.js";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
 import type { SomeBlock } from "../../engine/block/block.js";
 import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
 import type { MemPage } from "../../engine/mem/mem.js";
 /**
- * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Runs a Block's stub for one phase and returns what it painted.
  * Returns rings + episode fixtures (todos / todoIndex / zoom).
  *
  * @example
@@ -23,10 +23,6 @@ export declare function runStubPhase(block: SomeBlock, phase: HighlightStubPhase
 export declare function resolveHighlightSlots(block: SomeBlock, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
 }): ResolvedHighlight[];
-/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
-export declare function resolveSlides(block: SomeBlock, opts?: {
-    out?: Checkpoint<string>;
-}): WaygraphSlide[];
 /**
  * True when the block authored stubAfter (lifecycle fn or slots).
  * When true, demo should not use verify-trait fallback.

package/dist/demo/narration/narration.js

@@ -3,7 +3,7 @@ import { applyDefaultZoom, applyDefaultZoomOut, readStubRaw, resolvePhaseMap } f
 import { buildTodoDock, normalizeTodoStyle, normalizeTodos } from "./todo-dock.js";
 import { resolveDeviceState } from "./device.js";
 /**
- * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Runs a Block's stub for one phase and returns what it painted.
  * Returns rings + episode fixtures (todos / todoIndex / zoom).
  *
  * @example
@@ -27,6 +27,9 @@ export async function runStubPhase(block, phase, opts) {
             throw new Error(`${block.name}: its ${phase} stub threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
+    if (phase === "stubOnError" && bag.slides?.length) {
+        throw new Error(`${block.name}: its stubOnError stub set slides; slides play before or after a step (stubBefore / stubAfter), not on its failure`);
+    }
     let highlights = applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
     highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
     const todoDock = bag.hideTodos
@@ -95,6 +98,7 @@ export async function runStubPhase(block, phase, opts) {
         // Boolean, not string - "" isn't a state here, so a plain undefined-check (like zoom/title)
         // is enough; false is real ("author called hideNetworkTab()") and must still be forwarded.
         ...(bag.networkTabVisible !== undefined ? { networkTabVisible: bag.networkTabVisible } : {}),
+        slides: [...(bag.slides ?? [])],
         ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
         ...(bag.todoDockUi !== undefined ? { todoDockUi: bag.todoDockUi } : {}),
         ...(bag.todoParallel === true ? { todoParallel: true } : {}),
@@ -118,22 +122,6 @@ export function resolveHighlightSlots(block, phase, opts) {
     }
     return applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
 }
-/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
-export function resolveSlides(block, opts) {
-    const instr = block.instruction;
-    let raw = instr.slides;
-    if (typeof raw === "function") {
-        try {
-            raw = raw(opts?.out ?? { __state: "" });
-        }
-        catch {
-            raw = [];
-        }
-    }
-    if (!Array.isArray(raw))
-        return [];
-    return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
-}
 function stubPhaseLooksAuthored(block, phase) {
     return readStubRaw(block, phase) !== undefined;
 }