waygraph 0.15.53 → 0.16.0

package/dist/engine/stub/stub.d.ts

@@ -0,0 +1,268 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { MemPage } from "../mem/mem.js";
+import type { TodoDockState, TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput, WaygraphTodoInput, WaygraphTodoItem, WaygraphTodosOpts } from "./todos.js";
+import type { DeviceOrientation, DevicePreset, DeviceState, DeviceViewport } from "./viewport.js";
+import type { HighlightStubPhase, ResolvedHighlight, WaygraphHighlightStub } from "./ring.js";
+/** Where the top banner sits. */
+export type BannerPos = "left" | "center" | "right";
+/** Banner UX, mirrors {@link TodoDockUiOpts}: pass `false` fields to opt out for this phase. */
+export interface BannerUiOpts {
+    /** Move to a free spot while a highlight ring would overlap it (default true). */
+    collision?: boolean;
+    /** Hide the banner entirely for this phase. */
+    hidden?: boolean;
+    /**
+     * Fade duration (ms) when the banner's title text changes, so a change reads as a deliberate
+     * beat instead of an instant flicker. Default 220; 0 disables the fade (instant swap).
+     */
+    captionFadeMs?: number;
+}
+/** Episode-level fixtures authored inside stubBefore/After/OnError(ctx). */
+export type StubPhaseFixtures = {
+    todos?: readonly WaygraphTodoInput[];
+    /** Which todo is current (0-based). Rows before = done, after = pending. */
+    todoIndex?: number;
+    /** Heading above a single {@link StubCtx.todos} list. */
+    todoTitle?: string;
+    /**
+     * Stable dock id (`data-wg-todo-id`) for external redirect asserts
+     * (e.g. Mailhog -> back to app and still find the checklist).
+     */
+    todoId?: string;
+    /** `sequential` (default), `checklist`, or `bullets`. */
+    todoStyle?: TodoListStyle;
+    /** Multiple titled lists (FR / Scenarios / ACs). Wins over bare todos when set. */
+    todoGroups?: readonly WaygraphTodoGroupInput[];
+    /**
+     * Camera zoom (Screen Studio style) - scales the page toward the target /
+     * cursor. Not element CSS zoom. Typical `1.25` .. `2`.
+     */
+    zoom?: number;
+    /** Default zoomOut for rings (false = keep camera between rings). */
+    zoomOut?: boolean;
+    /** Top demo banner title (the purple "waygraph demo" card). */
+    title?: string;
+    /** Banner side/position (`left` | `center` | `right`). Authored control, like the todo dock's `pos`. */
+    titlePos?: BannerPos;
+    /** Banner UX: collision (move away from a ring it overlaps), hidden. See {@link BannerUiOpts}. */
+    bannerUi?: BannerUiOpts;
+    /**
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill, distinct from the banner (top, card-shaped). Omit/clear to hide it; set again
+     * to change the text, fading out/in.
+     */
+    caption?: string;
+    /**
+     * Network-tab overlay visibility - capture always happens in the background regardless; this
+     * only controls whether the panel itself is shown. Intentionally hidden by default (`undefined`
+     * on the very first phase); omit to leave whatever the previous step set alone.
+     */
+    networkTabVisible?: boolean;
+    /**
+     * Floating checklist dock side. `left` | `right`.
+     * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
+     */
+    todoPos?: "left" | "right";
+    /**
+     * Todo-dock UX (compact / collision / behind-ring). Merged onto env defaults.
+     * See {@link TodoDockUiOpts}.
+     */
+    todoDockUi?: TodoDockUiOpts;
+    /**
+     * Viewport preset: `mobile` | `tablet` | `desktop` (default / clear).
+     * Omit on later blocks = **keep** (same persist pattern as todos).
+     */
+    device?: DevicePreset | DeviceState;
+    /** Explicit pixel viewport (wins over preset width/height when both set). */
+    viewport?: DeviceViewport;
+    /** Touch theater + Playwright touchscreen when true. */
+    touch?: boolean;
+    /** Portrait / landscape (swaps preset width/height). */
+    orientation?: DeviceOrientation;
+};
+/**
+ * What a stub is given: chained where a flow uses a Block, it paints rings, todos, the device and the banner.
+ *
+ * @example
+ * LoginBlock.stubBefore((ctx) => {
+ *   ctx.todos("sign-in", ["Enter email", "Enter password", "Click Sign in"], { index: 0 });
+ *   ctx.zoom(1.35);
+ *   ctx.highlights({
+ *     email: { selector: "#email", label: "Email" },
+ *     submit: { selector: "#login-button", label: "Sign in" },
+ *   });
+ * })
+ * // Sequential plan: bump todoIndex in a later phase / a later Block's stubBefore
+ * .stubAfter((ctx) => {
+ *   ctx.todoIndex(2);
+ *   ctx.ring("inventory", { selector: ".inventory_list", label: "Landed" });
+ * });
+ */
+export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
+    /**
+     * Live Mem for this run - same store `act`/`observe` read. Prefer this over
+     * closing over outer scope or inventing parallel fixture bags.
+     * Undefined only if the caller ran a stub phase without passing mem (tests).
+     */
+    readonly mem: MemPage | undefined;
+    /** Present after resolve (stubAfter). Undefined for stubBefore. */
+    readonly out: Out | undefined;
+    /** Present on stubOnError when the step threw. */
+    readonly error: unknown | undefined;
+    /** Replace named highlight rings for this phase. */
+    highlights(slots: HighlightStubPhase): void;
+    /** Set / overwrite one named ring. */
+    ring(id: string, stub: WaygraphHighlightStub): void;
+    /**
+     * Floating checklist: `ctx.todos("login", ["Enter email", "Enter password"], { title: "Sign in", index: 0 })`.
+     * The id is the dock's `data-wg-todo-id` (stable through redirects). One dock at a time (setting todos replaces it);
+     * pass `{ parallel: true }` to keep docks with other ids. An empty list hides the dock.
+     */
+    todos(id: string, items: readonly WaygraphTodoInput[], opts?: WaygraphTodosOpts): void;
+    /** Moves the current dock's current item (sequential plans: a later step bumps it). */
+    todoIndex(n: number): void;
+    /** Several titled lists in one dock (e.g. Functional Requirements / Scenarios / ACs), with the same id and options as {@link StubCtx.todos}. */
+    todoGroups(id: string, groups: readonly WaygraphTodoGroupInput[], opts?: Omit<WaygraphTodosOpts, "index">): void;
+    /**
+     * Hide the floating todo dock. Omit todos on a later block = **keep** the
+     * previous dock (carry forward). Only hideTodos or an empty todos list clears it.
+     */
+    hideTodos(): void;
+    /**
+     * Viewport / device fixture (0.13+). `mobile` | `tablet` | `desktop`.
+     * Omit on later blocks = **keep** (same persist as todos). Use
+     * {@link StubCtx.hideDevice} or `device("desktop")` to return to desktop.
+     */
+    device(preset: DevicePreset | DeviceState): void;
+    /** Explicit CSS-pixel viewport (implies mobile-ish unless desktop-sized). */
+    viewport(box: DeviceViewport): void;
+    /** Enable / disable touch theater + touchscreen gestures. */
+    touch(on?: boolean): void;
+    /**
+     * Rotate viewport to portrait or landscape (0.13.3+).
+     * Keeps current preset; swaps width/height. Toast + lerp like device().
+     */
+    orientation(o: DeviceOrientation): void;
+    /**
+     * Reset to desktop viewport and clear touch mode. Omit device on a later
+     * block = **keep**; only hideDevice / device("desktop") clears.
+     */
+    hideDevice(): void;
+    /** Default camera zoom for rings without their own zoom. */
+    zoom(n: number): void;
+    /**
+     * Default zoomOut for rings in this phase. `false` = keep camera between rings.
+     */
+    zoomOut(keep: boolean): void;
+    /** Top banner title (waygraph demo card). `opts.pos` also places it (left | center | right). */
+    title(text: string, opts?: {
+        pos?: BannerPos;
+    }): void;
+    /** Place the banner: `left` | `center` | `right` (authored; click / env are fallbacks). */
+    titlePos(side: BannerPos): void;
+    /**
+     * Banner UX: `{ collision: false }` keeps it put even over a ring; `{ hidden: true }` hides it.
+     * @example ctx.bannerUi({ collision: false });
+     */
+    bannerUi(opts: BannerUiOpts): void;
+    /**
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill; distinct from {@link StubCtx.title}, which is the top banner card. Fades in/out
+     * on change. Pass `""` (or call {@link StubCtx.hideCaption}) to clear.
+     * @example ctx.caption("Click Add to cart to continue");
+     */
+    caption(text: string): void;
+    /** Clears the caption (fades it out). */
+    hideCaption(): void;
+    /** Shorthand for `bannerUi({ hidden: true })`. */
+    hideBanner(): void;
+    /**
+     * Shows the network-tab overlay (Postman-style inspector of real page traffic + defineApiBlock
+     * calls) - capture always runs in the background; this just reveals the panel. Hidden by default.
+     * @example ctx.showNetworkTab();
+     */
+    showNetworkTab(): void;
+    /** Hides the network-tab overlay (capture keeps running - only the panel disappears). */
+    hideNetworkTab(): void;
+    /**
+     * Todo-dock UX: compact fold, collision flip, dim-behind-ring.
+     * Defaults are smart-on; pass false fields to opt out for this phase.
+     * @example
+     * ctx.todoDockUi({ compact: false }); // always show the full list
+     */
+    todoDockUi(opts: TodoDockUiOpts): void;
+};
+/** A stub callback: receives the stub `ctx` and paints rings, titles and todos. */
+export type StubLifecycleFn<Out extends Checkpoint<string>> = (ctx: StubCtx<Out>) => void | Promise<void>;
+/** Result of running a stub phase (rings + episode fixtures). */
+export type StubPhaseResult = {
+    highlights: ResolvedHighlight[];
+    /** Flattened first-group items (compat). Prefer {@link todoDock}. */
+    todos: WaygraphTodoItem[];
+    todoIndex?: number;
+    todoDock?: TodoDockState;
+    /**
+     * Todo dock intent for this phase:
+     * - `set` - replace dock with {@link todoDock}
+     * - `clear` - hide dock (author called hideTodos / empty todos())
+     * - `keep` - author omitted todos; demo must leave previous dock alone
+     */
+    todoSync?: "set" | "clear" | "keep";
+    /** Todo-dock UX for this phase (when author called {@link StubCtx.todoDockUi}). */
+    todoDockUi?: TodoDockUiOpts;
+    /** Resolved device after this phase (undefined when keep with no prior). */
+    device?: DeviceState;
+    /**
+     * Device intent (mirror todoSync):
+     * - `set` - apply {@link device}
+     * - `clear` - reset to desktop (hideDevice / device desktop)
+     * - `keep` - author omitted device; demo must leave previous alone
+     */
+    deviceSync?: "set" | "clear" | "keep";
+    zoom?: number;
+    zoomOut?: boolean;
+    title?: string;
+    titlePos?: BannerPos;
+    bannerUi?: BannerUiOpts;
+    caption?: string;
+    networkTabVisible?: boolean;
+    todoPos?: "left" | "right";
+    /** When true, keep other docks (multi-todo). Default false = replace. */
+    todoParallel?: boolean;
+};
+/** Demo stub phase names. */
+export type HighlightStubPhaseName = "stubBefore" | "stubAfter" | "stubOnError";
+export type StubBagState = {
+    highlights: HighlightStubPhase;
+    todos?: readonly WaygraphTodoInput[] | undefined;
+    todoIndex?: number | undefined;
+    todoTitle?: string | undefined;
+    todoId?: string | undefined;
+    todoStyle?: TodoListStyle | undefined;
+    todoGroups?: readonly WaygraphTodoGroupInput[] | undefined;
+    /** Author touched the todo dock this phase (set or clear). */
+    todoTouched?: boolean | undefined;
+    /** Author asked to hide the dock. */
+    hideTodos?: boolean | undefined;
+    /** Author touched device this phase (set or clear). */
+    deviceTouched?: boolean | undefined;
+    /** Author asked to reset to desktop. */
+    hideDevice?: boolean | undefined;
+    device?: DeviceState | undefined;
+    /** Touch override when set via ctx.touch() alone or with device. */
+    touchOverride?: boolean | undefined;
+    /** Orientation override when set via ctx.orientation / landscape / portrait. */
+    orientationOverride?: DeviceOrientation | undefined;
+    zoom?: number | undefined;
+    zoomOut?: boolean | undefined;
+    title?: string | undefined;
+    titlePos?: BannerPos | undefined;
+    bannerUi?: BannerUiOpts | undefined;
+    caption?: string | undefined;
+    networkTabVisible?: boolean | undefined;
+    todoPos?: "left" | "right" | undefined;
+    /** Author patched todo-dock UX this phase. */
+    todoDockUi?: TodoDockUiOpts | undefined;
+    /** Keep sibling docks (compact todos opts.parallel). */
+    todoParallel?: boolean | undefined;
+};

package/dist/engine/stub/stub.js

@@ -0,0 +1 @@
+export {};

package/dist/engine/stub/todos.d.ts

@@ -0,0 +1,104 @@
+/**
+ * One checklist row for episode planning (demo panel).
+ * Set via {@link StubCtx.todos} / {@link StubCtx.todoIndex} inside the lifecycle.
+ */
+export type WaygraphTodoItem = {
+    text: string;
+    /**
+     * Stable id for external asserts / redirects (Mailhog, deep links).
+     * Stamped as `data-wg-todo-item` on the row.
+     */
+    id?: string;
+    /** Explicit done. If omitted, derived from todoIndex (index < todoIndex). */
+    done?: boolean;
+    /** Explicit current. If omitted, derived from todoIndex (index === todoIndex). */
+    current?: boolean;
+};
+/** One todo item as authored: a string or `{ id, text, done }`. */
+export type WaygraphTodoInput = string | WaygraphTodoItem;
+/**
+ * Dock list presentation:
+ * - `sequential` - arrow on current, strike done (demo walkthrough)
+ * - `checklist` - checkbox done/pending only (no current arrow; independent checks)
+ * - `bullets` - flat bullet list (no arrow/checkbox; open notes / trimmed dock)
+ */
+export type TodoListStyle = "sequential" | "checklist" | "bullets";
+/** One titled group in the floating todo dock (FR / Scenarios / ACs, etc.). */
+export type WaygraphTodoGroupInput = {
+    /** Stable group id -> `data-wg-todo-group`. */
+    id?: string;
+    /** Group heading shown above the items. */
+    title?: string;
+    /** Per-group style; falls back to dock default ({@link WaygraphTodosOpts.style}). */
+    style?: TodoListStyle;
+    items: readonly WaygraphTodoInput[];
+    /** Sequential only: which item is current (0-based). */
+    todoIndex?: number;
+};
+/** A titled checklist in the demo todo dock. */
+export type WaygraphTodoGroup = {
+    id?: string;
+    title?: string;
+    style: TodoListStyle;
+    items: WaygraphTodoItem[];
+};
+/** Full floating dock payload passed to the browser. */
+export type TodoDockState = {
+    /**
+     * Stable dock id for external targeting after redirects
+     * (`#wg-todo-dock[data-wg-todo-id="…"]`).
+     */
+    id?: string;
+    /** Default style for groups that omit their own. */
+    style: TodoListStyle;
+    /** Single-list title when using {@link StubCtx.todos} with `title`. */
+    title?: string;
+    groups: WaygraphTodoGroup[];
+    pos?: "left" | "right";
+};
+/** Options for compact {@link StubCtx.todos}(`id`, items, opts). */
+export type WaygraphTodosOpts = {
+    /** Dock heading. */
+    title?: string;
+    /** Current item index (0-based). */
+    index?: number;
+    /** `sequential` | `checklist` | `bullets`. */
+    style?: TodoListStyle;
+    /** Dock side. */
+    pos?: "left" | "right";
+    /**
+     * Keep other docks with different ids (multi-todo). Default false —
+     * one checklist at a time (setting todos replaces the previous dock).
+     */
+    parallel?: boolean;
+};
+/**
+ * Floating todo-dock UX knobs (0.15.8+). Defaults are **smart on** so long
+ * FR/AC checklists do not bury highlight rings. Opt out per phase or globally.
+ *
+ * Defaults: `compact`, `collision`, `behindRing` = true; `cap` = 5; `expandCap` = 14.
+ *
+ * Global: `WAYGRAPH_TODO_UI=full` / `waygraph demo --todo-full` turns smart off.
+ * Per-knob env: `WAYGRAPH_TODO_COMPACT=0`, `WAYGRAPH_TODO_COLLISION=0`,
+ * `WAYGRAPH_TODO_BEHIND=0`, `WAYGRAPH_TODO_CAP`, `WAYGRAPH_TODO_EXPAND_CAP`.
+ */
+export type TodoDockUiOpts = {
+    /** Fold long lists around the current row (+N more / hover). Default true. */
+    compact?: boolean;
+    /** Visible rows when compact. Default 5. */
+    cap?: number;
+    /** Visible rows on hover / pinned expand. Default 14. */
+    expandCap?: number;
+    /** Flip dock L/R when an active ring overlaps it. Default true. */
+    collision?: boolean;
+    /** Dim + lower z-index while a highlight ring is up. Default true. */
+    behindRing?: boolean;
+};
+/** Resolved todo-dock UX (all fields present). */
+export type TodoDockUiResolved = {
+    compact: boolean;
+    cap: number;
+    expandCap: number;
+    collision: boolean;
+    behindRing: boolean;
+};

package/dist/engine/stub/todos.js

@@ -0,0 +1,2 @@
+// The floating todo dock: its items, groups, and how it folds.
+export {};

package/dist/engine/stub/viewport.d.ts

@@ -0,0 +1,26 @@
+/** Named viewport presets (0.13+). */
+export type DevicePreset = "mobile" | "tablet" | "desktop";
+/** Explicit viewport box. */
+export type DeviceViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+/**
+ * Carried device fixture (todo-dock shaped persist).
+ * Omit on a later step = keep; hideDevice / desktop = clear to desktop.
+ */
+export type DeviceState = {
+    preset: DevicePreset;
+    viewport: DeviceViewport;
+    /** Playwright-ish: treat as mobile layout. */
+    isMobile: boolean;
+    /** Context needs hasTouch for touchscreen.tap (demo launches with hasTouch). */
+    hasTouch: boolean;
+    /** Demo gesture theater: finger cursor, tap/hold timing, prefer touchscreen. */
+    touchMode: boolean;
+    /** Viewport orientation (0.13.3+). Default derived from width/height. */
+    orientation?: DeviceOrientation;
+};
+/** Portrait (tall) or landscape (wide). */
+export type DeviceOrientation = "portrait" | "landscape";

package/dist/engine/stub/viewport.js

@@ -0,0 +1,2 @@
+// The device a stub puts the page in: preset, size, touch and orientation.
+export {};

package/dist/{trait.d.ts → engine/trait/trait.d.ts}

@@ -1,5 +1,5 @@
 import type { Page } from "@playwright/test";
-import type { MemPage } from "./mem-page.js";
+import type { MemPage } from "../mem/mem.js";
 import "urlpattern-polyfill";
 /**
  * A named, independently-reportable check. `check` never runs before `resolve` has

package/dist/index.d.ts

@@ -1,38 +1,86 @@
-export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInstanceOption } from "./types.js";
-export { connect, checkpoint } from "./types.js";
-export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
-export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
-export { css, byText, byRole } from "./selector.js";
-export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
-export type { WaygraphErrorCode } from "./errors.js";
-export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, withDialog, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
-export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./core/branch-regression.js";
-export type { ApiBlockOptions, ApiCallResult } from "./core/blocks/api.js";
-export type { MapStepOpts, MapFlowOpts } from "./core/map-builder.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, BannerPos, BannerUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
-export type { Flow, FlowOptions, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./core.js";
-export type { ActionPage } from "./types.js";
+import "./runtime/full-launch.js";
+import "./runtime/run-log.js";
+export type { Checkpoint, Start } from "./engine/checkpoint/checkpoint.js";
+export type { Instruction, Block, DefinedBlock, SomeBlock, SomeDefinedBlock, WaygraphInstanceOption } from "./engine/block/block.js";
+export { connect } from "./engine/run/connect.js";
+export { checkpoint } from "./engine/checkpoint/checkpoint.js";
+export { MemKey, MemPage, key, keyGroup } from "./engine/mem/mem.js";
+export { registerMemStub, seedMemStub, getMemStub } from "./engine/mem/mem-stub.js";
+export { css, byText, byRole } from "./engine/trait/selector.js";
+export { WaygraphError, WAYGRAPH_ERRORS } from "./engine/errors.js";
+export type { WaygraphErrorCode } from "./engine/errors.js";
+export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./engine/trait/trait.js";
+export { runGraph, spawnTab, narrate, preflight, defineLayout } from "./engine/run/run.js";
+export { Engine, map } from "./engine/engine.js";
+export { branch, withVerify, modVerify, modVerifyAll, defineBlock, withDialog } from "./engine/block/block.js";
+export { defineNavBlock, defineNavClickBlock, defineMemNavBlock } from "./engine/block/kinds/nav.js";
+export { defineMethodBlock, defineAssertBlock } from "./engine/block/kinds/method.js";
+export { definePageBlock } from "./engine/block/kinds/page.js";
+export { defineEffectBlock } from "./engine/block/kinds/effect.js";
+export { defineApiBlock } from "./engine/block/kinds/api.js";
+export { locate } from "./engine/locate.js";
+export { composeBlock, fastForwardComposeBlock, isFastForwardBlock } from "./engine/block/compose.js";
+export { MapBuilder } from "./engine/flow/map-builder.js";
+export { branchRoutes, collectBranchFlows, runBranchRegression } from "./engine/flow/branch-regression.js";
+export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./engine/flow/branch-regression.js";
+export type { ApiBlockOptions, ApiCallResult } from "./engine/block/kinds/api.js";
+export type { MapStepOpts, MapFlowOpts } from "./engine/flow/map-builder.js";
+export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.js";
+export { resolveFixtureDwellMs, normalizeDemoPace, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT } from "./demo/narration/demo-pace.js";
+export { formatHighlightCaption, applyHighlightStyleDefaults, toneIconPrefix } from "./demo/narration/style.js";
+export { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight } from "./engine/stub/ring.js";
+export { normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, resolveTodoDockUi } from "./demo/narration/todo-dock.js";
+export { applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS } from "./demo/narration/device.js";
+export { WAYGRAPH_RING_CSS } from "./demo/narration/css.js";
+export type { WaygraphHighlightStub, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, ResolvedHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults } from "./engine/stub/ring.js";
+export type { WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle } from "./engine/stub/todos.js";
+export type { BannerPos, BannerUiOpts, HighlightStubPhaseName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures } from "./engine/stub/stub.js";
+export type { DemoPace, DemoPaceName } from "./engine/stub/pace.js";
+export type { DevicePreset, DeviceViewport, DeviceState, DeviceOrientation } from "./engine/stub/viewport.js";
+export type { Flow, BlockInfo } from "./engine/flow/flow.js";
+export type { EngineConfig } from "./engine/config.js";
+export type { ComposedBlock, FastForwardComposedBlock } from "./engine/block/compose.js";
+export type { RunGraphOptions, Layout, LayoutOptions } from "./engine/run/run.js";
+export type { NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MemNavBlock } from "./engine/block/kinds/nav.js";
+export type { MethodBlock, AssertBlock, AssertBlockOptions } from "./engine/block/kinds/method.js";
+export type { PageBlock, PageBlockOptions, PageMethodEntry } from "./engine/block/kinds/page.js";
+export type { EffectBlock } from "./engine/block/kinds/effect.js";
+export type { MapBuilderOptions } from "./engine/flow/map-builder.js";
+export type { ActionPage } from "./engine/block/block.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
+export { buildManifest } from "./manifest/manifest.js";
+export { onRunEvent } from "./engine/run/events.js";
+export type { RunEvent } from "./engine/run/events.js";
+export type { Manifest, ManifestBlock, ManifestFlow } from "./manifest/manifest.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./analysis/graph.js";
-export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
-export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";
-export { EdgeLeaseCoordinator } from "./traverse/lease.js";
-export { runTraverse } from "./traverse/run.js";
-export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse/run.js";
-export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
-export type { TraverseCoverageReport } from "./traverse/coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
-export type { WgModalKind, WgBeaconRow } from "./session/overlay-beacon.js";
-export { AutoSession, stubFilePath } from "./auto-session.js";
-export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnapshotSection, ApplyPickResult, ApplyPathResult, TraceStep, ConsoleLogEntry, StorageSnapshot, ServiceWorkerRegistrationInfo, CookieInfo, StubFileKind, } from "./auto-session.js";
-export { pilotStart } from "./session/pilot.js";
-export type { PilotStartResult } from "./session/pilot.js";
-export { defineConfig, resolveBaseUrl } from "./config.js";
-export type { WaygraphConfig, ConfigContext, VideoSettings, RunSettings, DemoSettings } from "./config.js";
-export { withWebServer } from "./webserver.js";
-export { chromiumExecutablePath } from "./browser.js";
-export { resolveExtension, KNOWN_EXTENSIONS } from "./extensions.js";
-export type { ExtensionSpec } from "./extensions.js";
-export type { WebServerConfig } from "./webserver.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./manifest/select.js";
+export type { BlocksSelect, BlocksSelectKind } from "./manifest/select.js";
+export { EdgeLeaseCoordinator } from "./live/traverse/lease.js";
+export { runTraverse } from "./live/traverse/traverse.js";
+export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./live/traverse/traverse.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./live/traverse/coverage.js";
+export type { TraverseCoverageReport } from "./live/traverse/coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./demo/overlay/beacon.js";
+export type { WgModalKind, WgBeaconRow } from "./demo/overlay/beacon.js";
+export { AutoSession } from "./live/auto-session/auto-session.js";
+export { stubFilePath } from "./live/auto-session/helpers.js";
+export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnapshotSection, ApplyPickResult, ApplyPathResult, TraceStep, ConsoleLogEntry, StorageSnapshot, ServiceWorkerRegistrationInfo, CookieInfo, StubFileKind } from "./live/auto-session/helpers.js";
+export { pilotStart } from "./live/pilot/pilot.js";
+export type { PilotStartResult } from "./live/pilot/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./runtime/waygraph-config.js";
+export type { WaygraphConfig, ConfigContext, VideoSettings, RunSettings, DemoSettings } from "./runtime/waygraph-config.js";
+export { withWebServer } from "./runtime/webserver.js";
+export { chromiumExecutablePath } from "./runtime/browser.js";
+export { resolveExtension, KNOWN_EXTENSIONS } from "./runtime/extensions.js";
+export type { ExtensionSpec } from "./engine/config.js";
+export type { WebServerConfig } from "./runtime/webserver.js";
+export type { MapStart } from "./engine/engine.js";
+export type { WaygraphSlidesOrFn } from "./engine/stub/ring.js";
+export type { ConnectLayout } from "./engine/run/connect.js";
+export type { EffectExtras } from "./engine/block/kinds/effect.js";
+export type { BlockBase, RoutedBlockBase } from "./engine/checkpoint/route.js";
+export type { RunEventListener } from "./engine/run/events.js";
+export type { BlockKind, ScanOptions } from "./manifest/project.js";
+export type { DomSnapshot, InspectDomOptions, InspectDomResult } from "./live/auto-session/helpers.js";
+export type { BrowserStartInit } from "./live/auto-session/start.js";
+export type { PilotFixtureRing, PilotHighlightFixtures } from "./demo/overlay/pilot/fixtures.js";

package/dist/index.js

@@ -1,20 +1,45 @@
-export { connect, checkpoint } from "./types.js";
-export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
-export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
-export { css, byText, byRole } from "./selector.js";
-export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
-export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, withDialog, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
+// The runtime layer supplies how an Engine launches its own browser (config, Chromium path, extensions).
+import "./runtime/full-launch.js";
+// Run events are written to the project's run log (.waygraph/runs) when the CLI turns it on.
+import "./runtime/run-log.js";
+export { connect } from "./engine/run/connect.js";
+export { checkpoint } from "./engine/checkpoint/checkpoint.js";
+export { MemKey, MemPage, key, keyGroup } from "./engine/mem/mem.js";
+export { registerMemStub, seedMemStub, getMemStub } from "./engine/mem/mem-stub.js";
+export { css, byText, byRole } from "./engine/trait/selector.js";
+export { WaygraphError, WAYGRAPH_ERRORS } from "./engine/errors.js";
+export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./engine/trait/trait.js";
+export { runGraph, spawnTab, narrate, preflight, defineLayout } from "./engine/run/run.js";
+export { Engine, map } from "./engine/engine.js";
+export { branch, withVerify, modVerify, modVerifyAll, defineBlock, withDialog } from "./engine/block/block.js";
+export { defineNavBlock, defineNavClickBlock, defineMemNavBlock } from "./engine/block/kinds/nav.js";
+export { defineMethodBlock, defineAssertBlock } from "./engine/block/kinds/method.js";
+export { definePageBlock } from "./engine/block/kinds/page.js";
+export { defineEffectBlock } from "./engine/block/kinds/effect.js";
+export { defineApiBlock } from "./engine/block/kinds/api.js";
+export { locate } from "./engine/locate.js";
+export { composeBlock, fastForwardComposeBlock, isFastForwardBlock } from "./engine/block/compose.js";
+export { MapBuilder } from "./engine/flow/map-builder.js";
+export { branchRoutes, collectBranchFlows, runBranchRegression } from "./engine/flow/branch-regression.js";
+export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.js";
+export { resolveFixtureDwellMs, normalizeDemoPace, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT } from "./demo/narration/demo-pace.js";
+export { formatHighlightCaption, applyHighlightStyleDefaults, toneIconPrefix } from "./demo/narration/style.js";
+export { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight } from "./engine/stub/ring.js";
+export { normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, resolveTodoDockUi } from "./demo/narration/todo-dock.js";
+export { applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS } from "./demo/narration/device.js";
+export { WAYGRAPH_RING_CSS } from "./demo/narration/css.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
-export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
-export { EdgeLeaseCoordinator } from "./traverse/lease.js";
-export { runTraverse } from "./traverse/run.js";
-export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
-export { AutoSession, stubFilePath } from "./auto-session.js";
-export { pilotStart } from "./session/pilot.js";
-export { defineConfig, resolveBaseUrl } from "./config.js";
-export { withWebServer } from "./webserver.js";
-export { chromiumExecutablePath } from "./browser.js";
-export { resolveExtension, KNOWN_EXTENSIONS } from "./extensions.js";
+export { buildManifest } from "./manifest/manifest.js";
+export { onRunEvent } from "./engine/run/events.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./manifest/select.js";
+export { EdgeLeaseCoordinator } from "./live/traverse/lease.js";
+export { runTraverse } from "./live/traverse/traverse.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./live/traverse/coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./demo/overlay/beacon.js";
+export { AutoSession } from "./live/auto-session/auto-session.js";
+export { stubFilePath } from "./live/auto-session/helpers.js";
+export { pilotStart } from "./live/pilot/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./runtime/waygraph-config.js";
+export { withWebServer } from "./runtime/webserver.js";
+export { chromiumExecutablePath } from "./runtime/browser.js";
+export { resolveExtension, KNOWN_EXTENSIONS } from "./runtime/extensions.js";