waygraph 0.16.2 → 0.16.4

package/dist/demo/overlay/inpage/core.js

@@ -209,6 +209,7 @@ export function installCore({ envAutoplay, todoDockUi }) {
                 continue;
             const cur = dock.dataset.pos === "right" ? "right" : "left";
             dock.dataset.pos = cur === "right" ? "left" : "right";
+            __wgAdd(dock);
             try {
                 localStorage.setItem("wg-todo-pos", dock.dataset.pos);
             }

package/dist/demo/overlay/inpage/network.js

@@ -145,7 +145,7 @@ export function addNetworkEntry(entry) {
     const countEl = panel.querySelector(".wg-net-count");
     if (countEl)
         countEl.textContent = String(w.__wgNetworkEntries.length);
-    // Always captured, only shown when explicitly turned on (ctx.showNetworkTab(); default hidden -
+    // Always captured, only shown when explicitly turned on (ctx.ui.showNetworkTab(); default hidden -
     // see StubCtx's own doc comment) - the DOM/row still gets built either way, so toggling visible
     // later shows the full history immediately, not just entries captured after that point.
     if (w.__wgNetworkTabVisible) {

package/dist/demo/overlay/inpage/todos.js

@@ -38,19 +38,6 @@ export function installTodos({ todoPos }) {
         // Drop any in-panel leftover (old builds put #wg-todos in .wg-body).
         __wgQA("#wg-panel #wg-todos").forEach((el) => el.remove());
         const allDocks = () => [...__wgQA(".wg-todo-dock, #wg-todo-dock")].filter((el, i, arr) => arr.indexOf(el) === i);
-        const relayoutTodoDocks = () => {
-            const docks = allDocks();
-            // Must match .wg-todo-dock/#wg-todo-dock's own CSS `top` (demo/overlay/overlay-css.ts,
-            // ui/css/dock.css) - this inline style OVERRIDES that CSS the instant more than one
-            // dock exists (multi-todo stacking), so a CSS-only change here is silently underwater;
-            // real bug this was: the CSS top was bumped 72 -> 104 for banner clearance, but this
-            // hardcoded 72 kept winning at runtime and nothing actually moved.
-            let top = 104;
-            for (const el of docks) {
-                el.style.top = top + "px";
-                top += Math.max(48, el.getBoundingClientRect().height) + 10;
-            }
-        };
         const findDock = (key) => {
             if (key === "_default") {
                 return (__wgQ('.wg-todo-dock[data-wg-todo-key="_default"]') ||
@@ -88,7 +75,6 @@ export function installTodos({ todoPos }) {
             else {
                 allDocks().forEach((el) => el.remove());
             }
-            relayoutTodoDocks();
             return;
         }
         if (sync === "set" && replace) {
@@ -285,7 +271,6 @@ export function installTodos({ todoPos }) {
             });
         }
         dock._wgLastPayload = syncPayload;
-        relayoutTodoDocks();
         if (window.__wgStampModal) {
             window.__wgStampModal(dock, "todos", { ready: true });
         }

package/dist/demo/overlay/network-capture.js

@@ -55,6 +55,8 @@ export async function restoreNetworkHistory(page) {
     }
 }
 export function installNetworkCapture(page) {
+    // defineApiBlock reports its calls through the engine's hook; show them in the same panel.
+    setApiCallRecorder((p, entry) => recordNetworkEntry(p, entry));
     if (page.__wgNetworkCaptureInstalled)
         return;
     page.__wgNetworkCaptureInstalled = true;
@@ -123,5 +125,3 @@ export function installNetworkCapture(page) {
         });
     });
 }
-// defineApiBlock reports its calls through core's hook; show them in the same panel.
-setApiCallRecorder((page, entry) => recordNetworkEntry(page, entry));

package/dist/demo/overlay/overlay-css.js

@@ -15,12 +15,12 @@ import { SURFACE } from "./ui/tokens.js";
 // never collides with that bundle.
 export const RUNNER_EXTRA_CSS = 
 // Spotlight: dim everything except the highlight target (focus: true).
-"#wg-focus-veil{position:fixed;z-index:2147483644;pointer-events:none;" +
+"#wg-focus-veil{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-focus-veil.wg-in{opacity:1;}" +
     // Touch swipe trail (mobile/tablet orientation + device theater).
-    "#wg-swipe-layer{position:fixed;inset:0;z-index:2147483646;pointer-events:none;" +
+    "#wg-swipe-layer{position:fixed;inset:0;z-index:var(--wg-z-cursor);pointer-events:none;" +
     "overflow:hidden;}" +
     "#wg-swipe-layer .wg-swipe-dot{position:absolute;width:14px;height:14px;margin:-7px 0 0 -7px;" +
     "border-radius:50%;background:rgba(147,197,253,.55);border:2px solid rgba(255,255,255,.85);" +
@@ -34,8 +34,8 @@ export const RUNNER_EXTRA_CSS =
     "border:1px solid rgba(56,189,248,.55);font:700 12px/1.2 system-ui,sans-serif;" +
     "letter-spacing:.04em;text-transform:uppercase;opacity:0;transition:opacity .25s ease;}" +
     "#wg-swipe-layer.wg-in .wg-swipe-label{opacity:1;}" +
-    "#wg-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
-    "max-width:min(92vw,640px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
+    "#wg-panel{z-index:var(--wg-z-top);" +
+    "width:min(92vw,640px);overflow-y:auto;box-sizing:border-box;" +
     "background:" + SURFACE + ";color:#fff;border-radius:14px;" +
     "padding:16px 20px;font:14px/1.4 system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35);" +
     // .06s was tuned back when the panel was removed and recreated on
@@ -78,16 +78,14 @@ export const RUNNER_EXTRA_CSS =
     // Todo checklist(s) float outside #wg-panel so --mini / Hide never hide them.
     // Multiple docks (one per todoId) are supported - stacked on the same side.
     // Click a dock to slide left <-> right (WAYGRAPH_TODO_POS / --todo-left|right).
-    ".wg-todo-dock,#wg-todo-dock{position:fixed;z-index:2147483646;top:104px;left:14px;" +
-    "width:min(280px,42vw);max-height:calc(100vh - 100px);overflow:auto;box-sizing:border-box;" +
+    ".wg-todo-dock,#wg-todo-dock{z-index:var(--wg-z-dock);" +
+    "width:min(280px,42vw);overflow:auto;box-sizing:border-box;" +
     "padding:10px 12px;background:" + SURFACE + ";color:#fff;border-radius:12px;" +
     "border:1px solid rgba(124,58,237,.45);box-shadow:0 8px 24px rgba(0,0,0,.35);" +
     "pointer-events:auto;cursor:pointer;" +
-    "transition:transform .4s cubic-bezier(.22,1,.36,1),top .35s ease,opacity .25s ease,z-index 0s;transform:translateX(0);}" +
-    ".wg-todo-dock[data-pos=right],#wg-todo-dock[data-pos=right]{transform:translateX(calc(100vw - 100% - 28px));}" +
-    ".wg-todo-dock[data-pos=left],#wg-todo-dock[data-pos=left]{transform:translateX(0);}" +
+    "transition:opacity .25s ease,z-index 0s;}" +
     /* While a highlight ring is up: sit under the ring so captions stay readable. */
-    ".wg-todo-dock.wg-todo-behind,#wg-todo-dock.wg-todo-behind{z-index:2147483643;opacity:.42;}" +
+    ".wg-todo-dock.wg-todo-behind,#wg-todo-dock.wg-todo-behind{z-index:var(--wg-z-focus);opacity:.42;}" +
     /* Collision tuck: shrink so a mid-page ring can still breathe. */
     ".wg-todo-dock[data-tucked=\"1\"],#wg-todo-dock[data-tucked=\"1\"]{max-height:min(28vh,220px);}" +
     /* Compact + cap: fold overflow rows; hover / data-expanded reveals more. */
@@ -103,7 +101,7 @@ export const RUNNER_EXTRA_CSS =
     // Always-on zoom HUD - bottom-right (top-left is crowded: todos + banners). Violet, matching the
     // rest of the overlay's design tokens - this used to be a lone amber/yellow badge, the one
     // surface that never got pulled into the shared palette when everything else did.
-    "#wg-zoom-badge{position:fixed;z-index:2147483646;bottom:14px;right:14px;" +
+    "#wg-zoom-badge{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(124,58,237,.55);box-shadow:0 6px 18px rgba(0,0,0,.4);" +
@@ -115,16 +113,16 @@ export const RUNNER_EXTRA_CSS =
     "#wg-zoom-badge .wg-zoom-val{color:#c9a6ff;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}" +
     "#wg-zoom-badge[data-zoomed=\"1\"]{border-color:#7C3AED;}" +
     // Typing chip (method fills: username / password / etc.)
-    "#wg-typing-badge{position:fixed;z-index:2147483646;bottom:88px;left:50%;transform:translateX(-50%);" +
+    "#wg-typing-badge{z-index:var(--wg-z-chrome);" +
     "display:flex;align-items:center;gap:8px;padding:8px 14px;" +
     "border-radius:999px;background:rgba(20,10,40,.95);color:#e0f2fe;" +
     "border:1px solid rgba(56,189,248,.55);box-shadow:0 8px 22px rgba(0,0,0,.4);" +
     "font:700 12px/1.2 system-ui,sans-serif;pointer-events:none;" +
-    "opacity:0;transition:opacity .2s ease;}" +
+    "opacity:0;transition-duration:.2s;}" +
     "#wg-typing-badge.wg-in{opacity:1;}" +
     "#wg-typing-badge .wg-ty-dots{letter-spacing:.15em;color:#7dd3fc;}" +
     // Device toast + chip (0.13.2+) - icon toast on fixture change, then compact chip.
-    "#wg-device-toast{position:fixed;z-index:2147483647;top:14px;right:14px;" +
+    "#wg-device-toast{z-index:var(--wg-z-toast);" +
     "display:flex;align-items:center;gap:10px;min-width:200px;max-width:min(92vw,320px);" +
     "padding:12px 14px;border-radius:14px;background:rgba(20,10,40,.96);color:#f0e8ff;" +
     "border:1px solid rgba(124,58,237,.55);box-shadow:0 10px 28px rgba(0,0,0,.4);" +
@@ -146,20 +144,21 @@ export const RUNNER_EXTRA_CSS =
     "#wg-device-toast .wg-dev-title{font:800 13px/1.2 system-ui,sans-serif;color:#fff;}" +
     "#wg-device-toast .wg-dev-sub{margin-top:3px;font:600 11px/1.3 system-ui,sans-serif;" +
     "color:#c9a6ff;letter-spacing:.02em;}" +
-    "#wg-device-badge{position:fixed;z-index:2147483646;top:14px;right:14px;" +
+    "#wg-device-badge{z-index:var(--wg-z-chrome);" +
     "display:inline-flex;align-items:center;gap:6px;padding:6px 10px 6px 8px;" +
     "border-radius:999px;background:rgba(20,10,40,.92);color:#f0e8ff;" +
     "border:1px solid rgba(124,58,237,.5);font:700 11px/1.2 system-ui,sans-serif;" +
     "letter-spacing:.04em;text-transform:uppercase;pointer-events:none;" +
     "box-shadow:0 4px 14px rgba(0,0,0,.3);opacity:0;transform:translateY(-4px);" +
-    "transition:opacity .3s ease,transform .35s cubic-bezier(.22,1,.36,1);}" +
+    "transition-duration:.35s;transition-timing-function:cubic-bezier(.22,1,.36,1);}" +
     "#wg-device-badge.wg-in{opacity:1;transform:translateY(0);}" +
     "#wg-device-badge[data-preset=mobile]{border-color:#3B82F6;}" +
     "#wg-device-badge[data-preset=tablet]{border-color:#22C55E;}" +
     "#wg-device-badge[data-preset=desktop]{border-color:#9CA3AF;}" +
     "#wg-device-badge .wg-dev-icon{width:16px;height:16px;display:flex;align-items:center;justify-content:center;}" +
     "#wg-device-badge .wg-dev-icon svg{width:14px;height:14px;display:block;}" +
-    "#wg-device-badge .wg-dev-label{white-space:nowrap;}" +
+    "#wg-device-badge{overflow:hidden;}" +
+    "#wg-device-badge .wg-dev-label{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;min-width:0;}" +
     "#wg-cursor[data-touch=1]{width:28px;height:28px;}" +
     "#wg-todos,.wg-todos-list{list-style:none;margin:0 0 12px;padding:8px 10px;background:#0f0620;border-radius:8px;" +
     "border:1px solid #3a2a60;}" +
@@ -270,16 +269,14 @@ export const RUNNER_EXTRA_CSS =
     "#wg-panel button.wg-mini-next{background:#2a9d6f;border-color:#22855e;color:#fff;display:none;}" +
     "#wg-panel button.wg-mini-next:hover{background:#22855e;}" +
     "#wg-panel button.wg-mini-next:disabled{opacity:.55;cursor:default;}" +
-    "#wg-panel.wg-collapsed{width:auto;max-width:92vw;padding:8px 12px;max-height:none;overflow:hidden;}" +
+    "#wg-panel.wg-collapsed{width:auto;padding:8px 12px;overflow:hidden;}" +
     "#wg-panel.wg-collapsed .wg-body{display:none;}" +
     "#wg-panel.wg-collapsed .wg-chrome{margin:0;}" +
     "#wg-panel.wg-collapsed .wg-chrome-title{font:700 13px/1.25 system-ui,sans-serif;color:#fff;" +
     "letter-spacing:0;text-transform:none;}" +
     "#wg-panel.wg-collapsed button.wg-mini-next.wg-mini-next-show{display:inline-block;}" +
     "@media (max-width:640px){" +
-    "#wg-panel{left:8px;right:8px;bottom:8px;transform:none;max-width:none;width:auto;" +
-    "max-height:min(55vh,calc(100vh - 16px));padding:12px 14px;border-radius:12px;}" +
-    "#wg-panel.wg-collapsed{left:50%;right:auto;transform:translateX(-50%);width:auto;}" +
+    "#wg-panel{width:auto;padding:12px 14px;border-radius:12px;}" +
     "#wg-episodes{overflow-x:auto;-webkit-overflow-scrolling:touch;flex-wrap:nowrap;}" +
     "#wg-panel .wg-narration{font-size:13px;}" +
     "#wg-panel button{width:100%;}" +

package/dist/demo/overlay/overlay-stage.js

@@ -49,7 +49,7 @@ export function createOverlayStage(page, { todoDockRef, deviceRef }) {
         if (!docks.length) {
             // Empty registry: do NOT clear the DOM. renderBefore/After may have
             // just painted from lastTodoDock (keep). Clearing here made todos
-            // vanish until the next ctx.todos() set (PIA #15).
+            // vanish until the next ctx.ui.todos() set (PIA #15).
             return;
         }
         await page

package/dist/demo/overlay/phase-fixtures.js

@@ -43,17 +43,17 @@ export function phaseToOverlayFixtures(phase, holdMs = 6000) {
 export function describeOverlayFixtures(tag, f) {
     const out = [];
     if (f.title)
-        out.push(`${tag} ctx.title(${JSON.stringify(f.title)})${f.titlePos ? ` pos=${f.titlePos}` : ""}`);
+        out.push(`${tag} ctx.ui.title(${JSON.stringify(f.title)})${f.titlePos ? ` pos=${f.titlePos}` : ""}`);
     if (f.bannerUi)
-        out.push(`${tag} ctx.bannerUi(${JSON.stringify(f.bannerUi)})`);
+        out.push(`${tag} ctx.ui.bannerUi(${JSON.stringify(f.bannerUi)})`);
     if (f.todos?.length)
-        out.push(`${tag} ctx.todos n=${f.todos.length} index=${f.todoIndex ?? 0}${f.todoPos ? ` pos=${f.todoPos}` : ""}`);
+        out.push(`${tag} ctx.ui.todos n=${f.todos.length} index=${f.todoIndex ?? 0}${f.todoPos ? ` pos=${f.todoPos}` : ""}`);
     if (f.todoUi)
         out.push(`${tag} todoUi ${JSON.stringify(f.todoUi)}`);
     if (f.device)
-        out.push(`${tag} ctx.device(${typeof f.device === "string" ? f.device : f.device.preset ?? "custom"})`);
+        out.push(`${tag} ctx.ui.device(${typeof f.device === "string" ? f.device : f.device.preset ?? "custom"})`);
     if (f.zoom)
-        out.push(`${tag} ctx.zoom(${f.zoom})`);
+        out.push(`${tag} ctx.ui.zoom(${f.zoom})`);
     for (const r of f.rings ?? [])
         out.push(`${tag} ring ${r.selector} tone=${r.tone ?? "planned"} label=${JSON.stringify(r.label)}`);
     return out;

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/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,29 +266,25 @@
  * 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.showNetworkTab(); stays up once shown. In the shared
+ * 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{position:fixed;z-index:2147483646;bottom:14px;left:14px;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:opacity .25s ease,transform .25s ease;overflow:hidden;}
+#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;}

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/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[" + i + "]", {
+        demoFixture(tag, "ctx.ui.ring[" + i + "]", {
             selector: h.selector,
             label: h.label,
             detail: h.detail,

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

@@ -22,5 +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.slides(...)` for the step on screen, in the flow's highlight style. */
+/** 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>;