waygraph 0.16.1 → 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.d.ts

@@ -2,7 +2,7 @@ import { MemPage } from "../mem/mem.js";
 import type { Block } from "../block/block.js";
 import type { Checkpoint } from "../checkpoint/checkpoint.js";
 import type { Trait } from "../trait/trait.js";
-import type { BrowserContext, Locator, Page } from "@playwright/test";
+import type { BrowserContext, Page } from "@playwright/test";
 import type { SomeBlock } from "../block/block.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
@@ -125,21 +125,3 @@ export interface RunGraphOptions {
  * }
  */
 export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, page: Page, mem: MemPage, maxSteps?: number): Promise<TOut>;
-/**
- * Wraps one `act()` interaction with a caption and highlight, for a Block
- * author who wants to explicitly narrate a specific step rather than rely
- * on the generic per-fill/per-click narration `waygraph chain
- * WAYGRAPH_STEP=1` already does automatically -
- * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
- * reads at the call site instead of being inferred.
- *
- * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
- * for a `window.__wgPositionRing` hook the step-mode overlay installs on
- * the page before doing anything, so a headless/CI/automated run (nobody
- * watching, per-character delays and highlight pauses would just be wasted
- * time) pays zero extra cost - not even the boundingBox() lookup runs. The
- * `action` itself always runs regardless; only the narration is
- * conditional.
- * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
- */
-export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;

package/dist/engine/run/run.js

@@ -1,8 +1,9 @@
 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";
-import { ignorePageGone } from "../page-gone.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
@@ -79,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__");
@@ -91,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
@@ -100,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;
@@ -114,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
@@ -144,90 +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);
 }
-/**
- * Wraps one `act()` interaction with a caption and highlight, for a Block
- * author who wants to explicitly narrate a specific step rather than rely
- * on the generic per-fill/per-click narration `waygraph chain
- * WAYGRAPH_STEP=1` already does automatically -
- * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
- * reads at the call site instead of being inferred.
- *
- * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
- * for a `window.__wgPositionRing` hook the step-mode overlay installs on
- * the page before doing anything, so a headless/CI/automated run (nobody
- * watching, per-character delays and highlight pauses would just be wasted
- * time) pays zero extra cost - not even the boundingBox() lookup runs. The
- * `action` itself always runs regardless; only the narration is
- * conditional.
- * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
- */
-export async function narrate(locator, caption, action) {
-    const page = locator.page();
-    const active = await page
-        .evaluate(() => typeof globalThis.__wgPositionRing === "function")
-        .catch(() => false);
-    if (!active)
-        return action();
-    let owning = false;
-    try {
-        const box = await locator.boundingBox();
-        if (box) {
-            await page
-                .evaluate(({ box, caption }) => {
-                const w = globalThis;
-                if (w.__wgPositionRing)
-                    w.__wgPositionRing(box, caption, "planned");
-                // The CLI's own automatic per-fill/per-click narration checks
-                // this before showing (and overwriting) its own guess - an
-                // explicitly authored caption should win, not get immediately
-                // replaced a moment later by the generic one.
-                w.__wgLastNarrate = Date.now();
-                // Also claim the ring itself: the auto-highlight click/fill
-                // patches each hide the ring right after THEIR own step
-                // finishes, which - if action() below does more than one thing
-                // (e.g. a click then a wait for a toast) - would wipe this
-                // caption after just the first sub-step instead of the whole
-                // narrated action. Their hideRing() calls no-op while this is
-                // true; narrate() below is the one that actually clears it.
-                w.__wgNarrateOwnsRing = true;
-            }, { box, caption })
-                .catch(ignorePageGone);
-            owning = true;
-            // The ring alone is pointless if action() fires on the very next
-            // tick - a click that navigates (e.g. a form submit) wipes the ring
-            // before a human can read the caption at all. Give it the same
-            // "pop for a few seconds" dwell as the CLI's own auto-highlight
-            // clicks before the real action runs.
-            await new Promise((resolve) => setTimeout(resolve, 650));
-            // Re-stamp __wgLastNarrate right before handing off to action() - the
-            // CLI's auto-highlight patches only treat a narrate() as "just
-            // handled" within a short window (500ms), which the dwell above
-            // already burned through. Without this, action()'s own click/fill
-            // (same patched Locator prototype) would stomp this caption with its
-            // own generic one a moment after it finally became visible.
-            await page
-                .evaluate(() => {
-                globalThis.__wgLastNarrate = Date.now();
-            })
-                .catch(ignorePageGone);
-        }
-    }
-    catch {
-        // best-effort - the real action below still runs either way
-    }
+/** 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 {
-        return await action();
+        const { read, blocks } = await readCheckpoint(page, mem, checkpoint);
+        stepRead(checkpoint, { read: read.toJSON(), missing: [...read.missing], notes: { ...read.notes }, readBlocks: blocks });
     }
-    finally {
-        if (owning) {
-            await page
-                .evaluate(() => {
-                const w = globalThis;
-                w.__wgNarrateOwnsRing = false;
-                if (w.__wgHideRing)
-                    w.__wgHideRing();
-            })
-                .catch(ignorePageGone);
-        }
+    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/ring.d.ts

@@ -1,4 +1,3 @@
-import type { Checkpoint } from "../checkpoint/checkpoint.js";
 /** Shared dwell fields on stubs, fixtures, and yap slides. */
 export type FixtureDurationFields = {
     /**
@@ -83,8 +82,8 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
 /** A static stub phase: named ring slots to paint before or after a step. */
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 /**
- * One yap/slide in a multi-step demo caption sequence.
- * Not block lifecycle - demo pauses (Next / auto-next) between slides.
+ * One yap/slide in a multi-step demo caption sequence, painted with {@link StubCtx.slides}.
+ * The demo pauses on each (Next, or auto-next) before moving on.
  */
 export interface WaygraphSlide extends FixtureDurationFields {
     /** Primary caption (required). */
@@ -119,7 +118,6 @@ export type HighlightStyleDefaults = {
     size?: HighlightSize;
     weight?: HighlightWeight;
 };
-export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
 /** A ring or caption after its defaults and overrides are merged, ready to paint. */
 export type ResolvedHighlight = WaygraphHighlightStub;
 /** Map author aliases (`error` -> danger) to a canonical tone. */

package/dist/engine/stub/ring.js

@@ -1,3 +1,4 @@
+// A ring: one highlighted element with its caption, and its tone, size and weight; slides between steps.
 /** Map author aliases (`error` -> danger) to a canonical tone. */
 export function normalizeHighlightTone(raw) {
     if (typeof raw !== "string")