waygraph 0.15.47 → 0.15.50

package/dist/analysis/graph.js

@@ -229,12 +229,12 @@ function isBlockLike(val) {
     const instruction = obj.instruction;
     return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
 }
-/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
 function isNavBlockMarked(val) {
     const kind = val.__waygraphKind;
     return kind === "nav" || kind === "page";
 }
-/** Set by `defineAssertBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineAssertBlock` (non-enumerable) - see src/core.ts. */
 function isAssertBlockMarked(val) {
     return val.__waygraphKind === "assert";
 }

package/dist/auto-session/session.js

@@ -3,11 +3,11 @@ import { CONSOLE_LOG_MAX_ENTRIES, FULL_MODE_DEFAULT_DEPTH, FULL_MODE_MAX_NODES,
 import { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, phaseToOverlayFixtures, describeOverlayFixtures, updatePilotOverlay } from "../pilot-overlay.js";
 import { buildExploreContext, buildExploreMenu } from "../session/auto-explore.js";
 import { MemPage } from "../mem-page.js";
-import { Engine } from "../engine.js";
+import { Engine } from "../core.js";
 import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../session/auto-explore-run.js";
 import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../analysis/coverage-gap.js";
 import { runStubPhase } from "../highlights.js";
-import { verboseLog } from "../verbose-log.js";
+import { verboseLog } from "./verbose-log.js";
 import { findBlockPathDetailed } from "../analysis/graph.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
@@ -54,7 +54,7 @@ export class AutoSession {
         this.headless = headless;
     }
     static async start(init) {
-        const baseURL = init.baseURL ?? resolveBaseUrl(init.projectDir);
+        const baseURL = init.baseURL ?? (await resolveBaseUrl(init.projectDir));
         const skipNav = init.skipInitialNavigation === true;
         const startUrl = skipNav ? undefined : (init.startUrl ?? baseURL);
         const exploreOpts = {

package/dist/cli/discover.d.ts

@@ -22,7 +22,7 @@ export declare function isBlockLike(val: unknown): val is {
         act: unknown;
     };
 };
-/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
 export declare function isNavBlockMarked(val: Record<string, unknown>): boolean;
 export declare const NAV_METHOD_CALLS: readonly ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
 /**

package/dist/cli/discover.js

@@ -128,7 +128,7 @@ export function isBlockLike(val) {
     const instruction = obj.instruction;
     return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
 }
-/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
 export function isNavBlockMarked(val) {
     return val.__waygraphKind === "nav";
 }

package/dist/cli/flags.d.ts

@@ -1,3 +1,4 @@
+import { resolveBaseUrl } from "../config.js";
 interface RunFlags {
     step?: boolean;
     autoplay?: boolean;
@@ -73,16 +74,18 @@ export declare function applyRunFlags(flags: RunFlags, opts?: {
     allowDemoUi?: boolean;
 }): void;
 /**
- * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
- * package.json `waygraph.baseUrl` (or `baseURL`), then playwright.config `baseURL`.
+ * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set - see `../config.js`'s own
+ * `resolveBaseUrl` for the full resolution order (env / `.env` / `waygraph.config.*` /
+ * package.json / playwright.config). Re-exported here so existing importers of this module
+ * don't need to change their import path.
  */
-export declare function resolveBaseUrl(projectDir: string): string | undefined;
+export { resolveBaseUrl };
 /**
  * Friendly demo defaults: STEP on; headed only for live watch (no --video).
  * --video / --auto-play-video => headless unless --non-headless.
  * Call after applyRunFlags so explicit flags already won.
  */
-export declare function applyDemoDefaults(projectDir: string): void;
+export declare function applyDemoDefaults(projectDir: string): Promise<void>;
 export declare function resolveProjectDir(flags: RunFlags, fallbackIndex?: number): string;
 export declare function resolveSpec(flags: RunFlags): string | undefined;
 /** `shop.flow.ts` / `src/flows/cart-bulk.flow.ts` / absolute path — not a Checkpoint or export id. */
@@ -92,4 +95,3 @@ export declare function looksLikeFlowFileRef(ref: string): boolean;
  * `src/flows/shop.flow.ts` → `shopFlow`; leaves `loginFlow then nav-cart` alone.
  */
 export declare function expandSpecFlowFiles(projectDir: string, spec: string): Promise<string>;
-export {};

package/dist/cli/flags.js

@@ -1,7 +1,8 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { basename, join, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { walkDir } from "./discover.js";
+import { resolveBaseUrl } from "../config.js";
 function takeFlagValue(argv, i, a, flag) {
     if (a.startsWith(flag + "=")) {
         return { value: a.slice(flag.length + 1), nextI: i };
@@ -310,42 +311,18 @@ export function applyRunFlags(flags, opts) {
     }
 }
 /**
- * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
- * package.json `waygraph.baseUrl` (or `baseURL`), then playwright.config `baseURL`.
+ * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set - see `../config.js`'s own
+ * `resolveBaseUrl` for the full resolution order (env / `.env` / `waygraph.config.*` /
+ * package.json / playwright.config). Re-exported here so existing importers of this module
+ * don't need to change their import path.
  */
-export function resolveBaseUrl(projectDir) {
-    const pkgPath = join(projectDir, "package.json");
-    if (existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-            const fromPkg = pkg.waygraph?.baseUrl ??
-                pkg.waygraph?.baseURL ??
-                pkg.config?.waygraph?.baseUrl ??
-                pkg.config?.waygraph?.baseURL;
-            if (typeof fromPkg === "string" && fromPkg.trim())
-                return fromPkg.trim();
-        }
-        catch {
-            // ignore malformed package.json - fall through to playwright
-        }
-    }
-    for (const name of ["playwright.config.ts", "playwright.config.mts", "playwright.config.js", "playwright.config.mjs"]) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
-            continue;
-        const src = readFileSync(p, "utf-8");
-        const m = src.match(/baseURL\s*:\s*["']([^"']+)["']/);
-        if (m?.[1])
-            return m[1];
-    }
-    return undefined;
-}
+export { resolveBaseUrl };
 /**
  * Friendly demo defaults: STEP on; headed only for live watch (no --video).
  * --video / --auto-play-video => headless unless --non-headless.
  * Call after applyRunFlags so explicit flags already won.
  */
-export function applyDemoDefaults(projectDir) {
+export async function applyDemoDefaults(projectDir) {
     if (process.env.WAYGRAPH_STEP === undefined)
         process.env.WAYGRAPH_STEP = "1";
     if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {
@@ -363,7 +340,7 @@ export function applyDemoDefaults(projectDir) {
         }
     }
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(projectDir);
+        const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }

package/dist/cli/run-chain.js

@@ -41,7 +41,7 @@ mod.startRunner();
 export async function runChain(projectDir, spec) {
     const expanded = await expandSpecFlowFiles(projectDir, spec);
     if (process.env.WAYGRAPH_VIDEO && !process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(projectDir);
+        const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }

package/dist/cli.js

@@ -14,7 +14,7 @@
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */
-import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./agent-dive.js";
+import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./commands/agent-dive-scaffold.js";
 import { usage } from "./cli/usage.js";
 import { listCase, navCase } from "./commands/list.js";
 import { checkCase, typecheckCase, validateCase } from "./commands/check.js";

package/dist/{agent-dive.js → commands/agent-dive-scaffold.js}

@@ -6,8 +6,8 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 function packageRoot() {
-    // dist/agent-dive.js -> ..
-    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    // dist/commands/agent-dive-scaffold.js -> ../..
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
 function agentsTemplateDir() {
     return join(packageRoot(), "templates", "agents");

package/dist/commands/agent-dive.js

@@ -1,5 +1,5 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { runAgentDive } from "../agent-dive.js";
+import { runAgentDive } from "./agent-dive-scaffold.js";
 import { resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 export async function agentDiveCase(args) {

package/dist/commands/check.js

@@ -67,7 +67,7 @@ export async function runChainAuto(projectDir, fromTag, toTag) {
     const spec = path.join(" then ");
     console.error(`waygraph chain auto: ${fromTag} -> ${toTag} via ${spec}`);
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(projectDir);
+        const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }

package/dist/commands/run.js

@@ -24,7 +24,7 @@ export async function runCase(args) {
         process.exit(1);
     }
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(proj);
+        const resolved = await resolveBaseUrl(proj);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
@@ -60,13 +60,13 @@ export async function chainCase(args) {
     }
     const proj = resolve(flags.blocks ? (flags.positionals[0] ?? process.cwd()) : (flags.positionals[1] ?? process.cwd()));
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(proj);
+        const resolved = await resolveBaseUrl(proj);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
     // If caller asked for step overlay, behave like demo; else like run.
     if (flags.step === true || process.env.WAYGRAPH_STEP === "1") {
-        applyDemoDefaults(proj);
+        await applyDemoDefaults(proj);
     }
     await runChain(proj, spec);
     return;
@@ -92,7 +92,7 @@ export async function demoCase(args) {
     if (flags.step === undefined && process.env.WAYGRAPH_STEP === undefined) {
         process.env.WAYGRAPH_STEP = "1";
     }
-    applyDemoDefaults(proj);
+    await applyDemoDefaults(proj);
     console.error(`waygraph demo: STEP=${process.env.WAYGRAPH_STEP === "1" ? "on" : "off"}` +
         ` AUTO_NEXT=${process.env.WAYGRAPH_AUTOPLAY === "1" ? "on" : "off"}` +
         ` HEADED=${process.env.WAYGRAPH_HEADED === "0" ? "off" : "on"}` +

package/dist/commands/session.js

@@ -62,7 +62,7 @@ export async function sessionCase(args, command) {
                 console.error(`waygraph browser: no such directory: ${proj}`);
                 process.exit(1);
             }
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
             try {
                 const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
                 const result = await browserStart({
@@ -148,7 +148,7 @@ export async function sessionCase(args, command) {
             const flags = parseRunFlags(flagArgs);
             applyRunFlags(flags);
             const proj = resolve(flags.positionals[0] ?? process.cwd());
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
             try {
                 const result = await pilotStart({
                     projectDir: proj,
@@ -483,7 +483,7 @@ export async function sessionCase(args, command) {
             process.exit(1);
         }
         if (!process.env.WAYGRAPH_BASE_URL) {
-            const resolved = resolveBaseUrl(proj);
+            const resolved = await resolveBaseUrl(proj);
             if (resolved)
                 process.env.WAYGRAPH_BASE_URL = resolved;
         }
@@ -510,7 +510,7 @@ export async function sessionCase(args, command) {
             console.error("waygraph auto --detach requires --cli (headful has no session control)");
             process.exit(1);
         }
-        const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+        const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
         try {
             const meta = await spawnDetachedSession({
                 projectDir: proj,
@@ -535,7 +535,7 @@ export async function sessionCase(args, command) {
         }
         if (flags.blocks && isFileSelectToken(flags.blocks)) {
             const blocksSelect = parseBlocksSelect(flags.blocks);
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
             await runAutoExplore(proj, baseURL
                 ? { cli: cliPicker, baseURL, blocksSelect }
                 : { cli: cliPicker, blocksSelect });
@@ -565,7 +565,7 @@ export async function sessionCase(args, command) {
         }
         return;
     }
-    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
     await runAutoExplore(proj, baseURL ? { cli: cliPicker, baseURL } : { cli: cliPicker });
     return;
 }
@@ -578,7 +578,7 @@ export async function autoServeCase(args) {
         console.error("waygraph __auto-serve: missing --session-id");
         process.exit(1);
     }
-    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
     const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
     let headless;
     if (flags.headlessBrowser)

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+export interface WaygraphConfig {
+    /** Same value `resolveBaseUrl` would otherwise read from package.json's `waygraph.baseUrl`. */
+    baseUrl?: string;
+}
+/** Identity helper, purely for editor type-checking/autocomplete - same role `defineConfig` plays
+ * in a `playwright.config.ts` or `vite.config.ts`. `export default defineConfig({ ... })`. */
+export declare function defineConfig(config: WaygraphConfig): WaygraphConfig;
+/**
+ * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
+ * (the same mechanism that already lets a consumer's `.block.ts`/`.flow.ts` import directly), so
+ * no separate loader/transpile step is needed here. A broken config file throws loud, naming the
+ * file - silently swallowing it would make a missing `baseUrl` look like "nobody configured
+ * anything" instead of "your config file has a bug."
+ */
+export declare function loadWaygraphConfig(projectDir: string): Promise<WaygraphConfig | undefined>;
+/**
+ * Single source of truth for a project's base URL. Was three independently drifted copies
+ * (`src/cli/flags.ts`, `src/traverse/run.ts`, `src/session/auto-explore-run.ts`), each checking
+ * a slightly different subset of sources in a different order - real duplication, not just
+ * stylistic, since one copy skipped `config.waygraph.*` nesting and another checked
+ * `WAYGRAPH_BASE_URL` first instead of last. Checked in this order:
+ *
+ * 1. `WAYGRAPH_BASE_URL` - a real shell export, or one loaded from a `.env` file (see
+ *    `loadEnvFiles`, called here so every caller gets native `.env` support for free, not just
+ *    whichever command remembered to call it).
+ * 2. A `waygraph.config.*` file's `baseUrl`.
+ * 3. `package.json`'s `waygraph.baseUrl`/`baseURL` (`config.waygraph.*` also checked - a common
+ *    nested-config convention some tooling uses).
+ * 4. `playwright.config.*`'s own `baseURL` (regex-read as text, never imported - importing a
+ *    consumer's real playwright.config risks pulling in `@playwright/test`'s own global setup
+ *    as a side effect, which resolving a URL string has no business doing).
+ */
+export declare function resolveBaseUrl(projectDir: string): Promise<string | undefined>;

package/dist/config.js

@@ -0,0 +1,94 @@
+// waygraph.config.* - new, additive, optional. package.json's own "waygraph" field (baseUrl)
+// keeps working untouched; this is a second, richer place to put the same kind of project-level
+// setting, for consumers who'd rather have a real typed file than a JSON field. Real ask: "I
+// think its time to add waygraph config now."
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadEnvFiles } from "./env-file.js";
+/** Identity helper, purely for editor type-checking/autocomplete - same role `defineConfig` plays
+ * in a `playwright.config.ts` or `vite.config.ts`. `export default defineConfig({ ... })`. */
+export function defineConfig(config) {
+    return config;
+}
+const CONFIG_FILENAMES = [
+    "waygraph.config.ts",
+    "waygraph.config.mts",
+    "waygraph.config.mjs",
+    "waygraph.config.js",
+    "waygraph.config.cjs",
+];
+/**
+ * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
+ * (the same mechanism that already lets a consumer's `.block.ts`/`.flow.ts` import directly), so
+ * no separate loader/transpile step is needed here. A broken config file throws loud, naming the
+ * file - silently swallowing it would make a missing `baseUrl` look like "nobody configured
+ * anything" instead of "your config file has a bug."
+ */
+export async function loadWaygraphConfig(projectDir) {
+    for (const name of CONFIG_FILENAMES) {
+        const p = join(projectDir, name);
+        if (!existsSync(p))
+            continue;
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(p).href));
+        }
+        catch (err) {
+            throw new Error(`waygraph: failed to load ${name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return mod.default ?? mod;
+    }
+    return undefined;
+}
+/**
+ * Single source of truth for a project's base URL. Was three independently drifted copies
+ * (`src/cli/flags.ts`, `src/traverse/run.ts`, `src/session/auto-explore-run.ts`), each checking
+ * a slightly different subset of sources in a different order - real duplication, not just
+ * stylistic, since one copy skipped `config.waygraph.*` nesting and another checked
+ * `WAYGRAPH_BASE_URL` first instead of last. Checked in this order:
+ *
+ * 1. `WAYGRAPH_BASE_URL` - a real shell export, or one loaded from a `.env` file (see
+ *    `loadEnvFiles`, called here so every caller gets native `.env` support for free, not just
+ *    whichever command remembered to call it).
+ * 2. A `waygraph.config.*` file's `baseUrl`.
+ * 3. `package.json`'s `waygraph.baseUrl`/`baseURL` (`config.waygraph.*` also checked - a common
+ *    nested-config convention some tooling uses).
+ * 4. `playwright.config.*`'s own `baseURL` (regex-read as text, never imported - importing a
+ *    consumer's real playwright.config risks pulling in `@playwright/test`'s own global setup
+ *    as a side effect, which resolving a URL string has no business doing).
+ */
+export async function resolveBaseUrl(projectDir) {
+    loadEnvFiles(projectDir);
+    if (process.env.WAYGRAPH_BASE_URL)
+        return process.env.WAYGRAPH_BASE_URL;
+    const config = await loadWaygraphConfig(projectDir);
+    if (config?.baseUrl && config.baseUrl.trim())
+        return config.baseUrl.trim();
+    const pkgPath = join(projectDir, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            const fromPkg = pkg.waygraph?.baseUrl ??
+                pkg.waygraph?.baseURL ??
+                pkg.config?.waygraph?.baseUrl ??
+                pkg.config?.waygraph?.baseURL;
+            if (typeof fromPkg === "string" && fromPkg.trim())
+                return fromPkg.trim();
+        }
+        catch {
+            // ignore malformed package.json - fall through to playwright.config
+        }
+    }
+    for (const name of ["playwright.config.ts", "playwright.config.mts", "playwright.config.js", "playwright.config.mjs"]) {
+        const p = join(projectDir, name);
+        if (!existsSync(p))
+            continue;
+        const src = readFileSync(p, "utf-8");
+        const m = src.match(/baseURL\s*:\s*["']([^"']+)["']/);
+        if (m?.[1])
+            return m[1];
+    }
+    return undefined;
+}

package/dist/{engine/core.js → core/block.js}

@@ -1,15 +1,15 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_MODVERIFY_FUNCTION_FORM, MSG_MODVERIFY_NOT_FOUND_BY_INDEX, MSG_MODVERIFY_NOT_FOUND_BY_NAME, } from "../errors.js";
 export function findBlockIndex(middle, block) {
     if (typeof block === "number") {
         if (block < 0 || block >= middle.length) {
-            throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `Flow: no Block at index ${block} in this flow (has ${middle.length})`);
+            throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX(block, middle.length));
         }
         return block;
     }
     const blockName = typeof block === "string" ? block : block.name;
     const index = middle.findIndex((b) => b.name === blockName);
     if (index === -1) {
-        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
+        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME(blockName, middle.map((b) => b.name).join(", ")));
     }
     return index;
 }
@@ -229,15 +229,15 @@ export function withStubOnError(block, stub) {
 export function modVerify(block, nameOrIndex, newCheck) {
     const verify = block.instruction.verify;
     if (typeof verify === "function") {
-        throw new WaygraphError("WG_MODVERIFY_FUNCTION_FORM", `modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
+        throw new WaygraphError("WG_MODVERIFY_FUNCTION_FORM", MSG_MODVERIFY_FUNCTION_FORM(block.name));
     }
     const traits = verify ?? [];
     const index = typeof nameOrIndex === "number" ? nameOrIndex : traits.findIndex((t) => t.name === nameOrIndex);
     const existing = traits[index];
     if (!existing) {
         throw new WaygraphError("WG_MODVERIFY_NOT_FOUND", typeof nameOrIndex === "number"
-            ? `modVerify: "${block.name}" has no verify trait at index ${nameOrIndex} (has ${traits.length})`
-            : `modVerify: "${block.name}" has no verify trait named "${nameOrIndex}" (has: ${traits.map((t) => t.name).join(", ") || "none"})`);
+            ? MSG_MODVERIFY_NOT_FOUND_BY_INDEX(block.name, nameOrIndex, traits.length)
+            : MSG_MODVERIFY_NOT_FOUND_BY_NAME(block.name, nameOrIndex, traits.map((t) => t.name).join(", ")));
     }
     const replacement = typeof newCheck === "function"
         ? { name: typeof nameOrIndex === "string" ? nameOrIndex : existing.name, check: newCheck }

package/dist/core/blocks/api.d.ts

@@ -0,0 +1,54 @@
+import type { Checkpoint, DefinedBlock } from "../../types.js";
+import type { Trait } from "../../trait.js";
+import { MemPage } from "../../mem-page.js";
+import type { MemKey } from "../../mem-page.js";
+import type { APIRequestContext, APIResponse } from "@playwright/test";
+/** What `resolve`/`verify` see: the response's status and parsed body, nothing Playwright-specific. */
+export interface ApiCallResult {
+    status: number;
+    ok: boolean;
+    /** `response.json()` if the body parses as JSON, else the raw text (or `undefined` if neither). */
+    body: unknown;
+}
+export interface ApiBlockOptions<In extends Checkpoint<string>, Out extends Checkpoint<string>> {
+    name: string;
+    description?: string;
+    /**
+     * Make the request - `request` is Playwright's own `page.request` (same cookies/origin as the
+     * browser context, so an authenticated UI session carries over to the API call for free).
+     * @example call: ({ request }) => request.get("/api/orders/1")
+     */
+    call: (ctx: {
+        request: APIRequestContext;
+        mem: MemPage;
+    }) => Promise<APIResponse>;
+    /**
+     * HTTP method shown in the network-tab overlay (GET/POST/PATCH/...) - `APIResponse` (unlike a
+     * page's own `Response`) carries no back-reference to the request that produced it, so this
+     * can't be read back automatically; defaults to "GET" if omitted. Purely cosmetic - never
+     * affects the actual request `call` makes.
+     * @example method: "POST"
+     */
+    method?: string;
+    /** Pure, like every other Block's resolve - classifies the response into a Checkpoint tag. */
+    resolve: (result: ApiCallResult) => Out;
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    requires?: readonly MemKey<any>[];
+    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+}
+/**
+ * A Block whose `act()` is a real HTTP request, not a page interaction - lets one Flow narrate a
+ * UI step (`.gotoPage()`) and a backend check (`.method(checkOrderCreated)`) as the same state
+ * machine, checked by the same Trait/verify system. Runs through `page.request`, so it shares the
+ * browser context's cookies/origin - no separate auth dance for an already-logged-in session.
+ * @example
+ * const CheckOrderCreated = defineApiBlock<LoggedIn, OrderConfirmed | OrderFailed>({
+ *   name: "check-order-created",
+ *   call: ({ request }) => request.get("/api/orders/latest"),
+ *   resolve: (r) => (r.ok ? checkpoint("OrderConfirmed") : checkpoint("OrderFailed")),
+ *   verify: [Trait.disabled],
+ * });
+ */
+export declare function defineApiBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(options: ApiBlockOptions<In, Out>): DefinedBlock<In, Out>;

package/dist/core/blocks/api.js

@@ -0,0 +1,75 @@
+import { defineBlock } from "../block.js";
+import { key } from "../../mem-page.js";
+// Internal scratch key threading act()'s result to observe()/resolve() - Instruction has no other
+// channel for this (resolve is pure, given only what observe returns). Identity-keyed, so this can
+// never collide with a real author's own MemKey even if names happened to match; safe to share one
+// instance across every ApiBlock since runGraph runs act->observe->resolve fully serially per Block.
+const API_RESULT_SCRATCH = key("__wgApiBlockResult");
+/**
+ * A Block whose `act()` is a real HTTP request, not a page interaction - lets one Flow narrate a
+ * UI step (`.gotoPage()`) and a backend check (`.method(checkOrderCreated)`) as the same state
+ * machine, checked by the same Trait/verify system. Runs through `page.request`, so it shares the
+ * browser context's cookies/origin - no separate auth dance for an already-logged-in session.
+ * @example
+ * const CheckOrderCreated = defineApiBlock<LoggedIn, OrderConfirmed | OrderFailed>({
+ *   name: "check-order-created",
+ *   call: ({ request }) => request.get("/api/orders/latest"),
+ *   resolve: (r) => (r.ok ? checkpoint("OrderConfirmed") : checkpoint("OrderFailed")),
+ *   verify: [Trait.disabled],
+ * });
+ */
+export function defineApiBlock(options) {
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                const startedAt = Date.now();
+                const response = await options.call({ request: page.request, mem });
+                const ms = Date.now() - startedAt;
+                let body;
+                try {
+                    body = await response.json();
+                }
+                catch {
+                    body = await response.text().catch(() => undefined);
+                }
+                mem.set(API_RESULT_SCRATCH, { status: response.status(), ok: response.ok(), body });
+                // Best-effort, demo-only visibility - an API step has no DOM change and no ring of its own,
+                // so without this it's a silent title flash. No-ops outside a demo/pilot/auto run (see
+                // addNetworkEntry's own guard) and never fails the Block if painting the panel throws.
+                // Same network-tab panel real page traffic feeds too (network-capture.js) - this is the
+                // page.request side of it (a separate APIRequestContext, never seen by page.on('request')).
+                try {
+                    // recordNetworkEntry, not a bare addNetworkEntry evaluate - it also persists this entry
+                    // to page.__wgNetworkHistory (Node-side, survives navigation), so it isn't lost the
+                    // moment a later step in the same Flow navigates and wipes the panel's DOM.
+                    const { recordNetworkEntry } = await import("../../runner/network-capture.js");
+                    await recordNetworkEntry(page, {
+                        method: options.method || "GET",
+                        url: response.url(),
+                        status: response.status(),
+                        ok: response.ok(),
+                        ms,
+                        resHeaders: response.headers(),
+                        resBody: typeof body === "string" ? body : body !== undefined ? JSON.stringify(body) : undefined,
+                    });
+                }
+                catch {
+                    /* overlay not installed / page already closed - not this Block's job to report that */
+                }
+            },
+            async observe(_page, mem) {
+                return mem.get(API_RESULT_SCRATCH);
+            },
+            resolve: (observed) => options.resolve(observed),
+            ...(options.verify !== undefined ? { verify: options.verify } : {}),
+            ...(options.stubBefore !== undefined ? { stubBefore: options.stubBefore } : {}),
+            ...(options.stubAfter !== undefined ? { stubAfter: options.stubAfter } : {}),
+            ...(options.stubOnError !== undefined ? { stubOnError: options.stubOnError } : {}),
+        },
+    });
+    Object.defineProperty(built, "__waygraphKind", { value: "api", enumerable: false, configurable: false });
+    return built;
+}

package/dist/{engine → core}/blocks/effect.d.ts

@@ -1,7 +1,7 @@
 import type { Block, Checkpoint, DefinedBlock } from "../../types.js";
 import type { MemKey } from "../../mem-page.js";
 import type { Trait } from "../../trait.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 /**
  * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
  * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu

package/dist/{engine → core}/blocks/effect.js

@@ -1,4 +1,4 @@
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 /**
  * {@link defineBlock} constrained for effect-style instance menus: `requires` +
  * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /

package/dist/{engine → core}/blocks/method.d.ts

@@ -1,6 +1,6 @@
 import type { Checkpoint, DefinedBlock } from "../../types.js";
 import type { Trait } from "../../trait.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 import type { MemKey } from "../../mem-page.js";
 /**
  * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps