waygraph 0.13.7 → 0.15.0

package/templates/scaffold/src/map/(external)/mailpit/_page.block.ts

@@ -0,0 +1,30 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { MailpitInbox } from "../../../states/demo.states.js";
+import { AssertEmailReceivedBlock } from "./_methods/assert-email-received.method.block.js";
+import { OpenMessageBlock } from "./_methods/open-message.method.block.js";
+import { AssertEmailContentBlock } from "./_methods/assert-email-content.method.block.js";
+import { ExtractEmailLinkBlock } from "./_methods/extract-email-link.method.block.js";
+
+/**
+ * Kind: Page
+ * Helper: definePageBlock
+ * Route: (external)/mailpit/  (= http://127.0.0.1:8025/ by default)
+ *
+ * Hub for the Mailpit dev-inbox screen. Arrival-only (no url/click) -
+ * nav-mailpit-inbox owns the goto. Methods: confirm the email arrived, open
+ * it, confirm its content, then read its link - all mem-driven (recipient,
+ * link pattern, expected content), so this one page's methods serve any
+ * number of different email scenarios, not just one.
+ */
+export const MailpitInboxPageBlock = definePageBlock<MailpitInbox>({
+  name: "page-mailpit-inbox",
+  description: "Mailpit dev inbox hub - confirm arrival/content, open the expected message, read its link.",
+  checkpoint: "MailpitInbox",
+  verify: [Trait.url({ pathname: "/" })],
+  methods: {
+    assertEmailReceived: () => AssertEmailReceivedBlock,
+    openMessage: () => OpenMessageBlock,
+    assertEmailContent: () => AssertEmailContentBlock,
+    extractEmailLink: () => ExtractEmailLinkBlock,
+  },
+});

package/templates/scaffold/src/map/(external)/mailpit/_sel.ts

@@ -0,0 +1,5 @@
+/** Selectors confirmed against a real running `axllent/mailpit` container's web UI. */
+export const MailpitSel = {
+  messageRow: "a.message",
+  previewIframe: "#preview-html",
+} as const;

package/templates/scaffold/src/states/demo.mem-keys.ts

@@ -1,7 +1,31 @@
-import { keyGroup } from "waygraph";
+import { key, keyGroup } from "waygraph";
 
 /**
  * Which catalog row `add-item` / `remove-item` act on.
  * `waygraph auto` fills this via Effect `instanceOptions` (one menu row per live button).
  */
 export const SelectedItem = keyGroup<{ id: string; name: string }>("demo.selectedItem");
+
+/** The link read out of the opened message - set by extract-email-link. */
+export const EmailLink = keyGroup<{ url: string }>("demo.emailLink");
+
+/**
+ * The recipient open-message looks for in the inbox. Mailpit lists newest
+ * first, but `.first()` alone picks the wrong row once more than one
+ * recipient's mail is sitting in the same inbox - match by mem, not position.
+ */
+export const ExpectedRecipient = keyGroup<{ email: string }>("demo.expectedRecipient");
+
+/**
+ * Substring the link's `href` must contain - lets the same extract-email-link
+ * Block serve any number of different email templates/scenarios in one
+ * project without a new Block per scenario. Only the mem values change per
+ * run, not the Blocks.
+ */
+export const ExpectedLinkPattern = key<string>("demo.expectedLinkPattern");
+
+/**
+ * The substring the open message's body must contain - same reuse reasoning
+ * as ExpectedLinkPattern: one Block, many scenarios, driven by mem.
+ */
+export const ExpectedEmailContent = key<string>("demo.expectedEmailContent");

package/templates/scaffold/src/states/demo.states.ts

@@ -4,3 +4,14 @@ export type Home = Checkpoint<"Home">;
 export type HomeVerified = Checkpoint<"HomeVerified">;
 export type ItemInCart = Checkpoint<"ItemInCart">;
 export type CartEmpty = Checkpoint<"CartEmpty">;
+
+// --- Mailpit (external tool surface, src/map/(external)/mailpit/) ---
+
+/** Mailpit inbox UI reached; message list visible. */
+export type MailpitInbox = Checkpoint<"MailpitInbox">;
+
+/** The message addressed to the expected recipient is open; preview iframe visible. */
+export type MailpitMessageOpen = Checkpoint<"MailpitMessageOpen">;
+
+/** Reached via src/map/(app_base)/docs/ - see openspec/changes/waygraph-map. */
+export type Docs = Checkpoint<"Docs">;

package/templates/scaffold/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "failed",
+  "failedTests": []
+}

package/templates/scaffold/tests/example.spec.ts

@@ -4,9 +4,9 @@ import { exampleFlow } from "../src/flows/example.flow.js";
 import { shopFlow } from "../src/flows/shop.flow.js";
 import { SelectedItem } from "../src/states/demo.mem-keys.js";
 
-test("example flow reaches HomeVerified", async ({ context }) => {
+test("example flow reaches Docs (home -> assert -> sibling docs/ page)", async ({ context }) => {
   const result = await exampleFlow.run(context, new MemPage());
-  expect(result).toEqual(checkpoint("HomeVerified"));
+  expect(result).toEqual(checkpoint("Docs"));
 });
 
 test("shop flow adds then clears (Effect + Method)", async ({ context }) => {

package/templates/scaffold/tests/mail-verify.spec.ts

@@ -0,0 +1,191 @@
+import { test, expect } from "@playwright/test";
+import { spawnSync } from "node:child_process";
+import net from "node:net";
+import { MemPage, checkpoint } from "waygraph";
+import { mailVerifyFlow } from "../src/flows/mail-verify.flow.js";
+import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/states/demo.mem-keys.js";
+import { HOME_URL } from "../src/map/(app_base)/home/_sel.js";
+
+/**
+ * This scaffold has no real backend, so these tests play the role of "the
+ * app sent a verification email" themselves: spin up a real, throwaway
+ * Mailpit container, send a real SMTP message, then run mailVerifyFlow for
+ * real - a real cross-origin browser hop into Mailpit's own web UI and
+ * back, no mail-catcher REST API anywhere. Covers the happy path, both
+ * failure paths its QA-facing asserts exist for (no email arrived, wrong
+ * content), and - the actual point of making the mail-reading Blocks
+ * mem-driven - a second, entirely different email scenario running through
+ * the exact same four Blocks with zero new code.
+ */
+
+function runMailpit(): { containerId: string; smtpPort: number; httpPort: number } {
+  const run = spawnSync("docker", ["run", "--rm", "-d", "-p", "0:1025", "-p", "0:8025", "axllent/mailpit"], {
+    encoding: "utf8",
+  });
+  if (run.status !== 0) throw new Error(`docker run axllent/mailpit failed: ${run.stderr || run.stdout}`);
+  const containerId = run.stdout.trim();
+  const portCheck = spawnSync("docker", ["port", containerId], { encoding: "utf8" });
+  const portFor = (containerPort: number) => {
+    const line = portCheck.stdout.split("\n").find((l) => l.startsWith(`${containerPort}/tcp`) && l.includes("0.0.0.0"));
+    const m = line?.match(/:(\d+)\s*$/);
+    if (!m) throw new Error(`could not determine host port for ${containerPort}`);
+    return Number(m[1]);
+  };
+  return { containerId, smtpPort: portFor(1025), httpPort: portFor(8025) };
+}
+
+function dockerAvailable(): boolean {
+  return spawnSync("docker", ["ps"], { encoding: "utf8" }).status === 0;
+}
+
+async function sendTestEmail(opts: { host: string; port: number; to: string; subject: string; html: string }): Promise<void> {
+  const body = [
+    "From: scaffold-app@example.com",
+    `To: ${opts.to}`,
+    `Subject: ${opts.subject}`,
+    "Content-Type: text/html; charset=utf-8",
+    "",
+    opts.html,
+    ".",
+  ].join("\r\n");
+
+  await new Promise<void>((resolve, reject) => {
+    const socket = net.createConnection({ host: opts.host, port: opts.port });
+    function cmd(line: string): Promise<string> {
+      return new Promise((res) => {
+        socket.once("data", (d) => res(d.toString()));
+        socket.write(line + "\r\n");
+      });
+    }
+    socket.once("error", reject);
+    socket.once("connect", () => {
+      (async () => {
+        await new Promise<void>((r) => socket.once("data", () => r()));
+        await cmd("HELO localhost");
+        await cmd("MAIL FROM:<scaffold-app@example.com>");
+        await cmd(`RCPT TO:<${opts.to}>`);
+        await cmd("DATA");
+        await cmd(body);
+        await cmd("QUIT");
+        socket.end();
+        resolve();
+      })().catch(reject);
+    });
+  });
+}
+
+async function withMailpit<T>(fn: (opts: { httpPort: number; smtpPort: number }) => Promise<T>): Promise<T> {
+  const { containerId, smtpPort, httpPort } = runMailpit();
+  const originalMailUrl = process.env.WAYGRAPH_MAIL_URL;
+  try {
+    process.env.WAYGRAPH_MAIL_URL = `http://127.0.0.1:${httpPort}`;
+    return await fn({ httpPort, smtpPort });
+  } finally {
+    if (originalMailUrl === undefined) delete process.env.WAYGRAPH_MAIL_URL;
+    else process.env.WAYGRAPH_MAIL_URL = originalMailUrl;
+    spawnSync("docker", ["stop", containerId]);
+  }
+}
+
+const VERIFICATION_CONTENT = "Please confirm your email address to finish setting up your account.";
+
+test("mailVerifyFlow: confirms arrival, confirms content, reads the real link, navigates to it", async ({
+  context,
+}) => {
+  test.skip(!dockerAvailable(), "Docker not reachable in this environment");
+  test.setTimeout(60_000);
+
+  await withMailpit(async ({ smtpPort }) => {
+    const recipient = "demo-user@example.com";
+    await sendTestEmail({
+      host: "127.0.0.1",
+      port: smtpPort,
+      to: recipient,
+      subject: "Please verify your account",
+      html: `<p>${VERIFICATION_CONTENT}</p><a href="${HOME_URL}?verified=1">Verify your account</a>`,
+    });
+
+    const mem = new MemPage();
+    mem.set(ExpectedRecipient({ email: recipient }));
+    mem.set(ExpectedLinkPattern, "verified=1");
+    mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
+    const result = await mailVerifyFlow.run(context, mem);
+    expect(result).toEqual(checkpoint("HomeVerified"));
+  });
+});
+
+test("the same four mail-reading Blocks handle a second, unrelated email scenario - zero new Blocks", async ({
+  context,
+}) => {
+  test.skip(!dockerAvailable(), "Docker not reachable in this environment");
+  test.setTimeout(60_000);
+
+  await withMailpit(async ({ smtpPort }) => {
+    const recipient = "password-reset-user@example.com";
+    const resetContent = "We received a request to reset your password.";
+    await sendTestEmail({
+      host: "127.0.0.1",
+      port: smtpPort,
+      to: recipient,
+      subject: "Reset your password",
+      // A decoy link comes first - proves ExpectedLinkPattern actually
+      // discriminates between two links in the body, not just "the first one".
+      html: `<p>${resetContent}</p>
+             <a href="https://example.com/report-abuse?ref=xyz">Not you? Report this</a>
+             <a href="${HOME_URL}?verified=1">Reset your password</a>`,
+    });
+
+    const mem = new MemPage();
+    mem.set(ExpectedRecipient({ email: recipient }));
+    mem.set(ExpectedLinkPattern, "verified=1");
+    mem.set(ExpectedEmailContent, resetContent);
+    const result = await mailVerifyFlow.run(context, mem);
+    expect(result).toEqual(checkpoint("HomeVerified"));
+  });
+});
+
+test("assert-email-received fails loud, naming itself, when no email ever arrives", async ({ context }) => {
+  test.skip(!dockerAvailable(), "Docker not reachable in this environment");
+  test.setTimeout(30_000);
+
+  await withMailpit(async () => {
+    const mem = new MemPage();
+    mem.set(ExpectedRecipient({ email: "nobody-sent-this-one@example.com" }));
+    mem.set(ExpectedLinkPattern, "verified=1");
+    mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
+    // A defineFlow chain's verify-failure error names the whole path taken so
+    // far (each composed Block's own name accumulates through connect()),
+    // not just the leaf Block - real, useful QA context, not a bug - so this
+    // matches the accumulated name ending at assert-email-received, not an
+    // exact "failed after \"assert-email-received\"" alone.
+    await expect(mailVerifyFlow.run(context, mem)).rejects.toThrow(
+      /trait "email-received" failed after ".*assert-email-received"/,
+    );
+  });
+});
+
+test("assert-email-content fails loud, naming itself, when the email's copy doesn't match", async ({ context }) => {
+  test.skip(!dockerAvailable(), "Docker not reachable in this environment");
+  test.setTimeout(60_000);
+
+  await withMailpit(async ({ smtpPort }) => {
+    const recipient = "demo-user@example.com";
+    await sendTestEmail({
+      host: "127.0.0.1",
+      port: smtpPort,
+      to: recipient,
+      subject: "Please verify your account",
+      // A real link is present (so this isolates the content check, not the
+      // link-extraction step), but the surrounding copy is wrong.
+      html: `<p>Your package has shipped!</p><a href="${HOME_URL}?verified=1">Track it</a>`,
+    });
+
+    const mem = new MemPage();
+    mem.set(ExpectedRecipient({ email: recipient }));
+    mem.set(ExpectedLinkPattern, "verified=1");
+    mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
+    await expect(mailVerifyFlow.run(context, mem)).rejects.toThrow(
+      /trait "body-contains-expected-text" failed after ".*assert-email-content"/,
+    );
+  });
+});

package/templates/skills/waygraph-blind-pilot.skill.md

@@ -0,0 +1,61 @@
+---
+name: waygraph-blind-pilot
+description: Cold-start a waygraph project against a real site with zero existing Blocks - navigate with raw primitives, recognize real patterns, and author real Nav/Page/Method Blocks as you go. Use when the target app has no (or very little) waygraph coverage yet, not for driving an already-Block-covered app.
+---
+
+Blind Pilot is the same session mechanism as `waygraph-pilot`, minus the requirement of any
+pre-existing Blocks. `auto --cli --detach` tolerates a project with zero `.block.ts` files -
+`auto click/type/goto/press/upload` act on the real page before any Block exists to cover it.
+This package generates **no Block content for you** - you write real `.block.ts`/`*Sel`/
+mem-key files by hand as you go. That's the whole point: turn one-off exploration into
+permanent, reusable, typed coverage instead of leaving nothing behind.
+
+## The real loop
+
+1. `auto goto <sessionId> <url>` / `auto click` / `auto type` to explore the real page.
+2. `auto dom <sessionId> --mode full --selector <sel>` to read real structure before writing
+   a selector - never guess a selector, confirm it against the real DOM first. `--mode aria`
+   is faster for a first pass but can show stale/hidden responsive-duplicate content in some
+   real apps (confirmed live: a hidden `lg:hidden` panel's heading text showed up in an aria
+   snapshot even when scoped to `main`) - fall back to `--mode full` and check actual CSS
+   classes/structure if aria output looks inconsistent with what a screenshot shows.
+3. Once you recognize a real pattern (a login form, a list-item-with-action row, a modal),
+   write the real Blocks for it - `*Sel` object first (grounded in the DOM you just read),
+   then `Nav`/`Page`/`Method` Blocks, following `templates/scaffold`'s own folder convention
+   (`(group)/<page-slug>/page.block.ts` + `nav.block.ts` + `methods/*.block.ts` + one `*.sel.ts`)
+   so the result becomes part of the Waygraph Map, not a scattered one-off file.
+4. `auto reload <sessionId>` to pick up the newly-written Block(s) without restarting.
+5. Run the new Block for real via `auto send` - prove it works before moving to the next
+   pattern, exactly like any other real Block.
+6. Ask the user a clarifying question only when something genuinely can't be resolved from
+   the DOM alone (is this instance local or published? does a downstream integration exist?)
+   - don't ask about things `auto dom` can just answer.
+
+## Real gotchas specific to cold-start authoring
+
+- **`discoverGraph`'s per-file import errors are mostly silent.** A malformed newly-written
+  Block file can simply vanish from the graph with no error printed anywhere obvious - if a
+  Block you just wrote doesn't show up after `auto reload`, check `waygraph graph`'s own
+  `skipped` list and the file's syntax directly, don't assume it just needs more time.
+- **`defineAssertBlock` needs no `<In, Out>` generic to type-check** (`checkpoint: "X"` alone
+  is enough for TypeScript to infer it) - but older/naive static-graph discovery logic may
+  rely on parsing an explicit generic from source text. If a freshly-written
+  `defineAssertBlock` Block is missing from `waygraph graph`'s edges (silently, no error),
+  check whether this package's own `graph.ts` has the matching-marker fix for it, or add an
+  explicit generic type argument as a workaround.
+- **A `<p>`/text-based selector often needs scoping**, not just a class name - a sibling
+  "chat list item" and "message preview" frequently share the exact same CSS classes in real
+  apps, distinguished only by DOM position (first vs second child of a specific wrapper).
+  Confirm via `auto dom --mode full` before assuming a class alone is unique enough.
+- **Confirm a selector count, not just its first match**, when building anything the menu
+  will expand into multiple live rows (an `instanceOptions`-driven Block) - `auto dom`'s
+  default read can silently show only one match even when several exist; check the real
+  page count (e.g. via a scoped debug script) before assuming a plain `.first()` is safe
+  long-term. A `.first()`-shaped Block is a legitimate STARTING point for a page that only
+  ever has one real row to act on - promote it to a mem-driven `defineMemNavBlock` /
+  `defineEffectBlock` (see the `waygraph-pilot` skill and
+  `examples/saucedemo/.../nav-item-detail.block.ts` for the real pattern) once a second real
+  row genuinely exists to pick between, not before.
+- **Prefer the real Pilot overlay over ad hoc status output** when driving a
+  `--non-headless` session someone might be watching - it auto-updates on every menu build,
+  point a human at the badge/panel instead of re-inventing status reporting.

package/templates/skills/waygraph-pilot.skill.md

@@ -0,0 +1,108 @@
+---
+name: waygraph-pilot
+description: Drive an existing waygraph Block graph as a real agent - use when a task needs to operate a web app that already has waygraph Blocks written for it (login, checkout, matching, chat, admin flows, etc.), not when writing new Blocks from scratch.
+---
+
+Waygraph Pilot is not a planner you call and get an answer from - `pilot start` only
+bootstraps a session and hands you the whole project's Block graph as context. **You** are
+the reasoning agent. Every multi-step decision (which Block to run next, when a route needs
+`reach` vs `send`, when to fall back to raw primitives) is yours to make, turn by turn, by
+reading each `auto status`/`auto send` response.
+
+## Starting a session
+
+```
+waygraph pilot start                      # bootstraps: {sessionId, socketPath, headless, graph, snapshot}
+waygraph auto status <sessionId>          # re-read the live menu, no side effects
+waygraph auto send <sessionId> "<pick>"   # run exactly one Block (by menu index or name)
+waygraph auto reach <sessionId> <Checkpoint>  # path-find + run a whole route in one call
+```
+
+`graph` in `pilot start`'s response is the **whole project's** Block/Checkpoint graph, not
+just what's reachable from here - use it to plan several steps ahead before you start
+sending picks.
+
+## Rule 1: run real Blocks, not raw primitives
+
+Default action is always `auto send`/`auto reach` (a real Block). `auto dom/click/type/
+goto/press/upload` are for genuine gaps only - a page no Block covers yet. Before reaching
+for a raw primitive, check `auto status`'s own menu: if a Block already does this, use it.
+A raw click finishes the moment's task but leaves nothing typed, reusable, or re-runnable -
+the entire reason this package exists. If a needed action truly has no Block, write one
+properly (mirroring a sibling Block's shape) and `auto reload` it in rather than raw-clicking
+past the gap.
+
+The one legitimate exception: `auto dom` to resolve a real ambiguity the menu's own labels
+can't (e.g. two products tied at the same displayed price) - and say so explicitly when you
+do it.
+
+## Rule 2: `resync` fixes a stale position, but has its own real limit
+
+`auto resync <sessionId>` forces `here` to be re-detected from the live page right now -
+use it whenever something outside this session might have changed the page (a human
+co-driving a visible `--non-headless` session is the real, common case). But `resync` can
+only ever be as good as the project's own Block coverage: if two Checkpoints share a route
+and nothing in their `verify` arrays tells them apart, `resync` will confidently report the
+wrong one. This is a coverage gap in the project's Blocks, not a `resync` bug - if you hit
+one, fix the ambiguity (add a second, concrete `Trait.visible` condition that's only true in
+one of the two states - see `AppHomePageBlock`/`InPoolPageBlock` in a real veciro-waygraph
+example of exactly this: the same `/app` route, split by presence of a "Join Pool" vs
+"Leave pool" button).
+
+## Rule 3: mem is intent, Checkpoint is reality - never blur them
+
+Checkpoint is *designed* to be DOM-derivable (that's what `resync` does) - when in doubt,
+trust the DOM for "where am I." Mem is different: it holds the agent's own intent or
+expectation (which row to act on next, what value a later assertion should find) - it must
+never be inferred from the DOM, because doing so breaks assertion Blocks' entire ability to
+catch a real app bug (mem states what's expected, DOM states what's real, `verify` compares
+them - if mem always mirrored the DOM, a genuine bug would just silently agree with itself).
+A Block with an `instanceOptions` re-asserts its own mem input fresh every time it's picked
+from a live menu; a Block without one has no such protection - if something outside your
+control (a human click) might have interfered, re-supply mem explicitly before the next
+step rather than trusting stale state.
+
+## Rule 4: a transition Block needs its OWN `verify`
+
+A real bug this exact lesson comes from: a login Block's `act()` (click submit) succeeded
+instantly, but the real backend call failed a moment later (401, unverified email) - well
+after `resolve()` had already optimistically claimed "AppHome." The destination
+Checkpoint's own PageBlock `verify` never ran, because a Block's `verify` is its own, never
+inherited from another Block that merely resolves to the same tag. Without an explicit
+`verify: [Trait.visible(...)]` on the transition Block itself, a real failure silently
+self-reports success instead of failing loud. Any Block whose `act()` can plausibly fail
+server-side after a client-side click needs its own verify - don't assume the destination
+Checkpoint's PageBlock covers it.
+
+## Rule 5: `defineAssertBlock` for "already there, assert a fact" checks
+
+The majority shape of real QA/verification: you're already logged in, already at some
+Checkpoint, and need to assert something is true. `defineAssertBlock({ name, checkpoint,
+verify })` is sugar for exactly this - no hand-written act/resolve. For a check whose target
+varies per run (assert a specific matched user's name is present, not a fixed string), hand-
+write a `Trait` object directly instead of the `Trait.visible`/`text` factories - `Trait`'s
+own shape is `{ name, check(page, mem) }`, so a plain object literal gets real mem access a
+factory-built Trait can't. Gate it with `requires: [SomeKey]` so it's correctly hidden from
+the live menu until that mem is actually populated, rather than appearing early and failing
+confusingly.
+
+## Known real environment gotchas
+
+- **`auto reload`** picks up an edited/new consumer Block file mid-session, no restart
+  needed. It does NOT help if the waygraph *package's own source* changed (a detached
+  session process never re-imports its own already-loaded dependencies) - that needs a
+  full session restart. It also doesn't help for a non-`.block.ts` file (a `.sel.ts`, a
+  shared selector/type file) that some *other* already-loaded Block file imported earlier
+  in the session's life - ESM caches that import too, and only the top-level `.block.ts`
+  file gets cache-busted on reload. When in doubt after editing a shared file, restart.
+- **HeadlessUI-style popovers** (or similar open/close transitions) sometimes aren't
+  interactable the instant their trigger is clicked - a real, reproducible flake, not
+  paranoia. A short `page.waitForTimeout(300-400)` between opening a popover and acting
+  inside it is a real, load-bearing fix seen live more than once, not defensive padding.
+- **Orphan Blocks** (not wired into any `.flow.ts`) are still fully visible and runnable in
+  the live Pilot menu - orphan status only blocks `auto --blocks <From> <To>` pathfinding,
+  never `auto`'s own interactive menu.
+- A hard `page.goto()` straight to an SPA route can render a stale/incomplete view compared
+  to reaching the same page via a real in-app click-nav - if `auto dom` output looks wrong
+  right after a raw `goto`, try reaching the page through its real click-based NavBlock
+  instead before assuming the DOM read is broken.

package/templates/quickstart/README-saucedemo-commands.md

@@ -1,72 +0,0 @@
-# Sauce Demo - convention showcase
-
-Full live consumer for [saucedemo.com](https://www.saucedemo.com). This tree is
-the **reference** for waygraph consumer conventions:
-
-- Route folders under `src/blocks/saucedemo-web/` = real Swag Labs URLs
-- **Nav** / **Effect** / **Action** file kinds (helpers are TypeScript salt;
-  runtime is still `Block`)
-- `instanceOptions` menus for `waygraph auto` (Add/Remove + Open details)
-- Detailed Kind / Helper / Route comments on every Block file
-- Per-route `NAV.md` + root `src/blocks/SITE-MAP.md`
-
-**GitHub Pages walkthrough:**
-[docs/saucedemo](https://deviate-dv8.github.io/waygraph/saucedemo/)
-(`docs/saucedemo/` in this repo - README, SITE-MAP, kinds, layout, auto, comments).
-
-`waygraph try demo` copies the sibling template at `templates/quickstart`
-(same Blocks) into an OS temp dir.
-
-## Setup
-
-From the waygraph package root (after `npm run build`):
-
-```bash
-cd examples/saucedemo
-npm install
-npx playwright install chromium
-```
-
-## Commands
-
-| Want | Command |
-|------|---------|
-| Headless suite | `npm test` |
-| 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 (named flow) | `npm run demo:bulk` |
-| Cart bulk stepper | `npm run demo:bulk:step` |
-| **Cart bulk** chain (Block names only) | `npm run chain:bulk` |
-| List flows | `npm run flows` |
-
-**Demo vs auto vs chain for cart bulk**
-
-| | CLI | Needs `.flow.ts`? |
-|--|-----|-------------------|
-| **`chain` (block names)** | `npm run chain:bulk` → `loginFlow({…}) then add-all-to-cart then remove-all-from-cart` | No — Block `.name` only |
-| **`demo` (named flow)** | `npm run demo:bulk` → `cartBulkFlow` | Yes — `cart-bulk.flow.ts` |
-| **`auto` (pick live)** | `npm run auto` / `auto:cli` | No — menu from graph |
-
-Same Blocks either way. `chain` is the ad-hoc path (handout-style `"A then B then C"`).
-
-## Layout (short)
-
-```text
-src/blocks/
-  SITE-MAP.md
-  saucedemo-web/                 # URL /
-    NAV.md
-    nav-login.block.ts
-    methods/                     # submit-login, logout, …
-    inventory/                   # URL /inventory.html
-      nav-item-detail.block.ts   # MemNav
-      methods/*.effect.block.ts  # Add / Remove
-    cart/                        # URL /cart.html
-    checkout-step-one/
-    checkout-step-two/
-```
-
-Docs: [Sauce Demo showcase](../../docs/saucedemo/) ·
-[Auto explore](../../docs/auto.html) · [Consumer layout](../../docs/consumer.html)

package/templates/scaffold/src/blocks/SITE-MAP.md

@@ -1,12 +0,0 @@
-# Site map (scaffold)
-
-Offline catalog uses one synthetic namespace (`demo-web/`) and a local
-`home.html` fixture so `npm test` / `waygraph auto` need no network.
-
-| Folder | URL | Notes |
-|--------|-----|-------|
-| `demo-web/` | `/` (synthetic) | Nav + Page hub + methods/effects |
-| `demo-web/methods/` | same URL | assert, add/remove Effects, clear |
-
-When you wire a real app, rename `demo-web/` to your FE origin namespace and
-add one folder per real `page.tsx` route. See **Consumer layout** docs.

package/templates/scaffold/src/blocks/demo-web/NAV.md

@@ -1,29 +0,0 @@
-# demo-web / (synthetic home)
-
-**URL:** `http://127.0.0.1:4177/home.html` (offline catalog via `scripts/fixture-server.mjs` - replace with your real `/`)
-
-## Nav-to
-
-| From | Block | How |
-|------|-------|-----|
-| start | `nav-home` | `defineNavBlock` `url` → home.html |
-
-## Page hub
-
-| Block | Checkpoint | Methods |
-|-------|------------|---------|
-| `page-home` | `Home` | add-item, remove-item, clear-cart, assert-hello |
-
-## Methods / Effects
-
-| Block | Kind | Auto |
-|-------|------|------|
-| `assert-hello` | Method | single row |
-| `add-item` | Effect | one row per live Add button (`instanceOptions`) |
-| `remove-item` | Effect | one row per live Remove button |
-| `clear-cart` | Method | single row |
-
-## States / mem-keys
-
-- Checkpoints: `Home`, `HomeVerified`, `ItemInCart`, `CartEmpty`
-- Mem: `demo.selectedItem` (`SelectedItem`) - filled by auto or `--data`

package/templates/scaffold/src/blocks/demo-web/methods/assert-hello.method.block.ts

@@ -1,50 +0,0 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
-import { DemoSel } from "../demo-sel.js";
-
-/**
- * Kind: Method
- * Helper: defineMethodBlock
- * Route: demo-web/methods/
- *
- * Same-URL assert after nav - stubs + fixtures + YAP slide.
- */
-export const AssertHelloBlock = defineMethodBlock({
-  name: "assert-hello",
-  description: "Confirms the hello heading is still visible after arrival.",
-  instruction: {
-    async act(_page) {},
-    async observe(page) {
-      await page.locator(DemoSel.title).first().waitFor({ state: "visible", timeout: 5_000 });
-      return "ok" as const;
-    },
-    resolve: () => checkpoint("HomeVerified"),
-    verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.sub)],
-    stubBefore: {
-      title: { selector: DemoSel.title, label: "Heading about to check" },
-    },
-    stubAfter: {
-      title: {
-        selector: DemoSel.title,
-        label: "Hello confirmed",
-        detail: "Offline scaffold proof point.",
-        duration: true,
-      },
-      sub: { selector: DemoSel.sub, label: "Subcopy", duration: 1500 },
-    },
-    stubOnError: {
-      title: {
-        selector: DemoSel.title,
-        label: "Heading at failure",
-        tag: "FAIL",
-      },
-    },
-    slides: [
-      {
-        caption: "Scaffold covers auto + narration",
-        detail: "Page hub, Effect instanceOptions, stubs, fixtures, YAP.",
-        tag: "YAP",
-        duration: true,
-      },
-    ],
-  },
-});