waygraph 0.15.53 → 0.16.0

package/dist/{core → engine/flow}/map-builder.js

@@ -1,9 +1,8 @@
 import { WaygraphError, MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_SALT, MSG_MAP_WRONG_ORIGIN_INTERNAL, MSG_MAP_WRONG_ORIGIN_EXTERNAL, MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED, MSG_MAP_FF_ALREADY_OPEN, MSG_MAP_FF_NOT_OPEN, MSG_MAP_FF_EMPTY, MSG_MAP_METHOD_GOT_ASSERT, MSG_MAP_BRANCH_NO_PRIOR_STEP, MSG_MAP_FF_NOT_CLOSED, MSG_MAP_EMPTY, } from "../errors.js";
-import { end, start } from "./run-graph.js";
-import { MemPage } from "../mem-page.js";
-import { fastForwardComposeBlock } from "./compose.js";
-import { clearSessionState, withBlockPace } from "./flow.js";
-import { copyWaygraphRuntime } from "./block.js";
+import { MemPage } from "../mem/mem.js";
+import { fastForwardComposeBlock } from "../block/compose.js";
+import { clearSessionState } from "./flow.js";
+import { copyWaygraphRuntime } from "../block/block.js";
 /** Per-step options every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
 /** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
 function resetBefore(block) {
@@ -24,7 +23,11 @@ function resetBefore(block) {
 }
 /** Applies a step's `pace` option, keeping the Block's runtime markers. */
 function paced(block, opts) {
-    return (opts?.pace === undefined ? block : withBlockPace(block, opts.pace));
+    if (opts?.pace === undefined)
+        return block;
+    const next = { ...block, demoPace: opts.pace };
+    copyWaygraphRuntime(block, next);
+    return next;
 }
 function mapKindOf(block) {
     return block?.__waygraphKind;
@@ -44,6 +47,7 @@ const MAP_KIND_FACTORY_HINT = {
 const MAP_SALT_FACTORY_HINT = {
     method: "defineMethodBlock",
     effect: "defineEffectBlock",
+    api: "defineApiBlock",
 };
 function assertMapKind(block, allowed, method) {
     const kind = mapKindOf(block);
@@ -113,15 +117,14 @@ function buildBranchedFlow(before, routes) {
     });
     return {
         resetSession: before.resetSession,
-        ...(before.title !== undefined ? { title: before.title } : {}),
+        config: before.config,
         ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
-        ...(before.highlightFixtures !== undefined ? { highlightFixtures: before.highlightFixtures } : {}),
         ...(before.demoPace !== undefined ? { demoPace: before.demoPace } : {}),
         ...(before.highlightStyle !== undefined ? { highlightStyle: before.highlightStyle } : {}),
         ...(before.memStub !== undefined ? { memStub: before.memStub } : {}),
         // Read by branchRoutes()/branchInfo() (branch-regression.ts) - real, ORDINARY (enumerable)
-        // properties, not hidden ones, specifically so a `with*` wrapper's `{ ...flow, ... }` spread
-        // (withSessionReset, withTitle, etc.) carries them through instead of silently dropping them -
+        // properties, not hidden ones, specifically so a `{ ...flow, ... }` spread (withSettings) carries them
+        // through instead of silently dropping them -
         // the same class of bug branch()'s missing copyWaygraphRuntime call already was.
         __wgBranch: { before, routes },
         // Static introspection (`waygraph graph`/list): the fixed prefix, plus every branch's own
@@ -141,7 +144,7 @@ function buildBranchedFlow(before, routes) {
     };
 }
 /**
- * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
+ * The flow builder behind `engine.map()` - see `map()`'s own doc
  * comment for why this exists. Each step method is scoped to exactly the
  * Block kind its name promises, checked at RUNTIME against the
  * `__waygraphKind`/`__waygraphSalt` markers `defineNavBlock`/`definePageBlock`/
@@ -149,34 +152,35 @@ function buildBranchedFlow(before, routes) {
  * (the same markers `graph.ts` and `map-check.ts` trust) - not just a type
  * hint, since a hand-rolled object can satisfy the TypeScript `Block<In,Out>`
  * shape without ever going through a real factory. Each call also
- * typechecks the accumulated Checkpoint chain exactly like `defineFlow`'s
- * own tuple overloads do (a step's `In` must equal the previous step's
+ * typechecks the accumulated Checkpoint chain (a step's `In` must equal the previous step's
  * `Out`) - this is what "no teleporting" means: there is no method on this
  * builder that can skip from one Checkpoint to an unrelated one without a
  * real, kind-correct Block in between.
  */
 export class MapBuilder {
-    defineFlow;
+    build;
+    settings;
     steps;
     homeOrigin;
     ff;
     constructor(
-    // A plain defineFlow-shaped function, not the whole Engine - see DefineFlowFn's own comment.
-    defineFlow, steps, homeOrigin, 
+    // From Engine.map(): see BuildFlowFn.
+    build, settings, steps, homeOrigin, 
     // `auto: true` = opened implicitly by a `{ ff: true }` step flag, not an explicit .ffStart() -
     // closes silently at the next non-flagged step (or at .end()/.branch()) instead of demanding a
     // matching .ffEnd(), since the author never opened anything they'd need to remember to close.
     ff = null) {
-        this.defineFlow = defineFlow;
+        this.build = build;
+        this.settings = settings;
         this.steps = steps;
         this.homeOrigin = homeOrigin;
         this.ff = ff;
     }
     /** @internal - use `engine.map()` or the standalone `map()` export. */
-    static begin(defineFlow, homeOrigin) {
-        return new MapBuilder(defineFlow, [], homeOrigin, null);
+    static begin(build, settings, homeOrigin) {
+        return new MapBuilder(build, settings, [], homeOrigin, null);
     }
-    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
+    /** Readable chain-opener. Returns `this` unchanged; entirely optional. */
     start() {
         return this;
     }
@@ -192,7 +196,7 @@ export class MapBuilder {
         const ffName = typeof name === "string" && name.trim()
             ? name.trim()
             : `ff-${this.steps.length + 1}`;
-        return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
+        return new MapBuilder(this.build, this.settings, this.steps, this.homeOrigin, {
             name: ffName,
             buffer: [],
             auto: false,
@@ -216,10 +220,8 @@ export class MapBuilder {
         if (ff.buffer.length === 0) {
             throw new WaygraphError("WG_MAP_FF_EMPTY", MSG_MAP_FF_EMPTY(ff.name));
         }
-        const composed = fastForwardComposeBlock(ff.name, 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        ff.buffer);
-        return new MapBuilder(this.defineFlow, [...this.steps, composed], this.homeOrigin, null);
+        const composed = fastForwardComposeBlock(ff.name, ff.buffer);
+        return new MapBuilder(this.build, this.settings, [...this.steps, composed], this.homeOrigin, null);
     }
     /**
      * `ff`: inline fast-forward, no `.ffStart()/.ffEnd()` bracket needed - `.method(X, { ff: true })`
@@ -232,7 +234,7 @@ export class MapBuilder {
     appendStep(block, ff) {
         if (ff) {
             const win = this.ff ?? { name: `ff-${this.steps.length + 1}`, buffer: [], auto: true };
-            return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
+            return new MapBuilder(this.build, this.settings, this.steps, this.homeOrigin, {
                 name: win.name,
                 buffer: [...win.buffer, block],
                 auto: win.auto,
@@ -243,20 +245,20 @@ export class MapBuilder {
         }
         if (this.ff) {
             // Explicit .ffStart() window still open - absorbs a plain step too, same as always.
-            return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
+            return new MapBuilder(this.build, this.settings, this.steps, this.homeOrigin, {
                 name: this.ff.name,
                 buffer: [...this.ff.buffer, block],
                 auto: false,
             });
         }
-        return new MapBuilder(this.defineFlow, [...this.steps, block], this.homeOrigin, null);
+        return new MapBuilder(this.build, this.settings, [...this.steps, block], this.homeOrigin, null);
     }
     /**
      * Appends an internal navigation/page-arrival step - requires a Block from
      * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
      * anything else, including a `homeOrigin`-mismatched static `url`.
      * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
-     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     gotoPage(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoPage");
@@ -268,7 +270,7 @@ export class MapBuilder {
      * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
      * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
      * Compile-time: {@link NavBlock} or {@link PageBlock} only.
-     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     gotoExternal(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoExternal");
@@ -278,7 +280,7 @@ export class MapBuilder {
     /**
      * Appends a self-loop verification step - requires a Block from
      * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
-     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     assert(block, opts) {
         assertMapKind(block, ["assert"], "assert");
@@ -291,24 +293,25 @@ export class MapBuilder {
      * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
      * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
      * "assert"` (those still carry method salt from the factory internals).
-     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     method(block, opts) {
         if (mapKindOf(block) === "assert") {
             throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_METHOD_GOT_ASSERT(block.name));
         }
-        assertMapSalt(block, ["method", "effect"], "method");
+        assertMapSalt(block, ["method", "effect", "api"], "method");
         return this.appendStep(paced(block, opts), opts?.ff);
     }
     /**
      * Runs another flow's steps inline here, in the same page, browser and `mem`. This is how flows nest:
      * `map().flow(loginFlow).flow(viewerFlow, { reset: true })`. With `{ reset: true }` cookies and storage are cleared
-     * right before the sub-flow's first step. Replaces `chainFlow` and `withSessionReset`.
+     * right before the sub-flow's first step.
      */
     flow(sub, opts) {
+        // The steps' types live in `sub`; at runtime this is one untyped walk, typed again as the sub-flow's last Checkpoint.
         let next = this;
         sub.blocks().forEach((info, i) => {
-            const block = i === 0 && opts?.reset ? resetBefore(info.block) : info.block;
+            const block = i === 0 && (opts?.reset ?? sub.resetSession) ? resetBefore(info.block) : info.block;
             next = next.appendStep(block);
         });
         return next;
@@ -325,7 +328,7 @@ export class MapBuilder {
      * Checkpoint to chain `.method()/.gotoPage()/.assert()/.end()` (or another `.branch()`) off of.
      *
      * Real gap this fixes: the plain `branch()` helper's `.next` routing is only ever consulted by
-     * `runGraph`'s own graph walk - `defineFlow`/`.end()` compose steps pairwise via `connect()`,
+     * `runGraph`'s own graph walk - `.end()` composes steps pairwise via `connect()`,
      * which never looks at `.next` at all, so a Map-built Flow had no way to branch. This method
      * branches at the Flow level instead: it finalizes the prefix, runs it, and picks the next Flow
      * itself once the real tag is known - no engine-level routing involved.
@@ -336,7 +339,7 @@ export class MapBuilder {
      *
      * The route's first Block still sees `input.__state === "__start__"` in `act()`, not the tag that
      * routed there - `runGraph` seeds every Flow's entry Block that way unconditionally, the same as
-     * any standalone `defineFlow([start, block, end])` already does. Read `page`/`mem`, not `input`,
+     * any single-Block Flow does. Read `page`/`mem`, not `input`,
      * in `act()` - every real Block in this codebase already follows that convention.
      *
      * @example
@@ -352,32 +355,27 @@ export class MapBuilder {
         const before = this.end();
         const resolvedRoutes = {};
         for (const [tag, fn] of Object.entries(routes)) {
-            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.defineFlow, [], this.homeOrigin, null)) : null;
+            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.build, this.settings, [], this.homeOrigin, null)) : null;
         }
         return buildBranchedFlow(before, resolvedRoutes);
     }
     /**
-     * Finalizes this chain into a real, runnable {@link Flow} - same object
-     * `defineFlow` returns, so `withBlockVerify`/`modBlockVerify` and every
-     * `withTitle`/`withHighlightFixtures`/etc. decorator still apply exactly
-     * as they do today; this builder only changes how the chain is assembled,
-     * never what it produces. Throws if no step was ever added - an empty map
+     * Finalizes this chain into a runnable {@link Flow} with the settings given to `map({ ... })`;
+     * `withBlockVerify`/`modBlockVerify` work on it. Throws if no step was ever added - an empty map
      * isn't a flow. An auto-opened `{ ff: true }` window (see {@link MapStepOpts})
      * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
      * still throws - the author opened that one and needs to close it themselves.
      */
-    /** @param options @deprecated Pass flow settings to `map({ … })` instead. */
-    end(options) {
+    end() {
         if (this.ff && !this.ff.auto) {
             throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", MSG_MAP_FF_NOT_CLOSED(this.ff.name));
         }
         if (this.ff && this.ff.auto) {
-            return this.closeFf().end(options);
+            return this.closeFf().end();
         }
         if (this.steps.length === 0) {
             throw new WaygraphError("WG_MAP_EMPTY", MSG_MAP_EMPTY);
         }
-        const chain = [start, ...this.steps, end];
-        return this.defineFlow(chain, options);
+        return this.build(this.steps, this.settings);
     }
 }

package/dist/{core → engine}/locate.d.ts

@@ -1,4 +1,4 @@
-import type { NavBlock } from "./blocks/nav.js";
+import type { NavBlock } from "./block/kinds/nav.js";
 import type { Page } from "@playwright/test";
 /**
  * "Where am I" - reverse-matches a live `page` against every NavBlock /

package/dist/{core → engine}/locate.js

@@ -1,4 +1,4 @@
-import { MemPage } from "../mem-page.js";
+import { MemPage } from "./mem/mem.js";
 /**
  * "Where am I" - reverse-matches a live `page` against every NavBlock /
  * PageBlock in `library`, in order, returning the first one whose own `verify`
@@ -38,7 +38,6 @@ export async function locate(page, library, options) {
                 const traits = typeof verify === "function" ? verify(resolved) : (verify ?? []);
                 let allPass = true;
                 for (const trait of traits) {
-                    // eslint-disable-next-line no-await-in-loop
                     if (!(await trait.check(page, mem))) {
                         allPass = false;
                         break;

package/dist/{mem-stub.d.ts → engine/mem/mem-stub.d.ts}

@@ -6,18 +6,19 @@
  *
  * "Stub" here is unrelated to the other two meanings already in this
  * codebase: `stubBefore`/`stubAfter`/`stubOnError` (demo narration fixtures,
- * see highlights.ts's `runStubPhase`) and `upload`'s `stub: "image"|"pdf"|
+ * see demo/narration/index.ts's `runStubPhase`) and `upload`'s `stub: "image"|"pdf"|
  * "video"` (a placeholder file). This is a third, separate "stub."
  *
- * Opt-in only, per Flow (`withMemStub`, engine.ts) or per-run (`--mem-stub` /
+ * Opt-in only, per Flow (`map({ memStub: true })`) or per-run (`--mem-stub` /
  * WAYGRAPH_MEM_STUB=1) - a required key with no registered generator still
  * fails preflight exactly as before. Registered per MemKey *instance*
  * (identity, not `.name`), matching MemPage's own store - two keys sharing a
  * debug name must never cross-contaminate here either.
  */
-import type { MemKey } from "./mem-page.js";
-import type { MemPage } from "./mem-page.js";
-import type { Flow } from "./core.js";
+import type { MemKey } from "./mem.js";
+import type { MemPage } from "./mem.js";
+import type { Flow } from "../flow/flow.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
 /**
  * Registers a fake-value generator for one required MemKey.
  * @example registerMemStub(LoginCreds.key, () => ({
@@ -26,16 +27,16 @@ import type { Flow } from "./core.js";
  * }));
  */
 export declare function registerMemStub<T>(key: MemKey<T>, fake: () => T): void;
-/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub}/{@link withMemStub} instead. */
+/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub} and `map({ memStub: true })` instead. */
 export declare function getMemStub<T>(key: MemKey<T>): (() => T) | undefined;
 /**
  * For a bare library `flow.run(mem, ...)` call outside the CLI (which has its
  * own `--mem-stub`-aware seeding) - call this yourself before `run()` when
  * `flow.memStub` is true, the same way external tooling already reads
  * `flow.resetSession`/`flow.title`/etc. (`run()` itself never reads Flow
- * flags - see the `with*` helpers in engine.ts).
+ * flags; the settings come from `map({ ... })`).
  * @example
  * if (flow.memStub) seedMemStub(mem, flow);
  * await flow.run(mem, config);
  */
-export declare function seedMemStub(mem: MemPage, flow: Flow<any>): void;
+export declare function seedMemStub(mem: MemPage, flow: Flow<Checkpoint<string>>): void;

package/dist/{mem-stub.js → engine/mem/mem-stub.js}

@@ -9,7 +9,7 @@ const registry = new Map();
 export function registerMemStub(key, fake) {
     registry.set(key, fake);
 }
-/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub}/{@link withMemStub} instead. */
+/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub} and `map({ memStub: true })` instead. */
 export function getMemStub(key) {
     return registry.get(key);
 }
@@ -18,7 +18,7 @@ export function getMemStub(key) {
  * own `--mem-stub`-aware seeding) - call this yourself before `run()` when
  * `flow.memStub` is true, the same way external tooling already reads
  * `flow.resetSession`/`flow.title`/etc. (`run()` itself never reads Flow
- * flags - see the `with*` helpers in engine.ts).
+ * flags; the settings come from `map({ ... })`).
  * @example
  * if (flow.memStub) seedMemStub(mem, flow);
  * await flow.run(mem, config);

package/dist/{mem-page.d.ts → engine/mem/mem.d.ts}

@@ -55,7 +55,7 @@ export declare class MemPage {
      * can only have string/symbol property names, not object instances - a `[key,
      * value]` pair is the shape that keeps that identity-based guarantee.
      *
-     * Overloaded per pair count (2-6, same reasoning as `Engine.defineFlow`'s
+     * Overloaded per pair count (2-6, per-arity overloads like the old `defineFlow`'s
      * overloads) rather than one fully-generic variadic signature - each pair binds
      * its own type parameter independently, which TS checks reliably; a single
      * self-referential mapped-tuple-over-a-rest-parameter type was tried first and

package/dist/{mem-page.js → engine/mem/mem.js}

@@ -1,4 +1,5 @@
-import { WaygraphError, MSG_MEM_READ_BEFORE_SET } from "./errors.js";
+// Mem: the values a run carries between Blocks (credentials, the row just added), typed by MemKey.
+import { WaygraphError, MSG_MEM_READ_BEFORE_SET } from "../errors.js";
 /**
  * A typed key into MemPage. The phantom `_phantom` field is never assigned - it
  * exists only so TypeScript can infer `T` at each call site. The store is keyed by

package/dist/engine/page-gone.d.ts

@@ -0,0 +1,5 @@
+export declare function isPageGone(err: unknown): boolean;
+/** `.catch(ignorePageGone)`: the call is moot when the page went away; anything else is rethrown. */
+export declare function ignorePageGone(err: unknown): undefined;
+/** `.catch(ignoreTimeout)`: a probe that waited as long as it should (or whose page went away); anything else is rethrown. */
+export declare function ignoreTimeout(err: unknown): undefined;

package/dist/engine/page-gone.js

@@ -0,0 +1,20 @@
+// The failures a page call may ignore, and nothing else: the page went away (a navigation or a close), or a probe ran
+// out of time. Any other error is real and goes through.
+import { errors } from "@playwright/test";
+/** Playwright has no error class for a closed page or a destroyed document, only these messages. */
+const GONE = /Target page, context or browser has been closed|Target closed|Browser has been closed|Execution context was destroyed|frame was detached|Frame has been detached|Session closed|Cannot find context with specified id|Failed to find context with id/i;
+export function isPageGone(err) {
+    return err instanceof Error && GONE.test(err.message);
+}
+/** `.catch(ignorePageGone)`: the call is moot when the page went away; anything else is rethrown. */
+export function ignorePageGone(err) {
+    if (isPageGone(err))
+        return undefined;
+    throw err;
+}
+/** `.catch(ignoreTimeout)`: a probe that waited as long as it should (or whose page went away); anything else is rethrown. */
+export function ignoreTimeout(err) {
+    if (err instanceof errors.TimeoutError || isPageGone(err))
+        return undefined;
+    throw err;
+}

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

@@ -0,0 +1,28 @@
+import type { Block } from "../block/block.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Trait } from "../trait/trait.js";
+/**
+ * Structural twin of `run.ts`'s `Layout`, so this file needs no import from it. Any real `Layout` satisfies it with no
+ * cast at the `connect()` call site.
+ */
+export interface ConnectLayout {
+    name: string;
+    appliesTo: (tag: string) => boolean;
+    verify: Trait[] | ((out: any) => Trait[]);
+}
+/**
+ * Composes two Blocks into one, typechecked so this only compiles when A's output
+ * tag equals B's input tag. The composed Block's act runs A's full instruction
+ * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
+ * its own observe/resolve are simply B's, since B is what decides the final Out.
+ *
+ * `layouts`, if given, also runs against the intermediate Checkpoint (A's
+ * resolved output, right before B's act) - the same enforcement `runGraph`'s
+ * own loop already applies to a chain's FINAL Checkpoint, but a
+ * `map()`-built Flow never reaches that loop per-hop: `buildFlow`
+ * reduces the whole Block array into one `connect()`-composed super-Block, so
+ * every intermediate hop's verify (and now layout) has to run HERE, inside
+ * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
+ * one composed Block run start to finish.
+ */
+export declare function connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>, layouts?: readonly ConnectLayout[]): Block<A, C>;

package/dist/{types.js → engine/run/connect.js}

@@ -1,11 +1,5 @@
-import { runVerify, runPrecondition } from "./trait.js";
-/**
- * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
- * @example resolve: () => checkpoint("LoggedIn")
- */
-export function checkpoint(tag) {
-    return { __state: tag };
-}
+import { runVerify, runPrecondition } from "../trait/trait.js";
+import { isConnected, lastLeaf, stepEnded, stepStarted } from "./events.js";
 /**
  * Composes two Blocks into one, typechecked so this only compiles when A's output
  * tag equals B's input tag. The composed Block's act runs A's full instruction
@@ -15,7 +9,7 @@ export function checkpoint(tag) {
  * `layouts`, if given, also runs against the intermediate Checkpoint (A's
  * resolved output, right before B's act) - the same enforcement `runGraph`'s
  * own loop already applies to a chain's FINAL Checkpoint, but a
- * `defineFlow`-built Flow never reaches that loop per-hop: `buildFlow`
+ * `map()`-built Flow never reaches that loop per-hop: `buildFlow`
  * reduces the whole Block array into one `connect()`-composed super-Block, so
  * every intermediate hop's verify (and now layout) has to run HERE, inside
  * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
@@ -25,11 +19,13 @@ export function connect(a, b, layouts) {
     const bObserve = b.instruction.observe;
     const bVerify = b.instruction.verify;
     const requires = [...(a.requires ?? []), ...(b.requires ?? [])];
-    return {
+    const connected = {
         name: `${a.name} -> ${b.name}`,
         ...(requires.length > 0 ? { requires } : {}),
         instruction: {
             async act(page, input, mem) {
+                if (!isConnected(a))
+                    stepStarted(a.name, input.__state);
                 await runPrecondition(a.instruction.precondition, input, page, mem, a.name);
                 await a.instruction.act(page, input, mem);
                 const aObserved = a.instruction.observe
@@ -44,6 +40,9 @@ export function connect(a, b, layouts) {
                         await runVerify(layout.verify, mid, page, mem, `${a.name} (layout: "${layout.name}")`);
                     }
                 }
+                stepEnded(lastLeaf(a), mid.__state);
+                if (!isConnected(b))
+                    stepStarted(b.name, mid.__state);
                 await runPrecondition(b.instruction.precondition, mid, page, mem, b.name);
                 await b.instruction.act(page, mid, mem);
             },
@@ -54,4 +53,6 @@ export function connect(a, b, layouts) {
             ...(bVerify ? { verify: bVerify } : {}),
         },
     };
+    Object.defineProperty(connected, "__wgLastLeaf", { value: lastLeaf(b), enumerable: false });
+    return connected;
 }

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

@@ -0,0 +1,67 @@
+export type RunEvent = {
+    type: "run:start";
+    runId: string;
+    at: number;
+    label?: string;
+} | {
+    type: "step:start";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    from: string;
+} | {
+    type: "step:end";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    to: string;
+    ms: number;
+} | {
+    type: "step:error";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    error: string;
+    ms: number;
+} | {
+    type: "run:end";
+    runId: string;
+    at: number;
+    ok: boolean;
+    result?: string;
+    error?: string;
+    ms: number;
+} | {
+    type: "run:artifact";
+    runId: string;
+    at: number;
+    kind: "video" | "trace" | "screenshot";
+    path: string;
+};
+/** What {@link onRunEvent} calls with each event. */
+export type RunEventListener = (event: RunEvent) => void;
+/** Subscribes to every run event in this process; returns the unsubscribe function. */
+export declare function onRunEvent(listener: RunEventListener): () => void;
+/**
+ * Opens a run, or joins the one already open (a flow nested in another, or a runner driving a chain step by step). Returns
+ * whether this call opened it, so only the opener closes it.
+ */
+export declare function beginRun(label?: string): boolean;
+/** Closes the run when the matching `beginRun` opened it. */
+export declare function endRun(opened: boolean, outcome: {
+    result?: string;
+    error?: unknown;
+}): void;
+export declare function stepStarted(block: string, from: string): void;
+export declare function stepEnded(block: string, to: string): void;
+/** The step that started last failed. */
+export declare function stepFailed(error: unknown): void;
+/** The id of the run open right now, if any. */
+export declare function currentRunId(): string | undefined;
+export declare function recordArtifact(kind: "video" | "trace" | "screenshot", path: string, runId?: string | undefined): void;
+/** The last real Block inside a Block built by `connect` (or the Block itself). */
+export declare function lastLeaf(block: object): string;
+export declare function isConnected(block: object): boolean;

package/dist/engine/run/events.js

@@ -0,0 +1,90 @@
+// Run events: what happened, step by step, during a run. Core emits them; subscribers (the run log, the demo overlay,
+// reports, Waygraph UI) listen. Emitting never throws into the run.
+const listeners = new Set();
+/** Subscribes to every run event in this process; returns the unsubscribe function. */
+export function onRunEvent(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function emit(event) {
+    for (const listener of listeners) {
+        try {
+            listener(event);
+        }
+        catch {
+            /* a broken subscriber never breaks a run */
+        }
+    }
+}
+let open;
+/**
+ * Opens a run, or joins the one already open (a flow nested in another, or a runner driving a chain step by step). Returns
+ * whether this call opened it, so only the opener closes it.
+ */
+export function beginRun(label) {
+    if (open) {
+        open.depth += 1;
+        return false;
+    }
+    const at = Date.now();
+    open = { runId: `${new Date(at).toISOString().replace(/[:.]/g, "-")}-${crypto.randomUUID().slice(0, 8)}`, startedAt: at, depth: 1, index: 0 };
+    emit({ type: "run:start", runId: open.runId, at, ...(label ? { label } : {}) });
+    return true;
+}
+/** Closes the run when the matching `beginRun` opened it. */
+export function endRun(opened, outcome) {
+    if (!open)
+        return;
+    open.depth -= 1;
+    if (!opened)
+        return;
+    const at = Date.now();
+    emit({
+        type: "run:end",
+        runId: open.runId,
+        at,
+        ok: outcome.error === undefined,
+        ...(outcome.result !== undefined ? { result: outcome.result } : {}),
+        ...(outcome.error !== undefined ? { error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) } : {}),
+        ms: at - open.startedAt,
+    });
+    open = undefined;
+}
+export function stepStarted(block, from) {
+    if (!open)
+        return;
+    const at = Date.now();
+    open.step = { index: open.index++, block, startedAt: at };
+    emit({ type: "step:start", runId: open.runId, at, index: open.step.index, block, from });
+}
+export function stepEnded(block, to) {
+    if (!open?.step)
+        return;
+    const at = Date.now();
+    emit({ type: "step:end", runId: open.runId, at, index: open.step.index, block, to, ms: at - open.step.startedAt });
+    open.step = undefined;
+}
+/** The step that started last failed. */
+export function stepFailed(error) {
+    if (!open?.step)
+        return;
+    const at = Date.now();
+    const { index, block, startedAt } = open.step;
+    emit({ type: "step:error", runId: open.runId, at, index, block, error: error instanceof Error ? error.message : String(error), ms: at - startedAt });
+    open.step = undefined;
+}
+/** The id of the run open right now, if any. */
+export function currentRunId() {
+    return open?.runId;
+}
+export function recordArtifact(kind, path, runId = open?.runId) {
+    if (runId)
+        emit({ type: "run:artifact", runId, at: Date.now(), kind, path });
+}
+/** The last real Block inside a Block built by `connect` (or the Block itself). */
+export function lastLeaf(block) {
+    return block.__wgLastLeaf ?? block.name;
+}
+export function isConnected(block) {
+    return block.__wgLastLeaf !== undefined;
+}