waygraph 0.12.15 → 0.12.17

package/README.md

@@ -235,7 +235,9 @@ snapshot, partitions edges by hash, and claims via in-process edge leases (audit
 `docs/proposals/traverse-ffcompose-rfc.md`.
 
 **Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
-`tone: "info" | "warning" | "danger" | "success"` (iconified captions). Episode pacing:
+`tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus
+`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

@@ -213,6 +213,9 @@ import {
   hasAuthoredStubOnError,
   normalizeHighlightTone,
   normalizeDemoPace,
+  normalizeHighlightSize,
+  normalizeHighlightWeight,
+  applyHighlightStyleDefaults,
   resolveStepDemoPace,
 } from "waygraph";
 
@@ -425,6 +428,13 @@ const RING_CSS =
   "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
   "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
   "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
+  // size: ring pad + label font; weight: label boldness
+  "#wg-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}" +
+  "#wg-ring[data-size=lg]{border-width:4px;border-radius:12px;}" +
+  "#wg-ring-label[data-size=sm]{font-size:10px;line-height:1.25;padding:4px 7px;border-radius:5px;}" +
+  "#wg-ring-label[data-size=lg]{font-size:16px;line-height:1.35;padding:8px 14px;border-radius:9px;max-width:min(480px,85vw);}" +
+  "#wg-ring-label[data-weight=bold]{font-weight:800;}" +
+  "#wg-ring-label[data-weight=normal]{font-weight:600;}" +
   // Mouse cursor icon that travels to a target before it's acted on, plus a
   // quick expanding ripple at the moment of a click - same idea as
   // help-center-clip-engine's #clip-cursor/#clip-ring (video-pipeline). The
@@ -662,7 +672,7 @@ async function installOverlay(page, title) {
           const cursor = document.getElementById("wg-cursor");
           if (cursor) cursor.style.opacity = "0";
         };
-        window.__wgPositionRing = (box, label, tone) => {
+        window.__wgPositionRing = (box, label, tone, style) => {
           const ring = document.getElementById("wg-ring");
           const ringLabel = document.getElementById("wg-ring-label");
           if (!ring || !ringLabel) return;
@@ -671,15 +681,25 @@ async function installOverlay(page, title) {
             raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success"
               ? raw
               : "planned";
+          const st = style && typeof style === "object" ? style : {};
+          const sizeRaw = (st.size || "md") + "";
+          const size =
+            sizeRaw === "sm" || sizeRaw === "lg" ? sizeRaw : "md";
+          const weightRaw = (st.weight || "normal") + "";
+          const weight = weightRaw === "bold" ? "bold" : "normal";
           ring.dataset.tone = t;
           ringLabel.dataset.tone = t;
+          ring.dataset.size = size;
+          ringLabel.dataset.size = size;
+          ringLabel.dataset.weight = weight;
+          const pad = size === "sm" ? 3 : size === "lg" ? 10 : 6;
           const margin = 6;
           const vw = window.innerWidth;
           const vh = window.innerHeight;
-          let left = box.x - 6;
-          let top = box.y - 6;
-          const width = box.width + 12;
-          const height = box.height + 12;
+          let left = box.x - pad;
+          let top = box.y - pad;
+          const width = box.width + pad * 2;
+          const height = box.height + pad * 2;
           if (left < margin) left = margin;
           if (top < margin) top = margin;
           if (left + width > vw - margin) left = Math.max(margin, vw - margin - width);
@@ -1058,7 +1078,10 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
     try {
       const box = await page.locator(h.selector).first().boundingBox();
       if (box) {
-        await showRing(page, box, h.label, h.tone || "planned");
+        await showRing(page, box, h.label, h.tone || "planned", {
+          size: h.size,
+          weight: h.weight,
+        });
         const authored = resolveFixtureDwellMs(h, { gatesFast });
         const legacyMs = i === list.length - 1 ? 200 : 900;
         const holdMs =
@@ -1080,7 +1103,10 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             if (window.__wgHideRing) window.__wgHideRing();
             return;
           }
-          window.__wgPositionRing(el.getBoundingClientRect(), h.label, h.tone || "planned");
+          window.__wgPositionRing(el.getBoundingClientRect(), h.label, h.tone || "planned", {
+            size: h.size || "md",
+            weight: h.weight || "normal",
+          });
         };
         reposition();
         window.__wgRingTrack = reposition;
@@ -1425,13 +1451,17 @@ async function markStepRunning(page, _opts) {
     .catch(() => {});
 }
 
-async function showRing(page, box, label, tone) {
+async function showRing(page, box, label, tone, style) {
+  const size = normalizeHighlightSize(style && style.size);
+  const weight = normalizeHighlightWeight(style && style.weight);
   await page
     .evaluate(
-      ({ box, label, tone }) => {
-        if (window.__wgPositionRing) window.__wgPositionRing(box, label, tone || "planned");
+      ({ box, label, tone, size, weight }) => {
+        if (window.__wgPositionRing) {
+          window.__wgPositionRing(box, label, tone || "planned", { size, weight });
+        }
       },
-      { box, label, tone: tone || "planned" },
+      { box, label, tone: tone || "planned", size, weight },
     )
     .catch(() => {});
 }
@@ -1465,9 +1495,11 @@ async function captionForLocator(page, locator, stubs, fallback) {
     return {
       label: formatHighlightCaption(matched),
       tone: normalizeHighlightTone(matched.tone),
+      size: normalizeHighlightSize(matched.size),
+      weight: normalizeHighlightWeight(matched.weight),
     };
   }
-  return { label: fallback, tone: "auto" };
+  return { label: fallback, tone: "auto", size: "md", weight: "normal" };
 }
 
 async function dwellMatchedStub(page, locator, stubs, pacing) {
@@ -1510,13 +1542,17 @@ async function presentSlides(page, slides, _gate, opts) {
     const s = slides[i];
     const caption = formatHighlightCaption(s);
     const slideTone = normalizeHighlightTone(s.tone);
+    const slideStyle = {
+      size: normalizeHighlightSize(s.size),
+      weight: normalizeHighlightWeight(s.weight),
+    };
     const isLast = i === slides.length - 1;
     const dwellMs = resolveFixtureDwellMs(s, { gatesFast, pace: demoPace });
     await installOverlay(page, title);
     if (s.selector) {
       try {
         const box = await page.locator(s.selector).first().boundingBox();
-        if (box) await showRing(page, box, caption, slideTone);
+        if (box) await showRing(page, box, caption, slideTone, slideStyle);
       } catch {
         await hideRing(page);
       }
@@ -1828,7 +1864,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
           const cap = await captionForLocator(page, this, stubs, fallback);
           await moveCursorTo(page, box, cursorMs(500));
-          await showRing(page, box, cap.label, cap.tone);
+          await showRing(page, box, cap.label, cap.tone, {
+            size: cap.size,
+            weight: cap.weight,
+          });
           await dwellMatchedStub(page, this, stubs, pacing);
           await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 200));
         } else if (box) {
@@ -1900,7 +1939,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
           const cap = await captionForLocator(page, this, stubs, fallback);
           clickTone = cap.tone;
           clickPoint = await moveCursorTo(page, box, cursorMs(600));
-          await showRing(page, box, cap.label, cap.tone);
+          await showRing(page, box, cap.label, cap.tone, {
+            size: cap.size,
+            weight: cap.weight,
+          });
           await dwellMatchedStub(page, this, stubs, pacing);
           // "pop for a few seconds" - Dan's own phrase, matching the
           // zsign demo-engine's ring-before-click pattern in
@@ -2236,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.
@@ -2328,13 +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),
-        }));
+        }).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,
         });
@@ -2387,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,
@@ -2402,16 +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),
-        }),
+        (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,
@@ -2593,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
@@ -2662,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 {
@@ -2672,6 +2733,7 @@ async function main() {
           episodeTitle: undefined,
           highlightFixtures: undefined,
           demoPace: undefined,
+          highlightStyle: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2697,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

@@ -40,9 +40,19 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      * - `info` blue · `warning` yellow · `danger` red · `success` green
      */
     tone?: HighlightTone;
+    /**
+     * Ring padding + label font scale: `sm` | `md` (default) | `lg`.
+     * Aliases: small/medium/large, s/m/l.
+     */
+    size?: HighlightSize;
+    /**
+     * Label font weight: `normal` (default) | `bold`.
+     * Aliases: regular, strong.
+     */
+    weight?: HighlightWeight;
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | ((out: Out) => HighlightStubPhase);
 /**
@@ -57,14 +67,40 @@ export interface WaygraphSlide extends FixtureDurationFields {
     /** Optional ring while this slide is showing. */
     selector?: string;
     tone?: HighlightTone;
+    size?: HighlightSize;
+    weight?: HighlightWeight;
 }
 /**
  * Demo ring tones (iconified).
  * Automation (`auto`) is gray so authored planned/info/warning/danger/success stand out.
  */
 export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" | "success";
+/** Ring + label scale. */
+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. */
+export declare function normalizeHighlightSize(raw: unknown): HighlightSize;
+/** Map weight aliases to normal/bold. */
+export declare function normalizeHighlightWeight(raw: unknown): HighlightWeight;
 /** Prefix label with a short ASCII icon for semantic tones. */
 export declare function toneIconPrefix(tone: HighlightTone): string;
 /**

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: "",
@@ -35,6 +54,26 @@ export function normalizeHighlightTone(raw) {
         return "planned";
     return "planned";
 }
+/** Map size aliases to sm/md/lg. */
+export function normalizeHighlightSize(raw) {
+    if (typeof raw !== "string")
+        return "md";
+    const t = raw.trim().toLowerCase();
+    if (t === "sm" || t === "s" || t === "small" || t === "tiny")
+        return "sm";
+    if (t === "lg" || t === "l" || t === "large" || t === "big" || t === "xl")
+        return "lg";
+    return "md";
+}
+/** Map weight aliases to normal/bold. */
+export function normalizeHighlightWeight(raw) {
+    if (typeof raw !== "string")
+        return "normal";
+    const t = raw.trim().toLowerCase();
+    if (t === "bold" || t === "strong" || t === "heavy" || t === "b")
+        return "bold";
+    return "normal";
+}
 /** Prefix label with a short ASCII icon for semantic tones. */
 export function toneIconPrefix(tone) {
     const icon = TONE_ICONS[tone];
@@ -116,10 +155,24 @@ function pickDurationFields(base, patch) {
         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 mergeSlot(base, patch) {
     if (!base && !patch)
         return null;
     const dwell = pickDurationFields(base, patch);
+    const style = pickStyleFields(base, patch);
     if (!base && patch) {
         if (!patch.selector)
             return null;
@@ -128,12 +181,18 @@ function mergeSlot(base, patch) {
             label: patch.label,
             ...(patch.detail ? { detail: patch.detail } : {}),
             ...(patch.tag ? { tag: patch.tag } : {}),
-            ...(patch.tone ? { tone: normalizeHighlightTone(patch.tone) } : {}),
+            ...style,
             ...dwell,
         };
     }
-    if (base && !patch)
-        return { ...base };
+    if (base && !patch) {
+        return {
+            ...base,
+            ...(base.tone ? { tone: normalizeHighlightTone(base.tone) } : {}),
+            ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
+            ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
+        };
+    }
     return {
         selector: patch.selector ?? base.selector,
         label: patch.label,
@@ -143,11 +202,7 @@ function mergeSlot(base, patch) {
                 ? { detail: base.detail }
                 : {}),
         ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
-        ...(patch.tone !== undefined
-            ? { tone: normalizeHighlightTone(patch.tone) }
-            : base.tone
-                ? { tone: normalizeHighlightTone(base.tone) }
-                : {}),
+        ...style,
         ...dwell,
     };
 }

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, 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, 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, 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/dist/step-overlay.js

@@ -15,6 +15,12 @@ const RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none
     "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
     "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
     "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
+    "#wg-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}" +
+    "#wg-ring[data-size=lg]{border-width:4px;border-radius:12px;}" +
+    "#wg-ring-label[data-size=sm]{font-size:10px;line-height:1.25;padding:4px 7px;border-radius:5px;}" +
+    "#wg-ring-label[data-size=lg]{font-size:16px;line-height:1.35;padding:8px 14px;border-radius:9px;}" +
+    "#wg-ring-label[data-weight=bold]{font-weight:800;}" +
+    "#wg-ring-label[data-weight=normal]{font-weight:600;}" +
     "#wg-cursor{position:fixed;z-index:2147483647;width:24px;height:24px;pointer-events:none;" +
     "left:0;top:0;opacity:0;margin:0;" +
     "transition:transform var(--wg-cursor-ms,600ms) cubic-bezier(.22,1,.36,1),opacity .2s ease;" +
@@ -93,7 +99,7 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             void pulse.offsetWidth;
             pulse.classList.add("wg-pulse");
         };
-        window.__wgPositionRing = (box, label, tone) => {
+        window.__wgPositionRing = (box, label, tone, style) => {
             const ring = document.getElementById("wg-ring");
             const ringLabel = document.getElementById("wg-ring-label");
             if (!ring || !ringLabel)
@@ -106,12 +112,20 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
                 raw === "success"
                 ? raw
                 : "planned";
+            const sizeRaw = ((style && style.size) || "md") + "";
+            const size = sizeRaw === "sm" || sizeRaw === "lg" ? sizeRaw : "md";
+            const weightRaw = ((style && style.weight) || "normal") + "";
+            const weight = weightRaw === "bold" ? "bold" : "normal";
             ring.dataset.tone = t;
             ringLabel.dataset.tone = t;
-            ring.style.left = box.x - 6 + "px";
-            ring.style.top = box.y - 6 + "px";
-            ring.style.width = box.width + 12 + "px";
-            ring.style.height = box.height + 12 + "px";
+            ring.dataset.size = size;
+            ringLabel.dataset.size = size;
+            ringLabel.dataset.weight = weight;
+            const pad = size === "sm" ? 3 : size === "lg" ? 10 : 6;
+            ring.style.left = box.x - pad + "px";
+            ring.style.top = box.y - pad + "px";
+            ring.style.width = box.width + pad * 2 + "px";
+            ring.style.height = box.height + pad * 2 + "px";
             ring.style.opacity = "1";
             ringLabel.textContent = label;
             ringLabel.style.left = box.x + "px";

package/package.json

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