@plannotator/ui 0.38.2 → 0.39.0

package/HANDOFF.md

@@ -678,8 +678,9 @@ Additive only, but required: `@plannotator/ui` 0.32.0 imports the new `@plannota
 
 ## Publishing & versioning
 
-- The current pair is `@plannotator/ui` `0.38.2` on `@plannotator/core` `0.25.2`. UI 0.38.2 keeps the type word in a titled alert's accessible name through a visually hidden `sr-only` span before the title instead of an `aria-label` on the title row (naming a generic `div` is prohibited by ARIA and WebKit drops it, so VoiceOver on Safari read only the bold title in 0.38.1), and loosens the React peer back to `^19.2.3` (0.38.1 declared `^19.2.8` only because the dependency batch moved it; nothing in the package needs a newer API). **Do not consume ui 0.38.0**: it imports `@plannotator/core/token-hover` (the hover-card trigger settings, #1462) but pins core 0.25.1, which never exported that subpath, so it fails to compile in any consumer; 0.38.1 is the same UI pinning core 0.25.2, which publishes `./token-hover`, the rotated `guide-viewer-manifest` pin, and the `config-types` hover fields (core 0.25.2 is the first core publish since 0.25.1 even though those changes landed over several releases; the package smoke now diffs the UI's core imports against the registry so an unpublished core subpath fails preflight instead of the consumer). UI 0.38.1 also aligns `@codemirror/state` to `^6.7.2` beside `@codemirror/view ^6.43.10`, so a consumer can no longer resolve two state copies. UI 0.38.0 also renders a GitHub alert's bold-only first body line as its title on the icon row (an emoji on that line becomes the icon; `<!-- icon: name -->` is stripped and resolved through the new `alertIconRenderer` seam, null by default; grammar in `utils/alertTitle`, importable by a host editor so it writes the bytes the reader parses; a fenced code block inside an alert body still renders as text, deferred because nesting a `CodeBlock` inside a block interacts with the positional annotation anchors and needs its own design). UI 0.38.0 carries the whole unified decision-control stack: the internal primitives (`DecisionControl`, `utils/decisionSpec`, `hooks/useDismissablePopover` — not host-supported surface, see the unsupported list; `useDismissablePopover` also replaced the hand-rolled dismissal inside `ActionMenu`/`ApproveDropdown`, both likewise unsupported) plus one blessed-barrel addition: `decisionControlShortcuts` on `@plannotator/ui/shortcuts` (pure scope data, fetch-free, same contract as the other scopes). The removal of `ToolbarButtons`' platform-mode `muted` prop is internal — `ToolbarButtons` is not host-supported surface. UI 0.37.0 added the Viewer-owned document-header seam (a new public API, hence the minor bump; 0.36.1 was reserved for it but never published) while retaining the `hideQuickLabel` and `StickyHeaderLane` seams from the 0.35.x and 0.36.0 releases; core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`, and UI pins that corrected core exactly.
-- Recent pairs, for the consumer's install matrix: ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2, ui 0.36.0, and ui 0.37.0 on core 0.25.1 (0.36.1 was never published), and ui 0.38.1 and ui 0.38.2 on core 0.25.2. Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export. Do not consume ui 0.38.0 because its exact core 0.25.1 dependency lacks the `token-hover` export.
+- The current pair is `@plannotator/ui` `0.39.0` on `@plannotator/core` `0.25.2` (core unchanged; nothing under `packages/core` moved). UI 0.39.0 adds **element context** to raw-HTML and live-app pinpoint annotations (#1517, #1520): a new optional `Annotation.elementContext` (`HtmlElementContext` in `@plannotator/ui/types`) and `HtmlAnnotationTarget.context`, captured by the bridge at click time (tag, id, author classes, ancestor `path`, `role`, accessible `name`, an allowlisted `attrs` set with href/src scrubbed of query and fragment, rendered `text`, an adaptive collapsed HTML `outline`, child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint, and in live-app sessions `page`), hard-capped at 2 KiB serialized per primary and 1 KiB per extra target, and re-validated at the parent trust boundary by the new `parseHtmlElementContext` export of `@plannotator/ui/components/html-viewer`. New helpers on `@plannotator/ui/utils/parser`: `elementContextExportBlock(ann, { includeRoute })` (the fenced skeleton plus selector/path/role/name/attrs/text/box/near lines the full export now prints under a context-bearing comment) and `exportAnnotationEntry(ann, { includeRoute })` (one annotation as a standalone feedback entry, a pure helper for hosts; `AnnotationPanel`'s card chrome is unchanged from 0.38.2). The field is purely descriptive: `HtmlElementAnchor` and restore are untouched, no `BRIDGE_PROTOCOL_VERSION` bump, share links drop it like anchors, annotations without it export byte-identically, and the repaint path posts only anchors to the bridge. **Host persistence gap, tracked as #1521**: `@plannotator/core/html-anchor` (`buildPersistedHtmlAnchor`, `projectHostThreads`) does not carry `elementContext` yet, so a host persisting through those helpers drops it on save; until #1521 lands, hosts that want it must persist and project the field themselves. Peer ranges are unchanged from 0.38.2: `react` / `react-dom` `^19.2.3`, `tailwindcss` as before, and `@codemirror/state ^6.7.2` beside `@codemirror/view ^6.43.10`. Decision-control change in the same window (#1516): the header primary reads `Send Feedback` / `Post Comments` with no inline count (`DecisionPrimary.count` removed; internal, not host-supported surface).
+- The previous pair was `@plannotator/ui` `0.38.2` on `@plannotator/core` `0.25.2`. UI 0.38.2 keeps the type word in a titled alert's accessible name through a visually hidden `sr-only` span before the title instead of an `aria-label` on the title row (naming a generic `div` is prohibited by ARIA and WebKit drops it, so VoiceOver on Safari read only the bold title in 0.38.1), and loosens the React peer back to `^19.2.3` (0.38.1 declared `^19.2.8` only because the dependency batch moved it; nothing in the package needs a newer API). **Do not consume ui 0.38.0**: it imports `@plannotator/core/token-hover` (the hover-card trigger settings, #1462) but pins core 0.25.1, which never exported that subpath, so it fails to compile in any consumer; 0.38.1 is the same UI pinning core 0.25.2, which publishes `./token-hover`, the rotated `guide-viewer-manifest` pin, and the `config-types` hover fields (core 0.25.2 is the first core publish since 0.25.1 even though those changes landed over several releases; the package smoke now diffs the UI's core imports against the registry so an unpublished core subpath fails preflight instead of the consumer). UI 0.38.1 also aligns `@codemirror/state` to `^6.7.2` beside `@codemirror/view ^6.43.10`, so a consumer can no longer resolve two state copies. UI 0.38.0 also renders a GitHub alert's bold-only first body line as its title on the icon row (an emoji on that line becomes the icon; `<!-- icon: name -->` is stripped and resolved through the new `alertIconRenderer` seam, null by default; grammar in `utils/alertTitle`, importable by a host editor so it writes the bytes the reader parses; a fenced code block inside an alert body still renders as text, deferred because nesting a `CodeBlock` inside a block interacts with the positional annotation anchors and needs its own design). UI 0.38.0 carries the whole unified decision-control stack: the internal primitives (`DecisionControl`, `utils/decisionSpec`, `hooks/useDismissablePopover` — not host-supported surface, see the unsupported list; `useDismissablePopover` also replaced the hand-rolled dismissal inside `ActionMenu`/`ApproveDropdown`, both likewise unsupported) plus one blessed-barrel addition: `decisionControlShortcuts` on `@plannotator/ui/shortcuts` (pure scope data, fetch-free, same contract as the other scopes). The removal of `ToolbarButtons`' platform-mode `muted` prop is internal — `ToolbarButtons` is not host-supported surface. UI 0.37.0 added the Viewer-owned document-header seam (a new public API, hence the minor bump; 0.36.1 was reserved for it but never published) while retaining the `hideQuickLabel` and `StickyHeaderLane` seams from the 0.35.x and 0.36.0 releases; core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`, and UI pins that corrected core exactly.
+- Recent pairs, for the consumer's install matrix: ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2, ui 0.36.0, and ui 0.37.0 on core 0.25.1 (0.36.1 was never published), and ui 0.38.1, ui 0.38.2, and ui 0.39.0 on core 0.25.2. Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export. Do not consume ui 0.38.0 because its exact core 0.25.1 dependency lacks the `token-hover` export.
 - When both packages change, **publish `core` first**: ui 0.32.0 imports the `@plannotator/core/html-anchor` subpath, which no earlier published core (0.24.0 and before) has, just as ui 0.29.0 needed core 0.23.0 for `@plannotator/core/annotatable`. Bump core, update UI's exact core dependency to the same new version, and run `bun install` so `bun.lock` records the new workspace versions before packing either package.
 - The HTML annotation seams also changed the guides.show viewer **stylesheet** (five utility rules from `HtmlSurfaceControls`; the viewer JS is unchanged), so `packages/core/guide-viewer-manifest.ts` now pins a CSS hash that exists on guides.show only after the deploy workflow has published this build's `/v1/` assets. A guide exported from this build before that deploy would pin a stylesheet the host does not serve yet: **deploy guides.show before any release that ships this manifest.**
 - UI declares the already published core version exactly in its source manifest. Do not replace it with `workspace:*`: direct publication can preserve that protocol and make the package impossible to install outside this repository. Bun links the local core workspace whenever its version matches the exact dependency. Before publishing, run `bun run --cwd packages/ui smoke:package`; it checks the source and packed manifests, required tarball subpaths, local Bun linking, and a real pnpm install in an external temporary consumer. When both packages change, publish **`core` first, then `ui`**.

package/README.md

@@ -251,7 +251,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on an exact published `@plannotator/core` version. Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Currently `@plannotator/ui` 0.38.2 depends exactly on `@plannotator/core` 0.25.2. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
+- Currently `@plannotator/ui` 0.39.0 depends exactly on `@plannotator/core` 0.25.2. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
 
 ## The one rule
 

package/components/DecisionControl.tsx

@@ -475,16 +475,6 @@ export const DecisionControl: React.FC<DecisionControlProps> = ({
             {spec.primary.label}
           </span>
         )}
-        {typeof spec.primary.count === 'number' && (
-          // The count is the state indicator, not decoration: present at every
-          // breakpoint, unlike the labels.
-          <span
-            data-decision-count="true"
-            className="rounded-full bg-white/25 px-1.5 text-[10px] font-bold leading-4"
-          >
-            {spec.primary.count}
-          </span>
-        )}
       </Button>
   );
 

package/components/html-viewer/bridge-script.asset.js

@@ -116,6 +116,7 @@
   var pendingPinKey = null; // target key for the primary pinpoint target (multi-select)
   var pendingPinLabel = null; // semantic label captured for the primary target
   var pendingPinPoint = null; // normalized {x,y} click point inside the pinned element's rect
+  var pendingPinContext = null; // agent-facing element context for the primary target (see buildElementContext)
   var pendingPinViaPinpoint = false; // pinpoint drafts survive scroll-out (see postSelectionRect)
   // Multi-select is ARMED EXPLICITLY by the parent (arm-multi-select), and only
   // when the comment composer owns the draft. The bridge must never accept a
@@ -242,6 +243,7 @@
       pinpoint: (extras && extras.pinpoint) || undefined,
       targetKey: (extras && extras.targetKey) || undefined,
       targetLabel: (extras && extras.targetLabel) || undefined,
+      context: (extras && extras.context) || undefined,
       rect: { top: rect.top, left: rect.left, width: rect.width, height: rect.height }
     });
     renderAnnotationOverlay(); // draft selection highlight (overlay-projected)
@@ -2504,8 +2506,435 @@
     return el;
   }
 
+  // --- Element context: a bounded, agent-facing description of a pinpointed
+  // element, captured at click time (only the bridge can see the DOM). It is
+  // purely descriptive and NEVER consulted by restore (that is the anchor's
+  // job): the exported feedback prints it so an agent working in the app's
+  // source can find the element without having the page. Everything here is
+  // page-controlled, so the parent re-validates and re-caps it all at the
+  // trust boundary; this side keeps the wire payload honest.
+  //
+  // Constraints (the "smart" part is that they adapt to the element):
+  // - attributes are an ALLOWLIST (a page cannot add a key); no form values,
+  //   no on* handlers, no style, no script/style/template contents ever;
+  // - absolute http(s) URLs lose their query and fragment (tokens live
+  //   there), data: URIs keep only their media-type prefix;
+  // - the outline tries two levels of children, falls back to one, then to a
+  //   per-tag count, whichever first fits CTX_MAX_OUTLINE, so a click on a
+  //   whole <main> costs the same bytes as a click on a chip;
+  // - text is innerText (rendered words, not the DOM soup), word-boundary
+  //   truncated;
+  // - the serialized context stays under a byte budget by shedding the
+  //   expendable fields in a fixed order; tag/id/role/name/page never shed.
+  var CTX_MAX_BYTES = 2048;        // primary target
+  var CTX_MAX_BYTES_EXTRA = 1024;  // each shift-click additional target
+  var CTX_MAX_TEXT = 300;
+  var CTX_MAX_OUTLINE = 600;
+  var CTX_MAX_PATH_SEGMENTS = 8;
+  var CTX_MAX_CLASSES = 8;
+  var CTX_MAX_ATTRS = 10;
+  var CTX_MAX_ATTR_VALUE = 120;
+  var CTX_MAX_CHILDREN = 6;
+  var CONTEXT_ATTRS = ['href', 'src', 'alt', 'title', 'type', 'name', 'role', 'placeholder', 'for', 'target', 'rel',
+    'aria-label', 'aria-labelledby', 'aria-describedby', 'aria-current', 'aria-expanded', 'aria-hidden', 'aria-controls',
+    'data-annotate', 'data-testid', 'data-test', 'data-test-id', 'data-cy', 'data-qa', 'data-component', 'data-id'];
+  var CONTEXT_SKIP_TAGS = { SCRIPT: 1, STYLE: 1, TEMPLATE: 1, NOSCRIPT: 1 };
+  var CONTEXT_IMPLICIT_ROLE = { NAV: 'navigation', MAIN: 'main', HEADER: 'banner', FOOTER: 'contentinfo', ASIDE: 'complementary',
+    ARTICLE: 'article', SECTION: 'region', FORM: 'form', BUTTON: 'button', A: 'link', IMG: 'img', TABLE: 'table', UL: 'list',
+    OL: 'list', LI: 'listitem', H1: 'heading', H2: 'heading', H3: 'heading', H4: 'heading', H5: 'heading', H6: 'heading',
+    DIALOG: 'dialog', INPUT: 'textbox', TEXTAREA: 'textbox', SELECT: 'combobox', SUMMARY: 'button', PROGRESS: 'progressbar' };
+  var CONTEXT_LANDMARK_SELECTOR = 'main,nav,header,footer,aside,article,section,form,dialog,[role]';
+
+  // Collapse control characters and whitespace runs; the parent does it again.
+  function ctxCollapse(value, max) {
+    var s = String(value == null ? '' : value).replace(/[\x00-\x1f\x7f]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return max ? ctxTruncate(s, max) : s;
+  }
+
+  // Word-boundary truncation with an ellipsis, never splitting a surrogate pair.
+  function ctxTruncate(s, max) {
+    if (s.length <= max) return s;
+    var cut = s.lastIndexOf(' ', max - 1);
+    if (cut < max * 0.6) cut = max - 1;
+    var last = s.charCodeAt(cut - 1);
+    if (last >= 0xd800 && last <= 0xdbff) cut -= 1;
+    return s.slice(0, cut) + '…';
+  }
+
+  function ctxBytes(value) {
+    var json = JSON.stringify(value);
+    try { return new TextEncoder().encode(json).length; } catch (ex) {}
+    try { return unescape(encodeURIComponent(json)).length; } catch (ex2) { return json.length * 2; }
+  }
+
+  // URL attribute values: keep what locates the element in source, drop
+  // what identifies the user. Relative URLs are route state and stay whole.
+  function ctxScrubUrl(value) {
+    var v = String(value).trim();
+    if (/^javascript:/i.test(v)) return null;
+    if (/^data:/i.test(v)) {
+      var comma = v.indexOf(',');
+      return (comma > 0 ? v.slice(0, Math.min(comma, 40)) : v.slice(0, 40)) + ',…';
+    }
+    if (/^https?:\/\//i.test(v)) {
+      try {
+        var u = new URL(v);
+        return u.origin + u.pathname + (u.search || u.hash ? '?…' : '');
+      } catch (ex) { return ctxTruncate(v, CTX_MAX_ATTR_VALUE); }
+    }
+    return v;
+  }
+
+  function ctxAttrs(el) {
+    var out = [];
+    if (!el.getAttribute) return out;
+    for (var i = 0; i < CONTEXT_ATTRS.length && out.length < CTX_MAX_ATTRS; i++) {
+      var name = CONTEXT_ATTRS[i];
+      var value = el.getAttribute(name);
+      if (value == null) continue;
+      if (name === 'href' || name === 'src') {
+        value = ctxScrubUrl(value);
+        if (value == null) continue;
+      }
+      out.push([name, ctxCollapse(value, CTX_MAX_ATTR_VALUE)]);
+    }
+    return out;
+  }
+
+  function ctxClasses(el) {
+    var out = [];
+    if (!el.classList) return out;
+    for (var i = 0; i < el.classList.length && out.length < CTX_MAX_CLASSES; i++) {
+      var cls = String(el.classList[i]);
+      if (!cls || isLikelyGeneratedClass(cls)) continue;
+      out.push(ctxTruncate(cls, 48));
+    }
+    if (el.classList.length > out.length && out.length === CTX_MAX_CLASSES) out.push('+' + (el.classList.length - out.length) + ' more');
+    return out;
+  }
+
+  function ctxFirstClass(el) {
+    if (!el.classList) return null;
+    for (var i = 0; i < el.classList.length; i++) {
+      var cls = String(el.classList[i]);
+      if (cls && !isLikelyGeneratedClass(cls)) return ctxTruncate(cls, 48);
+    }
+    return null;
+  }
+
+  function ctxRole(el) {
+    var explicit = el.getAttribute && el.getAttribute('role');
+    if (explicit && explicit.trim()) return ctxCollapse(explicit, 32);
+    if (el.tagName === 'A' && !(el.getAttribute && el.getAttribute('href'))) return null;
+    return CONTEXT_IMPLICIT_ROLE[el.tagName] || null;
+  }
+
+  function ctxText(el) {
+    var raw = typeof el.innerText === 'string' && el.innerText ? el.innerText : (el.textContent || '');
+    return ctxCollapse(raw, CTX_MAX_TEXT);
+  }
+
+  // Accessible name, in the practical order: aria-label, aria-labelledby,
+  // alt, title, a <label for>, then the element's own short text.
+  function ctxName(el) {
+    if (!el.getAttribute) return null;
+    var aria = el.getAttribute('aria-label');
+    if (aria && aria.trim()) return ctxCollapse(aria, 120);
+    var by = el.getAttribute('aria-labelledby');
+    if (by && by.trim()) {
+      var ids = by.trim().split(/\s+/);
+      var parts = [];
+      for (var i = 0; i < ids.length && i < 4; i++) {
+        var ref = document.getElementById(ids[i]);
+        if (ref) parts.push(ref.textContent || '');
+      }
+      var joined = ctxCollapse(parts.join(' '), 120);
+      if (joined) return joined;
+    }
+    var alt = el.getAttribute('alt');
+    if (alt && alt.trim()) return ctxCollapse(alt, 120);
+    var title = el.getAttribute('title');
+    if (title && title.trim()) return ctxCollapse(title, 120);
+    if (el.id && typeof CSS !== 'undefined' && CSS.escape) {
+      var label = null;
+      try { label = document.querySelector('label[for="' + CSS.escape(el.id) + '"]'); } catch (ex) {}
+      if (label) {
+        var labelText = ctxCollapse(label.textContent, 120);
+        if (labelText) return labelText;
+      }
+    }
+    var own = ctxCollapse(el.textContent, 120);
+    return own && own.length <= 80 ? own : null;
+  }
+
+  // One path segment: tag, then the strongest cheap identity it carries, and
+  // a position only when a same-tag sibling would otherwise read the same.
+  function ctxSegment(el) {
+    var seg = el.tagName.toLowerCase();
+    if (el.id) return seg + '#' + ctxCollapse(el.id, 60);
+    var cls = ctxFirstClass(el);
+    if (cls) seg += '.' + cls;
+    var hook = el.getAttribute && (el.getAttribute('data-testid') || el.getAttribute('data-component'));
+    if (hook) seg += '[' + (el.getAttribute('data-testid') ? 'data-testid' : 'data-component') + '="' + ctxCollapse(hook, 40) + '"]';
+    // A position only when a same-tag sibling would read identically (same
+    // first class, same hook): p.beta among p.alpha / p.gamma needs none,
+    // the fourth of forty identical <li class="row"> does.
+    var parent = el.parentElement;
+    if (parent) {
+      var same = 0;
+      var index = 0;
+      var typeIndex = 0;
+      var typeCount = 0;
+      for (var i = 0; i < parent.children.length; i++) {
+        var sibling = parent.children[i];
+        if (sibling.tagName !== el.tagName) continue;
+        typeCount++;
+        if (sibling === el) typeIndex = typeCount;
+        if (sibling.id) continue;
+        if (ctxFirstClass(sibling) === cls && !!(sibling.getAttribute && (sibling.getAttribute('data-testid') || sibling.getAttribute('data-component'))) === !!hook) {
+          same++;
+          if (sibling === el) index = same;
+        }
+      }
+      if (same > 1) seg += ':nth-of-type(' + typeIndex + ')';
+    }
+    return seg;
+  }
+
+  function ctxPath(el) {
+    var parts = [];
+    var current = el;
+    while (current && current.nodeType === 1 && current !== document.documentElement) {
+      if (parts.length >= CTX_MAX_PATH_SEGMENTS) { parts.unshift('…'); break; }
+      parts.unshift(ctxSegment(current));
+      if (current === document.body) break;
+      current = current.parentElement;
+    }
+    return parts.join(' > ');
+  }
+
+  function ctxIsSkipped(node) {
+    return !node || node.nodeType !== 1 || CONTEXT_SKIP_TAGS[node.tagName] || isViewerOverlayNode(node);
+  }
+
+  function ctxElementChildren(el) {
+    var kids = [];
+    for (var i = 0; i < el.children.length; i++) {
+      if (!ctxIsSkipped(el.children[i])) kids.push(el.children[i]);
+    }
+    return kids;
+  }
+
+  function ctxTagCounts(nodes) {
+    var counts = {};
+    var order = [];
+    for (var i = 0; i < nodes.length; i++) {
+      var tag = nodes[i].tagName.toLowerCase();
+      if (!counts[tag]) { counts[tag] = 0; order.push(tag); }
+      counts[tag]++;
+    }
+    var out = [];
+    for (var j = 0; j < order.length && j < 4; j++) out.push(order[j] + '×' + counts[order[j]]);
+    if (order.length > 4) out.push('…');
+    return out.join(', ');
+  }
+
+  function ctxAttrString(pairs) {
+    var s = '';
+    for (var i = 0; i < pairs.length; i++) s += ' ' + pairs[i][0] + '="' + pairs[i][1].replace(/"/g, '&quot;') + '"';
+    return s;
+  }
+
+  // id and up to four author classes on an opening tag: the grep keys, first.
+  function ctxIdentityString(el) {
+    var s = '';
+    if (el.id) s += ' id="' + ctxCollapse(el.id, 60) + '"';
+    var classes = [];
+    if (el.classList) {
+      for (var i = 0; i < el.classList.length && classes.length < 4; i++) {
+        var cls = String(el.classList[i]);
+        if (cls && !isLikelyGeneratedClass(cls)) classes.push(ctxTruncate(cls, 48));
+      }
+    }
+    if (classes.length) s += ' class="' + classes.join(' ') + '"';
+    return s;
+  }
+
+  // A child rendered inside the outline: its tag with one identity hook, its
+  // own short text when it has no element children, an ellipsis otherwise.
+  function ctxChildTag(child, depth) {
+    var tag = child.tagName.toLowerCase();
+    var open = '<' + tag;
+    if (child.id) open += ' id="' + ctxCollapse(child.id, 60) + '"';
+    else {
+      var cls = ctxFirstClass(child);
+      if (cls) open += ' class="' + cls + '"';
+    }
+    var hook = child.getAttribute && child.getAttribute('data-testid');
+    if (hook) open += ' data-testid="' + ctxCollapse(hook, 40) + '"';
+    if (tag === 'a' && child.getAttribute('href')) {
+      var href = ctxScrubUrl(child.getAttribute('href'));
+      if (href) open += ' href="' + ctxCollapse(href, 60) + '"';
+    }
+    open += '>';
+    var kids = ctxElementChildren(child);
+    if (!kids.length) {
+      var own = ctxCollapse(child.textContent, 40);
+      return open + own + '</' + tag + '>';
+    }
+    if (depth <= 1) {
+      var leafText = ctxCollapse(child.textContent, 40);
+      return open + (leafText || '…') + '</' + tag + '>';
+    }
+    var lines = [open];
+    var shown = kids.slice(0, CTX_MAX_CHILDREN);
+    for (var i = 0; i < shown.length; i++) lines.push('  ' + ctxChildTag(shown[i], depth - 1));
+    if (kids.length > shown.length) lines.push('  <!-- +' + (kids.length - shown.length) + ' more: ' + ctxTagCounts(kids.slice(shown.length)) + ' -->');
+    lines.push('</' + tag + '>');
+    return lines.join('\n');
+  }
+
+  function ctxOutlineAtDepth(el, attrs, kids, depth) {
+    var tag = el.tagName.toLowerCase();
+    var open = '<' + tag + ctxIdentityString(el) + ctxAttrString(attrs) + '>';
+    if (!kids.length) {
+      var own = ctxCollapse(el.textContent, 80);
+      return open + own + '</' + tag + '>';
+    }
+    if (depth <= 0) return open + '<!-- ' + kids.length + ' children: ' + ctxTagCounts(kids) + ' -->' + '</' + tag + '>';
+    var lines = [open];
+    var shown = kids.slice(0, CTX_MAX_CHILDREN);
+    for (var i = 0; i < shown.length; i++) {
+      var rendered = ctxChildTag(shown[i], depth);
+      var childLines = rendered.split('\n');
+      for (var j = 0; j < childLines.length; j++) lines.push('  ' + childLines[j]);
+    }
+    if (kids.length > shown.length) lines.push('  <!-- +' + (kids.length - shown.length) + ' more: ' + ctxTagCounts(kids.slice(shown.length)) + ' -->');
+    lines.push('</' + tag + '>');
+    return lines.join('\n');
+  }
+
+  // Adaptive depth: two levels, then one, then a per-tag count — the first
+  // that fits the outline cap. A whole-page container never costs more than a chip.
+  function ctxOutline(el, attrs) {
+    var kids = ctxElementChildren(el);
+    var depths = [2, 1, 0];
+    for (var i = 0; i < depths.length; i++) {
+      var out = ctxOutlineAtDepth(el, attrs, kids, depths[i]);
+      if (out.length <= CTX_MAX_OUTLINE) return out;
+    }
+    return ctxTruncate(ctxOutlineAtDepth(el, attrs, kids, 0), CTX_MAX_OUTLINE);
+  }
+
+  function ctxLandmark(el) {
+    var parent = el.parentElement;
+    if (!parent || !parent.closest) return null;
+    var region = null;
+    try { region = parent.closest(CONTEXT_LANDMARK_SELECTOR); } catch (ex) { return null; }
+    if (!region || region === document.body) return null;
+    var seg = ctxSegment(region);
+    var name = region.getAttribute('aria-label');
+    if (name && name.trim()) seg += ' "' + ctxCollapse(name, 60) + '"';
+    return ctxTruncate(seg, 80);
+  }
+
+  // The nearest heading ABOVE the element in document order (or one that
+  // contains it): the section it sits in, which often names the source file.
+  function ctxHeading(el) {
+    var headings = document.querySelectorAll('h1,h2,h3,h4,h5,h6');
+    var best = null;
+    for (var i = 0; i < headings.length && i < 500; i++) {
+      var h = headings[i];
+      var pos = el.compareDocumentPosition(h);
+      if (pos & 2 || pos & 8) best = h; // PRECEDING or CONTAINS
+      else if (pos & 4) break;          // FOLLOWING: every later heading follows too
+    }
+    if (!best) return null;
+    var text = ctxCollapse(best.textContent, 120);
+    return text ? best.tagName.toLowerCase() + ' "' + text + '"' : null;
+  }
+
+  // The cheapest safe framework hint: an author-placed component marker on
+  // the element or a near ancestor. Deliberately no React fiber reads.
+  function ctxComponent(el) {
+    var current = el;
+    for (var depth = 0; current && current.nodeType === 1 && depth < 6; depth++) {
+      var attrs = ['data-component', 'data-testid', 'data-qa'];
+      for (var i = 0; i < attrs.length; i++) {
+        var value = current.getAttribute && current.getAttribute(attrs[i]);
+        if (value && value.trim()) return attrs[i] + '=' + ctxCollapse(value, 60);
+      }
+      current = current.parentElement;
+    }
+    return null;
+  }
+
+  function ctxRect(el) {
+    var r = el.getBoundingClientRect();
+    return {
+      x: Math.round(r.left), y: Math.round(r.top),
+      w: Math.round(r.width), h: Math.round(r.height),
+      vw: Math.round(window.innerWidth || 0), vh: Math.round(window.innerHeight || 0)
+    };
+  }
+
+  // Shed order when over budget: the fields an agent can live without first.
+  var CTX_SHED_ORDER = ['outline', 'text', 'attrs', 'classes', 'path', 'heading', 'landmark', 'component'];
+
+  function buildElementContext(el, maxBytes) {
+    if (!el || el.nodeType !== 1) return null;
+    try {
+      var attrs = ctxAttrs(el);
+      var context = { tag: el.tagName.toLowerCase() };
+      if (el.id) context.id = ctxCollapse(el.id, 100);
+      var classes = ctxClasses(el);
+      if (classes.length) context.classes = classes;
+      context.path = ctxPath(el);
+      var role = ctxRole(el);
+      if (role) context.role = role;
+      var name = ctxName(el);
+      if (name) context.name = name;
+      if (attrs.length) context.attrs = attrs;
+      var text = ctxText(el);
+      if (text) context.text = text;
+      context.outline = ctxOutline(el, attrs);
+      context.children = ctxElementChildren(el).length;
+      context.rect = ctxRect(el);
+      var landmark = ctxLandmark(el);
+      if (landmark) context.landmark = landmark;
+      var heading = ctxHeading(el);
+      if (heading) context.heading = heading;
+      var component = ctxComponent(el);
+      if (component) context.component = component;
+      if (LIVE) {
+        context.page = { url: currentPageUrl() };
+        var title = ctxCollapse(document.title, 200);
+        if (title) context.page.title = title;
+      }
+      // Byte budget: shed whole fields in order; a shed attrs/classes array
+      // first loses entries from the end before the field goes entirely.
+      for (var s = 0; s < CTX_SHED_ORDER.length && ctxBytes(context) > maxBytes; s++) {
+        var field = CTX_SHED_ORDER[s];
+        if (context[field] === undefined) continue;
+        if ((field === 'attrs' || field === 'classes') && context[field].length > 1) {
+          while (context[field].length > 1 && ctxBytes(context) > maxBytes) context[field].pop();
+          if (ctxBytes(context) <= maxBytes) break;
+        }
+        if (field === 'text' && context.text.length > 80) {
+          context.text = ctxTruncate(context.text, 80);
+          if (ctxBytes(context) <= maxBytes) break;
+        }
+        delete context[field];
+      }
+      return context;
+    } catch (ex) {
+      return null;
+    }
+  }
+
   function clearPendingPin() {
     pendingPinEl = null;
+    pendingPinContext = null;
     pendingPinAnchor = null;
     pendingPinKey = null;
     pendingPinLabel = null;
@@ -2626,6 +3055,7 @@
       pendingPinKey = next.key;
       pendingPinLabel = next.label;
       pendingPinPoint = next.point || null;
+      pendingPinContext = next.context || null;
       // A promoted primary commits as an element pin: the original text
       // selection belonged to the removed element and no longer applies.
       pendingSelection = { element: true };
@@ -2684,15 +3114,17 @@
     if (anchor && point) anchor.point = point;
     var label = pinpointHoverLabel(el);
     var text = elementTargetText(el, label);
+    var context = buildElementContext(el, CTX_MAX_BYTES_EXTRA);
     var key = makeTargetKey();
     var box = createMultiTargetBox(el);
-    pendingMultiTargets.push({ key: key, el: el, anchor: anchor, label: label, text: text, point: point, box: box });
+    pendingMultiTargets.push({ key: key, el: el, anchor: anchor, label: label, text: text, point: point, context: context, box: box });
     postToParent({
       type: PREFIX + 'multi-target-added',
       key: key,
       label: label,
       text: text,
-      anchor: anchor || undefined
+      anchor: anchor || undefined,
+      context: context || undefined
     });
   }
 
@@ -2793,11 +3225,15 @@
     pendingPinPoint = normalizePointInElement(el, clickPoint);
     if (pendingPinAnchor && pendingPinPoint) pendingPinAnchor.point = pendingPinPoint;
     pendingPinViaPinpoint = !!viaPinpoint;
+    // Agent-facing description, captured now while the element is in hand
+    // (an SPA re-render or navigation may have replaced it by submit time).
+    pendingPinContext = buildElementContext(el, CTX_MAX_BYTES);
     var extras = {
       anchor: pendingPinAnchor,
       pinpoint: !!viaPinpoint,
       targetKey: pendingPinKey,
-      targetLabel: pendingPinLabel
+      targetLabel: pendingPinLabel,
+      context: pendingPinContext
     };
     // Pinned outline: stronger accent box that tracks the element until the
     // composer resolves (create-mark or cancel-selection).
@@ -2839,6 +3275,7 @@
       pinpoint: !!viaPinpoint || undefined,
       targetKey: pendingPinKey || undefined,
       targetLabel: pendingPinLabel || undefined,
+      context: pendingPinContext || undefined,
       rect: { top: r.top, left: r.left, width: r.width, height: r.height } });
     return true;
   }