waygraph 0.12.16 → 0.12.17

package/README.md

@@ -236,7 +236,8 @@ snapshot, partitions edges by hash, and claims via in-process edge leases (audit
 
 **Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
 `tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus
-`size: "sm" | "md" | "lg"` and `weight: "normal" | "bold"`. Episode pacing:
+`size: "sm" | "md" | "lg"` and `weight: "normal" | "bold"`. Flow episode defaults:
+`withHighlightStyle(flow, { size, weight, tone? })` (slot/fixture wins). Episode pacing:
 `withDemoPace(flow, "fast" | "slow" | "normal" | "blitz")` or `withBlockPace(block, ...)`
 (FFCompose stays blitz). Living objectives: `docs/proposals/OBJECTIVES.md`.
 `spawnTab(entry, page, mem)` drives a genuinely separate second tab through its own

package/dist/cli.js

@@ -215,6 +215,7 @@ import {
   normalizeDemoPace,
   normalizeHighlightSize,
   normalizeHighlightWeight,
+  applyHighlightStyleDefaults,
   resolveStepDemoPace,
 } from "waygraph";
 
@@ -2277,7 +2278,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       !!r.block.fastForward ||
       !!r.wasFastForward;
     const fixtures = r.highlightFixtures;
-    stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
+    const flowStyle = r.highlightStyle;
+    stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures }).map((h) =>
+      applyHighlightStyleDefaults(h, flowStyle),
+    );
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Auto-next: tuck stepper on NavBlocks so the page transition fills the frame.
@@ -2369,15 +2373,18 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           .catch(() => {});
         const errHighlights = resolveHighlightSlots(r.block, "stubOnError", {
           fixtures: fixturesOnError,
-        }).map((h) => ({
-          selector: h.selector,
-          label: formatHighlightCaption(h),
-          duration: h.duration,
-          fastMode: h.fastMode,
-          tone: normalizeHighlightTone(h.tone),
-          size: normalizeHighlightSize(h.size),
-          weight: normalizeHighlightWeight(h.weight),
-        }));
+        }).map((h) => {
+          const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
+          return {
+            selector: styled.selector,
+            label: formatHighlightCaption(styled),
+            duration: styled.duration,
+            fastMode: styled.fastMode,
+            tone: styled.tone,
+            size: styled.size,
+            weight: styled.weight,
+          };
+        });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
         });
@@ -2430,7 +2437,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       .catch(() => {});
     result = stepOutcome.result;
     const fixturesAfter = r.highlightFixtures;
-    const slides = resolveSlides(r.block, { out: result, fixtures: fixturesAfter });
+    const slides = resolveSlides(r.block, { out: result, fixtures: fixturesAfter }).map((s) =>
+      applyHighlightStyleDefaults(s, r.highlightStyle),
+    );
     if (slides.length > 0) {
       await presentSlides(page, slides, gate, {
         title,
@@ -2445,18 +2454,23 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     let highlights;
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
       highlights = resolveHighlightSlots(r.block, "stubAfter", { out: result, fixtures: fixturesAfter }).map(
-        (h) => ({
-          selector: h.selector,
-          label: formatHighlightCaption(h),
-          duration: h.duration,
-          fastMode: h.fastMode,
-          tone: normalizeHighlightTone(h.tone),
-          size: normalizeHighlightSize(h.size),
-          weight: normalizeHighlightWeight(h.weight),
-        }),
+        (h) => {
+          const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
+          return {
+            selector: styled.selector,
+            label: formatHighlightCaption(styled),
+            duration: styled.duration,
+            fastMode: styled.fastMode,
+            tone: styled.tone,
+            size: styled.size,
+            weight: styled.weight,
+          };
+        },
       );
     } else {
-      highlights = extractVerifyHighlights(r.block, result.__state);
+      highlights = extractVerifyHighlights(r.block, result.__state).map((h) =>
+        applyHighlightStyleDefaults(h, r.highlightStyle),
+      );
     }
     await renderAfterStep(page, {
       index: i,
@@ -2638,6 +2652,7 @@ async function main() {
         seedMem: idx === 0 ? seedMem : undefined,
         highlightFixtures: flow.highlightFixtures,
         demoPace: flow.demoPace,
+        highlightStyle: flow.highlightStyle,
         expectedFailureReason:
           flow.expectedFailureReason && idx === blockInfos.length - 1
             ? flow.expectedFailureReason
@@ -2707,6 +2722,7 @@ async function main() {
           expectedFailureReason: flow.expectedFailureReason,
           highlightFixtures: flow.highlightFixtures,
           demoPace: flow.demoPace,
+          highlightStyle: flow.highlightStyle,
           seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref),
         });
       } else {
@@ -2717,6 +2733,7 @@ async function main() {
           episodeTitle: undefined,
           highlightFixtures: undefined,
           demoPace: undefined,
+          highlightStyle: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2742,6 +2759,7 @@ async function main() {
         episodeTitle: meta.episodeTitle,
         highlightFixtures: meta.highlightFixtures,
         demoPace: meta.demoPace,
+        highlightStyle: meta.highlightStyle,
         expectedFailureReason:
           meta.expectedFailureReason && remainingInFlow === 1 ? meta.expectedFailureReason : undefined,
         seedMem: isFirstOfSegment ? meta.seedMem : undefined,

package/dist/engine.d.ts

@@ -3,6 +3,7 @@ import type { Block, Checkpoint, Instruction, DefinedBlock, ActionPage, Waygraph
 import { MemPage } from "./mem-page.js";
 import type { MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
+import { type HighlightStyleDefaults, type DemoPace } from "./highlights.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
@@ -191,6 +192,11 @@ export interface Flow<Out extends Checkpoint<string>> {
      * `run()` ignores; step/demo applies per Block in the episode.
      */
     readonly demoPace?: import("./highlights.js").DemoPace;
+    /**
+     * Default highlight size/weight/tone for this Flow's episode (`withHighlightStyle`).
+     * Per-slot stub/fixture values win. `run()` ignores.
+     */
+    readonly highlightStyle?: import("./highlights.js").HighlightStyleDefaults;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -264,12 +270,18 @@ export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out
  * use this when an entire episode should be fast or slow.
  * @example withDemoPace(withTitle(gapFlow, "Episode 2 - gaps"), "slow")
  */
-export declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: import("./highlights.js").DemoPace): Flow<Out>;
+export declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: DemoPace): Flow<Out>;
+/**
+ * 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" })
+ */
+export declare function withHighlightStyle<Out extends Checkpoint<string>>(flow: Flow<Out>, style: HighlightStyleDefaults): Flow<Out>;
 /**
  * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
  * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
  */
-export declare function withBlockPace<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, pace: import("./highlights.js").DemoPace): Block<In, Out>;
+export declare function withBlockPace<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, pace: DemoPace): Block<In, Out>;
 /**
  * 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

package/dist/engine.js

@@ -2,6 +2,7 @@ import { chromium, firefox, webkit } from "@playwright/test";
 import { connect, checkpoint } from "./types.js";
 import { MemPage } from "./mem-page.js";
 import { runVerify, runPrecondition } from "./trait.js";
+import { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, } from "./highlights.js";
 const LAUNCHERS = { chromium, firefox, webkit };
 /**
  * Resolves which `BrowserType` actually launches for a `mem`-only run (no
@@ -366,6 +367,24 @@ export function withDemoPace(flow, pace) {
         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" })
+ */
+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")

package/dist/highlights.d.ts

@@ -79,6 +79,22 @@ export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" |
 export type HighlightSize = "sm" | "md" | "lg";
 /** Label font weight. */
 export type HighlightWeight = "normal" | "bold";
+/** Optional Flow-level defaults for demo rings (episode-wide). Stub/fixture wins. */
+export type HighlightStyleDefaults = {
+    tone?: HighlightTone;
+    size?: HighlightSize;
+    weight?: HighlightWeight;
+};
+/** Apply Flow defaults under per-slot authored values (slot wins when set). */
+export declare function applyHighlightStyleDefaults<T extends {
+    tone?: HighlightTone | string;
+    size?: HighlightSize | string;
+    weight?: HighlightWeight | string;
+}>(slot: T, defaults?: HighlightStyleDefaults | null): T & {
+    tone: HighlightTone;
+    size: HighlightSize;
+    weight: HighlightWeight;
+};
 /** Map author aliases (`error` -> danger) to a canonical tone. */
 export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
 /** Map size aliases to sm/md/lg. */

package/dist/highlights.js

@@ -8,6 +8,25 @@
  * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
+/** Apply Flow defaults under per-slot authored values (slot wins when set). */
+export function applyHighlightStyleDefaults(slot, defaults) {
+    const tone = slot.tone !== undefined && slot.tone !== ""
+        ? normalizeHighlightTone(slot.tone)
+        : defaults?.tone !== undefined
+            ? normalizeHighlightTone(defaults.tone)
+            : "planned";
+    const size = slot.size !== undefined && slot.size !== ""
+        ? normalizeHighlightSize(slot.size)
+        : defaults?.size !== undefined
+            ? normalizeHighlightSize(defaults.size)
+            : "md";
+    const weight = slot.weight !== undefined && slot.weight !== ""
+        ? normalizeHighlightWeight(slot.weight)
+        : defaults?.weight !== undefined
+            ? normalizeHighlightWeight(defaults.weight)
+            : "normal";
+    return { ...slot, tone, size, weight };
+}
 const TONE_ICONS = {
     planned: "",
     auto: "",

package/dist/index.d.ts

@@ -2,9 +2,9 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, toneIconPrefix, resolveStepDemoPace, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, DemoPace, } from "./highlights.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, toneIconPrefix, resolveStepDemoPace, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";

package/package.json

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