waygraph 0.15.54 → 0.16.0

package/dist/commands/check.js

@@ -1,192 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { INLINE_SELECTOR_CALL, NAV_METHOD_CALLS, discoverBlocks, discoverFlows, importFlowFile, importModule, isBlockLike, isFlowLike, isNavBlockMarked, walkDir } from "../cli/discover.js";
-import { basename, relative, resolve } from "node:path";
-import { discoverGraph, findBlockPath, findOrphanBlocks } from "../analysis/graph.js";
-import { parseRunFlags, resolveBaseUrl } from "../cli/flags.js";
-import { runChain } from "../cli/run-chain.js";
-import { collectPracticeWarnings, practiceKindLabel } from "../analysis/practices-check.js";
-import { readFileSync } from "node:fs";
-async function validateFlows(projectDir) {
-    const files = discoverFlows(projectDir);
-    const results = [];
-    for (const file of files) {
-        try {
-            const mod = await importFlowFile(file);
-            for (const [exportName, exported] of Object.entries(mod)) {
-                if (isFlowLike(exported)) {
-                    results.push({ file, name: exportName, valid: true });
-                }
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            results.push({ file, name: basename(file, ".ts"), valid: false, error: msg });
-        }
-    }
-    return results;
-}
-/**
- * Walks every `*.block.ts` file under `projectDir`, imports each to find its
- * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
- * that file's own source text for a navigation call. Warning only - never
- * throws, never changes the caller's exit code on its own account (a Block
- * file that fails to import for unrelated reasons is silently skipped here;
- * `validate` is the command that reports import failures).
- */
-function printOrphanReport(projectDir, orphans) {
-    if (orphans.length === 0) {
-        console.log(`waygraph check: no orphan Blocks (every *.block.ts export is wired into a flow)`);
-        return;
-    }
-    for (const o of orphans) {
-        console.warn(`waygraph check: orphan Block ${o.file} (${o.exportName} / "${o.block}") is not referenced in any defineFlow([...]) - wire it into a .flow.ts before chain auto shorthand`);
-    }
-    console.log(`waygraph check: ${orphans.length} orphan Block${orphans.length === 1 ? "" : "s"}`);
-}
-async function requireNoOrphans(projectDir, forCommand) {
-    const orphans = await findOrphanBlocks(projectDir);
-    if (orphans.length === 0)
-        return true;
-    console.error(`waygraph ${forCommand}: ${orphans.length} orphan Block(s) - wire every Block into a .flow.ts before auto shorthand. Run: waygraph check ${projectDir === process.cwd() ? "." : JSON.stringify(projectDir)}`);
-    for (const o of orphans) {
-        console.error(`  - ${o.file} (${o.exportName} / "${o.block}")`);
-    }
-    process.exitCode = 1;
-    return false;
-}
-export async function runChainAuto(projectDir, fromTag, toTag) {
-    if (!(await requireNoOrphans(projectDir, "chain auto")))
-        return;
-    const graph = await discoverGraph(projectDir);
-    const path = findBlockPath(graph, fromTag, toTag);
-    if (!path) {
-        console.error(`waygraph chain auto: no Block path from "${fromTag}" to "${toTag}" in the discovered graph`);
-        process.exitCode = 1;
-        return;
-    }
-    const spec = path.join(" then ");
-    console.error(`waygraph chain auto: ${fromTag} -> ${toTag} via ${spec}`);
-    if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = await resolveBaseUrl(projectDir);
-        if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
-    }
-    await runChain(projectDir, spec);
-}
-function printPracticeReport(projectDir, practiceWarnings) {
-    if (practiceWarnings.length === 0) {
-        console.log(`waygraph check: no bad-practice patterns under ${projectDir}`);
-        return;
-    }
-    for (const w of practiceWarnings) {
-        console.warn(`waygraph check: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
-    }
-    console.log(`waygraph check: ${practiceWarnings.length} bad-practice warning${practiceWarnings.length === 1 ? "" : "s"}`);
-}
-async function checkCommand(projectDir, opts) {
-    const files = discoverBlocks(projectDir);
-    const navWarnings = [];
-    const selWarnings = [];
-    for (const file of files) {
-        let mod;
-        try {
-            mod = await importModule(file);
-        }
-        catch {
-            continue;
-        }
-        let src;
-        for (const [exportName, exported] of Object.entries(mod)) {
-            if (!isBlockLike(exported))
-                continue;
-            src ??= readFileSync(file, "utf-8");
-            // Nav-escape: NavBlocks are exempt (their generated act() is the one
-            // legitimate goto/click call site).
-            if (!isNavBlockMarked(exported) &&
-                NAV_METHOD_CALLS.some((needle) => src.includes(needle))) {
-                navWarnings.push({ file, blockName: exported.name, exportName });
-            }
-            // Inline selector: applies to every Block kind, including NavBlocks -
-            // a Nav's own `verify` array is just as likely to inline a selector.
-            if (INLINE_SELECTOR_CALL.test(src)) {
-                selWarnings.push({ file, blockName: exported.name, exportName });
-            }
-        }
-    }
-    const practiceWarnings = collectPracticeWarnings(projectDir, walkDir, {
-        disabled: opts?.noPractices === true,
-    });
-    return { navWarnings, selWarnings, practiceWarnings };
-}
-async function runTypecheckCommand(projectDir, noPractices) {
-    const { spawnSync } = await import("node:child_process");
-    const tsc = spawnSync("npx", ["tsc", "--noEmit"], {
-        cwd: projectDir,
-        stdio: "inherit",
-        shell: false,
-    });
-    if (tsc.status !== 0) {
-        process.exit(tsc.status === null ? 1 : tsc.status);
-    }
-    if (noPractices)
-        return;
-    const practiceWarnings = collectPracticeWarnings(projectDir, walkDir);
-    printPracticeReport(projectDir, practiceWarnings);
-}
-export async function validateCase(args) {
-    const proj = resolve(args[1] ?? process.cwd());
-    const results = await validateFlows(proj);
-    let failed = 0;
-    for (const r of results) {
-        const rel = relative(proj, r.file);
-        if (r.valid) {
-            console.log(`OK    ${rel}  ${r.name}`);
-        }
-        else {
-            failed++;
-            console.log(`FAIL  ${rel}  ${r.name} -- ${r.error}`);
-        }
-    }
-    if (failed > 0)
-        process.exitCode = 1;
-    return;
-}
-export async function typecheckCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    const proj = resolve(flags.positionals[0] ?? process.cwd());
-    await runTypecheckCommand(proj, flags.noPractices === true);
-    return;
-}
-export async function checkCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    const proj = resolve(flags.positionals[0] ?? process.cwd());
-    const { navWarnings, selWarnings, practiceWarnings } = await checkCommand(proj, flags.noPractices ? { noPractices: true } : undefined);
-    if (navWarnings.length === 0) {
-        console.log(`waygraph check: no navigation found outside NavBlocks under ${proj}`);
-    }
-    else {
-        for (const w of navWarnings) {
-            const rel = relative(proj, w.file);
-            console.warn(`waygraph check: ${rel} (${w.blockName}) calls page.goto/reload/goBack/goForward outside a NavBlock - consider defineNavBlock instead`);
-        }
-        console.log(`waygraph check: ${navWarnings.length} nav warning${navWarnings.length === 1 ? "" : "s"}`);
-    }
-    if (selWarnings.length === 0) {
-        console.log(`waygraph check: no inline selectors found in verify arrays under ${proj}`);
-    }
-    else {
-        for (const w of selWarnings) {
-            const rel = relative(proj, w.file);
-            console.warn(`waygraph check: ${rel} (${w.blockName}) has an inline selector literal in verify - move it into a *Sel object`);
-        }
-        console.log(`waygraph check: ${selWarnings.length} inline-selector warning${selWarnings.length === 1 ? "" : "s"}`);
-    }
-    if (!flags.noPractices) {
-        printPracticeReport(proj, practiceWarnings);
-    }
-    const orphans = await findOrphanBlocks(proj);
-    printOrphanReport(proj, orphans);
-    // Warnings only - never fail exit code. Orphans are reported for
-    // human/agent cleanup; chain auto refuses while any remain.
-    return;
-}

package/dist/commands/map.js

@@ -1,29 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { relative, resolve } from "node:path";
-import { checkMap } from "../analysis/map-check.js";
-export async function mapCase(args) {
-    const proj = resolve(args[1] ?? process.cwd());
-    const result = await checkMap(proj);
-    if (!result.hasMapDir) {
-        console.log(`waygraph map: no src/map/ directory under ${proj} - nothing to check ` +
-            "(this project isn't on the Waygraph Map convention, or hasn't been migrated yet)");
-        return;
-    }
-    console.log(`waygraph map: ${result.nodes.length} node(s) found under ${relative(proj, result.mapRoot)}`);
-    if (result.violations.length === 0) {
-        console.log("waygraph map: 0 violations - every static Nav/Page url verbatim-matches its folder path");
-    }
-    else {
-        for (const v of result.violations) {
-            console.error(`waygraph map: ${v.file} (${v.block}) - ${v.reason}`);
-        }
-        console.error(`waygraph map: ${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}`);
-        // Unlike `check`'s warnings-only stance, a Map violation is exactly
-        // the class of bug this command exists to catch (a fabricated
-        // folder grouping that never matched the real site, e.g. the real
-        // (auth)/signin/ mistake this command's own header comment cites) -
-        // fail loud, not just warn.
-        process.exitCode = 1;
-    }
-    return;
-}

package/dist/commands/run.js

@@ -1,104 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { applyDemoDefaults, applyRunFlags, parseRunFlags, resolveBaseUrl, resolveProjectDir, resolveSpec } from "../cli/flags.js";
-import { runChain } from "../cli/run-chain.js";
-import { resolve } from "node:path";
-import { existsSync } from "node:fs";
-import { runChainAuto } from "./check.js";
-export async function runCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    applyRunFlags(flags);
-    const spec = resolveSpec(flags);
-    if (!spec) {
-        console.error("waygraph run: missing flow/spec — e.g.\n" +
-            "  waygraph run src/flows/shop.flow.ts\n" +
-            "  waygraph run --blocks shopFlow\n" +
-            "  waygraph list   # file → export map\n" +
-            "  Flags: --blocks --data --mem-stub --non-headless --video [dir] --step/--no-step");
-        process.exit(1);
-    }
-    const proj = flags.blocks
-        ? resolveProjectDir(flags, 0)
-        : resolve(flags.positionals[1] ?? process.cwd());
-    if (!existsSync(proj)) {
-        console.error(`waygraph: no such directory: ${proj}`);
-        process.exit(1);
-    }
-    if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = await resolveBaseUrl(proj);
-        if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
-    }
-    await runChain(proj, spec);
-    return;
-}
-export async function chainCase(args) {
-    // Compat alias: chain auto A B -> auto --blocks A B; else -> run --blocks.
-    const flags = parseRunFlags(args.slice(1));
-    applyRunFlags(flags);
-    const first = flags.positionals[0];
-    if (first === "auto") {
-        const fromTag = flags.positionals[1];
-        const toTag = flags.positionals[2];
-        if (!fromTag || !toTag) {
-            console.error("waygraph chain auto: missing <fromCheckpoint> <toCheckpoint> [project]");
-            console.error("  prefer: waygraph auto --blocks LoggedIn OrderComplete");
-            process.exit(1);
-        }
-        const proj = resolve(flags.positionals[3] ?? process.cwd());
-        if (!existsSync(proj)) {
-            console.error(`waygraph: no such directory: ${proj}`);
-            process.exit(1);
-        }
-        await runChainAuto(proj, fromTag, toTag);
-        return;
-    }
-    const spec = flags.blocks ?? first;
-    if (!spec) {
-        console.error('waygraph chain: missing <spec> — prefer: waygraph run --blocks "a then b"\n' +
-            "  or: waygraph auto --blocks <fromCheckpoint> <toCheckpoint>");
-        process.exit(1);
-    }
-    const proj = resolve(flags.blocks ? (flags.positionals[0] ?? process.cwd()) : (flags.positionals[1] ?? process.cwd()));
-    if (!process.env.WAYGRAPH_BASE_URL) {
-        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") {
-        await applyDemoDefaults(proj);
-    }
-    await runChain(proj, spec);
-    return;
-}
-export async function demoCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    applyRunFlags(flags, { allowAutoPlayVideo: true, allowDemoUi: true });
-    const spec = resolveSpec(flags);
-    if (!spec) {
-        console.error("waygraph demo: missing flow/spec — e.g.\n" +
-            "  waygraph demo src/flows/shop.flow.ts\n" +
-            "  waygraph demo --blocks shopFlow\n" +
-            "  Flags: --blocks --data --mem-stub --auto-next --fast --full --mini --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
-        process.exit(1);
-    }
-    const proj = flags.blocks
-        ? resolveProjectDir(flags, 0)
-        : resolve(flags.positionals[1] ?? process.cwd());
-    if (!existsSync(proj)) {
-        console.error(`waygraph: no such directory: ${proj}`);
-        process.exit(1);
-    }
-    if (flags.step === undefined && process.env.WAYGRAPH_STEP === undefined) {
-        process.env.WAYGRAPH_STEP = "1";
-    }
-    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"}` +
-        ` BASE_URL=${process.env.WAYGRAPH_BASE_URL ?? "(unset)"}` +
-        (process.env.WAYGRAPH_VIDEO ? ` VIDEO=${process.env.WAYGRAPH_VIDEO}` : "") +
-        (process.env.WAYGRAPH_TITLE ? ` TITLE=${JSON.stringify(process.env.WAYGRAPH_TITLE)}` : ""));
-    await runChain(proj, spec);
-    return;
-}

package/dist/commands/traverse.js

@@ -1,177 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { resolve } from "node:path";
-import { existsSync, statSync } from "node:fs";
-import { parseBlocksSelect } from "../blocks-select.js";
-import { parseMinEdgeCoverage } from "../traverse/coverage.js";
-import { runTraverse } from "../traverse/run.js";
-export async function traverseCase(args) {
-    if (args.includes("--step") || args.includes("--auto-next") || args.includes("--autoplay")) {
-        console.error("waygraph traverse: --step / --auto-next not supported (not a demo)");
-        process.exit(1);
-    }
-    const rest = args.slice(1);
-    let from;
-    let data;
-    let maxSteps;
-    let maxVisits;
-    let maxEdge;
-    let headed = false;
-    let baseUrl;
-    let blocksFilter;
-    let parallel;
-    let session;
-    let minEdgeCoverageRaw;
-    let coverageOut;
-    let noCoverageReport = false;
-    let projectDir = process.cwd();
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === "--from" || a.startsWith("--from=")) {
-            from = a.startsWith("--from=") ? a.slice(7) : rest[++i];
-            continue;
-        }
-        if (a === "--data" || a.startsWith("--data=")) {
-            data = a.startsWith("--data=") ? a.slice(7) : rest[++i];
-            continue;
-        }
-        if (a === "--blocks" || a.startsWith("--blocks=")) {
-            if (a.startsWith("--blocks=")) {
-                blocksFilter = a.slice("--blocks=".length);
-            }
-            else {
-                const v = rest[++i];
-                if (!v || v.startsWith("-")) {
-                    console.error("waygraph traverse: --blocks needs a glob, /regex/, or path substring");
-                    process.exit(1);
-                }
-                blocksFilter = v;
-            }
-            continue;
-        }
-        if (a === "--parallel" || a.startsWith("--parallel=")) {
-            const v = a.startsWith("--parallel=") ? a.slice("--parallel=".length) : rest[++i];
-            parallel = Number(v);
-            continue;
-        }
-        if (a === "--session" || a.startsWith("--session=")) {
-            const v = a.startsWith("--session=") ? a.slice("--session=".length) : rest[++i];
-            if (v !== "clone" && v !== "inherit") {
-                console.error('waygraph traverse: --session must be "clone" or "inherit"');
-                process.exit(1);
-            }
-            session = v;
-            continue;
-        }
-        if (a === "--min-edge-coverage" || a.startsWith("--min-edge-coverage=")) {
-            minEdgeCoverageRaw = a.startsWith("--min-edge-coverage=")
-                ? a.slice("--min-edge-coverage=".length)
-                : rest[++i];
-            continue;
-        }
-        if (a === "--coverage-out" || a.startsWith("--coverage-out=")) {
-            coverageOut = a.startsWith("--coverage-out=")
-                ? a.slice("--coverage-out=".length)
-                : rest[++i];
-            continue;
-        }
-        if (a === "--no-coverage-report") {
-            noCoverageReport = true;
-            continue;
-        }
-        if (a === "--max-steps" || a.startsWith("--max-steps=")) {
-            const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
-            maxSteps = Number(v);
-            continue;
-        }
-        if (a === "--max-visits" || a.startsWith("--max-visits=")) {
-            const v = a.startsWith("--max-visits=") ? a.slice(13) : rest[++i];
-            maxVisits = Number(v);
-            continue;
-        }
-        if (a === "--max-visits-per-edge" || a.startsWith("--max-visits-per-edge=")) {
-            const v = a.startsWith("--max-visits-per-edge=")
-                ? a.slice("--max-visits-per-edge=".length)
-                : rest[++i];
-            maxEdge = Number(v);
-            continue;
-        }
-        if (a === "--non-headless" || a === "--headed") {
-            headed = true;
-            continue;
-        }
-        if (a === "--base-url" || a.startsWith("--base-url=")) {
-            baseUrl = a.startsWith("--base-url=") ? a.slice(11) : rest[++i];
-            continue;
-        }
-        if (a === "--help" || a === "-h") {
-            console.log(`waygraph traverse [project] [flags]
-
-Graph crawl (RFC Phase B-E). Walks unused legal edges until a leaf,
-budget kill, or first broken edge. --parallel N uses session clone + edge leases.
-
-  --blocks <glob|/regex/|substr>  Phase C: filter *.block.ts discovery
-  --parallel N            Phase D: N clone workers (default 1, max 4)
-  --session clone|inherit Phase D: default clone; inherit refused if parallel>1
-  --min-edge-coverage X   Phase E: suite gate 0.8 | 80% | 80 (exit 2 if below)
-  --coverage-out PATH     Phase E: write JSON (default .waygraph-traverse/coverage.json)
-  --no-coverage-report    Phase E: print Coverage line only (no JSON file)
-  --from <Checkpoint>     start checkpoint (optional)
-  --data '{...}'          Mem seed JSON
-  --max-steps N           default 50 (per worker)
-  --max-visits N          per-node visit cap (default 2)
-  --max-visits-per-edge N default 1
-  --non-headless          show browser
-  --base-url URL
-
-Examples:
-  waygraph traverse --blocks '**/mailpit/**/*.block.ts'
-  waygraph traverse --parallel 2 --session clone --max-steps 20
-  waygraph traverse --min-edge-coverage 80% --coverage-out ./cov.json
-
-PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
-FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
-COVER: [Coverage edges=H/T ratio=R% min=M% PASS|FAIL]
-`);
-            process.exit(0);
-        }
-        if (!a.startsWith("-")) {
-            projectDir = resolve(a);
-        }
-    }
-    if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
-        console.error(`waygraph traverse: no such directory: ${projectDir}`);
-        process.exit(1);
-    }
-    const blocksSelect = blocksFilter
-        ? parseBlocksSelect(blocksFilter)
-        : undefined;
-    let minEdgeCoverage;
-    if (minEdgeCoverageRaw !== undefined) {
-        const parsed = parseMinEdgeCoverage(minEdgeCoverageRaw);
-        if (parsed === null) {
-            console.error(`waygraph traverse: --min-edge-coverage expects 0.8, 80%, or 80 (got ${JSON.stringify(minEdgeCoverageRaw)})`);
-            process.exit(1);
-        }
-        minEdgeCoverage = parsed;
-    }
-    const code = await runTraverse(projectDir, {
-        ...(from ? { from } : {}),
-        ...(data ? { data } : {}),
-        ...(maxSteps !== undefined && Number.isFinite(maxSteps) ? { maxSteps } : {}),
-        ...(maxVisits !== undefined && Number.isFinite(maxVisits)
-            ? { maxVisitsPerNode: maxVisits }
-            : {}),
-        ...(maxEdge !== undefined && Number.isFinite(maxEdge)
-            ? { maxVisitsPerEdge: maxEdge }
-            : {}),
-        headed,
-        ...(baseUrl ? { baseURL: baseUrl } : {}),
-        ...(blocksSelect ? { blocksSelect } : {}),
-        ...(parallel !== undefined && Number.isFinite(parallel) ? { parallel } : {}),
-        ...(session ? { session } : {}),
-        ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
-        ...(coverageOut ? { coverageOut: resolve(coverageOut) } : {}),
-        ...(noCoverageReport ? { noCoverageReport: true } : {}),
-    });
-    process.exit(code);
-}

package/dist/core/block.d.ts

@@ -1,109 +0,0 @@
-import type { ActionPage, Block, Checkpoint, DefinedBlock, Instruction } from "../types.js";
-import { MemPage } from "../mem-page.js";
-import type { MemKey } from "../mem-page.js";
-import type { Trait } from "../trait.js";
-export declare function findBlockIndex(middle: readonly Block<any, any>[], block: Block<any, any> | string | number): number;
-/**
- * Attaches routing to `block` without touching its act/observe/resolve/verify -
- * `routes` must cover every tag of `block`'s output (a missing route is a compile
- * error), and the returned Block runs exactly as `block` always did, just followed
- * by whichever next Block the resolved tag routes to. `null` for a tag means that
- * tag is terminal - the run stops there, same as a Block with no routing at all.
- * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
- * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
- * a route can lead anywhere, including back through itself, so there is no fixed
- * Out type to express; state the expected outcomes to `runGraph` via `terminals`
- * instead.
- */
-export declare function branch<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, routes: {
-    [K in Out["__state"]]: Block<Extract<Out, Checkpoint<K>>, any> | null;
-}): DefinedBlock<In, any>;
-/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
-export declare function copyWaygraphRuntime(from: object, to: object): void;
-/**
- * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
- * methods - `LoginBlock.withVerify([...])`, discoverable by typing
- * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
- * if you already know it exists. A raw object literal is still a perfectly
- * valid Block (every test fixture in this codebase is one) - it just won't have
- * these attached. The methods are thin: they delegate to the identically-named
- * free functions, which remain the one place this logic actually lives.
- */
-export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
-    name: string;
-    description?: Block<In, Out>["description"];
-    instruction: Omit<Instruction<In, Out, any>, "act"> & {
-        act(page: ActionPage, input: In, mem: MemPage): Promise<void>;
-    };
-    next?: Block<In, Out>["next"];
-    requires?: Block<In, Out>["requires"];
-    routes?: Block<In, Out>["routes"];
-    instanceOptions?: Block<In, Out>["instanceOptions"];
-}): DefinedBlock<In, Out>;
-/**
- * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
- * same routing - but with `verify` replaced. For giving one flow stricter (or
- * looser, or just different) confirmation on a Block it didn't author, without
- * that Block needing to have been written as a parameterized factory in
- * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
- * every Block to pre-build its own override mechanism.
- *
- * Wrap the one Block you want to change, in place, wherever it already sits in
- * a `defineFlow([...])` array - every other Block stays untouched:
- * `defineFlow([start, LoginBlock, withVerify(AddToCartBlock, [...]), end])`.
- * There is no separate positional array to keep in sync and no `null`
- * placeholder for "skip this one" - `defineFlow` has no per-slot verify
- * argument at all, only whatever `verify` each Block's own `instruction` (or
- * a `withVerify(...)` wrapping it) carries with it.
- */
-export declare function withVerify<B extends Block<any, any>>(block: B, verify: Trait[] | ((out: any) => Trait[])): B;
-type StubPhaseFn<Out extends Checkpoint<string>> = import("../highlights.js").HighlightStubPhaseOrFn<Out>;
-/**
- * Attach / chain a stubBefore lifecycle on a Block. Prefer
- * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
- * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
- * @deprecated Use the chained method: `Block.stubBefore((ctx) => …)`.
- */
-export declare function withStubBefore<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
-/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubAfter((ctx) => …)`.
- */
-export declare function withStubAfter<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
-/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubOnError((ctx) => …)`.
- */
-export declare function withStubOnError<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
-/**
- * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
- * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
- * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
- * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
- */
-export declare function withDialog<B extends Block<any, any>>(block: B, options?: {
-    accept?: boolean;
-    into?: MemKey<string>;
-    promptText?: string;
-}): B;
-/**
- * Replaces one Trait inside `block`'s verify list, leaving every other check
- * untouched - the v1/v2/legacy-variant case, where one check needs a different
- * selector or URL pattern but the rest of the Block is identical. Addressed by
- * the Trait's own `name` (recommended - inserting or reordering other checks
- * can't silently retarget it) or, if you genuinely know the position and don't
- * need that safety, a numeric index. Either way a bad address fails loud
- * immediately instead of quietly doing nothing. `newCheck` can be a bare
- * `check` function (keeps the existing name) or a full `Trait` (to rename too).
- * Only works on a flat `verify` array - a function-form `verify` (from
- * `verify: (out) => Trait[]`) has no fixed list to address into, so this
- * throws rather than guess; use `withVerify` to replace it wholesale instead.
- */
-export declare function modVerify<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
-/**
- * `modVerify`, but for several named checks in one call - a v2 variant that
- * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
- * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
- * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
- * fine here - unlike `MemPage`, there's no identity-collision reason to need
- * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
- * same fail-loud-on-unknown-name behavior holds for every entry.
- */
-export declare function modVerifyAll<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
-export {};

package/dist/core/blocks/effect.js

@@ -1,23 +0,0 @@
-import { defineBlock } from "../block.js";
-/**
- * {@link defineBlock} constrained for effect-style instance menus: `requires` +
- * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
- * toggles a live instance rather than navigating. Runtime result is an ordinary
- * Block - the helper is TypeScript salt only.
- */
-export function defineEffectBlock(base) {
-    const built = defineBlock(base);
-    Object.defineProperty(built, "__waygraphMemKind", {
-        value: "effect",
-        enumerable: false,
-        configurable: false,
-    });
-    Object.defineProperty(built, "__waygraphSalt", {
-        value: "effect",
-        enumerable: false,
-        configurable: false,
-    });
-    return built;
-}
-/** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
-export const defineMemEffectBlock = defineEffectBlock;

package/dist/core/config.js

@@ -1,17 +0,0 @@
-// Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { chromium, firefox, webkit } from "@playwright/test";
-const LAUNCHERS = { chromium, firefox, webkit };
-/**
- * Resolves which `BrowserType` actually launches for a `mem`-only run (no
- * caller-supplied context) - `config.browsers[browserName]` if given,
- * otherwise the real `@playwright/test` export. Waygraph is deliberately
- * "just an opinionated Playwright" - it doesn't own browser automation
- * itself, so it shouldn't force every consumer onto the vanilla launcher.
- * A stealth-patched or otherwise customized launcher (e.g. `playwright-extra`
- * plus a stealth plugin) is a drop-in replacement for `chromium`/`firefox`/
- * `webkit` - same `.launch()` shape - so accepting one here costs nothing for
- * a consumer who never sets it.
- */
-export function resolveLauncher(browserName, config) {
-    return config?.browsers?.[browserName] ?? LAUNCHERS[browserName];
-}