waygraph 0.15.51 → 0.15.53

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/highlights/demo-pace.d.ts

@@ -10,7 +10,6 @@ export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
 export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
 export declare function normalizeDemoPace(raw: unknown): DemoPace;
-/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
 export declare function demoPaceScale(pace: DemoPace): number;
 export declare function demoPaceIsBlitz(pace: DemoPace): boolean;
 /** True when pace should use the short-gate / fast fixture path (not slow authored). */

package/dist/highlights/demo-pace.js

@@ -34,6 +34,24 @@ export function normalizeDemoPace(raw) {
     return "normal";
 }
 /** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+/**
+ * What each named pace means, as a multiplier of normal dwell (1 = normal). `demo.speeds` in the config (or
+ * `WAYGRAPH_PACE_SPEEDS`, a JSON object) overrides any of them; the defaults are blitz 0.05, fast 0.33, slow 2.
+ */
+function paceSpeeds() {
+    const out = { blitz: 0.05, fast: 0.33, slow: 2 };
+    try {
+        const raw = process.env.WAYGRAPH_PACE_SPEEDS ? JSON.parse(process.env.WAYGRAPH_PACE_SPEEDS) : {};
+        for (const k of ["blitz", "fast", "slow"]) {
+            if (typeof raw[k] === "number" && raw[k] > 0)
+                out[k] = Math.min(10, raw[k]);
+        }
+    }
+    catch {
+        /* ignore a malformed value: defaults apply */
+    }
+    return out;
+}
 export function demoPaceScale(pace) {
     if (typeof pace === "number") {
         if (pace > 20)
@@ -41,11 +59,11 @@ export function demoPaceScale(pace) {
         return Math.min(10, Math.max(0.05, pace));
     }
     if (pace === "blitz")
-        return 0.05;
+        return paceSpeeds().blitz;
     if (pace === "fast")
-        return 0.33;
+        return paceSpeeds().fast;
     if (pace === "slow")
-        return 2;
+        return paceSpeeds().slow;
     return 1;
 }
 export function demoPaceIsBlitz(pace) {
@@ -73,6 +91,9 @@ export function demoPaceIsSlow(pace) {
 }
 /** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
 export function demoPaceGateMs(pace, baseAutoplayMs) {
+    if (pace === "blitz" && process.env.WAYGRAPH_PACE_SPEEDS) {
+        return Math.min(30000, Math.max(20, Math.round(baseAutoplayMs * paceSpeeds().blitz)));
+    }
     if (demoPaceIsBlitz(pace))
         return Math.min(80, baseAutoplayMs);
     if (typeof pace === "number" && pace > 20) {

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 type { MapStepOpts, MapFlowOpts } 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, VideoSettings, RunSettings, DemoSettings } 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/action-ring.d.ts

@@ -1,16 +1,7 @@
 import type { Page } from "@playwright/test";
-type Box = {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-/** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
-export declare function showPilotRect(page: Page, box: Box, label: string, tone?: string): Promise<void>;
 /**
  * Every Playwright instruction a Block runs against this session's page gets a gray (auto) ring + robot
  * label first, so a human watching a pilot window sees WHAT is being driven. `dwellMs` holds the ring
  * long enough to read before the action fires (0 for headless).
  */
 export declare function instrumentPilotActions(page: Page, dwellMs: number): void;
-export {};

package/dist/pilot-overlay/action-ring.js

@@ -1,6 +1,6 @@
 import { ensureInstalled } from "./shell.js";
 /** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
-export async function showPilotRect(page, box, label, tone = "auto") {
+async function showPilotRect(page, box, label, tone = "auto") {
     await ensureInstalled(page);
     await page
         .evaluate(({ box, label, tone }) => {

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/pilot-overlay/panel.d.ts

@@ -1,7 +1,7 @@
 import type { SessionSnapshot } from "../auto-session.js";
 import type { Page } from "@playwright/test";
 /** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
-export interface PilotOverlayGraph {
+interface PilotOverlayGraph {
     nodes: readonly {
         checkpoint: string;
     }[];
@@ -32,3 +32,4 @@ export interface PilotOverlayInfo {
  * operation over.
  */
 export declare function updatePilotOverlay(page: Page, info: PilotOverlayInfo): Promise<void>;
+export {};

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;

package/dist/runner/inpage/core.js

@@ -72,7 +72,14 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ring.style.width = width + "px";
           ring.style.height = height + "px";
           ring.style.opacity = "1";
-          ringLabel.textContent = label || "";
+          if (labelId === "wg-ring-label") {
+            // The demo ring's caption is drawn from data-label (CSS ::after), not DOM text, so the page's own
+            // text selectors (getByText, text=...) never match waygraph's overlay twice.
+            ringLabel.dataset.label = label || "";
+            ringLabel.textContent = "";
+          } else {
+            ringLabel.textContent = label || "";
+          }
           ringLabel.style.opacity = "1";
           const lw = ringLabel.offsetWidth;
           const lh = ringLabel.offsetHeight;
@@ -104,12 +111,6 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ringLabel.style.top = labelTop + "px";
           return [ring, ringLabel];
         };
-        window.__wgHideRingAt = (ringId, labelId) => {
-          const ring = __wgById(ringId);
-          const label = __wgById(labelId);
-          if (ring) ring.style.opacity = "0";
-          if (label) label.style.opacity = "0";
-        };
         window.__wgEnsureRingEl("wg-ring", "wg-ring-label");
         if (!__wgById("wg-cursor")) {
           const cursor = document.createElement("div");

package/dist/runner/interaction-patch.js

@@ -21,7 +21,36 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
   // (shorter Next/autoplay gates) and must NOT skip theater, or the whole demo
   // looks like plain waygraph run.
   const skipTheater = () => !!pacing.skipTheater;
-  const typeDelay = () => (skipTheater() ? 0 : slowMo ? 0 : 30);
+  // `slowMo` here is the demo's own beat: ms to rest after each action (once per call, never per keystroke). The browser
+  // itself is launched with slowMo 0 in step mode, so a step whose pace is blitz really does run at full speed.
+  const beat = () => (skipTheater() ? 0 : slowMo || 0);
+  const pause = (ms) => (ms > 0 ? new Promise((res) => setTimeout(res, ms)) : undefined);
+  // Per-character typing delay (WAYGRAPH_TYPING_MS, default 30). 0 for blitz steps.
+  const typingMs = () => {
+    if (skipTheater()) return 0;
+    const n = Number(process.env.WAYGRAPH_TYPING_MS);
+    return process.env.WAYGRAPH_TYPING_MS !== undefined && Number.isFinite(n) && n >= 0 ? n : 30;
+  };
+  const typeDelay = typingMs;
+  const keyboard = page.keyboard;
+  if (!keyboard.__wgBeatPatched) {
+    keyboard.__wgBeatPatched = true;
+    const originalType = keyboard.type.bind(keyboard);
+    keyboard.type = async (text, options) => {
+      await originalType(text, { delay: typingMs(), ...(options || {}) });
+      await pause(beat());
+    };
+    const originalPress = keyboard.press.bind(keyboard);
+    keyboard.press = async (key, options) => {
+      await originalPress(key, options);
+      await pause(beat());
+    };
+    const originalInsertText = keyboard.insertText.bind(keyboard);
+    keyboard.insertText = async (text) => {
+      await originalInsertText(text);
+      await pause(beat());
+    };
+  }
   // Click is a single action, not per-character, so it doesn't compound
   // the same way - but slowMo still adds its own pause around the actual
   // click, so trim our own explicit "pop" pauses when it's already active
@@ -155,6 +184,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
       // it - it was sticking around through the whole rest of the step.
       await hideRing(page);
       await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
+      await pause(beat());
       return result;
     };
   }
@@ -285,6 +315,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
       await hideRing(page);
       // Full document navigation drops #wg-todo-dock + rings; restore carry.
       await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
+      await pause(beat());
       return result;
     };
   }