waygraph 0.16.1 → 0.16.4

package/dist/demo/overlay/pilot/shell.js

@@ -13,8 +13,10 @@ import { ignorePageGone } from "../../../engine/page-gone.js";
 // re-invented) - genuinely the same visual language, not just the ring CSS
 // this file already shared via WAYGRAPH_RING_CSS.
 const OVERLAY_CSS = `
+/* Every element here sits in a slot of the overlay layout (ui/css/layout.css) - bottom-right, bottom-left, top-right -
+   or on its stage (the spotlight); none is positioned by hand. */
 #wg-pilot-overlay {
-  position: fixed; z-index: 2147483000; bottom: 12px; right: 12px;
+  z-index: var(--wg-z-top); display: flex; flex-direction: column; align-items: flex-end;
   font: 12px/1.4 ui-monospace, "SF Mono", Consolas, monospace;
   color: #fff; pointer-events: auto;
 }
@@ -56,7 +58,7 @@ const OVERLAY_CSS = `
 #wg-pilot-panel-graph .wg-pilot-graph-edge { padding: 2px 0 2px 14px; border-left: 2px solid rgba(255,255,255,.15); font-size: 11px; }
 #wg-pilot-panel-graph .wg-pilot-graph-edge .wg-pilot-kind { color: #c9a6ff; }
 #wg-pilot-activity {
-  position: fixed; z-index: 2147483000; bottom: 12px; left: 12px;
+  z-index: var(--wg-z-chrome);
   font: 12px/1.4 ui-monospace, "SF Mono", Consolas, monospace;
   background: ${SURFACE}; color: #fff; padding: 6px 10px; border-radius: 8px;
   box-shadow: 0 2px 8px rgba(0,0,0,0.25); white-space: nowrap; pointer-events: none;
@@ -68,12 +70,12 @@ const OVERLAY_CSS = `
    #wg-banner all come from the ONE shared bundle ensureShadowRoot installs (ui/css/*.css) - not
    redefined here. */
 /* Spotlight (demo focus:true) - dim page, cutout around target. */
-#wg-pilot-fx-focus{position:fixed;z-index:2147483644;pointer-events:none;
+#wg-pilot-fx-focus{position:fixed;z-index:var(--wg-z-focus);pointer-events:none;
   border-radius:12px;box-shadow:0 0 0 9999px rgba(8,4,20,.62);
   opacity:0;transition:opacity .3s ease,left .3s ease,top .3s ease,width .3s ease,height .3s ease;}
 #wg-pilot-fx-focus.wg-in{opacity:1;}
 /* Zoom HUD (demo parity - badge only; no CSS scale of the page). */
-#wg-pilot-fx-zoom{position:fixed;z-index:2147483646;bottom:14px;right:14px;
+#wg-pilot-fx-zoom{z-index:var(--wg-z-chrome);
   display:flex;align-items:center;gap:7px;padding:6px 11px 6px 8px;
   border-radius:999px;background:${SURFACE};color:#f0e8ff;
   border:1px solid rgba(250,204,21,.6);box-shadow:0 6px 18px rgba(0,0,0,.4);
@@ -83,7 +85,7 @@ const OVERLAY_CSS = `
 #wg-pilot-fx-zoom .wg-pilot-fx-zoom-ico svg{width:14px;height:14px;display:block;}
 #wg-pilot-fx-zoom .wg-pilot-fx-zoom-val{color:#fde68a;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}
 #wg-pilot-fx-zoom[data-zoomed="1"]{border-color:#fbbf24;}
-#wg-pilot-fx-device{position:fixed;z-index:2147483646;top:14px;right:14px;
+#wg-pilot-fx-device{z-index:var(--wg-z-chrome);
   padding:8px 12px;border-radius:10px;background:${SURFACE};color:#f0e8ff;
   border:1px solid rgba(124,58,237,.55);font:700 12px/1.2 system-ui,sans-serif;
   pointer-events:none;box-shadow:0 6px 18px rgba(0,0,0,.35);}

package/dist/demo/overlay/rings.d.ts

@@ -51,11 +51,3 @@ export declare function captionForLocator(page: WgPage, locator: Locator, stubs:
 }>;
 export declare function dwellMatchedStub(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined, pacing: Pick<Pacing, "gatesFast" | "demoPace"> | undefined): Promise<void>;
 export declare function hideRing(page: WgPage): Promise<void>;
-/**
- * True if the engine's own narrate() (waygraph's public export, for a Block
- * author explicitly captioning one action) JUST positioned the ring for
- * THIS action, moments ago - the automatic per-fill/per-click narration
- * below should not immediately overwrite an author's own explicit caption
- * with its generic guess.
- */
-export declare function wasJustNarrated(page: WgPage): Promise<boolean>;

package/dist/demo/overlay/rings.js

@@ -405,18 +405,3 @@ export async function hideRing(page) {
     })
         .catch(ignorePageGone);
 }
-/**
- * True if the engine's own narrate() (waygraph's public export, for a Block
- * author explicitly captioning one action) JUST positioned the ring for
- * THIS action, moments ago - the automatic per-fill/per-click narration
- * below should not immediately overwrite an author's own explicit caption
- * with its generic guess.
- */
-export async function wasJustNarrated(page) {
-    return page
-        .evaluate(() => {
-        const w = window;
-        return typeof w.__wgLastNarrate === "number" && Date.now() - w.__wgLastNarrate < 500;
-    })
-        .catch(() => false);
-}

package/dist/demo/overlay/ui/components/ring.js

@@ -11,13 +11,13 @@ function toneRules(sel, decl, only) {
 /** The highlight ring + its label (`#wg-ring`, `#wg-ring-label`): tone / size / weight variants. */
 export function ringCss() {
     const p = TONES.planned;
-    return ("#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
+    return ("#wg-ring{position:fixed;z-index:var(--wg-z-ring,2147483646);pointer-events:none;opacity:0;" +
         `border:2.5px solid ${p.ring};border-radius:10px;` +
         // Opacity fade only - NEVER transition border-color/box-shadow: tone swaps must snap.
         `box-shadow:0 0 0 4px ${p.glow};transition:opacity .3s ease;}` +
         toneRules("#wg-ring", (t) => `border-color:${t.ring};box-shadow:0 0 0 4px ${t.glow};`) +
         // A real element (not ::after) so JS can measure it and clamp it back onto the screen.
-        "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
+        "#wg-ring-label{position:fixed;z-index:var(--wg-z-ring,2147483646);pointer-events:none;opacity:0;" +
         `max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:${p.labelBg};color:${p.labelFg};` +
         "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
         "#wg-ring-label::after{content:attr(data-label);}" +

package/dist/demo/overlay/ui/overlay.css

@@ -31,16 +31,21 @@
   --wg-font: system-ui, sans-serif;
   --wg-font-mono: ui-monospace, "SF Mono", Consolas, monospace;
 
-  /* Stacking: Open Props' --layer-important is the one legitimate use of a max z-index (a
-     floating control that must sit above literally anything the host page can throw at it). */
-  --wg-z-top: var(--layer-important, 2147483647);
-  --wg-z-ring: 2147483646;
-  --wg-z-fx: 2147483645;
-  --wg-z-focus: 2147483644;
-  --wg-z-dock: 2147483000;
-  /* Banner sits BELOW rings/labels/todos - a title card must never shadow a highlight. */
-  --wg-z-banner: 2147483000;
-
+  /* Stacking. All overlay UI lives in one fixed parent (#wg-ui, layout.css) that sits above the host page with the one
+     max z-index; these values only order the layers inside it, lowest first. */
+  --wg-z-ui: var(--layer-important, 2147483647);
+  --wg-z-focus: 1;      /* the spotlight veil; chrome stepping back while a ring is the focus */
+  --wg-z-chrome: 2;     /* banner, todo docks, caption, chips, network tab */
+  --wg-z-dock: 2;
+  --wg-z-banner: 2;
+  --wg-z-fx: 4;         /* rings and their labels: a highlight is never covered by chrome */
+  --wg-z-ring: 4;
+  --wg-z-top: 6;        /* the step panel and other controls a person clicks */
+  --wg-z-toast: 7;      /* short-lived notices (device change) */
+  --wg-z-cursor: 8;     /* the cursor, click pulse and swipe trail: the pointer is always on top */
+  /* Spacing of the chrome layout: between items in a slot, and from the viewport edge. */
+  --wg-gap: 10px;
+  --wg-edge: 14px;
   --wg-ease: var(--ease-3, cubic-bezier(.22,1,.36,1));
   --wg-shadow-dock: var(--shadow-3, 0 2px 10px rgba(0,0,0,.3));
   --wg-shadow-banner: var(--shadow-4, 0 8px 20px rgba(0,0,0,.3));
@@ -50,6 +55,74 @@
 }
 
 
+/*
+ * The overlay's one layout. Every piece of waygraph UI lives in #wg-ui, a fixed layer over the page, in one of two
+ * places:
+ *
+ *   #wg-stage   things anchored to the page: ring, label, cursor, click pulse, spotlight veil, swipe trail. They follow
+ *               a target's coordinates (position: fixed against the viewport).
+ *   #wg-chrome  everything else, placed in a slot. Nothing in it is positioned by hand: a slot is a flex column with
+ *               a gap, so what shares a place stacks instead of overlapping, and a slot never grows past its row.
+ *
+ *     top-left    | top-center    | top-right       banner (by its side) · device chip / toast
+ *     left        |               | right           todo docks (by side)
+ *     bottom-left | bottom-center | bottom-right    network tab · typing, caption, step panel · zoom
+ *
+ * The slot an element goes in is decided once, in ui/shadow.ts (by id and data-pos), and a data-pos change moves it.
+ * Each row lays out on its own, so a wide step panel never squeezes the side docks.
+ */
+#wg-ui { position: fixed; inset: 0; z-index: var(--wg-z-ui); pointer-events: none; }
+#wg-stage { display: contents; }
+#wg-chrome {
+  position: absolute; inset: 0; box-sizing: border-box;
+  display: flex; flex-direction: column; gap: var(--wg-gap); padding: var(--wg-edge);
+}
+.wg-row { display: grid; grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr); gap: var(--wg-gap); min-height: 0; }
+.wg-row-top { flex: 0 0 auto; align-items: start; }
+.wg-row-middle { flex: 1 1 0; display: flex; justify-content: space-between; align-items: stretch; }
+.wg-row-bottom { flex: 0 1 auto; align-items: end; max-height: 62vh; }
+.wg-slot {
+  display: flex; flex-direction: column; gap: var(--wg-gap);
+  min-width: 0; min-height: 0; max-height: 100%; max-width: 100%;
+}
+.wg-slot[data-slot$="left"] { align-items: flex-start; }
+.wg-slot[data-slot$="center"] { align-items: center; }
+.wg-slot[data-slot$="right"] { align-items: flex-end; }
+.wg-row-bottom .wg-slot { justify-content: flex-end; }
+/* A slotted element shrinks (and scrolls inside) rather than spilling out of its slot: a min-width of its own (the
+   network tab's 260px) must not push it past the slot into its neighbour. */
+.wg-slot > * { position: relative; flex: 0 1 auto; box-sizing: border-box; pointer-events: auto; }
+/* The slot's limits win over an element's own sizing (an #id rule's min-width / max-height), hence the id here. */
+#wg-chrome .wg-slot > * { min-width: 0; min-height: 0; max-width: 100%; max-height: 100%; }
+
+/* Order inside a shared slot: what is being typed, what the narration says, then the controls. */
+#wg-typing-badge { order: 1; }
+#wg-caption-bar { order: 2; }
+#wg-panel, #wg-auto-panel { order: 3; }
+#wg-device-toast { order: 1; }
+#wg-device-badge, #wg-pilot-fx-device { order: 2; }
+
+/*
+ * Chrome that comes and goes takes no space while hidden (an empty gap above the step panel would read as a bug), and
+ * still fades: display switches with the transition (allow-discrete), and @starting-style is where the fade starts.
+ */
+#wg-caption-bar, #wg-typing-badge, #wg-network-log, #wg-device-badge {
+  transition-property: opacity, transform, display; transition-behavior: allow-discrete;
+}
+#wg-caption-bar:not(.wg-in), #wg-typing-badge:not(.wg-in), #wg-network-log:not(.wg-in), #wg-device-badge:not(.wg-in) {
+  display: none;
+}
+@starting-style {
+  #wg-caption-bar.wg-in, #wg-typing-badge.wg-in, #wg-network-log.wg-in, #wg-device-badge.wg-in { opacity: 0; }
+}
+
+/* Narrow viewports: the bottom row's three slots stack (network, then the step panel full width, then zoom). */
+@media (max-width: 640px) {
+  .wg-row-bottom { grid-template-columns: minmax(0, 1fr); }
+  .wg-slot[data-slot="bottom-center"] { align-items: stretch; }
+}
+
+
 /*
  * ONE ring implementation, shared by every surface (demo/auto's singleton #wg-ring, and Pilot's
  * multiple simultaneous fixture rings) - `.wg-ring-el`/`.wg-ring-el-label` is the real class every
@@ -110,14 +183,14 @@
 
 /* Travelling mouse cursor + click ripple (#wg-cursor, #wg-click-pulse). */
 #wg-cursor {
-  position: fixed; z-index: var(--wg-z-top); width: 24px; height: 24px; pointer-events: none;
+  position: fixed; z-index: var(--wg-z-cursor); width: 24px; height: 24px; pointer-events: none;
   left: 0; top: 0; opacity: 0; margin: 0;
   /* Travel time is JS-driven via --wg-cursor-ms (a hardcoded duration would make speed a no-op). */
   transition: transform var(--wg-cursor-ms, 600ms) var(--wg-ease), opacity .2s ease;
   filter: drop-shadow(0 2px 4px rgba(12,12,26,.4));
 }
 #wg-click-pulse {
-  position: fixed; z-index: var(--wg-z-top); width: 14px; height: 14px;
+  position: fixed; z-index: var(--wg-z-cursor); width: 14px; height: 14px;
   margin-left: -7px; margin-top: -7px; border-radius: 50%; pointer-events: none; opacity: 0;
   border: 2px solid var(--wg-tone-ring, var(--wg-tone-planned-ring)); background: var(--wg-tone-pulse, var(--wg-tone-planned-glow));
 }
@@ -130,19 +203,16 @@
 @keyframes wg-pulse { 0% { opacity: .9; transform: scale(.4); } 100% { opacity: 0; transform: scale(2.4); } }
 
 
-/* Top title banner (#wg-banner). Sits BELOW the ring/label/dock layers (--wg-z-banner) - a title
- * card must never shadow a highlight; see tokens.css. Moves out of the way of a ring it overlaps
- * (data-collision, driven from inpage/banner.ts's __wgBannerAvoidRing) unless authored off. */
+/* Top title banner (#wg-banner), in the top-left / top-center / top-right slot by its data-pos (layout.css). Sits
+ * below rings and labels (--wg-z-banner): a title card never shadows a highlight. Moves to another slot when a ring
+ * overlaps it (inpage/banner.ts's __wgBannerAvoidRing) unless authored off. */
 #wg-banner {
-  position: fixed; z-index: var(--wg-z-banner); top: 14px; left: 14px;
+  z-index: var(--wg-z-banner);
   background: var(--wg-surface); color: #fff; border-radius: var(--wg-radius-lg); padding: 10px 16px;
   font: 14px/1.4 var(--wg-font); box-shadow: var(--wg-shadow-banner);
-  border: 1px solid rgba(124,58,237,.4); cursor: pointer;
-  transition: left .3s var(--wg-ease), right .3s var(--wg-ease), transform .3s var(--wg-ease);
+  border: 1px solid rgba(124,58,237,.4); cursor: pointer; max-width: min(92vw, 520px);
+  transition: opacity .3s var(--wg-ease);
 }
-#wg-banner[data-pos=left]   { left: 14px; right: auto; transform: none; }
-#wg-banner[data-pos=center] { left: 50%; right: auto; transform: translateX(-50%); }
-#wg-banner[data-pos=right]  { right: 14px; left: auto; transform: none; }
 /* Same "auto opacity" step-back the todo dock already has (.wg-todo-behind) while a ring caption
    is the current focus - added via __wgBannerSetBehind, not just the collision-driven move. */
 #wg-banner.wg-banner-behind { opacity: .42; }
@@ -161,14 +231,11 @@
  * duplicate of this file's own rules, is consolidated.
  */
 #wg-pilot-fx-todos {
-  position: fixed; z-index: var(--wg-z-fx); top: 104px; max-width: 280px; max-height: calc(100vh - 132px);
-  overflow: auto; font: 12px/1.4 ui-sans-serif, system-ui, sans-serif; color: #fff;
+  z-index: var(--wg-z-dock); width: min(280px, 42vw); overflow: auto; font: 12px/1.4 ui-sans-serif, system-ui, sans-serif; color: #fff;
   background: var(--wg-surface); border-radius: var(--wg-radius-md); padding: 10px 12px;
   box-shadow: var(--wg-shadow-dock); pointer-events: auto; transition: opacity .25s ease;
 }
 #wg-pilot-fx-todos.wg-todo-behind { z-index: var(--wg-z-focus); opacity: .42; pointer-events: none; }
-#wg-pilot-fx-todos[data-pos=left]  { left: 14px; right: auto; }
-#wg-pilot-fx-todos[data-pos=right] { right: 14px; left: auto; }
 #wg-pilot-fx-todos .wg-pilot-fx-todo-title {
   font: 700 11px/1.2 system-ui, sans-serif; color: var(--wg-accent-soft);
   letter-spacing: .04em; text-transform: uppercase; margin: 0 0 8px;
@@ -199,19 +266,55 @@
  * chrome, this narrates the PAGE itself so it reads as a caption card, not more chrome).
  */
 #wg-caption-bar {
-  position: fixed; z-index: var(--wg-z-focus); left: 0; right: 0; bottom: 0;
-  /* Bottom padding clears the collapsed step-pill (#wg-panel, bottom:12px, ~40px tall,
-     z-index:2147483647 - always on top) - without it the pill sat right over the caption card,
-     both centered at the bottom of the viewport (see #wg-typing-badge's own bottom:88px, same
-     reason). */
-  padding: 0 6% 64px; display: flex; justify-content: center;
+  /* In the bottom-center slot, above the step panel (layout.css): the slot's gap keeps them apart. */
+  z-index: var(--wg-z-chrome); display: flex; justify-content: center; max-width: min(820px, 92vw);
   pointer-events: none; opacity: 0; transform: translateY(6px);
-  transition: opacity .3s ease, transform .3s ease;
+  transition-duration: .3s; transition-timing-function: ease;
 }
 #wg-caption-bar.wg-in { opacity: 1; transform: translateY(0); }
 #wg-caption-bar .wg-caption-text {
   font: 500 15px/1.4 var(--wg-font); color: #1c1917; text-align: center;
-  max-width: 82%; text-wrap: balance;
+  text-wrap: balance;
   background: #fff; border-radius: var(--wg-radius-lg);
   padding: 10px 18px; box-shadow: var(--wg-shadow-banner);
 }
+
+
+/* The network tab: real page traffic (network-capture.ts) and defineApiBlock's own calls, bottom-left (the one corner
+ * free of the zoom HUD and the typing chip). Hidden until ctx.ui.showNetworkTab(); stays up once shown. In the shared
+ * bundle, not the runner CSS: a navigation rebuilds the panel the moment the shadow root is back, before any later
+ * stylesheet, and without its CSS it painted unstyled and visible, then faded out. */
+#wg-network-log{z-index:var(--wg-z-chrome);min-width:260px;max-width:min(92vw,420px);max-height:min(60vh,420px);display:flex;flex-direction:column;border-radius:10px;background:var(--wg-surface);color:#f0e8ff;border:1px solid rgba(124,58,237,.45);box-shadow:0 8px 22px rgba(0,0,0,.4);font:12px/1.4 ui-monospace,"SF Mono",Consolas,monospace;opacity:0;transform:translateY(8px);transition-duration:.25s;transition-timing-function:ease;overflow:hidden;}
+#wg-network-log.wg-in{opacity:1;transform:translateY(0);}
+#wg-network-log.wg-net-collapsed .wg-net-list{display:none;}
+#wg-network-log .wg-net-header{display:flex;align-items:center;gap:6px;padding:8px 10px;border-bottom:1px solid rgba(124,58,237,.25);cursor:default;flex:0 0 auto;}
+#wg-network-log .wg-net-title{font:700 10px/1.2 system-ui,sans-serif;color:#c9a6ff;letter-spacing:.06em;text-transform:uppercase;flex:1 1 auto;}
+#wg-network-log .wg-net-count{font:700 10px/1.2 system-ui,sans-serif;color:#9CA3AF;background:rgba(124,58,237,.22);border-radius:999px;padding:1px 7px;}
+#wg-network-log .wg-net-collapse{flex:0 0 auto;width:18px;height:18px;border-radius:5px;border:none;background:rgba(124,58,237,.28);color:#e8dcff;font:700 13px/1 system-ui,sans-serif;cursor:pointer;pointer-events:auto;}
+#wg-network-log .wg-net-collapse:hover{background:rgba(124,58,237,.42);}
+#wg-network-log .wg-net-list{list-style:none;margin:0;padding:6px 8px;display:flex;flex-direction:column;gap:2px;overflow-y:auto;pointer-events:auto;}
+#wg-network-log .wg-net-row{display:flex;align-items:baseline;gap:7px;opacity:0;padding:3px 4px;border-radius:5px;cursor:pointer;transform:translateX(-4px);transition:opacity .2s ease,transform .2s ease;}
+#wg-network-log .wg-net-row:hover,#wg-network-log .wg-net-row.wg-net-open{background:rgba(124,58,237,.18);}
+#wg-network-log .wg-net-row.wg-in{opacity:1;transform:translateX(0);}
+#wg-network-log .wg-net-method{flex:0 0 auto;font-weight:800;font-size:10px;min-width:38px;}
+#wg-network-log .wg-net-method-get{color:#3B82F6;}
+#wg-network-log .wg-net-method-post{color:#22C55E;}
+#wg-network-log .wg-net-method-put{color:#F97316;}
+#wg-network-log .wg-net-method-delete{color:#EF4444;}
+#wg-network-log .wg-net-method-other{color:#9CA3AF;}
+#wg-network-log .wg-net-path{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:#e0e0f0;}
+#wg-network-log .wg-net-status{flex:0 0 auto;font-weight:700;color:#22C55E;}
+#wg-network-log .wg-net-row[data-ok="0"] .wg-net-status{color:#EF4444;}
+#wg-network-log .wg-net-ms{flex:0 0 auto;color:#9CA3AF;font-size:10px;}
+#wg-network-log .wg-net-detail{list-style:none;background:rgba(0,0,0,.28);border-radius:6px;padding:8px;margin:2px 0 6px;}
+#wg-network-log .wg-net-detail-section{margin-bottom:8px;}
+#wg-network-log .wg-net-detail-section:last-child{margin-bottom:0;}
+#wg-network-log .wg-net-detail-section h4{margin:0 0 4px;font:700 9px/1.2 system-ui,sans-serif;color:#9CA3AF;letter-spacing:.06em;text-transform:uppercase;}
+#wg-network-log .wg-net-headers{width:100%;border-collapse:collapse;font-size:11px;}
+#wg-network-log .wg-net-headers td{padding:1px 6px 1px 0;vertical-align:top;word-break:break-all;}
+#wg-network-log .wg-net-headers td:first-child{color:#c9a6ff;white-space:nowrap;}
+#wg-network-log .wg-net-body{margin:0;font-size:11px;white-space:pre-wrap;word-break:break-all;max-height:160px;overflow-y:auto;color:#e0e0f0;}
+#wg-network-log .wg-net-curl{color:#7dd3fc;}
+#wg-network-log .wg-net-empty{font-size:11px;color:#6b7280;font-style:italic;}
+#wg-network-log .wg-net-copy{margin-top:5px;padding:3px 9px;border-radius:5px;border:1px solid rgba(124,58,237,.5);background:rgba(124,58,237,.22);color:#e8dcff;font:700 10px system-ui,sans-serif;cursor:pointer;}
+#wg-network-log .wg-net-copy:hover{background:rgba(124,58,237,.38);}

package/dist/demo/overlay/ui/shadow.js

@@ -15,18 +15,85 @@ export function installShadowRoot(overlaySheet) {
             host?.remove();
             host = document.createElement("div");
             host.id = "wg-root";
-            // No box of its own: children are position:fixed, so the host must never affect page layout.
+            // No box of its own: everything inside is in the fixed #wg-ui layer, so the host never affects page layout.
             host.style.cssText = "display:contents";
             host.attachShadow({ mode: "open" });
             document.documentElement.appendChild(host);
         }
         return host.shadowRoot;
     };
+    // The one layout (ui/css/layout.css): #wg-ui holds the stage (anchored things) and the chrome's slots. Where a chrome
+    // element goes is decided here, once, by its id and data-pos; anything not in the table is anchored (the stage).
+    const SLOTS = ["top-left", "top-center", "top-right", "left", "right", "bottom-left", "bottom-center", "bottom-right"];
+    const SLOT_OF = {
+        "wg-typing-badge": "bottom-center",
+        "wg-caption-bar": "bottom-center",
+        "wg-panel": "bottom-center",
+        "wg-auto-panel": "bottom-center",
+        "wg-network-log": "bottom-left",
+        "wg-pilot-activity": "bottom-left",
+        "wg-zoom-badge": "bottom-right",
+        "wg-pilot-fx-zoom": "bottom-right",
+        "wg-pilot-overlay": "bottom-right",
+        "wg-device-toast": "top-right",
+        "wg-device-badge": "top-right",
+        "wg-pilot-fx-device": "top-right",
+    };
+    const slotOf = (el) => {
+        if (!(el instanceof HTMLElement))
+            return undefined;
+        const pos = el.dataset.pos;
+        if (el.id === "wg-banner")
+            return pos === "center" || pos === "right" ? `top-${pos}` : "top-left";
+        if (el.classList.contains("wg-todo-dock") || el.id === "wg-todo-dock" || el.id === "wg-pilot-fx-todos")
+            return pos === "right" ? "right" : "left";
+        return SLOT_OF[el.id];
+    };
+    const ui = () => {
+        const r = root();
+        let layer = r.getElementById("wg-ui");
+        if (layer)
+            return layer;
+        layer = document.createElement("div");
+        layer.id = "wg-ui";
+        const stage = document.createElement("div");
+        stage.id = "wg-stage";
+        const chrome = document.createElement("div");
+        chrome.id = "wg-chrome";
+        for (const [row, slots] of [["top", SLOTS.slice(0, 3)], ["middle", SLOTS.slice(3, 5)], ["bottom", SLOTS.slice(5)]]) {
+            const rowEl = document.createElement("div");
+            rowEl.className = `wg-row wg-row-${row}`;
+            for (const name of slots) {
+                const slot = document.createElement("div");
+                slot.className = "wg-slot";
+                slot.dataset.slot = name;
+                rowEl.appendChild(slot);
+            }
+            chrome.appendChild(rowEl);
+        }
+        layer.append(stage, chrome);
+        r.appendChild(layer);
+        // A data-pos change (banner click, a dock flipping away from a ring) moves the element to its new slot.
+        new MutationObserver((records) => {
+            for (const rec of records)
+                if (rec.target instanceof Element && rec.target.parentElement?.classList.contains("wg-slot"))
+                    place(rec.target);
+        }).observe(chrome, { subtree: true, attributes: true, attributeFilter: ["data-pos"] });
+        return layer;
+    };
+    const place = (node) => {
+        const layer = ui();
+        const slot = node instanceof Element ? slotOf(node) : undefined;
+        const parent = slot ? layer.querySelector(`[data-slot="${slot}"]`) : layer.querySelector("#wg-stage");
+        if (node.parentNode !== parent)
+            parent.appendChild(node);
+        return node;
+    };
     w.__wgRoot = root;
     w.__wgById = (id) => root().getElementById(id) || document.getElementById(id);
     w.__wgQ = (sel) => root().querySelector(sel) || document.querySelector(sel);
     w.__wgQA = (sel) => Array.from(root().querySelectorAll(sel)).concat(Array.from(document.querySelectorAll(sel)));
-    w.__wgAdd = (node) => root().appendChild(node);
+    w.__wgAdd = place;
     w.__wgCss = (css, key) => {
         const r = root();
         let style = Array.from(r.children).find((c) => c.tagName === "STYLE" && c.getAttribute("data-key") === key);

package/dist/demo/stepper/after.js

@@ -1,18 +1,19 @@
 import { envFlag } from "../../engine/env.js";
-import { hasAuthoredStubAfter, resolveSlides, runStubPhase } from "../narration/narration.js";
+import { hasAuthoredStubAfter, runStubPhase } from "../narration/narration.js";
 import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
 import { logBannerDom, probeBanner } from "./banner-log.js";
 import { logDocks } from "./before.js";
 import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
 import { renderAfterStep } from "./panel-after.js";
-import { presentSlides } from "./slides.js";
+import { showSlides } from "./slides.js";
 import { extractVerifyHighlights } from "./step-panels.js";
 import { forceCollapsed } from "./view.js";
 const quiet = () => envFlag("WAYGRAPH_JSON");
 export async function showAfter(ctx, view, result) {
     const { stage, refs } = ctx;
-    await showSlides(ctx, view, result);
     const after = hasAuthoredStubAfter(view.step.block, result) ? await narrateAfter(ctx, view, result) : undefined;
+    if (after)
+        await showSlides(ctx, view, after.phase.slides);
     const applied = after ? await stage.applyPhase(after.phase) : { appliedTodo: { sync: "keep" }, appliedDevice: { sync: "keep" } };
     await renderAfterStep(ctx.page, {
         index: view.index,
@@ -62,20 +63,6 @@ export async function showAfter(ctx, view, result) {
     }
     await ctx.gate.wait();
 }
-async function showSlides(ctx, view, result) {
-    const slides = resolveSlides(view.step.block, { out: result }).map((s) => applyHighlightStyleDefaults(s, view.step.highlightStyle));
-    if (slides.length === 0)
-        return;
-    await presentSlides(ctx.page, slides, {
-        title: ctx.title,
-        blockName: view.step.block.name,
-        fast: ctx.pacing.gatesFast,
-        pace: ctx.pacing.demoPace,
-        episodeNumber: view.step.episodeNumber,
-        episodeTitle: view.step.episodeTitle,
-        autoplayMs: ctx.gate.autoplayMs,
-    });
-}
 /** Runs the Block's stubAfter; its rings carry the flow's highlight style and a caption. */
 async function narrateAfter(ctx, view, result) {
     const style = view.step.highlightStyle;

package/dist/demo/stepper/before.js

@@ -1,4 +1,4 @@
-// Before a demo step runs: play the Block's stubBefore narration (rings, todos, device, title, caption) and show the
+// Before a demo step runs: play the Block's stubBefore narration (slides, rings, todos, device, title, caption) and show the
 // step's panel, then log what was painted so an agent without eyes can check it.
 import { envFlag } from "../../engine/env.js";
 import { runStubPhase } from "../narration/narration.js";
@@ -6,6 +6,7 @@ import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narratio
 import { logBannerDom, probeBanner } from "./banner-log.js";
 import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
 import { renderBeforeStep } from "./panel-before.js";
+import { showSlides } from "./slides.js";
 import { probeTodoDocksOnPage } from "./todo-advance.js";
 import { forceCollapsed } from "./view.js";
 const quiet = () => envFlag("WAYGRAPH_JSON");
@@ -13,6 +14,7 @@ export async function showBefore(ctx, view) {
     const { stage } = ctx;
     const phase = await narrateBefore(ctx, view);
     const { appliedTodo } = await stage.applyPhase(phase, { reapplyDeviceOnKeep: true });
+    await showSlides(ctx, view, phase.slides);
     if (phase.title && String(phase.title).trim())
         ctx.stickyTitle = String(phase.title).trim();
     view.overlayTitle = ctx.stickyTitle || (view.step.episodeTitle && String(view.step.episodeTitle).trim()) || ctx.title || "waygraph demo";

package/dist/demo/stepper/demo-log.js

@@ -177,13 +177,13 @@ export function logStubPhaseFixtures(phaseName, phase) {
         return;
     const tag = "stub." + phaseName;
     if (phase.title)
-        demoFixture(tag, "ctx.title(...)", JSON.stringify(phase.title));
+        demoFixture(tag, "ctx.ui.title(...)", JSON.stringify(phase.title));
     if (phase.titlePos)
-        demoFixture(tag, "ctx.titlePos(...)", JSON.stringify(phase.titlePos));
+        demoFixture(tag, "ctx.ui.titlePos(...)", JSON.stringify(phase.titlePos));
     if (phase.bannerUi)
-        demoFixture(tag, "ctx.bannerUi(...)", JSON.stringify(phase.bannerUi));
+        demoFixture(tag, "ctx.ui.bannerUi(...)", JSON.stringify(phase.bannerUi));
     if (phase.deviceSync && phase.deviceSync !== "keep") {
-        demoFixture(tag, phase.deviceSync === "clear" ? "ctx.hideDevice()" : "ctx.device(...)", phase.device
+        demoFixture(tag, phase.deviceSync === "clear" ? "ctx.ui.hideDevice()" : "ctx.ui.device(...)", phase.device
             ? {
                 preset: phase.device.preset,
                 w: phase.device.viewport && phase.device.viewport.width,
@@ -194,11 +194,11 @@ export function logStubPhaseFixtures(phaseName, phase) {
             : phase.deviceSync);
     }
     if (phase.zoom != null)
-        demoFixture(tag, "ctx.zoom(" + phase.zoom + ")", phase.zoom + "x");
+        demoFixture(tag, "ctx.ui.zoom(" + phase.zoom + ")", phase.zoom + "x");
     if (phase.zoomOut !== undefined)
-        demoFixture(tag, "ctx.zoomOut(" + !!phase.zoomOut + ")", !!phase.zoomOut);
+        demoFixture(tag, "ctx.ui.zoomOut(" + !!phase.zoomOut + ")", !!phase.zoomOut);
     if (phase.todoSync && phase.todoSync !== "keep") {
-        demoFixture(tag, phase.todoSync === "clear" ? "ctx.hideTodos() / clear" : "ctx.todos(...)", phase.todoDock
+        demoFixture(tag, phase.todoSync === "clear" ? "ctx.ui.hideTodos() / clear" : "ctx.ui.todos(...)", phase.todoDock
             ? {
                 id: phase.todoDock.id,
                 pos: phase.todoDock.pos,
@@ -208,7 +208,7 @@ export function logStubPhaseFixtures(phaseName, phase) {
             : phase.todoSync);
     }
     phase.highlights.forEach((h, i) => {
-        demoFixture(tag, "ctx.ring/highlights[" + i + "]", {
+        demoFixture(tag, "ctx.ui.ring[" + i + "]", {
             selector: h.selector,
             label: h.label,
             detail: h.detail,

package/dist/demo/stepper/interaction-patch.js

@@ -1,5 +1,5 @@
 import { installOverlay } from "../overlay/overlay.js";
-import { applyHighlightZoom, captionForLocator, dwellMatchedStub, ensureLocatorInView, hideRing, matchStubIndexForLocator, showRing, wasJustNarrated } from "../overlay/rings.js";
+import { applyHighlightZoom, captionForLocator, dwellMatchedStub, ensureLocatorInView, hideRing, matchStubIndexForLocator, showRing } from "../overlay/rings.js";
 import { syncTodoDockAdvance } from "./todo-advance.js";
 import { clickPulseAt, moveCursorTo } from "../overlay/cursor.js";
 import { demoHighlight } from "./demo-log.js";
@@ -109,7 +109,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
             catch {
                 /* ignore */
             }
-            if (box && !(await wasJustNarrated(page))) {
+            if (box) {
                 // Only trust the "last mem.get()" as THIS fill's source if it
                 // happened recently - a stale read from several actions ago is
                 // more likely unrelated than actually describing this field.
@@ -148,11 +148,6 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
                 if (cap && cap.label)
                     typeLabel = String(cap.label).slice(0, 40);
             }
-            else if (box) {
-                // Ring/caption already handled by narrate() - still move the
-                // cursor there, just skip re-showing the ring with a generic label.
-                await moveCursorTo(page, box, cursorMs(200));
-            }
             await page
                 .evaluate((label) => {
                 if (window.__wgSetTypingBadge)
@@ -191,8 +186,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
             // own click scroll is instant and reads as a teleport under --fast.
             await ensureLocatorInView(locator, { instant: skipTheater() });
             const box = await locator.boundingBox();
-            const narrated = box ? await wasJustNarrated(page) : false;
-            if (box && !narrated) {
+            if (box) {
                 let fallback = "click";
                 try {
                     const text = (await locator.textContent())?.trim();
@@ -241,12 +235,6 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
                 // services/help-center-clip-engine's video-pipeline.
                 await new Promise((res) => setTimeout(res, clickPrePop()));
             }
-            else if (box) {
-                // Ring/caption already handled by narrate() - still move the
-                // cursor + pulse the click point, just skip re-showing the ring.
-                clickPoint = await moveCursorTo(page, box, cursorMs(200));
-                clickTone = "planned";
-            }
             if (clickPoint) {
                 await clickPulseAt(page, clickPoint.x, clickPoint.y, clickTone);
                 // clickPulseAt only triggers the CSS animation class - it doesn't

package/dist/demo/stepper/panel-after.js

@@ -21,7 +21,7 @@ export async function renderAfterStep(page, info) {
     // Cycle through EVERY declared/recovered highlight in order, each shown
     // long enough to actually register - "it highlights something [...] then
     // it highlights something [else] and next," not just the first one.
-    // duration / fastMode on stubAfter (or flow fixtures) override the default
+    // duration / fastMode on stubAfter rings override the default
     // 900ms / 200ms holds when set.
     await cycleHighlightRings(page, highlights, gatesFast, {
         pace: info.pace,

package/dist/demo/stepper/slides.d.ts

@@ -1,6 +1,7 @@
 import type { WgPage } from "../types.js";
 import { type WaygraphSlide } from "../../engine/stub/ring.js";
 import type { DemoPace } from "../../engine/stub/pace.js";
+import type { StepperContext, StepView } from "./view.js";
 /** Where the slides sit (title, Block, episode) and how fast they advance. */
 export interface SlidesOptions {
     title?: string | undefined;
@@ -21,3 +22,5 @@ export interface SlidesOptions {
  * doing nothing. In-page data-wg-acked + autoplay poll is the source of truth.
  */
 export declare function presentSlides(page: WgPage, slides: readonly WaygraphSlide[], opts?: SlidesOptions): Promise<void>;
+/** Plays a stub phase's `ctx.ui.slides(...)` for the step on screen, in the flow's highlight style. */
+export declare function showSlides(ctx: StepperContext, view: StepView, slides: readonly WaygraphSlide[]): Promise<void>;

package/dist/demo/stepper/slides.js

@@ -1,10 +1,10 @@
 import { demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeDemoPace, resolveFixtureDwellMs } from "../narration/demo-pace.js";
-import { formatHighlightCaption } from "../narration/style.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
 import { installOverlay } from "../overlay/overlay.js";
 import { applyHighlightZoom, ensureSelectorInView, hideRing, showRing } from "../overlay/rings.js";
-import { demoPaceKind } from "./demo-log.js";
+import { demoLog, demoPaceKind } from "./demo-log.js";
 import { envFlag, envNumber, envString } from "../../engine/env.js";
+import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
 /**
  * Multi-step yap captions - not block lifecycle. Each slide waits for Next
  * (or auto-next), optional ring via slide.selector.
@@ -231,3 +231,19 @@ export async function presentSlides(page, slides, opts) {
     }
     await hideRing(page);
 }
+/** Plays a stub phase's `ctx.ui.slides(...)` for the step on screen, in the flow's highlight style. */
+export async function showSlides(ctx, view, slides) {
+    if (slides.length === 0)
+        return;
+    if (!envFlag("WAYGRAPH_JSON"))
+        demoLog(`  slides ${slides.length}: ` + slides.map((s) => JSON.stringify(s.caption)).join(" | "));
+    await presentSlides(ctx.page, slides.map((s) => applyHighlightStyleDefaults(s, view.step.highlightStyle)), {
+        title: ctx.title,
+        blockName: view.step.block.name,
+        fast: ctx.pacing.gatesFast,
+        pace: ctx.pacing.demoPace,
+        episodeNumber: view.step.episodeNumber,
+        episodeTitle: view.step.episodeTitle,
+        autoplayMs: ctx.gate.autoplayMs,
+    });
+}