waygraph 0.16.1 → 0.16.4

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

@@ -2,7 +2,7 @@ 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";
+import type { HighlightStubPhase, ResolvedHighlight, WaygraphHighlightStub, WaygraphSlide } 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. */
@@ -22,7 +22,7 @@ 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. */
+    /** Heading above a single {@link StubUi.todos} list. */
     todoTitle?: string;
     /**
      * Stable dock id (`data-wg-todo-id`) for external redirect asserts
@@ -85,17 +85,15 @@ export type StubPhaseFixtures = {
  *
  * @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" },
- *   });
+ *   ctx.ui.todos("sign-in", ["Enter email", "Enter password", "Click Sign in"], { index: 0 });
+ *   ctx.ui.zoom(1.35);
+ *   ctx.ui.ring("email", { selector: "#email", label: "Email" });
+ *   ctx.ui.ring("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" });
+ *   ctx.ui.todoIndex(2);
+ *   ctx.ui.ring("inventory", { selector: ".inventory_list", label: "Landed" });
  * });
  */
 export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
@@ -109,19 +107,22 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     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. */
+    /** Everything a stub paints in the demo: rings, todos, title, caption, device, zoom, network tab, slides. */
+    readonly ui: StubUi;
+};
+/** The demo UI a stub paints through: `ctx.ui.ring(...)`, `ctx.ui.todos(...)`, ... */
+export type StubUi = {
+    /** Paints one named ring this phase; the same id again replaces it. */
     ring(id: string, stub: WaygraphHighlightStub): void;
     /**
-     * Floating checklist: `ctx.todos("login", ["Enter email", "Enter password"], { title: "Sign in", index: 0 })`.
+     * Floating checklist: `ctx.ui.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}. */
+    /** Several titled lists in one dock (e.g. Functional Requirements / Scenarios / ACs), with the same id and options as {@link StubUi.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
@@ -131,7 +132,7 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     /**
      * 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.
+     * {@link StubUi.hideDevice} or `device("desktop")` to return to desktop.
      */
     device(preset: DevicePreset | DeviceState): void;
     /** Explicit CSS-pixel viewport (implies mobile-ish unless desktop-sized). */
@@ -162,24 +163,33 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     titlePos(side: BannerPos): void;
     /**
      * Banner UX: `{ collision: false }` keeps it put even over a ring; `{ hidden: true }` hides it.
-     * @example ctx.bannerUi({ collision: false });
+     * @example ctx.ui.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");
+     * the step pill; distinct from {@link StubUi.title}, which is the top banner card. Fades in/out
+     * on change. Pass `""` (or call {@link StubUi.hideCaption}) to clear.
+     * @example ctx.ui.caption("Click Add to cart to continue");
      */
     caption(text: string): void;
     /** Clears the caption (fades it out). */
     hideCaption(): void;
+    /**
+     * Multi-step "yap" captions with Next between each, for explaining a longer process. In `stubBefore` they play
+     * before the step runs, in `stubAfter` after it lands; a slide with a `selector` rings it while it is up.
+     * @example ctx.ui.slides([
+     *   { caption: "Checkout is three screens", tag: "YAP" },
+     *   { caption: "Overview confirms totals", selector: ".summary_info", duration: true },
+     * ]);
+     */
+    slides(slides: readonly WaygraphSlide[]): 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();
+     * @example ctx.ui.showNetworkTab();
      */
     showNetworkTab(): void;
     /** Hides the network-tab overlay (capture keeps running - only the panel disappears). */
@@ -188,7 +198,7 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
      * 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
+     * ctx.ui.todoDockUi({ compact: false }); // always show the full list
      */
     todoDockUi(opts: TodoDockUiOpts): void;
 };
@@ -208,7 +218,7 @@ export type StubPhaseResult = {
      * - `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}). */
+    /** Todo-dock UX for this phase (when author called {@link StubUi.todoDockUi}). */
     todoDockUi?: TodoDockUiOpts;
     /** Resolved device after this phase (undefined when keep with no prior). */
     device?: DeviceState;
@@ -226,6 +236,8 @@ export type StubPhaseResult = {
     bannerUi?: BannerUiOpts;
     caption?: string;
     networkTabVisible?: boolean;
+    /** Slides to play in this phase ({@link StubUi.slides}); empty when the stub set none. */
+    slides: WaygraphSlide[];
     todoPos?: "left" | "right";
     /** When true, keep other docks (multi-todo). Default false = replace. */
     todoParallel?: boolean;
@@ -249,9 +261,9 @@ export type StubBagState = {
     /** Author asked to reset to desktop. */
     hideDevice?: boolean | undefined;
     device?: DeviceState | undefined;
-    /** Touch override when set via ctx.touch() alone or with device. */
+    /** Touch override when set via ctx.ui.touch() alone or with device. */
     touchOverride?: boolean | undefined;
-    /** Orientation override when set via ctx.orientation / landscape / portrait. */
+    /** Orientation override when set via ctx.ui.orientation / landscape / portrait. */
     orientationOverride?: DeviceOrientation | undefined;
     zoom?: number | undefined;
     zoomOut?: boolean | undefined;
@@ -260,6 +272,7 @@ export type StubBagState = {
     bannerUi?: BannerUiOpts | undefined;
     caption?: string | undefined;
     networkTabVisible?: boolean | undefined;
+    slides?: readonly WaygraphSlide[] | undefined;
     todoPos?: "left" | "right" | undefined;
     /** Author patched todo-dock UX this phase. */
     todoDockUi?: TodoDockUiOpts | undefined;

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-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 } from "./engine/block/block.js";
 export type { WaygraphInstanceOption } from "./engine/block/action-page.js";
@@ -11,7 +9,7 @@ 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 { runGraph, spawnTab, preflight, defineLayout } from "./engine/run/run.js";
 export { Engine, map } from "./engine/engine.js";
 export { branch } from "./engine/block/branch.js";
 export { withVerify, modVerify, modVerifyAll, defineBlock } from "./engine/block/block.js";
@@ -29,7 +27,7 @@ export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from ".
 export type { ApiBlockOptions, ApiCallResult } from "./engine/block/kinds/api.js";
 export type { MapStepOpts } from "./engine/flow/map-steps.js";
 export type { MapFlowOpts } from "./engine/flow/map-builder.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.js";
+export { resolveHighlightSlots, 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";
@@ -55,7 +53,7 @@ export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./ana
 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 { Manifest, ManifestBlock, ManifestFlow, ManifestReadBlock } from "./manifest/manifest.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./analysis/graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp } from "./manifest/select.js";
 export type { BlocksSelect, BlocksSelectKind } from "./manifest/select.js";
@@ -67,6 +65,10 @@ 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 { SESSION_OPS, SESSION_PROTOCOL_VERSION } from "./live/auto-session/protocol.js";
+export type { SessionRequest, SessionResponse, SessionStreamMessage, HelloResponse } from "./live/auto-session/protocol.js";
+export { subscribeSession } from "./live/auto-session/feed.js";
+export { requestSession } from "./live/auto-session/ipc.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";
@@ -79,12 +81,12 @@ 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 { ScanOptions } from "./manifest/project.js";
+export type { BlockKind } from "./engine/block/kind.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,7 +1,9 @@
-// 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";
+import { installFullLaunch } from "./runtime/full-launch.js";
+import { installRunLog } from "./runtime/run-log.js";
+// The package entry wires the runtime in, explicitly: how an Engine launches its own browser (config, Chromium path,
+// extensions), and the run log (.waygraph/runs) the CLI turns on. No module switches itself on by being imported.
+installFullLaunch();
+installRunLog();
 export { connect } from "./engine/run/connect.js";
 export { checkpoint } from "./engine/checkpoint/checkpoint.js";
 export { MemKey, MemPage, key, keyGroup } from "./engine/mem/mem.js";
@@ -9,7 +11,7 @@ export { registerMemStub, seedMemStub, getMemStub } from "./engine/mem/mem-stub.
 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 { runGraph, spawnTab, preflight, defineLayout } from "./engine/run/run.js";
 export { Engine, map } from "./engine/engine.js";
 export { branch } from "./engine/block/branch.js";
 export { withVerify, modVerify, modVerifyAll, defineBlock } from "./engine/block/block.js";
@@ -23,7 +25,7 @@ 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 { resolveHighlightSlots, 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";
@@ -39,6 +41,9 @@ 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 { SESSION_OPS, SESSION_PROTOCOL_VERSION } from "./live/auto-session/protocol.js";
+export { subscribeSession } from "./live/auto-session/feed.js";
+export { requestSession } from "./live/auto-session/ipc.js";
 export { stubFilePath } from "./live/auto-session/helpers.js";
 export { pilotStart } from "./live/pilot/pilot.js";
 export { defineConfig, resolveBaseUrl } from "./runtime/waygraph-config.js";

package/dist/live/auto/auto.js

@@ -61,8 +61,6 @@ export async function runOneBlock(engine, entry, context, page, mem, headful) {
     await page.evaluate("delete window.__wgPendingNavClickLabel").catch(ignorePageGone);
     return result;
 }
-/** Shown in the headful panel after each Block run. */
-let lastRunNote = null;
 /**
  * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
  */
@@ -70,7 +68,8 @@ export async function runAutoExplore(projectDir, options = {}) {
     await withWebServer(projectDir, () => runAutoExploreCore(projectDir, options));
 }
 async function runAutoExploreCore(projectDir, options = {}) {
-    lastRunNote = null;
+    /** Shown in the headful panel after each Block run. */
+    let lastRunNote = null;
     const cli = options.cli === true;
     const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? envString("WAYGRAPH_BASE_URL");
     const startUrl = options.startUrl ?? baseURL;

package/dist/live/auto/menu.js

@@ -27,8 +27,9 @@ export async function setAutoPanelRunning(page, label) {
     }, label)
         .catch(ignorePageGone);
 }
-export const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
-    "max-width:min(92vw,720px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
+// In the bottom-center slot of the overlay layout (demo/overlay/ui/css/layout.css), like the demo's step panel.
+export const PANEL_CSS = "#wg-auto-panel{z-index:var(--wg-z-top);" +
+    "width:min(92vw,720px);overflow-y:auto;box-sizing:border-box;" +
     "background:rgba(20,10,40,.94);color:#fff;border-radius:14px;padding:16px 20px;" +
     "font:14px/1.4 system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35);}" +
     "#wg-auto-panel h3{margin:0 0 10px;font-size:16px;}" +

package/dist/live/auto-session/auto-session.d.ts

@@ -1,5 +1,6 @@
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
+import { type SessionRead } from "./read.js";
 /**
  * A live session driven over IPC (`browser start`, `pilot start`): the same graph, library, mem and browser as
  * `waygraph auto`, moved one call at a time (`applyPick`, `applyPath`, the raw actions) instead of a menu loop.
@@ -17,12 +18,12 @@ export declare class AutoSession {
     private page;
     private readonly startUrl;
     private readonly sessionId;
+    private readonly knownInteractionSelectors;
+    private readonly headless;
     private here;
     private lastRunNote;
     private readonly trace;
     private readonly consoleLog;
-    private readonly knownInteractionSelectors;
-    private readonly headless;
     private lastOverlayInfo;
     private constructor();
     static start(init: AutoSessionInit): Promise<AutoSession>;
@@ -43,8 +44,14 @@ export declare class AutoSession {
      * Deduped per page load so repeated status/send calls stay quiet.
      */
     private warnUnmappedInteractions;
+    /** The Checkpoint the session is at, if known. */
+    get where(): string | null;
     /** Pure getter - no Block runs, no mem/page mutation. */
     currentSnapshot(): Promise<SessionSnapshot>;
+    /** The menu as a snapshot, with what the page shows (Read Blocks) when any covers it. */
+    private snapshotOf;
+    /** Pure getter - what the page shows, from the project's Read Blocks (beta). */
+    read(path?: string): Promise<SessionRead>;
     /**
      * Pure getter - reads the live page's structure at the requested fidelity.
      * No Block runs, no mem/page mutation. `selector` scopes either mode to one

package/dist/live/auto-session/auto-session.js

@@ -3,7 +3,7 @@ import { findBlockPathDetailed } from "../../analysis/graph.js";
 import { runStubPhase } from "../../demo/narration/narration.js";
 import { describeOverlayFixtures, phaseToOverlayFixtures } from "../../demo/overlay/phase-fixtures.js";
 import { showPilotFixtures } from "../../demo/overlay/pilot/fixtures.js";
-import { showPilotActivity, showPilotVision } from "../../demo/overlay/pilot/shell.js";
+import { showPilotActivity } from "../../demo/overlay/pilot/shell.js";
 import { keepOverlayOnNavigation } from "../../demo/overlay/reattach.js";
 import { verboseLog } from "../../demo/verbose-log.js";
 import { Engine } from "../../engine/engine.js";
@@ -15,17 +15,10 @@ import { buildExploreContext, buildExploreMenu } from "../auto/explore.js";
 import { ensureMem, seedDefaultMem } from "../auto/mem.js";
 import { updatePilotOverlay } from "../pilot/panel.js";
 import { recordPageConsole } from "./console.js";
-import { CONSOLE_LOG_MAX_ENTRIES, TRACE_MAX_STEPS, buildSessionSnapshot, describeHighlight, parsePick, stubFilePath, stubPhaseHasContent } from "./helpers.js";
+import { CONSOLE_LOG_MAX_ENTRIES, TRACE_MAX_STEPS, buildSessionSnapshot, describeHighlight, parsePick, rawTarget, stubFilePath, stubPhaseHasContent } from "./helpers.js";
 import { inspectDom, inspectStorage } from "./inspect.js";
 import { openSessionBrowser } from "./open-browser.js";
-/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
-async function rawTarget(page, selector, label) {
-    const locator = page.locator(selector).first();
-    if ((await locator.count()) === 0)
-        return `no element matches selector "${selector}"`;
-    await showPilotVision(page, selector, label);
-    return locator;
-}
+import { readSession, snapshotRead } from "./read.js";
 /**
  * A live session driven over IPC (`browser start`, `pilot start`): the same graph, library, mem and browser as
  * `waygraph auto`, moved one call at a time (`applyPick`, `applyPath`, the raw actions) instead of a menu loop.
@@ -43,12 +36,12 @@ export class AutoSession {
     page;
     startUrl;
     sessionId;
+    knownInteractionSelectors;
+    headless;
     here = null;
     lastRunNote = null;
     trace = [];
     consoleLog = [];
-    knownInteractionSelectors;
-    headless;
     lastOverlayInfo = null;
     constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
         this.projectDir = projectDir;
@@ -118,7 +111,7 @@ export class AutoSession {
         // watching sees the state an API caller just got back, not a frame behind.
         this.lastOverlayInfo = {
             sessionId: this.sessionId,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(menu),
             graph: this.graph,
         };
         await updatePilotOverlay(this.page, this.lastOverlayInfo);
@@ -163,10 +156,20 @@ export class AutoSession {
         };
         await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(ignorePageGone);
     }
+    /** The Checkpoint the session is at, if known. */
+    get where() { return this.here; }
     /** Pure getter - no Block runs, no mem/page mutation. */
     async currentSnapshot() {
-        const menu = await this.currentMenu();
-        return buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote);
+        return this.snapshotOf(await this.currentMenu());
+    }
+    /** The menu as a snapshot, with what the page shows (Read Blocks) when any covers it. */
+    async snapshotOf(menu) {
+        return { ...buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote), ...(await snapshotRead(this.page, this.mem, this.here)) };
+    }
+    /** Pure getter - what the page shows, from the project's Read Blocks (beta). */
+    async read(path) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        return readSession(this.page, this.mem, this.here, path);
     }
     /**
      * Pure getter - reads the live page's structure at the requested fidelity.
@@ -238,7 +241,7 @@ export class AutoSession {
         const nextMenu = await this.currentMenu();
         return {
             ok: true,
-            snapshot: buildSessionSnapshot(nextMenu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(nextMenu),
             quit: false,
         };
     }
@@ -251,7 +254,7 @@ export class AutoSession {
         if (pick.type === "quit") {
             return {
                 ok: true,
-                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+                snapshot: await this.snapshotOf(menu),
                 quit: true,
             };
         }
@@ -292,7 +295,7 @@ export class AutoSession {
         this.lastRunNote = `resync -> ${this.here ?? "Unknown"}`;
         return {
             ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(menu),
             quit: false,
         };
     }
@@ -363,7 +366,7 @@ export class AutoSession {
         this.lastRunNote = `${what} -> ${this.here ?? "Unknown"}`;
         return {
             ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(menu),
             quit: false,
         };
     }
@@ -390,7 +393,7 @@ export class AutoSession {
                 ok: true,
                 painted,
                 missing,
-                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+                snapshot: await this.snapshotOf(menu),
             };
         }
         catch (err) {

package/dist/live/auto-session/feed.d.ts

@@ -0,0 +1,16 @@
+import { type Socket } from "node:net";
+import type { SessionStreamMessage } from "./protocol.js";
+/** The server side: subscribed sockets, fed every run event in this process until `close`. */
+export declare function createFeed(): {
+    add(sock: Socket): void;
+    send(message: SessionStreamMessage): void;
+    close(): void;
+};
+/**
+ * The client side: subscribes to a running session and calls `onMessage` for each line until `close()` (or the session
+ * ends). Rejects when the session is unknown or does not answer the subscribe.
+ */
+export declare function subscribeSession(projectDir: string, sessionId: string, onMessage: (message: SessionStreamMessage) => void, timeoutMs?: number): Promise<{
+    close(): void;
+    closed: Promise<void>;
+}>;

package/dist/live/auto-session/feed.js

@@ -0,0 +1,71 @@
+// A session's live feed (`subscribe`): every run event in the session (steps, reads) and the snapshot after each change,
+// as JSON lines to every subscribed socket. Waygraph UI watches a session through it; `pilot watch <id>` prints it.
+import { connect } from "node:net";
+import { onRunEvent } from "../../engine/run/events.js";
+import { resolveSessionMeta } from "./files.js";
+import { SESSION_PROTOCOL_VERSION } from "./protocol.js";
+/** The server side: subscribed sockets, fed every run event in this process until `close`. */
+export function createFeed() {
+    const subscribers = new Set();
+    const send = (message) => {
+        const line = JSON.stringify(message) + "\n";
+        for (const sock of subscribers)
+            if (!sock.destroyed)
+                sock.write(line);
+    };
+    const off = onRunEvent((event) => send({ type: "event", event }));
+    return {
+        add(sock) {
+            subscribers.add(sock);
+            sock.on("close", () => subscribers.delete(sock));
+            sock.write(JSON.stringify({ ok: true, protocol: SESSION_PROTOCOL_VERSION }) + "\n");
+        },
+        send,
+        close() {
+            off();
+            for (const sock of subscribers)
+                sock.end();
+            subscribers.clear();
+        },
+    };
+}
+/**
+ * The client side: subscribes to a running session and calls `onMessage` for each line until `close()` (or the session
+ * ends). Rejects when the session is unknown or does not answer the subscribe.
+ */
+export function subscribeSession(projectDir, sessionId, onMessage, timeoutMs = 15_000) {
+    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (!meta)
+        return Promise.reject(new Error(`no such session "${sessionId}" - \`waygraph pilot sessions\` lists live ids`));
+    return new Promise((resolve, reject) => {
+        const sock = connect(meta.socketPath);
+        const timer = setTimeout(() => {
+            sock.destroy();
+            reject(new Error(`session "${sessionId}" did not answer subscribe within ${timeoutMs}ms`));
+        }, timeoutMs);
+        const closed = new Promise((done) => sock.on("close", () => done()));
+        let buf = "";
+        let acked = false;
+        sock.on("connect", () => sock.write(JSON.stringify({ op: "subscribe" }) + "\n"));
+        sock.on("error", (err) => {
+            clearTimeout(timer);
+            if (!acked)
+                reject(err);
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf-8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) !== -1) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!acked) {
+                    acked = true;
+                    clearTimeout(timer);
+                    resolve({ close: () => sock.end(), closed });
+                    continue;
+                }
+                onMessage(JSON.parse(line));
+            }
+        });
+    });
+}

package/dist/live/auto-session/helpers.d.ts

@@ -1,3 +1,4 @@
+import type { Locator, Page } from "@playwright/test";
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 import type { StubPhaseResult } from "../../engine/stub/stub.js";
 import type { BlockEntry } from "../../manifest/project.js";
@@ -27,6 +28,10 @@ export interface SessionSnapshot {
     /** True when there are no runnable moves from `here` right now. */
     done: boolean;
     lastRunNote: string | null;
+    /** What the page shows, from the project's Read Blocks (beta); absent when none covers this page. */
+    read?: Record<string, unknown>;
+    missing?: string[];
+    readNotes?: Record<string, string>;
 }
 /** Plain, JSON-serializable view of a menu - no Block/MemKey/class references. */
 export declare function buildSessionSnapshot(menu: ExploreMenu, library: Map<string, BlockEntry>, here: string | null, lastRunNote: string | null): SessionSnapshot;
@@ -214,4 +219,6 @@ export interface StorageSnapshot {
 }
 /** What a highlight call paints, in a few words, for the session's activity line. */
 export declare function describeHighlight(fixtures: PilotHighlightFixtures): string;
+/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
+export declare function rawTarget(page: Page, selector: string, label: string): Promise<Locator | string>;
 export {};

package/dist/live/auto-session/helpers.js

@@ -1,6 +1,7 @@
 // The session's shared shapes and pure helpers: snapshots, picks, trace / console entries, DOM walking, stub files.
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { showPilotVision } from "../../demo/overlay/pilot/shell.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 export function stubPhaseHasContent(r) {
     return (Object.keys(r.highlights).length > 0 ||
@@ -163,3 +164,11 @@ export function describeHighlight(fixtures) {
         .filter(Boolean)
         .join(", ") || "fixtures");
 }
+/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
+export async function rawTarget(page, selector, label) {
+    const locator = page.locator(selector).first();
+    if ((await locator.count()) === 0)
+        return `no element matches selector "${selector}"`;
+    await showPilotVision(page, selector, label);
+    return locator;
+}