waygraph 0.7.15 → 0.10.0

package/dist/engine.d.ts

@@ -536,9 +536,79 @@ export type NavBlockOptions<Out extends Checkpoint<string>> = {
  * hand.
  * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
  * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
- * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
  */
 export declare function defineNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out>): NavBlock<Out>;
+/**
+ * Click-only {@link NavBlock}. Same runtime as {@link defineNavBlock} with
+ * `click` - use this in app code so you never wonder whether a Nav is url or
+ * click (no `__waygraphNavClick` sniffing at author time). Prefer
+ * {@link defineNavBlock} only for `url` / `goto` deep links.
+ */
+export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    checkpoint: Out["__state"];
+    click: string | ((mem: MemPage) => string);
+    requires?: readonly MemKey<any>[];
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
+    instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
+};
+export type NavClickBlock<Out extends Checkpoint<string>> = NavBlock<Out>;
+/** @see {@link NavClickBlockOptions} */
+export declare function defineNavClickBlock<Out extends Checkpoint<string>>(options: NavClickBlockOptions<Out>): NavClickBlock<Out>;
+/**
+ * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps
+ * (submit, upload, finish, logout) - **methods** on a page. Same runtime Block;
+ * marks `__waygraphSalt = "method"` so auto/docs can tell Method from bare
+ * {@link defineBlock}. Does not force `instanceOptions` - use
+ * {@link defineEffectBlock} when the auto menu should spawn one row per live
+ * DOM instance. Prefer hanging methods off a {@link definePageBlock} hub.
+ */
+export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = DefinedBlock<In, Out>;
+/** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
+export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
+export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
+/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
+export declare const defineActionBlock: typeof defineMethodBlock;
+/** One Block (or lazy factory) registered on a {@link PageBlock}. */
+export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
+export type PageBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    /** Checkpoint tag for this screen (hub). */
+    checkpoint: Out["__state"];
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
+    requires?: readonly MemKey<any>[];
+    /**
+     * Methods available on this page. Array, or a record of Blocks / `() => Block`
+     * factories (lazy so the page object can colocate method definitions).
+     */
+    methods?: readonly PageMethodEntry[] | Record<string, PageMethodEntry>;
+    /**
+     * Optional deep-link onto this page (`goto`). XOR with `click`. Omit when the
+     * hub is arrival-only (previous Block already resolved here).
+     */
+    url?: string | ((mem: MemPage) => string);
+    /** Optional click-nav onto this page. XOR with `url`. */
+    click?: string | ((mem: MemPage) => string);
+    instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
+};
+/**
+ * Page hub Block: one Checkpoint = this screen; methods hang off the hub for
+ * readability / auto grouping. Runtime is still a Block (`__waygraphKind = "page"`).
+ * `act` is goto/click when `url`/`click` is set, otherwise a no-op (already here).
+ * Child methods stay ordinary Blocks for graph edges - the page only registers them.
+ */
+export type PageBlock<Out extends Checkpoint<string>> = NavBlock<Out> & {
+    /** Resolved method Blocks registered at define time. */
+    readonly methods: readonly DefinedBlock<any, any>[];
+};
+/** @see {@link PageBlockOptions} */
+export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;
 /**
  * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
  * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu
@@ -582,14 +652,14 @@ export declare function defineMemNavBlock<Out extends Checkpoint<string>>(option
     instanceOptions: NonNullable<Block<Checkpoint<string>, Out>["instanceOptions"]>;
 }): MemNavBlock<Out>;
 /**
- * "Where am I" - reverse-matches a live `page` against every NavBlock in
- * `library`, in order, returning the first one whose own `verify` Traits all
- * pass (its `checkpoint`), or `null` if none match. Deliberately NavBlocks
- * only: a NavBlock has exactly one fixed `checkpoint` and a `verify` list
- * whose whole job is already "confirm arrival here," so it's a reliable
+ * "Where am I" - reverse-matches a live `page` against every NavBlock /
+ * PageBlock in `library`, in order, returning the first one whose own `verify`
+ * Traits all pass (its `checkpoint`), or `null` if none match. Deliberately
+ * Nav/Page hubs only: each has exactly one fixed `checkpoint` and a `verify`
+ * list whose whole job is already "confirm arrival here," so it's a reliable
  * fingerprint - a regular `defineBlock` can branch to different `Out` tags
  * depending on runtime evidence, so its `verify` alone doesn't identify a
- * single state the way a NavBlock's does.
+ * single state the way a hub's does.
  *
  * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
  * what pages exist and how to reach them; `locate()` is how an autonomous

package/dist/engine.js

@@ -634,7 +634,8 @@ export function defineBlock(base) {
  * hand.
  * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
  * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
- * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
  */
 export function defineNavBlock(options) {
     const built = defineBlock({
@@ -682,6 +683,101 @@ export function defineNavBlock(options) {
     }
     return built;
 }
+/** @see {@link NavClickBlockOptions} */
+export function defineNavClickBlock(options) {
+    return defineNavBlock({
+        name: options.name,
+        checkpoint: options.checkpoint,
+        click: options.click,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        ...(options.verify ? { verify: options.verify } : {}),
+        ...(options.highlights ? { highlights: options.highlights } : {}),
+        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
+    });
+}
+export function defineMethodBlock(base) {
+    const built = defineBlock(base);
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "method",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}
+/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
+export const defineActionBlock = defineMethodBlock;
+function resolvePageMethods(methods) {
+    if (!methods)
+        return [];
+    const entries = Array.isArray(methods) ? methods : Object.values(methods);
+    return entries.map((entry) => (typeof entry === "function" ? entry() : entry));
+}
+/** @see {@link PageBlockOptions} */
+export function definePageBlock(options) {
+    if (options.url !== undefined && options.click !== undefined) {
+        throw new Error(`definePageBlock("${options.name}"): pass url XOR click (or neither for arrival-only hub)`);
+    }
+    const methodList = resolvePageMethods(options.methods);
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                if (options.url !== undefined) {
+                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                    await page.goto(url);
+                }
+                else if (options.click !== undefined) {
+                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
+                    await page.locator(selector).click();
+                }
+                // else: arrival-only hub — previous Block already landed here
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            ...(options.verify ? { verify: options.verify } : {}),
+            ...(options.highlights ? { highlights: options.highlights } : {}),
+        },
+    });
+    Object.defineProperty(built, "__waygraphKind", {
+        value: "page",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "page",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "methods", {
+        value: Object.freeze([...methodList]),
+        enumerable: true,
+        configurable: false,
+        writable: false,
+    });
+    Object.defineProperty(built, "__waygraphMethods", {
+        value: methodList.map((m) => m.name),
+        enumerable: false,
+        configurable: false,
+    });
+    if (options.url !== undefined || options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphPageDeepLink", {
+            value: true,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    if (options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphNavClick", {
+            value: options.click,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    return built;
+}
 /**
  * {@link defineBlock} constrained for effect-style instance menus: `requires` +
  * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
@@ -695,6 +791,11 @@ export function defineEffectBlock(base) {
         enumerable: false,
         configurable: false,
     });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "effect",
+        enumerable: false,
+        configurable: false,
+    });
     return built;
 }
 /** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
@@ -715,14 +816,14 @@ export function defineMemNavBlock(options) {
     return built;
 }
 /**
- * "Where am I" - reverse-matches a live `page` against every NavBlock in
- * `library`, in order, returning the first one whose own `verify` Traits all
- * pass (its `checkpoint`), or `null` if none match. Deliberately NavBlocks
- * only: a NavBlock has exactly one fixed `checkpoint` and a `verify` list
- * whose whole job is already "confirm arrival here," so it's a reliable
+ * "Where am I" - reverse-matches a live `page` against every NavBlock /
+ * PageBlock in `library`, in order, returning the first one whose own `verify`
+ * Traits all pass (its `checkpoint`), or `null` if none match. Deliberately
+ * Nav/Page hubs only: each has exactly one fixed `checkpoint` and a `verify`
+ * list whose whole job is already "confirm arrival here," so it's a reliable
  * fingerprint - a regular `defineBlock` can branch to different `Out` tags
  * depending on runtime evidence, so its `verify` alone doesn't identify a
- * single state the way a NavBlock's does.
+ * single state the way a hub's does.
  *
  * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
  * what pages exist and how to reach them; `locate()` is how an autonomous

package/dist/graph.d.ts

@@ -48,7 +48,8 @@ export declare function toMermaid(graph: WaygraphGraph): string;
 /**
  * Blocks present on disk but never wired into a `.flow.ts` defineFlow array.
  * Required before `chain auto` can build a path from the discovered graph -
- * orphan Blocks are intentionally excluded from auto shorthand.
+ * orphan Blocks are intentionally excluded from auto shorthand. Arrival-only
+ * Page hubs and Blocks listed on a Page's `methods` are not orphans.
  */
 export declare function findOrphanBlocks(projectDir: string): Promise<OrphanBlock[]>;
 /**

package/dist/graph.js

@@ -77,7 +77,8 @@ function exportNameToBlockName(exportName) {
 /**
  * Blocks present on disk but never wired into a `.flow.ts` defineFlow array.
  * Required before `chain auto` can build a path from the discovered graph -
- * orphan Blocks are intentionally excluded from auto shorthand.
+ * orphan Blocks are intentionally excluded from auto shorthand. Arrival-only
+ * Page hubs and Blocks listed on a Page's `methods` are not orphans.
  */
 export async function findOrphanBlocks(projectDir) {
     const blockFiles = discoverBlocks(projectDir);
@@ -88,6 +89,27 @@ export async function findOrphanBlocks(projectDir) {
             referenced.add(ref);
         }
     }
+    const pageMethodNames = new Set();
+    for (const file of blockFiles) {
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch {
+            continue;
+        }
+        for (const exported of Object.values(mod)) {
+            if (!exported || typeof exported !== "object")
+                continue;
+            if (exported.__waygraphKind !== "page")
+                continue;
+            const names = exported.__waygraphMethods;
+            if (Array.isArray(names)) {
+                for (const n of names)
+                    pageMethodNames.add(n);
+            }
+        }
+    }
     const orphans = [];
     for (const file of blockFiles) {
         const relFile = relative(projectDir, file);
@@ -98,7 +120,11 @@ export async function findOrphanBlocks(projectDir) {
             const exportName = m[1];
             if (referenced.has(exportName))
                 continue;
-            if (!/defineBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineMemNavBlock/.test(src))
+            if (!/defineBlock|defineMethodBlock|defineActionBlock|definePageBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineNavClickBlock|defineMemNavBlock/.test(src))
+                continue;
+            // Arrival-only Page hubs are never orphans (even if import fails without tsx).
+            const assignSlice = src.slice(m.index, m.index + exportName.length + 80);
+            if (/=\s*definePageBlock\b/.test(assignSlice))
                 continue;
             let block = exportNameToBlockName(exportName);
             try {
@@ -106,6 +132,13 @@ export async function findOrphanBlocks(projectDir) {
                 const exported = mod[exportName];
                 if (isBlockLike(exported))
                     block = exported.name;
+                if (exported &&
+                    typeof exported === "object" &&
+                    exported.__waygraphKind === "page") {
+                    continue;
+                }
+                if (pageMethodNames.has(block))
+                    continue;
             }
             catch {
                 // import may fail in partial projects - keep derived name
@@ -155,7 +188,8 @@ function isBlockLike(val) {
 }
 /** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
 function isNavBlockMarked(val) {
-    return val.__waygraphKind === "nav";
+    const kind = val.__waygraphKind;
+    return kind === "nav" || kind === "page";
 }
 /**
  * Resolves `typeName` to every literal Checkpoint tag it can mean, within
@@ -242,9 +276,9 @@ function extractDefineBlockGenerics(src) {
     // alternation so both shapes come out of the same two capture groups.
     // Effect helpers are TypeScript salt over defineBlock - same In/Out edges.
     const arg = String.raw `(Checkpoint<[^>]*>|[A-Za-z_$][\w]*)`;
-    const re = new RegExp(String.raw `define(?:Mem)?(?:Effect)?Block<\s*${arg}\s*,\s*${arg}\s*>`, "g");
-    // Matches: defineBlock | defineEffectBlock | defineMemEffectBlock
-    // (defineMemBlock alone is not a real helper - Mem* only prefixes Effect.)
+    const re = new RegExp(String.raw `define(?:(?:Mem)?Effect|Method|Action)?Block<\s*${arg}\s*,\s*${arg}\s*>`, "g");
+    // Matches: defineBlock | defineMethodBlock | defineActionBlock | defineEffectBlock |
+    // defineMemEffectBlock (Nav / NavClick / Page use runtime markers, not this regex.)
     const calls = [];
     let m;
     while ((m = re.exec(src)) !== null) {
@@ -289,16 +323,22 @@ export async function discoverGraph(projectDir) {
             const blockName = exported.name;
             if (isNavBlockMarked(exported)) {
                 try {
-                    // NavBlock's own resolve() ignores whatever it's called with -
-                    // always exactly `checkpoint(options.checkpoint)`.
+                    // 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);
-                    edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                    // 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's own resolve() threw" });
+                    skipped.push({ block: blockName, file: relFile, reason: "NavBlock/PageBlock resolve() threw" });
                 }
                 continue;
             }
@@ -307,7 +347,7 @@ export async function discoverGraph(projectDir) {
                 skipped.push({
                     block: blockName,
                     file: relFile,
-                    reason: "no defineBlock/defineEffectBlock<In, Out> generic call found",
+                    reason: "no defineBlock/defineMethodBlock/defineEffectBlock<In, Out> generic call found",
                 });
                 continue;
             }

package/dist/index.d.ts

@@ -2,8 +2,8 @@ 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 } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } 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,5 +1,5 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/examples/saucedemo/README.md

@@ -32,11 +32,25 @@ npx playwright install chromium
 | Want | Command |
 |------|---------|
 | Headless suite | `npm test` |
-| Interactive explore | `npm run auto` |
-| Stepper (manual Next) | `npm run demo:step` |
-| Stepper (Auto-advance) | `npm run demo:autoplay` |
+| Interactive explore (headed panel) | `npm run auto` |
+| Interactive explore (terminal menu) | `npm run auto:cli` |
+| Shop demo stepper | `npm run demo:step` |
+| Shop demo autoplay | `npm run demo:autoplay` |
+| **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
+| Cart bulk stepper | `npm run demo:bulk:step` |
 | List flows | `npm run flows` |
 
+**Demo vs auto vs run for cart bulk**
+
+| | CLI | Needs `.flow.ts`? |
+|--|-----|-------------------|
+| **`run --blocks`** | `npm run run:bulk` — Block names + `--data` | No |
+| **`demo --blocks`** | `npm run demo:bulk` — named flow + `--data` | Optional (`cartBulkFlow`) |
+| **`auto`** | `npm run auto` / `auto:cli` | No — live menu |
+| **`auto --blocks From To`** | path-find on graph | No — checkpoints only |
+
+QA watch+record: `npm run demo:bulk:video` (`--auto-play-video`).
+
 ## Layout (short)
 
 ```text
@@ -45,10 +59,10 @@ src/blocks/
   saucedemo-web/                 # URL /
     NAV.md
     nav-login.block.ts
-    actions/                     # submit-login, logout, …
+    methods/                     # submit-login, logout, …
     inventory/                   # URL /inventory.html
       nav-item-detail.block.ts   # MemNav
-      actions/*.effect.block.ts  # Add / Remove
+      methods/*.effect.block.ts  # Add / Remove
     cart/                        # URL /cart.html
     checkout-step-one/
     checkout-step-two/

package/examples/saucedemo/docs/CONVENTION.md

@@ -1,11 +1,10 @@
 # saucedemo waygraph conventions
 
-Atomic Blocks - one nav / effect / action per real URL or on-page mutation so
+Atomic Blocks - one nav / effect / method per real URL or on-page mutation so
 `waygraph auto` can discover a real state graph (not a fat multi-page Block).
 
-**TypeScript salt only.** `defineNavBlock`, `defineEffectBlock`, and plain
-`defineBlock` are helpers that force a useful shape. At runtime everything is
-still a `Block` - there is no separate Effect or Nav engine.
+**TypeScript salt only.** Helpers force a useful shape. At runtime everything is
+still a `Block` - there is no separate Page / Effect / Nav engine.
 
 **Multi-route consumers:** folder layout must mirror Next.js `app/` page routes -
 see package docs `docs/consumer.html` (no invented `root/`, `landing/`, or
@@ -15,14 +14,18 @@ see package docs `docs/consumer.html` (no invented `root/`, `landing/`, or
 
 | Kind | File | Helper | `page.goto`? |
 |------|------|--------|--------------|
+| Page | `*.page.block.ts` | `definePageBlock` | Optional deep-link; usually arrival-only hub |
 | Nav | `nav-*.block.ts` | `defineNavBlock` / `defineMemNavBlock` | Yes (`url` XOR `click`) |
-| Effect | `*.effect.block.ts` | `defineEffectBlock` | No - mutates a live instance (add/remove/toggle) via mem + `instanceOptions` |
-| Action | `*.action.block.ts` | `defineBlock` | No - forms, submit, logout, etc. |
+| Effect | `*.effect.block.ts` in `methods/` | `defineEffectBlock` | No - mutates a live instance via mem + `instanceOptions` |
+| Method | `*.method.block.ts` in `methods/` | `defineMethodBlock` | No - forms, submit, logout, predefined queues |
 
-Only an explicit `page.goto()` (or NavBlock `click`) counts as navigation - an
-action/effect that fills a form or clicks a button stays non-nav even when the
+Only an explicit `page.goto()` (or NavBlock `click`) counts as navigation - a
+method/effect that fills a form or clicks a button stays non-nav even when the
 app changes URL as a side effect of `#continue`.
 
+**Selectors:** put DOM strings in `*Sel` next to the page (static + `(id) => …`).
+Mem keys store values, not selectors.
+
 ## Layout
 
 ```text
@@ -31,15 +34,16 @@ src/blocks/
   saucedemo-web/                 # THIS FOLDER IS URL "/"
     NAV.md
     nav-login.block.ts
-    actions/
-      submit-login.action.block.ts
+    methods/
+      submit-login.method.block.ts
       submit-login-for-flow.ts
-      submit-logout.action.block.ts
+      submit-logout.method.block.ts
     inventory/                   # /inventory.html
       NAV.md
+      inventory.page.block.ts     # Page hub + methods registry
       nav-item-detail.block.ts
-      actions/
-        inventory-items.ts
+      methods/
+        inventory-items.ts       # InventorySel + collectors
         add-to-cart.effect.block.ts
         remove-from-cart.effect.block.ts
     inventory-item/              # /inventory-item.html
@@ -53,18 +57,18 @@ src/blocks/
       nav-checkout-info.block.ts
     checkout-step-one/           # /checkout-step-one.html
       NAV.md
-      actions/
-        submit-checkout-info.action.block.ts
+      methods/
+        submit-checkout-info.method.block.ts
     checkout-step-two/           # /checkout-step-two.html
       NAV.md
-      actions/
-        finish-order.action.block.ts
+      methods/
+        finish-order.method.block.ts
 src/states/
 src/flows/
 ```
 
 `waygraph check` should report zero warnings - every navigation goes through
-a `defineNavBlock`, nothing else calls `page.goto`.
+a `defineNavBlock` / Page deep-link, nothing else calls `page.goto`.
 
 `waygraph auto` should discover Checkpoints as nodes and these Blocks as
 edges (including cycles via logout / continue-shopping / back-to-products).