@zumer/snapdom-plugins 1.2.0 → 2.2.0

package/README.md

@@ -170,88 +170,154 @@ snapdom(el, { plugins: [htmlInCanvas()] });
 
 ---
 
-### `prompt-export`
+### `agent-map`
 
-Adds a `toPrompt()` export method that returns an LLM-ready package: a structured element map with bounding boxes, a pre-formatted prompt text, and (optionally) an annotated screenshot. Tuned for vision-language models, browser-agent pipelines, visual QA, and any workflow that pairs a capture with structured metadata.
+Produces a Set-of-Mark package for **visual agents**: an annotated screenshot with numbered badges on interactive elements, plus a compact JSON map from badge index → role / accessible name / bbox / state. One call, fully client-side.
 
 ```js
-import { promptExport } from '@zumer/snapdom-plugins/prompt-export';
+import { agentMap } from '@zumer/snapdom-plugins/agent-map';
 
-const result = await snapdom(el, { plugins: [promptExport()] });
-// Default: no image, just the structured map + prompt text (cheapest)
-const { elements, prompt, dimensions } = await result.toPrompt();
+const result = await snapdom(el, { plugins: [agentMap()] });
+const { image, map, dimensions } = await result.toAgentMap();
+
+// image: data URL of the screenshot with numbered red badges overlaid
+// map:   [{ i, n, r, b, s? }, …] — index, name, role, bbox, state
+// Agent says "click element 2" → map[2].b gives [x, y, w, h]
 ```
 
-To also include the annotated image (for tasks that truly depend on vision):
+Map entry shape (default `fields: 'minimal'`):
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `i` | `number` | Index matching the badge drawn on the image |
+| `n` | `string` | Accessible name (aria-label → labelledby → alt → title → labels → textContent, truncated to 60 chars) |
+| `r` | `string` | ARIA-style role (`button`, `link`, `checkbox`, `radio`, `textbox`, `combobox`, `slider`, `heading`, …) — derived from `role` attribute or implicit role of the element |
+| `b` | `[x, y, w, h]` | Bounding box in pixels, scaled against `maxImageWidth` |
+| `s` | `object?` | State: included only when at least one key is meaningful — `checked`, `disabled`, `focus`, `expanded`, `pressed`, `selected`, `value`, `open`, `selectedText`, `covered` |
+
+Example map for a checkout form:
 
 ```js
-const result = await snapdom(el, {
-  plugins: [promptExport({ include: ['image', 'elements', 'prompt'] })]
-});
-const { image, elements, prompt, dimensions } = await result.toPrompt();
+[
+  { i: 0, n: 'Email',         r: 'textbox',  b: [28,  80, 280, 34], s: { value: 'ada@example.com' } },
+  { i: 1, n: 'Send product updates', r: 'checkbox', b: [28, 134,  13, 13], s: { checked: true } },
+  { i: 2, n: 'Apply coupon',  r: 'button',   b: [28, 176, 114, 38], s: { expanded: false } },
+  { i: 3, n: 'Remove coupon', r: 'button',   b: [150, 176, 140, 38], s: { disabled: true } },
+  { i: 4, n: 'Pay $53.90',    r: 'button',   b: [28, 220,  97, 38] }
+]
 ```
 
-The returned object (fields present only if requested via `include`):
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `image` | `'annotated' \| 'raw' \| false` | `'annotated'` | `'annotated'` overlays numbered badges; `'raw'` skips badges; `false` skips image generation entirely (no canvas draw, no toDataURL — cheapest path). |
+| `fields` | `'minimal' \| 'full'` | `'minimal'` | `'full'` adds `t` (raw text content) and `a` (meaningful attributes) per entry. |
+| `semantic` | `boolean` | `false` | Include non-interactive structural elements (headings, paragraphs, landmarks). Off by default — agents act on interactive. |
+| `maxImageWidth` | `number` | `1024` | Downscale target for the image; bboxes rescale to match. |
+| `imageFormat` | `'png' \| 'jpg' \| 'webp'` | `'png'` | Image format (only used when image is rendered). |
+| `imageQuality` | `number` | `0.8` | Quality for lossy formats. |
+| `interactiveSelector` | `string` | see below | CSS selector for interactive elements. |
+| `semanticSelector` | `string` | see below | CSS selector for semantic elements (used when `semantic: true`). |
+| `labelStyle` | `object` | `{}` | Override badge styles. |
+
+Defaults:
+- **interactive**: `a[href], button, input, select, textarea, [role="button"|"link"|"tab"|"menuitem"|"checkbox"|"radio"|"switch"|"slider"|"combobox"|"textbox"], [tabindex]:not([tabindex="-1"]), summary, [contenteditable="true"]`
+- **semantic**: `h1–h6, nav, main, article, section, header, footer, figcaption, blockquote, legend, p`
+
+Per-call options override constructor options (e.g. `result.toAgentMap({ image: false })`).
+
+#### When to use
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `elements` | `Array` | One entry per detected element: `{ id, tag, type, name, text, bbox, attributes, state?, styles?, covered? }` |
-| `prompt` | `string` | Pre-formatted text describing interactive + semantic elements |
-| `image` | `string` | Data URL of the (optionally annotated) screenshot — **only when `include` contains `'image'`** |
-| `dimensions` | `{width, height}` | Scaled dimensions (always present) |
+- Visual agents using Set-of-Mark prompting — one call gives you both the labelled image and the coordinate lookup table.
+- Computer-use / browser-agent harnesses that need click coordinates for a vision model's output.
+- Visual QA with an LLM judge — compare before/after captures with structured element identity.
+- Dataset generation for vision-LLM fine-tuning — (image, map) pairs.
 
-`elements` is split into two `type`s:
-- `'interactive'` — buttons, links, inputs, `[role]`/`[tabindex]` targets. These get numbered badges overlaid on the screenshot when `annotate` is on.
-- `'semantic'` — headings, paragraphs, `<nav>`, `<main>`, images with `alt`, table cells, etc. Structural context, not overlaid.
+Because it runs entirely in the browser, it works in contexts where Playwright / Puppeteer can't: Chrome extensions, SaaS web apps capturing the user's own page, Electron apps capturing their own window.
 
-Each `bbox` is in pixel coordinates of the returned image (scaled against `maxImageWidth`).
+---
 
-Each interactive entry also carries:
-- `name` — the computed accessible name (aria-label → labelledby → alt → title → labels[0] → textContent)
-- `state` — runtime state: `{ checked, disabled, focus, open, value, selectedText }` (only keys that apply)
-- `styles` — visually-meaningful computed props filtered to drop defaults
-- `covered: true` when another element is painted on top of the bbox center (an agent won't click through a modal)
+### `html-export`
+
+Adds a `toHtml()` export that returns the capture as a self-contained, **re-renderable HTML document** (clone + inlined styles/fonts) instead of pixels. It unwraps the SVG `<foreignObject>` SnapDOM already produced, so the markup and CSS match the capture byte-for-byte — nothing is rasterized.
 
 ```js
-// Example — feed a vision-capable LLM
-const { image, elements } = await result.toPrompt({
-  include: ['image', 'elements', 'prompt']
-});
+import { htmlExport } from '@zumer/snapdom-plugins/html-export';
 
-// image is a data URL → pass as image input
-// elements is JSON → pass as structured context alongside the image
-// "Click element [3]" → look up elements[3].bbox for real coordinates
+const result = await snapdom(el, { plugins: [htmlExport()] });
+const html = await result.toHtml();              // full <!DOCTYPE html> string
+
+// Or download a .html file:
+await result.toHtml({ download: 'snapshot.html' });
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `include` | `string[]` | `['elements', 'prompt']` | Fields to return. Add `'image'` for tasks that need vision (chart content, layout QA, canvas). Use `['prompt']` for the cheapest text-only mode. |
-| `annotate` | `boolean` | `true` | Overlay numbered badges on interactive elements (only affects the image when included) |
-| `promptMode` | `'compact' \| 'verbose'` | `'compact'` | Prompt text verbosity. Compact omits coords when badges are on the image. |
-| `includeCoords` | `boolean` | `true` | Include bbox in the prompt text |
-| `imageFormat` | `'png' \| 'jpg' \| 'webp'` | `'png'` | Output image format (only used when `image` is included) |
-| `imageQuality` | `number` | `0.8` | Quality for lossy formats (0–1) |
-| `maxImageWidth` | `number` | `1024` | Max width in px; downscales and rescales bboxes if larger |
-| `interactiveSelector` | `string` | see below | CSS selector for the interactive element set |
-| `semanticSelector` | `string` | see below | CSS selector for the semantic element set |
-| `labelStyle` | `object` | `{}` | Override styles for the numbered badges (`position`, `color`, `backgroundColor`, etc.) |
+| `fullDocument` | `boolean` | `true` | Wrap output in `<!DOCTYPE html>…`; if `false`, return just `<style>` + the fragment |
+| `filename` | `string` | `'capture.html'` | Download filename when `opts.download` is `true` |
 
-Defaults:
-- **interactive**: `a[href], button, input, select, textarea, [role="button"|"link"|"tab"|"menuitem"|"checkbox"|"radio"], [tabindex]:not([tabindex="-1"]), summary, [contenteditable="true"]`
-- **semantic**: `h1–h6, p, li, img[alt], nav, main, article, section, header, footer, label, td, th, figcaption, blockquote, legend`
+Per-call `opts`: `download` (`boolean \| string` — `true` triggers download, a string sets the filename), plus `fullDocument` / `filename` overrides. Returns the HTML `string`.
+
+---
 
-Both per-call options (`opts.include`, `opts.imageFormat`, etc.) and constructor options are supported; per-call wins.
+### `gif-export`
 
-The image is the most expensive part of `toPrompt()` to produce (canvas draw + data-URL serialization), so the default skips it. Add `'image'` to `include` when the task actually uses vision:
+Adds a `toGif()` export that records an **animated GIF** by re-capturing the live element over time and encoding the frames. The GIF89a encoder (median-cut quantization + LZW) is built in — no dependencies. Returns a `Blob` (`image/gif`).
 
 ```js
-// Vision-dependent task (chart content, layout QA, visual diff)
-await result.toPrompt({ include: ['image', 'elements', 'prompt'] });
+import { gifExport } from '@zumer/snapdom-plugins/gif-export';
 
-// Pure structured agent loop (cheapest)
-await result.toPrompt({ include: ['prompt'] });
+const result = await snapdom(el, { plugins: [gifExport({ fps: 12, duration: 3000 })] });
+const blob = await result.toGif();
+
+// Or download directly:
+await result.toGif({ download: 'animation.gif' });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fps` | `number` | `10` | Frames per second |
+| `duration` | `number` | `2000` | Total duration in ms (ignored if `frames` is set) |
+| `frames` | `number` | — | Explicit frame count (overrides `duration`) |
+| `maxColors` | `number` | `256` | Palette size per frame (2–256) |
+| `background` | `string` | `'#ffffff'` | Color composited under transparent pixels |
+| `scale` | `number` | `1` | Capture scale |
+| `repeat` | `number` | `0` | Loop count (`0` = forever, `-1` = play once) |
+| `filename` | `string` | `'capture.gif'` | Download filename |
+
+Per-call `opts` override any constructor option, plus `download` (`boolean \| string`). Each frame is captured live, so CSS animations / dynamic content are recorded as they play.
+
+---
+
+### `video-export`
+
+Adds a `toMp4()` export that records a **video** by re-capturing the live element over time and encoding the frames with the native `MediaRecorder`. Returns a `Blob` whose type reflects what was actually produced.
+
+```js
+import { videoExport } from '@zumer/snapdom-plugins/video-export';
+
+const result = await snapdom(el, { plugins: [videoExport({ fps: 30, duration: 4000 })] });
+const blob = await result.toMp4();
+
+// Or download directly:
+await result.toMp4({ download: true });
 ```
 
+> **Codec reality:** `MediaRecorder` output depends on the browser. Safari produces MP4 (H.264); Chromium typically produces WebM (VP8/VP9). When MP4 isn't supported the plugin falls back to WebM, warns in the console, and the downloaded file extension is set to `.mp4` / `.webm` accordingly.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fps` | `number` | `10` | Frames per second |
+| `duration` | `number` | `2000` | Total duration in ms (ignored if `frames` is set) |
+| `frames` | `number` | — | Explicit frame count (overrides `duration`) |
+| `background` | `string` | `'#ffffff'` | Color composited under transparent pixels |
+| `scale` | `number` | `1` | Capture scale |
+| `bitrate` | `number` | — | `videoBitsPerSecond` passed to `MediaRecorder` |
+| `filename` | `string` | — | Download filename (extension auto-set to `.mp4` / `.webm`) |
+
+Requires `MediaRecorder` (unavailable in some headless environments). Per-call `opts` override any constructor option, plus `download` (`boolean \| string`).
+
 ---
 
 ## Plugin registration

package/agent-map.js

@@ -0,0 +1,376 @@
+/**
+ * agentMap – Official SnapDOM Plugin
+ *
+ * Produces a Set-of-Mark package for visual agents: an annotated screenshot
+ * with numbered badges on interactive elements, plus a compact JSON map from
+ * badge index → role / name / bbox / state. Designed for one-call capture
+ * on the client side — visual agents, computer-use harnesses, dataset
+ * generation for vision training, visual QA.
+ *
+ * Usage:
+ *   import { agentMap } from '@zumer/snapdom-plugins/agent-map';
+ *   const result = await snapdom(el, { plugins: [agentMap()] });
+ *   const { image, map, dimensions } = await result.toAgentMap();
+ *
+ *   // model reply: "click element 2" → map[2].b gives [x, y, w, h]
+ *
+ * @param {Object} [options]
+ * @param {'annotated'|'raw'|false} [options.image='annotated']  Image output
+ *   mode. 'annotated' draws numbered badges on the rendered image, 'raw'
+ *   returns the image without badges, false skips image generation (cheapest).
+ * @param {'minimal'|'full'} [options.fields='minimal']  Per-entry shape.
+ *   'minimal' returns {i, n, r, b, s?}. 'full' adds {t (text), a (attrs)}.
+ * @param {boolean} [options.semantic=false]  Include non-interactive semantic
+ *   elements (headings, paragraphs, nav, main, landmarks). Off by default —
+ *   agents typically only act on interactive.
+ * @param {number}  [options.maxImageWidth=1024]  Downscale target for the image.
+ * @param {'png'|'jpg'|'webp'} [options.imageFormat='png']  Image format.
+ * @param {number}  [options.imageQuality=0.8]  Quality for lossy formats.
+ * @param {string}  [options.interactiveSelector]  CSS selector (default below).
+ * @param {string}  [options.semanticSelector]  CSS selector (default below).
+ * @param {Object}  [options.labelStyle={}]  Override badge styles.
+ * @returns {Object} SnapDOM plugin
+ */
+
+const DEFAULT_INTERACTIVE =
+  'a[href], button, input, select, textarea, ' +
+  '[role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [role="slider"], [role="combobox"], [role="textbox"], ' +
+  '[tabindex]:not([tabindex="-1"]), summary, [contenteditable="true"]';
+
+const DEFAULT_SEMANTIC =
+  'h1, h2, h3, h4, h5, h6, nav, main, article, section, header, footer, ' +
+  'figcaption, blockquote, legend, p';
+
+export function agentMap(options = {}) {
+  const {
+    image = 'annotated',
+    fields = 'minimal',
+    semantic = false,
+    maxImageWidth = 1024,
+    imageFormat = 'png',
+    imageQuality = 0.8,
+    interactiveSelector = DEFAULT_INTERACTIVE,
+    semanticSelector = DEFAULT_SEMANTIC,
+    labelStyle = {},
+  } = options;
+
+  return {
+    name: 'agent-map',
+
+    afterClone(ctx) {
+      const meta = extractMap(
+        ctx.element,
+        interactiveSelector,
+        semantic ? semanticSelector : null,
+        fields
+      );
+      // snapdom's export ctx is a fresh spread of ctx.options, so we stash on
+      // both for the agentMap() call below to find it.
+      ctx.__agentMapMeta = meta;
+      if (ctx.options) ctx.options.__agentMapMeta = meta;
+
+      if (image === 'annotated') {
+        addAnnotations(ctx.clone, meta.map, labelStyle);
+      }
+    },
+
+    defineExports() {
+      return {
+        agentMap: async (ctx, opts = {}) => {
+          const meta = ctx.__agentMapMeta;
+          const wantImage = opts.image !== undefined ? opts.image : image;
+
+          if (!meta || !meta.map.length) {
+            const out = { dimensions: { width: 0, height: 0 }, map: [] };
+            if (wantImage) out.image = ctx.export.url;
+            return out;
+          }
+
+          const format = opts.imageFormat || imageFormat;
+          const quality = opts.imageQuality || imageQuality;
+          const maxWidth = opts.maxImageWidth || maxImageWidth;
+
+          // Scale dimensions — whether we rasterize or not, bboxes get resized
+          // to the target output size so callers can overlay them on the image.
+          let w, h, dataURL;
+          if (wantImage) {
+            const img = new Image();
+            img.src = ctx.export.url;
+            await new Promise((res, rej) => { img.onload = res; img.onerror = rej; });
+            const ratio = img.naturalWidth > maxWidth ? maxWidth / img.naturalWidth : 1;
+            w = Math.round(img.naturalWidth * ratio);
+            h = Math.round(img.naturalHeight * ratio);
+            const canvas = document.createElement('canvas');
+            canvas.width = w;
+            canvas.height = h;
+            canvas.getContext('2d').drawImage(img, 0, 0, w, h);
+            const mime =
+              format === 'jpg' || format === 'jpeg' ? 'image/jpeg'
+              : format === 'webp' ? 'image/webp'
+              : 'image/png';
+            dataURL = canvas.toDataURL(mime, quality);
+          } else {
+            const sourceW = meta.dimensions.width || 1;
+            const ratio = sourceW > maxWidth ? maxWidth / sourceW : 1;
+            w = Math.round(sourceW * ratio);
+            h = Math.round(meta.dimensions.height * ratio);
+          }
+
+          const sx = w / (meta.dimensions.width || 1);
+          const sy = h / (meta.dimensions.height || 1);
+
+          const scaledMap = meta.map.map(e => {
+            const scaled = { ...e, b: [
+              Math.round(e.b[0] * sx),
+              Math.round(e.b[1] * sy),
+              Math.round(e.b[2] * sx),
+              Math.round(e.b[3] * sy),
+            ] };
+            return scaled;
+          });
+
+          const out = { dimensions: { width: w, height: h }, map: scaledMap };
+          if (wantImage) out.image = dataURL;
+          return out;
+        },
+      };
+    },
+  };
+}
+
+/* ── Role derivation ────────────────────────────── */
+
+function deriveRole(el) {
+  const explicit = el.getAttribute('role');
+  if (explicit) return explicit;
+  const tag = el.tagName.toLowerCase();
+  const type = (el.type || '').toLowerCase();
+  if (tag === 'button') return 'button';
+  if (tag === 'a' && el.hasAttribute('href')) return 'link';
+  if (tag === 'input') {
+    if (type === 'checkbox') return 'checkbox';
+    if (type === 'radio') return 'radio';
+    if (type === 'range') return 'slider';
+    if (type === 'file') return 'file';
+    if (type === 'submit' || type === 'button' || type === 'reset' || type === 'image') return 'button';
+    return 'textbox';
+  }
+  if (tag === 'select') return 'combobox';
+  if (tag === 'textarea') return 'textbox';
+  if (tag === 'summary') return 'button';
+  if (tag === 'details') return 'group';
+  if (/^h[1-6]$/.test(tag)) return 'heading';
+  if (tag === 'nav') return 'navigation';
+  if (tag === 'main') return 'main';
+  if (tag === 'header') return 'banner';
+  if (tag === 'footer') return 'contentinfo';
+  if (tag === 'article') return 'article';
+  if (tag === 'section') return 'region';
+  if (tag === 'p') return 'paragraph';
+  if (tag === 'img') return 'image';
+  return tag;
+}
+
+/* ── Accessible name ────────────────────────────── */
+
+function accessibleName(el) {
+  const ariaLabel = el.getAttribute('aria-label');
+  if (ariaLabel && ariaLabel.trim()) return ariaLabel.trim();
+
+  const labelledBy = el.getAttribute('aria-labelledby');
+  if (labelledBy) {
+    const root = el.getRootNode();
+    const getById = (id) =>
+      root && typeof root.getElementById === 'function'
+        ? root.getElementById(id) : document.getElementById(id);
+    const parts = labelledBy.trim().split(/\s+/)
+      .map(id => { const r = getById(id); return r ? (r.textContent || '').trim() : ''; })
+      .filter(Boolean);
+    if (parts.length) return parts.join(' ');
+  }
+
+  if (el.tagName === 'IMG' || (el.tagName === 'INPUT' && (el.type || '').toLowerCase() === 'image')) {
+    const alt = el.getAttribute('alt');
+    if (alt && alt.trim()) return alt.trim();
+  }
+
+  const title = el.getAttribute('title');
+  if (title && title.trim()) return title.trim();
+
+  if (el.labels && el.labels[0]) {
+    const t = (el.labels[0].textContent || '').trim();
+    if (t) return t;
+  }
+
+  const text = (el.textContent || '').replace(/\s+/g, ' ').trim();
+  if (text) return text.length > 60 ? text.slice(0, 59) + '…' : text;
+  return '';
+}
+
+/* ── State extraction ───────────────────────────── */
+
+/**
+ * Builds the `s` (state) object. Only meaningful states — never default
+ * values that add no signal for an agent. Critically, aria-expanded and
+ * aria-pressed are included for BOTH values (true and false) because
+ * "pressed: false" on a toggle is meaningful information.
+ */
+function deriveState(el, role, rect) {
+  const s = {};
+
+  try {
+    if (el.matches(':checked')) s.checked = true;
+    else if (role === 'checkbox' || role === 'radio') {
+      // include checked:false for form groups where an agent needs to
+      // know "unchecked" is a valid state distinct from "not a checkbox".
+      s.checked = false;
+    }
+    if (el.matches(':disabled')) s.disabled = true;
+    if (el.matches(':focus')) s.focus = true;
+  } catch { /* exotic nodes */ }
+
+  const expanded = el.getAttribute('aria-expanded');
+  if (expanded === 'true') s.expanded = true;
+  else if (expanded === 'false') s.expanded = false;
+
+  const pressed = el.getAttribute('aria-pressed');
+  if (pressed === 'true') s.pressed = true;
+  else if (pressed === 'false') s.pressed = false;
+
+  const selected = el.getAttribute('aria-selected');
+  if (selected === 'true') s.selected = true;
+  else if (selected === 'false' && (role === 'tab' || role === 'option')) s.selected = false;
+
+  if (el.tagName === 'INPUT') {
+    const type = (el.type || 'text').toLowerCase();
+    if (type !== 'checkbox' && type !== 'radio' && type !== 'submit' && type !== 'button' && type !== 'reset' && el.value) {
+      s.value = el.value;
+    }
+  } else if (el.tagName === 'TEXTAREA') {
+    if (el.value) s.value = el.value;
+  } else if (el.tagName === 'SELECT') {
+    s.value = el.value;
+    const opt = el.options && el.options[el.selectedIndex];
+    if (opt) s.selectedText = opt.text || '';
+  } else if (el.tagName === 'DETAILS') {
+    s.open = !!el.open;
+  }
+
+  // Covered — element visually occluded by something else at its center.
+  if (rect && rect.width && rect.height) {
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    if (cx >= 0 && cy >= 0) {
+      const doc = el.ownerDocument || document;
+      if (doc.elementFromPoint) {
+        const top = doc.elementFromPoint(cx, cy);
+        if (top && top !== el && !(el.contains && el.contains(top))) {
+          s.covered = true;
+        }
+      }
+    }
+  }
+
+  return Object.keys(s).length ? s : null;
+}
+
+/* ── Map extraction ─────────────────────────────── */
+
+function extractMap(element, interactiveSelector, semanticSelector, fields) {
+  const rootRect = element.getBoundingClientRect();
+  const map = [];
+  let i = 0;
+  const tracked = new Set();
+
+  for (const el of element.querySelectorAll(interactiveSelector)) {
+    const entry = buildEntry(el, rootRect, i, fields, 'interactive');
+    if (entry) { map.push(entry); tracked.add(el); i++; }
+  }
+
+  if (semanticSelector) {
+    for (const el of element.querySelectorAll(semanticSelector)) {
+      if (tracked.has(el)) continue;
+      const entry = buildEntry(el, rootRect, i, fields, 'semantic');
+      if (entry) { map.push(entry); i++; }
+    }
+  }
+
+  return {
+    map,
+    dimensions: { width: rootRect.width, height: rootRect.height },
+  };
+}
+
+function buildEntry(el, rootRect, i, fields, kind) {
+  const rect = el.getBoundingClientRect();
+  const b = [
+    Math.round(rect.left - rootRect.left),
+    Math.round(rect.top - rootRect.top),
+    Math.round(rect.width),
+    Math.round(rect.height),
+  ];
+  if (b[2] <= 0 && b[3] <= 0) return null;
+
+  const role = deriveRole(el);
+  const n = accessibleName(el);
+
+  const entry = { i, n, r: role, b };
+
+  if (kind === 'interactive') {
+    const s = deriveState(el, role, rect);
+    if (s) entry.s = s;
+  }
+
+  if (fields === 'full') {
+    const t = (el.textContent || '').replace(/\s+/g, ' ').trim();
+    if (t && t !== n) entry.t = t.length > 160 ? t.slice(0, 159) + '…' : t;
+    const a = {};
+    for (const name of ['href', 'type', 'name', 'placeholder', 'alt', 'title', 'role', 'aria-label']) {
+      const v = el.getAttribute(name);
+      if (v && v !== 'false') a[name] = v;
+    }
+    if (Object.keys(a).length) entry.a = a;
+  }
+
+  return entry;
+}
+
+/* ── Annotations ────────────────────────────────── */
+
+function addAnnotations(clone, entries, customStyle) {
+  const interactive = entries.filter(e => !e.isSemanticOnly);
+  if (!interactive.length) return;
+
+  const overlay = document.createElement('div');
+  overlay.setAttribute('data-snap-agent-overlay', 'true');
+  Object.assign(overlay.style, {
+    position: 'absolute',
+    top: '0', left: '0', width: '100%', height: '100%',
+    pointerEvents: 'none',
+    zIndex: '2147483647',
+    overflow: 'visible',
+  });
+
+  for (const e of interactive) {
+    const badge = document.createElement('span');
+    badge.textContent = String(e.i);
+    const cx = e.b[0] + e.b[2] / 2;
+    const cy = e.b[1] + e.b[3] / 2;
+    Object.assign(badge.style, {
+      position: 'absolute',
+      left: cx + 'px', top: cy + 'px',
+      transform: 'translate(-50%, -50%)',
+      minWidth: '18px', height: '18px',
+      lineHeight: '18px', fontSize: '11px', fontWeight: '700',
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      color: '#fff', backgroundColor: 'rgba(220, 38, 38, 0.92)',
+      borderRadius: '9px', textAlign: 'center', padding: '0 4px',
+      boxSizing: 'border-box', boxShadow: '0 1px 3px rgba(0,0,0,0.3)',
+      ...customStyle,
+    });
+    overlay.appendChild(badge);
+  }
+
+  clone.style.position = 'relative';
+  clone.appendChild(overlay);
+}