waygraph 0.7.13 → 0.7.15

package/README.md

@@ -34,7 +34,7 @@ This README stays the in-repo API narrative; Pages is the same material for eyeb
 | Goal | Command |
 |------|---------|
 | Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
-| Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto .` |
+| Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
 | Scaffold a new **offline** project (green `npm test` on a `data:` URL) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
 | Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
@@ -221,10 +221,10 @@ autoplay off** (manual "Run this step" / "Next"). Flags beat env:
 
 | Want | Command |
 |------|---------|
-| Manual watch | `waygraph demo shopFlow .` |
-| Auto-advance | `waygraph demo shopFlow . --autoplay` |
-| Same overlay on a chain | `waygraph chain "login then nav-cart" . --step` |
-| No overlay | `waygraph demo shopFlow . --no-step` |
+| Manual watch | `waygraph demo shopFlow` |
+| Auto-advance | `waygraph demo shopFlow --autoplay` |
+| Same overlay on a chain | `waygraph chain "login then nav-cart" --step` |
+| No overlay | `waygraph demo shopFlow --no-step` |
 
 `--step` = headed overlay. `--autoplay` = panel Auto-advance starts checked (timer;
 flip mid-run; manual click always wins). `chain` does **not** default to step — pass
@@ -234,14 +234,14 @@ flip mid-run; manual click always wins). `chain` does **not** default to step
 cursor travel + pulse before the real click; `url` NavBlocks still `goto`. Full page:
 https://deviate-dv8.github.io/waygraph/demo.html
 
-**Flow video (headless OK):** `waygraph chain "loginFlow({...}) then viewerBlockedFlow({...})" . --video`
+**Flow video (headless OK):** `waygraph chain "loginFlow({...}) then viewerBlockedFlow({...})" --video`
 uses Playwright `recordVideo` and prints the `.webm` path when done (default dir:
 `.waygraph-videos/`). Lighter than help-center-clip-engine (no overlay/ffmpeg pipeline).
 Same flag works on `waygraph demo`. Programmatic: `Engine({ recordVideo: { dir: "./videos" } })`.
 
-**Project hygiene:** `waygraph check .` warns on nav outside NavBlocks **and** lists
+**Project hygiene:** `waygraph check` warns on nav outside NavBlocks **and** lists
 **orphan Blocks** (a `*.block.ts` export not wired into any `.flow.ts` defineFlow array).
-Zero orphans is required before `waygraph chain auto <fromCheckpoint> <toCheckpoint> .`
+Zero orphans is required before `waygraph chain auto <fromCheckpoint> <toCheckpoint>`
 builds a chain spec from the `waygraph auto` graph.
 
 ## Example

package/dist/cli.js

@@ -2686,9 +2686,9 @@ function initCommand(projectName) {
     console.log("  npm install");
     console.log("  npx playwright install chromium");
     console.log("  npm test");
-    console.log("  waygraph check .     # nav hygiene + orphan Blocks");
-    console.log("  waygraph auto .      # interactive explore (headful picker)");
-    console.log("  waygraph graph .     # static state graph JSON");
+    console.log("  waygraph check       # nav hygiene + orphan Blocks");
+    console.log("  waygraph auto        # interactive explore (headful picker)");
+    console.log("  waygraph graph       # static state graph JSON");
 }
 async function checkCommand(projectDir) {
     const files = discoverBlocks(projectDir);
@@ -2910,13 +2910,16 @@ Demo / step / autoplay (read this - agents get this wrong):
   an in-flight autoplay wait. Flags beat WAYGRAPH_* and reset the checkbox
   at process start (so --no-autoplay after a prior --autoplay session works).
 
-  Manual watch (default):     waygraph demo shopFlow .
-  Auto-advance watch:         waygraph demo shopFlow . --autoplay
-  Same overlay on a chain:    waygraph chain "login then nav-cart" . --step
-  Unattended (no overlay):    waygraph demo shopFlow . --no-step
+  Manual watch (default):     waygraph demo shopFlow
+  Auto-advance watch:         waygraph demo shopFlow --autoplay
+  Same overlay on a chain:    waygraph chain "login then nav-cart" --step
+  Unattended (no overlay):    waygraph demo shopFlow --no-step
   Onboarding (temp dir):      npx waygraph try demo
   Explore (temp dir):         npx waygraph try auto
 
+  Project path is optional - omit it to use the current directory.
+  You do not need a trailing "." (that is only shell shorthand for cwd).
+
 Other run flags (chain / demo / try) - flags beat WAYGRAPH_* env:
   --base-url <url>                base URL for relative page.goto()
   --title <text>                  persistent overlay banner title
@@ -2976,7 +2979,7 @@ Prefer flags (or npm scripts that pass them) over an ENV soup of WAYGRAPH_*.
     "chain auto" builds the spec from waygraph auto's graph (requires zero
     orphan Blocks - run waygraph check first):
 
-      waygraph chain auto LoggedIn OrderComplete .
+      waygraph chain auto LoggedIn OrderComplete
 
     A Block with no requires needs no payload. One with several required
     keys takes one JSON object keyed by each key's own name instead of a
@@ -3030,11 +3033,11 @@ Prefer flags (or npm scripts that pass them) over an ENV soup of WAYGRAPH_*.
   "project" defaults to the current directory.
 
 Examples:
-  waygraph demo shopFlow .
-  waygraph demo shopFlow . --autoplay --title "Shop demo"
-  waygraph demo loginFlow . --base-url https://www.saucedemo.com
-  waygraph chain "login then nav-cart" . --step --no-autoplay
-  npm run demo                  # scaffold: waygraph demo exampleFlow .
+  waygraph demo shopFlow
+  waygraph demo shopFlow --autoplay --title "Shop demo"
+  waygraph demo loginFlow --base-url https://www.saucedemo.com
+  waygraph chain "login then nav-cart" --step --no-autoplay
+  npm run demo                  # scaffold: waygraph demo exampleFlow
 `);
     process.exit(0);
 }
@@ -3099,7 +3102,7 @@ async function main() {
                 const toTag = flags.positionals[2];
                 if (!fromTag || !toTag) {
                     console.error("waygraph chain auto: missing <fromCheckpoint> <toCheckpoint> [project]");
-                    console.error('  e.g. waygraph chain auto LoggedIn OrderComplete .');
+                    console.error('  e.g. waygraph chain auto LoggedIn OrderComplete');
                     process.exit(1);
                 }
                 const proj = resolve(flags.positionals[3] ?? process.cwd());
@@ -3130,7 +3133,7 @@ async function main() {
             applyRunFlags(flags);
             const spec = flags.positionals[0];
             if (!spec) {
-                console.error('waygraph demo: missing <flow|spec>, e.g. waygraph demo shopFlow .\n' +
+                console.error('waygraph demo: missing <flow|spec>, e.g. waygraph demo shopFlow\n' +
                     "  Flags: --step/--no-step --autoplay/--no-autoplay --base-url <url> --title <text> --video [dir]");
                 process.exit(1);
             }
@@ -3174,7 +3177,7 @@ async function main() {
                     `${graph.skipped.length} Block(s) skipped (Out not resolvable), ` +
                     `${orphans.length} orphan Block(s)`);
                 if (orphans.length > 0) {
-                    console.error("waygraph graph: orphan Blocks block chain auto shorthand - wire each into a .flow.ts (waygraph check .)");
+                    console.error("waygraph graph: orphan Blocks block chain auto shorthand - wire each into a .flow.ts (waygraph check)");
                 }
                 break;
             }

package/dist/graph.js

@@ -98,7 +98,7 @@ export async function findOrphanBlocks(projectDir) {
             const exportName = m[1];
             if (referenced.has(exportName))
                 continue;
-            if (!/defineBlock|defineNavBlock/.test(src))
+            if (!/defineBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineMemNavBlock/.test(src))
                 continue;
             let block = exportNameToBlockName(exportName);
             try {
@@ -234,14 +234,17 @@ function resolveGenericArg(blockFilePath, arg) {
         return [inline[1]];
     return resolveTypeToTags(blockFilePath, arg);
 }
-/** Every `defineBlock<In, Out>(` call site in a file's own source, in order. */
+/** Every `defineBlock` / `defineEffectBlock` / `defineMemEffectBlock` `<In, Out>` call site. */
 function extractDefineBlockGenerics(src) {
     // Each argument is either a plain identifier or an inline `Checkpoint<...>`
-    // (its own angle brackets, so the outer defineBlock<...> pair alone won't
+    // (its own angle brackets, so the outer defineX<...> pair alone won't
     // balance correctly against a naive greedy match) - captured as a single
     // 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 `defineBlock<\s*${arg}\s*,\s*${arg}\s*>`, "g");
+    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 calls = [];
     let m;
     while ((m = re.exec(src)) !== null) {
@@ -301,7 +304,11 @@ export async function discoverGraph(projectDir) {
             }
             const call = calls[callIndex++];
             if (!call) {
-                skipped.push({ block: blockName, file: relFile, reason: "no defineBlock<In, Out> generic call found" });
+                skipped.push({
+                    block: blockName,
+                    file: relFile,
+                    reason: "no defineBlock/defineEffectBlock<In, Out> generic call found",
+                });
                 continue;
             }
             const fromTags = resolveGenericArg(file, call.in);

package/examples/saucedemo/docs/CONVENTION.md

@@ -63,10 +63,10 @@ src/states/
 src/flows/
 ```
 
-`waygraph check .` should report zero warnings - every navigation goes through
+`waygraph check` should report zero warnings - every navigation goes through
 a `defineNavBlock`, nothing else calls `page.goto`.
 
-`waygraph auto .` should discover Checkpoints as nodes and these Blocks as
+`waygraph auto` should discover Checkpoints as nodes and these Blocks as
 edges (including cycles via logout / continue-shopping / back-to-products).
 
 ## Friendly demo run (DX)
@@ -74,10 +74,10 @@ edges (including cycles via logout / continue-shopping / back-to-products).
 Prefer flags (or npm scripts) over a pile of `WAYGRAPH_*` env vars:
 
 ```bash
-npm run demo                 # waygraph demo shopFlow .  (STEP+headed; BASE_URL from package.json / playwright)
+npm run demo                 # waygraph demo shopFlow  (STEP+headed; BASE_URL from package.json / playwright)
 npm run demo:autoplay        # --autoplay --title "Shop demo"
-waygraph demo shopFlow . --base-url https://www.saucedemo.com --title "Shop"
-waygraph chain "loginFlow" . --step --no-autoplay
+waygraph demo shopFlow --base-url https://www.saucedemo.com --title "Shop"
+waygraph chain "loginFlow" --step --no-autoplay
 ```
 
 Flags beat env: `--step` / `--no-step`, `--autoplay` / `--no-autoplay`,

package/examples/saucedemo/package.json

@@ -7,19 +7,19 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
-    "flows": "waygraph list .",
-    "demo": "waygraph demo shopFlow .",
-    "demo:step": "waygraph demo shopFlow . --step --no-autoplay --title \"Shop demo\"",
-    "demo:autoplay": "waygraph demo shopFlow . --autoplay --title \"Shop demo\"",
-    "auto": "waygraph auto .",
-    "auto:cli": "waygraph auto . --cli",
-    "graph": "waygraph graph .",
-    "graph:mermaid": "waygraph graph . --mermaid",
+    "flows": "waygraph list",
+    "demo": "waygraph demo shopFlow",
+    "demo:step": "waygraph demo shopFlow --step --no-autoplay --title \"Shop demo\"",
+    "demo:autoplay": "waygraph demo shopFlow --autoplay --title \"Shop demo\"",
+    "auto": "waygraph auto",
+    "auto:cli": "waygraph auto --cli",
+    "graph": "waygraph graph",
+    "graph:mermaid": "waygraph graph --mermaid",
     "prove:login-branch": "node scripts/prove-wrong-login-runtime.mjs",
     "prove:graph": "node scripts/prove-auto-graph.mjs",
     "prove:add-to-cart-menu": "node scripts/prove-add-to-cart-menu.mjs",
     "prove": "npm run prove:login-branch && npm run prove:graph && npm run prove:add-to-cart-menu && npm test",
-    "record": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}})\" . --video --no-step"
+    "record": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}})\" --video --no-step"
   },
   "waygraph": {
     "baseUrl": "https://www.saucedemo.com"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.7.13",
+  "version": "0.7.15",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/quickstart/docs/CONVENTION.md

@@ -63,10 +63,10 @@ src/states/
 src/flows/
 ```
 
-`waygraph check .` should report zero warnings - every navigation goes through
+`waygraph check` should report zero warnings - every navigation goes through
 a `defineNavBlock`, nothing else calls `page.goto`.
 
-`waygraph auto .` should discover Checkpoints as nodes and these Blocks as
+`waygraph auto` should discover Checkpoints as nodes and these Blocks as
 edges (including cycles via logout / continue-shopping / back-to-products).
 
 ## Friendly demo run (DX)
@@ -74,10 +74,10 @@ edges (including cycles via logout / continue-shopping / back-to-products).
 Prefer flags (or npm scripts) over a pile of `WAYGRAPH_*` env vars:
 
 ```bash
-npm run demo                 # waygraph demo shopFlow .  (STEP+headed; BASE_URL from package.json / playwright)
+npm run demo                 # waygraph demo shopFlow  (STEP+headed; BASE_URL from package.json / playwright)
 npm run demo:autoplay        # --autoplay --title "Shop demo"
-waygraph demo shopFlow . --base-url https://www.saucedemo.com --title "Shop"
-waygraph chain "loginFlow" . --step --no-autoplay
+waygraph demo shopFlow --base-url https://www.saucedemo.com --title "Shop"
+waygraph chain "loginFlow" --step --no-autoplay
 ```
 
 Flags beat env: `--step` / `--no-step`, `--autoplay` / `--no-autoplay`,

package/templates/quickstart/package.json

@@ -6,20 +6,20 @@
   "scripts": {
     "test": "playwright test",
     "typecheck": "tsc --noEmit",
-    "check": "waygraph check .",
-    "auto": "waygraph auto .",
-    "auto:cli": "waygraph auto . --cli",
-    "graph": "waygraph graph .",
-    "graph:mermaid": "waygraph graph . --mermaid",
-    "demo": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" . --step --no-autoplay",
-    "demo:autoplay": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" . --step --autoplay",
-    "record": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" . --video --no-step"
+    "check": "waygraph check",
+    "auto": "waygraph auto",
+    "auto:cli": "waygraph auto --cli",
+    "graph": "waygraph graph",
+    "graph:mermaid": "waygraph graph --mermaid",
+    "demo": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --step --no-autoplay",
+    "demo:autoplay": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --step --autoplay",
+    "record": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --video --no-step"
   },
   "waygraph": {
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.7.13"
+    "waygraph": "^0.7.15"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/scaffold/package.json

@@ -6,11 +6,11 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
-    "flows": "waygraph list .",
-    "check": "waygraph check .",
-    "auto": "waygraph auto .",
-    "graph": "waygraph graph .",
-    "demo": "waygraph demo exampleFlow ."
+    "flows": "waygraph list",
+    "check": "waygraph check",
+    "auto": "waygraph auto",
+    "graph": "waygraph graph",
+    "demo": "waygraph demo exampleFlow"
   },
   "waygraph": {
     "baseUrl": "https://example.com"