waygraph 0.16.0 → 0.16.2

package/dist/cli/commands/session.js

@@ -1,468 +1,27 @@
-import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
-import { printBrowserSessionsList, printBrowserUsage } from "../usage.js";
-import { applyRunFlags, looksLikeFlowFileRef, parseRunFlags } from "../flags.js";
-import { runChain } from "../run-chain.js";
-import { runChainAuto } from "../run-chain.js";
-import { resolve } from "node:path";
-import { browserStart } from "../../live/auto-session/start.js";
-import { listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../../live/auto-session/ipc.js";
+// `waygraph auto` / `graph` / `browser` / `pilot`: hands `browser` and `pilot` subcommands and session ops to their
+// files, then runs the interactive explore (or the graph print) for a project; `__auto-serve` is the session child.
 import { existsSync, statSync } from "node:fs";
-import { resolveInjectRoots } from "../../manifest/roots.js";
-import { requestSession, resolveSessionMeta, runAttachLoop, runAutoServeCommand } from "../../live/auto-session/ipc.js";
-import { pilotAttach, pilotStart } from "../../live/pilot/pilot.js";
-import { parseHighlightShorthand } from "../../demo/narration/shorthand.js";
-import { isFileSelectToken, parseBlocksSelect } from "../../manifest/select.js";
-import { runAutoExplore } from "../../live/auto/auto.js";
+import { resolve } from "node:path";
 import { discoverGraph, findOrphanBlocks, toMermaid } from "../../analysis/graph.js";
 import { envString, setEnv } from "../../engine/env.js";
-import { parseCommand } from "../args.js";
-const SEND_OPTIONS = {
-    timeout: { type: "string", value: "<ms>", help: "How long one Block may run (default 15000)" },
-};
-const DOM_OPTIONS = {
-    mode: { type: "string", value: "aria|full", help: "Accessibility tree (default) or the full DOM" },
-    selector: { type: "string", value: "<css>", help: "Only this element's subtree" },
-    depth: { type: "string", value: "N", help: "Levels to read" },
-};
+import { runAutoServeCommand } from "../../live/auto-session/ipc.js";
+import { runAutoExplore } from "../../live/auto/auto.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
+import { isFileSelectToken, parseBlocksSelect } from "../../manifest/select.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { applyRunFlags, looksLikeFlowFileRef, parseRunFlags } from "../flags.js";
+import { runChain, runChainAuto } from "../run-chain.js";
+import { browserCase } from "./browser.js";
+import { pilotCase } from "./pilot.js";
+import { isSessionOp, sessionOpCase } from "./session-ops.js";
 export async function sessionCase(args, command) {
-    if (command === "browser") {
-        const sub = args[1];
-        if (sub === "sessions") {
-            const { values, positionals: positional } = parseCommand("sessions", { json: { type: "boolean", help: "Machine-readable JSON" } }, args.slice(2));
-            const json = values.json === true;
-            const proj = resolve(positional[0] ?? process.cwd());
-            const sessions = listBrowserSessions(proj);
-            if (json) {
-                console.log(JSON.stringify(sessions, null, 2));
-            }
-            else {
-                printBrowserSessionsList(sessions, proj);
-            }
-            return;
-        }
-        if (sub === "stop") {
-            const proj = resolve(args[3] ?? process.cwd());
-            const target = args[2];
-            if (!target) {
-                console.error("waygraph browser stop: usage: waygraph browser stop <sessionId|--all> [project]");
-                process.exit(1);
-            }
-            if (target === "--all") {
-                const n = stopAllBrowserSessions(proj);
-                console.log(JSON.stringify({ stopped: n, projectDir: proj }));
-                return;
-            }
-            if (!stopBrowserSession(proj, target)) {
-                console.error(`waygraph browser stop: no such session "${target}"`);
-                process.exit(1);
-            }
-            console.log(JSON.stringify({ stopped: target }));
-            return;
-        }
-        if (!sub) {
-            printBrowserUsage();
-            return;
-        }
-        if (sub === "start" || sub.startsWith("-")) {
-            const flagArgs = sub === "start" ? args.slice(2) : args.slice(1);
-            const flags = parseRunFlags(flagArgs, "browser");
-            applyRunFlags(flags);
-            const proj = resolve(flags.positionals[0] ?? process.cwd());
-            if (!existsSync(proj)) {
-                console.error(`waygraph browser: no such directory: ${proj}`);
-                process.exit(1);
-            }
-            const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
-            try {
-                const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
-                const result = await browserStart({
-                    projectDir: proj,
-                    ...(inject?.length ? { inject } : {}),
-                    ...(baseURL ? { baseURL } : {}),
-                    ...(flags.goto
-                        ? { startUrl: flags.goto, skipInitialNavigation: false }
-                        : { skipInitialNavigation: flags.blank !== false }),
-                    headless: flags.headlessBrowser === true,
-                });
-                console.log(JSON.stringify(result));
-                if (!result.headless) {
-                    console.error(`Session ${result.sessionId} started. List all: waygraph browser sessions`);
-                }
-                if (flags.cli) {
-                    await runAttachLoop(proj, result.sessionId);
-                }
-            }
-            catch (err) {
-                console.error(`waygraph browser start: ${err instanceof Error ? err.message : String(err)}`);
-                process.exit(1);
-            }
-            return;
-        }
-        if (sub !== "send" &&
-            sub !== "status" &&
-            sub !== "attach" &&
-            sub !== "dom" &&
-            sub !== "trace" &&
-            sub !== "console" &&
-            sub !== "storage" &&
-            sub !== "upload" &&
-            sub !== "click" &&
-            sub !== "type" &&
-            sub !== "press" &&
-            sub !== "goto" &&
-            sub !== "reload" &&
-            sub !== "reach" &&
-            sub !== "resync" &&
-            sub !== "highlight") {
-            console.error("waygraph browser: unknown subcommand — run `waygraph browser` for usage");
-            printBrowserUsage();
-            process.exit(1);
-        }
-    }
-    if (command === "pilot") {
-        if (args[1] === "sessions") {
-            const { values, positionals: positional } = parseCommand("sessions", { json: { type: "boolean", help: "Machine-readable JSON" } }, args.slice(2));
-            const json = values.json === true;
-            const proj = resolve(positional[0] ?? process.cwd());
-            const sessions = listBrowserSessions(proj);
-            if (json) {
-                console.log(JSON.stringify(sessions, null, 2));
-            }
-            else {
-                printBrowserSessionsList(sessions, proj);
-            }
-            return;
-        }
-        if (args[1] === "attach") {
-            const sessionId = args[2];
-            if (!sessionId) {
-                console.error("waygraph pilot attach: usage: waygraph pilot attach <sessionId> [--inject …] [project]");
-                process.exit(1);
-            }
-            const flags = parseRunFlags(args.slice(3), "pilot");
-            const proj = resolve(flags.positionals[0] ?? process.cwd());
-            try {
-                const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
-                const result = await pilotAttach(proj, sessionId, inject);
-                console.log(JSON.stringify(result));
-            }
-            catch (err) {
-                console.error(`waygraph pilot attach: ${err instanceof Error ? err.message : String(err)}`);
-                process.exit(1);
-            }
-            return;
-        }
-        if (args[1] === "start" || !args[1] || args[1].startsWith("-")) {
-            const flagArgs = args[1] === "start" ? args.slice(2) : args.slice(1);
-            const flags = parseRunFlags(flagArgs, "pilot");
-            applyRunFlags(flags);
-            const proj = resolve(flags.positionals[0] ?? process.cwd());
-            const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
-            try {
-                const result = await pilotStart({
-                    projectDir: proj,
-                    ...(flags.inject?.length ? { injectTokens: flags.inject } : {}),
-                    ...(baseURL ? { baseURL } : {}),
-                    ...(flags.goto
-                        ? { startUrl: flags.goto, skipInitialNavigation: false }
-                        : flags.blank === true
-                            ? { skipInitialNavigation: true }
-                            : {}),
-                    headless: flags.headlessBrowser === true,
-                });
-                console.log(JSON.stringify(result));
-                if (!result.headless) {
-                    console.error(`Chromium window opened (session ${result.sessionId}). ` +
-                        `Terminal menu: waygraph pilot attach ${result.sessionId}`);
-                }
-                if (flags.cli) {
-                    await runAttachLoop(proj, result.sessionId);
-                }
-            }
-            catch (err) {
-                console.error(`waygraph pilot start: ${err instanceof Error ? err.message : String(err)}`);
-                process.exit(1);
-            }
-            return;
-        }
-        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") {
-            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)");
-            process.exit(1);
-        }
-    }
-    // auto send|status|attach <sessionId> - session control against a
-    // --detach'd background session. Intercepted before the normal
-    // project-directory resolution below, same pattern `try demo|auto|
-    // auto:cli` already uses for a sub-verb positional.
-    if ((command === "auto" || command === "browser" || command === "pilot") &&
-        (args[1] === "send" ||
-            args[1] === "status" ||
-            (args[1] === "attach" && command !== "pilot") ||
-            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")) {
-        const sub = args[1];
-        const sessionId = args[2];
-        if (!sessionId) {
-            console.error(`waygraph ${command} ${sub}: missing <sessionId>`);
-            process.exit(1);
-        }
-        const projHint = resolve(process.cwd());
-        const meta = resolveSessionMeta(sessionId, projHint);
-        if (!meta) {
-            console.error(`waygraph ${command} ${sub}: no such session "${sessionId}" — ` +
-                "wrong directory? run `waygraph pilot sessions` from the project that started it");
-            process.exit(1);
-        }
-        const proj = meta.projectDir;
-        if (sub === "attach") {
-            await runAttachLoop(proj, sessionId);
-            return;
-        }
-        if (sub === "send") {
-            const pick = args[3];
-            if (pick === undefined) {
-                console.error('waygraph auto send: usage: waygraph auto send <sessionId> "<pick>" [--timeout <ms>]');
-                process.exit(1);
-            }
-            // Real, direct need found live: a single Block can legitimately
-            // run a genuinely slow real interaction (e.g. a multi-step mouse
-            // drag) that exceeds the 15s default - same reasoning `auto
-            // reach` already gets a 90s default for (multiple Blocks in one
-            // call). Unlike reach, send has no way to know ahead of time
-            // whether the ONE Block it's running is fast or slow, so this is
-            // opt-in via a flag rather than a raised default.
-            let timeoutMs;
-            const raw = parseCommand("auto send", SEND_OPTIONS, args.slice(4)).values.timeout;
-            if (raw !== undefined) {
-                const n = Number(raw);
-                if (!Number.isFinite(n) || n <= 0) {
-                    console.error(`waygraph auto send: --timeout must be a positive number of ms, got "${raw}"`);
-                    process.exit(1);
-                }
-                timeoutMs = n;
-            }
-            const res = await requestSession(proj, sessionId, { op: "send", pick }, timeoutMs);
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "dom") {
-            const domArgs = args.slice(3);
-            let mode;
-            let selector;
-            let depth;
-            const dom = parseCommand("auto dom", DOM_OPTIONS, domArgs).values;
-            if (dom.mode !== undefined) {
-                if (dom.mode !== "aria" && dom.mode !== "full") {
-                    console.error(`waygraph auto dom: --mode must be "aria" or "full", got "${dom.mode}"`);
-                    process.exit(1);
-                }
-                mode = dom.mode;
-            }
-            selector = dom.selector;
-            if (dom.depth !== undefined) {
-                const n = Number(dom.depth);
-                if (!Number.isInteger(n) || n < 1) {
-                    console.error(`waygraph auto dom: --depth must be a positive integer, got "${dom.depth}"`);
-                    process.exit(1);
-                }
-                depth = n;
-            }
-            const res = await requestSession(proj, sessionId, {
-                op: "dom",
-                ...(mode ? { mode } : {}),
-                ...(selector ? { selector } : {}),
-                ...(depth !== undefined ? { depth } : {}),
-            });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "trace") {
-            const res = await requestSession(proj, sessionId, { op: "trace" });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "console") {
-            const res = await requestSession(proj, sessionId, { op: "console" });
-            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));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "click") {
-            const selector = args[3];
-            if (selector === undefined) {
-                console.error('waygraph auto click: usage: waygraph auto click <sessionId> "<selector>"');
-                process.exit(1);
-            }
-            const res = await requestSession(proj, sessionId, { op: "click", selector });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "type") {
-            const selector = args[3];
-            const text = args[4];
-            if (selector === undefined || text === undefined) {
-                console.error('waygraph auto type: usage: waygraph auto type <sessionId> "<selector>" "<text>"');
-                process.exit(1);
-            }
-            const res = await requestSession(proj, sessionId, { op: "type", selector, text });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "press") {
-            const selector = args[3];
-            const key = args[4];
-            if (selector === undefined || key === undefined) {
-                console.error('waygraph auto press: usage: waygraph auto press <sessionId> "<selector>" <key>');
-                process.exit(1);
-            }
-            const res = await requestSession(proj, sessionId, { op: "press", selector, key });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "goto") {
-            const url = args[3];
-            if (url === undefined) {
-                console.error("waygraph auto goto: usage: waygraph auto goto <sessionId> <url>");
-                process.exit(1);
-            }
-            const res = await requestSession(proj, sessionId, { op: "goto", url });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "upload") {
-            const selector = args[3];
-            const kindOrPath = args[4];
-            if (selector === undefined || kindOrPath === undefined) {
-                console.error('waygraph auto upload: usage: waygraph auto upload <sessionId> "<selector>" <image|pdf|video|path-to-file>');
-                process.exit(1);
-            }
-            const stub = kindOrPath === "image" || kindOrPath === "pdf" || kindOrPath === "video"
-                ? { selector, stub: kindOrPath }
-                : { selector, stub: { filePath: resolve(process.cwd(), kindOrPath) } };
-            const res = await requestSession(proj, sessionId, { op: "upload", ...stub });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "reload") {
-            const res = await requestSession(proj, sessionId, { op: "reload" });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "reach") {
-            const checkpoint = args[3];
-            if (checkpoint === undefined) {
-                console.error("waygraph auto reach: usage: waygraph auto reach <sessionId> <Checkpoint>");
-                process.exit(1);
-            }
-            // Longer than every other op's default (15s): a real multi-step
-            // route runs several real Blocks in sequence server-side before
-            // responding - a legitimately slow single request, not a hang.
-            const res = await requestSession(proj, sessionId, { op: "reach", checkpoint }, 90_000);
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "resync") {
-            const res = await requestSession(proj, sessionId, { op: "resync" });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        if (sub === "highlight") {
-            const raw = args[3];
-            if (raw === undefined) {
-                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 (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 ${command} highlight: do not set "op" (or set it to "highlight")`);
-                process.exit(1);
-            }
-            const { op: _ignore, ...rest } = fixtures;
-            const res = await requestSession(proj, sessionId, {
-                op: "highlight",
-                ...rest,
-            });
-            console.log(JSON.stringify(res));
-            if (!res.ok)
-                process.exitCode = 1;
-            return;
-        }
-        const res = await requestSession(proj, sessionId, { op: "status" });
-        console.log(JSON.stringify(res));
-        if (!res.ok)
-            process.exitCode = 1;
+    if (command === "browser" && (await browserCase(args)))
+        return;
+    if (command === "pilot" && (await pilotCase(args)))
+        return;
+    // A session op (`auto|browser|pilot send <sessionId> ...`) runs against a running session, before any project path.
+    if ((command === "auto" || command === "browser" || command === "pilot") && isSessionOp(command, args[1])) {
+        await sessionOpCase(args, command);
         return;
     }
     const flags = parseRunFlags(args.slice(1), command ?? "auto");

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

@@ -1,4 +1,4 @@
-import type { SessionMeta } from "../live/auto-session/ipc.js";
+import type { SessionMeta } from "../live/auto-session/files.js";
 export declare function printBrowserUsage(): void;
 export declare function printBrowserSessionsList(sessions: SessionMeta[], projectDir: string): void;
 export declare function usage(): void;

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`
@@ -37,7 +37,7 @@ export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: num
  */
 export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, opts?: {
     gatesFast?: boolean;
-    pace?: DemoPace;
+    pace?: DemoPace | undefined;
 }): number | null;
 /**
  * Effective demo pace for a step: block override > flow episode > normal.

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

@@ -23,8 +23,8 @@ export declare function resolveDeviceState(input: DevicePreset | DeviceState | D
  * - keep: omit - preserve previous (whole episode remain)
  */
 export declare function applyDevicePhase(prev: DeviceState | undefined, phase: {
-    deviceSync?: "set" | "clear" | "keep";
-    device?: DeviceState;
+    deviceSync?: "set" | "clear" | "keep" | undefined;
+    device?: DeviceState | undefined;
 }): {
     device: DeviceState | undefined;
     sync: "set" | "clear" | "keep";

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

@@ -1,8 +1,10 @@
 import type { HighlightStubPhase, ResolvedHighlight } from "../../engine/stub/ring.js";
 import type { HighlightStubPhaseName, StubLifecycleFn } from "../../engine/stub/stub.js";
-import type { Block } from "../../engine/block/block.js";
+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[];
-export declare function readStubRaw(block: Block<any, any>, phase: HighlightStubPhaseName): StubLifecycleFn<any> | undefined;
+/** 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);
@@ -61,11 +61,7 @@ export function resolvePhaseMap(phaseMap) {
     }
     return resolved;
 }
+/** The stub a Block's flow chained for this phase, if any. */
 export function readStubRaw(block, phase) {
-    const instr = block.instruction;
-    if (phase === "stubBefore")
-        return instr.stubBefore;
-    if (phase === "stubAfter")
-        return instr.stubAfter;
-    return instr.stubOnError;
+    return block.instruction[phase];
 }

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

@@ -1,39 +1,35 @@
 import type { HighlightStubPhaseName, StubPhaseResult } from "../../engine/stub/stub.js";
-import type { ResolvedHighlight, WaygraphSlide } from "../../engine/stub/ring.js";
-import type { Block } from "../../engine/block/block.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
  * const before = await runStubPhase(block, "stubBefore", { mem });
  * // before.todos, before.highlights
  */
-export declare function runStubPhase(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
-    out?: Checkpoint<string>;
+export declare function runStubPhase(block: SomeBlock, phase: HighlightStubPhaseName, opts?: {
+    out?: Checkpoint<string> | undefined;
     error?: unknown;
-    mem?: MemPage;
+    mem?: MemPage | undefined;
 }): Promise<StubPhaseResult>;
 /**
  * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
  * async lifecycles + episode fixtures (todos/zoom).
  */
-export declare function resolveHighlightSlots(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
+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: Block<any, any>, opts?: {
-    out?: Checkpoint<string>;
-}): WaygraphSlide[];
 /**
  * True when the block authored stubAfter (lifecycle fn or slots).
  * When true, demo should not use verify-trait fallback.
  */
-export declare function hasAuthoredStubAfter(block: Block<any, any>, out?: Checkpoint<string>): boolean;
+export declare function hasAuthoredStubAfter(block: SomeBlock, out?: Checkpoint<string>): boolean;
 /**
  * True when stubOnError is authored (lifecycle fn and/or rings).
  * Demo fail path only - success never consults this.
  */
-export declare function hasAuthoredStubOnError(block: Block<any, any>): boolean;
+export declare function hasAuthoredStubOnError(block: SomeBlock): boolean;