waygraph 0.15.10 → 0.15.14

package/dist/graph.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, dirname, relative, resolve } from "node:path";
 import { matchBlocksSelect, } from "./blocks-select.js";
+import { exploreRoots, injectTaggedFile } from "./block-inject.js";
 /**
  * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
  * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
@@ -343,110 +344,117 @@ function extractDefineBlockGenerics(src) {
  * specifically because it also EXECUTES Blocks, not just imports them.
  */
 export async function discoverGraph(projectDir, opts) {
-    let files = discoverBlocks(projectDir);
     const select = opts?.blocksSelect;
-    // Glob/bare: drop files early. Regex needs block names — filter per export below.
-    if (select && select.kind !== "regex") {
-        files = files.filter((file) => matchBlocksSelect(select, {
-            relFile: relative(projectDir, file).replace(/\\/g, "/"),
-        }));
-    }
     const nodeTags = new Set();
     const edges = [];
     const skipped = [];
-    for (const file of files) {
-        const relFile = relative(projectDir, file);
-        let mod;
-        try {
-            mod = await importModule(file);
+    const edgeSeen = new Set();
+    for (const root of exploreRoots(projectDir, opts?.inject)) {
+        let files = discoverBlocks(root);
+        // Glob/bare: drop files early. Regex needs block names — filter per export below.
+        if (select && select.kind !== "regex") {
+            files = files.filter((file) => matchBlocksSelect(select, {
+                relFile: relative(root, file).replace(/\\/g, "/"),
+            }));
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            // Dual @playwright/test installs fail here - surface instead of empty graph.
-            if (/second time|playwright/i.test(msg)) {
-                console.error(`waygraph graph: skip ${relFile}: ${msg.split("\n")[0]}`);
+        for (const file of files) {
+            const relFile = injectTaggedFile(projectDir, root, relative(root, file).replace(/\\/g, "/"));
+            let mod;
+            try {
+                mod = await importModule(file);
             }
-            continue;
-        }
-        const src = readFileSync(file, "utf-8");
-        // Assumes source order matches export-object iteration order - true for
-        // this codebase's own convention of one Block per file; a file with
-        // several regular Blocks in an unusual order is a known edge case, not
-        // handled specially here.
-        const calls = extractDefineBlockGenerics(src);
-        let callIndex = 0;
-        for (const exported of Object.values(mod)) {
-            if (!isBlockLike(exported))
-                continue;
-            const blockName = exported.name;
-            if (select &&
-                !matchBlocksSelect(select, {
-                    relFile: relFile.replace(/\\/g, "/"),
-                    blockName,
-                })) {
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // Dual @playwright/test installs fail here - surface instead of empty graph.
+                if (/second time|playwright/i.test(msg)) {
+                    console.error(`waygraph graph: skip ${relFile}: ${msg.split("\n")[0]}`);
+                }
                 continue;
             }
-            if (isAssertBlockMarked(exported)) {
-                try {
-                    // Same input-independent resolve() shape Nav/Page Blocks already
-                    // get this shortcut for - defineAssertBlock's own resolve() is
-                    // always `() => checkpoint(options.checkpoint)`, so no <In, Out>
-                    // generic needs to appear in source text for this to be found.
-                    const resolveFn = exported.instruction.resolve;
-                    const resolved = await resolveFn(undefined);
-                    const to = resolved.__state;
-                    nodeTags.add(to);
-                    // Self-loop by construction (defineAssertBlock is self-loop-only).
-                    edges.push({ block: blockName, file: relFile, from: to, to, kind: "action" });
+            const src = readFileSync(file, "utf-8");
+            // Assumes source order matches export-object iteration order - true for
+            // this codebase's own convention of one Block per file; a file with
+            // several regular Blocks in an unusual order is a known edge case, not
+            // handled specially here.
+            const calls = extractDefineBlockGenerics(src);
+            let callIndex = 0;
+            for (const exported of Object.values(mod)) {
+                if (!isBlockLike(exported))
+                    continue;
+                const blockName = exported.name;
+                if (select &&
+                    !matchBlocksSelect(select, {
+                        relFile: relFile.replace(/\\/g, "/"),
+                        blockName,
+                    })) {
+                    continue;
                 }
-                catch {
-                    skipped.push({ block: blockName, file: relFile, reason: "assertBlock resolve() threw" });
+                if (isAssertBlockMarked(exported)) {
+                    try {
+                        // Same input-independent resolve() shape Nav/Page Blocks already
+                        // get this shortcut for - defineAssertBlock's own resolve() is
+                        // always `() => checkpoint(options.checkpoint)`, so no <In, Out>
+                        // generic needs to appear in source text for this to be found.
+                        const resolveFn = exported.instruction.resolve;
+                        const resolved = await resolveFn(undefined);
+                        const to = resolved.__state;
+                        nodeTags.add(to);
+                        // Self-loop by construction (defineAssertBlock is self-loop-only).
+                        edges.push({ block: blockName, file: relFile, from: to, to, kind: "action" });
+                    }
+                    catch {
+                        skipped.push({ block: blockName, file: relFile, reason: "assertBlock resolve() threw" });
+                    }
+                    continue;
                 }
-                continue;
-            }
-            if (isNavBlockMarked(exported)) {
-                try {
-                    // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).
-                    const resolveFn = exported.instruction.resolve;
-                    const resolved = await resolveFn(undefined);
-                    const to = resolved.__state;
-                    nodeTags.add(to);
-                    // Arrival-only Page hubs register the Checkpoint node but do not emit
-                    // a Start-here edge (no deep link). Methods own the action edges.
-                    const isPage = exported.__waygraphKind === "page";
-                    const deepLink = !isPage ||
-                        exported.__waygraphPageDeepLink === true;
-                    if (deepLink) {
-                        edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                if (isNavBlockMarked(exported)) {
+                    try {
+                        // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).
+                        const resolveFn = exported.instruction.resolve;
+                        const resolved = await resolveFn(undefined);
+                        const to = resolved.__state;
+                        nodeTags.add(to);
+                        // Arrival-only Page hubs register the Checkpoint node but do not emit
+                        // a Start-here edge (no deep link). Methods own the action edges.
+                        const isPage = exported.__waygraphKind === "page";
+                        const deepLink = !isPage ||
+                            exported.__waygraphPageDeepLink === true;
+                        if (deepLink) {
+                            edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                        }
+                    }
+                    catch {
+                        skipped.push({ block: blockName, file: relFile, reason: "NavBlock/PageBlock resolve() threw" });
                     }
+                    continue;
                 }
-                catch {
-                    skipped.push({ block: blockName, file: relFile, reason: "NavBlock/PageBlock resolve() threw" });
+                const call = calls[callIndex++];
+                if (!call) {
+                    skipped.push({
+                        block: blockName,
+                        file: relFile,
+                        reason: "no defineBlock/defineMethodBlock/defineEffectBlock<In, Out> generic call found",
+                    });
+                    continue;
                 }
-                continue;
-            }
-            const call = calls[callIndex++];
-            if (!call) {
-                skipped.push({
-                    block: blockName,
-                    file: relFile,
-                    reason: "no defineBlock/defineMethodBlock/defineEffectBlock<In, Out> generic call found",
-                });
-                continue;
-            }
-            const fromTags = resolveGenericArg(file, call.in);
-            const toTags = resolveGenericArg(file, call.out);
-            if (fromTags.length === 0 || toTags.length === 0) {
-                const badName = fromTags.length === 0 ? call.in : call.out;
-                skipped.push({ block: blockName, file: relFile, reason: `couldn't resolve "${badName}" to a Checkpoint tag` });
-                continue;
-            }
-            for (const from of fromTags) {
-                for (const to of toTags) {
-                    if (from !== "*")
-                        nodeTags.add(from);
-                    nodeTags.add(to);
-                    edges.push({ block: blockName, file: relFile, from, to, kind: "action" });
+                const fromTags = resolveGenericArg(file, call.in);
+                const toTags = resolveGenericArg(file, call.out);
+                if (fromTags.length === 0 || toTags.length === 0) {
+                    const badName = fromTags.length === 0 ? call.in : call.out;
+                    skipped.push({ block: blockName, file: relFile, reason: `couldn't resolve "${badName}" to a Checkpoint tag` });
+                    continue;
+                }
+                for (const from of fromTags) {
+                    for (const to of toTags) {
+                        if (from !== "*")
+                            nodeTags.add(from);
+                        nodeTags.add(to);
+                        const key = `${blockName}\0${from}\0${to}`;
+                        if (edgeSeen.has(key))
+                            continue;
+                        edgeSeen.add(key);
+                        edges.push({ block: blockName, file: relFile, from, to, kind: "action" });
+                    }
                 }
             }
         }

package/dist/pilot-overlay.d.ts

@@ -16,9 +16,15 @@
  * dispatch as a side effect of loading a library module - unsafe. This
  * ships its own small, purpose-built badge + panel instead.
  */
-import type { Page } from "@playwright/test";
+import type { BrowserContext, Page } from "@playwright/test";
 import type { SessionSnapshot } from "./auto-session.js";
 import { type HighlightTone, type DevicePreset, type DeviceState, type TodoDockUiOpts } from "./highlights.js";
+/**
+ * Re-install the overlay shell on every navigation (about:blank, goto, etc.)
+ * so the badge/panel persist outside the app's own DOM — not lost when the
+ * page is blank or replaced.
+ */
+export declare function installPersistentPilotOverlay(context: BrowserContext): Promise<void>;
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right
  * badge - real, direct user request: something that visibly flags "a

package/dist/pilot-overlay.js

@@ -129,53 +129,67 @@ const OVERLAY_CSS = `
 #wg-pilot-fx-device[data-preset=tablet]{border-color:#22C55E;}
 #wg-pilot-fx-device[data-preset=desktop]{border-color:#9CA3AF;}
 ` + WAYGRAPH_RING_CSS;
-/** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
-async function ensureInstalled(page) {
-    await page.addStyleTag({ content: OVERLAY_CSS }).catch(() => { });
-    await page.evaluate(() => {
-        if (document.getElementById("wg-pilot-overlay"))
-            return;
-        const root = document.createElement("div");
-        root.id = "wg-pilot-overlay";
-        // Real, direct user request: a way to see the WHOLE project's graph
-        // (every Checkpoint/Block, not just what's reachable from the current
-        // page) directly in the overlay, "like a node tree" - toggled inside
-        // the same panel rather than a second popup, so there's one place to
-        // look, not two.
-        root.innerHTML =
-            '<div id="wg-pilot-badge"></div>' +
-                '<div id="wg-pilot-panel">' +
-                '<div id="wg-pilot-panel-toggle"><button id="wg-pilot-view-current" class="wg-pilot-tab-active">Here</button>' +
-                '<button id="wg-pilot-view-graph">All nodes</button></div>' +
-                '<div id="wg-pilot-panel-current"></div>' +
-                '<div id="wg-pilot-panel-graph" style="display:none"></div>' +
-                "</div>";
-        document.documentElement.appendChild(root);
-        document.getElementById("wg-pilot-badge").addEventListener("click", () => {
-            document.getElementById("wg-pilot-panel").classList.toggle("wg-pilot-open");
-        });
-        document.getElementById("wg-pilot-view-current").addEventListener("click", () => {
-            document.getElementById("wg-pilot-view-current").classList.add("wg-pilot-tab-active");
-            document.getElementById("wg-pilot-view-graph").classList.remove("wg-pilot-tab-active");
-            document.getElementById("wg-pilot-panel-current").style.display = "";
-            document.getElementById("wg-pilot-panel-graph").style.display = "none";
-        });
-        document.getElementById("wg-pilot-view-graph").addEventListener("click", () => {
-            document.getElementById("wg-pilot-view-graph").classList.add("wg-pilot-tab-active");
-            document.getElementById("wg-pilot-view-current").classList.remove("wg-pilot-tab-active");
-            document.getElementById("wg-pilot-panel-graph").style.display = "";
-            document.getElementById("wg-pilot-panel-current").style.display = "none";
-        });
+/** Browser-side shell install — runs on every document via context.addInitScript. */
+function installPilotOverlayShell(css) {
+    if (document.getElementById("wg-pilot-overlay"))
+        return;
+    const style = document.createElement("style");
+    style.id = "wg-pilot-overlay-css";
+    style.textContent = css;
+    document.documentElement.appendChild(style);
+    const root = document.createElement("div");
+    root.id = "wg-pilot-overlay";
+    root.innerHTML =
+        '<div id="wg-pilot-badge">Waygraph Pilot</div>' +
+            '<div id="wg-pilot-panel">' +
+            '<div id="wg-pilot-panel-toggle"><button id="wg-pilot-view-current" class="wg-pilot-tab-active">Here</button>' +
+            '<button id="wg-pilot-view-graph">All nodes</button></div>' +
+            '<div id="wg-pilot-panel-current"></div>' +
+            '<div id="wg-pilot-panel-graph" style="display:none"></div>' +
+            "</div>";
+    document.documentElement.appendChild(root);
+    document.getElementById("wg-pilot-badge").addEventListener("click", () => {
+        document.getElementById("wg-pilot-panel").classList.toggle("wg-pilot-open");
+    });
+    document.getElementById("wg-pilot-view-current").addEventListener("click", () => {
+        document.getElementById("wg-pilot-view-current").classList.add("wg-pilot-tab-active");
+        document.getElementById("wg-pilot-view-graph").classList.remove("wg-pilot-tab-active");
+        document.getElementById("wg-pilot-panel-current").style.display = "";
+        document.getElementById("wg-pilot-panel-graph").style.display = "none";
+    });
+    document.getElementById("wg-pilot-view-graph").addEventListener("click", () => {
+        document.getElementById("wg-pilot-view-graph").classList.add("wg-pilot-tab-active");
+        document.getElementById("wg-pilot-view-current").classList.remove("wg-pilot-tab-active");
+        document.getElementById("wg-pilot-panel-graph").style.display = "";
+        document.getElementById("wg-pilot-panel-current").style.display = "none";
+    });
+    if (!document.getElementById("wg-pilot-activity")) {
         const toast = document.createElement("div");
         toast.id = "wg-pilot-activity";
         document.documentElement.appendChild(toast);
+    }
+    if (!document.getElementById("wg-ring")) {
         const ring = document.createElement("div");
         ring.id = "wg-ring";
+        document.documentElement.appendChild(ring);
+    }
+    if (!document.getElementById("wg-ring-label")) {
         const ringLabel = document.createElement("div");
         ringLabel.id = "wg-ring-label";
-        document.documentElement.appendChild(ring);
         document.documentElement.appendChild(ringLabel);
-    }).catch(() => { });
+    }
+}
+/**
+ * Re-install the overlay shell on every navigation (about:blank, goto, etc.)
+ * so the badge/panel persist outside the app's own DOM — not lost when the
+ * page is blank or replaced.
+ */
+export async function installPersistentPilotOverlay(context) {
+    await context.addInitScript(installPilotOverlayShell, OVERLAY_CSS);
+}
+/** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
+async function ensureInstalled(page) {
+    await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(() => { });
 }
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right
@@ -630,10 +644,14 @@ export async function updatePilotOverlay(page, info) {
         if (!badge || !current || !graphPanel)
             return;
         const idPart = sessionId ? `session ${sessionId}` : "no session id";
-        badge.textContent = `Waygraph Pilot - ${idPart} - ${snapshot.here ?? "(unknown)"}`;
+        const onBlank = location.href === "about:blank" || location.protocol === "about:";
+        const hereLabel = snapshot.here ?? (onBlank ? "(blank page)" : "(unknown)");
+        badge.textContent = `Waygraph Pilot - ${idPart} - ${hereLabel}`;
         const totalEdges = snapshot.sections.reduce((n, s) => n + s.edges.length, 0);
         if (totalEdges === 0) {
-            current.innerHTML = '<div class="wg-pilot-empty">No moves from here right now.</div>';
+            current.innerHTML = onBlank
+                ? '<div class="wg-pilot-empty">Blank page — no Block moves yet. Use auto goto or a nav Block when ready.</div>'
+                : '<div class="wg-pilot-empty">No Block moves from here right now.</div>';
         }
         else {
             current.innerHTML = snapshot.sections

package/dist/pilot.d.ts

@@ -29,7 +29,9 @@
  * new execution primitive.
  */
 import { type WaygraphGraph } from "./graph.js";
-import type { AutoSessionInit, SessionSnapshot } from "./auto-session.js";
+import { listBrowserSessions, type SessionMeta } from "./auto-session-ipc.js";
+import { type BrowserStartInit } from "./browser.js";
+import type { SessionSnapshot } from "./auto-session.js";
 export interface PilotStartResult {
     sessionId: string;
     socketPath: string;
@@ -46,4 +48,7 @@ export interface PilotStartResult {
  * one round trip instead of separately knowing to chain `auto --cli
  * --detach` and `waygraph graph` itself.
  */
-export declare function pilotStart(init: AutoSessionInit): Promise<PilotStartResult>;
+export declare function pilotStart(init: BrowserStartInit): Promise<PilotStartResult>;
+/** Reattach to an existing browser session — does not spawn a new browser. */
+export declare function pilotAttach(projectDir: string, sessionId: string, inject?: string[]): Promise<PilotStartResult>;
+export { listBrowserSessions, type SessionMeta };

package/dist/pilot.js

@@ -29,7 +29,8 @@
  * new execution primitive.
  */
 import { discoverGraph } from "./graph.js";
-import { spawnDetachedSession, requestSession } from "./auto-session-ipc.js";
+import { requestSession, listBrowserSessions, resolveSessionMeta, } from "./auto-session-ipc.js";
+import { browserStart } from "./browser.js";
 /**
  * Starts a detached session and reads back its own graph + starting
  * snapshot in one call, so an agent bootstraps with everything it needs
@@ -38,16 +39,42 @@ import { spawnDetachedSession, requestSession } from "./auto-session-ipc.js";
  * --detach` and `waygraph graph` itself.
  */
 export async function pilotStart(init) {
-    const [meta, graph] = await Promise.all([
-        spawnDetachedSession(init),
-        discoverGraph(init.projectDir),
-    ]);
-    const status = await requestSession(init.projectDir, meta.sessionId, { op: "status" });
+    const { resolveInjectRoots } = await import("./block-inject.js");
+    const exploreInject = init.inject ??
+        (init.injectTokens?.length ? resolveInjectRoots(init.injectTokens, init.projectDir) : undefined);
+    const started = await browserStart({
+        ...init,
+        ...(exploreInject?.length ? { inject: exploreInject } : {}),
+        // Pilot navigates to baseURL on start (unlike `browser`, which defaults to about:blank).
+        skipInitialNavigation: init.skipInitialNavigation ?? false,
+    });
+    const graph = await discoverGraph(init.projectDir, exploreInject?.length ? { inject: exploreInject } : undefined);
+    const status = await requestSession(init.projectDir, started.sessionId, { op: "status" });
+    return {
+        sessionId: started.sessionId,
+        socketPath: started.socketPath,
+        headless: started.headless,
+        graph,
+        snapshot: status.ok ? status.snapshot : null,
+    };
+}
+/** Reattach to an existing browser session — does not spawn a new browser. */
+export async function pilotAttach(projectDir, sessionId, inject) {
+    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (!meta) {
+        throw new Error(`waygraph pilot attach: no such session "${sessionId}" — run \`waygraph pilot sessions\` from the project dir`);
+    }
+    const graph = await discoverGraph(meta.projectDir, inject?.length ? { inject } : undefined);
+    const status = await requestSession(meta.projectDir, sessionId, { op: "status" });
+    if (!status.ok) {
+        throw new Error(`waygraph pilot attach: session "${sessionId}" not reachable (${status.error})`);
+    }
     return {
         sessionId: meta.sessionId,
         socketPath: meta.socketPath,
         headless: meta.headless,
         graph,
-        snapshot: status.ok ? status.snapshot : null,
+        snapshot: status.snapshot,
     };
 }
+export { listBrowserSessions };

package/dist/practices-check.d.ts

@@ -0,0 +1,14 @@
+export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action";
+export interface PracticeWarning {
+    kind: PracticeKind;
+    file: string;
+    /** Short hint for humans/agents. */
+    detail: string;
+}
+export interface PracticeCheckOptions {
+    /** Skip all practice scanning (CLI `--no-practices`). */
+    disabled?: boolean;
+}
+export declare function collectPracticeWarnings(projectDir: string, walkDir: (dir: string, re: RegExp) => string[], opts?: PracticeCheckOptions): PracticeWarning[];
+export declare function practiceKindLabel(kind: PracticeKind): string;
+export declare function formatPracticeWarnings(projectDir: string, warnings: PracticeWarning[]): string[];

package/dist/practices-check.js

@@ -0,0 +1,115 @@
+/**
+ * `waygraph check` / `waygraph typecheck` practice warnings — style/typing issues
+ * that compile but erode the typed graph. Warnings only (never fail exit code)
+ * unless paired with `tsc` errors in `waygraph typecheck`.
+ */
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+/** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
+const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
+/** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
+const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
+const SCAN_GLOB = /\.(block|flow)\.ts$/;
+const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
+const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
+/** Whole-file opt-out: `// waygraph-ignore-practices` */
+const IGNORE_ALL = /waygraph-ignore-practices/;
+/** Per-kind opt-out: `// waygraph-ignore: multi-input, combined-action` */
+const IGNORE_KINDS = /waygraph-ignore:\s*([^\n*]+)/;
+function walkBlockAndFlowFiles(projectDir, walkDir) {
+    return walkDir(projectDir, SCAN_GLOB);
+}
+function ignoredKindsForFile(src) {
+    if (IGNORE_ALL.test(src))
+        return "all";
+    const m = IGNORE_KINDS.exec(src);
+    if (!m)
+        return new Set();
+    const kinds = new Set();
+    for (const token of m[1].split(/[,;\s]+/)) {
+        const t = token.trim();
+        if (t)
+            kinds.add(t);
+    }
+    return kinds;
+}
+function isIgnored(kind, ignore) {
+    return ignore === "all" || ignore.has(kind);
+}
+function countMatches(src, re) {
+    re.lastIndex = 0;
+    return (src.match(re) ?? []).length;
+}
+export function collectPracticeWarnings(projectDir, walkDir, opts) {
+    if (opts?.disabled)
+        return [];
+    const warnings = [];
+    for (const file of walkBlockAndFlowFiles(projectDir, walkDir)) {
+        const rel = relative(projectDir, file).replace(/\\/g, "/");
+        const src = readFileSync(file, "utf-8");
+        const ignore = ignoredKindsForFile(src);
+        if (!isIgnored("wildcard-checkpoint", ignore) && WILDCARD_CHECKPOINT.test(src)) {
+            warnings.push({
+                kind: "wildcard-checkpoint",
+                file: rel,
+                detail: 'uses Checkpoint<string> in a Block helper generic — prefer a typed Checkpoint from src/states/ (e.g. defineMethodBlock<LoginPage, LoginPage>)',
+            });
+        }
+        if (!isIgnored("assert-no-type-arg", ignore) && ASSERT_NO_TYPE_ARG.test(src)) {
+            warnings.push({
+                kind: "assert-no-type-arg",
+                file: rel,
+                detail: "defineAssertBlock({…}) without an explicit type argument — add defineAssertBlock<YourCheckpoint>({…}) so defineFlow typing stays honest",
+            });
+        }
+        const isMethodOrEffect = METHOD_OR_EFFECT_FILE.test(rel) || METHOD_OR_EFFECT_DEFINE.test(src);
+        if (isMethodOrEffect) {
+            const fills = countMatches(src, /\.fill\s*\(/g);
+            const clicks = countMatches(src, /\.click\s*\(/g);
+            if (!isIgnored("multi-input", ignore) && fills >= 2) {
+                warnings.push({
+                    kind: "multi-input",
+                    file: rel,
+                    detail: `Method/Effect act() has ${fills} .fill() calls — one distinct input per Block (split into separate defineMethodBlock files, e.g. fill-username + fill-password + submit-login)`,
+                });
+            }
+            if (!isIgnored("combined-action", ignore) && fills >= 1 && clicks >= 1) {
+                warnings.push({
+                    kind: "combined-action",
+                    file: rel,
+                    detail: "Method/Effect act() mixes .fill() and .click() — fill and submit must be separate Blocks (see examples/saucedemo login split)",
+                });
+            }
+        }
+    }
+    return warnings;
+}
+export function practiceKindLabel(kind) {
+    switch (kind) {
+        case "wildcard-checkpoint":
+            return "wildcard Checkpoint<string>";
+        case "assert-no-type-arg":
+            return "assert block missing type arg";
+        case "multi-input":
+            return "multiple inputs in one Block";
+        case "combined-action":
+            return "fill and click in one Block";
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+export function formatPracticeWarnings(projectDir, warnings) {
+    const lines = [];
+    for (const w of warnings) {
+        lines.push(`waygraph practices: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
+    }
+    if (warnings.length === 0) {
+        lines.push(`waygraph practices: no bad-practice patterns under ${projectDir}`);
+    }
+    else {
+        lines.push(`waygraph practices: ${warnings.length} bad-practice warning${warnings.length === 1 ? "" : "s"}`);
+    }
+    return lines;
+}

package/examples/saucedemo/.waygraph-auto/0b937f26.log

@@ -0,0 +1,4 @@
+(node:1438382) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1438382) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/2d9622a5.log

@@ -0,0 +1,4 @@
+(node:1432340) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1432340) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/305f6e5b.log

@@ -0,0 +1,4 @@
+(node:1419780) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1419780) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/418befbf.log

@@ -0,0 +1,4 @@
+(node:1429820) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1429820) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/483bd763.log

@@ -0,0 +1,4 @@
+(node:1432363) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1432363) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/4adfbe91.json

@@ -0,0 +1,8 @@
+{
+  "sessionId": "4adfbe91",
+  "socketPath": "/tmp/waygraph-auto/4adfbe91.sock",
+  "pid": 1479053,
+  "projectDir": "/home/dan/Desktop/Projects/waygraph/examples/saucedemo",
+  "startedAt": "2026-09-22T02:04:35.751Z",
+  "headless": false
+}

package/examples/saucedemo/.waygraph-auto/4f0e33e7.log

@@ -0,0 +1,4 @@
+(node:1419814) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1419814) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)