waygraph 0.15.36 → 0.15.37

package/dist/engine/branch-regression.d.ts

@@ -1,6 +1,7 @@
 import type { Checkpoint } from "../types.js";
 import type { Flow } from "./flow.js";
 import type { RunGraphOptions } from "./run-graph.js";
+import { MemPage } from "../mem-page.js";
 import type { BrowserContext } from "@playwright/test";
 /** One branch reachable from `flow`, possibly several `.branch()` levels deep. */
 export interface BranchEntry {
@@ -13,27 +14,33 @@ export declare function branchRoutes(flow: Flow<any>): ReadonlyMap<string, Flow<
 /**
  * Every branch Flow reachable from `flow`, at any depth, deduped by object identity (the same
  * route Flow reused under two tags is only listed once). Doesn't include `flow` itself - only its
- * `.branch()` continuations.
+ * `.branch()` continuations. Static - doesn't run anything.
  */
 export declare function collectBranchFlows(flow: Flow<any>): BranchEntry[];
-/** Why a branch was skipped instead of run. */
-export type BranchSkipReason = "first Block is not nav/page - this branch needs page state a live run would have reached through its prefix, not its own blocks";
 export interface BranchRunResult {
     path: string;
-    status: "ok" | "failed" | "skipped";
+    status: "ok" | "failed";
     result?: Checkpoint<string>;
     error?: string;
-    reason?: BranchSkipReason;
+}
+export interface RunBranchRegressionOptions extends RunGraphOptions {
+    /**
+     * Default `true`: clone the real session (storageState + current URL) at every branch point, so
+     * every route runs from a genuine copy of the live state, not a fresh page. `false` runs the
+     * whole tree exactly once, through whichever single path the live state actually takes (same as
+     * calling `flow.run()` directly) - can't explore siblings, since the one real page has moved on
+     * once a branch's Blocks run.
+     */
+    cloneSession?: boolean;
 }
 /**
- * Runs every independently-enterable branch of `flow` (one whose own first Block navigates), each
- * with a fresh `MemPage` seeded via {@link seedMemStub} and a fresh page. Branches that assume
- * prior page state (first Block isn't nav/page) are reported as `"skipped"`, not silently run into
- * a confusing failure - see this file's own header for why that's a real, unavoidable limit, not a
- * gap to code around.
+ * Runs every path through `flow`'s `.branch()` tree - by default in a CLONED session per branch
+ * point (see this file's own header), so one branch finishing doesn't consume another's chance to
+ * run. Each explored branch gets its own `MemPage` (via {@link MemPage.clone}, seeded further with
+ * {@link seedMemStub} for anything a route alone requires that the shared prefix didn't already set).
  * @example
  * for (const r of await runBranchRegression(loginFlow, context)) {
- *   console.log(r.path, r.status, r.error ?? r.reason ?? "");
+ *   console.log(r.path, r.status, r.error ?? "");
  * }
  */
-export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, options?: RunGraphOptions): Promise<BranchRunResult[]>;
+export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, mem?: MemPage, options?: RunBranchRegressionOptions): Promise<BranchRunResult[]>;

package/dist/engine/branch-regression.js

@@ -1,14 +1,17 @@
 import { MemPage } from "../mem-page.js";
 import { seedMemStub } from "../mem-stub.js";
+function branchInfo(flow) {
+    return flow.__wgBranch;
+}
 /** This Flow's own immediate `.branch()` routes, or `undefined` if it wasn't built by `.branch()`. */
 export function branchRoutes(flow) {
-    const routes = flow.__wgBranchRoutes;
-    return routes ? new Map(Object.entries(routes)) : undefined;
+    const info = branchInfo(flow);
+    return info ? new Map(Object.entries(info.routes)) : undefined;
 }
 /**
  * Every branch Flow reachable from `flow`, at any depth, deduped by object identity (the same
  * route Flow reused under two tags is only listed once). Doesn't include `flow` itself - only its
- * `.branch()` continuations.
+ * `.branch()` continuations. Static - doesn't run anything.
  */
 export function collectBranchFlows(flow) {
     const out = [];
@@ -30,43 +33,85 @@ export function collectBranchFlows(flow) {
     return out;
 }
 /**
- * Runs every independently-enterable branch of `flow` (one whose own first Block navigates), each
- * with a fresh `MemPage` seeded via {@link seedMemStub} and a fresh page. Branches that assume
- * prior page state (first Block isn't nav/page) are reported as `"skipped"`, not silently run into
- * a confusing failure - see this file's own header for why that's a real, unavoidable limit, not a
- * gap to code around.
+ * Runs every path through `flow`'s `.branch()` tree - by default in a CLONED session per branch
+ * point (see this file's own header), so one branch finishing doesn't consume another's chance to
+ * run. Each explored branch gets its own `MemPage` (via {@link MemPage.clone}, seeded further with
+ * {@link seedMemStub} for anything a route alone requires that the shared prefix didn't already set).
  * @example
  * for (const r of await runBranchRegression(loginFlow, context)) {
- *   console.log(r.path, r.status, r.error ?? r.reason ?? "");
+ *   console.log(r.path, r.status, r.error ?? "");
  * }
  */
-export async function runBranchRegression(flow, context, options) {
-    const entries = collectBranchFlows(flow);
+export async function runBranchRegression(flow, context, mem = new MemPage(), options) {
+    const cloneSession = options?.cloneSession ?? true;
     const results = [];
-    for (const entry of entries) {
-        const first = entry.flow.blocks()[0]?.block;
-        const kind = first?.__waygraphKind;
-        if (kind !== "nav" && kind !== "page") {
-            results.push({
-                path: entry.path,
-                status: "skipped",
-                reason: "first Block is not nav/page - this branch needs page state a live run would have reached through its prefix, not its own blocks",
-            });
-            continue;
+    const browser = cloneSession ? context.browser() : null;
+    if (cloneSession && !browser) {
+        throw new Error("Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
+            "has none) - pass { cloneSession: false } to run the single live path in this context instead.");
+    }
+    /** `entryPage`, when given, is already positioned (cloned session + navigated) - reused as-is,
+     *  never replaced by a fresh `ctx.newPage()` (that would throw away the whole point of cloning). */
+    async function walk(f, ctx, m, path, entryPage) {
+        const info = branchInfo(f);
+        if (!info) {
+            // Leaf: whatever Blocks this route itself adds - run them to completion from the (possibly
+            // cloned, already-positioned) session already in place.
+            seedMemStub(m, f);
+            const page = entryPage ?? (await ctx.newPage());
+            try {
+                const result = await f.run(ctx, m, { ...options, page, closeOnFinish: true });
+                results.push({ path, status: "ok", result: result });
+            }
+            catch (err) {
+                results.push({ path, status: "failed", error: err instanceof Error ? err.message : String(err) });
+            }
+            return;
         }
-        const mem = new MemPage();
-        seedMemStub(mem, entry.flow);
+        seedMemStub(m, info.before);
+        const page = entryPage ?? (await ctx.newPage());
+        let first;
         try {
-            const result = await entry.flow.run(context, mem, { ...options, closeOnFinish: true });
-            results.push({ path: entry.path, status: "ok", result: result });
+            first = (await info.before.run(ctx, m, { ...options, page, closeOnFinish: false }));
         }
         catch (err) {
-            results.push({
-                path: entry.path,
-                status: "failed",
-                error: err instanceof Error ? err.message : String(err),
-            });
+            results.push({ path, status: "failed", error: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        if (!cloneSession) {
+            // Shared-session mode: only the ONE route the live state actually resolved to is reachable -
+            // the page has already moved past every other tag.
+            const route = info.routes[first.result.__state];
+            const tagPath = path ? `${path} > ${first.result.__state}` : first.result.__state;
+            if (!route) {
+                results.push({ path: tagPath, status: "ok", result: first.result });
+                return;
+            }
+            await walk(route, ctx, m, tagPath, first.page);
+            return;
+        }
+        const url = first.page.url();
+        const storageState = await ctx.storageState();
+        await first.page.close();
+        for (const [tag, route] of Object.entries(info.routes)) {
+            const branchPath = path ? `${path} > ${tag}` : tag;
+            if (!route) {
+                results.push({ path: branchPath, status: "ok", result: { __state: tag } });
+                continue;
+            }
+            const branchContext = await browser.newContext({ storageState });
+            try {
+                const branchPage = await branchContext.newPage();
+                // Best-effort: land back on the same page the prefix ended on before this route's own
+                // Blocks run - restores cookies/localStorage AND which page was loaded, not just auth state.
+                await branchPage.goto(url).catch(() => { });
+                await walk(route, branchContext, m.clone(), branchPath, branchPage);
+            }
+            finally {
+                await branchContext.close();
+            }
         }
     }
+    await walk(flow, context, mem, "");
     return results;
 }

package/dist/engine/engine-class.js

@@ -134,7 +134,7 @@ function buildBranchedFlow(before, routes) {
         }
         return branchFlow.run(context, mem, { ...options, page: first.page, closeOnFinish });
     });
-    const flow = {
+    return {
         resetSession: before.resetSession,
         ...(before.title !== undefined ? { title: before.title } : {}),
         ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
@@ -142,6 +142,11 @@ function buildBranchedFlow(before, routes) {
         ...(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 -
+        // 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
         // Blocks prefixed by the tag that leads to them - can't know at analysis time which one a real
         // run takes, so this shows all of them rather than none.
@@ -157,10 +162,6 @@ function buildBranchedFlow(before, routes) {
             return buildBranchedFlow(before.modBlockVerify(block, nameOrIndex, newCheck), routes);
         },
     };
-    // Non-enumerable so it doesn't show up on a spread/JSON.stringify of the Flow - read by
-    // branchRoutes()/collectBranchFlows() (branch-regression.ts), not part of the public Flow shape.
-    Object.defineProperty(flow, "__wgBranchRoutes", { value: routes, enumerable: false, configurable: true });
-    return flow;
 }
 /**
  * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./engine.js";
-export type { BranchEntry, BranchRunResult, BranchSkipReason } from "./engine/branch-regression.js";
+export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./engine/branch-regression.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, BannerPos, BannerUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";

package/dist/mem-page.d.ts

@@ -67,4 +67,12 @@ export declare class MemPage {
     setAll<A, B, C, D>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D]): void;
     setAll<A, B, C, D, E>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D], p5: readonly [MemKey<E>, E]): void;
     setAll<A, B, C, D, E, F>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D], p5: readonly [MemKey<E>, E], p6: readonly [MemKey<F>, F]): void;
+    /**
+     * An independent copy of every key currently set - a later `.set()` on either the original or the
+     * clone never touches the other. For branch-session cloning (`runBranchRegression`): each explored
+     * branch gets its own mem, so one branch's writes can't bleed into a sibling that also gets tried
+     * from the same snapshot point. Shallow per value (same as `set()` always was - MemPage never
+     * owned deep-copying the values themselves, only which keys point to which).
+     */
+    clone(): MemPage;
 }

package/dist/mem-page.js

@@ -68,4 +68,18 @@ export class MemPage {
             this.set(k, v);
         }
     }
+    /**
+     * An independent copy of every key currently set - a later `.set()` on either the original or the
+     * clone never touches the other. For branch-session cloning (`runBranchRegression`): each explored
+     * branch gets its own mem, so one branch's writes can't bleed into a sibling that also gets tried
+     * from the same snapshot point. Shallow per value (same as `set()` always was - MemPage never
+     * owned deep-copying the values themselves, only which keys point to which).
+     */
+    clone() {
+        const copy = new MemPage();
+        for (const [k, v] of this.store) {
+            copy.store.set(k, v);
+        }
+        return copy;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.36",
+  "version": "0.15.37",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",