waygraph 0.16.2 → 0.16.4

package/dist/demo/stepper/slides.js

@@ -231,7 +231,7 @@ export async function presentSlides(page, slides, opts) {
     }
     await hideRing(page);
 }
-/** Plays a stub phase's `ctx.slides(...)` for the step on screen, in the flow's highlight style. */
+/** Plays a stub phase's `ctx.ui.slides(...)` for the step on screen, in the flow's highlight style. */
 export async function showSlides(ctx, view, slides) {
     if (slides.length === 0)
         return;

package/dist/demo/stepper/stepper.js

@@ -83,7 +83,7 @@ export async function createStepper(page, mem, steps, options) {
 }
 /**
  * Some Blocks call page.setViewportSize() in their own act for their own tests; in a watched demo that would resize
- * the window, so it does nothing here. An authored ctx.device() still resizes through __wgRealSetViewportSize.
+ * the window, so it does nothing here. An authored ctx.ui.device() still resizes through __wgRealSetViewportSize.
  */
 function keepWindowSize(page) {
     page.__wgRealSetViewportSize = page.setViewportSize.bind(page);

package/dist/engine/block/kind.d.ts

@@ -0,0 +1,3 @@
+/** Which factory made a Block: `nav`, `page`, `assert`, `method`, `effect`, `api`, or a plain `block` (`defineBlock`). */
+export type BlockKind = "nav" | "page" | "assert" | "method" | "effect" | "api" | "block";
+export declare function blockKindOf(block: object): BlockKind;

package/dist/engine/block/kind.js

@@ -0,0 +1,11 @@
+// A Block's kind, from the marker its factory stamps on it: what the manifest lists, what a run event carries, what a
+// viewer colours a step by.
+export function blockKindOf(block) {
+    const kind = block.__waygraphKind;
+    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";
+}

package/dist/engine/errors.d.ts

@@ -108,6 +108,16 @@ export declare const WAYGRAPH_ERRORS: {
         readonly means: "The Trait name/index given doesn't exist in this Block's verify list.";
         readonly fix: "Check the Block's actual verify list for the right name/index.";
     };
+    readonly WG_READ_MISSING: {
+        readonly where: "engine/read/read-page.ts - ReadPage.get()";
+        readonly means: "read.get(key) asked for a value the page did not show, or that no Read Block for this page reads.";
+        readonly fix: "Check read.has(key) first, or read.missing / read.notes for why; add the field to the page's Read Block.";
+    };
+    readonly WG_READ_DUPLICATE: {
+        readonly where: "engine/read/read-block.ts - readCheckpoint()";
+        readonly means: "Two Read Blocks for the same page both read one key, so it has two answers.";
+        readonly fix: "Read each key in one Read Block per Checkpoint (an every-page Read Block counts for every Checkpoint).";
+    };
     readonly WG_MEM_READ_BEFORE_SET: {
         readonly where: "engine/mem/mem.ts - MemPage.get()";
         readonly means: "mem.get(key) was called for a key that was never mem.set() on this MemPage.";
@@ -143,6 +153,8 @@ export declare const MSG_MAP_FF_NOT_CLOSED: (ffName: string) => string;
 export declare const MSG_MAP_EMPTY: string;
 export declare const MSG_BRANCH_REGRESSION_NO_BROWSER: string;
 export declare const MSG_MEM_READ_BEFORE_SET: (keyName: string) => string;
+export declare const MSG_READ_MISSING: (path: string, note?: string) => string;
+export declare const MSG_READ_DUPLICATE: (path: string, first: string, second: string) => string;
 export declare const MSG_COMPOSE_EMPTY: (name: string) => string;
 export declare const MSG_FASTFORWARD_EMPTY: (name: string) => string;
 export declare const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX: (index: number, count: number) => string;

package/dist/engine/errors.js

@@ -108,6 +108,16 @@ export const WAYGRAPH_ERRORS = {
         means: "The Trait name/index given doesn't exist in this Block's verify list.",
         fix: "Check the Block's actual verify list for the right name/index.",
     },
+    WG_READ_MISSING: {
+        where: "engine/read/read-page.ts - ReadPage.get()",
+        means: "read.get(key) asked for a value the page did not show, or that no Read Block for this page reads.",
+        fix: "Check read.has(key) first, or read.missing / read.notes for why; add the field to the page's Read Block.",
+    },
+    WG_READ_DUPLICATE: {
+        where: "engine/read/read-block.ts - readCheckpoint()",
+        means: "Two Read Blocks for the same page both read one key, so it has two answers.",
+        fix: "Read each key in one Read Block per Checkpoint (an every-page Read Block counts for every Checkpoint).",
+    },
     WG_MEM_READ_BEFORE_SET: {
         where: "engine/mem/mem.ts - MemPage.get()",
         means: "mem.get(key) was called for a key that was never mem.set() on this MemPage.",
@@ -156,6 +166,8 @@ export const MSG_MAP_EMPTY = "Waygraph map: .end() called with zero steps - add
 export const MSG_BRANCH_REGRESSION_NO_BROWSER = "Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
     "has none) - pass { cloneSession: false } to run the single live path in this context instead.";
 export const MSG_MEM_READ_BEFORE_SET = (keyName) => `MemPage: "${keyName}" read before it was set`;
+export const MSG_READ_MISSING = (path, note) => `ReadPage: "${path}" was not shown on this page${note ? ` (${note})` : ""}`;
+export const MSG_READ_DUPLICATE = (path, first, second) => `Read Blocks "${first}" and "${second}" both read "${path}" on the same page`;
 export const MSG_COMPOSE_EMPTY = (name) => `composeBlock: "${name}" needs at least one step`;
 export const MSG_FASTFORWARD_EMPTY = (name) => `fastForwardComposeBlock: "${name}" needs at least one step`;
 export const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX = (index, count) => `chainFlow: no Block at index ${index} across ${count} chained flows`;

package/dist/engine/read/read-block.d.ts

@@ -0,0 +1,61 @@
+import type { Page } from "@playwright/test";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { MemKey, MemPage } from "../mem/mem.js";
+import type { ReadSpec } from "./read-key.js";
+import { ReadPage } from "./read-page.js";
+import { type ReadCtx } from "./readers.js";
+/** Options for {@link defineReadBlock}: shaped like a Method's, with one instruction phase. */
+export interface ReadBlockOptions {
+    name: string;
+    description?: string;
+    /** The Checkpoint(s) whose page this reads. Leave it out to read on every page (a header, the signed-in user). */
+    from?: Checkpoint<string> | readonly Checkpoint<string>[];
+    /** Mem keys `read` uses through `ctx.mem`; without them set, this Read Block is skipped (and said so). */
+    requires?: readonly MemKey<unknown>[];
+    instruction: {
+        /** Returns one namespace's spec (`Post({ ... })`) or several. Runs on every read, so it can use `ctx.mem`. */
+        read(ctx: ReadCtx): ReadSpec | readonly ReadSpec[];
+    };
+}
+/** A defined Read Block. */
+export interface ReadBlock {
+    readonly name: string;
+    readonly description: string;
+    /** Checkpoint names, or `["*"]` for every page. */
+    readonly from: readonly string[];
+    readonly requires: readonly MemKey<unknown>[];
+    readonly instruction: ReadBlockOptions["instruction"];
+}
+/**
+ * Declares what a page shows, as typed data an agent or a test can read.
+ * @example
+ * export const PostReadBlock = defineReadBlock({
+ *   name: "read-post",
+ *   from: PostOpen,
+ *   instruction: {
+ *     read: (ctx) => Post({ title: ctx.page.text("h1"), likes: ctx.page.number(".likes") }),
+ *   },
+ * });
+ */
+export declare function defineReadBlock(options: ReadBlockOptions): ReadBlock;
+/** The Read Blocks that read `checkpoint`'s page (its own, then the every-page ones). `null`: only the every-page ones. */
+export declare function readBlocksFor(checkpoint: string | null): ReadBlock[];
+/** What a read of one Checkpoint's page found, and which Read Blocks took part. */
+export interface CheckpointRead {
+    read: ReadPage;
+    blocks: string[];
+    /** Read Blocks left out, and why (a Mem key they need is not set). */
+    skipped: {
+        block: string;
+        reason: string;
+    }[];
+}
+/** Reads `checkpoint`'s page with every Read Block for it, merged into one {@link ReadPage}. */
+export declare function readCheckpoint(page: Page, mem: MemPage, checkpoint: string | null): Promise<CheckpointRead>;
+/** What a field reads, as a type a viewer can show: `"string"`, `"number"`, `"boolean"`, `"string[]"`, a row shape. */
+export type ReadShape = string | readonly [Record<string, string>];
+/**
+ * The fields a Read Block reads and their shapes, by path (`"catalog.items": [{ name: "string", price: "number" }]`),
+ * without a page: `read` only builds plans. Throws when `read` needs a Mem value that `mem` does not have.
+ */
+export declare function readBlockShape(block: ReadBlock, mem: MemPage): Record<string, ReadShape>;

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

@@ -0,0 +1,94 @@
+import { WaygraphError, MSG_READ_DUPLICATE } from "../errors.js";
+import { ReadPage } from "./read-page.js";
+import { createReadCtx, Reader } from "./readers.js";
+import { runReadSpecs, settlePage } from "./run-read.js";
+/** Every Read Block a loaded file defined, by name (the scanner re-imports files; a re-import replaces, never duplicates). */
+const registry = new Map();
+/**
+ * Declares what a page shows, as typed data an agent or a test can read.
+ * @example
+ * export const PostReadBlock = defineReadBlock({
+ *   name: "read-post",
+ *   from: PostOpen,
+ *   instruction: {
+ *     read: (ctx) => Post({ title: ctx.page.text("h1"), likes: ctx.page.number(".likes") }),
+ *   },
+ * });
+ */
+export function defineReadBlock(options) {
+    const from = options.from === undefined ? ["*"] : (Array.isArray(options.from) ? options.from : [options.from]).map((c) => c.__state);
+    const block = {
+        name: options.name,
+        description: options.description ?? "",
+        from,
+        requires: options.requires ?? [],
+        instruction: options.instruction,
+    };
+    registry.set(block.name, block);
+    return block;
+}
+/** The Read Blocks that read `checkpoint`'s page (its own, then the every-page ones). `null`: only the every-page ones. */
+export function readBlocksFor(checkpoint) {
+    const blocks = [...registry.values()];
+    return [...blocks.filter((b) => checkpoint !== null && b.from.includes(checkpoint)), ...blocks.filter((b) => b.from.includes("*"))];
+}
+/** Reads `checkpoint`'s page with every Read Block for it, merged into one {@link ReadPage}. */
+export async function readCheckpoint(page, mem, checkpoint) {
+    const specs = [];
+    const owner = new Map();
+    const blocks = [];
+    const skipped = [];
+    for (const block of readBlocksFor(checkpoint)) {
+        const unset = block.requires.filter((k) => !mem.has(k)).map((k) => k.name);
+        if (unset.length) {
+            skipped.push({ block: block.name, reason: `needs mem ${unset.join(", ")}` });
+            continue;
+        }
+        const got = block.instruction.read(createReadCtx(mem));
+        for (const spec of Array.isArray(got) ? got : [got]) {
+            for (const field of Object.keys(spec.fields)) {
+                const path = `${spec.namespace}.${field}`;
+                const other = owner.get(path);
+                if (other)
+                    throw new WaygraphError("WG_READ_DUPLICATE", MSG_READ_DUPLICATE(path, other, block.name));
+                owner.set(path, block.name);
+            }
+            specs.push(spec);
+        }
+        blocks.push(block.name);
+    }
+    if (specs.length)
+        await settlePage(page);
+    const { values, notes } = await runReadSpecs(page, mem, specs);
+    return { read: new ReadPage(values, notes), blocks, skipped };
+}
+const SHAPE = { text: "string", attr: "string", value: "string", number: "number", count: "number", visible: "boolean", texts: "string[]", fn: "unknown" };
+/**
+ * The fields a Read Block reads and their shapes, by path (`"catalog.items": [{ name: "string", price: "number" }]`),
+ * without a page: `read` only builds plans. Throws when `read` needs a Mem value that `mem` does not have.
+ */
+export function readBlockShape(block, mem) {
+    const out = {};
+    const walk = (fields, prefix) => {
+        for (const [name, value] of Object.entries(fields)) {
+            if (value === undefined)
+                continue;
+            const path = `${prefix}.${name}`;
+            if (!(value instanceof Reader)) {
+                walk(value, path);
+                continue;
+            }
+            const plan = value.plan;
+            if (plan.kind === "list")
+                out[path] = [Object.fromEntries(Object.entries(plan.fields).map(([k, f]) => [k, SHAPE[f.kind] ?? "unknown"]))];
+            else if (plan.kind === "table")
+                out[path] = [Object.fromEntries(Object.keys(plan.columns).map((k) => [k, "string"]))];
+            else
+                out[path] = SHAPE[plan.kind] ?? "unknown";
+        }
+    };
+    const got = block.instruction.read(createReadCtx(mem));
+    for (const spec of Array.isArray(got) ? got : [got])
+        walk(spec.fields, spec.namespace);
+    return out;
+}

package/dist/engine/read/read-key.d.ts

@@ -0,0 +1,32 @@
+import type { Reader, ReadFields } from "./readers.js";
+/** A typed key into a {@link ReadPage}, named by its path (`"post.likes"`). Made by a {@link reads} namespace. */
+export declare class ReadKey<T> {
+    readonly path: string;
+    /** Type-only: carries `T` for `ReadPage.get`. Never set. */
+    readonly __type?: T;
+    constructor(path: string);
+}
+/** One namespace's fields and the reader that fills each: what calling a namespace returns (`Post({ ... })`). */
+export interface ReadSpec {
+    readonly namespace: string;
+    readonly fields: ReadFields;
+}
+/**
+ * The readers a namespace's fields take, checked against its type: each field optional (a page may read part of a
+ * namespace), a reader of that field's type, or for an object field, the same shape one level down.
+ */
+export type ReadFieldsOf<T> = {
+    readonly [K in keyof T]?: Reader<T[K]> | (T[K] extends readonly unknown[] ? never : T[K] extends object ? ReadFieldsOf<T[K]> : never);
+};
+/** A read namespace: each property is that field's {@link ReadKey}; calling it builds the namespace's {@link ReadSpec}. */
+export type ReadNamespace<T> = {
+    readonly [K in keyof T & string]: ReadKey<T[K]>;
+} & ((fields: ReadFieldsOf<T>) => ReadSpec);
+/**
+ * Declares a read namespace: one type, its property names become key paths, no `const` per key.
+ * @example
+ * export const Post = reads("post")<{ title: string; likes: number; comments: { author: string; body: string }[] }>();
+ * Post.likes;                                 // ReadKey<number>, path "post.likes"
+ * Post({ title: ctx.page.text("h1") });            // the spec a Read Block returns
+ */
+export declare function reads(namespace: string): <T extends object>() => ReadNamespace<T>;

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

@@ -0,0 +1,34 @@
+/** A typed key into a {@link ReadPage}, named by its path (`"post.likes"`). Made by a {@link reads} namespace. */
+export class ReadKey {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+}
+/** Names that must not mint a key: awaiting, printing or inspecting a namespace reads these. */
+const NOT_KEYS = new Set(["then", "toJSON", "constructor", "prototype", "name", "length", "call", "apply", "bind"]);
+/**
+ * Declares a read namespace: one type, its property names become key paths, no `const` per key.
+ * @example
+ * export const Post = reads("post")<{ title: string; likes: number; comments: { author: string; body: string }[] }>();
+ * Post.likes;                                 // ReadKey<number>, path "post.likes"
+ * Post({ title: ctx.page.text("h1") });            // the spec a Read Block returns
+ */
+export function reads(namespace) {
+    return () => {
+        const cache = new Map();
+        const build = (fields) => ({ namespace, fields });
+        return new Proxy(build, {
+            get(target, prop) {
+                if (typeof prop !== "string" || NOT_KEYS.has(prop))
+                    return Reflect.get(target, prop);
+                let key = cache.get(prop);
+                if (!key) {
+                    key = new ReadKey(`${namespace}.${prop}`);
+                    cache.set(prop, key);
+                }
+                return key;
+            },
+        });
+    };
+}

package/dist/engine/read/read-page.d.ts

@@ -0,0 +1,19 @@
+import type { ReadKey } from "./read-key.js";
+export declare class ReadPage {
+    private readonly tree;
+    /** Paths the page did not show (`null` in {@link toJSON}). */
+    readonly missing: readonly string[];
+    /** Why a path is missing or partial, e.g. a table column that isn't there, or rows not rendered yet. */
+    readonly notes: Readonly<Record<string, string>>;
+    constructor(values: ReadonlyMap<string, unknown>, notes?: ReadonlyMap<string, string>);
+    private at;
+    /** True when the page showed `key` (a read that found nothing is not shown). */
+    has<T>(key: ReadKey<T>): boolean;
+    /**
+     * The value the page showed for `key`, typed by the key. Throws (naming the key) when this read did not include it
+     * or the page did not show it - like `mem.get` on a key never set.
+     */
+    get<T>(key: ReadKey<T>): T;
+    /** The read as one object, nested by key path (`{ post: { title, comments: [...] } }`); missing paths are `null`. */
+    toJSON(): Record<string, unknown>;
+}

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

@@ -0,0 +1,50 @@
+// A ReadPage: what a page showed, read once, kept like a MemPage - typed `get` by key, and loud when a value is missing.
+import { WaygraphError, MSG_READ_MISSING } from "../errors.js";
+export class ReadPage {
+    tree = {};
+    /** Paths the page did not show (`null` in {@link toJSON}). */
+    missing;
+    /** Why a path is missing or partial, e.g. a table column that isn't there, or rows not rendered yet. */
+    notes;
+    constructor(values, notes = new Map()) {
+        const missing = [];
+        for (const [path, value] of values) {
+            if (value === null || value === undefined)
+                missing.push(path);
+            const parts = path.split(".");
+            let node = this.tree;
+            for (const part of parts.slice(0, -1))
+                node = (node[part] ??= {});
+            node[parts[parts.length - 1]] = value ?? null;
+        }
+        this.missing = missing;
+        this.notes = Object.fromEntries(notes);
+    }
+    at(path) {
+        let node = this.tree;
+        for (const part of path.split(".")) {
+            if (node === null || typeof node !== "object")
+                return undefined;
+            node = node[part];
+        }
+        return node;
+    }
+    /** True when the page showed `key` (a read that found nothing is not shown). */
+    has(key) {
+        const v = this.at(key.path);
+        return v !== undefined && v !== null;
+    }
+    /**
+     * The value the page showed for `key`, typed by the key. Throws (naming the key) when this read did not include it
+     * or the page did not show it - like `mem.get` on a key never set.
+     */
+    get(key) {
+        if (!this.has(key))
+            throw new WaygraphError("WG_READ_MISSING", MSG_READ_MISSING(key.path, this.notes[key.path]));
+        return this.at(key.path);
+    }
+    /** The read as one object, nested by key path (`{ post: { title, comments: [...] } }`); missing paths are `null`. */
+    toJSON() {
+        return this.tree;
+    }
+}

package/dist/engine/read/readers.d.ts

@@ -0,0 +1,82 @@
+import type { Page } from "@playwright/test";
+import type { MemPage } from "../mem/mem.js";
+/** What to take from the matched element(s). */
+export type FieldKind = "text" | "texts" | "number" | "attr" | "value" | "visible" | "count";
+/** One field: a CSS selector (inside a list row; `""` is the row itself) and what to take from it. */
+export interface FieldPlan {
+    kind: FieldKind;
+    selector: string;
+    attr?: string;
+}
+/** A reader's plan. Top-level selectors are Playwright selectors; selectors inside a list row are CSS. */
+export type ReaderPlan = FieldPlan | {
+    kind: "list";
+    selector: string;
+    fields: Record<string, FieldPlan>;
+} | {
+    kind: "table";
+    selector: string;
+    columns: Record<string, string>;
+} | {
+    kind: "fn";
+    fn: (page: Page, mem: MemPage) => unknown;
+};
+/** A reader of a `T`, handed out by a {@link ReadCtx}. */
+export declare class Reader<T> {
+    readonly plan: ReaderPlan;
+    /** Type-only: carries `T` so a reader of the wrong type doesn't compile. Never set. */
+    readonly __type?: T;
+    constructor(plan: ReaderPlan);
+}
+/** A namespace's fields after its type is checked: a reader, or nested fields one level down. */
+export interface ReadFields {
+    readonly [field: string]: Reader<unknown> | ReadFields | undefined;
+}
+/** The readers a list row offers, each scoped to the row (no selector: the row itself). */
+export interface RowCtx {
+    text(selector?: string): Reader<string>;
+    texts(selector?: string): Reader<string[]>;
+    /** The first number in the text (`"$1,299.00"` -> 1299, `"41 likes"` -> 41). */
+    number(selector?: string): Reader<number>;
+    attr(selector: string, name: string): Reader<string>;
+    value(selector?: string): Reader<string>;
+    visible(selector?: string): Reader<boolean>;
+    count(selector: string): Reader<number>;
+}
+/** What a Read Block's `read` is given: the run's Mem, and `page`, the readers for what the page shows. */
+export interface ReadCtx {
+    readonly mem: MemPage;
+    /** Readers for the page: `ctx.page.text(sel)`, `ctx.page.list(sel, (row) => ...)`, ... */
+    readonly page: PageReaders;
+}
+/** The readers a Read Block reads the page with. */
+export interface PageReaders {
+    /** Text of the first match (textContent, whitespace collapsed). */
+    text(selector: string): Reader<string>;
+    /** Text of every match (textContent, whitespace collapsed). */
+    texts(selector: string): Reader<string[]>;
+    /** The first number in the first match's text (`"$1,299.00"` -> 1299, `"41 likes"` -> 41). */
+    number(selector: string): Reader<number>;
+    attr(selector: string, name: string): Reader<string>;
+    /** A form field's current value. */
+    value(selector: string): Reader<string>;
+    /** Whether any match is visible (false, not missing, when nothing matches). */
+    visible(selector: string): Reader<boolean>;
+    count(selector: string): Reader<number>;
+    /**
+     * One object per row, each field read inside its row, in one round trip for the whole list.
+     * @example ctx.page.list(".comment", (row) => ({ author: row.text(".author"), body: row.text(".body") }))
+     */
+    list<R>(rowSelector: string, row: (row: RowCtx) => {
+        readonly [K in keyof R]: Reader<R[K]>;
+    }): Reader<R[]>;
+    /**
+     * One object per table row, each field the cell under the column with that header text (`<th>` or
+     * `role=columnheader`), in one round trip. A header that isn't there is reported as missing.
+     * @example ctx.page.table("#orders", { id: "Order #", total: "Total" })
+     */
+    table<C extends string>(selector: string, columns: Readonly<Record<C, string>>): Reader<Record<C, string>[]>;
+    /** Anything the helpers don't cover; `null` or `undefined` is reported as missing. */
+    fn<T>(read: (page: Page, mem: MemPage) => T | Promise<T>): Reader<Awaited<T>>;
+}
+export declare function createReadCtx(mem: MemPage): ReadCtx;

package/dist/engine/read/readers.js

@@ -0,0 +1,43 @@
+/** A reader of a `T`, handed out by a {@link ReadCtx}. */
+export class Reader {
+    plan;
+    constructor(plan) {
+        this.plan = plan;
+    }
+}
+function fieldReaders() {
+    const field = (kind, selector = "", attr) => new Reader(attr === undefined ? { kind, selector } : { kind, selector, attr });
+    return {
+        text: (s) => field("text", s),
+        texts: (s) => field("texts", s),
+        number: (s) => field("number", s),
+        attr: (s, name) => field("attr", s, name),
+        value: (s) => field("value", s),
+        visible: (s) => field("visible", s),
+        count: (s) => field("count", s),
+    };
+}
+export function createReadCtx(mem) {
+    const row = fieldReaders();
+    return {
+        mem,
+        page: {
+            text: (s) => row.text(s),
+            texts: (s) => row.texts(s),
+            number: (s) => row.number(s),
+            attr: (s, name) => row.attr(s, name),
+            value: (s) => row.value(s),
+            visible: (s) => row.visible(s),
+            count: (s) => row.count(s),
+            list: (selector, build) => {
+                const fields = {};
+                for (const [name, reader] of Object.entries(build(fieldReaders()))) {
+                    fields[name] = reader.plan;
+                }
+                return new Reader({ kind: "list", selector, fields });
+            },
+            table: (selector, columns) => new Reader({ kind: "table", selector, columns: { ...columns } }),
+            fn: (read) => new Reader({ kind: "fn", fn: read }),
+        },
+    };
+}

package/dist/engine/read/run-read.d.ts

@@ -0,0 +1,17 @@
+import type { Page } from "@playwright/test";
+import type { MemPage } from "../mem/mem.js";
+import type { ReadSpec } from "./read-key.js";
+/** A read's leaves by path (`post.likes`), `null` where the page did not show it, plus why a path is missing. */
+export interface ReadResult {
+    values: Map<string, unknown>;
+    notes: Map<string, string>;
+}
+/**
+ * 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 declare function settlePage(page: Page, quietMs?: number, capMs?: number): Promise<void>;
+/** The first number in a display text: `"$1,299.00"` -> 1299, `"41 likes"` -> 41, no number -> null. */
+export declare function firstNumber(text: unknown): number | null;
+/** Reads every field of every spec, in parallel, into leaves by path. */
+export declare function runReadSpecs(page: Page, mem: MemPage, specs: readonly ReadSpec[]): Promise<ReadResult>;