waygraph 0.7.12 → 0.7.14

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
@@ -2952,13 +2955,12 @@ Prefer flags (or npm scripts that pass them) over an ENV soup of WAYGRAPH_*.
                                   a stateDiagram-v2 text export. Reports how
                                   many Blocks' Out couldn't be resolved
                                   (skipped, not crashed).
-  waygraph try [demo]             One-shot saucedemo onboarding - "npx waygraph
-                                  try demo" (bare "try" is the same). Copies
-                                  into an OS temp dir (never your cwd),
-                                  npm installs there, runs chainFlow(loginFlow,
-                                  shopFlow) in step mode (Episode 1 + 2,
-                                  manual Next by default), then npm test,
-                                  then prints the temp path + source files.
+  waygraph try [demo|auto]        One-shot saucedemo - "npx waygraph try demo"
+                                  (bare "try" = demo) or "npx waygraph try auto"
+                                  for the headed explorer. Copies into an OS
+                                  temp dir (never your cwd), npm installs there.
+                                  demo: chainFlow step-through then npm test.
+                                  auto: waygraph auto (Effect / MemNav picker).
                                   Permanent scaffold: waygraph init <name>
 
     "check" is a secondary sweep, complementary to the always-on TypeScript
@@ -2977,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
@@ -3031,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);
 }
@@ -3100,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());
@@ -3131,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);
             }
@@ -3175,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/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.12",
+  "version": "0.7.14",
   "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.12"
+    "waygraph": "^0.7.14"
   },
   "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"