waygraph 0.15.10 → 0.15.14

package/dist/auto-session.js

@@ -5,7 +5,8 @@ import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { ensureLivePage, detectHere, seedDefaultMem, ensureMem, runOneBlock, resolveBaseUrl, } from "./auto-explore-run.js";
 import { runStubPhase } from "./highlights.js";
 import { findBlockPathDetailed } from "./graph.js";
-import { updatePilotOverlay, showPilotActivity, showPilotVision, showPilotFixtures } from "./pilot-overlay.js";
+import { updatePilotOverlay, showPilotActivity, showPilotVision, showPilotFixtures, installPersistentPilotOverlay, } from "./pilot-overlay.js";
+import { collectKnownInteractionSelectors, unmappedInteractionsPageScript, } from "./coverage-gap.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 function stubPhaseHasContent(r) {
     return (Object.keys(r.highlights).length > 0 ||
@@ -142,6 +143,7 @@ const CONSOLE_LOG_MAX_ENTRIES = 200;
  */
 export class AutoSession {
     projectDir;
+    inject;
     blocksSelect;
     graph;
     library;
@@ -156,8 +158,12 @@ export class AutoSession {
     lastRunNote = null;
     trace = [];
     consoleLog = [];
-    constructor(projectDir, blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, sessionId) {
+    knownInteractionSelectors;
+    headless;
+    lastOverlayInfo = null;
+    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
         this.projectDir = projectDir;
+        this.inject = inject;
         this.blocksSelect = blocksSelect;
         this.graph = graph;
         this.library = library;
@@ -168,11 +174,18 @@ export class AutoSession {
         this.page = page;
         this.startUrl = startUrl;
         this.sessionId = sessionId;
+        this.knownInteractionSelectors = knownInteractionSelectors;
+        this.headless = headless;
     }
     static async start(init) {
         const baseURL = init.baseURL ?? resolveBaseUrl(init.projectDir);
-        const startUrl = init.startUrl ?? baseURL;
-        const { graph, library } = await buildExploreContext(init.projectDir, init.blocksSelect ? { blocksSelect: init.blocksSelect } : undefined);
+        const skipNav = init.skipInitialNavigation === true;
+        const startUrl = skipNav ? undefined : (init.startUrl ?? baseURL);
+        const exploreOpts = {
+            ...(init.blocksSelect ? { blocksSelect: init.blocksSelect } : {}),
+            ...(init.inject?.length ? { inject: init.inject } : {}),
+        };
+        const { graph, library } = await buildExploreContext(init.projectDir, Object.keys(exploreOpts).length ? exploreOpts : undefined);
         const mem = new MemPage();
         seedDefaultMem(library.byName, mem);
         const headless = init.headless ?? true;
@@ -188,6 +201,9 @@ export class AutoSession {
         // headless keeps the fixed viewport since there's no real window to size.
         const launchOpts = {
             headless,
+            // Keep Playwright's default --no-startup-window for headful: without it
+            // Chromium opens its own "New Tab" window AND our context.newPage() opens
+            // a second about:blank window. bringToFront() below surfaces the real page.
             args: headless ? [] : ["--start-maximized"],
         };
         if (executablePath)
@@ -199,12 +215,24 @@ export class AutoSession {
         if (baseURL)
             contextOpts.baseURL = baseURL;
         const context = await browser.newContext(contextOpts);
+        await installPersistentPilotOverlay(context);
         const page = await context.newPage();
         if (startUrl) {
             await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
             await page.waitForLoadState("load").catch(() => { });
         }
-        const session = new AutoSession(init.projectDir, init.blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, init.sessionId);
+        else {
+            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);
+        page.on("load", () => {
+            void session.repaintOverlayAfterNavigation();
+        });
+        if (!headless) {
+            await session.bootstrapOverlay().catch(() => { });
+            await page.bringToFront().catch(() => { });
+        }
         // Attached once, on the page created here - `ensureLivePage` only swaps
         // to a fresh Page if the current one closed (a rare case, e.g. the human
         // closing the tab), not on ordinary same-page SPA navigation, which is
@@ -277,65 +305,52 @@ export class AutoSession {
         // whole point is a human watching the screen sees the SAME state a
         // concurrent API caller just got back, not a stale frame that catches
         // up moments later.
-        await updatePilotOverlay(this.page, {
+        this.lastOverlayInfo = {
             sessionId: this.sessionId,
             snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
             graph: this.graph,
-        });
-        await this.warnUnmappedLinks();
+        };
+        await updatePilotOverlay(this.page, this.lastOverlayInfo);
+        await this.warnUnmappedInteractions();
         return menu;
     }
+    /** Paint the overlay on about:blank / immediately after session start (headful browser). */
+    async bootstrapOverlay() {
+        await this.currentMenu();
+    }
+    /** Re-apply cached overlay state after navigation (init script restores shell only). */
+    async repaintOverlayAfterNavigation() {
+        if (this.lastOverlayInfo) {
+            await updatePilotOverlay(this.page, this.lastOverlayInfo).catch(() => { });
+            return;
+        }
+        if (!this.headless) {
+            await this.bootstrapOverlay().catch(() => { });
+        }
+    }
     /**
-     * Real, direct user request: a Blind Pilot agent had no way to ask "which
-     * of the links visible on THIS page are already covered by a NavBlock" -
-     * only manual DOM inspection + guessing hrefs, exactly what this session
-     * had been doing by hand the whole time this feature was built. Compares
-     * every same-origin `<a href>` on the page against every NavBlock's own
-     * static url (`__waygraphNavUrl` - see `defineNavBlock`'s own comment for
-     * why only plain-string urls qualify), and `console.warn()`s each pathname
-     * with no NavBlock at all - surfaced through the same real console capture
-     * `auto console` already reads, not a separate channel. Deduped per path
-     * per page load (a `Set` living on `window`, so it survives repeated
-     * `currentMenu()` calls but resets on a real navigation) - once is enough
-     * to flag a gap, repeating it on every status/send call would just be noise.
+     * Flags same-origin `<a href>` paths and visible buttons with no NavBlock
+     * URL / Block selector in the loaded library — read via `auto console`.
+     * Deduped per page load so repeated status/send calls stay quiet.
      */
-    async warnUnmappedLinks() {
-        const known = new Set();
+    async warnUnmappedInteractions() {
+        const knownPathnames = [];
         for (const entry of this.library.navBlocks) {
             const url = entry.block.__waygraphNavUrl;
             if (!url)
                 continue;
             try {
-                known.add(new URL(url, this.page.url()).pathname);
+                knownPathnames.push(new URL(url, this.page.url()).pathname);
             }
             catch {
                 /* not a resolvable URL (relative to an unset base, etc.) - skip */
             }
         }
-        await this.page
-            .evaluate((knownPathnames) => {
-            const w = window;
-            w.__wgWarnedPaths ??= new Set();
-            const seenThisPass = new Set();
-            for (const a of Array.from(document.querySelectorAll("a[href]"))) {
-                let url;
-                try {
-                    url = new URL(a.getAttribute("href") || "", location.href);
-                }
-                catch {
-                    continue;
-                }
-                if (url.origin !== location.origin)
-                    continue;
-                const path = url.pathname;
-                if (seenThisPass.has(path) || knownPathnames.includes(path) || w.__wgWarnedPaths.has(path))
-                    continue;
-                seenThisPass.add(path);
-                w.__wgWarnedPaths.add(path);
-                console.warn(`[waygraph] unmapped nav link on this page: ${path} - no NavBlock covers this URL`);
-            }
-        }, Array.from(known))
-            .catch(() => { });
+        const payload = {
+            knownPathnames,
+            knownSelectors: this.knownInteractionSelectors,
+        };
+        await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(() => { });
     }
     /** Pure getter - no Block runs, no mem/page mutation. */
     async currentSnapshot() {
@@ -514,7 +529,11 @@ export class AutoSession {
     async reloadLibrary() {
         if (this.page)
             await showPilotActivity(this.page, "Running: reload");
-        const { graph, library } = await buildExploreContext(this.projectDir, this.blocksSelect ? { blocksSelect: this.blocksSelect } : undefined);
+        const exploreOpts = {
+            ...(this.blocksSelect ? { blocksSelect: this.blocksSelect } : {}),
+            ...(this.inject?.length ? { inject: this.inject } : {}),
+        };
+        const { graph, library } = await buildExploreContext(this.projectDir, Object.keys(exploreOpts).length ? exploreOpts : undefined);
         this.graph = graph;
         this.library = library;
         if (this.page)
@@ -561,7 +580,7 @@ export class AutoSession {
      */
     async rawClick(selector) {
         this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (Dom): click "${selector}"`);
+        await showPilotActivity(this.page, `Running (no Block): click "${selector}"`);
         const locator = this.page.locator(selector).first();
         if ((await locator.count()) === 0) {
             return { ok: false, error: `no element matches selector "${selector}"` };
@@ -579,7 +598,7 @@ export class AutoSession {
     }
     async rawType(selector, text) {
         this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (Dom): type into "${selector}"`);
+        await showPilotActivity(this.page, `Running (no Block): type into "${selector}"`);
         const locator = this.page.locator(selector).first();
         if ((await locator.count()) === 0) {
             return { ok: false, error: `no element matches selector "${selector}"` };
@@ -604,7 +623,7 @@ export class AutoSession {
      */
     async rawPress(selector, key) {
         this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (Dom): press "${key}" on "${selector}"`);
+        await showPilotActivity(this.page, `Running (no Block): press "${key}" on "${selector}"`);
         const locator = this.page.locator(selector).first();
         if ((await locator.count()) === 0) {
             return { ok: false, error: `no element matches selector "${selector}"` };
@@ -622,7 +641,7 @@ export class AutoSession {
     }
     async rawGoto(url) {
         this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (Dom): goto "${url}"`);
+        await showPilotActivity(this.page, `Running (no Block): goto "${url}"`);
         try {
             await this.page.goto(url, { waitUntil: "domcontentloaded" });
         }
@@ -649,7 +668,7 @@ export class AutoSession {
         this.page = await ensureLivePage(this.context, this.page, this.startUrl);
         const filePath = typeof stub === "string" ? stubFilePath(stub) : stub.filePath;
         const label = typeof stub === "string" ? stub : filePath;
-        await showPilotActivity(this.page, `Running (Dom): upload ${label} into "${selector}"`);
+        await showPilotActivity(this.page, `Running (no Block): upload ${label} into "${selector}"`);
         const locator = this.page.locator(selector).first();
         if ((await locator.count()) === 0) {
             return { ok: false, error: `no element matches selector "${selector}"` };

package/dist/block-inject.d.ts

@@ -0,0 +1,15 @@
+export declare function packageRoot(): string;
+/** Human label for an injected root (used in merged `file` paths). */
+export declare function injectLabel(root: string): string;
+/**
+ * Display path for a Block discovered under an inject root (not the host cwd).
+ * Primary project files stay relative as-is; injected ones are tagged `@label/...`.
+ */
+export declare function injectTaggedFile(hostDir: string, root: string, relFile: string): string;
+/**
+ * Resolve one `--inject` token to an absolute directory (preset name or path).
+ */
+export declare function resolveInjectRoot(token: string, cwd?: string): string;
+export declare function resolveInjectRoots(tokens: string[], cwd?: string): string[];
+/** Roots to scan: host project first, then each inject path (deduped). */
+export declare function exploreRoots(projectDir: string, inject?: string[]): string[];

package/dist/block-inject.js

@@ -0,0 +1,91 @@
+/**
+ * Merge Block libraries / graphs from extra project roots into a host session
+ * (waygraph browser `--inject`). Presets name bundled or well-known checkouts.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+export function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+/** Human label for an injected root (used in merged `file` paths). */
+export function injectLabel(root) {
+    return basename(root.replace(/\/$/, ""));
+}
+/**
+ * Display path for a Block discovered under an inject root (not the host cwd).
+ * Primary project files stay relative as-is; injected ones are tagged `@label/...`.
+ */
+export function injectTaggedFile(hostDir, root, relFile) {
+    const host = resolve(hostDir);
+    const r = resolve(root);
+    if (r === host)
+        return relFile.replace(/\\/g, "/");
+    return `@${injectLabel(r)}/${relFile.replace(/\\/g, "/")}`;
+}
+const PRESETS = {
+    saucedemo: () => join(packageRoot(), "examples", "saucedemo"),
+    demosauce: () => join(packageRoot(), "examples", "saucedemo"),
+    veciro: () => {
+        if (process.env.WAYGRAPH_INJECT_VECIRO) {
+            return resolve(process.env.WAYGRAPH_INJECT_VECIRO);
+        }
+        for (const c of [
+            join(homedir(), "Desktop", "Work", "veciro-waygraph"),
+            join(homedir(), "Desktop", "Projects", "veciro-waygraph"),
+        ]) {
+            if (existsSync(c))
+                return c;
+        }
+        return null;
+    },
+};
+/**
+ * Resolve one `--inject` token to an absolute directory (preset name or path).
+ */
+export function resolveInjectRoot(token, cwd = process.cwd()) {
+    const raw = token.trim();
+    if (!raw)
+        throw new Error("waygraph inject: empty --inject value");
+    const preset = PRESETS[raw.toLowerCase()];
+    if (preset) {
+        const dir = preset();
+        if (!dir || !existsSync(dir)) {
+            throw new Error(`waygraph inject: preset "${raw}" not found on disk (pass an absolute path to the Block library root)`);
+        }
+        return resolve(dir);
+    }
+    const abs = resolve(cwd, raw);
+    if (!existsSync(abs)) {
+        throw new Error(`waygraph inject: no such directory: ${abs}`);
+    }
+    return abs;
+}
+export function resolveInjectRoots(tokens, cwd = process.cwd()) {
+    const seen = new Set();
+    const out = [];
+    for (const t of tokens) {
+        const abs = resolveInjectRoot(t, cwd);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        out.push(abs);
+    }
+    return out;
+}
+/** Roots to scan: host project first, then each inject path (deduped). */
+export function exploreRoots(projectDir, inject) {
+    const host = resolve(projectDir);
+    const extra = inject ?? [];
+    const seen = new Set([host]);
+    const roots = [host];
+    for (const r of extra) {
+        const abs = resolve(r);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        roots.push(abs);
+    }
+    return roots;
+}

package/dist/browser.d.ts

@@ -0,0 +1,15 @@
+import type { AutoSessionInit } from "./auto-session.js";
+export interface BrowserStartInit extends AutoSessionInit {
+    /** Preset names or paths; resolved before spawn. */
+    injectTokens?: string[];
+}
+export interface BrowserStartResult {
+    sessionId: string;
+    socketPath: string;
+    headless: boolean;
+    /** Resolved inject roots merged into this session (host project excluded). */
+    inject: string[];
+}
+/** Always spawns a new detached session — does not stop or reuse existing ones. */
+export declare function browserStart(init: BrowserStartInit): Promise<BrowserStartResult>;
+export { listBrowserSessions, stopBrowserSession, stopAllBrowserSessions, type SessionMeta, } from "./auto-session-ipc.js";

package/dist/browser.js

@@ -0,0 +1,29 @@
+/**
+ * `waygraph browser` — persistent Playwright session with the project's Block
+ * library loaded (and optional `--inject` roots). Pilot drives these sessions
+ * via `browser send|status|highlight|…`; it does not spawn its own browser.
+ *
+ * Session lifecycle is explicit: `browser sessions` lists what's live;
+ * `browser start` always opens another; `browser attach` / `browser stop` pick one up or shut it down.
+ */
+import { spawnDetachedSession } from "./auto-session-ipc.js";
+import { resolveInjectRoots } from "./block-inject.js";
+/** Always spawns a new detached session — does not stop or reuse existing ones. */
+export async function browserStart(init) {
+    const inject = init.inject ??
+        (init.injectTokens?.length ? resolveInjectRoots(init.injectTokens, init.projectDir) : []);
+    const headless = init.headless ?? false;
+    const meta = await spawnDetachedSession({
+        ...init,
+        inject,
+        headless,
+        skipInitialNavigation: init.skipInitialNavigation ?? true,
+    });
+    return {
+        sessionId: meta.sessionId,
+        socketPath: meta.socketPath,
+        headless: meta.headless,
+        inject,
+    };
+}
+export { listBrowserSessions, stopBrowserSession, stopAllBrowserSessions, } from "./auto-session-ipc.js";

package/dist/cli.d.ts

@@ -8,6 +8,7 @@
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
+ * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.