waygraph 0.16.1 → 0.16.4

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

@@ -1,52 +1,8 @@
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 import { AutoSession } from "./auto-session.js";
 import { SessionMeta } from "./files.js";
-import { type ApplyPathResult, type AutoSessionInit, type ConsoleLogEntry, type DomSnapshot, type InspectDomOptions, type SessionSnapshot, type StorageSnapshot, type StubFileKind, type TraceStep } from "./helpers.js";
-export type StatusOrSendResponse = {
-    ok: true;
-    snapshot: SessionSnapshot;
-    quit: boolean;
-} | {
-    ok: false;
-    error: string;
-};
-export type DomResponse = {
-    ok: true;
-    snapshot: DomSnapshot;
-} | {
-    ok: false;
-    error: string;
-};
-export type TraceResponse = {
-    ok: true;
-    trace: TraceStep[];
-} | {
-    ok: false;
-    error: string;
-};
-export type ConsoleResponse = {
-    ok: true;
-    consoleLog: ConsoleLogEntry[];
-} | {
-    ok: false;
-    error: string;
-};
-export type StorageResponse = ({
-    ok: true;
-} & StorageSnapshot) | {
-    ok: false;
-    error: string;
-};
-export type ReachResponse = ApplyPathResult;
-export type HighlightResponse = {
-    ok: true;
-    painted: number;
-    missing: string[];
-    snapshot: SessionSnapshot;
-} | {
-    ok: false;
-    error: string;
-};
+import { type AutoSessionInit, type InspectDomOptions, type StubFileKind } from "./helpers.js";
+import type { HelloResponse, ConsoleResponse, DomResponse, HighlightResponse, ReachResponse, ReadResponse, StatusOrSendResponse, StorageResponse, TraceResponse } from "./protocol.js";
 /**
  * Client-side: sends one request to a running session and returns its
  * response. Reports a stale/unreachable session as an error within
@@ -94,6 +50,16 @@ export declare function requestSession(projectDir: string, sessionId: string, re
 export declare function requestSession(projectDir: string, sessionId: string, request: {
     op: "storage";
 }, timeoutMs?: number): Promise<StorageResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "hello";
+}, timeoutMs?: number): Promise<HelloResponse | {
+    ok: false;
+    error: string;
+}>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "read";
+    path?: string;
+}, timeoutMs?: number): Promise<ReadResponse>;
 export declare function requestSession(projectDir: string, sessionId: string, request: {
     op: "reach";
     checkpoint: string;
@@ -110,7 +76,9 @@ export declare function requestSession(projectDir: string, sessionId: string, re
  * already prevents true parallelism, but two overlapping `await`-heavy
  * handlers could still interleave against the same page/mem.
  */
-export declare function serveSession(session: AutoSession, projectDir: string, sessionId: string, headless?: boolean): Promise<void>;
+export declare function serveSession(session: AutoSession, projectDir: string, sessionId: string, headless?: boolean, 
+/** After a quit closed the session and removed its files: the session process exits here. */
+onShutdown?: () => void): Promise<void>;
 /** Entry point for the hidden `__auto-serve` CLI command (runs in the detached child). */
 export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: string): Promise<void>;
 /**

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

@@ -5,7 +5,7 @@
  * See openspec/changes/waygraph-auto-cli-session-control.
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, openSync, rmSync, writeFileSync, } from "node:fs";
+import { mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { connect, createServer } from "node:net";
 import { dirname, join } from "node:path";
@@ -15,6 +15,8 @@ import { fileURLToPath } from "node:url";
 import { ignorePageGone } from "../../engine/page-gone.js";
 import { AutoSession } from "./auto-session.js";
 import { generateSessionId, isPidAlive, logPathFor, metaPath, readSessionMeta, removeSessionFiles, resolveSessionMeta, sessionDir, socketDir, socketPathFor, writeGlobalSessionMeta } from "./files.js";
+import { createFeed } from "./feed.js";
+import { SESSION_PROTOCOL_VERSION } from "./protocol.js";
 /** Reads newline-delimited JSON off a socket, one message at a time. */
 function readOneMessage(sock, timeoutMs) {
     return new Promise((resolvePromise, reject) => {
@@ -109,7 +111,9 @@ export async function requestSession(projectDir, sessionId, request, timeoutMs =
  * already prevents true parallelism, but two overlapping `await`-heavy
  * handlers could still interleave against the same page/mem.
  */
-export async function serveSession(session, projectDir, sessionId, headless = true) {
+export async function serveSession(session, projectDir, sessionId, headless = true, 
+/** After a quit closed the session and removed its files: the session process exits here. */
+onShutdown = () => { }) {
     mkdirSync(sessionDir(projectDir), { recursive: true });
     mkdirSync(socketDir(), { recursive: true });
     const socketPath = socketPathFor(sessionId);
@@ -120,6 +124,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
         queue = next.catch(() => { });
         return next;
     };
+    const feed = createFeed();
     const server = createServer((sock) => {
         let buf = "";
         sock.on("data", (chunk) => {
@@ -141,6 +146,15 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
             sock.write(JSON.stringify({ ok: false, error: "malformed request (invalid JSON)" }) + "\n");
             return;
         }
+        // Neither waits behind a running request: hello names the protocol, subscribe turns this socket into a live feed.
+        if (request.op === "hello") {
+            sock.write(JSON.stringify({ ok: true, protocol: SESSION_PROTOCOL_VERSION, waygraph: waygraphVersion(), sessionId, here: session.where }) + "\n");
+            return;
+        }
+        if (request.op === "subscribe") {
+            feed.add(sock);
+            return;
+        }
         await enqueue(async () => {
             let response;
             let shouldQuit = false;
@@ -165,6 +179,9 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
                 else if (request.op === "console") {
                     response = { ok: true, consoleLog: session.getConsoleLog() };
                 }
+                else if (request.op === "read") {
+                    response = { ok: true, ...(await session.read(request.path)) };
+                }
                 else if (request.op === "storage") {
                     response = { ok: true, ...(await session.inspectStorage()) };
                 }
@@ -213,6 +230,9 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
                 response = { ok: false, error: err instanceof Error ? err.message : String(err) };
             }
             sock.write(JSON.stringify(response) + "\n");
+            // Whatever changed (a step ran, a reload, a raw action): subscribers get the new snapshot.
+            if (response.ok && "snapshot" in response && "sections" in response.snapshot)
+                feed.send({ type: "snapshot", snapshot: response.snapshot });
             if (shouldQuit) {
                 setImmediate(() => void shutdown());
             }
@@ -224,9 +244,10 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
             return;
         shuttingDown = true;
         server.close();
+        feed.close();
         await session.close().catch(ignorePageGone);
         removeSessionFiles(projectDir, sessionId);
-        process.exit(0);
+        onShutdown();
     }
     await new Promise((resolvePromise, reject) => {
         server.on("error", reject);
@@ -248,7 +269,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
 /** Entry point for the hidden `__auto-serve` CLI command (runs in the detached child). */
 export async function runAutoServeCommand(init, sessionId) {
     const session = await AutoSession.start({ ...init, sessionId });
-    await serveSession(session, init.projectDir, sessionId, init.headless ?? true);
+    await serveSession(session, init.projectDir, sessionId, init.headless ?? true, () => process.exit(0));
     // Tell the parent that spawned us (spawnDetachedSession) we are serving, then let it go.
     process.send?.({ ready: true });
     process.disconnect?.();
@@ -372,3 +393,12 @@ export async function runAttachLoop(projectDir, sessionId) {
         rl.close();
     }
 }
+/** This package's version, for `hello` (the file sits three levels below the package root in src/ and dist/). */
+function waygraphVersion() {
+    try {
+        return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}

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

@@ -0,0 +1,127 @@
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
+import type { RunEvent } from "../../engine/run/events.js";
+import type { ApplyPathResult, ConsoleLogEntry, DomSnapshot, InspectDomOptions, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
+import type { SessionRead } from "./read.js";
+/** Bumped when a request or response changes shape (adding an op or an optional field does not). */
+export declare const SESSION_PROTOCOL_VERSION = 1;
+/** Every request a session answers. */
+export type SessionRequest = {
+    op: "hello";
+} | {
+    op: "subscribe";
+} | {
+    op: "status";
+} | {
+    op: "send";
+    pick: string;
+} | ({
+    op: "dom";
+} & InspectDomOptions) | {
+    op: "trace";
+} | {
+    op: "click";
+    selector: string;
+} | {
+    op: "type";
+    selector: string;
+    text: string;
+} | {
+    op: "press";
+    selector: string;
+    key: string;
+} | {
+    op: "goto";
+    url: string;
+} | {
+    op: "reload";
+} | {
+    op: "reach";
+    checkpoint: string;
+} | {
+    op: "resync";
+} | {
+    op: "console";
+} | {
+    op: "storage";
+} | {
+    op: "read";
+    path?: string;
+} | {
+    op: "upload";
+    selector: string;
+    stub: StubFileKind | {
+        filePath: string;
+    };
+} | ({
+    op: "highlight";
+} & PilotHighlightFixtures);
+export type StatusOrSendResponse = {
+    ok: true;
+    snapshot: SessionSnapshot;
+    quit: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export type DomResponse = {
+    ok: true;
+    snapshot: DomSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+export type TraceResponse = {
+    ok: true;
+    trace: TraceStep[];
+} | {
+    ok: false;
+    error: string;
+};
+export type ConsoleResponse = {
+    ok: true;
+    consoleLog: ConsoleLogEntry[];
+} | {
+    ok: false;
+    error: string;
+};
+export type StorageResponse = ({
+    ok: true;
+} & StorageSnapshot) | {
+    ok: false;
+    error: string;
+};
+export type ReachResponse = ApplyPathResult;
+export type ReadResponse = ({
+    ok: true;
+} & SessionRead) | {
+    ok: false;
+    error: string;
+};
+export type HighlightResponse = {
+    ok: true;
+    painted: number;
+    missing: string[];
+    snapshot: SessionSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+/** What `hello` answers: the protocol a client is talking to, and where the session is (`null` until a status or step has located it). */
+export type HelloResponse = {
+    ok: true;
+    protocol: number;
+    waygraph: string;
+    sessionId: string;
+    here: string | null;
+};
+/** One line of a `subscribe` feed: every run event in the session (steps, reads), and the snapshot after each change. */
+export type SessionStreamMessage = {
+    type: "event";
+    event: RunEvent;
+} | {
+    type: "snapshot";
+    snapshot: SessionSnapshot;
+};
+export type SessionResponse = HelloResponse | StatusOrSendResponse | DomResponse | TraceResponse | ConsoleResponse | StorageResponse | ReachResponse | ReadResponse | HighlightResponse;
+/** Every op, once: the server, the CLI and `pilot` all check against this list. */
+export declare const SESSION_OPS: readonly ["hello", "subscribe", "status", "send", "dom", "trace", "console", "storage", "read", "upload", "click", "type", "press", "goto", "reload", "reach", "resync", "highlight"];

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;
-}