@ulpi/browse 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/ulpi-io/browse"

package/skill/SKILL.md

@@ -261,7 +261,8 @@ browse accessibility      Accessibility tree snapshot (ARIA)
 ```
 browse snapshot           Full accessibility tree with @refs
 browse snapshot -i        Interactive elements only — terse flat list (minimal tokens)
-browse snapshot -i -v     Interactive elements — verbose indented tree with props
+browse snapshot -i -f     Interactive elements — full indented tree with props
+browse snapshot -i -V     Interactive elements — viewport only (skip below-fold)
 browse snapshot -c        Compact (no empty structural elements)
 browse snapshot -C        Cursor-interactive (detect divs with cursor:pointer/onclick/tabindex)
 browse snapshot -d <N>    Limit depth to N levels

package/src/cli.ts

@@ -612,7 +612,7 @@ Inspection:     js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
                 cookies | storage [set <k> <v>] | perf
                 value <sel> | count <sel> | clipboard [write <text>]
 Visual:         screenshot [path] | pdf [path] | responsive [prefix]
-Snapshot:       snapshot [-i] [-v] [-c] [-C] [-d N] [-s sel]
+Snapshot:       snapshot [-i] [-f] [-V] [-c] [-C] [-d N] [-s sel]
 Find:           find role|text|label|placeholder|testid <query> [name]
 Compare:        diff <url1> <url2> | screenshot-diff <baseline> [current]
 Multi-step:     chain (reads JSON from stdin)
@@ -639,7 +639,8 @@ Options:
 
 Snapshot flags:
   -i            Interactive elements only (terse flat list by default)
-  -v            Verbose — full indented tree with props (use with -i)
+  -f            Full — indented tree with props and children (use with -i)
+  -V            Viewport — only elements visible in current viewport
   -c            Compact — remove empty structural elements
   -C            Cursor-interactive — detect divs with cursor:pointer,
                 onclick, tabindex, data-action (missed by ARIA tree)

package/src/snapshot.ts

@@ -31,8 +31,9 @@ const INTERACTIVE_ROLES = new Set([
 
 interface SnapshotOptions {
   interactive?: boolean;  // -i: only interactive elements (terse flat list by default)
-  verbose?: boolean;      // -v: full indented ARIA tree with props/children (overrides -i terse default)
+  full?: boolean;         // -f: full indented ARIA tree with props/children (overrides -i terse default)
   compact?: boolean;      // -c: remove empty structural elements
+  viewport?: boolean;     // -V: only elements visible in current viewport
   depth?: number;         // -d N: limit tree depth
   selector?: string;      // -s SEL: scope to CSS selector
   cursor?: boolean;       // -C: detect cursor-interactive elements (divs with cursor:pointer, onclick, tabindex)
@@ -73,9 +74,13 @@ export function parseSnapshotArgs(args: string[]): SnapshotOptions {
       case '--compact':
         opts.compact = true;
         break;
-      case '-v':
-      case '--verbose':
-        opts.verbose = true;
+      case '-f':
+      case '--full':
+        opts.full = true;
+        break;
+      case '-V':
+      case '--viewport':
+        opts.viewport = true;
         break;
       case '-C':
       case '--cursor':
@@ -422,8 +427,8 @@ export async function handleSnapshot(
     refMap.set(ref, locator);
 
     // Format output line
-    // -i without -v: terse flat list (no indent, no props, no children)
-    const terse = opts.interactive && !opts.verbose;
+    // -i without -f: terse flat list (no indent, no props, no children)
+    const terse = opts.interactive && !opts.full;
     let outputLine: string;
     if (terse) {
       outputLine = `@${ref} [${node.role}]`;
@@ -441,6 +446,89 @@ export async function handleSnapshot(
     output.push(outputLine);
   }
 
+  // Viewport filter: remove elements outside the visible viewport
+  // Uses a single page.evaluate() for speed — checking 189 locators individually is slow
+  if (opts.viewport) {
+    const vp = page.viewportSize();
+    if (vp) {
+      // Build a list of {ref, role, name} to check in the DOM
+      const checks = Array.from(refMap.keys()).map(ref => {
+        const line = output.find(l => l.includes(`@${ref} `));
+        const roleMatch = line?.match(/\[(\w+)\]/);
+        const nameMatch = line?.match(/"([^"]*)"/);
+        return { ref, role: roleMatch?.[1] || '', name: nameMatch?.[1] || '' };
+      });
+
+      const visibleRefs = await evalCtx.evaluate(
+        ({ checks, vpHeight }) => {
+          const ROLE_TO_SELECTOR: Record<string, string> = {
+            link: 'a,[role="link"]',
+            button: 'button,[role="button"],input[type="button"],input[type="submit"]',
+            textbox: 'input:not([type="checkbox"]):not([type="radio"]):not([type="submit"]):not([type="button"]):not([type="hidden"]),textarea,[role="textbox"]',
+            checkbox: 'input[type="checkbox"],[role="checkbox"]',
+            radio: 'input[type="radio"],[role="radio"]',
+            combobox: 'select,[role="combobox"]',
+            searchbox: 'input[type="search"],[role="searchbox"]',
+            tab: '[role="tab"]',
+            switch: '[role="switch"]',
+            slider: 'input[type="range"],[role="slider"]',
+            menuitem: '[role="menuitem"]',
+            option: 'option,[role="option"]',
+          };
+
+          const visible = new Set<string>();
+          // Track which elements we've already matched per role+name
+          const roleCounts = new Map<string, number>();
+
+          for (const { ref, role, name } of checks) {
+            const selector = ROLE_TO_SELECTOR[role] || `[role="${role}"]`;
+            const all = document.querySelectorAll(selector);
+            const key = `${role}:${name}`;
+            const skip = roleCounts.get(key) || 0;
+
+            let matched = 0;
+            for (let i = 0; i < all.length; i++) {
+              const el = all[i] as HTMLElement;
+              // Match by accessible name (textContent or aria-label)
+              const accName = (el.getAttribute('aria-label') || el.textContent || '').trim();
+              // For terse mode, name may be truncated — check startsWith
+              const nameMatches = !name || accName === name ||
+                (name.endsWith('...') && accName.startsWith(name.slice(0, -3)));
+              if (!nameMatches) continue;
+
+              if (matched < skip) { matched++; continue; }
+
+              const rect = el.getBoundingClientRect();
+              if (rect.y + rect.height > 0 && rect.y < vpHeight) {
+                visible.add(ref);
+              }
+              matched++;
+              break;
+            }
+            roleCounts.set(key, skip + 1);
+          }
+          return [...visible];
+        },
+        { checks, vpHeight: vp.height }
+      );
+
+      const visibleSet = new Set(visibleRefs);
+      const toRemove = new Set<string>();
+      for (const ref of refMap.keys()) {
+        if (!visibleSet.has(ref)) toRemove.add(ref);
+      }
+      for (const ref of toRemove) {
+        refMap.delete(ref);
+      }
+      for (let i = output.length - 1; i >= 0; i--) {
+        const match = output[i].match(/@(e\d+)/);
+        if (match && toRemove.has(match[1])) {
+          output.splice(i, 1);
+        }
+      }
+    }
+  }
+
   // Cursor-interactive detection: supplement ARIA tree with DOM-level scan
   if (opts.cursor) {
     const result = await appendCursorElements(evalCtx, locatorRoot, opts, output, refMap, refCounter, bm);