waygraph 0.15.53 → 0.16.0

package/dist/core/flow.js

@@ -1,432 +0,0 @@
-// Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { connect } from "../types.js";
-import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../browser.js";
-import { resolveExtensions } from "../extensions.js";
-import { loadWaygraphConfig } from "../config.js";
-import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
-import { preflight, runGraph } from "./run-graph.js";
-import { resolveLauncher } from "./config.js";
-import { MemPage } from "../mem-page.js";
-import { copyWaygraphRuntime, findBlockIndex, modVerify, withVerify } from "./block.js";
-import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../highlights.js";
-/** Launches the browser and context an Engine uses when the caller gave none, from its config. */
-async function openOwnContext(engineConfig) {
-    // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with, so a flow that imports
-    // an engine from one config file still follows the config the run selected.
-    const chosen = process.env.WAYGRAPH_CONFIG ? await loadWaygraphConfig(process.cwd()) : undefined;
-    const config = chosen
-        ? {
-            ...engineConfig,
-            ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
-            ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
-        }
-        : engineConfig;
-    const browserName = config?.browserName ?? "chromium";
-    const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-    const baseURL = config?.baseUrl ?? process.env.WAYGRAPH_BASE_URL;
-    return launchContext({
-        launcher: resolveLauncher(browserName, config),
-        launch: {
-            headless: config?.headless ?? true,
-            ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-            ...(executablePath ? { executablePath } : {}),
-        },
-        context: {
-            ...(baseURL ? { baseURL } : {}),
-            ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
-        },
-        extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
-    });
-}
-export function buildFlow(middle, engineConfig) {
-    // resetSession/title start false/unset here - defineFlow itself carries
-    // no such options anymore. They're set by wrapping the result in
-    // withSessionReset()/withTitle() instead (non-destructive decorators,
-    // same pattern as withVerify), which also re-apply themselves after any
-    // further withBlockVerify/modBlockVerify patch so the flag survives.
-    // Layouts have to be threaded into every pairwise connect(), not just the
-    // trailing runGraph call - see connect()'s own doc comment in types.ts:
-    // buildFlow's reduce IS the only place a defineFlow-built Flow's
-    // intermediate (non-final) Checkpoints are ever verified at all.
-    const chain = middle.reduce((a, b) => connect(a, b, engineConfig.layouts));
-    // Declared separately (not as the object-literal method below) so the
-    // three-overload `Flow.run` signature can be checked against the actual
-    // per-call-shape behavior, then attached with a cast - object-literal
-    // methods can't satisfy TS's per-overload implementation check the way a
-    // standalone function assigned to the property can.
-    const run = async function run(contextOrMem, memOrConfig, options) {
-        if (contextOrMem instanceof MemPage) {
-            const mem = contextOrMem;
-            const config = { ...engineConfig, ...memOrConfig };
-            // Checked again inside runGraph too, but doing it here first means a
-            // missing key fails before a browser process even launches, not just
-            // before a page opens - the same "fail loud, cheaply" guarantee
-            // run(context, mem) already has via an existing context.
-            preflight(mem, chain);
-            const { context, close } = await openOwnContext(config);
-            try {
-                try {
-                    return await runGraph(chain, undefined, context, mem, 5000, {
-                        ...(config.layouts !== undefined ? { layouts: config.layouts } : {}),
-                    });
-                }
-                finally {
-                    // Playwright finalizes recordVideo on context.close(); skip when
-                    // not recording so mem-only runs with stub contexts stay unchanged.
-                    if (config.recordVideo) {
-                        await context.close();
-                    }
-                }
-            }
-            finally {
-                await close();
-            }
-        }
-        const context = contextOrMem;
-        const mem = memOrConfig;
-        // Open (or reuse) the page here, not inside runGraph, so this method -
-        // not runGraph - decides whether to close it once the run is over; the
-        // page reference has to survive past runGraph's own return either way.
-        const gotOwnPage = options?.page === undefined;
-        const page = options?.page ?? (await context.newPage());
-        // Defaulting close-on-finish to `true` unconditionally would close a
-        // page the *caller* opened and handed in via `options.page` - the exact
-        // thing this option exists to let a caller keep driving. Only default to
-        // closing when this call opened the page itself (no `options.page`
-        // given), which is the one case that matches every `run(context, mem)`
-        // call from before this option existed. An explicit `closeOnFinish`
-        // always wins either way.
-        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
-        const resolvedLayouts = options?.layouts ?? engineConfig.layouts;
-        const result = await runGraph(chain, undefined, context, mem, 5000, {
-            page,
-            closeOnFinish: false,
-            ...(resolvedLayouts !== undefined ? { layouts: resolvedLayouts } : {}),
-        });
-        if (closeOnFinish) {
-            await page.close();
-        }
-        // The return *shape* only changes on an explicit `closeOnFinish: false`
-        // (the literal the `{ result, page }` overload is typed against) - not
-        // on the computed `closeOnFinish` default above. A caller who passed
-        // their own `page` and left `closeOnFinish` unset already holds that
-        // page reference; handing it back again in a different return shape
-        // would silently break the plain-`Out` overload their call actually
-        // matched at the type level.
-        if (options?.closeOnFinish === false) {
-            return { result, page };
-        }
-        return result;
-    };
-    return {
-        resetSession: false,
-        blocks: () => middle.map((b) => ({
-            name: b.name,
-            block: b,
-            ...(b.routes ? { routes: b.routes } : {}),
-            ...(b.__waygraphResetBefore ? { resetSessionBefore: true } : {}),
-        })),
-        run: run,
-        withBlockVerify(block, verify) {
-            const index = findBlockIndex(middle, block);
-            const patched = [...middle];
-            patched[index] = withVerify(middle[index], verify);
-            return buildFlow(patched, engineConfig);
-        },
-        modBlockVerify(block, nameOrIndex, newCheck) {
-            const index = findBlockIndex(middle, block);
-            const patched = [...middle];
-            patched[index] = modVerify(middle[index], nameOrIndex, newCheck);
-            return buildFlow(patched, engineConfig);
-        },
-    };
-}
-/**
- * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
- * browser state - e.g. a login flow meant to be re-entered later in a longer
- * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
- * new Flow: the original is untouched, and the flag survives any further
- * `withBlockVerify`/`modBlockVerify` patch applied to the result.
- *
- * By itself this does nothing - `Flow.run()` never reads `resetSession`.
- * It's a hint {@link chainFlow} looks for: right before this Flow's first
- * Block runs (skipped if it's the very first thing in the chain - nothing
- * to reset yet), chainFlow clears cookies and storage so this Flow starts
- * exactly as if a human had opened the app fresh, not wherever the
- * previous Flow in the chain happened to leave the page.
- * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
- * @deprecated Use `map().flow(sub, { reset: true })`; the reset belongs to where flows are joined.
- */
-export function withSessionReset(flow) {
-    return {
-        ...flow,
-        resetSession: true,
-        withBlockVerify: (block, verify) => withSessionReset(flow.withBlockVerify(block, verify)),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withSessionReset(flow.modBlockVerify(block, nameOrIndex, newCheck)),
-    };
-}
-/**
- * Names a Flow for display - a step-through overlay/showcase (waygraph's
- * `chain --step`) shows this as the running banner while this Flow's own
- * Blocks are executing, instead of one fixed title for the whole run.
- * Non-destructive, same pattern as {@link withSessionReset}.
- * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
- * @deprecated Name a flow with `ctx.title(...)` in a stub on its first step.
- */
-export function withTitle(flow, title) {
-    return {
-        ...flow,
-        title,
-        withBlockVerify: (block, verify) => withTitle(flow.withBlockVerify(block, verify), title),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
-    };
-}
-/**
- * Opts this Flow into memStub: `requires` keys the caller didn't supply get
- * filled from `registerMemStub`'s registry (`src/mem-stub.ts`) instead of
- * failing preflight, for any key that has a registered fake generator - a
- * required key with no registration still fails exactly as before.
- * Non-destructive, same pattern as {@link withTitle}. `run()` never reads
- * this itself - the CLI's `--data`/`--mem-stub` seeding, or a bare-library
- * caller's own explicit `seedMemStub(mem, flow)` call, does the filling.
- * @example const demoLogin = withMemStub(loginFlow);
- * @deprecated Use `engine.map({ memStub: true })`.
- */
-export function withMemStub(flow) {
-    return {
-        ...flow,
-        memStub: true,
-        withBlockVerify: (block, verify) => withMemStub(flow.withBlockVerify(block, verify)),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withMemStub(flow.modBlockVerify(block, nameOrIndex, newCheck)),
-    };
-}
-/**
- * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
- * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;
- * use this when an entire episode should be fast or slow.
- * @example withDemoPace(withTitle(gapFlow, "Episode 2 - gaps"), "slow")
- * @example withDemoPace(happyFlow, 0.5)  // 2x faster than normal
- * @example withDemoPace(gapFlow, 2.5)    // 2.5x slower
- * @example withDemoPace(gapFlow, 4500)   // absolute ~4.5s gates/dwells
- * @deprecated Use `engine.map({ demoPace })`, a step `{ pace }`, or `demo.pace` in the config.
- */
-export function withDemoPace(flow, pace) {
-    const demoPace = pace;
-    return {
-        ...flow,
-        demoPace,
-        withBlockVerify: (block, verify) => withDemoPace(flow.withBlockVerify(block, verify), demoPace),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withDemoPace(flow.modBlockVerify(block, nameOrIndex, newCheck), demoPace),
-    };
-}
-/**
- * Default highlight look for a Flow episode (size / weight / optional tone).
- * Per-slot stub or {@link withHighlightFixtures} values win when set.
- * @example withHighlightStyle(withDemoPace(gapFlow, "slow"), { size: "lg", weight: "bold" })
- * @deprecated Use `engine.map({ highlightStyle })`.
- */
-export function withHighlightStyle(flow, style) {
-    const highlightStyle = {
-        ...(style.tone !== undefined ? { tone: normalizeHighlightTone(style.tone) } : {}),
-        ...(style.size !== undefined ? { size: normalizeHighlightSize(style.size) } : {}),
-        ...(style.weight !== undefined ? { weight: normalizeHighlightWeight(style.weight) } : {}),
-    };
-    return {
-        ...flow,
-        highlightStyle,
-        withBlockVerify: (block, verify) => withHighlightStyle(flow.withBlockVerify(block, verify), highlightStyle),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightStyle(flow.modBlockVerify(block, nameOrIndex, newCheck), highlightStyle),
-    };
-}
-/**
- * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
- * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
- * @deprecated Use a step option: `.method(Block, { pace })`.
- */
-export function withBlockPace(block, pace) {
-    const next = { ...block, demoPace: pace };
-    copyWaygraphRuntime(block, next);
-    return next;
-}
-/**
- * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
- * login attempt genuinely failing, demonstrating the app's own real
- * behavior rather than a bug in the demo. Non-destructive, same pattern as
- * {@link withTitle}.
- *
- * By itself this changes nothing about how the Flow runs - it still throws
- * Marks a Flow whose last step is an intentional product failure (demo overlay).
- * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
- * - the last block **throws**, or
- * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
- *   after submit-login branched instead of throwing).
- * Headless `run()` is unchanged - branching success returns the checkpoint.
- * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
- *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
- * );
- * @deprecated Use `engine.map({ expectedFailure: reason })`.
- */
-export function withExpectedFailure(flow, reason) {
-    return {
-        ...flow,
-        expectedFailureReason: reason,
-        withBlockVerify: (block, verify) => withExpectedFailure(flow.withBlockVerify(block, verify), reason),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withExpectedFailure(flow.modBlockVerify(block, nameOrIndex, newCheck), reason),
-    };
-}
-/**
- * Attaches demo highlight fixtures to a Flow - unlimited purposes on `.flow.ts`
- * (AC copy, BUG/GATE tags, detail) merged onto each block's stubBefore/stubAfter/
- * stubOnError slots. Non-destructive, same pattern as {@link withTitle}.
- * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
- * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
- * @deprecated Chain ctx stubs on the Block: `Block.stubAfter((ctx) => …)`.
- */
-export function withHighlightFixtures(flow, fixtures) {
-    return {
-        ...flow,
-        highlightFixtures: fixtures,
-        withBlockVerify: (block, verify) => withHighlightFixtures(flow.withBlockVerify(block, verify), fixtures),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightFixtures(flow.modBlockVerify(block, nameOrIndex, newCheck), fixtures),
-    };
-}
-/** Applies each set option through its `with*` wrapper, so both spellings produce the same Flow. */
-export function applyFlowOptions(flow, options) {
-    if (!options)
-        return flow;
-    let f = flow;
-    if (options.sessionReset)
-        f = withSessionReset(f);
-    if (options.title !== undefined)
-        f = withTitle(f, options.title);
-    if (options.demoPace)
-        f = withDemoPace(f, options.demoPace);
-    if (options.highlightStyle)
-        f = withHighlightStyle(f, options.highlightStyle);
-    if (options.expectedFailure !== undefined)
-        f = withExpectedFailure(f, options.expectedFailure);
-    if (options.memStub)
-        f = withMemStub(f);
-    return f;
-}
-function locateInChain(flows, block) {
-    if (typeof block === "number") {
-        let remaining = block;
-        for (let fi = 0; fi < flows.length; fi++) {
-            const len = flows[fi].blocks().length;
-            if (remaining < len)
-                return { flowIndex: fi, localIndex: remaining };
-            remaining -= len;
-        }
-        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX(block, flows.length));
-    }
-    const blockName = typeof block === "string" ? block : block.name;
-    for (let fi = 0; fi < flows.length; fi++) {
-        const localIndex = flows[fi].blocks().findIndex((bi) => bi.name === blockName);
-        if (localIndex !== -1)
-            return { flowIndex: fi, localIndex };
-    }
-    throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME(blockName));
-}
-export async function clearSessionState(context, page) {
-    await context.clearCookies().catch(() => { });
-    await page
-        .evaluate(() => {
-        try {
-            localStorage.clear();
-            sessionStorage.clear();
-        }
-        catch {
-            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
-        }
-    })
-        .catch(() => { });
-}
-/**
- * Runs several complete, independent Flows one after another, reusing the
- * same page/context/mem in order - each remains its own validated
- * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
- * untouched), this only sequences whole Flows. Deliberately NOT the same
- * thing as {@link composeBlock}: composeBlock nests several Blocks into
- * one Block that can drop back into another `defineFlow([...])` - a
- * chainFlow result is a Flow, but not meant to be nested inside another
- * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
- * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
- * "ticket #123 end to end, then ticket #456 end to end").
- *
- * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
- * cleared right before it runs (skipped for the very first flow in the
- * chain - nothing to reset yet). The combined result is whatever the LAST
- * flow resolved to.
- * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
- * @deprecated Nest flows with `map().flow(a).flow(b, { reset: true })`.
- */
-export function chainFlow(...flows) {
-    if (flows.length === 0) {
-        throw new WaygraphError("WG_CHAINFLOW_EMPTY", MSG_CHAINFLOW_EMPTY);
-    }
-    const run = async function run(contextOrMem, memOrConfig, options) {
-        if (contextOrMem instanceof MemPage) {
-            const mem = contextOrMem;
-            const config = memOrConfig;
-            // One browser for the WHOLE chain - each sub-flow's own run(mem,
-            // config) would otherwise each launch a separate browser, defeating
-            // the point of sequencing them (a fresh browser is itself a full
-            // session reset, silently making withSessionReset a no-op).
-            const { context, close } = await openOwnContext(config);
-            try {
-                try {
-                    return await run(context, mem, { closeOnFinish: true });
-                }
-                finally {
-                    await context.close();
-                }
-            }
-            finally {
-                await close();
-            }
-        }
-        const context = contextOrMem;
-        const mem = memOrConfig;
-        const gotOwnPage = options?.page === undefined;
-        const page = options?.page ?? (await context.newPage());
-        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
-        let result;
-        for (let i = 0; i < flows.length; i++) {
-            const flow = flows[i];
-            if (i > 0 && flow.resetSession) {
-                await clearSessionState(context, page);
-            }
-            const outcome = (await flow.run(context, mem, { page, closeOnFinish: false }));
-            result = outcome.result;
-        }
-        if (closeOnFinish) {
-            await page.close();
-        }
-        if (options?.closeOnFinish === false) {
-            return { result, page };
-        }
-        return result;
-    };
-    return {
-        resetSession: false,
-        blocks: () => flows.flatMap((flow, idx) => flow.blocks().map((bi, i) => ({
-            ...bi,
-            ...(i === 0 && idx > 0 && flow.resetSession ? { resetSessionBefore: true } : {}),
-        }))),
-        run: run,
-        withBlockVerify(block, verify) {
-            const { flowIndex, localIndex } = locateInChain(flows, block);
-            const patched = [...flows];
-            patched[flowIndex] = patched[flowIndex].withBlockVerify(localIndex, verify);
-            return chainFlow(...patched);
-        },
-        modBlockVerify(block, nameOrIndex, newCheck) {
-            const { flowIndex, localIndex } = locateInChain(flows, block);
-            const patched = [...flows];
-            patched[flowIndex] = patched[flowIndex].modBlockVerify(localIndex, nameOrIndex, newCheck);
-            return chainFlow(...patched);
-        },
-    };
-}

package/dist/core.d.ts

@@ -1,14 +0,0 @@
-export * from "./core/config.js";
-export * from "./core/run-graph.js";
-export * from "./core/flow.js";
-export * from "./core/block.js";
-export * from "./core/compose.js";
-export * from "./core/engine.js";
-export * from "./core/map-builder.js";
-export * from "./core/blocks/nav.js";
-export * from "./core/blocks/method.js";
-export * from "./core/blocks/page.js";
-export * from "./core/blocks/effect.js";
-export * from "./core/blocks/api.js";
-export * from "./core/locate.js";
-export * from "./core/branch-regression.js";

package/dist/core.js

@@ -1,15 +0,0 @@
-// Barrel: the engine lives in src/core/ (see src/ARCHITECTURE.md). Kept so existing imports of "./core.js" don't change.
-export * from "./core/config.js";
-export * from "./core/run-graph.js";
-export * from "./core/flow.js";
-export * from "./core/block.js";
-export * from "./core/compose.js";
-export * from "./core/engine.js";
-export * from "./core/map-builder.js";
-export * from "./core/blocks/nav.js";
-export * from "./core/blocks/method.js";
-export * from "./core/blocks/page.js";
-export * from "./core/blocks/effect.js";
-export * from "./core/blocks/api.js";
-export * from "./core/locate.js";
-export * from "./core/branch-regression.js";

package/dist/highlights/merge.d.ts

@@ -1,8 +0,0 @@
-import type { HighlightStubPhase, HighlightStubPhaseName, HighlightStubPhaseOrFn, ResolvedHighlight, WaygraphHighlightFixture } from "./types.js";
-import type { Block, Checkpoint } from "../types.js";
-export declare function isStubPhase(v: unknown): v is HighlightStubPhase;
-export declare function applyDefaultZoom(slots: ResolvedHighlight[], defaultZoom?: number): ResolvedHighlight[];
-export declare function applyDefaultZoomOut(slots: ResolvedHighlight[], defaultZoomOut?: boolean): ResolvedHighlight[];
-export declare function mergePhaseMaps(phaseMap: HighlightStubPhase, fixturePhase: Record<string, WaygraphHighlightFixture> | undefined): ResolvedHighlight[];
-export declare function readStubRaw(block: Block<any, any>, phase: HighlightStubPhaseName): HighlightStubPhaseOrFn<any> | undefined;
-export declare function applyLegacyHighlightsShim(block: Block<any, any>, phase: HighlightStubPhaseName, phaseMap: HighlightStubPhase, out?: Checkpoint<string>): HighlightStubPhase;

package/dist/highlights/merge.js

@@ -1,173 +0,0 @@
-import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "./style.js";
-export function isStubPhase(v) {
-    return !!v && typeof v === "object" && !Array.isArray(v);
-}
-function pickDurationFields(base, patch) {
-    const out = {};
-    const duration = patch?.duration !== undefined ? patch.duration : base?.duration;
-    const fastMode = patch?.fastMode !== undefined ? patch.fastMode : base?.fastMode;
-    if (duration !== undefined)
-        out.duration = duration;
-    if (fastMode !== undefined)
-        out.fastMode = fastMode;
-    return out;
-}
-function pickStyleFields(base, patch) {
-    const out = {};
-    const tone = patch?.tone !== undefined ? patch.tone : base?.tone;
-    const size = patch?.size !== undefined ? patch.size : base?.size;
-    const weight = patch?.weight !== undefined ? patch.weight : base?.weight;
-    if (tone !== undefined)
-        out.tone = normalizeHighlightTone(tone);
-    if (size !== undefined)
-        out.size = normalizeHighlightSize(size);
-    if (weight !== undefined)
-        out.weight = normalizeHighlightWeight(weight);
-    return out;
-}
-function pickZoom(base, patch) {
-    const zoom = patch?.zoom !== undefined ? patch.zoom : base?.zoom;
-    if (zoom !== undefined && Number.isFinite(zoom) && zoom > 0)
-        return { zoom };
-    return {};
-}
-function pickFxFields(base, patch) {
-    const out = {};
-    const focus = patch?.focus !== undefined ? patch.focus : base?.focus;
-    const color = patch?.color !== undefined ? patch.color : base?.color;
-    const cursor = patch?.cursor !== undefined ? patch.cursor : base?.cursor;
-    const todo = patch?.todo !== undefined ? patch.todo : base?.todo;
-    const gesture = patch?.gesture !== undefined ? patch.gesture : base?.gesture;
-    if (focus !== undefined)
-        out.focus = !!focus;
-    if (color !== undefined && String(color).trim())
-        out.color = String(color).trim();
-    if (cursor !== undefined)
-        out.cursor = !!cursor;
-    if (todo !== undefined && String(todo).trim())
-        out.todo = String(todo).trim();
-    if (gesture === "tap" || gesture === "hold" || gesture === "click" || gesture === "swipe") {
-        out.gesture = gesture;
-    }
-    return out;
-}
-function mergeSlot(base, patch) {
-    if (!base && !patch)
-        return null;
-    const dwell = pickDurationFields(base, patch);
-    const style = pickStyleFields(base, patch);
-    const zoom = pickZoom(base, patch);
-    const fx = pickFxFields(base, patch);
-    if (!base && patch) {
-        if (!patch.selector)
-            return null;
-        return {
-            selector: patch.selector,
-            label: patch.label,
-            ...(patch.detail ? { detail: patch.detail } : {}),
-            ...(patch.tag ? { tag: patch.tag } : {}),
-            ...style,
-            ...dwell,
-            ...zoom,
-            ...fx,
-        };
-    }
-    if (base && !patch) {
-        return {
-            ...base,
-            ...(base.tone ? { tone: normalizeHighlightTone(base.tone) } : {}),
-            ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
-            ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
-            ...pickZoom(base, undefined),
-            ...pickFxFields(base, undefined),
-        };
-    }
-    return {
-        selector: patch.selector ?? base.selector,
-        label: patch.label,
-        ...(patch.detail !== undefined
-            ? { detail: patch.detail }
-            : base.detail
-                ? { detail: base.detail }
-                : {}),
-        ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
-        ...style,
-        ...dwell,
-        ...zoom,
-        ...fx,
-    };
-}
-export function applyDefaultZoom(slots, defaultZoom) {
-    if (defaultZoom === undefined || !(defaultZoom > 0))
-        return slots;
-    return slots.map((h) => (h.zoom !== undefined && h.zoom > 0 ? h : { ...h, zoom: defaultZoom }));
-}
-export function applyDefaultZoomOut(slots, defaultZoomOut) {
-    if (defaultZoomOut === undefined)
-        return slots;
-    return slots.map((h) => h.zoomOut !== undefined ? h : { ...h, zoomOut: defaultZoomOut });
-}
-export function mergePhaseMaps(phaseMap, fixturePhase) {
-    const phaseKeys = Object.keys(phaseMap);
-    const fixtureKeys = Object.keys(fixturePhase || {});
-    const allKeys = [...new Set([...phaseKeys, ...fixtureKeys])];
-    const allNumeric = allKeys.length > 0 && allKeys.every((k) => Number.isFinite(Number(k)) && String(Number(k)) === k);
-    // Numeric stub ids (legacy "0","1") sort by number. Named stubs keep author
-    // insertion order - localeCompare used to reorder password/submit/username
-    // and advance the wrong todo index on fill.
-    const ordered = allNumeric
-        ? [...allKeys].sort((a, b) => Number(a) - Number(b))
-        : [...phaseKeys, ...fixtureKeys.filter((k) => !phaseKeys.includes(k))];
-    const resolved = [];
-    for (const id of ordered) {
-        const merged = mergeSlot(phaseMap[id], fixturePhase?.[id]);
-        if (merged) {
-            resolved.push({
-                ...merged,
-                slotId: id,
-                ...(merged.todo ? { todo: merged.todo } : {}),
-            });
-        }
-    }
-    return resolved;
-}
-function phaseFromLegacyHighlights(highlights) {
-    const out = {};
-    if (!highlights)
-        return out;
-    highlights.forEach((h, i) => {
-        if (h && typeof h.selector === "string" && typeof h.label === "string") {
-            out[String(i)] = {
-                selector: h.selector,
-                label: h.label,
-                ...(h.tone ? { tone: normalizeHighlightTone(h.tone) } : {}),
-            };
-        }
-    });
-    return out;
-}
-export function readStubRaw(block, phase) {
-    const instr = block.instruction;
-    if (phase === "stubBefore")
-        return instr.stubBefore;
-    if (phase === "stubAfter")
-        return instr.stubAfter;
-    return instr.stubOnError;
-}
-export function applyLegacyHighlightsShim(block, phase, phaseMap, out) {
-    if (phase !== "stubAfter" || Object.keys(phaseMap).length > 0)
-        return phaseMap;
-    const instr = block.instruction;
-    if (!instr.highlights)
-        return phaseMap;
-    let legacy = instr.highlights;
-    if (typeof legacy === "function") {
-        try {
-            legacy = legacy(out ?? { __state: "" });
-        }
-        catch {
-            legacy = [];
-        }
-    }
-    return phaseFromLegacyHighlights(Array.isArray(legacy) ? legacy : []);
-}

package/dist/highlights/stub-ctx.d.ts

@@ -1,10 +0,0 @@
-import type { StubBagState, StubCtx } from "./types.js";
-import type { Checkpoint } from "../types.js";
-import type { MemPage } from "../mem-page.js";
-export declare function createStubCtx<Out extends Checkpoint<string>>(bag: StubBagState, opts: {
-    out?: Out;
-    error?: unknown;
-    mem?: MemPage;
-}): StubCtx<Out>;
-/** Lift legacy per-slot todos (0.12.23) onto the phase bag once. */
-export declare function liftLegacySlotTodos(bag: StubBagState): void;