waygraph 0.16.2 → 0.16.4

package/README.md

@@ -100,6 +100,7 @@ names) still works and is fine for small projects, but the Map is where the tool
 | See the whole graph | `waygraph graph` |
 | Lint your Blocks and folders | `waygraph check` / `waygraph typecheck` / `waygraph map` |
 | Open a persistent browser for an agent | `waygraph browser start` |
+| Read what the page shows, as JSON (beta: Read Blocks) | `waygraph pilot read <id> [path]` |
 | Highlight things on the live page | `waygraph browser highlight <id> "#login\|Login button\|warning"` |
 | Set up coding-agent skills | `waygraph agent-dive --loop claude` |
 
@@ -124,4 +125,15 @@ npm run typecheck && npm test        # unit + Playwright suites
 Working on waygraph: [`AGENTS.md`](./AGENTS.md) (the rules, how to verify) and
 [`src/ARCHITECTURE.md`](./src/ARCHITECTURE.md) (where the code starts).
 
+## Status: alpha
+
+> [!WARNING]
+> Waygraph is an alpha build. Its syntax may still change in major ways between releases, and a release can remove
+> API (each removal is listed in [what was removed](./docs/deprecated.md); `waygraph upgrade --codemod` converts most
+> of it). For now we recommend staying on 0.16.0:
+>
+> ```bash
+> npm install --save-exact waygraph@0.16.0
+> ```
+
 MIT

package/dist/analysis/practices-check.d.ts

@@ -1,4 +1,4 @@
-export type PracticeKind = "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
+export type PracticeKind = "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file" | "hand-written-ui";
 export interface PracticeWarning {
     kind: PracticeKind;
     file: string;

package/dist/analysis/practices-check.js

@@ -46,6 +46,15 @@ const XPATH_LOCATOR = /\.locator\(\s*["'`](?:xpath=)?\/\//;
  *  scoped to simple, single-token selectors (id/class/attr/tag) so this doesn't fire on the
  *  legitimate multi-part selectors `.sel.ts` files themselves are made of. */
 const INLINE_SIMPLE_SELECTOR = /(?:\.locator|\bclick|\burl)\s*[:(]\s*["'`](#|\.)[\w-]+["'`]/;
+/**
+ * Hand-written UI in a test project - real, recurring pattern: an LLM wanting a caption, a highlight or a banner builds
+ * its own DOM in the page or restyles / reaches into waygraph's overlay, instead of using `ctx.ui`. It changes the page
+ * under test and breaks whenever the overlay changes.
+ */
+const OVERLAY_INTERNALS = /\b__wg[A-Za-z]|["'`][^"'`\n]*(?:#wg-|\.wg-|wg-root)/;
+const DOM_BUILD = /\bdocument\.createElement\(|\.innerHTML\s*=|\binsertAdjacentHTML\(|\baddStyleTag\(|\.style\.cssText|\.style\.[a-zA-Z]+\s*=(?!=)/;
+/** Shared narration (`src/stubs/*.ts`) is checked for hand-written UI too, next to Block and flow files. */
+const STUB_FILE = /[\\/]stubs[\\/][^\\/]+\.ts$/;
 const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
 const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
 /** Whole-file opt-out: `// waygraph-ignore-practices` */
@@ -55,6 +64,13 @@ const IGNORE_KINDS = /waygraph-ignore:\s*([^\n*]+)/;
 function walkBlockAndFlowFiles(projectDir, walkDir) {
     return walkDir(projectDir, SCAN_GLOB);
 }
+function handWrittenUi(src) {
+    if (OVERLAY_INTERNALS.test(src))
+        return "reaches into waygraph's overlay (#wg-*, .wg-*, window.__wg*)";
+    if (DOM_BUILD.test(src))
+        return "builds or restyles page DOM (createElement / innerHTML / addStyleTag / .style)";
+    return undefined;
+}
 function ignoredKindsForFile(src) {
     if (IGNORE_ALL.test(src))
         return "all";
@@ -143,6 +159,9 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
                 });
             }
         }
+        const ui = isIgnored("hand-written-ui", ignore) ? undefined : handWrittenUi(src);
+        if (ui)
+            warnings.push(handWrittenUiWarning(rel, ui));
         if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
             warnings.push({
                 kind: "empty-verify",
@@ -152,8 +171,23 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
             });
         }
     }
+    for (const file of walkDir(projectDir, /\.ts$/).filter((f) => STUB_FILE.test(f) && !SCAN_GLOB.test(f))) {
+        const src = readFileSync(file, "utf-8");
+        const ui = isIgnored("hand-written-ui", ignoredKindsForFile(src)) ? undefined : handWrittenUi(src);
+        if (ui)
+            warnings.push(handWrittenUiWarning(relative(projectDir, file).replace(/\\/g, "/"), ui));
+    }
     return warnings;
 }
+function handWrittenUiWarning(file, what) {
+    return {
+        kind: "hand-written-ui",
+        file,
+        detail: `${what} - narration goes through ctx.ui (ring, caption, title, todos, slides, device, zoom, network tab), ` +
+            "and a test never changes the page it tests. Missing something in ctx.ui? Ask for it in waygraph instead of " +
+            "overriding; opt out with // waygraph-ignore: hand-written-ui",
+    };
+}
 export function practiceKindLabel(kind) {
     switch (kind) {
         case "multi-input":
@@ -166,6 +200,8 @@ export function practiceKindLabel(kind) {
             return "regex/XPath selector where a plain one would do";
         case "inline-selector-should-use-sel-file":
             return "inline selector — a _sel.ts/*.sel.ts file already exists here";
+        case "hand-written-ui":
+            return "hand-written UI — use ctx.ui, don't build or override the overlay";
         default: {
             const _exhaustive = kind;
             return _exhaustive;

package/dist/beta.d.ts

@@ -0,0 +1,6 @@
+export { reads, ReadKey } from "./engine/read/read-key.js";
+export type { ReadNamespace, ReadSpec, ReadFieldsOf } from "./engine/read/read-key.js";
+export type { Reader, ReadCtx, RowCtx } from "./engine/read/readers.js";
+export { ReadPage } from "./engine/read/read-page.js";
+export { defineReadBlock, readCheckpoint } from "./engine/read/read-block.js";
+export type { ReadBlock, ReadBlockOptions, CheckpointRead } from "./engine/read/read-block.js";

package/dist/beta.js

@@ -0,0 +1,5 @@
+// The `waygraph/beta` entry: features whose shape may still change before they move into `waygraph`. Import them from
+// "waygraph/beta"; a beta release can rename or reshape them.
+export { reads, ReadKey } from "./engine/read/read-key.js";
+export { ReadPage } from "./engine/read/read-page.js";
+export { defineReadBlock, readCheckpoint } from "./engine/read/read-block.js";

package/dist/cli/commands/codemod-flows.js

@@ -103,7 +103,7 @@ function indentOf(node) {
     return " ".repeat(statement.getIndentationLevel() * 2);
 }
 function titleStub(block, title, indent) {
-    return `${block}.stubBefore((ctx) => {\n${indent}    ctx.title(${title});\n${indent}  })`;
+    return `${block}.stubBefore((ctx) => {\n${indent}    ctx.ui.title(${title});\n${indent}  })`;
 }
 function chain(head, steps, indent) {
     return [head, ...steps, ".end()"].join(`\n${indent}  `);
@@ -172,7 +172,7 @@ function rewrite(call, kindOf, needsMap) {
         if (name === "withTitle") {
             const first = mapCall && firstStepOf(mapCall);
             if (!first)
-                return `withTitle(${flow.getText().split("\n")[0]}, …): name the flow with ctx.title(…) in a stub on its first step`;
+                return `withTitle(${flow.getText().split("\n")[0]}, …): name the flow with ctx.ui.title(…) in a stub on its first step`;
             addTitle(first, args[1].getText());
         }
         else if (mapCall) {

package/dist/cli/commands/codemod-stubs.js

@@ -6,7 +6,8 @@
 // `ctx.ring` calls, and a stub set in a `define*Block({ ... })` (options or instruction) moves out to a chained
 // `.stubBefore(...)` on the Block; a Block's `slides` become `ctx.slides(...)` in its chained `.stubAfter(...)`;
 // `ctx.highlights({ a: ring })` becomes one `ctx.ring("a", ring)` per ring; `narrate(locator, caption, action)` in an
-// `act` becomes the action, reported so the caption can move to a stubBefore ring. Works on the TypeScript AST (ts-morph).
+// `act` becomes the action, reported so the caption can move to a stubBefore ring. Last, everything a stub paints moves
+// under `ctx.ui` (`ctx.ring(...)` -> `ctx.ui.ring(...)`). Works on the TypeScript AST (ts-morph).
 import { Node, SyntaxKind } from "ts-morph";
 const RENAMED = {
     banner: (a) => `title(${a.join(", ")})`,
@@ -248,6 +249,45 @@ function unwrapNarrate(sf, problems) {
     }
     return changed;
 }
+/** Everything a stub paints, which 0.16.3 moved under `ctx.ui`. */
+const UI_METHODS = new Set(["ring", "todos", "todoIndex", "todoGroups", "hideTodos", "device", "viewport", "touch", "orientation", "hideDevice", "zoom", "zoomOut", "title", "titlePos", "bannerUi", "caption", "hideCaption", "slides", "hideBanner", "showNetworkTab", "hideNetworkTab", "todoDockUi"]);
+/** Whether `name` at `node` is a stub's ctx: the nearest enclosing function with a parameter of that name is a stub. */
+function isStubCtxName(node, name) {
+    for (const fn of node.getAncestors()) {
+        if (!(Node.isArrowFunction(fn) || Node.isFunctionExpression(fn) || Node.isFunctionDeclaration(fn) || Node.isMethodDeclaration(fn)))
+            continue;
+        const param = fn.getParameters().find((p) => p.getName() === name);
+        if (!param)
+            continue;
+        if (/StubCtx/.test(param.getType().getText(param)))
+            return true;
+        const parent = fn.getParent();
+        const callee = Node.isCallExpression(parent) ? parent.getExpression() : undefined;
+        if (Node.isPropertyAccessExpression(callee) && /^stub(Before|After|OnError)$/.test(callee.getName()))
+            return true;
+        if (Node.isPropertyAssignment(parent) && /^stub(Before|After|OnError)$/.test(parent.getName()))
+            return true;
+        // `((ctx) => ...)(ctx)`, as the slides merge writes it: called at once with an outer stub's ctx.
+        const call = Node.isParenthesizedExpression(parent) ? parent.getParent() : undefined;
+        const arg = Node.isCallExpression(call) ? call.getArguments()[0] : undefined;
+        return arg !== undefined && Node.isIdentifier(arg) && isStubCtxName(call, arg.getText());
+    }
+    return false;
+}
+/** `ctx.ring(...)` -> `ctx.ui.ring(...)`, everywhere a stub's ctx paints (idempotent: `ctx.ui.ring` is left alone). */
+function moveToUi(sf) {
+    let changed = false;
+    for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression).reverse()) {
+        if (access.wasForgotten() || !UI_METHODS.has(access.getName()))
+            continue;
+        const receiver = access.getExpression();
+        if (!Node.isIdentifier(receiver) || !isStubCtxName(access, receiver.getText()))
+            continue;
+        access.replaceWithText(`${receiver.getText()}.ui.${access.getName()}`);
+        changed = true;
+    }
+    return changed;
+}
 /** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
 export function convertStubs(project) {
     const changed = [];
@@ -267,6 +307,8 @@ export function convertStubs(project) {
             if (convertStatements(block.getStatements(), left))
                 touched = true;
         }
+        if (moveToUi(sf))
+            touched = true;
         if (touched)
             changed.push(sf);
         problems.push(...left.map((p) => ({ file: sf.getFilePath(), ...p })));

package/dist/cli/commands/pilot.js

@@ -9,6 +9,7 @@ import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
 import { parseCommand } from "../args.js";
 import { applyRunFlags, parseRunFlags } from "../flags.js";
 import { printBrowserSessionsList } from "../usage.js";
+import { isSessionOp } from "./session-ops.js";
 /** Runs a `pilot` subcommand; false when it is a session op for session-ops.ts. */
 export async function pilotCase(args) {
     if (args[1] === "sessions") {
@@ -76,26 +77,12 @@ export async function pilotCase(args) {
         }
         return true;
     }
-    if (args[1] !== "send" &&
-        args[1] !== "status" &&
-        args[1] !== "dom" &&
-        args[1] !== "trace" &&
-        args[1] !== "console" &&
-        args[1] !== "storage" &&
-        args[1] !== "upload" &&
-        args[1] !== "click" &&
-        args[1] !== "type" &&
-        args[1] !== "press" &&
-        args[1] !== "goto" &&
-        args[1] !== "reload" &&
-        args[1] !== "reach" &&
-        args[1] !== "resync" &&
-        args[1] !== "highlight") {
+    if (!isSessionOp("pilot", args[1])) {
         console.error("waygraph pilot: usage:\n" +
             "  waygraph pilot start [--inject …] [--goto <url>] [--headless] [--cli] [--base-url <url>] [project]\n" +
             "  waygraph pilot sessions [project]   # list live browser sessions\n" +
             "  waygraph pilot attach <sessionId>   # graph + snapshot for an existing session\n" +
-            "  waygraph pilot send|status|attach|highlight|… <sessionId> …  (controls browser — same as browser/auto)");
+            "  waygraph pilot send|status|read|attach|highlight|… <sessionId> …  (controls browser — same as browser/auto)");
         process.exit(1);
     }
     return false;

package/dist/cli/commands/session-ops.js

@@ -5,6 +5,8 @@ import { parseHighlightShorthand } from "../../demo/narration/shorthand.js";
 import { resolveSessionMeta } from "../../live/auto-session/files.js";
 import { requestSession, runAttachLoop } from "../../live/auto-session/ipc.js";
 import { parseCommand } from "../args.js";
+import { subscribeSession } from "../../live/auto-session/feed.js";
+import { SESSION_OPS } from "../../live/auto-session/protocol.js";
 const SEND_OPTIONS = {
     timeout: { type: "string", value: "<ms>", help: "How long one Block may run (default 15000)" },
 };
@@ -13,7 +15,8 @@ const DOM_OPTIONS = {
     selector: { type: "string", value: "<css>", help: "Only this element's subtree" },
     depth: { type: "string", value: "N", help: "Levels to read" },
 };
-const OPS = new Set(["send", "status", "attach", "dom", "trace", "console", "storage", "upload", "click", "type", "press", "goto", "reload", "reach", "resync", "highlight"]);
+/** The protocol's ops, as CLI subcommands: `subscribe` is `watch`; `attach` is the CLI's own interactive loop. */
+const OPS = new Set([...SESSION_OPS.filter((op) => op !== "subscribe"), "watch", "attach"]);
 /** Whether `sub` is a session op (`attach` is pilot's own subcommand, not an op, under `pilot`). */
 export function isSessionOp(command, sub) {
     return sub !== undefined && OPS.has(sub) && !(sub === "attach" && command === "pilot");
@@ -113,6 +116,28 @@ export async function sessionOpCase(args, command) {
             process.exitCode = 1;
         return;
     }
+    if (sub === "hello") {
+        const res = await requestSession(proj, sessionId, { op: "hello" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "watch") {
+        // One JSON line per run event (steps, reads) and per new snapshot, until Ctrl-C or the session ends.
+        const feed = await subscribeSession(proj, sessionId, (message) => console.log(JSON.stringify(message)));
+        process.once("SIGINT", () => feed.close());
+        await feed.closed;
+        return;
+    }
+    if (sub === "read") {
+        const path = args[3];
+        const res = await requestSession(proj, sessionId, path ? { op: "read", path } : { op: "read" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (sub === "storage") {
         const res = await requestSession(proj, sessionId, { op: "storage" });
         console.log(JSON.stringify(res));

package/dist/cli/flags.d.ts

@@ -110,7 +110,7 @@ export declare const RUN_OPTIONS: {
     };
     readonly "todo-left": {
         readonly type: "boolean";
-        readonly help: "Floating checklist dock on the left (also ctx.todos(id, items, { pos }))";
+        readonly help: "Floating checklist dock on the left (also ctx.ui.todos(id, items, { pos }))";
         readonly for: readonly ["demo"];
     };
     readonly "todo-right": {

package/dist/cli/flags.js

@@ -18,7 +18,7 @@ export const RUN_OPTIONS = {
     "fast": { type: "boolean", help: "Shorter auto-next / Next gates (keeps the smooth cursor)", for: ["demo"] },
     "full": { type: "boolean", help: "Classic wrap-all block chips (default: carousel)", for: ["demo"] },
     "mini": { type: "boolean", help: "Force the compact mini panel (Hide pill + Next)", for: ["demo"] },
-    "todo-left": { type: "boolean", help: "Floating checklist dock on the left (also ctx.todos(id, items, { pos }))", for: ["demo"] },
+    "todo-left": { type: "boolean", help: "Floating checklist dock on the left (also ctx.ui.todos(id, items, { pos }))", for: ["demo"] },
     "todo-right": { type: "boolean", help: "Floating checklist dock on the right", for: ["demo"] },
     "todo-full": { type: "boolean", help: "Full checklist: no compact / collision / behind-ring", for: ["demo"] },
     "todo-smart": { type: "boolean", help: "Compact + collision + behind-ring (the default)", for: ["demo"] },

package/dist/cli/usage.js

@@ -66,6 +66,12 @@ Primary (less is more):
                                            does nothing observable in the DOM) that inspectDom
                                            alone can't explain, since it only reads what actually
                                            rendered, not what the page/network actually said
+  waygraph auto watch <sessionId>          Live feed, one JSON line each: every run event (steps,
+                                           step:read) and the snapshot after each change. Ctrl-C ends
+  waygraph auto hello <sessionId>          The session protocol version, waygraph version, where it is
+  waygraph auto read <sessionId> [path]    (beta) What the page shows, as JSON, from the project's
+                                           Read Blocks (*.read.block.ts); [path] narrows it, e.g.
+                                           post.comments. Read it before reaching for dom
   waygraph auto storage <sessionId>        Read localStorage/sessionStorage plus registered
                                            service workers (scope/active URL/state) - client-
                                            side state (push-subscription/auth tokens etc.) that

package/dist/demo/narration/stub-ctx.js

@@ -25,136 +25,138 @@ export function createStubCtx(bag, opts) {
         mem: opts.mem,
         out: opts.out,
         error: opts.error,
-        ring(id, stub) {
-            bag.highlights = { ...bag.highlights, [id]: stub };
-        },
-        todos(id, items, opts = {}) {
-            setDock(id, opts);
-            bag.todos = items;
-            if (opts.index != null)
-                bag.todoIndex = Number(opts.index);
-            if (!items.length)
-                bag.hideTodos = true;
-        },
-        todoIndex(n) {
-            bag.todoIndex = n;
-        },
-        todoGroups(id, groups, opts = {}) {
-            setDock(id, opts);
-            bag.todoGroups = groups;
-            if (!groups.length)
+        ui: {
+            ring(id, stub) {
+                bag.highlights = { ...bag.highlights, [id]: stub };
+            },
+            todos(id, items, opts = {}) {
+                setDock(id, opts);
+                bag.todos = items;
+                if (opts.index != null)
+                    bag.todoIndex = Number(opts.index);
+                if (!items.length)
+                    bag.hideTodos = true;
+            },
+            todoIndex(n) {
+                bag.todoIndex = n;
+            },
+            todoGroups(id, groups, opts = {}) {
+                setDock(id, opts);
+                bag.todoGroups = groups;
+                if (!groups.length)
+                    bag.hideTodos = true;
+            },
+            hideTodos() {
+                bag.todoTouched = true;
                 bag.hideTodos = true;
-        },
-        hideTodos() {
-            bag.todoTouched = true;
-            bag.hideTodos = true;
-            bag.todos = [];
-            delete bag.todoGroups;
-        },
-        device(preset) {
-            bag.deviceTouched = true;
-            bag.hideDevice = false;
-            const resolved = resolveDeviceState(preset, bag.touchOverride, bag.orientationOverride);
-            if (resolved) {
-                bag.device = resolved;
-                if (resolved.preset === "desktop" && !resolved.touchMode) {
-                    bag.hideDevice = true;
+                bag.todos = [];
+                delete bag.todoGroups;
+            },
+            device(preset) {
+                bag.deviceTouched = true;
+                bag.hideDevice = false;
+                const resolved = resolveDeviceState(preset, bag.touchOverride, bag.orientationOverride);
+                if (resolved) {
+                    bag.device = resolved;
+                    if (resolved.preset === "desktop" && !resolved.touchMode) {
+                        bag.hideDevice = true;
+                    }
                 }
-            }
-        },
-        viewport(box) {
-            bag.deviceTouched = true;
-            bag.hideDevice = false;
-            const resolved = resolveDeviceState(box, bag.touchOverride, bag.orientationOverride);
-            if (resolved)
-                bag.device = resolved;
-        },
-        touch(on) {
-            bag.deviceTouched = true;
-            const enabled = on === undefined ? true : !!on;
-            bag.touchOverride = enabled;
-            if (enabled)
+            },
+            viewport(box) {
+                bag.deviceTouched = true;
                 bag.hideDevice = false;
-            if (bag.device) {
-                bag.device = {
-                    ...bag.device,
-                    touchMode: enabled,
-                    hasTouch: bag.device.hasTouch || enabled,
-                };
+                const resolved = resolveDeviceState(box, bag.touchOverride, bag.orientationOverride);
+                if (resolved)
+                    bag.device = resolved;
+            },
+            touch(on) {
+                bag.deviceTouched = true;
+                const enabled = on === undefined ? true : !!on;
+                bag.touchOverride = enabled;
                 if (enabled)
                     bag.hideDevice = false;
-            }
-            else if (enabled) {
-                const base = resolveDeviceState("desktop", true, bag.orientationOverride);
+                if (bag.device) {
+                    bag.device = {
+                        ...bag.device,
+                        touchMode: enabled,
+                        hasTouch: bag.device.hasTouch || enabled,
+                    };
+                    if (enabled)
+                        bag.hideDevice = false;
+                }
+                else if (enabled) {
+                    const base = resolveDeviceState("desktop", true, bag.orientationOverride);
+                    if (base)
+                        bag.device = { ...base, touchMode: true, hasTouch: true };
+                }
+            },
+            orientation(o) {
+                const want = normalizeDeviceOrientation(o);
+                if (!want)
+                    return;
+                bag.deviceTouched = true;
+                bag.hideDevice = false;
+                bag.orientationOverride = want;
+                const base = bag.device ||
+                    resolveDeviceState("mobile", bag.touchOverride) ||
+                    resolveDeviceState("mobile");
                 if (base)
-                    bag.device = { ...base, touchMode: true, hasTouch: true };
-            }
-        },
-        orientation(o) {
-            const want = normalizeDeviceOrientation(o);
-            if (!want)
-                return;
-            bag.deviceTouched = true;
-            bag.hideDevice = false;
-            bag.orientationOverride = want;
-            const base = bag.device ||
-                resolveDeviceState("mobile", bag.touchOverride) ||
-                resolveDeviceState("mobile");
-            if (base)
-                bag.device = applyOrientation(base, want);
-        },
-        hideDevice() {
-            bag.deviceTouched = true;
-            bag.hideDevice = true;
-            bag.device = resolveDeviceState("desktop", false);
-            bag.touchOverride = false;
-            bag.orientationOverride = undefined;
-        },
-        zoom(n) {
-            if (Number.isFinite(n) && n > 0)
-                bag.zoom = n;
-        },
-        zoomOut(keep) {
-            bag.zoomOut = !!keep;
-        },
-        title(text, opts) {
-            bag.title = String(text ?? "");
-            const p = normalizeBannerPos(opts?.pos);
-            if (p)
-                bag.titlePos = p;
-        },
-        titlePos(side) {
-            const p = normalizeBannerPos(side);
-            if (p)
-                bag.titlePos = p;
-        },
-        caption(text) {
-            bag.caption = String(text ?? "");
-        },
-        slides(slides) {
-            bag.slides = slides;
-        },
-        hideCaption() {
-            bag.caption = "";
-        },
-        showNetworkTab() {
-            bag.networkTabVisible = true;
-        },
-        hideNetworkTab() {
-            bag.networkTabVisible = false;
-        },
-        bannerUi(opts) {
-            if (!opts || typeof opts !== "object")
-                return;
-            bag.bannerUi = { ...(bag.bannerUi || {}), ...opts };
-        },
-        hideBanner() {
-            bag.bannerUi = { ...(bag.bannerUi || {}), hidden: true };
-        },
-        todoDockUi(opts) {
-            if (!opts || typeof opts !== "object")
-                return;
-            bag.todoDockUi = { ...(bag.todoDockUi || {}), ...opts };
+                    bag.device = applyOrientation(base, want);
+            },
+            hideDevice() {
+                bag.deviceTouched = true;
+                bag.hideDevice = true;
+                bag.device = resolveDeviceState("desktop", false);
+                bag.touchOverride = false;
+                bag.orientationOverride = undefined;
+            },
+            zoom(n) {
+                if (Number.isFinite(n) && n > 0)
+                    bag.zoom = n;
+            },
+            zoomOut(keep) {
+                bag.zoomOut = !!keep;
+            },
+            title(text, opts) {
+                bag.title = String(text ?? "");
+                const p = normalizeBannerPos(opts?.pos);
+                if (p)
+                    bag.titlePos = p;
+            },
+            titlePos(side) {
+                const p = normalizeBannerPos(side);
+                if (p)
+                    bag.titlePos = p;
+            },
+            caption(text) {
+                bag.caption = String(text ?? "");
+            },
+            slides(slides) {
+                bag.slides = slides;
+            },
+            hideCaption() {
+                bag.caption = "";
+            },
+            showNetworkTab() {
+                bag.networkTabVisible = true;
+            },
+            hideNetworkTab() {
+                bag.networkTabVisible = false;
+            },
+            bannerUi(opts) {
+                if (!opts || typeof opts !== "object")
+                    return;
+                bag.bannerUi = { ...(bag.bannerUi || {}), ...opts };
+            },
+            hideBanner() {
+                bag.bannerUi = { ...(bag.bannerUi || {}), hidden: true };
+            },
+            todoDockUi(opts) {
+                if (!opts || typeof opts !== "object")
+                    return;
+                bag.todoDockUi = { ...(bag.todoDockUi || {}), ...opts };
+            },
         },
     };
 }

package/dist/demo/overlay/cursor.js

@@ -51,7 +51,7 @@ export async function playSwipeTrail(page, opts) {
         layer.id = "wg-swipe-layer";
         layer.setAttribute("data-wg-ui", "1");
         layer.style.cssText =
-            "position:fixed;inset:0;z-index:2147483646;pointer-events:none;overflow:hidden;";
+            "position:fixed;inset:0;z-index:var(--wg-z-cursor,2147483646);pointer-events:none;overflow:hidden;";
         const finger = document.createElement("div");
         finger.style.cssText =
             "position:absolute;width:28px;height:28px;margin:-14px 0 0 -14px;border-radius:50%;" +

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

@@ -2,6 +2,7 @@ export function installBanner({ title, favicon, bannerPos, bannerUi, tag: banner
     const POSITIONS = ["left", "center", "right"];
     const applyPos = (el, pos) => {
         el.dataset.pos = pos;
+        __wgAdd(el);
         el.dataset.home = pos;
         try {
             localStorage.setItem("wg-banner-pos", pos);
@@ -79,6 +80,7 @@ export function installBanner({ title, favicon, bannerPos, bannerUi, tag: banner
     if (bannerEl) {
         if (bui.pos && POSITIONS.includes(bui.pos) && bannerEl.dataset.home !== bui.pos) {
             bannerEl.dataset.pos = bui.pos;
+            __wgAdd(bannerEl);
             bannerEl.dataset.home = bui.pos;
             bannerEl.dataset.authored = "1";
         }
@@ -108,6 +110,7 @@ export function installBanner({ title, favicon, bannerPos, bannerUi, tag: banner
                 (window.__wgBannerLog = window.__wgBannerLog || []).push(line);
         };
         b.dataset.pos = home;
+        __wgAdd(b);
         if (!hits()) {
             delete b.dataset.moved;
             log("clear");
@@ -115,6 +118,7 @@ export function installBanner({ title, favicon, bannerPos, bannerUi, tag: banner
         }
         for (const cand of POSITIONS.filter((p) => p !== home)) {
             b.dataset.pos = cand;
+            __wgAdd(b);
             if (!hits()) {
                 b.dataset.moved = home + ">" + cand;
                 log("moved:" + cand, "moved " + home + " -> " + cand + " (ring overlap)");
@@ -122,6 +126,7 @@ export function installBanner({ title, favicon, bannerPos, bannerUi, tag: banner
             }
         }
         b.dataset.pos = home;
+        __wgAdd(b);
         b.dataset.moved = "none-free";
         log("none-free", "overlap at every position (kept " + home + ")");
     };