waygraph 0.16.2 → 0.16.4

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

@@ -0,0 +1,6 @@
+/** Bumped when a request or response changes shape (adding an op or an optional field does not). */
+export const SESSION_PROTOCOL_VERSION = 1;
+/** Every op, once: the server, the CLI and `pilot` all check against this list. */
+export const SESSION_OPS = ["hello", "subscribe", "status", "send", "dom", "trace", "console", "storage", "read", "upload", "click", "type", "press", "goto", "reload", "reach", "resync", "highlight"];
+const complete = true;
+void complete;

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

@@ -0,0 +1,25 @@
+import type { Page } from "@playwright/test";
+import type { MemPage } from "../../engine/mem/mem.js";
+/** The answer to `waygraph pilot read <id> [path]`. */
+export interface SessionRead {
+    page: string | null;
+    url: string;
+    read: Record<string, unknown>;
+    missing: string[];
+    notes: Record<string, string>;
+    readBlocks: string[];
+    skipped: {
+        block: string;
+        reason: string;
+    }[];
+    /** Set when no Read Block covers this page. */
+    hint?: string;
+}
+/** Reads the page the session is on (`here`); with `path`, only that part (`post.comments`). */
+export declare function readSession(page: Page, mem: MemPage, here: string | null, path?: string): Promise<SessionRead>;
+/** The read a status / send / reach snapshot carries: lists cut to a few items, nothing at all without Read Blocks. */
+export declare function snapshotRead(page: Page, mem: MemPage, here: string | null): Promise<{
+    read?: Record<string, unknown>;
+    missing?: string[];
+    readNotes?: Record<string, string>;
+}>;

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

@@ -0,0 +1,50 @@
+import { readBlocksFor, readCheckpoint } from "../../engine/read/read-block.js";
+/** A snapshot shows at most this many items of a list; `read <path>` returns the rest. */
+const SNAPSHOT_LIST_CAP = 20;
+function pick(tree, path) {
+    const parts = path.split(".");
+    let node = tree;
+    for (const part of parts)
+        node = node !== null && typeof node === "object" ? node[part] : undefined;
+    const out = {};
+    let at = out;
+    for (const part of parts.slice(0, -1))
+        at = at[part] = {};
+    at[parts[parts.length - 1]] = node ?? null;
+    return out;
+}
+/** Reads the page the session is on (`here`); with `path`, only that part (`post.comments`). */
+export async function readSession(page, mem, here, path) {
+    const base = { page: here, url: page.url() };
+    if (readBlocksFor(here).length === 0) {
+        return { ...base, read: {}, missing: [], notes: {}, readBlocks: [], skipped: [], hint: "no Read Block for this page: use `dom` to look at it" };
+    }
+    const { read, blocks, skipped } = await readCheckpoint(page, mem, here);
+    const inPath = (p) => !path || p === path || p.startsWith(path + ".");
+    return {
+        ...base,
+        read: path ? pick(read.toJSON(), path) : read.toJSON(),
+        missing: read.missing.filter(inPath),
+        notes: Object.fromEntries(Object.entries(read.notes).filter(([p]) => inPath(p))),
+        readBlocks: blocks,
+        skipped,
+    };
+}
+/** The read a status / send / reach snapshot carries: lists cut to a few items, nothing at all without Read Blocks. */
+export async function snapshotRead(page, mem, here) {
+    if (readBlocksFor(here).length === 0)
+        return {};
+    const got = await readSession(page, mem, here);
+    const notes = { ...got.notes };
+    const cap = (node, path) => {
+        if (Array.isArray(node)) {
+            if (node.length > SNAPSHOT_LIST_CAP)
+                notes[path] = `${SNAPSHOT_LIST_CAP} of ${node.length} shown: \`read <id> ${path}\` for all`;
+            return node.slice(0, SNAPSHOT_LIST_CAP);
+        }
+        if (node === null || typeof node !== "object")
+            return node;
+        return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, cap(v, path ? `${path}.${k}` : k)]));
+    };
+    return { read: cap(got.read, ""), missing: got.missing, ...(Object.keys(notes).length ? { readNotes: notes } : {}) };
+}

package/dist/live/traverse/worker.d.ts

@@ -34,4 +34,5 @@ export interface WorkerOpts {
     mem: MemPage;
     leases: EdgeLeaseCoordinator;
 }
+/** One worker's walk, as one run of its own (parallel workers never share a run id or step counter). */
 export declare function runTraverseWorker(opts: WorkerOpts): Promise<TraverseWorkerResult>;

package/dist/live/traverse/worker.js

@@ -1,6 +1,7 @@
 import { envString } from "../../engine/env.js";
 import { buildFlow } from "../../engine/flow/flow.js";
 import { ignorePageGone } from "../../engine/page-gone.js";
+import { inRun } from "../../engine/run/events.js";
 import { detectHere } from "../auto/auto.js";
 import { buildExploreMenu } from "../auto/explore.js";
 import { memStubValue } from "../auto/mem.js";
@@ -83,7 +84,11 @@ export async function runOneBlock(engine, entry, context, page, mem) {
             clearTimeout(timer);
     }
 }
-export async function runTraverseWorker(opts) {
+/** One worker's walk, as one run of its own (parallel workers never share a run id or step counter). */
+export function runTraverseWorker(opts) {
+    return inRun(`traverse ${opts.traverseId} worker ${opts.workerIndex}`, () => walk(opts), (r) => r.leaf);
+}
+async function walk(opts) {
     const { traverseId, workerIndex, parallel, maxSteps, maxVisitsPerNode, maxVisitsPerEdge, timeoutMs, graph, library, engine, context, mem, leases, } = opts;
     let page = opts.page;
     const startUrl = opts.startUrl;

package/dist/manifest/manifest.d.ts

@@ -1,5 +1,7 @@
-import type { BlockKind, ProjectScan, ScanOptions } from "./project.js";
-export declare const MANIFEST_VERSION = 1;
+import type { BlockKind } from "../engine/block/kind.js";
+import type { ProjectScan, ScanOptions } from "./project.js";
+import { type ReadShape } from "../engine/read/read-block.js";
+export declare const MANIFEST_VERSION = 2;
 export interface ManifestBlock {
     /** `file#exportName`, unique across the project. */
     id: string;
@@ -33,6 +35,22 @@ export interface ManifestFlow {
         demoPace?: unknown;
     };
 }
+/** A Read Block (beta): which Checkpoints it reads and the shape of what it returns. */
+export interface ManifestReadBlock {
+    id: string;
+    name: string;
+    exportName: string;
+    description: string;
+    /** Checkpoint tags it reads on (`"*"` = every page). */
+    from: string[];
+    requires: string[];
+    /** Field path -> shape (`"catalog.items": [{ name: "string", price: "number" }]`); absent when `read` needs Mem to build. */
+    fields?: Record<string, ReadShape>;
+    /** Why `fields` is absent. */
+    fieldsError?: string;
+    file: string;
+    map?: string;
+}
 export interface Manifest {
     version: number;
     project: {
@@ -43,6 +61,8 @@ export interface Manifest {
     checkpoints: string[];
     maps: string[];
     blocks: ManifestBlock[];
+    /** What each Checkpoint's page shows, from its Read Blocks (version 2+). */
+    readBlocks: ManifestReadBlock[];
     flows: ManifestFlow[];
     skipped: ProjectScan["skipped"];
 }

package/dist/manifest/manifest.js

@@ -3,7 +3,9 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { scanProject } from "./project.js";
-export const MANIFEST_VERSION = 1;
+import { MemPage } from "../engine/mem/mem.js";
+import { readBlockShape } from "../engine/read/read-block.js";
+export const MANIFEST_VERSION = 2;
 function packageVersion() {
     try {
         return JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "..", "package.json"), "utf8")).version;
@@ -77,12 +79,36 @@ export function manifestFromScan(scan) {
             },
         };
     });
+    const readBlocks = scan.readBlocks.map((r) => {
+        let shape;
+        try {
+            shape = { fields: readBlockShape(r.block, new MemPage()) };
+        }
+        catch (err) {
+            shape = { fieldsError: err instanceof Error ? err.message : String(err) };
+        }
+        for (const t of r.block.from)
+            if (t !== "*")
+                checkpoints.add(t);
+        return {
+            id: `${r.file}#${r.exportName}`,
+            name: r.block.name,
+            exportName: r.exportName,
+            description: r.block.description,
+            from: [...r.block.from],
+            requires: r.block.requires.map((k) => k.name),
+            ...shape,
+            file: r.file,
+            ...(r.map ? { map: r.map } : {}),
+        };
+    });
     return {
         version: MANIFEST_VERSION,
         project: { name: projectName(scan.projectDir), dir: scan.projectDir, waygraph: packageVersion() },
         checkpoints: [...checkpoints].sort(),
         maps: [...maps].sort(),
         blocks,
+        readBlocks,
         flows,
         skipped: scan.skipped,
     };

package/dist/manifest/project.d.ts

@@ -1,6 +1,7 @@
 import type { BlocksSelect } from "./select.js";
+import type { ReadBlock } from "../engine/read/read-block.js";
 import type { AnyBlock } from "./scan.js";
-export type BlockKind = "nav" | "page" | "assert" | "method" | "effect" | "api" | "block";
+import { type BlockKind } from "../engine/block/kind.js";
 export interface ScannedBlock {
     block: AnyBlock;
     name: string;
@@ -34,9 +35,17 @@ export interface BlockEntry {
     kind: "nav" | "action";
     description: string;
 }
+/** A Read Block found in a scanned file (beta). */
+export interface ScannedReadBlock {
+    block: ReadBlock;
+    exportName: string;
+    file: string;
+    map?: string;
+}
 export interface ProjectScan {
     projectDir: string;
     blocks: ScannedBlock[];
+    readBlocks: ScannedReadBlock[];
     flows: ScannedFlow[];
     skipped: {
         block: string;

package/dist/manifest/project.js

@@ -2,17 +2,9 @@
 import { relative } from "node:path";
 import { matchBlocksSelect } from "./select.js";
 import { exploreRoots, injectTaggedFile } from "./roots.js";
-import { blockKind, importFresh, isBlockLike, isFlowLike, walkDir } from "./scan.js";
+import { importFresh, isBlockLike, isFlowLike, isReadBlockLike, walkDir } from "./scan.js";
 import { installedMapPackages, mapPackageBlockFiles } from "./maps.js";
-function kindOf(block) {
-    const kind = blockKind(block);
-    if (kind === "nav" || kind === "page" || kind === "assert" || kind === "api")
-        return kind;
-    const salt = block.__waygraphSalt;
-    if (salt === "effect" || salt === "method" || salt === "api")
-        return salt;
-    return "block";
-}
+import { blockKindOf } from "../engine/block/kind.js";
 /** A file that fails to import is left out of the scan, and said so: a silent skip reads as "nothing there". */
 export function reportImportError(relFile, err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -23,6 +15,7 @@ export async function scanProject(projectDir, opts = {}) {
     const select = opts.blocksSelect;
     const onError = opts.onImportError ?? reportImportError;
     const blocks = [];
+    const readBlocks = [];
     const flows = [];
     const skipped = [];
     const scanBlockFile = async (absFile, rel, file, map) => {
@@ -35,6 +28,10 @@ export async function scanProject(projectDir, opts = {}) {
             return;
         }
         for (const [exportName, exported] of Object.entries(mod)) {
+            if (isReadBlockLike(exported)) {
+                readBlocks.push({ block: exported, exportName, file, ...(map ? { map } : {}) });
+                continue;
+            }
             if (!isBlockLike(exported))
                 continue;
             if (select && !matchBlocksSelect(select, { relFile: file, blockName: exported.name }))
@@ -49,7 +46,7 @@ export async function scanProject(projectDir, opts = {}) {
                 block: exported,
                 name: exported.name,
                 exportName,
-                kind: kindOf(exported),
+                kind: blockKindOf(exported),
                 description: typeof exported.description === "string" ? exported.description : "",
                 from: [...from],
                 to: [...to],
@@ -97,5 +94,5 @@ export async function scanProject(projectDir, opts = {}) {
             }
         }
     }
-    return { projectDir, blocks, flows, skipped };
+    return { projectDir, blocks, readBlocks, flows, skipped };
 }

package/dist/manifest/read-blocks.d.ts

@@ -0,0 +1,2 @@
+/** Imports every Read Block file of the project; returns how many loaded. */
+export declare function loadReadBlocks(projectDir: string): Promise<number>;

package/dist/manifest/read-blocks.js

@@ -0,0 +1,23 @@
+// Loads a project's Read Blocks (`*.read.block.ts`, its own and its installed map packages'): importing one registers it,
+// so every run can read the pages it lands on. Sessions get them from the full project scan; a run by flow name does not.
+import { relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { installedMapPackages, mapPackageBlockFiles } from "./maps.js";
+import { reportImportError } from "./project.js";
+import { walkDir } from "./scan.js";
+const READ_BLOCK = /\.read\.block\.ts$/;
+/** Imports every Read Block file of the project; returns how many loaded. */
+export async function loadReadBlocks(projectDir) {
+    const files = [...walkDir(projectDir, READ_BLOCK), ...installedMapPackages(projectDir).flatMap(mapPackageBlockFiles).filter((f) => READ_BLOCK.test(f))];
+    let loaded = 0;
+    for (const file of files) {
+        try {
+            await import(pathToFileURL(file).href);
+            loaded += 1;
+        }
+        catch (err) {
+            reportImportError(relative(projectDir, file), err);
+        }
+    }
+    return loaded;
+}

package/dist/manifest/scan.d.ts

@@ -1,5 +1,6 @@
 import type { Block } from "../engine/block/block.js";
 import type { Checkpoint } from "../engine/checkpoint/checkpoint.js";
+import type { ReadBlock } from "../engine/read/read-block.js";
 /** Every file under `dir` whose name matches, skipping `node_modules`, `dist` and `.git`. */
 export declare function walkDir(dir: string, pattern: RegExp): string[];
 /**
@@ -11,9 +12,9 @@ export type AnyBlock = Block<Checkpoint<string>, Checkpoint<string>> & {
     description?: string;
 };
 export declare function isBlockLike(val: unknown): val is AnyBlock;
+/** A Read Block (`defineReadBlock`): a name, the Checkpoints it reads, and an instruction with only `read`. */
+export declare function isReadBlockLike(val: unknown): val is ReadBlock;
 export declare function isFlowLike(val: unknown): val is {
     run: (...args: unknown[]) => Promise<unknown>;
     blocks: () => unknown[];
 };
-/** The factory kind a Block was built with (`nav`, `page`, `assert`), or undefined for Methods and Effects. */
-export declare function blockKind(block: object): string | undefined;

package/dist/manifest/scan.js

@@ -45,13 +45,17 @@ export function isBlockLike(val) {
     const instruction = obj.instruction;
     return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
 }
+/** A Read Block (`defineReadBlock`): a name, the Checkpoints it reads, and an instruction with only `read`. */
+export function isReadBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    const instruction = obj.instruction;
+    return typeof obj.name === "string" && Array.isArray(obj.from) && typeof instruction?.read === "function" && instruction.act === undefined;
+}
 export function isFlowLike(val) {
     return (val !== null &&
         typeof val === "object" &&
         typeof val.run === "function" &&
         typeof val.blocks === "function");
 }
-/** The factory kind a Block was built with (`nav`, `page`, `assert`), or undefined for Methods and Effects. */
-export function blockKind(block) {
-    return block.__waygraphKind;
-}

package/dist/runner/runner.d.ts

@@ -1,4 +1,3 @@
-import "../runtime/run-log.js";
 export declare function play(projectDir: string, spec: string): Promise<void>;
 /** The process entry the CLI's bootstrap calls: one run (and one run log) per invocation. */
 export declare function startRunner(): void;

package/dist/runner/runner.js

@@ -2,9 +2,10 @@
 // Playwright is used) with the project dir and the spec ("cartFlow", "loginFlow then add-item"). Every mode plays the
 // same steps through the same engine; the mode decides what happens around each step.
 import { MemPage } from "../engine/mem/mem.js";
-import { beginRun, endRun } from "../engine/run/events.js";
+import { inRun } from "../engine/run/events.js";
 import { withWebServer } from "../runtime/webserver.js";
-import "../runtime/run-log.js";
+import { installRunLog } from "../runtime/run-log.js";
+import { loadReadBlocks } from "../manifest/read-blocks.js";
 import { planSteps } from "./plan/plan.js";
 import { readOptions, slowMoFor } from "./options.js";
 import { openSession } from "./session.js";
@@ -16,6 +17,7 @@ import { reportMode } from "./modes/report.js";
 export async function play(projectDir, spec) {
     const options = readOptions();
     const mem = new MemPage();
+    await loadReadBlocks(projectDir);
     const { steps, flows } = await planSteps(projectDir, spec, mem, options);
     if (options.mode === "branches")
         return playBranches(flows, mem, options);
@@ -52,12 +54,10 @@ function finish(outcome) {
 }
 /** The process entry the CLI's bootstrap calls: one run (and one run log) per invocation. */
 export function startRunner() {
+    installRunLog();
     const projectDir = process.argv[2] ?? process.cwd();
     const spec = process.argv[3] ?? "";
-    const opened = beginRun(spec);
-    withWebServer(projectDir, () => play(projectDir, spec))
-        .then(() => endRun(opened, {}), (err) => {
-        endRun(opened, { error: err });
+    inRun(spec, () => withWebServer(projectDir, () => play(projectDir, spec))).catch((err) => {
         console.error(err && err.stack ? err.stack : String(err));
         process.exitCode = 1;
     });

package/dist/runtime/full-launch.d.ts

@@ -1 +1,2 @@
-export {};
+/** How an Engine launches its own browser: the selected config (--config), the Chromium override, the extensions. Called by the package entry. */
+export declare function installFullLaunch(): void;

package/dist/runtime/full-launch.js

@@ -4,31 +4,33 @@ import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "./
 import { resolveExtensions } from "./extensions.js";
 import { loadWaygraphConfig } from "./waygraph-config.js";
 import { envString } from "../engine/env.js";
-// An Engine's own browser follows the selected config (--config), the Chromium override and the configured extensions.
-setOwnContextLauncher(async (engineConfig) => {
-    // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with.
-    const chosen = envString("WAYGRAPH_CONFIG") ? await loadWaygraphConfig(process.cwd()) : undefined;
-    const config = chosen
-        ? {
-            ...engineConfig,
-            ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
-            ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
-        }
-        : engineConfig;
-    const browserName = config?.browserName ?? "chromium";
-    const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-    const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
-    return launchContext({
-        launcher: resolveLauncher(browserName, config),
-        launch: {
-            headless: config?.headless ?? true,
-            ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-            ...(executablePath ? { executablePath } : {}),
-        },
-        context: {
-            ...(baseURL ? { baseURL } : {}),
-            ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
-        },
-        extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+/** How an Engine launches its own browser: the selected config (--config), the Chromium override, the extensions. Called by the package entry. */
+export function installFullLaunch() {
+    setOwnContextLauncher(async (engineConfig) => {
+        // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with.
+        const chosen = envString("WAYGRAPH_CONFIG") ? await loadWaygraphConfig(process.cwd()) : undefined;
+        const config = chosen
+            ? {
+                ...engineConfig,
+                ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
+                ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
+            }
+            : engineConfig;
+        const browserName = config?.browserName ?? "chromium";
+        const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
+        const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
+        return launchContext({
+            launcher: resolveLauncher(browserName, config),
+            launch: {
+                headless: config?.headless ?? true,
+                ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+                ...(executablePath ? { executablePath } : {}),
+            },
+            context: {
+                ...(baseURL ? { baseURL } : {}),
+                ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+            },
+            extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+        });
     });
-});
+}

package/dist/runtime/run-log.d.ts

@@ -1,2 +1,4 @@
+/** Starts writing run events to the run log. Called by the package entry and the runner; a second call does nothing. */
+export declare function installRunLog(): void;
 /** The folder run logs go to for a project unless the config or the environment says otherwise. */
 export declare function defaultRunLogDir(projectDir: string): string;

package/dist/runtime/run-log.js

@@ -4,13 +4,20 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { onRunEvent } from "../engine/run/events.js";
 import { envString } from "../engine/env.js";
-onRunEvent((event) => {
-    const dir = envString("WAYGRAPH_RUN_LOG");
-    if (!dir || dir === "0")
+let installed = false;
+/** Starts writing run events to the run log. Called by the package entry and the runner; a second call does nothing. */
+export function installRunLog() {
+    if (installed)
         return;
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, `${event.runId}.jsonl`), JSON.stringify(event) + "\n");
-});
+    installed = true;
+    onRunEvent((event) => {
+        const dir = envString("WAYGRAPH_RUN_LOG");
+        if (!dir || dir === "0")
+            return;
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, `${event.runId}.jsonl`), JSON.stringify(event) + "\n");
+    });
+}
 /** The folder run logs go to for a project unless the config or the environment says otherwise. */
 export function defaultRunLogDir(projectDir) {
     return join(projectDir, ".waygraph", "runs");

package/examples/saucedemo/README.md

@@ -13,7 +13,7 @@ the **reference** for waygraph consumer conventions:
 - `defineApiBlock` - a real backend/HTTP check as one step in the same Flow as
   a UI step, with its own live network-activity panel during a demo - see
   `apiDemoFlow` (`src/flows/api-demo.flow.ts`)
-- `ctx.caption()` (bottom subtitle-bar) + `ctx.titlePos()` (banner
+- `ctx.ui.caption()` (bottom subtitle-bar) + `ctx.ui.titlePos()` (banner
   left/center/right) - also on `checkoutFlow`
 
 **GitHub Pages walkthrough:**
@@ -48,7 +48,7 @@ npx playwright install chromium
 | **Device showcase** (mobile/tablet + portrait/landscape; narration in `src/stubs/device-showcase.ts`) | `npm run demo:device` |
 | Device showcase + `.webm` | `npm run demo:video` |
 | **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
-| **Owner checkout** (inline `{ ff: true }`, `ctx.caption()`, banner position) | `npm run demo:checkout` |
+| **Owner checkout** (inline `{ ff: true }`, `ctx.ui.caption()`, banner position) | `npm run demo:checkout` |
 | **FE + BE in one Flow** (`defineApiBlock`, live network panel) | `npm run demo:api` |
 | Record (headless `.webm`) | `npm run record` |
 | List flows | `npm run flows` |

package/examples/saucedemo/src/blocks/SITE-MAP.md

@@ -9,6 +9,7 @@ src/blocks/
   saucedemo-web/                      # URL /
     NAV.md
     nav-login.block.ts                # Page  definePageBlock url:/
+    header.read.block.ts              # Read  defineReadBlock (beta, every page: title, cart count)
     methods/
       fill-username.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
       fill-password.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
@@ -18,6 +19,7 @@ src/blocks/
       login.sel.ts                    # LoginSel (not a Block)
     inventory/                        # URL /inventory.html
       inventory.page.block.ts       # Page definePageBlock
+      inventory.read.block.ts       # Read defineReadBlock (beta: products, prices, in cart, sort)
       NAV.md
       nav-item-detail.block.ts        # Nav  defineMemNavBlock (instance row)
       methods/
@@ -36,6 +38,7 @@ src/blocks/
       NAV.md
       cart.sel.ts                     # CartSel (not a Block)
       nav-cart.block.ts               # Nav click header cart
+      cart.read.block.ts              # Read defineReadBlock (beta: the cart's lines)
       nav-checkout-info.block.ts
     checkout-step-one/                # URL /checkout-step-one.html
       NAV.md

package/examples/saucedemo/src/blocks/saucedemo-web/cart/cart.read.block.ts

@@ -0,0 +1,26 @@
+import { defineReadBlock } from "waygraph/beta";
+import { CartPage } from "../../../states/checkout.states.js";
+import { Cart } from "../../../states/checkout.reads.js";
+
+/**
+ * Kind: Read (beta)
+ * Helper: defineReadBlock
+ * Route: saucedemo-web/cart/  (= /cart.html)
+ *
+ * The cart's lines: name, quantity and price.
+ */
+export const CartReadBlock = defineReadBlock({
+  name: "read-cart",
+  description: "Each line in the cart: name, quantity, price.",
+  from: CartPage,
+  instruction: {
+    read: (ctx) =>
+      Cart({
+        lines: ctx.page.list(".cart_item", (row) => ({
+          name: row.text(".inventory_item_name"),
+          qty: row.number(".cart_quantity"),
+          price: row.number(".inventory_item_price"),
+        })),
+      }),
+  },
+});

package/examples/saucedemo/src/blocks/saucedemo-web/header.read.block.ts

@@ -0,0 +1,25 @@
+import { defineReadBlock } from "waygraph/beta";
+import { Header } from "../../states/checkout.reads.js";
+import { InventorySel } from "./inventory/methods/inventory-items.js";
+
+/**
+ * Kind: Read (beta)
+ * Helper: defineReadBlock
+ * Route: saucedemo-web/  (every signed-in page)
+ *
+ * The header every page shares: the page title and how many items are in the cart (0 when the badge is not shown).
+ */
+export const HeaderReadBlock = defineReadBlock({
+  name: "read-header",
+  description: "The page title and the cart count.",
+  instruction: {
+    read: (ctx) =>
+      Header({
+        title: ctx.page.text(".title"),
+        cartCount: ctx.page.fn(async (page) => {
+          const badge = page.locator(InventorySel.cartBadge);
+          return (await badge.count()) ? Number(await badge.first().innerText()) : 0;
+        }),
+      }),
+  },
+});

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/inventory.read.block.ts

@@ -0,0 +1,28 @@
+import { defineReadBlock } from "waygraph/beta";
+import { ItemInCart, LoggedIn } from "../../../states/checkout.states.js";
+import { Catalog } from "../../../states/checkout.reads.js";
+import { InventorySel } from "./methods/inventory-items.js";
+
+/**
+ * Kind: Read (beta)
+ * Helper: defineReadBlock
+ * Route: saucedemo-web/inventory/  (= /inventory.html)
+ *
+ * The catalogue as data: every product with its price and whether it is in the cart, and the sort order.
+ */
+export const InventoryReadBlock = defineReadBlock({
+  name: "read-inventory",
+  description: "Every product, its price and whether it is in the cart; the sort order.",
+  from: [LoggedIn, ItemInCart],
+  instruction: {
+    read: (ctx) =>
+      Catalog({
+        items: ctx.page.list(InventorySel.card, (row) => ({
+          name: row.text(InventorySel.name),
+          price: row.number(".inventory_item_price"),
+          inCart: row.visible(InventorySel.removeBtnPrefix),
+        })),
+        sort: ctx.page.value(".product_sort_container"),
+      }),
+  },
+});

package/examples/saucedemo/src/flows/api-demo.flow.ts

@@ -32,7 +32,7 @@ export const apiDemoEpisode = engine
   .start()
   .method(
     CheckBackendHealth.stubBefore((ctx) => {
-      ctx.title("Checking backend health · real HTTP request, no browser");
+      ctx.ui.title("Checking backend health · real HTTP request, no browser");
     }),
   )
   .end();