waygraph 0.13.6 → 0.14.0

package/dist/engine.js

@@ -797,6 +797,20 @@ export function defineNavBlock(options) {
             configurable: false,
         });
     }
+    // Same idea, for the url case - only when it's a plain string (a
+    // function URL is mem-dependent/dynamic, can't be compared statically
+    // without running it). Real, direct request this responds to: an agent
+    // driving Blind Pilot had no structured way to ask "which of the links
+    // on THIS page are already covered by a NavBlock" without re-parsing
+    // every nav.block.ts's own source - this is what `AutoSession` now reads
+    // to warn about real, unmapped nav links found live on the page.
+    if (typeof options.url === "string") {
+        Object.defineProperty(built, "__waygraphNavUrl", {
+            value: options.url,
+            enumerable: false,
+            configurable: false,
+        });
+    }
     return built;
 }
 /** @see {@link NavClickBlockOptions} */
@@ -826,6 +840,60 @@ export function defineMethodBlock(base) {
 }
 /** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
 export const defineActionBlock = defineMethodBlock;
+/**
+ * Sugar for a self-loop-only "pure assertion" Block: no hand-written
+ * `act`/`resolve`, just a name, a `checkpoint` tag, and a `verify` array.
+ * `resolve` is generated from the one `checkpoint` field given, closing the
+ * copy/rename footgun where a hand-restated checkpoint string can silently
+ * drift wrong across a copy/pasted file. Mirrors `definePageBlock`'s own
+ * construction pattern (flat options in, `defineBlock` built internally).
+ * See openspec/changes/waygraph-agent-skill-hardening/spec.md.
+ * @example
+ * defineAssertBlock({
+ *   name: "assert-raw-materials-table",
+ *   checkpoint: "RawMaterials",
+ *   waitForHeading: "Raw Materials & Lead Times",
+ *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
+ * });
+ */
+export function defineAssertBlock(options) {
+    const built = defineMethodBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        instruction: {
+            async act(page) {
+                if (options.waitForHeading !== undefined) {
+                    await page.getByRole("heading", { name: options.waitForHeading }).waitFor();
+                }
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            verify: options.verify,
+            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
+            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
+            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
+            ...(options.slides ? { slides: options.slides } : {}),
+        },
+    });
+    // Real bug this closes: `waygraph graph`'s static discovery only knows
+    // how to read a Block's Checkpoint tags from an EXPLICIT `<In, Out>`
+    // generic written in the source text (or, for Nav/Page Blocks, by calling
+    // their own input-independent `resolve()` directly). `defineAssertBlock`'s
+    // whole point is skipping that generic - called exactly as documented
+    // (`defineAssertBlock({ name, checkpoint, verify })`, no generics), it was
+    // silently invisible to both `waygraph graph` and the live Pilot menu
+    // ("2 Block(s) skipped (Out not resolvable)", confirmed live against a
+    // real veciro-waygraph session). `resolve()` here is ALSO input-
+    // independent (always `checkpoint(options.checkpoint)`), so the same
+    // resolve()-calling path Nav/Page Blocks already use is reused via this
+    // marker instead of requiring authors to write generics just to be found.
+    Object.defineProperty(built, "__waygraphKind", {
+        value: "assert",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}
 function resolvePageMethods(methods) {
     if (!methods)
         return [];
@@ -884,6 +952,20 @@ export function definePageBlock(options) {
         enumerable: false,
         configurable: false,
     });
+    // Same marker `defineNavBlock` sets, same reason - a page hub with a
+    // `url` (deep-link) is exactly as "known, coverable" as a plain
+    // `defineNavBlock`, and in practice most real projects' own nav Blocks
+    // ARE page hubs (methods hanging off them), not bare NavBlocks - the real
+    // saucedemo fixture this whole package tests against uses definePageBlock
+    // for every one of its own nav-* Blocks. Missing this here meant the
+    // marker existed but was never actually set on any real project's Blocks.
+    if (typeof options.url === "string") {
+        Object.defineProperty(built, "__waygraphNavUrl", {
+            value: options.url,
+            enumerable: false,
+            configurable: false,
+        });
+    }
     if (options.url !== undefined || options.click !== undefined) {
         Object.defineProperty(built, "__waygraphPageDeepLink", {
             value: true,

package/dist/graph.d.ts

@@ -58,6 +58,24 @@ export declare function findOrphanBlocks(projectDir: string): Promise<OrphanBloc
  * edges. NavBlocks (`from: "*"`) count from any state.
  */
 export declare function findBlockPath(graph: WaygraphGraph, fromTag: string, toTag: string): string[] | null;
+export interface BlockPathStep {
+    block: string;
+    /** The specific Checkpoint this hop's edge targets - NOT re-derivable by
+     * looking up `block` by name afterward, since a union-Out Block (e.g.
+     * "Union Out tags create duplicate edges for the same Block", see
+     * `discoverGraph`'s own comment above) can have several edges with the
+     * same `block` name but different `to` tags; only the specific edge BFS
+     * actually routed through here is correct. */
+    to: string;
+}
+/**
+ * Same BFS as `findBlockPath`, but returns each hop's specific edge (block
+ * name + the Checkpoint it targets), not just the block name - needed by any
+ * caller that must verify a step actually landed where the route intended,
+ * not just re-guess it afterward. `findBlockPath` itself is unchanged and
+ * still used wherever only the block-name sequence matters.
+ */
+export declare function findBlockPathDetailed(graph: WaygraphGraph, fromTag: string, toTag: string): BlockPathStep[] | null;
 /**
  * Walks every `*.block.ts` file under `projectDir` and builds the app's own
  * state graph. Shares the same in-process-import limitation `waygraph

package/dist/graph.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, dirname, relative, resolve } from "node:path";
 import { matchBlocksSelect, } from "./blocks-select.js";
 /**
@@ -174,8 +174,49 @@ export function findBlockPath(graph, fromTag, toTag) {
     }
     return null;
 }
+/**
+ * Same BFS as `findBlockPath`, but returns each hop's specific edge (block
+ * name + the Checkpoint it targets), not just the block name - needed by any
+ * caller that must verify a step actually landed where the route intended,
+ * not just re-guess it afterward. `findBlockPath` itself is unchanged and
+ * still used wherever only the block-name sequence matters.
+ */
+export function findBlockPathDetailed(graph, fromTag, toTag) {
+    if (fromTag === toTag)
+        return [];
+    const queue = [{ tag: fromTag, path: [] }];
+    const visited = new Set([fromTag]);
+    while (queue.length > 0) {
+        const { tag, path } = queue.shift();
+        for (const edge of graph.edges) {
+            if (edge.from !== tag && edge.from !== "*")
+                continue;
+            const nextPath = [...path, { block: edge.block, to: edge.to }];
+            if (edge.to === toTag)
+                return nextPath;
+            if (!visited.has(edge.to)) {
+                visited.add(edge.to);
+                queue.push({ tag: edge.to, path: nextPath });
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Same real, confirmed reload-caching bug `auto-explore.ts`'s own copy of
+ * this function fixes (see its own comment) - `discoverGraph` (used for
+ * `this.graph`/path-finding) and `loadBlockLibrary` (used for `this.library`/
+ * the live menu) are two independent importers, each with their own
+ * duplicate `importModule`, so each needed the same mtime-based cache-bust
+ * fix separately - fixing only one left the other still serving a session's
+ * `reloadLibrary()` a stale (or, for a brand-new file only ever discovered
+ * through THIS path, silently absent) graph.
+ */
 async function importModule(filePath) {
-    const url = new URL(`file://${resolve(filePath)}`);
+    const resolved = resolve(filePath);
+    const url = new URL(`file://${resolved}`);
+    const mtimeMs = statSync(resolved).mtimeMs;
+    url.searchParams.set("t", String(mtimeMs));
     return (await import(url.href));
 }
 function isBlockLike(val) {
@@ -192,6 +233,10 @@ function isNavBlockMarked(val) {
     const kind = val.__waygraphKind;
     return kind === "nav" || kind === "page";
 }
+/** Set by `defineAssertBlock` (non-enumerable) - see src/engine.ts. */
+function isAssertBlockMarked(val) {
+    return val.__waygraphKind === "assert";
+}
 /**
  * Resolves `typeName` to every literal Checkpoint tag it can mean, within
  * one `*.states.ts` file's own source text - `type X = Checkpoint<"Tag">`
@@ -341,6 +386,24 @@ export async function discoverGraph(projectDir, opts) {
                 })) {
                 continue;
             }
+            if (isAssertBlockMarked(exported)) {
+                try {
+                    // Same input-independent resolve() shape Nav/Page Blocks already
+                    // get this shortcut for - defineAssertBlock's own resolve() is
+                    // always `() => checkpoint(options.checkpoint)`, so no <In, Out>
+                    // generic needs to appear in source text for this to be found.
+                    const resolveFn = exported.instruction.resolve;
+                    const resolved = await resolveFn(undefined);
+                    const to = resolved.__state;
+                    nodeTags.add(to);
+                    // Self-loop by construction (defineAssertBlock is self-loop-only).
+                    edges.push({ block: blockName, file: relFile, from: to, to, kind: "action" });
+                }
+                catch {
+                    skipped.push({ block: blockName, file: relFile, reason: "assertBlock resolve() threw" });
+                }
+                continue;
+            }
             if (isNavBlockMarked(exported)) {
                 try {
                     // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).

package/dist/highlights.d.ts

@@ -200,6 +200,20 @@ export declare function applyDevicePhase(prev: DeviceState | undefined, phase: {
     device: DeviceState | undefined;
     sync: "set" | "clear" | "keep";
 };
+/**
+ * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
+ * actual visual language `cli.ts`'s own demo stepper paints with. Extracted
+ * here (not left as a private `cli.ts` constant) so anything else wanting the
+ * SAME "waygraph vision" ring can import pure CSS text, not the rendering
+ * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
+ * module load with no `import.meta.url` guard, so importing anything from it
+ * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
+ * comment for the same reasoning re: the badge/panel). This file has always
+ * been the pure, side-effect-free home for tone/size/weight - the CSS that
+ * renders them belongs alongside it for the same reason. `cli.ts` imports
+ * this constant instead of keeping its own duplicate copy.
+ */
+export declare const WAYGRAPH_RING_CSS: string;
 /** One named highlight slot on a block (selector + caption). */
 export interface WaygraphHighlightStub extends FixtureDurationFields {
     selector: string;
@@ -445,8 +459,13 @@ export interface WaygraphSlide extends FixtureDurationFields {
 /**
  * Demo ring tones (iconified).
  * Automation (`auto`) is gray so authored planned/info/warning/danger/success stand out.
+ * `orange` added for Blind Pilot's own real, direct user request: a visible
+ * color distinction between a real Playwright-driven action (a Block run,
+ * or a raw click/type/upload - `auto` gray, already meant exactly this) and
+ * a pure DOM inspection (`auto dom` - orange, new) - "gray is waygraph
+ * playwright run. orange is dom check."
  */
-export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" | "success";
+export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" | "success" | "orange";
 /** Ring + label scale. */
 export type HighlightSize = "sm" | "md" | "lg";
 /** Label font weight. */

package/dist/highlights.js

@@ -183,6 +183,63 @@ export function applyDevicePhase(prev, phase) {
     }
     return { device: prev, sync: "keep" };
 }
+/**
+ * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
+ * actual visual language `cli.ts`'s own demo stepper paints with. Extracted
+ * here (not left as a private `cli.ts` constant) so anything else wanting the
+ * SAME "waygraph vision" ring can import pure CSS text, not the rendering
+ * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
+ * module load with no `import.meta.url` guard, so importing anything from it
+ * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
+ * comment for the same reasoning re: the badge/panel). This file has always
+ * been the pure, side-effect-free home for tone/size/weight - the CSS that
+ * renders them belongs alongside it for the same reason. `cli.ts` imports
+ * this constant instead of keeping its own duplicate copy.
+ */
+export const WAYGRAPH_RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
+    "border:2.5px solid #7C3AED;border-radius:10px;" +
+    // Opacity fade only - NEVER transition border-color/box-shadow. Tone swaps
+    // (auto gray -> planned purple -> warning yellow) must snap instantly;
+    // color transitions read as a muddy gray/purple/yellow morph on ring 2+.
+    "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
+    // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
+    // Automation (verify fallback, unmatched fill/click) = gray - operators
+    // can ignore engine checks and watch purple + semantic tones.
+    "#wg-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}" +
+    "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
+    "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
+    "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
+    "#wg-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}" +
+    "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}" +
+    // Real, direct user request: a visible color distinction between a real
+    // Playwright-driven action (auto gray, unchanged) and a pure DOM
+    // inspection (this - orange).
+    "#wg-ring[data-tone=orange]{border-color:#F97316;box-shadow:0 0 0 4px rgba(249,115,22,.22);}" +
+    // A real element, not a ::after pseudo-element - a pseudo-element's
+    // position is CSS-relative to the ring's own box (left:0 always meant
+    // "the ring's own left edge"), so it had no way to be clamped back onto
+    // screen when that box sat near a viewport edge - the label's text just
+    // ran off, invisibly, with no overflow guard at all. A real sibling can
+    // be measured (its actual rendered width) and repositioned in JS -
+    // pushed back onto screen, same width, never shrunk. See
+    // window.__wgPositionRing in cli.ts's own installOverlay.
+    "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
+    "max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:#7C3AED;color:#fff;" +
+    "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
+    "#wg-ring-label[data-tone=planned]{background:#7C3AED;color:#fff;}" +
+    "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
+    "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
+    "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
+    "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
+    "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
+    "#wg-ring-label[data-tone=orange]{background:#EA580C;color:#fff;}" +
+    // size: ring pad + label font; weight: label boldness
+    "#wg-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}" +
+    "#wg-ring[data-size=lg]{border-width:4px;border-radius:12px;}" +
+    "#wg-ring-label[data-size=sm]{font-size:10px;line-height:1.25;padding:4px 7px;border-radius:5px;}" +
+    "#wg-ring-label[data-size=lg]{font-size:16px;line-height:1.35;padding:8px 14px;border-radius:9px;max-width:min(480px,85vw);}" +
+    "#wg-ring-label[data-weight=bold]{font-weight:800;}" +
+    "#wg-ring-label[data-weight=normal]{font-weight:600;}";
 /** Apply Flow defaults under per-slot authored values (slot wins when set). */
 export function applyHighlightStyleDefaults(slot, defaults) {
     const tone = slot.tone !== undefined && slot.tone !== ""
@@ -209,6 +266,7 @@ const TONE_ICONS = {
     warning: "!",
     danger: "x",
     success: "+",
+    orange: "",
 };
 /** Map author aliases (`error` -> danger) to a canonical tone. */
 export function normalizeHighlightTone(raw) {
@@ -225,6 +283,8 @@ export function normalizeHighlightTone(raw) {
         return "danger";
     if (t === "success" || t === "ok" || t === "green")
         return "success";
+    if (t === "orange" || t === "amber" || t === "dom" || t === "inspect")
+        return "orange";
     if (t === "planned" || t === "purple" || t === "authored")
         return "planned";
     return "planned";

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInstanceOption } from "./types.js";
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
-export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export { Trait, urlMatches, textEquals, visible, 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, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.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, 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, 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, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";
@@ -18,3 +18,7 @@ export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, form
 export type { TraverseCoverageReport } from "./traverse-coverage.js";
 export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
 export type { WgModalKind, WgBeaconRow } from "./overlay-beacon.js";
+export { AutoSession, stubFilePath } from "./auto-session.js";
+export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnapshotSection, ApplyPickResult, ApplyPathResult, TraceStep, ConsoleLogEntry, StorageSnapshot, ServiceWorkerRegistrationInfo, CookieInfo, StubFileKind, } from "./auto-session.js";
+export { pilotStart } from "./pilot.js";
+export type { PilotStartResult } from "./pilot.js";

package/dist/index.js

@@ -1,11 +1,13 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
-export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export { Trait, urlMatches, textEquals, visible, 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, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.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, 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 "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
 export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
+export { AutoSession, stubFilePath } from "./auto-session.js";
+export { pilotStart } from "./pilot.js";

package/dist/pilot-overlay.d.ts

@@ -0,0 +1,88 @@
+/**
+ * A small, self-contained on-page indicator for a live AutoSession -
+ * "this browser is being driven by Waygraph," plus an expandable panel
+ * showing the session's own current live menu. Real, direct user request:
+ * a headful Pilot session looks like an ordinary browser tab with no
+ * indication anything is driving it, which matters once a human might be
+ * co-driving the same visible session (see `AutoSession.resync()`'s own
+ * doc comment for the related state-desync problem that scenario causes).
+ *
+ * Deliberately NOT built on `src/cli.ts`'s own demo-panel/banner overlay
+ * system, for the same reason `pilot-v1`'s narrate-mode ring renderer
+ * wasn't either (see the git history at tag
+ * `waygraph-pilot-v1-logs-prettified`): `cli.ts` runs `main().catch(...)`
+ * unconditionally at module load with no `import.meta.url` guard, so
+ * importing anything from it here would trigger the whole CLI's argument
+ * dispatch as a side effect of loading a library module - unsafe. This
+ * ships its own small, purpose-built badge + panel instead.
+ */
+import type { Page } from "@playwright/test";
+import type { SessionSnapshot } from "./auto-session.js";
+import { type HighlightTone } from "./highlights.js";
+/**
+ * Bottom-left transient toast, separate from the persistent bottom-right
+ * badge - real, direct user request: something that visibly flags "a
+ * command is running" / "the map just changed" distinct from the
+ * always-on Checkpoint badge. Self-clearing (CSS fade after a timeout),
+ * not tied to the next `currentMenu()` snapshot the way the badge is,
+ * since some callers (rawClick/rawType/rawGoto/reloadLibrary/applyPick)
+ * only call `currentMenu()` again once the whole operation - including
+ * this toast's own lifetime - should already be over.
+ */
+export declare function showPilotActivity(page: Page, text: string): Promise<void>;
+/**
+ * "browser-use"-style vision box: a ring drawn around the exact element
+ * `auto dom --selector <sel>` just inspected, so a human watching a headful
+ * Pilot session can see what the agent is actually looking at, not just a
+ * JSON blob in a terminal. Real, direct user request.
+ *
+ * Reuses the real `#wg-ring`/`#wg-ring-label` elements + `WAYGRAPH_RING_CSS`
+ * (see `highlights.ts`) - the exact same visual language `cli.ts`'s own demo
+ * stepper paints rings with, not a separate look-alike. Still a purpose-built
+ * renderer here (position/show/hide only, via plain `getBoundingClientRect` -
+ * no camera zoom/spotlight/todo-dock/pacing), since that whole engine still
+ * lives in `cli.ts`, which this file continues to avoid importing (see this
+ * file's own header). Auto-fades a few real seconds after showing (or
+ * sooner if explicitly replaced/hidden first) - tuned live twice: an
+ * original 2.5s fade read as gone before it could be seen, a since-tried
+ * "stay up indefinitely" alternative read as lingering clutter instead.
+ *
+ * `tone` defaults to "auto" (gray) - real, direct user request: "gray is
+ * waygraph playwright run. orange is dom check" - a real Block run or a
+ * raw click/type/upload IS a real Playwright-driven action (`auto` was
+ * always documented as meaning exactly that), while a pure `auto dom` read
+ * touches nothing, so it gets its own "orange" tone instead.
+ */
+export declare function showPilotVision(page: Page, selector: string, label: string, tone?: HighlightTone): Promise<void>;
+/** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
+export interface PilotOverlayGraph {
+    nodes: readonly {
+        checkpoint: string;
+    }[];
+    edges: readonly {
+        block: string;
+        from: string;
+        to: string;
+        kind: "nav" | "action";
+    }[];
+}
+export interface PilotOverlayInfo {
+    sessionId: string | undefined;
+    snapshot: SessionSnapshot;
+    /**
+     * The WHOLE project's graph, not just what's reachable from the current
+     * page - real, direct user request: "i have a button where it shows all
+     * the nodes like a node tree stuff". Optional so a caller that doesn't
+     * have it handy (or doesn't want the extra payload every call) can omit
+     * it; the "All nodes" tab just shows nothing until one arrives.
+     */
+    graph?: PilotOverlayGraph;
+}
+/**
+ * Refreshes the badge text and the (possibly-collapsed) panel's two tabs
+ * ("Here" - current live menu; "All nodes" - whole project graph as a
+ * tree). Never throws - a page mid-navigation when this fires is a real,
+ * expected timing case, not an error worth failing the caller's own real
+ * operation over.
+ */
+export declare function updatePilotOverlay(page: Page, info: PilotOverlayInfo): Promise<void>;