waygraph 0.15.50 → 0.15.52

package/dist/analysis/graph.d.ts

@@ -13,7 +13,7 @@ export interface WaygraphEdge {
     block: string;
     /** Path the Block was discovered in, relative to the project root. */
     file: string;
-    /** `"*"` for a NavBlock - reachable from anywhere, by design. */
+    /** `"*"` for a NavBlock - reachable from anywhere, unless it declares `from` (then one edge per tag). */
     from: string;
     to: string;
     kind: "nav" | "action";

package/dist/analysis/graph.js

@@ -53,21 +53,10 @@ function discoverBlocks(projectDir) {
 function discoverFlows(projectDir) {
     return walkDir(projectDir, /\.flow\.ts$/);
 }
-/** Block export ids listed inside any `defineFlow([...])` array in flow files. */
+/** Block export ids a flow file uses: every identifier outside its import lines (a Block can sit in the array or in a local like `const AddShown = AddBlock.stubAfter(...)`). */
 function extractFlowBlockRefs(flowSrc) {
-    const refs = [];
-    const re = /defineFlow(?:<[\s\S]*?>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/g;
-    let m;
-    while ((m = re.exec(flowSrc)) !== null) {
-        for (const part of m[1].split(",")) {
-            const trimmed = part.trim().replace(/\/\/.*$/, "").trim();
-            const id = trimmed.split(/\s+/)[0];
-            if (!id || id === "start" || id === "end")
-                continue;
-            refs.push(id);
-        }
-    }
-    return refs;
+    const body = flowSrc.replace(/^\s*import[\s\S]*?;\s*$/gm, "").replace(/\/\/.*$/gm, "");
+    return body.match(/[A-Za-z_$][\w$]*/g) ?? [];
 }
 function exportNameToBlockName(exportName) {
     const base = exportName.replace(/Block$/, "");
@@ -420,7 +409,13 @@ export async function discoverGraph(projectDir, opts) {
                         const deepLink = !isPage ||
                             exported.__waygraphPageDeepLink === true;
                         if (deepLink) {
-                            edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                            // `from: [...]` on the Nav = only those Checkpoints; otherwise reachable from anywhere.
+                            const navFrom = exported.__waygraphNavFrom;
+                            for (const from of navFrom ?? ["*"]) {
+                                if (from !== "*")
+                                    nodeTags.add(from);
+                                edges.push({ block: blockName, file: relFile, from, to, kind: "nav" });
+                            }
                         }
                     }
                     catch {

package/dist/analysis/map-check.js

@@ -117,12 +117,15 @@ export async function checkMap(projectDir) {
                 continue; // only statically-urled Nav/Page Blocks are checkable
             let pathname;
             try {
-                pathname = new URL(navUrl).pathname;
+                // Relative URLs (the normal baseUrl case) are paths from the app root.
+                pathname = new URL(navUrl, "http://app.invalid/").pathname;
             }
             catch {
-                continue; // a relative/templated URL - not verbatim-checkable
+                continue;
             }
             const urlSegments = pathname.split("/").filter(Boolean);
+            if (urlSegments.at(-1) === "index.html")
+                urlSegments.pop(); // /docs/index.html is the docs/ folder
             const folderSegments = realSegments(relative(mapRoot, file));
             const matches = urlSegments.length === folderSegments.length && urlSegments.every((s, i) => s === folderSegments[i]);
             if (!matches) {

package/dist/analysis/practices-check.d.ts

@@ -11,4 +11,3 @@ export interface PracticeCheckOptions {
 }
 export declare function collectPracticeWarnings(projectDir: string, walkDir: (dir: string, re: RegExp) => string[], opts?: PracticeCheckOptions): PracticeWarning[];
 export declare function practiceKindLabel(kind: PracticeKind): string;
-export declare function formatPracticeWarnings(projectDir: string, warnings: PracticeWarning[]): string[];

package/dist/analysis/practices-check.js

@@ -5,8 +5,20 @@
  */
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, relative } from "node:path";
-/** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
-const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
+/** Every define*Block<In, Out> / <Out> generic list - args may themselves be Checkpoint<...>. */
+const BLOCK_GENERICS = /\bdefine(?:Method|Effect|MemEffect|Page|Nav|MemNav|NavClick|Action)Block\s*<\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*(?:,\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*)?>/g;
+/**
+ * A wildcard Out (the Block's result is untyped). A wildcard In is fine - it's the documented
+ * "reachable from anywhere" form (graph.ts treats it like a NavBlock's "*").
+ */
+function hasWildcardOut(src) {
+    for (const m of src.matchAll(BLOCK_GENERICS)) {
+        const out = (m[2] ?? m[1]).trim();
+        if (/^Checkpoint\s*<\s*string\s*>$/.test(out))
+            return true;
+    }
+    return false;
+}
 /** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
 const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
 /** defineAssertBlock, any form - used to scope the empty-verify check below. */
@@ -74,11 +86,12 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
         const rel = relative(projectDir, file).replace(/\\/g, "/");
         const src = readFileSync(file, "utf-8");
         const ignore = ignoredKindsForFile(src);
-        if (!isIgnored("wildcard-checkpoint", ignore) && WILDCARD_CHECKPOINT.test(src)) {
+        if (!isIgnored("wildcard-checkpoint", ignore) && hasWildcardOut(src)) {
             warnings.push({
                 kind: "wildcard-checkpoint",
                 file: rel,
-                detail: 'uses Checkpoint<string> in a Block helper generic — prefer a typed Checkpoint from src/states/ (e.g. defineMethodBlock<LoginPage, LoginPage>)',
+                detail: "the Block's output is Checkpoint<string>, so its result is untyped — use a typed Checkpoint from " +
+                    "src/states/ (e.g. defineMethodBlock<LoginPage, LoggedIn>); a wildcard input is fine",
             });
         }
         if (!isIgnored("assert-no-type-arg", ignore) && ASSERT_NO_TYPE_ARG.test(src)) {
@@ -180,16 +193,3 @@ export function practiceKindLabel(kind) {
         }
     }
 }
-export function formatPracticeWarnings(projectDir, warnings) {
-    const lines = [];
-    for (const w of warnings) {
-        lines.push(`waygraph practices: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
-    }
-    if (warnings.length === 0) {
-        lines.push(`waygraph practices: no bad-practice patterns under ${projectDir}`);
-    }
-    else {
-        lines.push(`waygraph practices: ${warnings.length} bad-practice warning${warnings.length === 1 ? "" : "s"}`);
-    }
-    return lines;
-}

package/dist/auto-session/session.d.ts

@@ -16,7 +16,7 @@ export declare class AutoSession {
     private library;
     private readonly mem;
     private readonly engine;
-    private readonly browser;
+    private readonly closeBrowser;
     private readonly context;
     private page;
     private readonly startUrl;

package/dist/auto-session/session.js

@@ -9,6 +9,8 @@ import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from
 import { runStubPhase } from "../highlights.js";
 import { verboseLog } from "./verbose-log.js";
 import { findBlockPathDetailed } from "../analysis/graph.js";
+import { configuredExtensions } from "../config.js";
+import { chromiumExecutablePath, launchContext } from "../browser.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
  * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
@@ -25,7 +27,7 @@ export class AutoSession {
     library;
     mem;
     engine;
-    browser;
+    closeBrowser;
     context;
     page;
     startUrl;
@@ -37,7 +39,7 @@ export class AutoSession {
     knownInteractionSelectors;
     headless;
     lastOverlayInfo = null;
-    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
+    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
         this.projectDir = projectDir;
         this.inject = inject;
         this.blocksSelect = blocksSelect;
@@ -45,7 +47,7 @@ export class AutoSession {
         this.library = library;
         this.mem = mem;
         this.engine = engine;
-        this.browser = browser;
+        this.closeBrowser = closeBrowser;
         this.context = context;
         this.page = page;
         this.startUrl = startUrl;
@@ -67,7 +69,7 @@ export class AutoSession {
         const headless = init.headless ?? true;
         const engine = new Engine({ headless });
         const { chromium } = await import("@playwright/test");
-        const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+        const executablePath = chromiumExecutablePath();
         // Real gap found live: a headed (--non-headless) session kept a fixed
         // 1280x720 content area even when the user maximized/fullscreened the
         // actual window - `viewport: null` alone only makes the PAGE track the
@@ -84,13 +86,17 @@ export class AutoSession {
         };
         if (executablePath)
             launchOpts.executablePath = executablePath;
-        const browser = await chromium.launch(launchOpts);
         const contextOpts = {
             viewport: headless ? { width: 1280, height: 720 } : null,
         };
         if (baseURL)
             contextOpts.baseURL = baseURL;
-        const context = await browser.newContext(contextOpts);
+        const { close: closeBrowser, context } = await launchContext({
+            launcher: chromium,
+            launch: launchOpts,
+            context: contextOpts,
+            extensions: await configuredExtensions(init.projectDir),
+        });
         await installPersistentPilotOverlay(context);
         const page = await context.newPage();
         instrumentPilotActions(page, headless ? 0 : 450);
@@ -102,7 +108,7 @@ export class AutoSession {
             await page.goto("about:blank").catch(() => { });
         }
         const knownInteractionSelectors = collectKnownInteractionSelectors(init.projectDir, library, init.inject);
-        const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
+        const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
         page.on("load", () => {
             void session.repaintOverlayAfterNavigation();
         });
@@ -708,6 +714,6 @@ export class AutoSession {
     }
     async close() {
         await this.context.close();
-        await this.browser.close();
+        await this.closeBrowser();
     }
 }

package/dist/blocks-select.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Shared `--blocks` select grammar (RFC Phase C).
+ *
+ * - `/pattern/`  -> regex on relative file path OR block name
+ * - has `*`/`**` -> glob on relative file path (POSIX-ish)
+ * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
+ */
 export type BlocksSelectKind = "regex" | "glob" | "bare";
 export interface BlocksSelect {
     kind: BlocksSelectKind;
@@ -16,7 +23,3 @@ export declare function matchBlocksSelect(select: BlocksSelect, opts: {
     relFile: string;
     blockName?: string;
 }): boolean;
-export declare function filterByBlocksSelect<T extends {
-    file: string;
-    block?: string;
-}>(items: T[], select: BlocksSelect | undefined, projectDir: string): T[];

package/dist/blocks-select.js

@@ -5,7 +5,6 @@
  * - has `*`/`**` -> glob on relative file path (POSIX-ish)
  * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
  */
-import { relative } from "node:path";
 /** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
 export function isFileSelectToken(token) {
     if (!token)
@@ -70,16 +69,3 @@ export function matchBlocksSelect(select, opts) {
         return true;
     return false;
 }
-export function filterByBlocksSelect(items, select, projectDir) {
-    if (!select)
-        return items;
-    return items.filter((it) => {
-        const relFile = it.file.startsWith(projectDir)
-            ? relative(projectDir, it.file)
-            : it.file;
-        return matchBlocksSelect(select, {
-            relFile: relFile.replace(/\\/g, "/"),
-            ...(it.block !== undefined ? { blockName: it.block } : {}),
-        });
-    });
-}

package/dist/browser.d.ts

@@ -0,0 +1,27 @@
+import type { Browser, BrowserContext, BrowserContextOptions, BrowserType, LaunchOptions } from "@playwright/test";
+/**
+ * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
+ * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
+ */
+export declare function chromiumExecutablePath(): string | undefined;
+/** Unpacked extension directories, as resolved by `resolveExtensions` - also what `WAYGRAPH_EXTENSIONS` carries to child processes. */
+export declare function extensionPathsFromEnv(): string[];
+export interface LaunchedContext {
+    /** Null for a persistent (extension) context. */
+    browser: Browser | null;
+    context: BrowserContext;
+    /** Closes the context and the browser (and the throwaway profile when extensions are loaded). */
+    close(): Promise<void>;
+}
+/**
+ * Launches a browser and its first context. With `extensions` it uses a persistent context, the only
+ * way Chromium loads extensions: new headless (`channel: "chromium"`; the default headless shell
+ * ignores them) and Playwright's own Chromium (branded Chrome 137+ ignores `--load-extension`).
+ * Extensions are not active in extra contexts made with `browser.newContext()`.
+ */
+export declare function launchContext(opts: {
+    launcher: BrowserType;
+    launch: LaunchOptions;
+    context?: BrowserContextOptions;
+    extensions?: readonly string[];
+}): Promise<LaunchedContext>;

package/dist/browser.js

@@ -0,0 +1,62 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+let warned = false;
+/**
+ * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
+ * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
+ */
+export function chromiumExecutablePath() {
+    const path = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    if (!path)
+        return undefined;
+    if (existsSync(path))
+        return path;
+    if (!warned) {
+        warned = true;
+        console.error(`waygraph: CHROME_PATH/CHROMIUM_PATH "${path}" does not exist - using Playwright's bundled Chromium`);
+    }
+    return undefined;
+}
+/** Unpacked extension directories, as resolved by `resolveExtensions` - also what `WAYGRAPH_EXTENSIONS` carries to child processes. */
+export function extensionPathsFromEnv() {
+    return (process.env.WAYGRAPH_EXTENSIONS ?? "").split(",").filter(Boolean);
+}
+/**
+ * Launches a browser and its first context. With `extensions` it uses a persistent context, the only
+ * way Chromium loads extensions: new headless (`channel: "chromium"`; the default headless shell
+ * ignores them) and Playwright's own Chromium (branded Chrome 137+ ignores `--load-extension`).
+ * Extensions are not active in extra contexts made with `browser.newContext()`.
+ */
+export async function launchContext(opts) {
+    const extensions = opts.extensions ?? [];
+    if (extensions.length === 0) {
+        const browser = await opts.launcher.launch(opts.launch);
+        const context = await browser.newContext(opts.context);
+        return { browser, context, close: () => browser.close() };
+    }
+    if (opts.launcher.name() !== "chromium")
+        throw new Error("waygraph: extensions only work in Chromium");
+    const list = extensions.join(",");
+    const { executablePath: _ignored, ...launch } = opts.launch;
+    const profile = mkdtempSync(join(tmpdir(), "waygraph-profile-"));
+    const context = await opts.launcher.launchPersistentContext(profile, {
+        ...launch,
+        ...opts.context,
+        ...(launch.headless === false ? {} : { channel: "chromium" }),
+        args: [...(launch.args ?? []), `--disable-extensions-except=${list}`, `--load-extension=${list}`],
+    });
+    // An extension's background worker registers its page hooks, so wait for it before the first navigation.
+    const hasWorker = extensions.some((dir) => JSON.parse(readFileSync(join(dir, "manifest.json"), "utf-8")).background?.service_worker !== undefined);
+    if (hasWorker && context.serviceWorkers().length === 0) {
+        await context.waitForEvent("serviceworker", { timeout: 10_000 }).catch(() => undefined);
+    }
+    return {
+        browser: context.browser(),
+        context,
+        close: async () => {
+            await context.close();
+            rmSync(profile, { recursive: true, force: true });
+        },
+    };
+}

package/dist/cli/run-chain.js

@@ -1,4 +1,5 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { configuredExtensions } from "../config.js";
 import { expandSpecFlowFiles, resolveBaseUrl } from "./flags.js";
 import { join } from "node:path";
 import { rmSync, writeFileSync } from "node:fs";
@@ -45,10 +46,14 @@ export async function runChain(projectDir, spec) {
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
+    const extensions = await configuredExtensions(projectDir);
+    if (extensions.length > 0)
+        process.env.WAYGRAPH_EXTENSIONS = extensions.join(",");
     const tsxEsm = import.meta.resolve("tsx/esm");
     const scriptPath = join(projectDir, `.waygraph-chain-${process.pid}.mjs`);
     writeFileSync(scriptPath, CHAIN_RUNNER_BOOTSTRAP);
     try {
+        // webServer is started inside the child (runner/main.js), never here - see CHAIN_RUNNER_BOOTSTRAP.
         const code = await new Promise((res, rej) => {
             const child = spawn(process.execPath, ["--import", tsxEsm, scriptPath, projectDir, expanded], {
                 stdio: "inherit",

package/dist/cli/usage.js

@@ -156,7 +156,9 @@ Primary (less is more):
                  --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
                  --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless
                  --auto-play-video-head    Same, but keep the browser visible (--non-headless)
-                 --video [dir]             Record .webm (demo: headless unless --non-headless)
+                 --video [dir]             Record .webm (demo: headless unless --non-headless);
+                                           default folder ~/Downloads/waygraph-videos/<project>,
+                                           or video.dir in the config / WAYGRAPH_VIDEO_DIR
                  --video-viewport WxH       Recording size (default demo: 1920x1080)
                  --title / --base-url
   waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)
@@ -184,6 +186,17 @@ Primary (less is more):
                                            has a trace - test report opens it.
 
 Also:
+  --env <mode>   (any command) load .env.<mode> / .env.<mode>.local on top of .env, e.g.
+                 waygraph test --env staging   (default: NODE_ENV, else development)
+  waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff]
+                                           Compare a project with the scaffold in this waygraph:
+                                           lists new and differing files and a stale waygraph
+                                           dependency. Dry run unless --apply; only the paths you
+                                           name are copied, differing files only with --overwrite.
+  waygraph extensions install [project] [--update]
+                                           Download the browser extensions listed in
+                                           waygraph.config.* (extensions: ["hoppscotch"]) into
+                                           the user cache; runs also fetch them on first use.
   waygraph list | nav | validate | check | typecheck | graph | init <name>
                  check/typecheck --no-practices  Skip bad-practice warnings
   waygraph map   [project]                 Waygraph Map convention enforcement: every static

package/dist/cli.js

@@ -15,6 +15,7 @@
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */
 import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./commands/agent-dive-scaffold.js";
+import { takeEnvFlag } from "./env-file.js";
 import { usage } from "./cli/usage.js";
 import { listCase, navCase } from "./commands/list.js";
 import { checkCase, typecheckCase, validateCase } from "./commands/check.js";
@@ -25,8 +26,10 @@ import { traverseCase } from "./commands/traverse.js";
 import { agentDiveCase } from "./commands/agent-dive.js";
 import { autoServeCase, sessionCase } from "./commands/session.js";
 import { tryCase } from "./commands/try.js";
+import { upgradeCase } from "./commands/upgrade.js";
+import { extensionsCase } from "./commands/extensions.js";
 import { mapCase } from "./commands/map.js";
-const args = process.argv.slice(2);
+const args = takeEnvFlag(process.argv.slice(2));
 const command = args[0];
 async function main() {
     if (!command || command === "--help" || command === "-h") {
@@ -97,6 +100,12 @@ async function main() {
         case "map":
             await mapCase(args);
             break;
+        case "upgrade":
+            await upgradeCase(args);
+            break;
+        case "extensions":
+            await extensionsCase(args);
+            break;
         default:
             console.error(`waygraph: unknown command "${command}"`);
             process.exit(1);

package/dist/commands/agent-dive-scaffold.d.ts

@@ -28,6 +28,11 @@ export declare const SKILL_FLAG_MAP: {
 export type SkillFlag = keyof typeof SKILL_FLAG_MAP;
 /** Raw skill markdown (frontmatter + body), as shipped in the package. */
 export declare function readSkillMarkdown(stem: string): string;
+/** Every packaged skill as `.agents/skills/<name>/SKILL.md` (relative path + markdown), the cross-agent skills folder. */
+export declare function agentSkillFiles(): {
+    rel: string;
+    text: string;
+}[];
 /** Print `--skill` index (available flags + one-line descriptions). */
 export declare function printSkillIndex(): void;
 export interface AgentDiveOptions {

package/dist/commands/agent-dive-scaffold.js

@@ -100,6 +100,13 @@ export function readSkillMarkdown(stem) {
     const raw = readFileSync(path, "utf-8");
     return raw.endsWith("\n") ? raw : raw + "\n";
 }
+/** Every packaged skill as `.agents/skills/<name>/SKILL.md` (relative path + markdown), the cross-agent skills folder. */
+export function agentSkillFiles() {
+    return Object.values(SKILL_FLAG_MAP).map((stem) => ({
+        rel: join(".agents", "skills", stem, "SKILL.md"),
+        text: readSkillMarkdown(stem),
+    }));
+}
 /** Print `--skill` index (available flags + one-line descriptions). */
 export function printSkillIndex() {
     const skills = loadSkillSpecs();

package/dist/commands/extensions.d.ts

@@ -0,0 +1 @@
+export declare function extensionsCase(args: string[]): Promise<void>;

package/dist/commands/extensions.js

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+import { loadWaygraphConfig } from "../config.js";
+import { extensionInfo, resolveExtension } from "../extensions.js";
+export async function extensionsCase(args) {
+    const update = args.includes("--update");
+    const rest = args.slice(2).filter((a) => a !== "--update");
+    if (args[1] !== "install") {
+        console.error("usage: waygraph extensions install [project] [--update]");
+        process.exit(1);
+    }
+    const proj = resolve(rest[0] ?? process.cwd());
+    const specs = (await loadWaygraphConfig(proj))?.extensions ?? [];
+    if (specs.length === 0) {
+        console.log("waygraph extensions: no `extensions` in waygraph.config.* - nothing to install");
+        return;
+    }
+    for (const spec of specs) {
+        const dir = await resolveExtension(spec, proj, { update });
+        const { name, version } = extensionInfo(dir);
+        console.log(`waygraph extensions: ${name} ${version} -> ${dir}`);
+    }
+}

package/dist/commands/init.js

@@ -1,7 +1,34 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { packageRoot } from "../cli/util.js";
-import { basename, join, relative, resolve } from "node:path";
+import { agentSkillFiles } from "./agent-dive-scaffold.js";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+/**
+ * Running from a checkout (not an installed package), npm doesn't have this build's code, so a plain `^version` would install an
+ * older waygraph and break the scaffold's types. Pack this checkout into the project and depend on that file instead.
+ */
+function packLocalBuild(targetDir) {
+    const root = packageRoot();
+    if (root.split(sep).includes("node_modules"))
+        return undefined;
+    const dir = join(targetDir, ".waygraph-local");
+    mkdirSync(dir, { recursive: true });
+    const packed = spawnSync("npm", ["pack", "--pack-destination", dir, "--silent"], {
+        cwd: root,
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+    });
+    const file = packed.stdout?.trim().split("\n").pop();
+    if (packed.status !== 0 || !file) {
+        console.error("waygraph init: could not pack this checkout; the project will depend on the published waygraph");
+        rmSync(dir, { recursive: true, force: true });
+        return undefined;
+    }
+    writeFileSync(join(targetDir, ".gitignore"), readFileSync(join(targetDir, ".gitignore"), "utf-8") + ".waygraph-local/\n");
+    return `file:.waygraph-local/${file}`;
+}
 function initCommand(projectName) {
     if (!projectName) {
         console.error("waygraph init: missing <project-name>, e.g. waygraph init my-app");
@@ -30,8 +57,23 @@ function initCommand(projectName) {
         writeFileSync(join(targetDir, ".gitignore"), readFileSync(gitignoreSrc, "utf-8"));
         rmSync(gitignoreSrc);
     }
+    // Demo pages open via file://; the absolute path is only known once copied, so it's filled in here.
+    const appBaseUrl = pathToFileURL(join(targetDir, "src", "map", "(app_base)", "index.html")).href;
     const packageJsonPath = join(targetDir, "package.json");
-    writeFileSync(packageJsonPath, readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
+    // Pin the project to the waygraph that created it - a stale range here installs an old engine.
+    const ownVersion = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf-8")).version;
+    const local = packLocalBuild(targetDir);
+    pkg.dependencies.waygraph = local ?? `^${ownVersion}`;
+    if (local)
+        console.log(`(running from a waygraph checkout: depending on its local build, ${local})`);
+    writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+    const configPath = join(targetDir, "config", "waygraph.config.ts");
+    writeFileSync(configPath, readFileSync(configPath, "utf-8").replaceAll("__APP_BASE_URL__", appBaseUrl));
+    for (const { rel, text } of agentSkillFiles()) {
+        mkdirSync(dirname(join(targetDir, rel)), { recursive: true });
+        writeFileSync(join(targetDir, rel), text);
+    }
     console.log(`Scaffolded ${pkgName}/`);
     console.log("");
     console.log(`  cd ${relative(process.cwd(), targetDir) || pkgName}`);
@@ -45,6 +87,7 @@ function initCommand(projectName) {
     console.log("  waygraph auto --cli  # same menus in the terminal");
     console.log("  waygraph demo --blocks exampleFlow");
     console.log("  waygraph graph       # static state graph JSON");
+    console.log("  .agents/skills/      # waygraph skills for coding agents (waygraph agent-dive adds agent personas)");
     console.log("");
     console.log("  Layout: see STRUCTURE.md (or https://deviate-dv8.github.io/waygraph/scaffold.html)");
 }

package/dist/commands/test.js

@@ -1,7 +1,9 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { configuredExtensions } from "../config.js";
 import { runInherited } from "../cli/util.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
+import { packageRoot } from "../cli/util.js";
 export async function testCase(args) {
     const rest = args.slice(1);
     const proj = process.cwd();
@@ -23,11 +25,23 @@ export async function testCase(args) {
         process.exitCode = await runPw(["show-trace", ...rest.slice(1)]);
         return;
     }
+    const extensions = await configuredExtensions(proj);
+    if (extensions.length > 0)
+        process.env.WAYGRAPH_EXTENSIONS = extensions.join(",");
+    // No playwright.config in the project: waygraph builds one from config/waygraph.config.ts.
+    const hasOwnConfig = ["ts", "mts", "js", "mjs", "cjs"].some((e) => existsSync(join(proj, `playwright.config.${e}`)));
+    if (hasOwnConfig) {
+        console.error("waygraph: playwright.config is deprecated - move its settings into config/waygraph.config.ts");
+    }
+    else {
+        process.env.WAYGRAPH_PROJECT_DIR = proj;
+    }
+    const configArgs = hasOwnConfig ? [] : ["-c", join(packageRoot(), "dist", "playwright.config.js")];
     const wantsUi = rest[0] === "ui" || rest.includes("--ui");
     const forwarded = rest[0] === "ui" ? rest.slice(1) : rest;
     const pwArgs = wantsUi && !forwarded.includes("--ui")
-        ? ["test", "--ui", ...forwarded]
-        : ["test", ...forwarded];
+        ? ["test", ...configArgs, "--ui", ...forwarded]
+        : ["test", ...configArgs, ...forwarded];
     process.exitCode = await runPw(pwArgs);
     return;
 }

package/dist/commands/try.js

@@ -6,6 +6,7 @@ import { packageRoot, runInherited } from "../cli/util.js";
 import { tmpdir } from "node:os";
 import { runChain } from "../cli/run-chain.js";
 import { applyRunFlags, parseRunFlags } from "../cli/flags.js";
+import { resolveVideoDir } from "../video-dir.js";
 /**
  * Runs a throwaway probe script rooted at `projectDir` - the exact same
  * directory the real demo files get copied into, so it resolves "waygraph"
@@ -196,7 +197,7 @@ async function runTryDemo() {
     const videoTo = process.env.WAYGRAPH_VIDEO;
     console.log(videoTo
         ? "waygraph try demo: step-through + record (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next; video -> " +
-            (videoTo === "1" ? ".waygraph-videos/" : videoTo)
+            (videoTo === "1" ? await resolveVideoDir(destDir) : videoTo)
         : "waygraph try demo: step-through (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next for each step ...");
     await runChain(destDir, TRY_DEMO_CHAIN);
     if (process.exitCode)

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff]`
+ * Compares the project with the scaffold shipped in this waygraph. Dry run by default.
+ * Only the paths you name are copied, because a real project deliberately drops parts of the demo.
+ */
+export declare function upgradeCase(args: string[]): Promise<void>;