waygraph 0.15.35 → 0.15.36

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

@@ -0,0 +1,39 @@
+import type { Checkpoint } from "../types.js";
+import type { Flow } from "./flow.js";
+import type { RunGraphOptions } from "./run-graph.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.
+ */
+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";
+    result?: Checkpoint<string>;
+    error?: string;
+    reason?: BranchSkipReason;
+}
+/**
+ * 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.
+ * @example
+ * for (const r of await runBranchRegression(loginFlow, context)) {
+ *   console.log(r.path, r.status, r.error ?? r.reason ?? "");
+ * }
+ */
+export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, options?: RunGraphOptions): Promise<BranchRunResult[]>;

package/dist/engine/branch-regression.js

@@ -0,0 +1,72 @@
+import { MemPage } from "../mem-page.js";
+import { seedMemStub } from "../mem-stub.js";
+/** 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;
+}
+/**
+ * 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.
+ */
+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 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.
+ * @example
+ * for (const r of await runBranchRegression(loginFlow, context)) {
+ *   console.log(r.path, r.status, r.error ?? r.reason ?? "");
+ * }
+ */
+export async function runBranchRegression(flow, context, options) {
+    const entries = collectBranchFlows(flow);
+    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 mem = new MemPage();
+        seedMemStub(mem, entry.flow);
+        try {
+            const result = await entry.flow.run(context, mem, { ...options, closeOnFinish: true });
+            results.push({ path: entry.path, status: "ok", result: result });
+        }
+        catch (err) {
+            results.push({
+                path: entry.path,
+                status: "failed",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    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 });
     });
-    return {
+    const flow = {
         resetSession: before.resetSession,
         ...(before.title !== undefined ? { title: before.title } : {}),
         ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
@@ -157,6 +157,10 @@ 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/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, BranchSkipReason } 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/package.json

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