waygraph 0.15.23 → 0.15.25

package/dist/commands/traverse.js

@@ -0,0 +1,177 @@
+// 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/commands/try.d.ts

@@ -0,0 +1 @@
+export declare function tryCase(args: string[]): Promise<void>;

package/dist/commands/try.js

@@ -0,0 +1,298 @@
+// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { join } from "node:path";
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { packageRoot, runInherited } from "../cli/util.js";
+import { tmpdir } from "node:os";
+import { runChain } from "../cli/run-chain.js";
+import { applyRunFlags, parseRunFlags } from "../cli/flags.js";
+/**
+ * Runs a throwaway probe script rooted at `projectDir` - the exact same
+ * directory the real demo files get copied into, so it resolves "waygraph"
+ * and "@playwright/test" exactly as they will - and actually launches (then
+ * immediately closes) chromium, a real check rather than a guess at whether
+ * the browser's installed. Never leaves the probe script behind.
+ */
+async function probeTryPrereqs(projectDir) {
+    const tsxEsm = import.meta.resolve("tsx/esm");
+    const probeScript = [
+        "try {",
+        '  await import("waygraph");',
+        "} catch {",
+        '  console.error("WAYGRAPH_TRY_MISSING_WAYGRAPH");',
+        "  process.exit(1);",
+        "}",
+        "let mod;",
+        "try {",
+        '  mod = await import("@playwright/test");',
+        "} catch {",
+        '  console.error("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST");',
+        "  process.exit(1);",
+        "}",
+        "try {",
+        "  const browser = await mod.chromium.launch({ headless: true });",
+        "  await browser.close();",
+        "} catch (err) {",
+        "  if (String(err && err.message).includes(\"Executable doesn't exist\")) {",
+        '    console.error("WAYGRAPH_TRY_MISSING_BROWSER");',
+        "    process.exit(1);",
+        "  }",
+        "  console.error(String((err && err.stack) || err));",
+        "  process.exit(1);",
+        "}",
+    ].join("\n");
+    const probePath = join(projectDir, `.waygraph-try-probe-${process.pid}.mjs`);
+    writeFileSync(probePath, probeScript);
+    try {
+        const result = await new Promise((res, rej) => {
+            const child = spawn(process.execPath, ["--import", tsxEsm, probePath], {
+                cwd: projectDir,
+                stdio: ["ignore", "ignore", "pipe"],
+                env: process.env,
+            });
+            let stderrBuf = "";
+            child.stderr?.on("data", (d) => { stderrBuf += d.toString(); });
+            child.on("error", rej);
+            child.on("exit", (code) => res({ code: code ?? 1, stderr: stderrBuf }));
+        });
+        if (result.code === 0)
+            return { ok: true };
+        const stderr = result.stderr;
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_WAYGRAPH"))
+            return { ok: false, missing: "waygraph" };
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST"))
+            return { ok: false, missing: "playwright-test" };
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_BROWSER"))
+            return { ok: false, missing: "browser" };
+        return { ok: false, missing: "unknown", detail: stderr.trim() || `probe exited with code ${result.code}` };
+    }
+    finally {
+        rmSync(probePath, { force: true });
+    }
+}
+/** Installs deps + chromium inside an already-copied quickstart folder. */
+async function ensureDirPrereqs(dir, label) {
+    let status = await probeTryPrereqs(dir);
+    if (status.ok)
+        return null;
+    if (!existsSync(join(dir, "package.json"))) {
+        return `${label}: no package.json in ${dir}`;
+    }
+    if (status.missing === "waygraph" || status.missing === "playwright-test" || status.missing === "unknown") {
+        // Copied quickstart must not keep a workspace-tainted lockfile (breaks temp-dir npm install).
+        rmSync(join(dir, "package-lock.json"), { force: true });
+        console.log(`${label}: installing dependencies in ${dir} ...`);
+        const installCode = await runInherited("npm", ["install"], dir);
+        if (installCode !== 0) {
+            return `npm install exited with code ${installCode} - see the output above.`;
+        }
+        status = await probeTryPrereqs(dir);
+        if (status.ok)
+            return null;
+        if (status.missing === "unknown") {
+            return formatProbeFailure(status.detail ?? "probe failed");
+        }
+    }
+    console.log(`${label}: downloading Playwright's chromium browser ...`);
+    const localPlaywrightBin = join(dir, "node_modules", ".bin", "playwright");
+    const browserCode = existsSync(localPlaywrightBin)
+        ? await runInherited(localPlaywrightBin, ["install", "chromium"], dir)
+        : await runInherited("npx", ["--yes", "playwright", "install", "chromium"], dir);
+    if (browserCode !== 0) {
+        return `"playwright install chromium" exited with code ${browserCode} - see the output above.`;
+    }
+    status = await probeTryPrereqs(dir);
+    if (status.ok)
+        return null;
+    return formatProbeFailure(status.detail ?? "prerequisites still aren't ready after attempting to install them.");
+}
+/** Playwright browser binary present but OS libs missing (common in Docker/Codespaces). */
+function formatProbeFailure(detail) {
+    const needsDeps = /shared libraries|libnspr4|libnss3|libatk|cannot open shared object file/i.test(detail);
+    const hint = needsDeps
+        ? "\n\nChromium needs OS packages too - try:\n  sudo npx playwright install-deps chromium\n" +
+            "In cloud/CI without a display, record headless:\n  npx waygraph try demo --video ./out --no-step"
+        : "";
+    return `couldn't verify prerequisites:\n${detail}${hint}`;
+}
+const TRY_DEMO_CHAIN = 'loginFlow({"saucedemo.credentials":{"username":"standard_user","password":"secret_sauce"}}) then ' +
+    'shopFlow({"saucedemo.selectedItem":{"id":"sauce-labs-backpack","name":"Sauce Labs Backpack"}}) then ' +
+    'viewerBlockedFlow({"saucedemo.credentials":{"username":"locked_out_user","password":"secret_sauce"}})';
+/**
+ * Point a copied quickstart at this checkout's waygraph build (not npm registry).
+ * Uses `npm pack` into destDir - a file: symlink to the dev tree can double-load
+ * @playwright/test when sibling projects also install Playwright.
+ */
+async function wireQuickstartToPackageRoot(destDir) {
+    const root = packageRoot();
+    const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+    const packCode = await runInherited("npm", ["pack", "--pack-destination", destDir, "--silent"], root);
+    if (packCode !== 0) {
+        throw new Error(`waygraph try demo: npm pack failed with exit code ${packCode}`);
+    }
+    const tgz = join(destDir, `waygraph-${version}.tgz`);
+    const pkgPath = join(destDir, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (!pkg.dependencies)
+        pkg.dependencies = {};
+    pkg.dependencies.waygraph = `file:${tgz}`;
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+/**
+ * Copy templates/quickstart into a fresh OS temp dir and wire it to this
+ * package build. Returns destDir, or null after setting exitCode on failure.
+ */
+async function prepareTryQuickstart(label) {
+    const destDir = mkdtempSync(join(tmpdir(), `${label}-`));
+    cpSync(join(packageRoot(), "templates", "quickstart"), destDir, { recursive: true });
+    rmSync(join(destDir, "node_modules"), { recursive: true, force: true });
+    rmSync(join(destDir, "test-results"), { recursive: true, force: true });
+    rmSync(join(destDir, "package-lock.json"), { force: true });
+    try {
+        await wireQuickstartToPackageRoot(destDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return null;
+    }
+    const problem = await ensureDirPrereqs(destDir, label);
+    if (problem) {
+        console.error(`${label}: couldn't get ready.\n${problem}`);
+        process.exitCode = 1;
+        return null;
+    }
+    return destDir;
+}
+/**
+ * `waygraph try demo` - copy a self-contained saucedemo project into a temp
+ * dir (never the caller's cwd), run a chainFlow step demo (Sign In + Shop +
+ * blocked Viewer), then run the headless Playwright test, and print where
+ * everything lives.
+ */
+async function runTryDemo() {
+    const destDir = await prepareTryQuickstart("waygraph-try-demo");
+    if (!destDir)
+        return;
+    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
+    process.env.WAYGRAPH_STEP ??= "1";
+    process.env.WAYGRAPH_AUTOPLAY ??= "0";
+    // Explicit --no-step --video = unattended headless .webm only (the
+    // documented cloud/CI recipe above) - nobody needs to watch a live
+    // window for Playwright's own recordVideo to capture the right thing.
+    // This must be decided BEFORE the headed default below, or the
+    // unconditional "??=" there always wins and the documented recipe never
+    // actually runs headless.
+    const unattendedVideo = Boolean(process.env.WAYGRAPH_VIDEO) && process.env.WAYGRAPH_STEP === "0";
+    if (unattendedVideo) {
+        process.env.WAYGRAPH_AUTOPLAY ??= "1";
+        process.env.WAYGRAPH_HEADED ??= "0";
+    }
+    else {
+        // Default: headed stepper, manual Next. --video records that session
+        // too (not a headless rush) as long as --step is still on.
+        process.env.WAYGRAPH_HEADED ??= "1";
+    }
+    const videoTo = process.env.WAYGRAPH_VIDEO;
+    console.log(videoTo
+        ? "waygraph try demo: step-through + record (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next; video -> " +
+            (videoTo === "1" ? ".waygraph-videos/" : videoTo)
+        : "waygraph try demo: step-through (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next for each step ...");
+    await runChain(destDir, TRY_DEMO_CHAIN);
+    if (process.exitCode)
+        return;
+    console.log("\nwaygraph try demo: running headless chainFlow test ...");
+    const testCode = await runInherited("npm", ["test"], destDir);
+    if (testCode !== 0) {
+        process.exitCode = testCode;
+        return;
+    }
+    const testFile = join(destDir, "tests", "chain-flow.spec.ts");
+    const loginFlowFile = join(destDir, "src", "flows", "login.flow.ts");
+    const shopFlowFile = join(destDir, "src", "flows", "shop.flow.ts");
+    const viewerBlockedFlowFile = join(destDir, "src", "flows", "viewer-blocked.flow.ts");
+    console.log("\nwaygraph try demo: done.\n\n" +
+        "Temp project (does not touch your cwd - lives under the OS temp dir):\n" +
+        `  ${destDir}\n\n` +
+        "Episodes you just watched (same Flow objects the test imports):\n" +
+        `  ${loginFlowFile}\n` +
+        `  ${shopFlowFile}\n` +
+        `  ${viewerBlockedFlowFile}\n\n` +
+        "Headless chainFlow test (automated - no clicking):\n" +
+        `  ${testFile}\n\n` +
+        "Run again in that temp folder:\n" +
+        `  cd ${destDir}\n` +
+        "  npm run demo    # step-through, manual Next (--step --no-autoplay)\n" +
+        "  npm run auto    # interactive explore (Effect Add/Remove, MemNav Open details)\n" +
+        "  npm test        # playwright chainFlow test\n\n" +
+        "Permanent full example in this package: examples/saucedemo\n" +
+        "Keep a permanent scaffold in your tree: waygraph init my-app\n");
+}
+const TRY_AUTO_DATA = '{"saucedemo.credentials":{"username":"standard_user","password":"secret_sauce"}}';
+/**
+ * `waygraph try auto` / `try auto:cli` - temp Sauce Demo explore.
+ * Default is the **headed** browser panel. Pass `auto:cli` or `--cli` for the
+ * terminal menu (same rows).
+ *
+ * Runs as a child in the temp project so Block imports share that install's
+ * `@playwright/test`. In-process explore from the outer CLI against a packed
+ * `file:*.tgz` copy double-loads Playwright and silently yields 0 graph edges
+ * ("LoginPage / No moves").
+ */
+async function runTryAuto(opts = { cli: false }) {
+    const destDir = await prepareTryQuickstart("waygraph-try-auto");
+    if (!destDir)
+        return;
+    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
+    const cli = opts.cli === true;
+    console.log(cli
+        ? "waygraph try auto: CLI explore on Sauce Demo (temp dir).\n" +
+            "  Creds pre-seeded (saucedemo.credentials).\n" +
+            "  Pick [1] submit-login, then inventory Add/Remove / Open details.\n" +
+            "  Type q to quit. Headed panel: waygraph try auto\n"
+        : "waygraph try auto: headed explore on Sauce Demo (temp dir).\n" +
+            "  Creds pre-seeded. CLI menu: waygraph try auto:cli\n" +
+            "  Pick submit-login, then inventory menus. Quit from the panel.\n");
+    const bin = join(destDir, "node_modules", ".bin", "waygraph");
+    const args = ["auto"];
+    if (cli)
+        args.push("--cli");
+    args.push("--data", TRY_AUTO_DATA);
+    const code = await runInherited(bin, args, destDir);
+    if (code !== 0)
+        process.exitCode = code;
+    console.log("\nwaygraph try auto: explorer closed.\n\n" +
+        `Temp project:\n  ${destDir}\n\n` +
+        "Run again:\n" +
+        `  cd ${destDir} && npm run auto\n` +
+        `  cd ${destDir} && npm run auto:cli\n\n` +
+        "In-package: examples/saucedemo\n" +
+        "Docs: https://deviate-dv8.github.io/waygraph/auto.html\n");
+}
+export async function tryCase(args) {
+    const flags = parseRunFlags(args.slice(1));
+    applyRunFlags(flags);
+    const modeRaw = (flags.positionals[0] ?? "demo").toLowerCase();
+    // auto:cli / --cli = CLI; bare try auto = headed panel
+    const mode = modeRaw === "auto:cli" || modeRaw === "auto-cli"
+        ? "auto:cli"
+        : modeRaw === "auto"
+            ? "auto"
+            : modeRaw;
+    if (mode === "auto" || mode === "auto:cli") {
+        const cli = mode === "auto:cli" || flags.cli === true
+            ? true
+            : flags.headed === true || flags.nonHeadless === true
+                ? false
+                : false; // try auto default = headed
+        await runTryAuto({ cli });
+    }
+    else if (mode === "demo" || mode === "") {
+        await runTryDemo();
+    }
+    else {
+        console.error(`waygraph try: unknown mode "${modeRaw}" - use "demo", "auto", or "auto:cli"`);
+        process.exitCode = 1;
+    }
+    return;
+}

package/dist/engine/blocks/effect.d.ts

@@ -0,0 +1,41 @@
+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";
+/**
+ * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
+ * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu
+ * row per live instance (add/remove/toggle). Not a separate engine concept -
+ * everything is still a Block.
+ */
+export type EffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<DefinedBlock<In, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "effect";
+    requires: readonly MemKey<any>[];
+    instanceOptions: NonNullable<Block<In, Out>["instanceOptions"]>;
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): EffectBlock<In, Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): EffectBlock<In, Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): EffectBlock<In, Out>;
+    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+};
+/** @deprecated Prefer {@link EffectBlock} - same type; Mem* was an early name. */
+export type MemEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = EffectBlock<In, Out>;
+/**
+ * {@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 declare function defineEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0] & {
+    requires: readonly MemKey<any>[];
+    instanceOptions: NonNullable<Block<In, Out>["instanceOptions"]>;
+}): EffectBlock<In, Out>;
+/** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
+export declare const defineMemEffectBlock: typeof defineEffectBlock;

package/dist/engine/blocks/effect.js

@@ -0,0 +1,23 @@
+import { defineBlock } from "../core.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/engine/blocks/method.d.ts

@@ -0,0 +1,90 @@
+import type { Checkpoint, DefinedBlock } from "../../types.js";
+import type { Trait } from "../../trait.js";
+import { defineBlock } from "../core.js";
+import type { MemKey } from "../../mem-page.js";
+/**
+ * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps
+ * (submit, upload, finish, logout) - **methods** on a page. Same runtime Block;
+ * marks `__waygraphSalt = "method"` so auto/docs can tell Method from bare
+ * {@link defineBlock}. Does not force `instanceOptions` - use
+ * {@link defineEffectBlock} when the auto menu should spawn one row per live
+ * DOM instance. Prefer hanging methods off a {@link definePageBlock} hub.
+ */
+export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<DefinedBlock<In, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "method";
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): MethodBlock<In, Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): MethodBlock<In, Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): MethodBlock<In, Out>;
+    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+};
+/** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
+export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
+export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
+/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
+export declare const defineActionBlock: typeof defineMethodBlock;
+export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<string>> {
+    name: string;
+    description?: string;
+    /** Self-loop target - the Checkpoint this assertion runs on and returns to. */
+    checkpoint: Out["__state"];
+    /**
+     * Shorthand for the wait-then-assert shape found repeatedly in hand-written
+     * assertion Blocks: waits for a heading with this accessible name before
+     * `verify` runs. Omit for a pure "assert whatever is already on the page"
+     * check with no wait. Not a general `act()` override - a Block that needs
+     * more than this stays a plain `defineMethodBlock`.
+     */
+    waitForHeading?: string;
+    verify: Trait[] | ((out: Out) => Trait[]);
+    /** Mem keys this assertion's `verify` reads (e.g. a mem-aware Trait) - checked by preflight before the flow runs. */
+    requires?: readonly MemKey<any>[];
+    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    /** Multi-step yap slides (demo only) - same field `Instruction.slides` exposes elsewhere. */
+    slides?: import("../../highlights.js").WaygraphSlidesOrFn<Out>;
+}
+/**
+ * Sugar for a self-loop-only "pure assertion" Block: no hand-written
+ * `act`/`resolve`, just a name, a `checkpoint` tag, and a `verify` array.
+ * `resolve` is generated from the one `checkpoint` field given, closing the
+ * copy/rename footgun where a hand-restated checkpoint string can silently
+ * drift wrong across a copy/pasted file. Mirrors `definePageBlock`'s own
+ * construction pattern (flat options in, `defineBlock` built internally).
+ * See openspec/changes/waygraph-agent-skill-hardening/spec.md.
+ * @example
+ * defineAssertBlock({
+ *   name: "assert-raw-materials-table",
+ *   checkpoint: "RawMaterials",
+ *   waitForHeading: "Raw Materials & Lead Times",
+ *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
+ * });
+ */
+export declare function defineAssertBlock<Out extends Checkpoint<string> = Checkpoint<string>>(options: AssertBlockOptions<Out>): AssertBlock<Out>;
+/**
+ * Self-loop verify Block from {@link defineAssertBlock}. Branded for
+ * {@link MapBuilder.assert} (not accepted by `.method()`).
+ */
+export type AssertBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Out, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "assert";
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): AssertBlock<Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): AssertBlock<Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): AssertBlock<Out>;
+    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+};