waygraph 0.10.5 → 0.10.7

package/README.md

@@ -3,7 +3,7 @@
 A typed graph of reusable Blocks for driving a browser through E2E flows, in place of a
 flat pile of ad hoc helper functions.
 
-**Current:** `0.10.5` — CLI less-is-more (`auto` / `demo` / `run` + `.flow.ts` paths). Page hubs still as in 0.9.0.
+**Current:** `0.10.6` — `try auto` headed by default; `init` / create-waygraph scaffolds on 0.10 + `.flow.ts` scripts.
 
 This repo is the `waygraph` npm package itself. The full live **Sauce Demo** example
 (Page inventory hub, Effect Add/Remove, MemNav Open details, `waygraph auto`) ships

package/dist/cli.js

@@ -1286,10 +1286,12 @@ function extractVerifyHighlights(block, resultTag) {
  * __wgNext no-ops once already consumed - but looked live when it wasn't).
  * Disables the button and mem-key textareas, and swaps whichever gate
  * text was showing (manual button or "Auto-advancing...") to "Running...".
+ * When autoCollapsePanel is set (QA video / autoplay), tuck the stepper
+ * away so ring captions + the app fill the frame - Dan: stepper + auto panels.
  */
-async function markStepRunning(page) {
+async function markStepRunning(page, opts?: { autoCollapsePanel?: boolean }) {
   await page
-    .evaluate(() => {
+    .evaluate(({ autoCollapsePanel }) => {
       const runBtn = document.getElementById("wg-run");
       if (runBtn) {
         runBtn.disabled = true;
@@ -1300,7 +1302,15 @@ async function markStepRunning(page) {
       document.querySelectorAll("#wg-panel textarea[data-key]").forEach((ta) => {
         ta.disabled = true;
       });
-    })
+      if (autoCollapsePanel) {
+        const panel = document.getElementById("wg-panel");
+        if (panel) {
+          panel.classList.add("wg-collapsed");
+          const toggle = panel.querySelector("[data-wg-toggle]");
+          if (toggle) toggle.textContent = "Show";
+        }
+      }
+    }, { autoCollapsePanel: !!opts?.autoCollapsePanel })
     .catch(() => {});
 }
 
@@ -1815,7 +1825,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         }
       }
     }
-    await markStepRunning(page);
+    const recordingVideo = !!process.env.WAYGRAPH_VIDEO;
+    const autoCollapsePanel = recordingVideo || (await currentAutoplay());
+    await markStepRunning(page, { autoCollapsePanel });
     // NavBlock click-nav: label the upcoming Locator.click demo cursor as
     // "nav: <block>" so pia/demo watchers see cursor+pulse on click nav
     // (not only on regular Block clicks).
@@ -1997,6 +2009,18 @@ async function runChainedFlows(chainFlow, chainFlows, context, mem, page) {
   }
 }
 
+/** Parses WAYGRAPH_VIDEO_VIEWPORT / --video-viewport: "1920x1080" or "1920,1080". */
+function parseVideoViewport(raw: string | undefined): { width: number; height: number } | null {
+  if (!raw?.trim()) return null;
+  const m = raw.trim().match(/^(\d{3,5})[xX,](\d{3,5})$/);
+  if (!m) return null;
+  const width = Number(m[1]);
+  const height = Number(m[2]);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  if (width < 320 || height < 240 || width > 7680 || height > 4320) return null;
+  return { width, height };
+}
+
 async function main() {
   const projectDir = process.argv[2];
   const spec = process.argv[3];
@@ -2170,6 +2194,13 @@ async function main() {
     videoDir = videoEnv === "1" ? join(projectDir, ".waygraph-videos") : videoEnv;
     mkdirSync(videoDir, { recursive: true });
   }
+  /** Fixed 16:9 capture for --video (demo QA and headless run). Step+video no longer maximizes. */
+  const DEFAULT_VIDEO_VIEWPORT = { width: 1920, height: 1080 };
+  const DEFAULT_RUN_VIDEO_VIEWPORT = { width: 1280, height: 720 };
+  const videoViewportParsed = parseVideoViewport(process.env.WAYGRAPH_VIDEO_VIEWPORT);
+  const fixedVideoViewport = videoDir
+    ? (videoViewportParsed ?? (step ? DEFAULT_VIDEO_VIEWPORT : DEFAULT_RUN_VIDEO_VIEWPORT))
+    : null;
   const engine = new Engine({ headless: !headed, slowMo });
   let result;
   // Non-interactive execution (no --step) runs the whole chain as one
@@ -2200,14 +2231,20 @@ async function main() {
     const browser = await chromium.launch({
       headless: !headed,
       slowMo,
-      args: step ? ["--start-maximized"] : [],
+      // Maximized only for interactive step mode WITHOUT a fixed video viewport -
+      // recording uses a locked 16:9 viewport so .webm has no gray letterboxing.
+      args: step && !fixedVideoViewport ? ["--start-maximized"] : [],
       ...(executablePath ? { executablePath } : {}),
     });
-    const contextOpts = step
-      ? { baseURL, viewport: null }
-      : { baseURL, viewport: { width: 1280, height: 720 } };
+    const contextOpts = fixedVideoViewport
+      ? { baseURL, viewport: fixedVideoViewport }
+      : step
+        ? { baseURL, viewport: null }
+        : { baseURL, viewport: { width: 1280, height: 720 } };
     if (videoDir) {
-      contextOpts.recordVideo = { dir: videoDir };
+      contextOpts.recordVideo = fixedVideoViewport
+        ? { dir: videoDir, size: fixedVideoViewport }
+        : { dir: videoDir };
     }
     const context = await browser.newContext(contextOpts);
     let pageForVideo = null;
@@ -2557,26 +2594,27 @@ async function runTryDemo() {
 const TRY_AUTO_DATA = '{"saucedemo.credentials":{"username":"standard_user","password":"secret_sauce"}}';
 /**
  * `waygraph try auto` / `try auto:cli` - temp Sauce Demo explore.
- * Default is CLI menu (same as `npm run auto:cli`). Pass `--headed` for the browser panel.
+ * Default is the **headed** browser panel. Pass `auto:cli` or `--cli` for the
+ * terminal menu (same rows).
  *
  * Runs as a child in the temp project so Block imports share that install's
  * `@playwright/test`. In-process explore from the outer CLI against a packed
  * `file:*.tgz` copy double-loads Playwright and silently yields 0 graph edges
  * ("LoginPage / No moves").
  */
-async function runTryAuto(opts = { cli: true }) {
+async function runTryAuto(opts = { cli: false }) {
     const destDir = await prepareTryQuickstart("waygraph-try-auto");
     if (!destDir)
         return;
     process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
-    const cli = opts.cli !== false;
+    const cli = opts.cli === true;
     console.log(cli
         ? "waygraph try auto: CLI explore on Sauce Demo (temp dir).\n" +
             "  Creds pre-seeded (saucedemo.credentials).\n" +
             "  Pick [1] submit-login, then inventory Add/Remove / Open details.\n" +
-            "  Type q to quit. Headed panel: waygraph try auto --headed\n"
+            "  Type q to quit. Headed panel: waygraph try auto\n"
         : "waygraph try auto: headed explore on Sauce Demo (temp dir).\n" +
-            "  Creds pre-seeded. Prefer CLI: waygraph try auto:cli\n" +
+            "  Creds pre-seeded. CLI menu: waygraph try auto:cli\n" +
             "  Pick submit-login, then inventory menus. Quit from the panel.\n");
     const bin = join(destDir, "node_modules", ".bin", "waygraph");
     const args = ["auto"];
@@ -2589,8 +2627,8 @@ async function runTryAuto(opts = { cli: true }) {
     console.log("\nwaygraph try auto: explorer closed.\n\n" +
         `Temp project:\n  ${destDir}\n\n` +
         "Run again:\n" +
-        `  cd ${destDir} && npm run auto:cli\n` +
-        `  cd ${destDir} && npm run auto\n\n` +
+        `  cd ${destDir} && npm run auto\n` +
+        `  cd ${destDir} && npm run auto:cli\n\n` +
         "In-package: examples/saucedemo\n" +
         "Docs: https://deviate-dv8.github.io/waygraph/auto.html\n");
 }
@@ -2692,6 +2730,7 @@ function initCommand(projectName) {
         process.exit(1);
     }
     const targetDir = resolve(process.cwd(), projectName);
+    const pkgName = basename(targetDir);
     if (existsSync(targetDir)) {
         const entries = readdirSync(targetDir);
         if (entries.length > 0) {
@@ -2714,15 +2753,18 @@ function initCommand(projectName) {
         rmSync(gitignoreSrc);
     }
     const packageJsonPath = join(targetDir, "package.json");
-    writeFileSync(packageJsonPath, readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", projectName));
-    console.log(`Scaffolded ${projectName}/`);
+    writeFileSync(packageJsonPath, readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
+    console.log(`Scaffolded ${pkgName}/`);
     console.log("");
-    console.log(`  cd ${projectName}`);
+    console.log(`  cd ${relative(process.cwd(), targetDir) || pkgName}`);
     console.log("  npm install");
     console.log("  npx playwright install chromium");
     console.log("  npm test");
+    console.log("  waygraph list        # .flow.ts → export map");
     console.log("  waygraph check       # nav hygiene + orphan Blocks");
-    console.log("  waygraph auto        # interactive explore (headful picker)");
+    console.log("  waygraph auto        # interactive explore (headed panel)");
+    console.log("  waygraph auto --cli  # same menus in the terminal");
+    console.log("  waygraph demo src/flows/example.flow.ts");
     console.log("  waygraph graph       # static state graph JSON");
 }
 async function checkCommand(projectDir) {
@@ -2843,6 +2885,11 @@ function parseRunFlags(argv) {
                 }
             }
         }
+        else if (a === "--video-viewport" || a.startsWith("--video-viewport=")) {
+            const t = takeFlagValue(argv, i, a, "--video-viewport");
+            out.videoViewport = t.value;
+            i = t.nextI;
+        }
         else if (a === "--blocks" || a.startsWith("--blocks=")) {
             if (a.startsWith("--blocks=")) {
                 out.blocks = a.slice("--blocks=".length);
@@ -2869,6 +2916,21 @@ function parseRunFlags(argv) {
     }
     return out;
 }
+/** Parses WAYGRAPH_VIDEO_VIEWPORT / --video-viewport: "1920x1080" or "1920,1080". */
+function parseVideoViewportFlag(raw) {
+    if (!raw?.trim())
+        return null;
+    const m = raw.trim().match(/^(\d{3,5})[xX,](\d{3,5})$/);
+    if (!m)
+        return null;
+    const width = Number(m[1]);
+    const height = Number(m[2]);
+    if (!Number.isFinite(width) || !Number.isFinite(height))
+        return null;
+    if (width < 320 || height < 240 || width > 7680 || height > 4320)
+        return null;
+    return { width, height };
+}
 /** Writes flag values into process.env so the chain child inherits them. Flags beat prior env. */
 function applyRunFlags(flags, opts) {
     if (flags.autoPlayVideo) {
@@ -2908,6 +2970,13 @@ function applyRunFlags(flags, opts) {
     if (flags.video !== undefined) {
         process.env.WAYGRAPH_VIDEO = flags.video || "1";
     }
+    if (flags.videoViewport !== undefined) {
+        if (!parseVideoViewportFlag(flags.videoViewport)) {
+            console.error('waygraph: --video-viewport must look like "1920x1080"');
+            process.exit(1);
+        }
+        process.env.WAYGRAPH_VIDEO_VIEWPORT = flags.videoViewport;
+    }
     if (flags.data !== undefined) {
         process.env.WAYGRAPH_DATA = flags.data;
     }
@@ -3067,22 +3136,27 @@ Primary (less is more):
                  --data '{...}'            Mem seed JSON (or inline flow({...}))
                  --auto-next               Auto-advance steps (alias: --autoplay)
                  --auto-play-video         QA: --auto-next + --video (+ step)
+                 --video-viewport WxH       Recording size (default demo: 1920x1080)
                  --title / --base-url
   waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)
                  --data '{...}'
                  --non-headless            Show browser
                  --video [dir]             Record .webm
+                 --video-viewport WxH       Recording size (default run: 1280x720)
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
-                 try auto --headed         Browser panel instead of CLI
+                 try auto                  Headed browser panel (default)
+                 try auto:cli / --cli      Terminal menu instead
+                 try auto --headed         Same as try auto (compat)
 
 Examples:
   waygraph list                                          # file → export map
   waygraph run src/flows/shop.flow.ts --data '{...}'
   waygraph run --blocks shopFlow --non-headless --video
   waygraph demo --blocks src/flows/cart-bulk.flow.ts --auto-next
+  waygraph try auto
   waygraph try auto:cli
   waygraph auto src/flows/shop.flow.ts --data '{...}'   # run by file (same as run)
   waygraph auto --cli --data '{"saucedemo.credentials":{...}}'
@@ -3310,19 +3384,18 @@ async function main() {
             const flags = parseRunFlags(args.slice(1));
             applyRunFlags(flags);
             const modeRaw = (flags.positionals[0] ?? "demo").toLowerCase();
-            // auto:cli / auto-cli = CLI explore; auto --headed = browser panel; auto = CLI default
+            // auto:cli / --cli = CLI; bare try auto = headed panel
             const mode = modeRaw === "auto:cli" || modeRaw === "auto-cli"
                 ? "auto:cli"
                 : modeRaw === "auto"
                     ? "auto"
                     : modeRaw;
             if (mode === "auto" || mode === "auto:cli") {
-                // CLI is the default for try auto (same menus as headed). --headed = panel.
                 const cli = mode === "auto:cli" || flags.cli === true
                     ? true
                     : flags.headed === true || flags.nonHeadless === true
                         ? false
-                        : true;
+                        : false; // try auto default = headed
                 await runTryAuto({ cli });
             }
             else if (mode === "demo" || mode === "") {

package/package.json

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

package/templates/quickstart/package.json

@@ -23,7 +23,7 @@
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.10.5"
+    "waygraph": "^0.10.6"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/scaffold/package.json

@@ -6,17 +6,19 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
-    "flows": "waygraph list",
+    "list": "waygraph list",
     "check": "waygraph check",
     "auto": "waygraph auto",
-    "graph": "waygraph graph",
-    "demo": "waygraph demo exampleFlow"
+    "auto:cli": "waygraph auto --cli",
+    "demo": "waygraph demo src/flows/example.flow.ts",
+    "run": "waygraph run src/flows/example.flow.ts",
+    "graph": "waygraph graph"
   },
   "waygraph": {
     "baseUrl": "https://example.com"
   },
   "dependencies": {
-    "waygraph": "^0.9.0"
+    "waygraph": "^0.10.6"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",