@ubio/webvision 3.1.8 → 3.2.0

package/README.md

@@ -0,0 +1,173 @@
+# WebVision
+
+**Structured, ref-addressable views of the live DOM** for automation, debugging, and tooling.
+
+WebVision walks the browser document, builds a compact **VX tree** (semantic nodes with stable refs), and can **render** it as text, **highlight** regions on the page, and **resolve** refs back to real DOM nodes. It is designed for scenarios where you need a consistent, inspectable snapshot of “what’s on screen” without shipping a full browser automation stack.
+
+---
+
+## Why use it?
+
+- **Stable refs** — Each meaningful node gets a ref you can use to talk about “that button” or “that heading” across snapshots and tools.
+- **Readable dumps** — Turn the tree into a line-oriented string (tags, ids, classes, key attrs, text) for LLMs, logs, or diffing.
+- **Visual debugging** — Draw overlays on elements that correspond to VX nodes.
+- **Shadow DOM** — Open shadow roots are flattened into the tree by default (see [Shadow DOM](#shadow-dom)).
+- **Ships for browser and Node-oriented bundles** — ESM page bundle, IIFE global, optional Tampermonkey userscript for the **page** console.
+
+---
+
+## Install
+
+```bash
+npm install @ubio/webvision
+```
+
+Build artifacts (`out/page`, `build/*`) are included in the published package. Run `npm run compile` after cloning the repo if you develop from source.
+
+---
+
+## Quick start (ESM)
+
+```javascript
+import { captureSnapshot } from '@ubio/webvision';
+
+const tree = await captureSnapshot();
+console.log(tree.render({ renderRefs: true, renderTagNames: true }));
+```
+
+`captureSnapshot()` parses `document`, stores the latest tree and ref→DOM map on `globalThis`, and returns a **`VxTreeView`**.
+
+---
+
+## Core API
+
+| Export | Role |
+|--------|------|
+| `captureSnapshot(options?)` | Parse the page; returns `VxTreeView`; updates last snapshot. |
+| `getSnapshot()` | Return the last `VxTreeView` (throws if none). |
+| `resolveDomNode(ref)` | Map a ref string to a DOM `Node` or `null`. |
+| `renderVxNode(node, options?)` | Render a single `VxNode` subtree as text. |
+
+### `VxTreeView`
+
+| Method / property | Description |
+|-------------------|-------------|
+| `render(options?)` | String dump of the frame’s tree (see `VxRenderOptions` in source). |
+| `nodeCount` | Number of ref’d nodes in the map. |
+| `highlight(options?)` | Overlay borders for refs (needs snapshot first). |
+| `findNode(ref)` | Get the `VxNode` for a ref. |
+
+### Example: snapshot, render, highlight
+
+```javascript
+import { captureSnapshot, resolveDomNode } from '@ubio/webvision';
+
+const tree = await captureSnapshot();
+
+console.log(tree.render({
+  renderRefs: true,
+  renderTagNames: true,
+  renderIds: true,
+}));
+
+tree.highlight({ clearOverlay: true });
+
+const el = resolveDomNode('0abc'); // example ref from render output
+```
+
+### Parser options (`VxTreeOptions`)
+
+Passed to `captureSnapshot({ ... })`:
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `flattenShadowDom` | `true` | Include **open** shadow roots after light-DOM children; set `false` for light DOM only. |
+| `viewportOnly` | `false` | Drop nodes outside the viewport. |
+| `probeViewport` | `false` | Extra viewport probing (see `probe.ts`). |
+| `skipImages` | `false` | Omit `img` nodes when omitting. |
+| `opaqueOverlays` | `false` | Try to flatten opaque overlays for parsing. |
+| `unnestDivs` | `false` | Aggressive pruning of bare div/spans. |
+| `frameId` / `iframeRef` | — | Multi-frame scenarios. |
+
+---
+
+## Shadow DOM
+
+Open shadow trees are walked **after** each host’s light DOM children so the rendered tree matches a **flattened** structural view. **Closed** shadow roots cannot be accessed from script.
+
+To restore the previous behavior (ignore shadow trees):
+
+```javascript
+await captureSnapshot({ flattenShadowDom: false });
+```
+
+---
+
+## Package exports
+
+| Import path | Output | Use case |
+|-------------|--------|----------|
+| `@ubio/webvision` | `out/page` (TypeScript build) | Types + ESM in TS projects. |
+| `@ubio/webvision/page` | `build/page.mjs` | Single ESM bundle of the page module. |
+| `@ubio/webvision/global` | `build/global.js` | IIFE; exposes `globalThis.WebVision` in the browser. |
+
+Generate bundles from source:
+
+```bash
+npm run compile:page    # build/page.mjs
+npm run compile:global    # build/global.js + source map
+```
+
+---
+
+## Browser console: Tampermonkey
+
+For **`window.WebVision`** in the **page** DevTools console (not the extension isolated world), use the generated userscript.
+
+1. **Build** (from repo root):
+
+   ```bash
+   npm run compile:userscript
+   ```
+
+   Produces `build/global.js` and `build/webvision.user.js`.
+
+2. **Default workflow (hot reload)**  
+   - Terminal A: `npm run serve:build` — serves `build/` at `http://127.0.0.1:3847`.  
+   - Terminal B: `npm run dev:global` — rebuilds `global.js` on TS changes.  
+   - Install **`build/webvision.user.js`** in Tampermonkey (Dashboard → install).  
+   - Reload the tab; the script fetches `global.js` with a cache-busting query and injects it into the page.
+
+3. **Offline / no server** — embed the bundle when generating:
+
+   ```bash
+   WEBVISION_INLINE=1 npm run compile:userscript
+   ```
+
+   Reinstall the userscript after each rebuild (large file).
+
+4. **Custom URL** when building:
+
+   ```bash
+   WEBVISION_INJECT_URL=https://your.cdn/webvision/global.js npm run compile:userscript
+   ```
+
+Requires `@grant GM.xmlHttpRequest` and matching `// @connect` for the host (generated for you for `http`/`https` URLs).
+
+---
+
+## Development
+
+| Script | Purpose |
+|--------|---------|
+| `npm run compile` | Clean, `tsc`, bundle `page.mjs` + `global.js` + `webvision.user.js`. |
+| `npm run dev` | Parallel `tsc -w` and esbuild watch for `page.mjs`. |
+| `npm run dev:global` | Watch rebuild `build/global.js`. |
+| `npm run dev:userscript` | One-shot userscript build, then `dev:global` watch. |
+| `npm run lint` | ESLint. |
+
+---
+
+## License
+
+ISC

package/build/global.js

@@ -57,8 +57,10 @@ var WebVision = (() => {
     isHidden: () => isHidden,
     isInteractive: () => isInteractive,
     isObjectEmpty: () => isObjectEmpty,
+    isPopup: () => isPopup,
     isRandomIdentifier: () => isRandomIdentifier,
     isRectInViewport: () => isRectInViewport,
+    iterate: () => iterate,
     makeOverlaysOpaque: () => makeOverlaysOpaque,
     normalizeRef: () => normalizeRef,
     normalizeText: () => normalizeText,
@@ -71,6 +73,31 @@ var WebVision = (() => {
     truncateAttrValue: () => truncateAttrValue
   });
 
+  // src/page/util.ts
+  function isContainerNode(vxNode) {
+    if (vxNode.tagName === "select") {
+      return false;
+    }
+    const children = vxNode.children ?? [];
+    const hasTextChildren = children.some((child) => !child.tagName);
+    return children.length > 0 && !hasTextChildren;
+  }
+  function isObjectEmpty(obj) {
+    return !Object.values(obj).some((value) => !!value);
+  }
+  function normalizeRef(ref) {
+    return String(ref).toLowerCase().trim().replace(/[^a-z0-9]/gi, "");
+  }
+  function* iterate(items) {
+    if (!items) {
+      return;
+    }
+    for (let i = 0; i < items.length; i += 1) {
+      const item = items[i];
+      yield item;
+    }
+  }
+
   // src/page/dom.ts
   var ORIGINAL_STYLE_SYMBOL = Symbol("vx:originalStyle");
   var INTERACTIVE_TAGS = ["a", "button", "input", "textarea", "select", "label", "option", "optgroup"];
@@ -155,7 +182,15 @@ var WebVision = (() => {
       return true;
     }
     if (!hasVisibleArea(element)) {
-      return [...element.children].every((el) => isDeepHidden(el));
+      if (element.children.length === 0) {
+        return true;
+      }
+      for (const child of iterate(element.children)) {
+        if (!isDeepHidden(child)) {
+          return false;
+        }
+      }
+      return true;
     }
     return false;
   }
@@ -181,6 +216,21 @@ var WebVision = (() => {
     }
     return false;
   }
+  function isPopup(el) {
+    const style = getComputedStyle(el);
+    const zIndex = parseInt(style.zIndex, 10);
+    const hasPopupPosition = style.position === "fixed" || style.position === "sticky" || style.position === "absolute" && zIndex >= 1e3;
+    if (!hasPopupPosition) {
+      return false;
+    }
+    const rect = el.getBoundingClientRect();
+    const area = rect.width * rect.height;
+    const viewportArea = window.innerWidth * window.innerHeight;
+    if (area <= viewportArea * 0.2) {
+      return false;
+    }
+    return true;
+  }
   function getViewportSize() {
     return {
       width: window.innerWidth,
@@ -291,11 +341,11 @@ var WebVision = (() => {
       return;
     }
     yield element;
-    for (const child of element.children) {
+    for (const child of iterate(element.children)) {
       yield* traverseElements(child);
     }
     if (element.shadowRoot) {
-      for (const child of element.shadowRoot.children) {
+      for (const child of iterate(element.shadowRoot.children)) {
         yield* traverseElements(child);
       }
     }
@@ -316,7 +366,7 @@ var WebVision = (() => {
     }
     for (const { x, y } of points.getAll()) {
       const element = document.elementFromPoint(x, y);
-      if (element && !result.has(element)) {
+      if (element) {
         result.add(element);
       }
     }
@@ -355,22 +405,6 @@ var WebVision = (() => {
     }
   };
 
-  // src/page/util.ts
-  function isContainerNode(vxNode) {
-    if (vxNode.tagName === "select") {
-      return false;
-    }
-    const children = vxNode.children ?? [];
-    const hasTextChildren = children.some((child) => !child.tagName);
-    return children.length > 0 && !hasTextChildren;
-  }
-  function isObjectEmpty(obj) {
-    return !Object.values(obj).some((value) => !!value);
-  }
-  function normalizeRef(ref) {
-    return String(ref).toLowerCase().trim().replace(/[^a-z0-9]/gi, "");
-  }
-
   // src/page/render.ts
   function renderVxNode(scope, options = {}) {
     const buffer = [];
@@ -388,14 +422,12 @@ var WebVision = (() => {
     return buffer.join("\n");
   }
   function renderIndentedLine(indent, vxNode, options = {}) {
-    const diffPrefix = options.renderDiff ? vxNode.isNew ? "+ " : "  " : "";
     if (!vxNode.tagName) {
-      return [diffPrefix, indent, vxNode.textContent].filter(Boolean).join("");
+      return [indent, vxNode.textContent].filter(Boolean).join("");
     }
     const tagLine = renderTagLine(vxNode, options);
     const htmlStyle = options.renderStyle === "html";
     return [
-      diffPrefix,
       indent,
       tagLine,
       htmlStyle ? "" : " ",
@@ -431,6 +463,9 @@ var WebVision = (() => {
         components.push(`[@${vxNode.ref}]`);
       }
     }
+    for (const meta of vxNode.meta ?? []) {
+      components.push(`[${meta}]`);
+    }
     const attrs = [];
     if (options.renderLabelAttrs) {
       for (const [attr, value] of Object.entries(vxNode.labelAttrs ?? {})) {
@@ -482,7 +517,7 @@ var WebVision = (() => {
   var VX_LAST_REFS_SYMBOL = Symbol("vx:lastRefs");
   async function captureSnapshot(options = {}) {
     const parser = new VxTreeParser(options);
-    await parser.parse();
+    parser.parse();
     const domMap = parser.getDomMap();
     const vxTree = parser.getTree();
     globalThis[VX_DOM_SYMBOL] = domMap;
@@ -555,9 +590,7 @@ var WebVision = (() => {
       for (const ref of refs) {
         const el = resolveDomNode(ref);
         if (el instanceof Element) {
-          const vxNode = this.findNode(ref);
-          const isNew = vxNode?.isNew ?? false;
-          const color = options.useColors ? void 0 : isNew ? "#0a0" : "#060";
+          const color = options.useColors ? void 0 : "#060";
           highlightEl(el, ref, color);
         }
       }
@@ -602,7 +635,7 @@ var WebVision = (() => {
     /title-/i
     // title-* attributes
   ];
-  var VX_VALUE_ATTRS = ["value", "checked", "selected", "disabled", "readonly"];
+  var VX_VALUE_ATTRS = ["role", "value", "checked", "selected", "disabled", "readonly"];
   var VX_SRC_ATTRS = ["src", "href"];
   var VX_TAG_PREFERENCE = [
     "a",
@@ -721,6 +754,8 @@ var WebVision = (() => {
       const parentEl = el.matches("option, optgroup") ? el.closest("select") ?? el : el;
       const rect = parentEl.getBoundingClientRect();
       const id = el.getAttribute("id") ?? "";
+      const isProbeHit = this.isProbeHit(parentEl);
+      const isInViewport = isRectInViewport(rect, this.viewport);
       const vxNode = this.makeElementNode(el, {
         tagName: el.tagName.toLowerCase(),
         id: isRandomIdentifier(id) ? void 0 : id,
@@ -730,19 +765,23 @@ var WebVision = (() => {
         srcAttrs: this.collectSrcAttrs(el),
         hasVisibleArea: hasVisibleArea(parentEl),
         isInteractive: isInteractive(parentEl),
-        isOutsideViewport: !isRectInViewport(rect, this.viewport),
-        isProbeHit: this.isProbeHit(parentEl),
-        isKept: el.matches(VX_KEEP_SELECTOR)
+        isOutsideViewport: !isInViewport,
+        isProbeHit,
+        isKept: el.matches(VX_KEEP_SELECTOR),
+        meta: [
+          isPopup(parentEl) ? "popup" : null,
+          isInViewport && !isProbeHit ? "occluded" : null
+        ].filter((_) => _ != null)
       });
       const children = [];
-      for (const child of el.childNodes) {
+      for (const child of iterate(el.childNodes)) {
         const childNode = this.parseNode(child, vxNode);
         if (childNode != null) {
           children.push(childNode);
         }
       }
       if (this.options.flattenShadowDom !== false && el.shadowRoot) {
-        for (const child of el.shadowRoot.childNodes) {
+        for (const child of iterate(el.shadowRoot.childNodes)) {
           const childNode = this.parseNode(child, vxNode);
           if (childNode != null) {
             children.push(childNode);
@@ -758,9 +797,8 @@ var WebVision = (() => {
     }
     makeElementNode(el, spec) {
       const existingRef = el[VX_NODE_REF_SYMBOL];
-      const isNew = existingRef === void 0;
       let ref;
-      if (isNew) {
+      if (existingRef === void 0) {
         const counter = this.nextCounterValue();
         ref = `${this.frameId}${counter}`;
         this.usedCounters.add(counter);
@@ -771,8 +809,7 @@ var WebVision = (() => {
       }
       const vxNode = {
         ...spec,
-        ref,
-        isNew
+        ref
       };
       this.domRefMap.set(ref, el);
       return vxNode;
@@ -867,7 +904,7 @@ var WebVision = (() => {
     }
     collectLabelAttrs(el) {
       const attrs = {};
-      for (const attr of el.attributes) {
+      for (const attr of iterate(el.attributes)) {
         const attrName = attr.name;
         const value = truncateAttrValue(attr.value);
         if (!value) {
@@ -907,11 +944,11 @@ var WebVision = (() => {
       delete node[VX_NODE_REF_SYMBOL];
       delete node[VX_NODE_COUNTER_SYMBOL];
       if (node instanceof Element) {
-        for (const child of node.children) {
+        for (const child of iterate(node.children)) {
           this.clearRecursive(child);
         }
         if (node.shadowRoot) {
-          for (const child of node.shadowRoot.children) {
+          for (const child of iterate(node.shadowRoot.children)) {
             this.clearRecursive(child);
           }
         }
@@ -931,11 +968,11 @@ var WebVision = (() => {
       if (cnt !== void 0) {
         this.usedCounters.add(cnt);
       }
-      for (const child of el.children ?? []) {
+      for (const child of iterate(el.children)) {
         this.collectDomCounters(child);
       }
       if (el.shadowRoot) {
-        for (const child of el.shadowRoot.children) {
+        for (const child of iterate(el.shadowRoot.children)) {
           this.collectDomCounters(child);
         }
       }