waygraph 0.15.35 → 0.15.37

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

@@ -0,0 +1,46 @@
+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 {
+    /** `"Away"`, or `"Away > Far"` for a nested branch - the route tags that lead here, in order. */
+    path: string;
+    flow: Flow<any>;
+}
+/** This Flow's own immediate `.branch()` routes, or `undefined` if it wasn't built by `.branch()`. */
+export declare function branchRoutes(flow: Flow<any>): ReadonlyMap<string, Flow<any> | null> | 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. Static - doesn't run anything.
+ */
+export declare function collectBranchFlows(flow: Flow<any>): BranchEntry[];
+export interface BranchRunResult {
+    path: string;
+    status: "ok" | "failed";
+    result?: Checkpoint<string>;
+    error?: string;
+}
+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 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 ?? "");
+ * }
+ */
+export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, mem?: MemPage, options?: RunBranchRegressionOptions): Promise<BranchRunResult[]>;

package/dist/engine/branch-regression.js

@@ -0,0 +1,117 @@
+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 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. Static - doesn't run anything.
+ */
+export function collectBranchFlows(flow) {
+    const out = [];
+    const seen = new Set();
+    const walk = (f, prefix) => {
+        const routes = branchRoutes(f);
+        if (!routes)
+            return;
+        for (const [tag, route] of routes) {
+            if (!route || seen.has(route))
+                continue;
+            seen.add(route);
+            const path = prefix ? `${prefix} > ${tag}` : tag;
+            out.push({ path, flow: route });
+            walk(route, path);
+        }
+    };
+    walk(flow, "");
+    return out;
+}
+/**
+ * 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 ?? "");
+ * }
+ */
+export async function runBranchRegression(flow, context, mem = new MemPage(), options) {
+    const cloneSession = options?.cloneSession ?? true;
+    const results = [];
+    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;
+        }
+        seedMemStub(m, info.before);
+        const page = entryPage ?? (await ctx.newPage());
+        let first;
+        try {
+            first = (await info.before.run(ctx, m, { ...options, page, closeOnFinish: false }));
+        }
+        catch (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

@@ -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.

package/dist/engine.d.ts

@@ -9,3 +9,4 @@ export * from "./engine/blocks/method.js";
 export * from "./engine/blocks/page.js";
 export * from "./engine/blocks/effect.js";
 export * from "./engine/locate.js";
+export * from "./engine/branch-regression.js";

package/dist/engine.js

@@ -10,3 +10,4 @@ export * from "./engine/blocks/method.js";
 export * from "./engine/blocks/page.js";
 export * from "./engine/blocks/effect.js";
 export * from "./engine/locate.js";
+export * from "./engine/branch-regression.js";

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { connect, checkpoint } from "./types.js";
 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, } from "./engine.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, 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/index.js

@@ -2,7 +2,7 @@ export { connect, checkpoint } from "./types.js";
 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, } from "./engine.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 { 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 { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.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.35",
+  "version": "0.15.37",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",