waygraph 0.15.54 → 0.16.0

package/dist/cli/usage.js

@@ -1,3 +1,4 @@
+import { optionHelp } from "./flags.js";
 export function printBrowserUsage() {
     console.log(`waygraph browser — persistent Playwright sessions (headful by default)
 
@@ -36,26 +37,22 @@ export function usage() {
 Primary (less is more):
   waygraph auto  [project|.flow.ts]        Interactive explore (picker)
                  --cli                     Terminal menu instead of browser panel
-                 --cli --detach            Run the --cli session as a background socket
-                                           server; prints {sessionId, socketPath} and exits
                  --blocks <From> <To>      Graph path-find From->To, then run
                  --data '{...}'            Mem seed (same as demo/run)
                  (pass a .flow.ts to run that flow - same as run)
-                 --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
+  waygraph auto send <sessionId> "<pick>"  Send one pick to a session (browser start / pilot start), print
                                            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).
+                                           prefix for a 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)
-  waygraph auto status <sessionId>         Read a --detach session's state (no side effects)
+  waygraph auto status <sessionId>         Read a session's state (no side effects)
   waygraph auto attach <sessionId>         Reopen an interactive terminal against a
-                                           running --detach session
+                                           running session
   waygraph auto dom <sessionId>            Read the live page's structure (no side effects)
                  --mode aria|full          Default aria (Playwright ariaSnapshotJSON, AI mode);
                                            full = bounded raw DOM walk (tag/attrs/text/children)
@@ -114,8 +111,8 @@ Primary (less is more):
                                            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).
+                                           '<json>' (prefer that prefix for a 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".
@@ -124,11 +121,7 @@ Primary (less is more):
                                            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)
-                 --goto <url>              Navigate on start (disables blank page)
-                 --blank                   Force about:blank on start (default)
-                 --headless                Headless session (default is visible browser)
-                 --cli                     After start, open the terminal picker (auto attach)
+${optionHelp("session")}
   waygraph browser sessions [project]      List live browser sessions (attach/status/stop by id)
   waygraph browser send|status|attach|…    Same session control as auto (see auto send/status/…)
   waygraph pilot start                     Bootstrap: browser session + whole-project graph +
@@ -140,40 +133,9 @@ Primary (less is more):
   waygraph auto                            Interactive explore (picker) — NOT the persistent browser
                                            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)
-                 --mini                    Force compact mini panel (Hide pill + Next); alias --stepper-mini
-                 --todo-left|--todo-right  Floating checklist dock side (also ctx.todoPos / WAYGRAPH_TODO_POS)
-                 --todo-full               Opt out: full checklist, no compact/collision/behind-ring
-                 --todo-smart              Opt in: compact + collision + behind-ring (default)
-                 --ff-expand               Expand fastForwardComposeBlock inners as separate steps
-                 --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
-                 --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless
-                 --auto-play-video-head    Same, but keep the browser visible (--non-headless)
-                 --video [dir]             Record .webm (demo: headless unless --non-headless);
-                                           default folder ~/Downloads/waygraph-videos/<project>,
-                                           or video.dir in the config / WAYGRAPH_VIDEO_DIR
-                 --video-viewport WxH       Recording size (default demo: 1920x1080)
-                 --title / --base-url
+${optionHelp("demo")}
   waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)
-                 --data '{...}'
-                 --mem-stub                Same as demo's --mem-stub
-                 --all-branches            Bare Flow ref only: explore every MapBuilder.branch()
-                                           path, cloning the session (storageState+URL) at each
-                                           branch point - see runBranchRegression()
-                 --shared-session          With --all-branches: one shared session instead of
-                                           cloning (follows only the live-dispatch path)
-                 --non-headless            Show browser
-                 --video [dir]             Record .webm
-                 --video-viewport WxH       Recording size (default run: 1280x720)
-                 --ff-expand               Same as demo (expand FFCompose inners)
-                 --ff-disabled             Same as demo (dispute: expand FF)
+${optionHelp("run")}
   waygraph test                            Runs the project's @playwright/test suite (cwd) -
                                            thin wrapper: forwards to the local playwright
                                            binary (or npx playwright as a fallback)
@@ -186,6 +148,11 @@ Primary (less is more):
                                            has a trace - test report opens it.
 
 Also:
+  waygraph manifest [project] [--out <file>]
+                                           Every Block (kind, route from -> to, requires, map
+                                           group), Flow (use case, steps, settings) and
+                                           Checkpoint of the project, as JSON - what Waygraph UI
+                                           and map packages read.
   --config <name|file>   (any command) use another config instead of waygraph.config.ts, e.g.
                  waygraph test --config staging   (config/waygraph.staging.config.ts)
   --env <mode>   (any command) load .env.<mode> / .env.<mode>.local on top of .env, e.g.
@@ -196,6 +163,8 @@ Also:
                                            dependency. Dry run unless --apply; only the paths you
                                            name are copied, differing files only with --overwrite.
                                            --skills refreshes .agents/skills to this waygraph's.
+                                           --codemod checkpoints rewrites tag strings and <In, Out>
+                                           to Checkpoint values (checkpoint: Home, from/to).
   waygraph extensions install [project] [--update]
                                            Download the browser extensions listed in
                                            waygraph.config.* (extensions: ["hoppscotch"]) into
@@ -208,6 +177,9 @@ Also:
                                            violation, unlike check's warnings-only stance. A
                                            no-op (exit 0, informational) if the project has no
                                            src/map/ directory at all.
+  waygraph map pack <group> [project]      Pack a src/map/ group that owns its _states.ts into
+                 --out <dir> --name <pkg>  a package (.waygraph/packages/<group>); installed
+                 --version <x.y.z>         elsewhere, its Blocks join the scan
   waygraph traverse [project]              Graph crawl (Phase B-E)
                  --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --parallel N              Phase D: N clone workers (max 4)
@@ -222,7 +194,6 @@ Also:
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
                  try auto                  Headed browser panel (default)
                  try auto:cli / --cli      Terminal menu instead
-                 try auto --headed         Same as try auto (compat)
 
 Skills (print packaged skill markdown to stdout - for agents / paste):
   waygraph --skill                         List available skills
@@ -246,10 +217,7 @@ Examples:
   waygraph traverse --parallel 2 --session clone         # Phase D clone workers
   waygraph run  --blocks "loginFlow then add-all-to-cart" --data '{...}' --video
 
-Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto --blocks A B;
-  --autoplay -> --auto-next. Prefer the primary verbs above.
-
-Project path optional (defaults to cwd). Flags beat WAYGRAPH_* env.
+Project path optional (defaults to cwd). Flags beat WAYGRAPH_* env. \`waygraph <command> --help\`: that command's flags.
 \`run\`/\`demo\`/\`auto\`: Flow export, .flow.ts path, or "a then b" chain (auto also explores).
 Hide stepper = compact "N / M · block" pill. Collapses while a step runs (clicks hit the page). Video mode stays compact.
 `);

package/dist/cli/util.d.ts

@@ -2,9 +2,9 @@
  * This package's own installed root (contains `templates/`, sibling to `dist/`) - this file
  * compiles to `dist/cli/util.js`, so it's TWO levels up, not one. Real regression once, from the
  * 0.15.24 cli.ts split: this function was copied verbatim from its old top-level `src/cli.ts`
- * location (one level: `dist/cli.js` -> `..`) into `src/cli/util.ts` (compiles one level deeper)
+ * location (one level: `dist/cli/cli.js` -> `..`) into `src/cli/util.ts` (compiles one level deeper)
  * without adjusting the path math - silently broke `waygraph init`/`try` (no build-level test
- * caught it, since tests never ran the actual compiled dist/cli.js for these two commands).
+ * caught it, since tests never ran the actual compiled dist/cli/cli.js for these two commands).
  */
 export declare function packageRoot(): string;
 /** Spawns with inherited stdio (the real npm/playwright output, visible) and resolves to its exit code. */

package/dist/cli/util.js

@@ -1,4 +1,3 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -14,9 +13,9 @@ import { spawn } from "node:child_process";
  * This package's own installed root (contains `templates/`, sibling to `dist/`) - this file
  * compiles to `dist/cli/util.js`, so it's TWO levels up, not one. Real regression once, from the
  * 0.15.24 cli.ts split: this function was copied verbatim from its old top-level `src/cli.ts`
- * location (one level: `dist/cli.js` -> `..`) into `src/cli/util.ts` (compiles one level deeper)
+ * location (one level: `dist/cli/cli.js` -> `..`) into `src/cli/util.ts` (compiles one level deeper)
  * without adjusting the path math - silently broke `waygraph init`/`try` (no build-level test
- * caught it, since tests never ran the actual compiled dist/cli.js for these two commands).
+ * caught it, since tests never ran the actual compiled dist/cli/cli.js for these two commands).
  */
 export function packageRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");

package/dist/{highlights → demo/narration}/css.d.ts

@@ -5,7 +5,7 @@
  * SAME "waygraph vision" ring can import pure CSS text, not the rendering
  * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
  * module load with no `import.meta.url` guard, so importing anything from it
- * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
+ * is unsafe as a library dependency (see `overlay/pilot-shell.ts`'s own doc
  * comment for the same reasoning re: the badge/panel). This file has always
  * been the pure, side-effect-free home for tone/size/weight - the CSS that
  * renders them belongs alongside it for the same reason. `cli.ts` imports

package/dist/{highlights → demo/narration}/css.js

@@ -1,5 +1,4 @@
-import { ringCss } from "../ui/components/ring.js";
-// Split out of the former 2,100-line highlights.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { ringCss } from "../overlay/ui/components/ring.js";
 /**
  * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
  * actual visual language `cli.ts`'s own demo stepper paints with. Extracted
@@ -7,7 +6,7 @@ import { ringCss } from "../ui/components/ring.js";
  * SAME "waygraph vision" ring can import pure CSS text, not the rendering
  * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
  * module load with no `import.meta.url` guard, so importing anything from it
- * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
+ * is unsafe as a library dependency (see `overlay/pilot-shell.ts`'s own doc
  * comment for the same reasoning re: the badge/panel). This file has always
  * been the pure, side-effect-free home for tone/size/weight - the CSS that
  * renders them belongs alongside it for the same reason. `cli.ts` imports

package/dist/{highlights → demo/narration}/demo-pace.d.ts

@@ -1,14 +1,11 @@
-import type { DemoPace, FixtureDurationFields } from "./types.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { FixtureDurationFields } from "../../engine/stub/ring.js";
 /** Default fixture dwell when `duration: true`. */
 export declare const FIXTURE_DURATION_MS_DEFAULT = 2000;
 /** Default fixture dwell under `--fast` when duration is enabled. */
 export declare const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
 /** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
 export declare const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
-/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
-export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
-/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
-export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
 /** Turns any accepted pace spelling into a `DemoPace`; unknown values mean normal. */
 export declare function normalizeDemoPace(raw: unknown): DemoPace;
 /** The multiplier a pace applies to dwell and gate time (1 = normal); `demo.speeds` redefines the named ones. */
@@ -33,7 +30,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),
- * or `null` when duration is unset (caller keeps legacy timing).
+ * or `null` when duration is unset (caller keeps its default timing).
  *
  * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
  * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
@@ -42,11 +39,6 @@ export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, op
     gatesFast?: boolean;
     pace?: DemoPace;
 }): number | null;
-/** @deprecated Prefer {@link resolveFixtureDwellMs} */
-export declare function resolveSlideDwellMs(slide: FixtureDurationFields, opts?: {
-    gatesFast?: boolean;
-    pace?: DemoPace;
-}): number | null;
 /**
  * Effective demo pace for a step: block override > flow episode > normal.
  * Opaque FF / wasFastForward always win as blitz.

package/dist/{highlights → demo/narration}/demo-pace.js

@@ -1,13 +1,10 @@
+import { envString } from "../../engine/env.js";
 /** Default fixture dwell when `duration: true`. */
 export const FIXTURE_DURATION_MS_DEFAULT = 2000;
 /** Default fixture dwell under `--fast` when duration is enabled. */
 export const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
 /** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
 export const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
-/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
-export const SLIDE_DURATION_MS_DEFAULT = FIXTURE_DURATION_MS_DEFAULT;
-/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
-export const SLIDE_DURATION_FAST_MS_DEFAULT = FIXTURE_DURATION_FAST_MS_DEFAULT;
 /** Turns any accepted pace spelling into a `DemoPace`; unknown values mean normal. */
 export function normalizeDemoPace(raw) {
     if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
@@ -42,7 +39,8 @@ export function normalizeDemoPace(raw) {
 function paceSpeeds() {
     const out = { blitz: 0.05, fast: 0.33, slow: 2 };
     try {
-        const raw = process.env.WAYGRAPH_PACE_SPEEDS ? JSON.parse(process.env.WAYGRAPH_PACE_SPEEDS) : {};
+        const speeds = envString("WAYGRAPH_PACE_SPEEDS");
+        const raw = speeds ? JSON.parse(speeds) : {};
         for (const k of ["blitz", "fast", "slow"]) {
             if (typeof raw[k] === "number" && raw[k] > 0)
                 out[k] = Math.min(10, raw[k]);
@@ -95,7 +93,7 @@ export function demoPaceIsSlow(pace) {
 }
 /** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
 export function demoPaceGateMs(pace, baseAutoplayMs) {
-    if (pace === "blitz" && process.env.WAYGRAPH_PACE_SPEEDS) {
+    if (pace === "blitz" && envString("WAYGRAPH_PACE_SPEEDS")) {
         return Math.min(30000, Math.max(20, Math.round(baseAutoplayMs * paceSpeeds().blitz)));
     }
     if (demoPaceIsBlitz(pace))
@@ -153,7 +151,7 @@ export function formatDemoPaceLabel(pace, baseAutoplayMs = 1800) {
 }
 /**
  * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
- * or `null` when duration is unset (caller keeps legacy timing).
+ * or `null` when duration is unset (caller keeps its default timing).
  *
  * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
  * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
@@ -188,10 +186,6 @@ export function resolveFixtureDwellMs(fixture, opts) {
         return Math.max(normalMs, FIXTURE_DURATION_SLOW_MS_DEFAULT);
     return normalMs;
 }
-/** @deprecated Prefer {@link resolveFixtureDwellMs} */
-export function resolveSlideDwellMs(slide, opts) {
-    return resolveFixtureDwellMs(slide, opts);
-}
 /**
  * Effective demo pace for a step: block override > flow episode > normal.
  * Opaque FF / wasFastForward always win as blitz.

package/dist/{highlights → demo/narration}/device.d.ts

@@ -1,4 +1,4 @@
-import type { DeviceOrientation, DevicePreset, DeviceState, DeviceViewport } from "./types.js";
+import type { DeviceOrientation, DevicePreset, DeviceState, DeviceViewport } from "../../engine/stub/viewport.js";
 /** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
 export declare const DEVICE_PRESETS: Record<DevicePreset, Omit<DeviceState, "touchMode"> & {
     touchMode?: boolean;
@@ -18,7 +18,7 @@ export declare function applyOrientation(state: DeviceState, orientation: Device
 export declare function resolveDeviceState(input: DevicePreset | DeviceState | DeviceViewport | undefined, touchOverride?: boolean, orientationOverride?: DeviceOrientation): DeviceState | undefined;
 /**
  * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
- * - clear: hideDevice / clearDevice / device("desktop") with clear intent
+ * - clear: hideDevice / device("desktop") with clear intent
  * - set: author set device/viewport/touch this phase
  * - keep: omit - preserve previous (whole episode remain)
  */

package/dist/{highlights → demo/narration}/device.js

@@ -154,7 +154,7 @@ export function resolveDeviceState(input, touchOverride, orientationOverride) {
 }
 /**
  * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
- * - clear: hideDevice / clearDevice / device("desktop") with clear intent
+ * - clear: hideDevice / device("desktop") with clear intent
  * - set: author set device/viewport/touch this phase
  * - keep: omit - preserve previous (whole episode remain)
  */

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

@@ -0,0 +1,8 @@
+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";
+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. */
+export declare function resolvePhaseMap(phaseMap: HighlightStubPhase): ResolvedHighlight[];
+export declare function readStubRaw(block: Block<any, any>, phase: HighlightStubPhaseName): StubLifecycleFn<any> | undefined;

package/dist/demo/narration/merge.js

@@ -0,0 +1,71 @@
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
+function zoomOf(slot) {
+    return slot.zoom !== undefined && Number.isFinite(slot.zoom) && slot.zoom > 0 ? { zoom: slot.zoom } : {};
+}
+function fxOf(slot) {
+    const out = {};
+    if (slot.focus !== undefined)
+        out.focus = !!slot.focus;
+    if (slot.color !== undefined && String(slot.color).trim())
+        out.color = String(slot.color).trim();
+    if (slot.cursor !== undefined)
+        out.cursor = !!slot.cursor;
+    if (slot.todo !== undefined && String(slot.todo).trim())
+        out.todo = String(slot.todo).trim();
+    if (slot.gesture === "tap" || slot.gesture === "hold" || slot.gesture === "click" || slot.gesture === "swipe") {
+        out.gesture = slot.gesture;
+    }
+    return out;
+}
+/** A Block's own stub slot with its style fields normalized. */
+function normalizeSlot(slot) {
+    if (!slot)
+        return null;
+    return {
+        ...slot,
+        ...(slot.tone ? { tone: normalizeHighlightTone(slot.tone) } : {}),
+        ...(slot.size ? { size: normalizeHighlightSize(slot.size) } : {}),
+        ...(slot.weight ? { weight: normalizeHighlightWeight(slot.weight) } : {}),
+        ...zoomOf(slot),
+        ...fxOf(slot),
+    };
+}
+export function applyDefaultZoom(slots, defaultZoom) {
+    if (defaultZoom === undefined || !(defaultZoom > 0))
+        return slots;
+    return slots.map((h) => (h.zoom !== undefined && h.zoom > 0 ? h : { ...h, zoom: defaultZoom }));
+}
+export function applyDefaultZoomOut(slots, defaultZoomOut) {
+    if (defaultZoomOut === undefined)
+        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. */
+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);
+    // Numeric stub ids ("0", "1") sort by number. Named stubs keep author
+    // insertion order - localeCompare used to reorder password/submit/username
+    // and advance the wrong todo index on fill.
+    const ordered = allNumeric ? [...phaseKeys].sort((a, b) => Number(a) - Number(b)) : phaseKeys;
+    const resolved = [];
+    for (const id of ordered) {
+        const merged = normalizeSlot(phaseMap[id]);
+        if (merged) {
+            resolved.push({
+                ...merged,
+                slotId: id,
+                ...(merged.todo ? { todo: merged.todo } : {}),
+            });
+        }
+    }
+    return resolved;
+}
+export function readStubRaw(block, phase) {
+    const instr = block.instruction;
+    if (phase === "stubBefore")
+        return instr.stubBefore;
+    if (phase === "stubAfter")
+        return instr.stubAfter;
+    return instr.stubOnError;
+}

package/dist/{highlights/run-phase.d.ts → demo/narration/narration.d.ts}

@@ -1,19 +1,20 @@
-import type { HighlightFixtureMap, HighlightStubPhaseName, ResolvedHighlight, StubPhaseResult, WaygraphSlide } from "./types.js";
-import type { Block, Checkpoint } from "../types.js";
-import type { MemPage } from "../mem-page.js";
+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 { 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.
  * Returns rings + episode fixtures (todos / todoIndex / zoom).
  *
  * @example
- * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * 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>;
     error?: unknown;
     mem?: MemPage;
-    fixtures?: HighlightFixtureMap;
 }): Promise<StubPhaseResult>;
 /**
  * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
@@ -21,23 +22,18 @@ export declare function runStubPhase(block: Block<any, any>, phase: HighlightStu
  */
 export declare function resolveHighlightSlots(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
-    fixtures?: HighlightFixtureMap;
 }): ResolvedHighlight[];
-/**
- * Resolve multi-step yap slides: flow fixture `slides` wins when present,
- * else `instruction.slides` (function form allowed).
- */
+/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
 export declare function resolveSlides(block: Block<any, any>, opts?: {
     out?: Checkpoint<string>;
-    fixtures?: HighlightFixtureMap;
 }): WaygraphSlide[];
 /**
- * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * 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>, fixtures?: HighlightFixtureMap): boolean;
+export declare function hasAuthoredStubAfter(block: Block<any, any>, 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>, fixtures?: HighlightFixtureMap): boolean;
+export declare function hasAuthoredStubOnError(block: Block<any, any>): boolean;

package/dist/{highlights/run-phase.js → demo/narration/narration.js}

@@ -1,5 +1,5 @@
-import { createStubCtx, liftLegacySlotTodos } from "./stub-ctx.js";
-import { applyDefaultZoom, applyDefaultZoomOut, applyLegacyHighlightsShim, isStubPhase, mergePhaseMaps, readStubRaw } from "./merge.js";
+import { createStubCtx } from "./stub-ctx.js";
+import { applyDefaultZoom, applyDefaultZoomOut, readStubRaw, resolvePhaseMap } from "./merge.js";
 import { buildTodoDock, normalizeTodoStyle, normalizeTodos } from "./todo-dock.js";
 import { resolveDeviceState } from "./device.js";
 /**
@@ -7,7 +7,7 @@ import { resolveDeviceState } from "./device.js";
  * Returns rings + episode fixtures (todos / todoIndex / zoom).
  *
  * @example
- * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * const before = await runStubPhase(block, "stubBefore", { mem });
  * // before.todos, before.highlights
  */
 export async function runStubPhase(block, phase, opts) {
@@ -18,43 +18,16 @@ export async function runStubPhase(block, phase, opts) {
         ...(opts?.mem !== undefined ? { mem: opts.mem } : {}),
     });
     const raw = readStubRaw(block, phase);
-    if (typeof raw === "function") {
+    if (raw) {
         try {
-            const ret = await raw(ctx);
-            if (isStubPhase(ret)) {
-                bag.highlights = { ...bag.highlights, ...ret };
-            }
-        }
-        catch {
-            /* best-effort */
+            await raw(ctx);
         }
-        // Compat: legacy `(out) => map` that expected Checkpoint (__state on arg). Only worth trying
-        // when the real ctx call genuinely did nothing - checked against the WHOLE bag, not just
-        // highlights/todos, so a stubBefore that only calls e.g. ctx.caption()/ctx.title()/ctx.zoom()
-        // (no highlights, no todos) isn't mistaken for "didn't run" and re-invoked with a bare
-        // Checkpoint that has none of StubCtx's methods - a real, previously-triggered bug (caught via
-        // examples/saucedemo/src/flows/checkout.flow.ts's own stubBefore(ctx) { ctx.caption(...) }).
-        const bagUntouched = Object.keys(bag).length === 1 && Object.keys(bag.highlights).length === 0;
-        if (bagUntouched) {
-            try {
-                const legacyOut = (opts?.out ?? { __state: "" });
-                const ret2 = raw(legacyOut);
-                if (isStubPhase(ret2))
-                    bag.highlights = { ...ret2 };
-            }
-            catch {
-                /* ignore */
-            }
+        catch (err) {
+            // A mistake in the author's stub: shown on the step (the demo's failure panel), never dropped.
+            throw new Error(`${block.name}: its ${phase} stub threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
-    else if (isStubPhase(raw)) {
-        bag.highlights = { ...raw };
-    }
-    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
-    liftLegacySlotTodos(bag);
-    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
-    let highlights = mergePhaseMaps(bag.highlights, fixturePhase);
-    highlights = applyDefaultZoom(highlights, bag.zoom);
+    let highlights = applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
     highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
     const todoDock = bag.hideTodos
         ? undefined
@@ -134,45 +107,19 @@ export async function runStubPhase(block, phase, opts) {
 export function resolveHighlightSlots(block, phase, opts) {
     const bag = { highlights: {} };
     const raw = readStubRaw(block, phase);
-    if (typeof raw === "function") {
+    if (raw) {
+        // Synchronous read: the rings a stub paints before its first await.
         try {
-            const ctx = createStubCtx(bag, {
-                ...(opts?.out !== undefined ? { out: opts.out } : {}),
-            });
-            const ret = raw(ctx);
-            if (isStubPhase(ret)) {
-                bag.highlights = { ...bag.highlights, ...ret };
-            }
+            void raw(createStubCtx(bag, { ...(opts?.out !== undefined ? { out: opts.out } : {}) }));
         }
-        catch {
-            try {
-                const legacyOut = (opts?.out ?? { __state: "" });
-                const ret2 = raw(legacyOut);
-                if (isStubPhase(ret2))
-                    bag.highlights = { ...ret2 };
-            }
-            catch {
-                bag.highlights = {};
-            }
+        catch (err) {
+            throw new Error(`${block.name}: its ${phase} stub threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
-    else if (isStubPhase(raw)) {
-        bag.highlights = { ...raw };
-    }
-    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
-    liftLegacySlotTodos(bag);
-    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
-    return applyDefaultZoom(mergePhaseMaps(bag.highlights, fixturePhase), bag.zoom);
+    return applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
 }
-/**
- * Resolve multi-step yap slides: flow fixture `slides` wins when present,
- * else `instruction.slides` (function form allowed).
- */
+/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
 export function resolveSlides(block, opts) {
-    const fromFixture = opts?.fixtures?.[block.name]?.slides;
-    if (fromFixture && fromFixture.length > 0) {
-        return [...fromFixture];
-    }
     const instr = block.instruction;
     let raw = instr.slides;
     if (typeof raw === "function") {
@@ -187,40 +134,24 @@ export function resolveSlides(block, opts) {
         return [];
     return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
 }
-function stubPhaseLooksAuthored(block, phase, fixtures) {
-    const raw = readStubRaw(block, phase);
-    if (typeof raw === "function")
-        return true;
-    if (isStubPhase(raw) && Object.keys(raw).length > 0)
-        return true;
-    const fx = fixtures?.[block.name]?.[phase];
-    if (fx && Object.keys(fx).length > 0)
-        return true;
-    return false;
+function stubPhaseLooksAuthored(block, phase) {
+    return readStubRaw(block, phase) !== undefined;
 }
 /**
- * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * True when the block authored stubAfter (lifecycle fn or slots).
  * When true, demo should not use verify-trait fallback.
  */
-export function hasAuthoredStubAfter(block, out, fixtures) {
-    if (stubPhaseLooksAuthored(block, "stubAfter", fixtures))
-        return true;
-    const instr = block.instruction;
-    if (instr.highlights)
+export function hasAuthoredStubAfter(block, out) {
+    if (stubPhaseLooksAuthored(block, "stubAfter"))
         return true;
-    return resolveHighlightSlots(block, "stubAfter", {
-        ...(out !== undefined ? { out } : {}),
-        ...(fixtures !== undefined ? { fixtures } : {}),
-    }).length > 0;
+    return resolveHighlightSlots(block, "stubAfter", out !== undefined ? { out } : {}).length > 0;
 }
 /**
  * True when stubOnError is authored (lifecycle fn and/or rings).
  * Demo fail path only - success never consults this.
  */
-export function hasAuthoredStubOnError(block, fixtures) {
-    if (stubPhaseLooksAuthored(block, "stubOnError", fixtures))
+export function hasAuthoredStubOnError(block) {
+    if (stubPhaseLooksAuthored(block, "stubOnError"))
         return true;
-    return (resolveHighlightSlots(block, "stubOnError", {
-        ...(fixtures !== undefined ? { fixtures } : {}),
-    }).length > 0);
+    return resolveHighlightSlots(block, "stubOnError").length > 0;
 }