waygraph 0.15.51 → 0.15.52

package/dist/core/flow.js

@@ -1,12 +1,32 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { connect } from "../types.js";
-import { chromiumExecutablePath } from "../browser-path.js";
+import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../browser.js";
+import { resolveExtensions } from "../extensions.js";
 import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
 import { MemPage } from "../mem-page.js";
 import { findBlockIndex, modVerify, withVerify } from "./block.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../highlights.js";
+/** Launches the browser and context an Engine uses when the caller gave none, from its config. */
+async function openOwnContext(config) {
+    const browserName = config?.browserName ?? "chromium";
+    const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
+    const baseURL = config?.baseUrl ?? process.env.WAYGRAPH_BASE_URL;
+    return launchContext({
+        launcher: resolveLauncher(browserName, config),
+        launch: {
+            headless: config?.headless ?? true,
+            ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+            ...(executablePath ? { executablePath } : {}),
+        },
+        context: {
+            ...(baseURL ? { baseURL } : {}),
+            ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+        },
+        extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+    });
+}
 export function buildFlow(middle, engineConfig) {
     // resetSession/title start false/unset here - defineFlow itself carries
     // no such options anymore. They're set by wrapping the result in
@@ -32,16 +52,8 @@ export function buildFlow(middle, engineConfig) {
             // before a page opens - the same "fail loud, cheaply" guarantee
             // run(context, mem) already has via an existing context.
             preflight(mem, chain);
-            const browserName = config.browserName ?? "chromium";
-            const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-            const browser = await launch.launch({
-                headless: config.headless ?? true,
-                ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                ...(executablePath ? { executablePath } : {}),
-            });
+            const { context, close } = await openOwnContext(config);
             try {
-                const context = await browser.newContext(config.recordVideo ? { recordVideo: config.recordVideo } : {});
                 try {
                     return await runGraph(chain, undefined, context, mem, 5000, {
                         ...(config.layouts !== undefined ? { layouts: config.layouts } : {}),
@@ -56,7 +68,7 @@ export function buildFlow(middle, engineConfig) {
                 }
             }
             finally {
-                await browser.close();
+                await close();
             }
         }
         const context = contextOrMem;
@@ -256,6 +268,25 @@ export function withHighlightFixtures(flow, fixtures) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightFixtures(flow.modBlockVerify(block, nameOrIndex, newCheck), fixtures),
     };
 }
+/** Applies each set option through its `with*` wrapper, so both spellings produce the same Flow. */
+export function applyFlowOptions(flow, options) {
+    if (!options)
+        return flow;
+    let f = flow;
+    if (options.sessionReset)
+        f = withSessionReset(f);
+    if (options.title !== undefined)
+        f = withTitle(f, options.title);
+    if (options.demoPace)
+        f = withDemoPace(f, options.demoPace);
+    if (options.highlightStyle)
+        f = withHighlightStyle(f, options.highlightStyle);
+    if (options.expectedFailure !== undefined)
+        f = withExpectedFailure(f, options.expectedFailure);
+    if (options.memStub)
+        f = withMemStub(f);
+    return f;
+}
 function locateInChain(flows, block) {
     if (typeof block === "number") {
         let remaining = block;
@@ -319,16 +350,8 @@ export function chainFlow(...flows) {
             // config) would otherwise each launch a separate browser, defeating
             // the point of sequencing them (a fresh browser is itself a full
             // session reset, silently making withSessionReset a no-op).
-            const browserName = config?.browserName ?? "chromium";
-            const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-            const browser = await launch.launch({
-                headless: config?.headless ?? true,
-                ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                ...(executablePath ? { executablePath } : {}),
-            });
+            const { context, close } = await openOwnContext(config);
             try {
-                const context = await browser.newContext(config?.recordVideo ? { recordVideo: config.recordVideo } : {});
                 try {
                     return await run(context, mem, { closeOnFinish: true });
                 }
@@ -337,7 +360,7 @@ export function chainFlow(...flows) {
                 }
             }
             finally {
-                await browser.close();
+                await close();
             }
         }
         const context = contextOrMem;

package/dist/core/map-builder.d.ts

@@ -1,6 +1,6 @@
 import type { Block, Checkpoint } from "../types.js";
 import type { EndMarker, StartMarker } from "./run-graph.js";
-import type { Flow } from "./flow.js";
+import type { Flow, FlowOptions } from "./flow.js";
 import type { NavBlock } from "./blocks/nav.js";
 import type { PageBlock } from "./blocks/page.js";
 import type { AssertBlock, MethodBlock } from "./blocks/method.js";
@@ -12,7 +12,7 @@ type S = Checkpoint<"__start__">;
  * import each other (Engine.map() builds a MapBuilder; MapBuilder.end() calls back into
  * defineFlow) - a real cycle check:structure forbids. This type is how that's avoided.
  */
-export type DefineFlowFn = (blocks: readonly [StartMarker, ...Block<any, any>[], EndMarker]) => Flow<any>;
+export type DefineFlowFn = (blocks: readonly [StartMarker, ...Block<any, any>[], EndMarker], options?: FlowOptions) => Flow<any>;
 /** Per-step options every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
 export interface MapStepOpts {
     /**
@@ -166,6 +166,6 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
      * still throws - the author opened that one and needs to close it themselves.
      */
-    end(): Flow<Out>;
+    end(options?: FlowOptions): Flow<Out>;
 }
 export {};

package/dist/core/map-builder.js

@@ -329,17 +329,17 @@ export class MapBuilder {
      * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
      * still throws - the author opened that one and needs to close it themselves.
      */
-    end() {
+    end(options) {
         if (this.ff && !this.ff.auto) {
             throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", MSG_MAP_FF_NOT_CLOSED(this.ff.name));
         }
         if (this.ff && this.ff.auto) {
-            return this.closeFf().end();
+            return this.closeFf().end(options);
         }
         if (this.steps.length === 0) {
             throw new WaygraphError("WG_MAP_EMPTY", MSG_MAP_EMPTY);
         }
         const chain = [start, ...this.steps, end];
-        return this.defineFlow(chain);
+        return this.defineFlow(chain, options);
     }
 }

package/dist/env-file.d.ts

@@ -1,10 +1,10 @@
+/** The env mode: `--env <mode>` / `WAYGRAPH_ENV`, else `NODE_ENV`, else "development". */
+export declare function envMode(): string;
+/** Removes `--env <mode>` / `--env=<mode>` from argv and records it as `WAYGRAPH_ENV`, so it never reaches a forwarded command. */
+export declare function takeEnvFlag(argv: string[]): string[];
 /**
- * Auto-loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root,
- * same layering Vite/Next use (`mode` defaults to `NODE_ENV`, falling back to "development"),
- * merged into `process.env` in increasing priority. A real, already-set `process.env` value -
- * whatever the shell actually exported - always wins over every file; a `.env` file only fills
- * a gap, it never silently overrides something the caller explicitly set. Safe to call more
- * than once (e.g. once eagerly at `cwd`, again once the real project dir is known) - loading
- * twice is a no-op the second time for any key already filled.
+ * Loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root, the layering
+ * Vite and Next use: each later file overrides the earlier ones (`.env.<mode>.local` wins). A value the
+ * shell already exported always beats every file, so a file only fills gaps. Calling it twice is harmless.
  */
 export declare function loadEnvFiles(projectDir: string, mode?: string): void;

package/dist/env-file.js

@@ -28,31 +28,44 @@ function parseEnvFile(content) {
     }
     return out;
 }
+/** The env mode: `--env <mode>` / `WAYGRAPH_ENV`, else `NODE_ENV`, else "development". */
+export function envMode() {
+    return process.env.WAYGRAPH_ENV || process.env.NODE_ENV || "development";
+}
+/** Removes `--env <mode>` / `--env=<mode>` from argv and records it as `WAYGRAPH_ENV`, so it never reaches a forwarded command. */
+export function takeEnvFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--env" && argv[i + 1] !== undefined)
+            process.env.WAYGRAPH_ENV = argv[++i];
+        else if (a.startsWith("--env="))
+            process.env.WAYGRAPH_ENV = a.slice("--env=".length);
+        else
+            out.push(a);
+    }
+    return out;
+}
 /**
- * Auto-loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root,
- * same layering Vite/Next use (`mode` defaults to `NODE_ENV`, falling back to "development"),
- * merged into `process.env` in increasing priority. A real, already-set `process.env` value -
- * whatever the shell actually exported - always wins over every file; a `.env` file only fills
- * a gap, it never silently overrides something the caller explicitly set. Safe to call more
- * than once (e.g. once eagerly at `cwd`, again once the real project dir is known) - loading
- * twice is a no-op the second time for any key already filled.
+ * Loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root, the layering
+ * Vite and Next use: each later file overrides the earlier ones (`.env.<mode>.local` wins). A value the
+ * shell already exported always beats every file, so a file only fills gaps. Calling it twice is harmless.
  */
-export function loadEnvFiles(projectDir, mode = process.env.NODE_ENV || "development") {
-    const files = [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`];
-    for (const name of files) {
+export function loadEnvFiles(projectDir, mode = envMode()) {
+    const merged = {};
+    for (const name of [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`]) {
         const p = join(projectDir, name);
         if (!existsSync(p))
             continue;
-        let parsed;
         try {
-            parsed = parseEnvFile(readFileSync(p, "utf-8"));
+            Object.assign(merged, parseEnvFile(readFileSync(p, "utf-8")));
         }
         catch {
             continue; // unreadable file - never fail a run over an optional .env
         }
-        for (const [key, value] of Object.entries(parsed)) {
-            if (process.env[key] === undefined)
-                process.env[key] = value;
-        }
+    }
+    for (const [key, value] of Object.entries(merged)) {
+        if (process.env[key] === undefined)
+            process.env[key] = value;
     }
 }

package/dist/extensions.d.ts

@@ -0,0 +1,21 @@
+/** A known name (`"hoppscotch"`), a Chrome Web Store id, a path to an unpacked extension, or `{ id, sha256 }`. */
+export type ExtensionSpec = string | {
+    id?: string;
+    path?: string;
+    sha256?: string;
+};
+export declare const KNOWN_EXTENSIONS: Readonly<Record<string, string>>;
+/** Unpacks a .crx and pins the manifest `key`, so the extension keeps its store id (its origin is then stable, e.g. for an API allowlist). */
+export declare function unpackCrx(crx: Buffer, dest: string): void;
+/**
+ * Returns an unpacked directory for one config entry, downloading it on first use. An installed
+ * extension is never silently replaced - pass `update: true` (`waygraph extensions install --update`) to refetch.
+ */
+export declare function resolveExtension(spec: ExtensionSpec, projectDir: string, opts?: {
+    update?: boolean;
+}): Promise<string>;
+export declare function resolveExtensions(specs: readonly ExtensionSpec[] | undefined, projectDir: string): Promise<string[]>;
+export declare function extensionInfo(dir: string): {
+    name: string;
+    version: string;
+};

package/dist/extensions.js

@@ -0,0 +1,178 @@
+// Browser extensions for waygraph runs: resolve a config entry to an unpacked directory Chromium can load.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { inflateRawSync } from "node:zlib";
+export const KNOWN_EXTENSIONS = {
+    hoppscotch: "amknoiejhlmhancpahfcfcfhllgkpbld",
+};
+const STORE_ID = /^[a-p]{32}$/;
+function cacheDir() {
+    const base = process.env.WAYGRAPH_CACHE_DIR ?? join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "waygraph");
+    return join(base, "extensions");
+}
+/** Reads the end-of-central-directory record and extracts every entry; rejects paths that escape `dest`. */
+function unzipTo(zip, dest) {
+    let eocd = zip.length - 22;
+    while (eocd >= 0 && zip.readUInt32LE(eocd) !== 0x06054b50)
+        eocd--;
+    if (eocd < 0)
+        throw new Error("not a zip archive");
+    const count = zip.readUInt16LE(eocd + 10);
+    let p = zip.readUInt32LE(eocd + 16);
+    const root = resolve(dest);
+    for (let i = 0; i < count; i++) {
+        if (zip.readUInt32LE(p) !== 0x02014b50)
+            throw new Error("corrupt zip directory");
+        const method = zip.readUInt16LE(p + 10);
+        const size = zip.readUInt32LE(p + 20);
+        const nameLen = zip.readUInt16LE(p + 28);
+        const extraLen = zip.readUInt16LE(p + 30);
+        const commentLen = zip.readUInt16LE(p + 32);
+        const local = zip.readUInt32LE(p + 42);
+        const name = zip.toString("utf8", p + 46, p + 46 + nameLen);
+        p += 46 + nameLen + extraLen + commentLen;
+        const target = resolve(root, name);
+        if (target !== root && !target.startsWith(root + sep))
+            throw new Error(`unsafe path in archive: ${name}`);
+        if (name.endsWith("/")) {
+            mkdirSync(target, { recursive: true });
+            continue;
+        }
+        const dataStart = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+        const raw = zip.subarray(dataStart, dataStart + size);
+        if (method !== 0 && method !== 8)
+            throw new Error(`unsupported zip compression (${method}) for ${name}`);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, method === 0 ? raw : inflateRawSync(raw));
+    }
+}
+/** A .crx is a signed header followed by a normal zip. The signature is not checked here - pin `sha256` to do that. */
+function crxToZip(crx) {
+    if (crx.toString("latin1", 0, 4) !== "Cr24")
+        throw new Error("not a Chrome extension (.crx) file");
+    const version = crx.readUInt32LE(4);
+    if (version === 3)
+        return crx.subarray(12 + crx.readUInt32LE(8));
+    if (version === 2)
+        return crx.subarray(16 + crx.readUInt32LE(8) + crx.readUInt32LE(12));
+    throw new Error(`unsupported .crx version ${version}`);
+}
+/** Reads the length-delimited fields of one protobuf message as [fieldNumber, bytes] pairs; other wire types are skipped. */
+function protoFields(buf) {
+    const out = [];
+    let p = 0;
+    const varint = () => {
+        let n = 0;
+        for (let shift = 0;; shift += 7) {
+            const b = buf[p++];
+            n += (b & 0x7f) * 2 ** shift;
+            if (!(b & 0x80))
+                return n;
+        }
+    };
+    while (p < buf.length) {
+        const tag = varint();
+        const wire = tag & 7;
+        if (wire === 2) {
+            const len = varint();
+            out.push([tag >>> 3, buf.subarray(p, p + len)]);
+            p += len;
+        }
+        else if (wire === 0)
+            varint();
+        else if (wire === 1)
+            p += 8;
+        else if (wire === 5)
+            p += 4;
+        else
+            break;
+    }
+    return out;
+}
+/** The extension's public key (DER), from which Chrome derives its id: with it in the manifest the id equals the store's. */
+function crxPublicKey(crx) {
+    const version = crx.readUInt32LE(4);
+    if (version === 2)
+        return crx.subarray(16, 16 + crx.readUInt32LE(8));
+    const header = protoFields(crx.subarray(12, 12 + crx.readUInt32LE(8)));
+    const signed = header.find(([n]) => n === 10000)?.[1];
+    const crxId = signed ? protoFields(signed).find(([n]) => n === 1)?.[1] : undefined;
+    for (const [n, proof] of header) {
+        if (n !== 2 && n !== 3)
+            continue;
+        const key = protoFields(proof).find(([f]) => f === 1)?.[1];
+        if (key && crxId && createHash("sha256").update(key).digest().subarray(0, 16).equals(crxId))
+            return key;
+    }
+    return undefined;
+}
+/** Unpacks a .crx and pins the manifest `key`, so the extension keeps its store id (its origin is then stable, e.g. for an API allowlist). */
+export function unpackCrx(crx, dest) {
+    unzipTo(crxToZip(crx), dest);
+    const key = crxPublicKey(crx);
+    if (!key)
+        return;
+    const file = join(dest, "manifest.json");
+    const manifest = JSON.parse(readFileSync(file, "utf-8"));
+    manifest.key = key.toString("base64");
+    writeFileSync(file, JSON.stringify(manifest, null, 2));
+}
+function readManifest(dir) {
+    const file = join(dir, "manifest.json");
+    if (!existsSync(file))
+        throw new Error(`no manifest.json in ${dir}`);
+    return JSON.parse(readFileSync(file, "utf-8"));
+}
+async function download(id, sha256) {
+    const url = "https://clients2.google.com/service/update2/crx?response=redirect&prodversion=130.0.0.0" +
+        `&acceptformat=crx2,crx3&x=id%3D${id}%26uc`;
+    const res = await fetch(url);
+    const body = Buffer.from(await res.arrayBuffer());
+    if (!res.ok || body.length < 16 || body.toString("latin1", 0, 4) !== "Cr24") {
+        throw new Error(`extension ${id} was not found in the Chrome Web Store (HTTP ${res.status})`);
+    }
+    if (sha256 && createHash("sha256").update(body).digest("hex") !== sha256.toLowerCase()) {
+        throw new Error(`extension ${id}: downloaded file does not match the pinned sha256`);
+    }
+    return body;
+}
+/**
+ * Returns an unpacked directory for one config entry, downloading it on first use. An installed
+ * extension is never silently replaced - pass `update: true` (`waygraph extensions install --update`) to refetch.
+ */
+export async function resolveExtension(spec, projectDir, opts = {}) {
+    const entry = typeof spec === "string" ? (spec.startsWith(".") || spec.includes("/") ? { path: spec } : { id: spec }) : spec;
+    if (entry.path) {
+        const dir = resolve(projectDir, entry.path);
+        readManifest(dir);
+        return dir;
+    }
+    const id = KNOWN_EXTENSIONS[entry.id ?? ""] ?? entry.id ?? "";
+    if (!STORE_ID.test(id)) {
+        throw new Error(`unknown extension "${entry.id}" - use a known name (${Object.keys(KNOWN_EXTENSIONS).join(", ")}), a Chrome Web Store id, or { path }`);
+    }
+    const dir = join(cacheDir(), id);
+    if (!opts.update && existsSync(join(dir, "manifest.json")))
+        return dir;
+    const tmp = `${dir}.tmp-${process.pid}`;
+    rmSync(tmp, { recursive: true, force: true });
+    try {
+        unpackCrx(await download(id, entry.sha256), tmp);
+        readManifest(tmp);
+        rmSync(dir, { recursive: true, force: true });
+        renameSync(tmp, dir);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    return dir;
+}
+export async function resolveExtensions(specs, projectDir) {
+    return Promise.all((specs ?? []).map((s) => resolveExtension(s, projectDir)));
+}
+export function extensionInfo(dir) {
+    const m = readManifest(dir);
+    return { name: m.name ?? dir, version: m.version ?? "?" };
+}

package/dist/index.d.ts

@@ -6,13 +6,13 @@ export { css, byText, byRole } from "./selector.js";
 export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
 export type { WaygraphErrorCode } from "./errors.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, withDialog, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
 export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./core/branch-regression.js";
 export type { ApiBlockOptions, ApiCallResult } from "./core/blocks/api.js";
 export type { MapStepOpts } from "./core/map-builder.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, BannerPos, BannerUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
-export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./core.js";
+export type { Flow, FlowOptions, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./core.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./analysis/graph.js";
@@ -30,7 +30,9 @@ export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnap
 export { pilotStart } from "./session/pilot.js";
 export type { PilotStartResult } from "./session/pilot.js";
 export { defineConfig, resolveBaseUrl } from "./config.js";
-export type { WaygraphConfig } from "./config.js";
+export type { WaygraphConfig, ConfigContext } from "./config.js";
 export { withWebServer } from "./webserver.js";
-export { chromiumExecutablePath } from "./browser-path.js";
+export { chromiumExecutablePath } from "./browser.js";
+export { resolveExtension, KNOWN_EXTENSIONS } from "./extensions.js";
+export type { ExtensionSpec } from "./extensions.js";
 export type { WebServerConfig } from "./webserver.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 export { css, byText, byRole } from "./selector.js";
 export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, withDialog, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
@@ -16,4 +16,5 @@ export { AutoSession, stubFilePath } from "./auto-session.js";
 export { pilotStart } from "./session/pilot.js";
 export { defineConfig, resolveBaseUrl } from "./config.js";
 export { withWebServer } from "./webserver.js";
-export { chromiumExecutablePath } from "./browser-path.js";
+export { chromiumExecutablePath } from "./browser.js";
+export { resolveExtension, KNOWN_EXTENSIONS } from "./extensions.js";

package/dist/pilot-overlay/overlay-fixtures.d.ts

@@ -1,12 +1,5 @@
 import type { StubPhaseResult } from "../highlights.js";
 import type { PilotHighlightFixtures } from "./fixtures.js";
-/**
- * Resolve agent-sent "waygraph overlay fixtures" (`auto highlight` JSON / shorthand) through the SAME
- * stub-ctx path a Block's `stubBefore(ctx)` uses, so ctx.todos / ctx.device / ctx.title / ctx.bannerUi semantics
- * (keep vs set vs clear, defaults, normalisation) cannot diverge between `waygraph demo` and pilot/auto/browser.
- * Not Playwright test fixtures - these describe what the waygraph overlay paints on the page under test.
- */
-export declare function overlayFixturesToPhase(f: PilotHighlightFixtures): Promise<StubPhaseResult>;
 /**
  * The reverse: a resolved stub phase (what `runStubPhase` returns for a Block's stubBefore/After/OnError)
  * -> what the Pilot painter takes. Lets `auto/browser/pilot send` paint a Block's authored waygraph overlay

package/dist/pilot-overlay/overlay-fixtures.js

@@ -1,48 +1,3 @@
-import { runStubPhase } from "../highlights.js";
-/**
- * Resolve agent-sent "waygraph overlay fixtures" (`auto highlight` JSON / shorthand) through the SAME
- * stub-ctx path a Block's `stubBefore(ctx)` uses, so ctx.todos / ctx.device / ctx.title / ctx.bannerUi semantics
- * (keep vs set vs clear, defaults, normalisation) cannot diverge between `waygraph demo` and pilot/auto/browser.
- * Not Playwright test fixtures - these describe what the waygraph overlay paints on the page under test.
- */
-export async function overlayFixturesToPhase(f) {
-    const lifecycle = (ctx) => {
-        if (f.clear) {
-            ctx.hideTodos();
-            ctx.hideDevice();
-            return;
-        }
-        if (f.title !== undefined)
-            ctx.title(f.title, f.titlePos ? { pos: f.titlePos } : undefined);
-        else if (f.titlePos)
-            ctx.titlePos(f.titlePos);
-        if (f.bannerUi)
-            ctx.bannerUi(f.bannerUi);
-        if (f.todos !== undefined) {
-            ctx.todos("pilot", f.todos, {
-                title: f.todoTitle ?? "Plan",
-                index: f.todoIndex ?? 0,
-                pos: f.todoPos === "left" ? "left" : "right",
-            });
-        }
-        const ui = f.todoDockUi ?? f.todoUi;
-        if (ui)
-            ctx.todoDockUi(ui);
-        if (f.device)
-            ctx.device(f.device);
-        if (typeof f.zoom === "number" && Number.isFinite(f.zoom) && f.zoom > 0)
-            ctx.zoom(f.zoom);
-        if (f.zoomOut !== undefined)
-            ctx.zoomOut(f.zoomOut);
-        if (f.rings?.length) {
-            f.rings.forEach((r, i) => {
-                const { selector, label, ...rest } = r;
-                ctx.ring(`ring${i + 1}`, { selector, label, ...rest });
-            });
-        }
-    };
-    return runStubPhase({ name: "overlay-fixtures", stubBefore: lifecycle }, "stubBefore");
-}
 /**
  * The reverse: a resolved stub phase (what `runStubPhase` returns for a Block's stubBefore/After/OnError)
  * -> what the Pilot painter takes. Lets `auto/browser/pilot send` paint a Block's authored waygraph overlay

package/dist/playwright-config.d.ts

@@ -0,0 +1,4 @@
+import type { PlaywrightTestConfig } from "@playwright/test";
+import type { WaygraphConfig } from "./config.js";
+/** The test runner's config for a project, built from its waygraph config. `waygraph test` uses this when there is no playwright.config. */
+export declare function playwrightConfigFrom(config: WaygraphConfig, projectDir: string, baseURL: string | undefined): PlaywrightTestConfig;

package/dist/playwright-config.js

@@ -0,0 +1,15 @@
+import { join } from "node:path";
+/** The test runner's config for a project, built from its waygraph config. `waygraph test` uses this when there is no playwright.config. */
+export function playwrightConfigFrom(config, projectDir, baseURL) {
+    const { use, ...rest } = config.playwright ?? {};
+    const webServers = [config.webServer ?? []].flat().map((s) => ({ ...s, cwd: join(projectDir, s.cwd ?? ".") }));
+    return {
+        testDir: join(projectDir, config.testDir ?? "tests"),
+        outputDir: join(projectDir, "test-results"),
+        fullyParallel: true,
+        reporter: [["list"], ["html", { open: "never", outputFolder: join(projectDir, "playwright-report") }]],
+        ...(webServers.length > 0 ? { webServer: webServers } : {}),
+        ...rest,
+        use: { baseURL, trace: "retain-on-failure", ...use },
+    };
+}

package/dist/playwright.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@playwright/test").PlaywrightTestConfig<{}, {}>;
+export default _default;

package/dist/playwright.config.js

@@ -0,0 +1,6 @@
+// Loaded by `waygraph test` (playwright test -c) for projects that keep their settings in config/waygraph.config.ts.
+import { defineConfig } from "@playwright/test";
+import { loadWaygraphConfig, resolveBaseUrl } from "./config.js";
+import { playwrightConfigFrom } from "./playwright-config.js";
+const projectDir = process.env.WAYGRAPH_PROJECT_DIR ?? process.cwd();
+export default defineConfig(playwrightConfigFrom((await loadWaygraphConfig(projectDir)) ?? {}, projectDir, await resolveBaseUrl(projectDir)));

package/dist/runner/demo-log.js

@@ -109,14 +109,8 @@ function demoTs() {
   );
 }
 
-let logSurface = "demo";
-/** Which surface is talking (demo | auto | browser | pilot) - same log format everywhere, only the tag differs. */
-export function setDemoLogSurface(name) {
-  logSurface = String(name || "demo");
-}
-
 function demoPrefix() {
-  return ansiPaint(ANSI.dim, "[" + demoTs() + "]") + " waygraph " + logSurface + ": ";
+  return ansiPaint(ANSI.dim, "[" + demoTs() + "]") + " waygraph demo: ";
 }
 
 export function demoLog(msg) {

package/dist/runner/inpage/core.d.ts

@@ -1,4 +1,4 @@
 /** In-page installer (page.evaluate target) - see core.js's own header. Installs the shared ring
- * primitive (__wgEnsureRingEl/__wgPaintRingAt/__wgHideRingAt), cursor, click-pulse, focus veil,
+ * primitive (__wgEnsureRingEl/__wgPaintRingAt), cursor, click-pulse, focus veil,
  * and the #wg-ring singleton every surface's "current action" ring uses. */
 export function installCore(args: Record<string, unknown>): void;