waygraph 0.12.15 → 0.12.16

package/README.md

@@ -235,7 +235,8 @@ 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"`. 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,8 @@ import {
   hasAuthoredStubOnError,
   normalizeHighlightTone,
   normalizeDemoPace,
+  normalizeHighlightSize,
+  normalizeHighlightWeight,
   resolveStepDemoPace,
 } from "waygraph";
 
@@ -425,6 +427,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 +671,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 +680,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 +1077,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 +1102,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 +1450,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 +1494,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 +1541,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 +1863,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 +1938,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
@@ -2334,6 +2375,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           duration: h.duration,
           fastMode: h.fastMode,
           tone: normalizeHighlightTone(h.tone),
+          size: normalizeHighlightSize(h.size),
+          weight: normalizeHighlightWeight(h.weight),
         }));
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
@@ -2408,6 +2451,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           duration: h.duration,
           fastMode: h.fastMode,
           tone: normalizeHighlightTone(h.tone),
+          size: normalizeHighlightSize(h.size),
+          weight: normalizeHighlightWeight(h.weight),
         }),
       );
     } else {

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,24 @@ 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";
 /** 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

@@ -35,6 +35,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 +136,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 +162,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 +183,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

@@ -3,8 +3,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 type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, DemoPace, } from "./highlights.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 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

@@ -2,7 +2,7 @@ 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 { 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 { 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.16",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",