waygraph 0.13.7 → 0.15.0

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, defineLayout, map, MapBuilder, } 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, Layout, LayoutOptions, MapBuilderOptions, } 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, defineLayout, map, MapBuilder, } 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/map-check.d.ts

@@ -0,0 +1,18 @@
+export interface MapViolation {
+    file: string;
+    block: string;
+    reason: string;
+}
+export interface MapNode {
+    block: string;
+    checkpoint: string | undefined;
+    file: string;
+    kind: "nav" | "page" | "other";
+}
+export interface MapCheckResult {
+    mapRoot: string;
+    hasMapDir: boolean;
+    nodes: MapNode[];
+    violations: MapViolation[];
+}
+export declare function checkMap(projectDir: string): Promise<MapCheckResult>;

package/dist/map-check.js

@@ -0,0 +1,140 @@
+/**
+ * `waygraph map` - enforcement for the Waygraph Map folder convention.
+ * Real, direct user correction: this is not just a naming preference, it's
+ * a forced structure. Requires `src/map/` to exist, and for every Nav/Page
+ * Block whose `url` is a plain string, the folder path (relative to
+ * `src/map/`, with `(group)` segments excluded - those are intentionally
+ * invisible in the real URL, same as Next.js route groups) must verbatim
+ * match the URL's own real pathname segments, in order. Catches exactly
+ * the class of bug a live session found: `(auth)/signin/` grouping a page
+ * whose real URL is `/signin`, not `/auth/signin` - a fabricated grouping
+ * that never matched the real site.
+ *
+ * Self-contained (no import from cli.ts), same reasoning as graph.ts's own
+ * header comment: cli.ts runs main() unconditionally at module load.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+function walkBlockFiles(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
+                continue;
+            results.push(...walkBlockFiles(full));
+        }
+        else if (/\.block\.ts$/.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+async function importModule(filePath) {
+    const url = pathToFileURL(filePath);
+    const mtimeMs = statSync(filePath).mtimeMs;
+    url.searchParams.set("t", String(mtimeMs));
+    return (await import(url.href));
+}
+/**
+ * `(group)` segments never appear in the real URL (Next.js route-group
+ * convention this whole system is explicitly modeled on) - excluded from
+ * the comparison, not just cosmetically ignored by discoverGraph.
+ *
+ * A leading-underscore segment (`_methods/`, same as Next.js's own private-
+ * folder convention) is the fixed machinery belonging to ONE endpoint - not
+ * a route segment of its own - excluded from the comparison for the same
+ * reason `(group)` is: real direct request answering "so i have clear
+ * distinction of endpoints vs block folders" - a bare (non-underscore,
+ * non-parenthesized) folder name always means a real child Checkpoint/URL
+ * segment, no exceptions, so `_methods/foo.block.ts` never gets mistaken
+ * for a sibling endpoint the way a bare `methods/` folder structurally
+ * could be.
+ */
+function realSegments(relPath) {
+    return dirname(relPath)
+        .split(sep)
+        .filter((s) => s !== "." && s !== "" && !/^\(.*\)$/.test(s) && !s.startsWith("_"));
+}
+export async function checkMap(projectDir) {
+    const mapRoot = join(projectDir, "src", "map");
+    if (!existsSync(mapRoot)) {
+        return { mapRoot, hasMapDir: false, nodes: [], violations: [] };
+    }
+    const files = walkBlockFiles(mapRoot);
+    const nodes = [];
+    const violations = [];
+    for (const file of files) {
+        const relFile = relative(projectDir, file);
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch (err) {
+            violations.push({
+                file: relFile,
+                block: "(import failed)",
+                reason: err instanceof Error ? err.message.split("\n")[0] : String(err),
+            });
+            continue;
+        }
+        for (const exported of Object.values(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            const waygraphKind = exported.__waygraphKind;
+            const kind = waygraphKind === "nav" ? "nav" : waygraphKind === "page" ? "page" : "other";
+            const navUrl = exported.__waygraphNavUrl;
+            let checkpoint;
+            const instruction = exported.instruction;
+            if (instruction?.resolve && typeof instruction.resolve === "function") {
+                try {
+                    const out = (await instruction.resolve(undefined));
+                    checkpoint = out?.__state;
+                }
+                catch {
+                    /* resolve() needing real input (a Method Block) - not position-defining, skip */
+                }
+            }
+            nodes.push({ block: exported.name, checkpoint, file: relFile, kind });
+            if (typeof navUrl !== "string")
+                continue; // only statically-urled Nav/Page Blocks are checkable
+            let pathname;
+            try {
+                pathname = new URL(navUrl).pathname;
+            }
+            catch {
+                continue; // a relative/templated URL - not verbatim-checkable
+            }
+            const urlSegments = pathname.split("/").filter(Boolean);
+            const folderSegments = realSegments(relative(mapRoot, file));
+            const matches = urlSegments.length === folderSegments.length && urlSegments.every((s, i) => s === folderSegments[i]);
+            if (!matches) {
+                violations.push({
+                    file: relFile,
+                    block: exported.name,
+                    reason: `folder path "${folderSegments.join("/")}" doesn't verbatim-match the real URL path ` +
+                        `"${urlSegments.join("/")}" (${navUrl}) - (group) segments are excluded from this comparison, ` +
+                        "everything else must match exactly, same as Next.js file-based routing",
+                });
+            }
+        }
+    }
+    return { mapRoot, hasMapDir: true, nodes, violations };
+}

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>;