waygraph 0.15.53 → 0.16.0

package/dist/engine/run/hooks.d.ts

@@ -0,0 +1,16 @@
+import type { Page } from "@playwright/test";
+/** One HTTP call a Block made on its own (`defineApiBlock`), for whatever is showing network activity. */
+export interface ApiCallRecord {
+    method: string;
+    url: string;
+    status: number;
+    ok: boolean;
+    ms: number;
+    resHeaders?: Record<string, string> | undefined;
+    resBody?: string | undefined;
+}
+type ApiCallRecorder = (page: Page, entry: ApiCallRecord) => void | Promise<void>;
+/** The demo layer registers how an API call is shown (the network panel). Without one, calls are not recorded. */
+export declare function setApiCallRecorder(recorder: ApiCallRecorder | undefined): void;
+export declare function recordApiCall(page: Page, entry: ApiCallRecord): Promise<void>;
+export {};

package/dist/engine/run/hooks.js

@@ -0,0 +1,8 @@
+let apiCallRecorder;
+/** The demo layer registers how an API call is shown (the network panel). Without one, calls are not recorded. */
+export function setApiCallRecorder(recorder) {
+    apiCallRecorder = recorder;
+}
+export async function recordApiCall(page, entry) {
+    await apiCallRecorder?.(page, entry);
+}

package/dist/engine/run/launch.d.ts

@@ -0,0 +1,13 @@
+import type { BrowserContext } from "@playwright/test";
+import type { EngineConfig } from "../config.js";
+/** A browser context an Engine opened for itself, and how to close it again. */
+export interface OwnContext {
+    context: BrowserContext;
+    close(): Promise<void>;
+}
+type OwnContextLauncher = (config: EngineConfig | undefined) => Promise<OwnContext>;
+/** The runtime layer registers the full launch (selected config, Chromium path, extensions); see `runtime/full-launch.ts`. */
+export declare function setOwnContextLauncher(next: OwnContextLauncher): void;
+/** Opens the browser and context a `Flow.run(mem)` uses when the caller gave none. */
+export declare function launchOwnContext(config: EngineConfig | undefined): Promise<OwnContext>;
+export {};

package/dist/engine/run/launch.js

@@ -0,0 +1,27 @@
+import { resolveLauncher } from "../config.js";
+import { envString } from "../env.js";
+/** Plain Playwright launch: what an Engine does when nothing richer is registered (no config file, no extensions). */
+async function plainLaunch(config) {
+    if (config?.extensions?.length) {
+        throw new Error('waygraph: browser extensions need the runtime layer - import the Engine from "waygraph"');
+    }
+    const browser = await resolveLauncher(config?.browserName ?? "chromium", config).launch({
+        headless: config?.headless ?? true,
+        ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+    });
+    const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
+    const context = await browser.newContext({
+        ...(baseURL ? { baseURL } : {}),
+        ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+    });
+    return { context, close: () => browser.close() };
+}
+let launcher = plainLaunch;
+/** The runtime layer registers the full launch (selected config, Chromium path, extensions); see `runtime/full-launch.ts`. */
+export function setOwnContextLauncher(next) {
+    launcher = next;
+}
+/** Opens the browser and context a `Flow.run(mem)` uses when the caller gave none. */
+export function launchOwnContext(config) {
+    return launcher(config);
+}

package/dist/{core/run-graph.d.ts → engine/run/run.d.ts}

@@ -1,16 +1,18 @@
-import { MemPage } from "../mem-page.js";
-import type { Block, Checkpoint } from "../types.js";
-import type { Trait } from "../trait.js";
+import { MemPage } from "../mem/mem.js";
+import type { Block } from "../block/block.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Trait } from "../trait/trait.js";
 import type { BrowserContext, Locator, Page } from "@playwright/test";
+import type { SomeBlock } from "../block/block.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
- * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
+ * composed Block, so calling this on a `map()`-built Flow's entry - which
  * `runGraph` does automatically, before opening a tab - covers every Block in
  * that flow. It does not see Blocks only reachable through `branch()` routing,
  * since those depend on a runtime decision that hasn't happened yet.
  */
-export declare function preflight(mem: MemPage, block: Block<any, any>): void;
+export declare function preflight(mem: MemPage, block: SomeBlock): void;
 /**
  * A cross-cutting, automatically-enforced verify - the real engine
  * primitive behind "persistent UI" (a sidebar, a header, anything that's
@@ -36,6 +38,7 @@ export interface Layout {
     /** Function form gets the full resolved Checkpoint, same shape `runVerify`/a Block's own `verify` already use - not just the tag. */
     verify: Trait[] | ((out: Checkpoint<string>) => Trait[]);
 }
+/** Options for `defineLayout`: which Checkpoints it applies to and the Traits it enforces. */
 export interface LayoutOptions {
     name: string;
     description?: string;
@@ -72,7 +75,7 @@ export declare function defineLayout(options: LayoutOptions): Layout;
  * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
  * one of the tags the caller actually expects, or the run fails loud instead of
  * silently returning an unexpected result. Omit it when there is only ever one
- * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
+ * reachable outcome by construction (as with a `map()`-built Flow, which has
  * no routing at all) - there is nothing to validate against.
  */
 export declare function runGraph<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, terminals: ReadonlySet<string> | undefined, context: BrowserContext, mem: MemPage, maxSteps?: number, options?: RunGraphOptions): Promise<TOut>;
@@ -140,8 +143,3 @@ export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<C
  * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
  */
 export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;
-/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
-export declare const start: unique symbol;
-export declare const end: unique symbol;
-export type StartMarker = typeof start;
-export type EndMarker = typeof end;

package/dist/{core/run-graph.js → engine/run/run.js}

@@ -1,10 +1,12 @@
 import { WaygraphError, MSG_PREFLIGHT_MISSING_KEY, MSG_RUNGRAPH_MAX_STEPS, MSG_RUNGRAPH_NOT_TERMINAL } from "../errors.js";
-import { checkpoint } from "../types.js";
-import { runPrecondition, runVerify } from "../trait.js";
+import { checkpoint } from "../checkpoint/checkpoint.js";
+import { beginRun, endRun, isConnected, lastLeaf, stepEnded, stepFailed, stepStarted } from "./events.js";
+import { runPrecondition, runVerify } from "../trait/trait.js";
+import { ignorePageGone } from "../page-gone.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
- * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
+ * composed Block, so calling this on a `map()`-built Flow's entry - which
  * `runGraph` does automatically, before opening a tab - covers every Block in
  * that flow. It does not see Blocks only reachable through `branch()` routing,
  * since those depend on a runtime decision that hasn't happened yet.
@@ -70,15 +72,17 @@ async function runLayouts(layouts, tag, out, page, mem, blockName) {
  * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
  * one of the tags the caller actually expects, or the run fails loud instead of
  * silently returning an unexpected result. Omit it when there is only ever one
- * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
+ * reachable outcome by construction (as with a `map()`-built Flow, which has
  * no routing at all) - there is nothing to validate against.
  */
 export async function runGraph(entry, terminals, context, mem, maxSteps = 5000, options) {
     preflight(mem, entry);
     const page = options?.page ?? (await context.newPage());
     const closeOnFinish = options?.closeOnFinish ?? true;
+    const opened = beginRun();
+    let result;
+    let failure;
     try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let current = entry;
         let input = checkpoint("__start__");
         let steps = 0;
@@ -86,6 +90,8 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             if (++steps > maxSteps) {
                 throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", MSG_RUNGRAPH_MAX_STEPS(maxSteps));
             }
+            if (!isConnected(current))
+                stepStarted(current.name, input.__state);
             await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
             const observed = current.instruction.observe
@@ -94,18 +100,26 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             const checkpoint = await current.instruction.resolve(observed);
             await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
             await runLayouts(options?.layouts, checkpoint.__state, checkpoint, page, mem, current.name);
+            stepEnded(lastLeaf(current), checkpoint.__state);
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
                     throw new WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", MSG_RUNGRAPH_NOT_TERMINAL(current.name, checkpoint.__state, [...terminals].join(", ")));
                 }
+                result = checkpoint.__state;
                 return checkpoint;
             }
             current = next;
             input = checkpoint;
         }
     }
+    catch (err) {
+        failure = err;
+        stepFailed(err);
+        throw err;
+    }
     finally {
+        endRun(opened, failure === undefined ? { ...(result !== undefined ? { result } : {}) } : { error: failure });
         if (closeOnFinish) {
             await page.close();
         }
@@ -177,7 +191,7 @@ export async function narrate(locator, caption, action) {
                 // true; narrate() below is the one that actually clears it.
                 w.__wgNarrateOwnsRing = true;
             }, { box, caption })
-                .catch(() => { });
+                .catch(ignorePageGone);
             owning = true;
             // The ring alone is pointless if action() fires on the very next
             // tick - a click that navigates (e.g. a form submit) wipes the ring
@@ -195,7 +209,7 @@ export async function narrate(locator, caption, action) {
                 .evaluate(() => {
                 globalThis.__wgLastNarrate = Date.now();
             })
-                .catch(() => { });
+                .catch(ignorePageGone);
         }
     }
     catch {
@@ -213,10 +227,7 @@ export async function narrate(locator, caption, action) {
                 if (w.__wgHideRing)
                     w.__wgHideRing();
             })
-                .catch(() => { });
+                .catch(ignorePageGone);
         }
     }
 }
-/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
-export const start = Symbol("waygraph.start");
-export const end = Symbol("waygraph.end");

package/dist/engine/stub/pace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Demo pacing for a Flow episode or a Block/compose group.
+ * - `blitz` - FF-like: skip theater + short gates (same as fastForwardComposeBlock)
+ * - `fast` - shorter gates, keep cursor theater (~0.33x normal)
+ * - `normal` - default demo pace (1x)
+ * - `slow` - longer autoplay + fixture dwell (~2x)
+ * - `number` - scale vs normal when `<= 20` (e.g. `0.5`, `1.5`, `3`);
+ *   absolute gate/dwell ms when `> 20` (e.g. `4500`)
+ */
+export type DemoPaceName = "blitz" | "fast" | "normal" | "slow";
+/** How fast a demo step runs: `"fast"`, `"slow"`, `"blitz"`, `"normal"`, or a multiplier (`0.5`, `2`). */
+export type DemoPace = DemoPaceName | number;

package/dist/engine/stub/pace.js

@@ -0,0 +1,2 @@
+// How fast a demo step plays.
+export {};

package/dist/engine/stub/ring.d.ts

@@ -0,0 +1,130 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+/** Shared dwell fields on stubs, fixtures, and yap slides. */
+export type FixtureDurationFields = {
+    /**
+     * Min time this fixture stays visible before the demo advances.
+     * - `true` - defaults (2000ms normal, {@link FixtureDurationFields.fastMode} or 600ms when --fast)
+     * - `number` - override normal dwell ms
+     * - omit / false - no authored dwell (caller keeps its default timing)
+     */
+    duration?: boolean | number;
+    /**
+     * Dwell ms when demo `--fast` / gatesFast (only when {@link duration} is set).
+     * Default 600.
+     */
+    fastMode?: number;
+};
+/** One named highlight slot on a block (selector + caption). */
+export interface WaygraphHighlightStub extends FixtureDurationFields {
+    selector: string;
+    /** Primary caption line. */
+    label: string;
+    /** Extra caption line (ring / slide body). */
+    detail?: string;
+    /** Short badge, e.g. AC / BUG / GATE / YAP. */
+    tag?: string;
+    /**
+     * Demo ring color + icon:
+     * - `planned` purple (authored narration, default)
+     * - `auto` gray (engine automation / verify fallback)
+     * - `info` blue · `warning` yellow · `danger` red · `success` green
+     */
+    tone?: HighlightTone;
+    /**
+     * Ring padding + label font scale: `sm` | `md` (default) | `lg`.
+     * Aliases: small/medium/large, s/m/l.
+     */
+    size?: HighlightSize;
+    /**
+     * Label font weight: `normal` (default) | `bold`.
+     * Aliases: regular, strong.
+     */
+    weight?: HighlightWeight;
+    /**
+     * Camera zoom while this ring is up (Screen Studio style - page scales toward
+     * the target / cursor). Typical `1.25` .. `2`. Cleared when the ring hides
+     * unless `zoomOut: false`. Episode default: {@link StubCtx.zoom}.
+     */
+    zoom?: number;
+    /**
+     * When false, keep the camera zoomed after this ring (pan to the next target
+     * instead of zooming out). Default true. Phase default: {@link StubCtx.zoomOut}.
+     */
+    zoomOut?: boolean;
+    /**
+     * Spotlight: dim the rest of the page, keep this target as the focal point.
+     */
+    focus?: boolean;
+    /**
+     * Caption text color (CSS color). Overrides tone label color when set.
+     */
+    color?: string;
+    /**
+     * Move the demo cursor to the target while this ring is up (default true
+     * for authored stub queues; set false to keep cursor hidden).
+     */
+    cursor?: boolean;
+    /**
+     * Optional link to a todo item id. When set, Method fill/click advances that
+     * todo row instead of relying on stub array index (avoids password/submit/username
+     * alphabetical reorder bugs).
+     */
+    todo?: string;
+    /** Slot key from stubBefore/After map (e.g. "username") - set by resolver. */
+    slotId?: string;
+    /**
+     * Pointer feel when touchMode is on (0.13+):
+     * - `tap` - short press via touchscreen (default in touch mode)
+     * - `hold` - long-press (~600ms) then release
+     * - `click` - mouse click even in touch mode
+     */
+    gesture?: "tap" | "hold" | "click" | "swipe";
+}
+/** A static stub phase: named ring slots to paint before or after a step. */
+export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
+/**
+ * One yap/slide in a multi-step demo caption sequence.
+ * Not block lifecycle - demo pauses (Next / auto-next) between slides.
+ */
+export interface WaygraphSlide extends FixtureDurationFields {
+    /** Primary caption (required). */
+    caption: string;
+    detail?: string;
+    tag?: string;
+    /** Optional ring while this slide is showing. */
+    selector?: string;
+    tone?: HighlightTone;
+    size?: HighlightSize;
+    weight?: HighlightWeight;
+    /** Magnify via camera (Screen Studio) while this slide is showing. */
+    zoom?: number;
+}
+/**
+ * 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" | "orange";
+/** Ring + label scale. */
+export type HighlightSize = "sm" | "md" | "lg";
+/** Label font weight. */
+export type HighlightWeight = "normal" | "bold";
+/** Optional Flow-level defaults for demo rings (episode-wide). Stub/fixture wins. */
+export type HighlightStyleDefaults = {
+    tone?: HighlightTone;
+    size?: HighlightSize;
+    weight?: HighlightWeight;
+};
+export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
+/** A ring or caption after its defaults and overrides are merged, ready to paint. */
+export type ResolvedHighlight = WaygraphHighlightStub;
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
+/** Map size aliases to sm/md/lg. */
+export declare function normalizeHighlightSize(raw: unknown): HighlightSize;
+/** Map weight aliases to normal/bold. */
+export declare function normalizeHighlightWeight(raw: unknown): HighlightWeight;

package/dist/engine/stub/ring.js

@@ -0,0 +1,41 @@
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export function normalizeHighlightTone(raw) {
+    if (typeof raw !== "string")
+        return "planned";
+    const t = raw.trim().toLowerCase();
+    if (t === "auto" || t === "automation" || t === "engine")
+        return "auto";
+    if (t === "info" || t === "blue")
+        return "info";
+    if (t === "warning" || t === "warn" || t === "yellow")
+        return "warning";
+    if (t === "danger" || t === "error" || t === "red")
+        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";
+}
+/** Map size aliases to sm/md/lg. */
+export function normalizeHighlightSize(raw) {
+    if (typeof raw !== "string")
+        return "md";
+    const t = raw.trim().toLowerCase();
+    if (t === "sm" || t === "s" || t === "small" || t === "tiny")
+        return "sm";
+    if (t === "lg" || t === "l" || t === "large" || t === "big" || t === "xl")
+        return "lg";
+    return "md";
+}
+/** Map weight aliases to normal/bold. */
+export function normalizeHighlightWeight(raw) {
+    if (typeof raw !== "string")
+        return "normal";
+    const t = raw.trim().toLowerCase();
+    if (t === "bold" || t === "strong" || t === "heavy" || t === "b")
+        return "bold";
+    return "normal";
+}