waygraph 0.13.7 → 0.15.0

package/examples/routed-demo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "waygraph-example-routed-demo",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "Waygraph Map folder convention proof - (group)/<page>/page.block.ts + nav.block.ts + methods/*.block.ts, offline fixture, zero new engine code.",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "npm run fixture:test",
+    "fixture": "node scripts/fixture-server.mjs",
+    "fixture:test": "node scripts/with-fixture.mjs npx playwright test",
+    "graph": "waygraph graph",
+    "auto:cli": "node scripts/with-fixture.mjs waygraph auto --cli"
+  },
+  "waygraph": {
+    "baseUrl": "http://127.0.0.1:4277"
+  },
+  "dependencies": {
+    "waygraph": "file:../.."
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/examples/routed-demo/playwright.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "@playwright/test";
+
+const PORT = process.env.WAYGRAPH_FIXTURE_PORT || "4277";
+const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: false,
+  workers: 1,
+  timeout: 30_000,
+  reporter: "list",
+  use: {
+    headless: true,
+    baseURL: process.env.WAYGRAPH_BASE_URL || `http://${HOST}:${PORT}`,
+    launchOptions: {
+      executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
+      args: ["--no-sandbox", "--disable-dev-shm-usage"],
+    },
+  },
+});

package/examples/routed-demo/scripts/fixture-server.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Tiny static server for this example's offline fixture pages.
+ * Mirrors templates/scaffold's own scripts/fixture-server.mjs exactly.
+ */
+import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, extname, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../src/pages");
+const PORT = Number(process.env.WAYGRAPH_FIXTURE_PORT || 4277);
+const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+};
+
+const server = createServer((req, res) => {
+  const raw = (req.url || "/").split("?")[0] || "/";
+  const rel = raw === "/" ? "dashboard.html" : raw.replace(/^\//, "");
+  const full = normalize(join(ROOT, rel));
+  if (!full.startsWith(ROOT) || !existsSync(full)) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("not found");
+    return;
+  }
+  const type = TYPES[extname(full)] || "application/octet-stream";
+  res.writeHead(200, { "content-type": type });
+  res.end(readFileSync(full));
+});
+
+server.listen(PORT, HOST, () => {
+  if (process.env.WAYGRAPH_FIXTURE_QUIET !== "1") {
+    console.error(`waygraph fixture: http://${HOST}:${PORT}/dashboard.html`);
+  }
+});

package/examples/routed-demo/scripts/with-fixture.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Start fixture-server, run a child command, tear down on exit.
+ * Usage: node scripts/with-fixture.mjs [--] <cmd> [args...]
+ * Mirrors templates/scaffold's own scripts/with-fixture.mjs exactly.
+ */
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PORT = process.env.WAYGRAPH_FIXTURE_PORT || "4277";
+const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+
+const argv = process.argv.slice(2).filter((a) => a !== "--");
+if (argv.length === 0) {
+  console.error("usage: node scripts/with-fixture.mjs <cmd> [args...]");
+  process.exit(1);
+}
+
+const env = {
+  ...process.env,
+  WAYGRAPH_FIXTURE_PORT: PORT,
+  WAYGRAPH_FIXTURE_HOST: HOST,
+  WAYGRAPH_FIXTURE_QUIET: "1",
+  WAYGRAPH_BASE_URL: process.env.WAYGRAPH_BASE_URL || `http://${HOST}:${PORT}`,
+};
+
+const server = spawn(process.execPath, [join(HERE, "fixture-server.mjs")], {
+  env,
+  stdio: ["ignore", "ignore", "inherit"],
+});
+
+function killServer() {
+  try {
+    server.kill("SIGTERM");
+  } catch {
+    /* ignore */
+  }
+}
+
+async function waitReady(ms = 5000) {
+  const url = `http://${HOST}:${PORT}/dashboard.html`;
+  const start = Date.now();
+  while (Date.now() - start < ms) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return;
+    } catch {
+      /* retry */
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`fixture server not ready at ${url}`);
+}
+
+let code = 1;
+try {
+  await waitReady();
+  const child = spawn(argv[0], argv.slice(1), { env, stdio: "inherit", shell: false });
+  code = await new Promise((resolve) => {
+    child.on("exit", (c, signal) => resolve(signal ? 1 : (c ?? 1)));
+  });
+} catch (e) {
+  console.error(e instanceof Error ? e.message : String(e));
+  code = 1;
+} finally {
+  killServer();
+}
+process.exit(code);

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

@@ -0,0 +1,12 @@
+import { Engine, start, end } 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();
+
+/** Smoke: dashboard -> click widget -> docs, all Blocks under the Waygraph Map folder convention. */
+export const routedDemoFlow = engine.defineFlow([start, NavDashboardBlock, ClickWidgetBlock, NavDocsBlock, end]);

package/examples/routed-demo/src/map/(app_base)/dashboard/_methods/click-widget.block.ts

@@ -0,0 +1,23 @@
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+import type { Dashboard } from "../../../../states/routed-demo.states.js";
+import { DashboardSel } from "../_sel.js";
+
+/**
+ * Kind: Method
+ * 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
+ * convention's own methods/ subfolder.
+ */
+export const ClickWidgetBlock = defineMethodBlock<Dashboard, Dashboard>({
+  name: "click-widget",
+  description: "Clicks the dashboard's demo widget button.",
+  instruction: {
+    async act(page) {
+      await page.locator(DashboardSel.widgetBtn).click();
+    },
+    resolve: () => checkpoint("Dashboard"),
+    verify: [Trait.text(DashboardSel.widgetOut, "clicked")],
+  },
+});

package/examples/routed-demo/src/map/(app_base)/dashboard/_nav.block.ts

@@ -0,0 +1,18 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { Dashboard } from "../../../states/routed-demo.states.js";
+import { DashboardSel, DASHBOARD_URL } from "./_sel.js";
+
+/**
+ * Kind: Nav
+ * 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.
+ */
+export const NavDashboardBlock = defineNavBlock<Dashboard>({
+  name: "nav-dashboard",
+  description: "Opens the dashboard page.",
+  checkpoint: "Dashboard",
+  url: DASHBOARD_URL,
+  verify: [Trait.visible(DashboardSel.heading)],
+});

package/examples/routed-demo/src/map/(app_base)/dashboard/_page.block.ts

@@ -0,0 +1,22 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { Dashboard } from "../../../states/routed-demo.states.js";
+import { DashboardSel } from "./_sel.js";
+import { ClickWidgetBlock } from "./_methods/click-widget.block.js";
+
+/**
+ * Kind: Page
+ * 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
+ * (nav.block.ts already landed on Dashboard).
+ */
+export const DashboardPageBlock = definePageBlock<Dashboard>({
+  name: "page-dashboard",
+  description: "Dashboard hub - the routed-demo example's (app_base) group.",
+  checkpoint: "Dashboard",
+  verify: [Trait.visible(DashboardSel.heading)],
+  methods: {
+    clickWidget: () => ClickWidgetBlock,
+  },
+});

package/examples/routed-demo/src/map/(app_base)/dashboard/_sel.ts

@@ -0,0 +1,10 @@
+export const DASHBOARD_URL =
+  process.env.WAYGRAPH_DASHBOARD_URL ??
+  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4277"}/dashboard.html`;
+
+export const DashboardSel = {
+  heading: "#dashboard-heading",
+  widgetBtn: "#widget-btn",
+  widgetOut: "#widget-out",
+  goDocs: "#go-docs",
+} as const;

package/examples/routed-demo/src/map/(external)/docs/_nav.block.ts

@@ -0,0 +1,21 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { Docs } from "../../../states/routed-demo.states.js";
+import { DocsSel, DOCS_URL } from "./_sel.js";
+
+/**
+ * Kind: Nav
+ * Route: (external)/docs/
+ *
+ * `(external)` is a purely organizational group folder (Next.js route-group
+ * style, parens never affect the Checkpoint tag) - separates cross-origin/
+ * external tooling from the app's own `(app_base)` pages, matching the
+ * already-established `*-external/` namespacing precedent from
+ * waygraph-mail-adapters.
+ */
+export const NavDocsBlock = defineNavBlock<Docs>({
+  name: "nav-docs",
+  description: "Opens the docs page.",
+  checkpoint: "Docs",
+  url: DOCS_URL,
+  verify: [Trait.visible(DocsSel.heading)],
+});

package/examples/routed-demo/src/map/(external)/docs/_page.block.ts

@@ -0,0 +1,15 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { Docs } from "../../../states/routed-demo.states.js";
+import { DocsSel } from "./_sel.js";
+
+/**
+ * Kind: Page
+ * Route: (external)/docs/
+ * Arrival-only (nav.block.ts already landed on Docs).
+ */
+export const DocsPageBlock = definePageBlock<Docs>({
+  name: "page-docs",
+  description: "Docs hub - the routed-demo example's (external) group.",
+  checkpoint: "Docs",
+  verify: [Trait.visible(DocsSel.heading)],
+});

package/examples/routed-demo/src/map/(external)/docs/_sel.ts

@@ -0,0 +1,7 @@
+export const DOCS_URL =
+  process.env.WAYGRAPH_DOCS_URL ??
+  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4277"}/docs.html`;
+
+export const DocsSel = {
+  heading: "#docs-heading",
+} as const;

package/examples/routed-demo/src/pages/dashboard.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+<head><title>Routed demo - dashboard</title></head>
+<body>
+  <h1 id="dashboard-heading">Dashboard</h1>
+  <button id="widget-btn" onclick="document.getElementById('widget-out').textContent = 'clicked'">Click widget</button>
+  <div id="widget-out"></div>
+  <a id="go-docs" href="/docs.html">Docs</a>
+</body>
+</html>

package/examples/routed-demo/src/pages/docs.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+<head><title>Routed demo - docs</title></head>
+<body>
+  <h1 id="docs-heading">Docs</h1>
+  <a id="go-dashboard" href="/dashboard.html">Back to dashboard</a>
+</body>
+</html>

package/examples/routed-demo/src/states/routed-demo.states.ts

@@ -0,0 +1,10 @@
+import type { Checkpoint } from "waygraph";
+
+/**
+ * Checkpoint names match their own folder's page-slug (PascalCase) under the
+ * Waygraph Map convention - `dashboard/` -> `Dashboard`, `docs/` -> `Docs`.
+ * See openspec/changes/waygraph-map for why this is a naming convention, not
+ * something any tool enforces.
+ */
+export type Dashboard = Checkpoint<"Dashboard">;
+export type Docs = Checkpoint<"Docs">;

package/examples/routed-demo/test-results/.last-run.json

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

package/examples/routed-demo/tests/routed-demo-map.spec.ts

@@ -0,0 +1,17 @@
+import { test, expect } from "@playwright/test";
+import { MemPage, checkpoint } from "waygraph";
+import { routedDemoMapFlow } from "../src/flows/routed-demo-map.flow.js";
+
+/**
+ * Proof that `engine.map()` (the fluent, kind-checked flow builder) works
+ * end to end against a real browser/DOM, not just the in-memory fakes
+ * tests/nav/map-builder.spec.ts already covers in the main waygraph
+ * package - same real fixture server and real Blocks routed-demo.spec.ts
+ * already proves work via defineFlow/the CLI, this time built with
+ * .start().gotoPage(...).method(...).gotoPage(...).end() instead.
+ */
+test("engine.map()-built flow runs for real: Dashboard -> click widget -> Docs", async ({ context }) => {
+  const mem = new MemPage();
+  const result = await routedDemoMapFlow.run(context, mem);
+  expect(result).toEqual(checkpoint("Docs"));
+});

package/examples/routed-demo/tests/routed-demo.spec.ts

@@ -0,0 +1,75 @@
+import { test, expect } from "@playwright/test";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+
+/**
+ * Proof for openspec/changes/waygraph-map: every existing command works
+ * against a project organized under the Waygraph Map folder convention
+ * ((group)/<page-slug>/page.block.ts + nav.block.ts + methods/*.block.ts)
+ * with ZERO new engine code - discoverGraph/loadBlockLibrary already walk
+ * any folder structure, matching only the .block.ts filename pattern.
+ */
+
+const exec = promisify(execFile);
+const node = process.execPath;
+const CLI = join(import.meta.dirname, "..", "..", "..", "bin", "waygraph");
+const root = join(import.meta.dirname, "..");
+
+async function runCli(args: string[]): Promise<{ stdout: string; code: number }> {
+  try {
+    const { stdout } = (await exec(node, [CLI, ...args], { cwd: root })) as { stdout: string };
+    return { stdout, code: 0 };
+  } catch (err) {
+    const e = err as { stdout?: string; code?: number };
+    if (e.stdout !== undefined) return { stdout: e.stdout, code: e.code ?? 1 };
+    throw err;
+  }
+}
+
+test("waygraph graph discovers both Checkpoints via the exact same discoverGraph path a freeform project uses", async () => {
+  const { stdout, code } = await runCli(["graph"]);
+  expect(code).toBe(0);
+  const graph = JSON.parse(stdout.trim());
+  const checkpoints = graph.nodes.map((n: { checkpoint: string }) => n.checkpoint);
+  expect(checkpoints).toEqual(expect.arrayContaining(["Dashboard", "Docs"]));
+  expect(graph.edges.some((e: { block: string }) => e.block === "nav-dashboard")).toBe(true);
+  expect(graph.edges.some((e: { block: string }) => e.block === "nav-docs")).toBe(true);
+});
+
+test("a real detached session navigates the convention-organized site for real, including a real click", async () => {
+  test.setTimeout(30_000);
+  const { stdout } = await exec(node, [
+    CLI,
+    "auto",
+    "--cli",
+    "--detach",
+    "--base-url",
+    process.env.WAYGRAPH_BASE_URL || "http://127.0.0.1:4277",
+    root,
+  ]).then((r) => r);
+  const { sessionId } = JSON.parse(stdout.trim());
+  try {
+    const status = await exec(node, [CLI, "auto", "status", sessionId], { cwd: root });
+    const statusRes = JSON.parse(status.stdout.trim());
+    expect(statusRes.snapshot.here).toBe("Dashboard");
+
+    const clickEdge = statusRes.snapshot.sections
+      .flatMap((s: { edges: { block: string; index: number }[] }) => s.edges)
+      .find((e: { block: string }) => e.block === "click-widget");
+    expect(clickEdge).toBeTruthy();
+    const clickRes = await exec(node, [CLI, "auto", "send", sessionId, String(clickEdge.index)], { cwd: root });
+    const clickJson = JSON.parse(clickRes.stdout.trim());
+    expect(clickJson.ok).toBe(true);
+    expect(clickJson.snapshot.here).toBe("Dashboard");
+
+    // auto reach: one call, real multi-step route (Dashboard -> Docs via nav-docs).
+    const reachRes = await exec(node, [CLI, "auto", "reach", sessionId, "Docs"], { cwd: root });
+    const reachJson = JSON.parse(reachRes.stdout.trim());
+    expect(reachJson.ok).toBe(true);
+    expect(reachJson.path).toEqual(["nav-docs"]);
+    expect(reachJson.snapshot.here).toBe("Docs");
+  } finally {
+    await exec(node, [CLI, "auto", "send", sessionId, "q"], { cwd: root }).catch(() => {});
+  }
+});

package/examples/routed-demo/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noImplicitAny": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/examples/routed-demo-consumer/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "waygraph-example-routed-demo-consumer",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "Waygraph Map 'waypack' loading proof - depends on routed-demo as a plain file: dependency, no separate manifest, waygraph graph understands it via the loaded package's own node_modules path.",
+  "scripts": {
+    "graph:own": "waygraph graph",
+    "graph:loaded": "waygraph graph node_modules/waygraph-example-routed-demo"
+  },
+  "dependencies": {
+    "waygraph": "file:../..",
+    "waygraph-example-routed-demo": "file:../routed-demo"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/examples/saucedemo/.waygraph-auto/0b1f5b26.json

@@ -0,0 +1,8 @@
+{
+  "sessionId": "0b1f5b26",
+  "socketPath": "/tmp/waygraph-auto/0b1f5b26.sock",
+  "pid": 1136773,
+  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
+  "startedAt": "2026-09-20T18:04:00.000Z",
+  "headless": false
+}