waygraph 0.16.2 → 0.16.4

package/dist/engine/read/run-read.js

@@ -0,0 +1,156 @@
+import { ignorePageGone, ignoreTimeout } from "../page-gone.js";
+import { Reader } from "./readers.js";
+/** In the page (self-contained, shipped by evaluateAll): reads a field, list rows or a table from the matched elements. */
+function readInPage(matched, ask) {
+    const shown = (el) => {
+        const box = el.getBoundingClientRect();
+        const style = getComputedStyle(el);
+        return box.width > 0 && box.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+    };
+    // textContent, whitespace collapsed: innerText forces layout per element (125ms vs 3ms for 8,000 table cells).
+    const textOf = (el) => (el.textContent ?? "").replace(/\s+/g, " ").trim();
+    const take = (els, plan) => {
+        const first = els[0];
+        switch (plan.kind) {
+            case "count":
+                return els.length;
+            case "visible":
+                return els.some(shown);
+            case "texts":
+                return els.map(textOf);
+            case "attr":
+                return first ? first.getAttribute(plan.attr ?? "") : null;
+            case "value":
+                return first && "value" in first ? String(first.value) : null;
+            default:
+                // text, and number (parsed in Node from the text)
+                return first ? textOf(first) : null;
+        }
+    };
+    const within = (root, plan) => (plan.selector ? [...root.querySelectorAll(plan.selector)] : [root]);
+    if (ask.mode === "field")
+        return take(matched, ask.plan);
+    if (ask.mode === "list") {
+        return matched.map((row) => {
+            const out = {};
+            for (const [name, plan] of Object.entries(ask.fields))
+                out[name] = take(within(row, plan), plan);
+            return out;
+        });
+    }
+    const table = matched[0];
+    if (!table)
+        return null;
+    const HEAD = "th, [role=columnheader]";
+    const CELL = "td, th, [role=cell], [role=gridcell], [role=rowheader], [role=columnheader]";
+    const rows = [...table.querySelectorAll("tr, [role=row]")];
+    const headRow = rows.find((r) => r.querySelector(HEAD) && !r.querySelector("td, [role=cell], [role=gridcell]"));
+    const headers = headRow ? [...headRow.querySelectorAll(CELL)].map(textOf) : [];
+    const index = {};
+    const absent = [];
+    for (const [name, header] of Object.entries(ask.columns)) {
+        const at = headers.findIndex((h) => h.toLowerCase() === header.toLowerCase());
+        if (at < 0)
+            absent.push(name);
+        else
+            index[name] = at;
+    }
+    const body = rows.filter((r) => r !== headRow && r.querySelector("td, [role=cell], [role=gridcell], [role=rowheader]"));
+    const out = body.map((r) => {
+        const cells = [...r.querySelectorAll(CELL)];
+        const row = {};
+        for (const name of Object.keys(ask.columns)) {
+            const cell = index[name] === undefined ? undefined : cells[index[name]];
+            row[name] = cell ? textOf(cell) : null;
+        }
+        return row;
+    });
+    const declared = Number(table.getAttribute("aria-rowcount"));
+    return { rows: out, absent, rowCount: Number.isFinite(declared) && declared > 0 ? declared - (headRow ? 1 : 0) : out.length };
+}
+/** In the page: resolves once the DOM has had no change for `quietMs` (or after `capMs`, whichever comes first). */
+function domQuiet({ quietMs, capMs }) {
+    return new Promise((resolve) => {
+        const done = () => {
+            observer.disconnect();
+            clearTimeout(quiet);
+            clearTimeout(cap);
+            resolve();
+        };
+        let quiet = setTimeout(done, quietMs);
+        const cap = setTimeout(done, capMs);
+        const observer = new MutationObserver(() => {
+            clearTimeout(quiet);
+            quiet = setTimeout(done, quietMs);
+        });
+        observer.observe(document, { subtree: true, childList: true, characterData: true, attributes: true });
+    });
+}
+/**
+ * Waits for the page to stop changing before a read. A step's verify can pass before the app has rendered where it
+ * landed (a URL check passes the moment a client-side route changes), so a read right after it can see the old page.
+ */
+export async function settlePage(page, quietMs = 150, capMs = 2000) {
+    await page.waitForLoadState("domcontentloaded", { timeout: capMs }).catch(ignoreTimeout);
+    await page.evaluate(domQuiet, { quietMs, capMs }).catch(ignorePageGone);
+}
+/** The first number in a display text: `"$1,299.00"` -> 1299, `"41 likes"` -> 41, no number -> null. */
+export function firstNumber(text) {
+    if (typeof text !== "string")
+        return null;
+    const m = /-?\d[\d,]*(?:\.\d+)?/.exec(text);
+    return m ? Number(m[0].replace(/,/g, "")) : null;
+}
+function finishField(plan, raw) {
+    return plan.kind === "number" ? firstNumber(raw) : raw;
+}
+async function readOne(page, mem, plan, path, notes) {
+    if (plan.kind === "fn")
+        return (await plan.fn(page, mem)) ?? null;
+    const matched = page.locator(plan.selector);
+    if (plan.kind === "list") {
+        const rows = (await matched.evaluateAll(readInPage, { mode: "list", fields: plan.fields }));
+        return rows.map((row) => {
+            for (const [name, field] of Object.entries(plan.fields))
+                row[name] = finishField(field, row[name]);
+            return row;
+        });
+    }
+    if (plan.kind === "table") {
+        const got = (await matched.evaluateAll(readInPage, { mode: "table", columns: plan.columns }));
+        if (!got)
+            return null;
+        const why = [];
+        if (got.absent.length)
+            why.push(`no column ${got.absent.map((c) => JSON.stringify(plan.columns[c])).join(", ")}`);
+        if (got.rowCount > got.rows.length)
+            why.push(`${got.rows.length} of ${got.rowCount} rows rendered (scroll or page to read more)`);
+        if (why.length)
+            notes.set(path, why.join("; "));
+        return got.rows;
+    }
+    return finishField(plan, await matched.evaluateAll(readInPage, { mode: "field", plan }));
+}
+/** Reads every field of every spec, in parallel, into leaves by path. */
+export async function runReadSpecs(page, mem, specs) {
+    const values = new Map();
+    const notes = new Map();
+    const jobs = [];
+    const walk = (fields, prefix) => {
+        for (const [name, value] of Object.entries(fields)) {
+            if (value === undefined)
+                continue;
+            const path = `${prefix}.${name}`;
+            if (value instanceof Reader) {
+                values.set(path, null);
+                jobs.push(readOne(page, mem, value.plan, path, notes).then((v) => void values.set(path, v)));
+            }
+            else
+                walk(value, path);
+        }
+    };
+    for (const spec of specs)
+        walk(spec.fields, spec.namespace);
+    await Promise.all(jobs);
+    return { values, notes };
+}

package/dist/engine/run/connect.js

@@ -1,5 +1,6 @@
 import { runVerify, runPrecondition } from "../trait/trait.js";
 import { isConnected, lastLeaf, stepEnded, stepStarted } from "./events.js";
+import { blockKindOf } from "../block/kind.js";
 /**
  * Composes two Blocks into one, typechecked so this only compiles when A's output
  * tag equals B's input tag. The composed Block's act runs A's full instruction
@@ -25,7 +26,7 @@ export function connect(a, b, layouts) {
         instruction: {
             async act(page, input, mem) {
                 if (!isConnected(a))
-                    stepStarted(a.name, input.__state);
+                    stepStarted(a.name, blockKindOf(a), input.__state);
                 await runPrecondition(a.instruction.precondition, input, page, mem, a.name);
                 await a.instruction.act(page, input, mem);
                 const aObserved = a.instruction.observe
@@ -42,7 +43,7 @@ export function connect(a, b, layouts) {
                 }
                 stepEnded(lastLeaf(a), mid.__state);
                 if (!isConnected(b))
-                    stepStarted(b.name, mid.__state);
+                    stepStarted(b.name, blockKindOf(b), mid.__state);
                 await runPrecondition(b.instruction.precondition, mid, page, mem, b.name);
                 await b.instruction.act(page, mid, mem);
             },

package/dist/engine/run/events.d.ts

@@ -1,3 +1,4 @@
+import type { BlockKind } from "../block/kind.js";
 export type RunEvent = {
     type: "run:start";
     runId: string;
@@ -9,6 +10,7 @@ export type RunEvent = {
     at: number;
     index: number;
     block: string;
+    kind: BlockKind;
     from: string;
 } | {
     type: "step:end";
@@ -16,6 +18,7 @@ export type RunEvent = {
     at: number;
     index: number;
     block: string;
+    kind: BlockKind;
     to: string;
     ms: number;
 } | {
@@ -24,9 +27,18 @@ export type RunEvent = {
     at: number;
     index: number;
     block: string;
+    kind: BlockKind;
     error: string;
     ms: number;
-} | {
+} | ({
+    type: "step:read";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    kind: BlockKind;
+    checkpoint: string;
+} & StepRead) | {
     type: "run:end";
     runId: string;
     at: number;
@@ -41,22 +53,28 @@ export type RunEvent = {
     kind: "video" | "trace" | "screenshot";
     path: string;
 };
+/** What the page showed after a step, from the Read Blocks for the Checkpoint it landed on (beta). */
+export interface StepRead {
+    read: Record<string, unknown>;
+    missing: string[];
+    notes: Record<string, string>;
+    readBlocks: string[];
+    /** A Read Block that failed (two reading one key, say): the step still ran; the read is empty. */
+    error?: string;
+}
 /** What {@link onRunEvent} calls with each event. */
 export type RunEventListener = (event: RunEvent) => void;
 /** Subscribes to every run event in this process; returns the unsubscribe function. */
 export declare function onRunEvent(listener: RunEventListener): () => void;
 /**
- * Opens a run, or joins the one already open (a flow nested in another, or a runner driving a chain step by step). Returns
- * whether this call opened it, so only the opener closes it.
+ * Runs `body` as a run: opens one (`run:start` ... `run:end`), or joins the run its caller is already in (a flow nested in
+ * another, a runner driving a chain step by step). `resultOf` names the outcome for `run:end`.
  */
-export declare function beginRun(label?: string): boolean;
-/** Closes the run when the matching `beginRun` opened it. */
-export declare function endRun(opened: boolean, outcome: {
-    result?: string;
-    error?: unknown;
-}): void;
-export declare function stepStarted(block: string, from: string): void;
+export declare function inRun<T>(label: string | undefined, body: () => Promise<T>, resultOf?: (value: T) => string | undefined): Promise<T>;
+export declare function stepStarted(block: string, kind: BlockKind, from: string): void;
 export declare function stepEnded(block: string, to: string): void;
+/** What the page showed after the current step (emitted between its verify and its `step:end`). */
+export declare function stepRead(checkpoint: string, read: StepRead): void;
 /** The step that started last failed. */
 export declare function stepFailed(error: unknown): void;
 /** The id of the run open right now, if any. */

package/dist/engine/run/events.js

@@ -1,5 +1,6 @@
 // Run events: what happened, step by step, during a run. Core emits them; subscribers (the run log, the demo overlay,
 // reports, Waygraph UI) listen. Emitting never throws into the run.
+import { AsyncLocalStorage } from "node:async_hooks";
 const listeners = new Set();
 /** Subscribes to every run event in this process; returns the unsubscribe function. */
 export function onRunEvent(listener) {
@@ -16,68 +17,81 @@ function emit(event) {
         }
     }
 }
-let open;
 /**
- * Opens a run, or joins the one already open (a flow nested in another, or a runner driving a chain step by step). Returns
- * whether this call opened it, so only the opener closes it.
+ * The run each async call chain is in. Per chain, not per process: two runs at once (parallel traverse workers, a UI
+ * hosting several) each get their own id and step counter; a flow nested in another joins its parent's run.
  */
-export function beginRun(label) {
-    if (open) {
-        open.depth += 1;
-        return false;
-    }
-    const at = Date.now();
-    open = { runId: `${new Date(at).toISOString().replace(/[:.]/g, "-")}-${crypto.randomUUID().slice(0, 8)}`, startedAt: at, depth: 1, index: 0 };
-    emit({ type: "run:start", runId: open.runId, at, ...(label ? { label } : {}) });
-    return true;
-}
-/** Closes the run when the matching `beginRun` opened it. */
-export function endRun(opened, outcome) {
-    if (!open)
-        return;
-    open.depth -= 1;
-    if (!opened)
-        return;
+const scope = new AsyncLocalStorage();
+/**
+ * Runs `body` as a run: opens one (`run:start` ... `run:end`), or joins the run its caller is already in (a flow nested in
+ * another, a runner driving a chain step by step). `resultOf` names the outcome for `run:end`.
+ */
+export async function inRun(label, body, resultOf) {
+    if (scope.getStore())
+        return body();
     const at = Date.now();
-    emit({
-        type: "run:end",
-        runId: open.runId,
-        at,
-        ok: outcome.error === undefined,
-        ...(outcome.result !== undefined ? { result: outcome.result } : {}),
-        ...(outcome.error !== undefined ? { error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) } : {}),
-        ms: at - open.startedAt,
-    });
-    open = undefined;
+    const run = { runId: `${new Date(at).toISOString().replace(/[:.]/g, "-")}-${crypto.randomUUID().slice(0, 8)}`, startedAt: at, index: 0 };
+    emit({ type: "run:start", runId: run.runId, at, ...(label ? { label } : {}) });
+    const end = (outcome) => {
+        const done = Date.now();
+        emit({
+            type: "run:end",
+            runId: run.runId,
+            at: done,
+            ok: !("error" in outcome),
+            ...(outcome.result !== undefined ? { result: outcome.result } : {}),
+            ...("error" in outcome ? { error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) } : {}),
+            ms: done - run.startedAt,
+        });
+    };
+    try {
+        const value = await scope.run(run, body);
+        end({ result: resultOf?.(value) });
+        return value;
+    }
+    catch (err) {
+        end({ error: err });
+        throw err;
+    }
 }
-export function stepStarted(block, from) {
+export function stepStarted(block, kind, from) {
+    const open = scope.getStore();
     if (!open)
         return;
     const at = Date.now();
-    open.step = { index: open.index++, block, startedAt: at };
-    emit({ type: "step:start", runId: open.runId, at, index: open.step.index, block, from });
+    open.step = { index: open.index++, block, kind, startedAt: at };
+    emit({ type: "step:start", runId: open.runId, at, index: open.step.index, block, kind, from });
 }
 export function stepEnded(block, to) {
+    const open = scope.getStore();
     if (!open?.step)
         return;
     const at = Date.now();
-    emit({ type: "step:end", runId: open.runId, at, index: open.step.index, block, to, ms: at - open.step.startedAt });
+    emit({ type: "step:end", runId: open.runId, at, index: open.step.index, block, kind: open.step.kind, to, ms: at - open.step.startedAt });
     open.step = undefined;
 }
+/** What the page showed after the current step (emitted between its verify and its `step:end`). */
+export function stepRead(checkpoint, read) {
+    const open = scope.getStore();
+    if (!open?.step)
+        return;
+    emit({ type: "step:read", runId: open.runId, at: Date.now(), index: open.step.index, block: open.step.block, kind: open.step.kind, checkpoint, ...read });
+}
 /** The step that started last failed. */
 export function stepFailed(error) {
+    const open = scope.getStore();
     if (!open?.step)
         return;
     const at = Date.now();
-    const { index, block, startedAt } = open.step;
-    emit({ type: "step:error", runId: open.runId, at, index, block, error: error instanceof Error ? error.message : String(error), ms: at - startedAt });
+    const { index, block, kind, startedAt } = open.step;
+    emit({ type: "step:error", runId: open.runId, at, index, block, kind, error: error instanceof Error ? error.message : String(error), ms: at - startedAt });
     open.step = undefined;
 }
 /** The id of the run open right now, if any. */
 export function currentRunId() {
-    return open?.runId;
+    return scope.getStore()?.runId;
 }
-export function recordArtifact(kind, path, runId = open?.runId) {
+export function recordArtifact(kind, path, runId = scope.getStore()?.runId) {
     if (runId)
         emit({ type: "run:artifact", runId, at: Date.now(), kind, path });
 }

package/dist/engine/run/run.js

@@ -1,6 +1,8 @@
 import { WaygraphError, MSG_PREFLIGHT_MISSING_KEY, MSG_RUNGRAPH_MAX_STEPS, MSG_RUNGRAPH_NOT_TERMINAL } from "../errors.js";
 import { checkpoint } from "../checkpoint/checkpoint.js";
-import { beginRun, endRun, isConnected, lastLeaf, stepEnded, stepFailed, stepStarted } from "./events.js";
+import { inRun, isConnected, lastLeaf, stepEnded, stepFailed, stepRead, stepStarted } from "./events.js";
+import { readBlocksFor, readCheckpoint } from "../read/read-block.js";
+import { blockKindOf } from "../block/kind.js";
 import { runPrecondition, runVerify } from "../trait/trait.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
@@ -78,9 +80,13 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
     preflight(mem, entry);
     const page = options?.page ?? (await context.newPage());
     const closeOnFinish = options?.closeOnFinish ?? true;
-    const opened = beginRun();
-    let result;
-    let failure;
+    return inRun(undefined, () => playGraph(entry, terminals, page, mem, maxSteps, options), (out) => out.__state).finally(async () => {
+        if (closeOnFinish)
+            await page.close();
+    });
+}
+/** The step loop of {@link runGraph}, inside its run: act, observe, resolve, verify, then the next Block. */
+async function playGraph(entry, terminals, page, mem, maxSteps, options) {
     try {
         let current = entry;
         let input = checkpoint("__start__");
@@ -90,7 +96,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
                 throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", MSG_RUNGRAPH_MAX_STEPS(maxSteps));
             }
             if (!isConnected(current))
-                stepStarted(current.name, input.__state);
+                stepStarted(current.name, blockKindOf(current), input.__state);
             await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
             const observed = current.instruction.observe
@@ -99,13 +105,13 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             const checkpoint = await current.instruction.resolve(observed);
             await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
             await runLayouts(options?.layouts, checkpoint.__state, checkpoint, page, mem, current.name);
+            await readLanding(page, mem, checkpoint.__state);
             stepEnded(lastLeaf(current), checkpoint.__state);
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
                     throw new WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", MSG_RUNGRAPH_NOT_TERMINAL(current.name, checkpoint.__state, [...terminals].join(", ")));
                 }
-                result = checkpoint.__state;
                 return checkpoint;
             }
             current = next;
@@ -113,16 +119,9 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
         }
     }
     catch (err) {
-        failure = err;
         stepFailed(err);
         throw err;
     }
-    finally {
-        endRun(opened, failure === undefined ? { ...(result !== undefined ? { result } : {}) } : { error: failure });
-        if (closeOnFinish) {
-            await page.close();
-        }
-    }
 }
 /**
  * Drives a genuinely separate second tab through its own Block/Flow, in the
@@ -143,3 +142,16 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
 export async function spawnTab(entry, page, mem, maxSteps = 5000) {
     return runGraph(entry, undefined, page.context(), mem, maxSteps);
 }
+/** After a step's verify: what the page shows, from the Read Blocks for where it landed (none loaded: nothing to do). */
+async function readLanding(page, mem, checkpoint) {
+    if (readBlocksFor(checkpoint).length === 0)
+        return;
+    try {
+        const { read, blocks } = await readCheckpoint(page, mem, checkpoint);
+        stepRead(checkpoint, { read: read.toJSON(), missing: [...read.missing], notes: { ...read.notes }, readBlocks: blocks });
+    }
+    catch (err) {
+        // A broken Read Block is reported on the step, never fails the run it observes.
+        stepRead(checkpoint, { read: {}, missing: [], notes: {}, readBlocks: [], error: err instanceof Error ? err.message : String(err) });
+    }
+}

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

@@ -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,15 +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.ring("email", { selector: "#email", label: "Email" });
- *   ctx.ring("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>> = {
@@ -107,17 +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;
+    /** 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
@@ -127,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). */
@@ -158,14 +163,14 @@ 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). */
@@ -173,7 +178,7 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     /**
      * 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.slides([
+     * @example ctx.ui.slides([
      *   { caption: "Checkout is three screens", tag: "YAP" },
      *   { caption: "Overview confirms totals", selector: ".summary_info", duration: true },
      * ]);
@@ -184,7 +189,7 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     /**
      * 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). */
@@ -193,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;
 };
@@ -213,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;
@@ -231,7 +236,7 @@ export type StubPhaseResult = {
     bannerUi?: BannerUiOpts;
     caption?: string;
     networkTabVisible?: boolean;
-    /** Slides to play in this phase ({@link StubCtx.slides}); empty when the stub set none. */
+    /** 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. */
@@ -256,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;

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";
@@ -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";
@@ -83,7 +85,8 @@ 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";