waygraph 0.14.0 → 0.15.1

package/README.md

@@ -138,6 +138,84 @@ structurally incapable of touching the browser or shared memory. `verify` runs o
   its own panel row; former FF inners keep blitz pacing so wall-clock stays comparable.
   `--ff-expand` is the older expand-only flag (same flatten).
 
+### Cross-cutting Layouts (`defineLayout`)
+
+Real, direct request this responds to: persistent chrome (a sidebar, say) that's supposed
+to stay on screen across most of an app shouldn't need its own `Trait` copy-pasted into
+every single Checkpoint's `verify` - one missed copy and a regression silently ships. A
+**Layout** is a `verify` that's enforced automatically, by Checkpoint tag, wherever it
+applies - not once per Block:
+
+```ts
+import { defineLayout, Engine } from "waygraph";
+
+const AppShellLayout = defineLayout({
+  name: "AppShell",
+  // string[] of exact Checkpoint tags, or a (tag) => boolean predicate for a
+  // broader match (e.g. "every Checkpoint except the signed-out ones")
+  appliesTo: ["AppHome", "Chats", "Notifications", "Settings"],
+  verify: [Trait.visible(AppShellSel.sidebar)],
+});
+
+const engine = new Engine({ layouts: [AppShellLayout] });
+```
+
+Every `Flow` this `Engine` defines - **and every intermediate Checkpoint inside it**, not
+just the final one - runs `AppShellLayout.verify` automatically whenever it resolves to a
+tag `appliesTo` matches, alongside that Block's own `verify`. `runGraph`/`Flow.run` also
+take `{ layouts }` directly (`RunGraphOptions.layouts`), for driving a Layout outside an
+`Engine`-owned Flow (e.g. `waygraph auto`'s own runtime pathfinding).
+
+Deliberately matched by Checkpoint tag, never by folder path - a Layout works identically
+whether a project uses the [Waygraph Map](#waygraph-map) convention or the older freeform
+folder style, since some real consumers of this package still use the latter.
+
+### `map()` - a kind-checked, no-teleporting flow builder
+
+`Engine.defineFlow([start, ...blocks, end])` already typechecks that each Block's `Out`
+matches the next one's `In`. It does **not** stop an agent (or a careless human) from
+handing it a hand-rolled plain object that merely *looks* like a Block - TypeScript's
+structural typing can't tell a real `defineNavBlock(...)` output from a copy-pasted
+object literal with the right shape. That gap is exactly what broke down in real
+consumer projects: agents editing/hand-composing Blocks into ad hoc shapes, a "locks"
+convention tried and still bypassed. `map()` closes it with an actual runtime check, not
+just a convention:
+
+```ts
+import { Engine } from "waygraph";
+
+const engine = new Engine();
+const flow = engine
+  .map({ homeOrigin: "https://app.example.com" })
+  .start()
+  .gotoPage(NavHomeBlock) // must be defineNavBlock / defineMemNavBlock / definePageBlock
+  .assert(AssertHelloBlock) // must be defineAssertBlock
+  .gotoExternal(NavMailpitBlock) // same kind requirement, plus the INVERSE origin check
+  .method(ClearCartBlock) // must be defineMethodBlock / defineActionBlock / defineEffectBlock
+  .end(); // -> a real Flow<Out> - withBlockVerify/withTitle/withHighlightFixtures/etc. all still apply
+```
+
+Each step method is scoped to exactly the Block kind its name promises, checked against
+the same `__waygraphKind`/`__waygraphSalt` runtime markers `waygraph check`/`graph`/`map`
+already trust - a Block that didn't come from a real `define*Block` factory throws
+immediately, naming the step and the factory it should have used, instead of silently
+entering the chain. Give `homeOrigin` and `.gotoPage()`/`.gotoExternal()` also cross-check
+each Nav/Page Block's own static `url` against it (skipped, honestly, for click-based or
+mem-dependent nav - not statically checkable). The Checkpoint chain itself is still
+typechecked exactly like `defineFlow`'s own tuple overloads - 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, which is what "no teleporting" means here.
+
+`map()` is sugar over `defineFlow`, not a new execution engine - the result is a real
+`Flow`, so every existing Flow-level feature (Layouts, `withBlockVerify`, demo narration,
+`chainFlow`) works on it unchanged. `import { map } from "waygraph"` is also available
+standalone (`map(options)` ~= `new Engine(options).map(options)`) for a call site that
+doesn't otherwise need its own `Engine` instance. **Recommended for new projects** over
+hand-assembled `defineFlow([start, ...])` arrays - the freeform array form still works
+and isn't going away (real consumers on the older folder convention depend on it), but
+`map()` is the one that actually stops a broken/hacked Block from entering a flow
+unnoticed.
+
 ### Traits beyond the page
 
 A hand-written `Trait`'s `check(page, mem)` receives `mem` too, for the same-Checkpoint
@@ -324,7 +402,7 @@ export const AssertItemAddedBlock = defineAssertBlock<ItemInCart>({
 engine.defineFlow([start, NavHomeBlock, AddItemBlock, AssertItemAddedBlock, ClearCartBlock, end])
 ```
 
-Live reference: `templates/scaffold/src/blocks/demo-web/methods/assert-item-added.method.block.ts`,
+Live reference: `templates/scaffold/src/map/(app_base)/home/_methods/assert-item-added.method.block.ts`,
 wired into `shop.flow.ts`.
 
 **`methods/` folder:** on-page work lives next to the route, not free-floating.
@@ -439,7 +517,7 @@ preflight reject the run before it ever gets a chance to produce it - `requires`
 keys a caller truly must supply from outside the chain (like `ExpectedRecipient` above).
 
 Live reference, proven end to end against a real, throwaway Mailpit container:
-`templates/scaffold/src/blocks/demo-external/mailpit/` + `src/flows/mail-verify.flow.ts` +
+`templates/scaffold/src/map/(external)/mailpit/` + `src/flows/mail-verify.flow.ts` +
 `tests/mail-verify.spec.ts`.
 
 ### Reusable across scenarios: mem-driven, not one Block per email
@@ -720,27 +798,46 @@ recurse through any folder structure, matching only the `.block.ts` filename pat
 naming and depth are already 100% cosmetic to every existing command.
 
 ```text
-src/routes/
-  (base_app)/              # purely organizational - never part of any Checkpoint tag
-    dashboard/              # one folder per Checkpoint - "Dashboard"
-      page.block.ts          # arrival hub (definePageBlock) - fixed name, every folder
-      nav.block.ts            # navigation (defineNavBlock) - fixed name, every folder
-      dashboard.sel.ts
-      methods/
-        click-widget.block.ts
-  (external)/
-    docs/                    # a different group, same shape - "Docs"
-      page.block.ts
-      nav.block.ts
-      docs.sel.ts
+src/map/
+  (app_base)/              # the landing/base group - purely organizational, never part of
+    dashboard/              # any Checkpoint tag. One folder per Checkpoint - "Dashboard"
+      _page.block.ts         # arrival hub (definePageBlock) - fixed name, every folder
+      _nav.block.ts           # navigation (defineNavBlock) - fixed name, every folder
+      _sel.ts                  # selectors for this Checkpoint - fixed name, every folder
+      _methods/                 # this Checkpoint's own action Blocks - fixed name, every
+        click-widget.block.ts    # folder. Contents keep their own descriptive names -
+  (external)/                     # only the folder itself is fixed.
+    docs/                    # a genuinely cross-origin group, same shape - "Docs"
+      _page.block.ts
+      _nav.block.ts
+      _sel.ts
 ```
 
-Same Block helpers as today's freeform "manual mode" (`definePageBlock`/`defineNavBlock`/
-`defineMethodBlock`/etc.) - this only changes *where files live and what they're named*,
-never what kind of Block authors them or how they execute. A project adopts it incrementally,
-folder by folder; the two styles compose in the same flow with no special-casing (proven in
-`templates/scaffold`'s own `routes-demo.flow.ts`: `nav-home` from `src/blocks/`, manual mode,
-into `nav-docs` from `src/routes/`, Map convention, one real navigation).
+**Not just a naming preference - a forced convention.** Folder nesting under `map/(group)/`
+must **verbatim-match** the real site's own URL path segments, `(group)` parens excluded
+(purely organizational, same as a Next.js route group): `/app/chats` lives at
+`map/(app_base)/app/chats/`, never `map/(auth)/chats/` for a fabricated grouping that was
+never a real `/auth/*` URL. `waygraph map [project]` (see [CLI reference](#cli-reference))
+enforces this mechanically and exits 1 on a mismatch - don't rely on review alone. Same Block
+helpers as today's freeform "manual mode" (`definePageBlock`/`defineNavBlock`/
+`defineMethodBlock`/etc.) either way - Map only changes *where files live and what they're
+named*, never what kind of Block authors them or how they execute. A project adopts it
+incrementally, folder by folder. Prefer [`map()`](#map---a-kind-checked-no-teleporting-flow-builder)
+over a hand-assembled `defineFlow([start, ...])` array when wiring these Blocks into a Flow -
+it's the one that can't silently accept a Block that didn't come from a real factory.
+
+**Leading underscore = this Checkpoint's own fixed machinery, never a route segment.**
+`_nav.block.ts`/`_page.block.ts`/`_sel.ts`/`_methods/` (same private-folder idea as Next.js's
+own `_folder` convention) mark "this belongs to the endpoint whose folder it's directly in,"
+so a bare (non-underscore, non-`(group)`) folder name always means a real child
+Checkpoint/URL segment - `_methods/` can never be mistaken for a sibling endpoint folder the
+way a bare `methods/` structurally could be, since only ONE of those two readings is
+mechanically distinguishable at a glance. `waygraph map`'s own folder-vs-URL comparison
+excludes underscore segments the same way it excludes `(group)` ones - `_methods/foo.block.ts`
+compares against the URL as if `_methods/` weren't there at all. Individual files inside
+`_methods/` keep their own descriptive names (`join-pool.method.block.ts`, not
+`_join-pool...`) - they're hand-authored per-project content, not fixed convention names; the
+`_methods/` folder boundary alone already marks the whole subtree as non-route.
 
 **"waypack" - loading another project's Blocks needs no separate manifest either.** A second
 project depending on a Map-convention project as a plain `file:` dependency (the same
@@ -763,6 +860,58 @@ Full design history (why "Router" isn't a separate thing to build, two prior wro
 of this before landing here, and everything above stated as requirements) in
 `openspec/changes/waygraph-map/`.
 
+## Migrating from freeform ("router") to Waygraph Map
+
+"Router" isn't a separate mode to turn off - it's this project's own name for today's
+freeform, folder-organized style (`src/blocks/<slug>/`, any nesting, any file names).
+Migrating means moving those files under `src/map/(group)/<page-slug>/` with verbatim
+URL-matching names, nothing more - no engine change, no new Block helpers, no flag to flip.
+Do it incrementally: the two styles coexist in the same project (and even the same Flow) with
+no special-casing, since `discoverGraph`/`loadBlockLibrary` only ever match the `.block.ts`
+filename pattern, never folder depth or naming.
+
+1. **List every real URL your NavBlocks/PageBlocks already navigate to.** For each one with a
+   static string `url`, note its real path. For each one that's `click`-based (no `url` field
+   at all) or a dynamic `(mem) => string` function, note that too - neither is statically
+   checkable by `waygraph map`, so they can go wherever makes sense; only a literal string
+   `url` is verified.
+2. **Pick your group(s).** `(app_base)/` for the landing/base app (organizational only, never
+   part of a Checkpoint tag); `(external)/` for genuinely cross-origin Blocks (mail tools,
+   third-party embeds) - verify with the real URL, not the folder's own current name, since a
+   folder can already be mis-grouped (a real bug this session found: a project's own
+   `(external)/docs/` was actually same-origin the whole time).
+3. **Create `src/map/(group)/<verbatim-url-segments>/` per Checkpoint**, `git mv` each
+   Block/Sel file in, and rename the fixed ones: `nav.block.ts` -> `_nav.block.ts`,
+   `page.block.ts` -> `_page.block.ts`, your selector file -> `_sel.ts` (drops its slug - now a
+   fully fixed name), `methods/` -> `_methods/` (contents keep their own names unchanged).
+   **Two Checkpoints sharing one real URL** (a DOM-state distinction, not a URL one - e.g. a
+   "joined" vs "not joined" variant of the same page) can't both use the bare fixed names in
+   one folder; give each pair a slug prefix instead (`app-home._nav.block.ts` /
+   `in-pool._nav.block.ts`, or similar) rather than nesting either under its own subfolder
+   (that would add a folder segment the real URL doesn't have, and fail step 5).
+4. **A dynamic per-instance URL** (a real chat/order/ticket id, not a fixed route) - if it's
+   currently a plain string constant, wrap it as `url: () => thatConstant` instead. A bare
+   string is always treated as a real, checkable static route; a function is correctly treated
+   as dynamic/non-canonical and skipped, matching how you'd actually navigate a real instance of
+   it in practice anyway.
+5. **Fix every import** the moves break (states/mem-key paths change depth; sibling
+   nav/page/methods imports need their new `_`-prefixed names) - let the compiler do this for
+   you: `tsc --noEmit` if the project has one, otherwise `waygraph check [project]` and
+   `waygraph graph [project]` (both do real dynamic imports of every Block file and report
+   import failures by name) are just as effective a proof.
+6. **Run `waygraph map [project]`.** Exit 0 / "0 violations" is the actual finish line - not a
+   subjective review. A remaining violation names the exact file, its real folder path, and the
+   real URL it doesn't match; fix the folder, not the check.
+7. **Diff `waygraph graph`'s node/edge/skipped/orphan counts against before the move.** A pure
+   migration changes zero Block behavior - if a count changed, something broke in transit
+   (a bad import silently dropped a Block from discovery is the usual cause), not something to
+   wave off as "close enough."
+
+Once the folder structure is settled, prefer building/rebuilding Flows over these Blocks with
+[`map()`](#map---a-kind-checked-no-teleporting-flow-builder) instead of a hand-assembled
+`defineFlow([start, ...])` array - it's the one that can't silently accept a Block that isn't
+really a Nav/Page/Assert/Method from this package's own factories.
+
 ## Getting started (pick one)
 
 | Goal | Command |
@@ -881,6 +1030,7 @@ Flows are files (0.10.5+):
 | Detached session with a real visible browser | `waygraph auto --cli --detach --non-headless` |
 | Read the session's Checkpoint/Block history | `waygraph auto trace <sessionId>` |
 | Whole-project nav-escape + inline-selector + orphan sweep | `waygraph check [project]` |
+| Waygraph Map enforcement (verbatim url-vs-folder, exits 1 on a violation) | `waygraph map [project]` |
 | Graph crawl | `waygraph traverse [project] --parallel N --min-edge-coverage 80%` |
 | Coding-agent defs | `waygraph agent-dive --loop claude` |
 | One-shot temp-dir demo | `waygraph try demo` / `waygraph try auto` / `waygraph try auto:cli` |

package/dist/cli.js

@@ -18,6 +18,7 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
+import { checkMap } from "./map-check.js";
 import { runAutoExplore } from "./auto-explore-run.js";
 import { pilotStart } from "./pilot.js";
 import { spawnDetachedSession, requestSession, runAttachLoop, runAutoServeCommand, } from "./auto-session-ipc.js";
@@ -3808,6 +3809,62 @@ async function hideRing(page) {
     .catch(() => {});
 }
 
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
+  const needs =
+    (await page
+      .evaluate(() => !window.__wgSyncTodos || !document.getElementById("wg-ring"))
+      .catch(() => true)) || false;
+  if (!needs) {
+    // Overlay survived (SPA / no full document wipe) - still refresh dock
+    // if Node has a carry and the DOM lost .wg-todo-dock.
+    const hasDock = await page
+      .evaluate(() => !!document.querySelector(".wg-todo-dock, #wg-todo-dock"))
+      .catch(() => false);
+    if (hasDock || !todoDockRef || !todoDockRef.current) return;
+  }
+  await installOverlay(page);
+  const dock = todoDockRef && todoDockRef.current;
+  if (dock) {
+    await page
+      .evaluate((d) => {
+        if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "set", dock: d });
+      }, dock)
+      .catch(() => {});
+  }
+  if (deviceRef && deviceRef.current) {
+    await applyDeviceToPage(page, deviceRef.current, "set").catch(() => {});
+  }
+  // Re-show first matching stubBefore ring if selector still exists (sidebar
+  // nav targets often survive the route change).
+  const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+  for (const h of stubs) {
+    if (!h || !h.selector) continue;
+    const box = await page
+      .evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        if (r.width < 2 || r.height < 2) return null;
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+      }, h.selector)
+      .catch(() => null);
+    if (box) {
+      await showRing(page, box, formatHighlightCaption(h), h.tone || "planned", {
+        size: h.size,
+        weight: h.weight,
+        selector: h.selector,
+        focus: !!h.focus,
+      }).catch(() => {});
+      break;
+    }
+  }
+}
+
 /**
  * Removes every overlay element (panel, ring, ring-label, cursor,
  * click-pulse, banner) and stops the live resize/scroll ring tracker, once
@@ -4541,6 +4598,7 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
       // of leaving it lit until the next Block's own before-panel clears
       // it - it was sticking around through the whole rest of the step.
       await hideRing(page);
+      await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
       return result;
     };
   }
@@ -4669,6 +4727,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
       }
       await new Promise((res) => setTimeout(res, clickPostPop()));
       await hideRing(page);
+      // Full document navigation drops #wg-todo-dock + rings; restore carry.
+      await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
       return result;
     };
   }
@@ -4920,17 +4980,21 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     if (sync === "set" && dock) {
       if (!parallel) todoDockById.clear();
       todoDockById.set(dockRegistryKey(dock), dock);
+      return;
+    }
+    // keep: refresh / re-seed so syncAllTodoDocks never sees an empty map
+    // while lastTodoDock still carries (nav wipe + mid-act advance).
+    if (sync === "keep" && dock) {
+      todoDockById.set(dockRegistryKey(dock), dock);
     }
   };
   const syncAllTodoDocks = async (opts) => {
     const docks = [...todoDockById.values()];
     const parallel = !!(opts && opts.parallel);
     if (!docks.length) {
-      await page
-        .evaluate(() => {
-          if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "clear" });
-        })
-        .catch(() => {});
+      // Empty registry: do NOT clear the DOM. renderBefore/After may have
+      // just painted from lastTodoDock (keep). Clearing here made todos
+      // vanish until the next ctx.todos() set (PIA #15).
       return;
     }
     await page
@@ -6971,6 +7035,12 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
+  waygraph map   [project]                 Waygraph Map convention enforcement: every static
+                                           Nav/Page url must verbatim-match its src/map/ folder
+                                           path ((group) segments excluded) - exits 1 on a
+                                           violation, unlike check's warnings-only stance. A
+                                           no-op (exit 0, informational) if the project has no
+                                           src/map/ directory at all.
   waygraph traverse [project]              Graph crawl (Phase B-E)
                  --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --parallel N              Phase D: N clone workers (max 4)
@@ -7801,6 +7871,32 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
             // human/agent cleanup; chain auto refuses while any remain.
             break;
         }
+        case "map": {
+            const proj = resolve(args[1] ?? process.cwd());
+            const result = await checkMap(proj);
+            if (!result.hasMapDir) {
+                console.log(`waygraph map: no src/map/ directory under ${proj} - nothing to check ` +
+                    "(this project isn't on the Waygraph Map convention, or hasn't been migrated yet)");
+                break;
+            }
+            console.log(`waygraph map: ${result.nodes.length} node(s) found under ${relative(proj, result.mapRoot)}`);
+            if (result.violations.length === 0) {
+                console.log("waygraph map: 0 violations - every static Nav/Page url verbatim-matches its folder path");
+            }
+            else {
+                for (const v of result.violations) {
+                    console.error(`waygraph map: ${v.file} (${v.block}) - ${v.reason}`);
+                }
+                console.error(`waygraph map: ${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}`);
+                // Unlike `check`'s warnings-only stance, a Map violation is exactly
+                // the class of bug this command exists to catch (a fabricated
+                // folder grouping that never matched the real site, e.g. the real
+                // (auth)/signin/ mistake this command's own header comment cites) -
+                // fail loud, not just warn.
+                process.exitCode = 1;
+            }
+            break;
+        }
         default:
             console.error(`waygraph: unknown command "${command}"`);
             process.exit(1);

package/dist/engine.d.ts

@@ -13,6 +13,52 @@ import { type HighlightStyleDefaults, type DemoPace } from "./highlights.js";
  * since those depend on a runtime decision that hasn't happened yet.
  */
 export declare function preflight(mem: MemPage, block: Block<any, any>): void;
+/**
+ * A cross-cutting, automatically-enforced verify - the real engine
+ * primitive behind "persistent UI" (a sidebar, a header, anything that's
+ * supposed to be present on many/most Checkpoints, not just one page's own
+ * Block). Deliberately NOT tied to any folder convention - `appliesTo`
+ * matches by Checkpoint tag, explicitly, so this works the same whether a
+ * project uses the Waygraph Map folder convention or the older freeform
+ * "manual mode" layout real production consumers (pia-waygraph,
+ * zsign-atomic-waygraph) already use - registering a Layout with an Engine
+ * is the only requirement, folder structure is irrelevant to it.
+ *
+ * Not a Block: no `act`/`resolve`/Checkpoint of its own, never a graph
+ * node - it only ever adds extra `verify` Traits to Checkpoints something
+ * else already resolved to, the same way `runVerify` already runs after
+ * any Block's own `resolve()` (see `runGraph`'s own verify step, just
+ * below) - a Layout is that mechanism made reusable across many
+ * Checkpoints instead of hand-repeated per Block.
+ */
+export interface Layout {
+    name: string;
+    description?: string;
+    appliesTo: (tag: string) => boolean;
+    /** Function form gets the full resolved Checkpoint, same shape `runVerify`/a Block's own `verify` already use - not just the tag. */
+    verify: Trait[] | ((out: Checkpoint<string>) => Trait[]);
+}
+export interface LayoutOptions {
+    name: string;
+    description?: string;
+    /** A fixed tag list, or a predicate for open-ended matching (e.g. a naming pattern). */
+    appliesTo: readonly string[] | ((tag: string) => boolean);
+    verify: Trait[] | ((out: Checkpoint<string>) => Trait[]);
+}
+/**
+ * @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 declare function defineLayout(options: LayoutOptions): Layout;
 /**
  * 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
@@ -52,6 +98,14 @@ export interface RunGraphOptions {
      * `page` and `closeOnFinish` together) - it just does what you ask.
      */
     closeOnFinish?: boolean;
+    /**
+     * Layouts (see {@link defineLayout}) whose `verify` runs automatically
+     * after any Block in this run resolves to a Checkpoint they apply to -
+     * `Flow.run` threads this in from `EngineConfig.layouts` by default; pass
+     * it directly here to call `runGraph` standalone (outside a `Flow`) with
+     * layouts still enforced.
+     */
+    layouts?: readonly Layout[];
 }
 /**
  * Drives a genuinely separate second tab through its own Block/Flow, in the
@@ -435,6 +489,14 @@ export interface EngineConfig {
             height: number;
         };
     };
+    /**
+     * Cross-cutting, automatically-enforced verify (see {@link defineLayout})
+     * - applies to every Flow this Engine defines. Works the same regardless
+     * of folder convention (Waygraph Map or freeform "manual mode") since
+     * matching is by Checkpoint tag, never by file path.
+     * @example new Engine({ layouts: [AppShellLayout] })
+     */
+    layouts?: readonly Layout[];
 }
 type S = Checkpoint<"__start__">;
 /**
@@ -595,7 +657,106 @@ export declare class Engine {
         Block<N, O>,
         EndMarker
     ]): Flow<O>;
+    /**
+     * 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?: MapBuilderOptions): MapBuilder<S>;
 }
+export interface MapBuilderOptions {
+    /**
+     * This project's own origin (e.g. `"https://app.example.com"`) - enables
+     * `.gotoPage()`/`.gotoExternal()`'s origin check against a Block's static
+     * `url`. Omit to skip that check entirely (still fully kind-checked either
+     * way; only the internal/external origin distinction is opt-in).
+     */
+    homeOrigin?: string;
+}
+/**
+ * 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 declare class MapBuilder<Out extends Checkpoint<string>> {
+    private readonly engine;
+    private readonly steps;
+    private readonly homeOrigin;
+    private constructor();
+    /** @internal - use `engine.map()` or the standalone `map()` export. */
+    static begin(engine: Engine, homeOrigin: string | undefined): MapBuilder<S>;
+    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
+    start(): MapBuilder<Out>;
+    /**
+     * 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<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /**
+     * 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<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
+    assert<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /**
+     * Appends a non-navigating page action (submit, upload, add/remove an
+     * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
+     * `defineEffectBlock`/`defineMemEffectBlock`.
+     */
+    method<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /**
+     * 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(): Flow<Out>;
+}
+/**
+ * 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 declare function map(options?: MapBuilderOptions & EngineConfig): MapBuilder<S>;
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -
  * `routes` must cover every tag of `block`'s output (a missing route is a compile