waygraph 0.14.0 → 0.15.1

package/dist/engine.js

@@ -34,6 +34,46 @@ export function preflight(mem, block) {
             .join(", ")}`);
     }
 }
+/**
+ * @example
+ * const AppShellLayout = defineLayout({
+ *   name: "app-shell",
+ *   appliesTo: ["AppHome", "Chats", "Notifications", "Settings"],
+ *   verify: [Trait.visible(SidebarSel.root)],
+ * });
+ * const engine = new Engine({ layouts: [AppShellLayout] });
+ * // Now every Block resolving to one of those four Checkpoints, in any
+ * // Flow this engine defines, also gets AppShellLayout's own verify run
+ * // automatically - a page that silently drops the sidebar fails loud,
+ * // even though no individual Block's own `verify` mentions it.
+ */
+export function defineLayout(options) {
+    const appliesTo = typeof options.appliesTo === "function"
+        ? options.appliesTo
+        : (tag) => options.appliesTo.includes(tag);
+    return {
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        appliesTo,
+        verify: options.verify,
+    };
+}
+/**
+ * Runs every registered layout whose `appliesTo(tag)` matches the just-
+ * resolved Checkpoint, in registration order, right after the Block's own
+ * `verify` already ran. A layout's own Trait failing throws the same way
+ * any other `runVerify` failure does, naming the layout so it's clearly
+ * distinguishable from the Block's own verify in the error message.
+ */
+async function runLayouts(layouts, tag, out, page, mem, blockName) {
+    if (!layouts)
+        return;
+    for (const layout of layouts) {
+        if (!layout.appliesTo(tag))
+            continue;
+        await runVerify(layout.verify, out, page, mem, `${blockName} (layout: "${layout.name}")`);
+    }
+}
 /**
  * Runs `entry` against a fresh tab and returns the resulting terminal Checkpoint.
  * The engine owns the tab's lifecycle, not any individual Block: the tab is
@@ -72,6 +112,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
                 : undefined;
             const checkpoint = await current.instruction.resolve(observed);
             await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
+            await runLayouts(options?.layouts, checkpoint.__state, checkpoint, page, mem, current.name);
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
@@ -218,7 +259,11 @@ function buildFlow(middle, engineConfig) {
     // withSessionReset()/withTitle() instead (non-destructive decorators,
     // same pattern as withVerify), which also re-apply themselves after any
     // further withBlockVerify/modBlockVerify patch so the flag survives.
-    const chain = middle.reduce((a, b) => connect(a, b));
+    // Layouts have to be threaded into every pairwise connect(), not just the
+    // trailing runGraph call - see connect()'s own doc comment in types.ts:
+    // buildFlow's reduce IS the only place a defineFlow-built Flow's
+    // intermediate (non-final) Checkpoints are ever verified at all.
+    const chain = middle.reduce((a, b) => connect(a, b, engineConfig.layouts));
     // Declared separately (not as the object-literal method below) so the
     // three-overload `Flow.run` signature can be checked against the actual
     // per-call-shape behavior, then attached with a cast - object-literal
@@ -248,7 +293,9 @@ function buildFlow(middle, engineConfig) {
             try {
                 const context = await browser.newContext(config.recordVideo ? { recordVideo: config.recordVideo } : {});
                 try {
-                    return await runGraph(chain, undefined, context, mem);
+                    return await runGraph(chain, undefined, context, mem, 5000, {
+                        ...(config.layouts !== undefined ? { layouts: config.layouts } : {}),
+                    });
                 }
                 finally {
                     // Playwright finalizes recordVideo on context.close(); skip when
@@ -277,9 +324,11 @@ function buildFlow(middle, engineConfig) {
         // call from before this option existed. An explicit `closeOnFinish`
         // always wins either way.
         const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        const resolvedLayouts = options?.layouts ?? engineConfig.layouts;
         const result = await runGraph(chain, undefined, context, mem, 5000, {
             page,
             closeOnFinish: false,
+            ...(resolvedLayouts !== undefined ? { layouts: resolvedLayouts } : {}),
         });
         if (closeOnFinish) {
             await page.close();
@@ -655,6 +704,185 @@ export class Engine {
     defineFlow(blocks) {
         return buildFlow(blocks.slice(1, -1), this.config);
     }
+    /**
+     * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
+     * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's
+     * own agents kept hand-editing/hand-composing Blocks into ad hoc shapes
+     * ("locks" convention tried, still got broken) - `map()` forces every step
+     * through this Engine's own `define*Block` factories (checked by the same
+     * `__waygraphKind`/`__waygraphSalt` runtime markers `graph.ts`/`map-check.ts`
+     * already trust), so a hand-rolled plain-object Block can never silently
+     * pass as a real navigation/assertion/method step. `homeOrigin`, if given,
+     * also gates `.gotoPage()`/`.gotoExternal()` against each Nav/Page Block's
+     * own static `url` (skipped, honestly, for click-based/dynamic nav - not
+     * statically checkable, same limitation `map-check.ts` already documents).
+     * @example
+     * const flow = engine.map({ homeOrigin: "https://app.example.com" })
+     *   .start()
+     *   .gotoPage(NavHomeBlock)
+     *   .assert(AssertHelloBlock)
+     *   .gotoExternal(NavMailpitBlock)
+     *   .end();
+     */
+    map(options) {
+        return MapBuilder.begin(this, options?.homeOrigin);
+    }
+}
+function mapKindOf(block) {
+    return block?.__waygraphKind;
+}
+function mapSaltOf(block) {
+    return block?.__waygraphSalt;
+}
+function mapNavUrlOf(block) {
+    const url = block?.__waygraphNavUrl;
+    return typeof url === "string" ? url : undefined;
+}
+const MAP_KIND_FACTORY_HINT = {
+    nav: "defineNavBlock/defineMemNavBlock",
+    page: "definePageBlock",
+    assert: "defineAssertBlock",
+};
+const MAP_SALT_FACTORY_HINT = {
+    method: "defineMethodBlock",
+    effect: "defineEffectBlock",
+};
+function assertMapKind(block, allowed, method) {
+    const kind = mapKindOf(block);
+    if (kind !== undefined && allowed.includes(kind))
+        return;
+    const wanted = allowed.map((k) => MAP_KIND_FACTORY_HINT[k] ?? k).join(" or ");
+    const found = kind ? `a Block of kind "${kind}"` : "an object with no waygraph kind marker at all";
+    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
+        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
+        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
+}
+function assertMapSalt(block, allowed, method) {
+    const salt = mapSaltOf(block);
+    if (salt !== undefined && allowed.includes(salt))
+        return;
+    const wanted = allowed.map((s) => MAP_SALT_FACTORY_HINT[s] ?? s).join(" or ");
+    const found = salt ? `a Block salted "${salt}"` : "an object with no waygraph salt marker at all";
+    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
+        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
+        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
+}
+function assertMapOrigin(block, homeOrigin, expect, method) {
+    if (!homeOrigin)
+        return; // not configured - can't validate, honest no-op
+    const navUrl = mapNavUrlOf(block);
+    if (navUrl === undefined)
+        return; // click-based/dynamic nav - not statically checkable
+    let targetOrigin;
+    let wantOrigin;
+    try {
+        targetOrigin = new URL(navUrl, homeOrigin).origin;
+        wantOrigin = new URL(homeOrigin).origin;
+    }
+    catch {
+        return; // malformed URL - not this check's job to validate that
+    }
+    const isExternal = targetOrigin !== wantOrigin;
+    if (expect === "internal" && isExternal) {
+        throw new Error(`Waygraph map: .gotoPage("${block.name}") targets ${targetOrigin}, which is NOT this map's ` +
+            `home origin (${wantOrigin}) - use .gotoExternal() for a genuinely cross-origin destination.`);
+    }
+    if (expect === "external" && !isExternal) {
+        throw new Error(`Waygraph map: .gotoExternal("${block.name}") targets ${targetOrigin}, which IS this map's ` +
+            `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`);
+    }
+}
+/**
+ * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
+ * comment for why this exists. Each step method is scoped to exactly the
+ * Block kind its name promises, checked at RUNTIME against the
+ * `__waygraphKind`/`__waygraphSalt` markers `defineNavBlock`/`definePageBlock`/
+ * `defineAssertBlock`/`defineMethodBlock`/`defineEffectBlock` already set
+ * (the same markers `graph.ts` and `map-check.ts` trust) - not just a type
+ * hint, since a hand-rolled object can satisfy the TypeScript `Block<In,Out>`
+ * shape without ever going through a real factory. Each call also
+ * typechecks the accumulated Checkpoint chain exactly like `defineFlow`'s
+ * own tuple overloads do (a step's `In` must equal the previous step's
+ * `Out`) - this is what "no teleporting" means: there is no method on this
+ * builder that can skip from one Checkpoint to an unrelated one without a
+ * real, kind-correct Block in between.
+ */
+export class MapBuilder {
+    engine;
+    steps;
+    homeOrigin;
+    constructor(engine, steps, homeOrigin) {
+        this.engine = engine;
+        this.steps = steps;
+        this.homeOrigin = homeOrigin;
+    }
+    /** @internal - use `engine.map()` or the standalone `map()` export. */
+    static begin(engine, homeOrigin) {
+        return new MapBuilder(engine, [], homeOrigin);
+    }
+    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
+    start() {
+        return this;
+    }
+    /**
+     * Appends an internal navigation/page-arrival step - requires a Block from
+     * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
+     * anything else, including a `homeOrigin`-mismatched static `url`.
+     */
+    gotoPage(block) {
+        assertMapKind(block, ["nav", "page"], "gotoPage");
+        assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /**
+     * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
+     * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
+     * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
+     */
+    gotoExternal(block) {
+        assertMapKind(block, ["nav", "page"], "gotoExternal");
+        assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
+    assert(block) {
+        assertMapKind(block, ["assert"], "assert");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /**
+     * Appends a non-navigating page action (submit, upload, add/remove an
+     * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
+     * `defineEffectBlock`/`defineMemEffectBlock`.
+     */
+    method(block) {
+        assertMapSalt(block, ["method", "effect"], "method");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /**
+     * Finalizes this chain into a real, runnable {@link Flow} - same object
+     * `defineFlow` returns, so `withBlockVerify`/`modBlockVerify` and every
+     * `withTitle`/`withHighlightFixtures`/etc. decorator still apply exactly
+     * as they do today; this builder only changes how the chain is assembled,
+     * never what it produces. Throws if no step was ever added - an empty map
+     * isn't a flow.
+     */
+    end() {
+        if (this.steps.length === 0) {
+            throw new Error("Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
+                ".assert()/.method() before .end()");
+        }
+        const chain = [start, ...this.steps, end];
+        return this.engine.defineFlow(chain);
+    }
+}
+/**
+ * Standalone convenience for `new Engine(config).map(options)` - use this
+ * when a call site doesn't otherwise need its own `Engine` instance (no
+ * shared `headless`/`slowMo`/`layouts` across several flows).
+ * @example const flow = map({ homeOrigin: "https://app.example.com" }).gotoPage(NavHomeBlock).end();
+ */
+export function map(options) {
+    return new Engine(options).map(options);
 }
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible, frameVisible, frameTextEquals, frameContainsText } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
-export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible, frameVisible, frameTextEquals, frameContainsText } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";

package/dist/map-check.d.ts

@@ -0,0 +1,18 @@
+export interface MapViolation {
+    file: string;
+    block: string;
+    reason: string;
+}
+export interface MapNode {
+    block: string;
+    checkpoint: string | undefined;
+    file: string;
+    kind: "nav" | "page" | "other";
+}
+export interface MapCheckResult {
+    mapRoot: string;
+    hasMapDir: boolean;
+    nodes: MapNode[];
+    violations: MapViolation[];
+}
+export declare function checkMap(projectDir: string): Promise<MapCheckResult>;

package/dist/map-check.js

@@ -0,0 +1,140 @@
+/**
+ * `waygraph map` - enforcement for the Waygraph Map folder convention.
+ * Real, direct user correction: this is not just a naming preference, it's
+ * a forced structure. Requires `src/map/` to exist, and for every Nav/Page
+ * Block whose `url` is a plain string, the folder path (relative to
+ * `src/map/`, with `(group)` segments excluded - those are intentionally
+ * invisible in the real URL, same as Next.js route groups) must verbatim
+ * match the URL's own real pathname segments, in order. Catches exactly
+ * the class of bug a live session found: `(auth)/signin/` grouping a page
+ * whose real URL is `/signin`, not `/auth/signin` - a fabricated grouping
+ * that never matched the real site.
+ *
+ * Self-contained (no import from cli.ts), same reasoning as graph.ts's own
+ * header comment: cli.ts runs main() unconditionally at module load.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+function walkBlockFiles(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
+                continue;
+            results.push(...walkBlockFiles(full));
+        }
+        else if (/\.block\.ts$/.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+async function importModule(filePath) {
+    const url = pathToFileURL(filePath);
+    const mtimeMs = statSync(filePath).mtimeMs;
+    url.searchParams.set("t", String(mtimeMs));
+    return (await import(url.href));
+}
+/**
+ * `(group)` segments never appear in the real URL (Next.js route-group
+ * convention this whole system is explicitly modeled on) - excluded from
+ * the comparison, not just cosmetically ignored by discoverGraph.
+ *
+ * A leading-underscore segment (`_methods/`, same as Next.js's own private-
+ * folder convention) is the fixed machinery belonging to ONE endpoint - not
+ * a route segment of its own - excluded from the comparison for the same
+ * reason `(group)` is: real direct request answering "so i have clear
+ * distinction of endpoints vs block folders" - a bare (non-underscore,
+ * non-parenthesized) folder name always means a real child Checkpoint/URL
+ * segment, no exceptions, so `_methods/foo.block.ts` never gets mistaken
+ * for a sibling endpoint the way a bare `methods/` folder structurally
+ * could be.
+ */
+function realSegments(relPath) {
+    return dirname(relPath)
+        .split(sep)
+        .filter((s) => s !== "." && s !== "" && !/^\(.*\)$/.test(s) && !s.startsWith("_"));
+}
+export async function checkMap(projectDir) {
+    const mapRoot = join(projectDir, "src", "map");
+    if (!existsSync(mapRoot)) {
+        return { mapRoot, hasMapDir: false, nodes: [], violations: [] };
+    }
+    const files = walkBlockFiles(mapRoot);
+    const nodes = [];
+    const violations = [];
+    for (const file of files) {
+        const relFile = relative(projectDir, file);
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch (err) {
+            violations.push({
+                file: relFile,
+                block: "(import failed)",
+                reason: err instanceof Error ? err.message.split("\n")[0] : String(err),
+            });
+            continue;
+        }
+        for (const exported of Object.values(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            const waygraphKind = exported.__waygraphKind;
+            const kind = waygraphKind === "nav" ? "nav" : waygraphKind === "page" ? "page" : "other";
+            const navUrl = exported.__waygraphNavUrl;
+            let checkpoint;
+            const instruction = exported.instruction;
+            if (instruction?.resolve && typeof instruction.resolve === "function") {
+                try {
+                    const out = (await instruction.resolve(undefined));
+                    checkpoint = out?.__state;
+                }
+                catch {
+                    /* resolve() needing real input (a Method Block) - not position-defining, skip */
+                }
+            }
+            nodes.push({ block: exported.name, checkpoint, file: relFile, kind });
+            if (typeof navUrl !== "string")
+                continue; // only statically-urled Nav/Page Blocks are checkable
+            let pathname;
+            try {
+                pathname = new URL(navUrl).pathname;
+            }
+            catch {
+                continue; // a relative/templated URL - not verbatim-checkable
+            }
+            const urlSegments = pathname.split("/").filter(Boolean);
+            const folderSegments = realSegments(relative(mapRoot, file));
+            const matches = urlSegments.length === folderSegments.length && urlSegments.every((s, i) => s === folderSegments[i]);
+            if (!matches) {
+                violations.push({
+                    file: relFile,
+                    block: exported.name,
+                    reason: `folder path "${folderSegments.join("/")}" doesn't verbatim-match the real URL path ` +
+                        `"${urlSegments.join("/")}" (${navUrl}) - (group) segments are excluded from this comparison, ` +
+                        "everything else must match exactly, same as Next.js file-based routing",
+                });
+            }
+        }
+    }
+    return { mapRoot, hasMapDir: true, nodes, violations };
+}

package/dist/types.d.ts

@@ -277,10 +277,30 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
 };
+/**
+ * Structural (not imported) twin of `engine.ts`'s `Layout` - `types.ts` sits
+ * below `engine.ts` in the module graph, so it can't import `Layout` without
+ * a cycle. Same shape, matched by TypeScript's structural typing: any real
+ * `Layout` satisfies this with no cast needed at the `connect()` call site.
+ */
+export interface ConnectLayout {
+    name: string;
+    appliesTo: (tag: string) => boolean;
+    verify: Trait[] | ((out: any) => Trait[]);
+}
 /**
  * Composes two Blocks into one, typechecked so this only compiles when A's output
  * tag equals B's input tag. The composed Block's act runs A's full instruction
  * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
  * its own observe/resolve are simply B's, since B is what decides the final Out.
+ *
+ * `layouts`, if given, also runs against the intermediate Checkpoint (A's
+ * resolved output, right before B's act) - the same enforcement `runGraph`'s
+ * own loop already applies to a chain's FINAL Checkpoint, but a
+ * `defineFlow`-built Flow never reaches that loop per-hop: `buildFlow`
+ * reduces the whole Block array into one `connect()`-composed super-Block, so
+ * every intermediate hop's verify (and now layout) has to run HERE, inside
+ * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
+ * one composed Block run start to finish.
  */
-export declare function connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>): Block<A, C>;
+export declare function connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>, layouts?: readonly ConnectLayout[]): Block<A, C>;

package/dist/types.js

@@ -11,8 +11,17 @@ export function checkpoint(tag) {
  * tag equals B's input tag. The composed Block's act runs A's full instruction
  * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
  * its own observe/resolve are simply B's, since B is what decides the final Out.
+ *
+ * `layouts`, if given, also runs against the intermediate Checkpoint (A's
+ * resolved output, right before B's act) - the same enforcement `runGraph`'s
+ * own loop already applies to a chain's FINAL Checkpoint, but a
+ * `defineFlow`-built Flow never reaches that loop per-hop: `buildFlow`
+ * reduces the whole Block array into one `connect()`-composed super-Block, so
+ * every intermediate hop's verify (and now layout) has to run HERE, inside
+ * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
+ * one composed Block run start to finish.
  */
-export function connect(a, b) {
+export function connect(a, b, layouts) {
     const bObserve = b.instruction.observe;
     const bVerify = b.instruction.verify;
     const requires = [...(a.requires ?? []), ...(b.requires ?? [])];
@@ -28,6 +37,13 @@ export function connect(a, b) {
                     : undefined;
                 const mid = await a.instruction.resolve(aObserved);
                 await runVerify(a.instruction.verify, mid, page, mem, a.name);
+                if (layouts) {
+                    for (const layout of layouts) {
+                        if (!layout.appliesTo(mid.__state))
+                            continue;
+                        await runVerify(layout.verify, mid, page, mem, `${a.name} (layout: "${layout.name}")`);
+                    }
+                }
                 await runPrecondition(b.instruction.precondition, mid, page, mem, b.name);
                 await b.instruction.act(page, mid, mem);
             },

package/examples/routed-demo/src/flows/routed-demo-map.flow.ts

@@ -0,0 +1,39 @@
+import { Engine } from "waygraph";
+import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
+import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
+import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
+// Page hubs registered for auto/docs grouping (arrival-only after nav).
+import "../map/(app_base)/dashboard/_page.block.js";
+import "../map/(external)/docs/_page.block.js";
+
+const engine = new Engine();
+
+const homeOrigin = process.env.WAYGRAPH_BASE_URL || "http://127.0.0.1:4277";
+
+/**
+ * Same real Blocks, same real Checkpoints, same real fixture server as
+ * routed-demo.flow.ts - built with `engine.map()` instead of
+ * `engine.defineFlow([start, ..., end])` to prove the fluent builder
+ * against a real browser/DOM, not just the in-memory fakes
+ * tests/nav/map-builder.spec.ts already covers in the main package.
+ *
+ * Both nav steps use `.gotoPage()`, not `.gotoExternal()` - even though
+ * NavDocsBlock's file lives under the `(external)/` group. That group name
+ * is organizational intent (docs.sel.ts's own `WAYGRAPH_DOCS_URL` env
+ * override exists for genuinely pointing it at a different origin), but
+ * this fixture server happens to serve docs.html from the exact same
+ * origin as dashboard.html - the same real inconsistency this session
+ * found and fixed in templates/scaffold's own (external)/docs -> (app_base)
+ * rename, left as-is here since routed-demo is the one place a reader
+ * benefits from seeing it: passing a real `homeOrigin` below means
+ * `.gotoExternal(NavDocsBlock)` would actually THROW (same-origin, not
+ * cross-origin) - `.gotoPage()` is the one that's honest about what this
+ * fixture really does, regardless of the folder it's grouped under.
+ */
+export const routedDemoMapFlow = engine
+  .map({ homeOrigin })
+  .start()
+  .gotoPage(NavDashboardBlock)
+  .method(ClickWidgetBlock)
+  .gotoPage(NavDocsBlock)
+  .end();

package/examples/routed-demo/src/flows/routed-demo.flow.ts

@@ -1,10 +1,10 @@
 import { Engine, start, end } from "waygraph";
-import { NavDashboardBlock } from "../routes/(base_app)/dashboard/nav.block.js";
-import { ClickWidgetBlock } from "../routes/(base_app)/dashboard/methods/click-widget.block.js";
-import { NavDocsBlock } from "../routes/(external)/docs/nav.block.js";
+import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
+import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
+import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
 // Page hubs registered for auto/docs grouping (arrival-only after nav).
-import "../routes/(base_app)/dashboard/page.block.js";
-import "../routes/(external)/docs/page.block.js";
+import "../map/(app_base)/dashboard/_page.block.js";
+import "../map/(external)/docs/_page.block.js";
 
 const engine = new Engine();
 

package/examples/routed-demo/src/{routes/(base_app)/dashboard/methods → map/(app_base)/dashboard/_methods}/click-widget.block.ts

@@ -1,10 +1,10 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { Dashboard } from "../../../../states/routed-demo.states.js";
-import { DashboardSel } from "../dashboard.sel.js";
+import { DashboardSel } from "../_sel.js";
 
 /**
  * Kind: Method
- * Route: (base_app)/dashboard/methods/
+ * Route: (app_base)/dashboard/_methods/
  *
  * Fixed folder name under the Waygraph Map convention - every page-slug
  * folder's own actions live under methods/, same as today's freeform

package/examples/routed-demo/src/{routes/(base_app)/dashboard/nav.block.ts → map/(app_base)/dashboard/_nav.block.ts}

@@ -1,10 +1,10 @@
 import { defineNavBlock, Trait } from "waygraph";
 import type { Dashboard } from "../../../states/routed-demo.states.js";
-import { DashboardSel, DASHBOARD_URL } from "./dashboard.sel.js";
+import { DashboardSel, DASHBOARD_URL } from "./_sel.js";
 
 /**
  * Kind: Nav
- * Route: (base_app)/dashboard/
+ * Route: (app_base)/dashboard/
  *
  * Fixed file name under the Waygraph Map convention - every page-slug
  * folder's own navigation Block is always nav.block.ts.

package/examples/routed-demo/src/{routes/(base_app)/dashboard/page.block.ts → map/(app_base)/dashboard/_page.block.ts}

@@ -1,11 +1,11 @@
 import { definePageBlock, Trait } from "waygraph";
 import type { Dashboard } from "../../../states/routed-demo.states.js";
-import { DashboardSel } from "./dashboard.sel.js";
-import { ClickWidgetBlock } from "./methods/click-widget.block.js";
+import { DashboardSel } from "./_sel.js";
+import { ClickWidgetBlock } from "./_methods/click-widget.block.js";
 
 /**
  * Kind: Page
- * Route: (base_app)/dashboard/
+ * Route: (app_base)/dashboard/
  *
  * Fixed file name under the Waygraph Map convention - every page-slug
  * folder's own arrival hub is always page.block.ts. Arrival-only
@@ -13,7 +13,7 @@ import { ClickWidgetBlock } from "./methods/click-widget.block.js";
  */
 export const DashboardPageBlock = definePageBlock<Dashboard>({
   name: "page-dashboard",
-  description: "Dashboard hub - the routed-demo example's (base_app) group.",
+  description: "Dashboard hub - the routed-demo example's (app_base) group.",
   checkpoint: "Dashboard",
   verify: [Trait.visible(DashboardSel.heading)],
   methods: {