@plannotator/ui 0.49.0 → 0.51.0

package/components/html-viewer/HtmlViewer.tsx

@@ -17,6 +17,7 @@ import {
 import type { Annotation, EditorMode, ImageAttachment, InputMethod } from "../../types";
 import { AnnotationType } from "../../types";
 import { copyTextPreservingFocus } from "../../utils/clipboard";
+import { elementIdentityForAskAI } from "../../utils/parser";
 import { getIdentity } from "../../utils/identity";
 import { THUMBS_UP_LABEL } from "../../utils/quickLabels";
 import {
@@ -674,6 +675,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       }));
     }, [hook.draftTargets]);
 
+    // Ask AI from a pinpoint draft: which element(s) the question is about,
+    // in the identity lines the feedback export prints (no outline).
+    const askAIElementDetail = useMemo(
+      () => elementIdentityForAskAI(hook.draftTargets) || undefined,
+      [hook.draftTargets],
+    );
+
     useEffect(() => {
       function handler(e: MessageEvent<unknown>) {
         if (e.source !== iframeRef.current?.contentWindow) return;
@@ -1244,9 +1252,10 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               draftKey={`html:${hook.commentPopover.draftKey}`}
               onSubmit={hook.handleCommentSubmit}
               mentionSource={mentionSource}
-              // Pinpoint clicks open this composer directly, so it carries
-              // the surface's one-click "Looks good" (the global composer
-              // does not: a document-wide thumbs-up is not a thing).
+              // A pinpoint click opens this composer directly (never the
+              // selection toolbar), so it carries the surface's one-click 👍.
+              // It also shows when the composer opens from a text selection's
+              // Comment button: a harmless duplicate of the toolbar 👍.
               onQuickLookGood={hook.handleCommentLooksGood}
               onClose={hook.handleCommentClose}
               skillReferences
@@ -1255,6 +1264,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 kind: "selection",
                 label: "Selected HTML",
                 text: hook.commentPopover.selectedText ?? hook.commentPopover.contextText,
+                ...(askAIElementDetail ? { detail: askAIElementDetail } : {}),
               }}
               targetChips={targetChips}
               onRemoveTargetChip={targetChips ? hook.removeDraftTarget : undefined}

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

@@ -96,17 +96,89 @@
   });
 
   // --- Resize ---
-  var lastHeight = 0;
+  // The last child of el whose bottom margin could collapse through el's
+  // bottom edge: out-of-flow children (display:none, absolute/fixed, floats)
+  // never do, which also skips the bridge's own fixed overlay elements and a
+  // trailing script element.
+  function lastInFlowChild(el) {
+    for (var child = el.lastElementChild; child; child = child.previousElementSibling) {
+      var cs = window.getComputedStyle(child);
+      if (cs.display === 'none' || cs.display === 'contents') continue;
+      if (cs.position === 'absolute' || cs.position === 'fixed') continue;
+      if (cs.float && cs.float !== 'none') continue;
+      return child;
+    }
+    return null;
+  }
+
+  // Height the auto-sized frame needs to show the whole document.
+  // Not body.scrollHeight alone: when body has no top padding or border, a
+  // first child's top margin collapses THROUGH body and moves body's box down
+  // without making it taller (the same holds at the bottom), so the page was
+  // cut short by those margins. Not documentElement.scrollHeight either: it
+  // never reports less than the frame's own viewport, so the frame could grow
+  // but never shrink back, and an html{height:100%} page would pin it at
+  // whatever height it had. Instead body's box is placed in document
+  // coordinates (its top already includes a collapsed top margin), and the
+  // bottom margins that can collapse through body's bottom edge are added by
+  // walking the last in-flow child chain. Nothing here reads the frame's own
+  // height, so the measure cannot feed back on itself.
+  function measureContentHeight() {
+    var body = document.body;
+    var scrollY = window.pageYOffset || 0;
+    var bodyRect = body.getBoundingClientRect();
+    var bottom = Math.max(bodyRect.bottom, bodyRect.top + (body.clientTop || 0) + body.scrollHeight) + scrollY;
+    var el = body;
+    for (var depth = 0; el && depth < 64; depth++) {
+      var cs = window.getComputedStyle(el);
+      var marginBottom = parseFloat(cs.marginBottom) || 0;
+      if (marginBottom > 0) bottom = Math.max(bottom, el.getBoundingClientRect().bottom + scrollY + marginBottom);
+      // A child's bottom margin only collapses through a plain block parent
+      // with no bottom padding or border that does not clip (flex/grid
+      // containers, flow-root and scroll containers keep it inside).
+      if (cs.display !== 'block' && cs.display !== 'list-item') break;
+      if (cs.overflowY && cs.overflowY !== 'visible') break;
+      if ((parseFloat(cs.paddingBottom) || 0) > 0 || (parseFloat(cs.borderBottomWidth) || 0) > 0) break;
+      el = lastInFlowChild(el);
+    }
+    var rootStyle = window.getComputedStyle(document.documentElement);
+    bottom += (parseFloat(rootStyle.paddingBottom) || 0) + (parseFloat(rootStyle.borderBottomWidth) || 0);
+    return Math.max(0, Math.ceil(bottom));
+  }
+
+  // Feedback guard. Content sized by the frame itself (html,body{height:100%},
+  // min-height:100vh, a 100vh section) plus anything around it (a collapsed
+  // margin, body's own margin) always measures taller than the frame, so every
+  // grow would ask for another: the frame would grow forever. The first
+  // measure after the parent applied a GROW we asked for decides: if the page
+  // still overflows by at least as much as it did before the grow, it grew
+  // with the frame, and the frame stays where it is. Later content changes
+  // post as usual (and re-run the check on their own grow). Pure, so the
+  // test can drive it: returns the height to post, or null for none.
+  function nextResizeHeight(state, h, viewport) {
+    var applied = state.awaiting && Math.abs(viewport - state.last) <= 1;
+    if (applied) state.awaiting = false;
+    if (h === state.last) return null;
+    if (applied && state.excess > 0 && h > viewport && h - viewport >= state.excess - 1) {
+      state.last = h; // held: report nothing until the content measures differently
+      return null;
+    }
+    state.excess = h - viewport;
+    state.awaiting = true;
+    state.last = h;
+    return h;
+  }
+
+  var resizeState = { last: 0, excess: 0, awaiting: false };
   function postResize() {
     if (LIVE) return; // live surfaces render full-viewport; the parent ignores height
     if (!document.body) return;
-    var h = document.body.scrollHeight;
-    if (h !== lastHeight) {
-      lastHeight = h;
-      postToParent({ type: PREFIX + 'resize', height: h });
-    }
+    var h = nextResizeHeight(resizeState, measureContentHeight(), window.innerHeight);
+    if (h !== null) postToParent({ type: PREFIX + 'resize', height: h });
   }
   window.addEventListener('load', postResize);
+  // The frame resizing is what tells the guard its last grow was applied.
+  window.addEventListener('resize', postResize, { passive: true });
 
   // --- Selection ---
   var pendingSelection = null;
@@ -908,6 +980,10 @@
 
   // Floating label naming the element under the cursor (like the markdown overlay).
   var PINPOINT_LABELS = { H1:'Heading', H2:'Heading', H3:'Heading', H4:'Heading', H5:'Heading', H6:'Heading', P:'Paragraph', UL:'List', OL:'List', LI:'List item', A:'Link', BUTTON:'Button', IMG:'Image', TABLE:'Table', THEAD:'Table', TBODY:'Table', TR:'Row', TD:'Cell', TH:'Header cell', SECTION:'Section', NAV:'Navigation', HEADER:'Header', FOOTER:'Footer', ARTICLE:'Article', ASIDE:'Sidebar', BLOCKQUOTE:'Quote', PRE:'Code', CODE:'Code', FIGURE:'Figure', FIGCAPTION:'Caption', MAIN:'Main', FORM:'Form', INPUT:'Input', LABEL:'Label' };
+  // Media kinds name themselves only when the page gives no accessible name:
+  // unlike the semantic tags above, an aria-label on a <video> is a better
+  // label than "Video", and it keeps winning exactly as it did before.
+  var MEDIA_PINPOINT_LABELS = { VIDEO:'Video', AUDIO:'Audio', IFRAME:'Frame', CANVAS:'Canvas' };
 
   var MAX_HOVER_LABEL = 40;
   function truncateLabel(text) {
@@ -943,6 +1019,8 @@
     if (known) return known;
     var aria = el.getAttribute && el.getAttribute('aria-label');
     if (aria && aria.trim()) return truncateLabel(aria.trim());
+    var media = MEDIA_PINPOINT_LABELS[el.tagName];
+    if (media) return media;
     var role = el.getAttribute && el.getAttribute('role');
     if (role && role.trim()) return truncateLabel(role.trim());
     var tokens = meaningfulClassTokens(el);
@@ -2608,6 +2686,25 @@
   function ctxScrubUrl(value) {
     var v = String(value).trim();
     if (/^javascript:/i.test(v)) return null;
+    // Srcdoc sessions serve a document's relative assets through the
+    // session's own asset route (/api/html-assets/<token>/<path>). The token
+    // means nothing outside this session; the path after it is the author's
+    // own, relative to the document, which is what an agent can find.
+    if (!LIVE) {
+      var asset = v.match(/^\/api\/html-assets\/[^\/?#]+\/([^?#]*)/);
+      if (asset && asset[1]) {
+        // The route percent-encodes each segment; show the name the author
+        // wrote (jane doe.png, not jane%20doe.png). A malformed escape, or one
+        // that decodes to ? or # (which the query scrub below would cut), keeps
+        // the raw text.
+        var authored = asset[1];
+        try {
+          var decoded = decodeURIComponent(authored);
+          if (!/[?#]/.test(decoded)) authored = decoded;
+        } catch (ex) {}
+        v = authored + v.slice(asset[0].length);
+      }
+    }
     if (/^data:/i.test(v)) {
       var comma = v.indexOf(',');
       return (comma > 0 ? v.slice(0, Math.min(comma, 40)) : v.slice(0, 40)) + ',…';
@@ -2917,7 +3014,8 @@
   }
 
   // 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'];
+  // Mirrors ELEMENT_CONTEXT_SHED_ORDER in @plannotator/core/html-anchor.
+  var CTX_SHED_ORDER = ['outline', 'text', 'attrs', 'classes', 'path', 'heading', 'landmark', 'component', 'sourceName'];
 
   function buildElementContext(el, maxBytes) {
     if (!el || el.nodeType !== 1) return null;
@@ -2944,6 +3042,12 @@
       if (heading) context.heading = heading;
       var component = ctxComponent(el);
       if (component) context.component = component;
+      // The media file this element shows, resolved exactly as the composer
+      // quote resolves it (src, a lazy data-src, srcset, <picture>/<source>,
+      // poster; see descRawSource), so the exported heading can name the file
+      // even when the element has no usable src attribute.
+      var sourceName = descSourceName(el);
+      if (sourceName) context.sourceName = sourceName;
       if (LIVE) {
         context.page = { url: currentPageUrl() };
         var title = ctxCollapse(document.title, 200);
@@ -3056,11 +3160,95 @@
     }
   }
 
-  // Element text for an additional target: same capping and text-less
-  // description used by the primary element path in annotateElement.
+  // --- Text-less element descriptions ---
+  // A pinpoint on an element with no text quotes a description instead
+  // ("[element: …]"). The hover label alone ("Image") cannot tell one image
+  // from the next, so the description adds what identifies THIS element: its
+  // accessible name (aria-label, alt, title, ...) and, for media, the source
+  // file name. The source goes through the same scrub the element context
+  // uses (no query, no fragment, data: reduced to its media type). Square
+  // brackets become parentheses and double quotes single ones, so the whole
+  // description stays one "[element: …]" token the export recognizes.
+  var DESC_MAX_NAME = 80;
+  var DESC_MAX_FILE = 60;
+  var DESC_SRC_ATTR = { IMG: 'src', VIDEO: 'src', AUDIO: 'src', IFRAME: 'src', EMBED: 'src', SOURCE: 'src', TRACK: 'src', INPUT: 'src', OBJECT: 'data' };
+
+  function descClean(value, max) {
+    return ctxCollapse(String(value).replace(/\[/g, '(').replace(/\]/g, ')').replace(/"/g, "'"), max);
+  }
+
+  // Candidates are comma-separated ("a.png, b.png 2x"); the URL is the
+  // first candidate's first word. A data: URL carries its own comma, so it is
+  // taken up to whitespace instead.
+  function descFirstSrcsetUrl(value) {
+    var srcset = String(value || '').trim();
+    if (!srcset) return '';
+    return (/^data:/i.test(srcset) ? srcset : srcset.split(',')[0]).trim().split(/\s+/)[0] || '';
+  }
+
+  function descRawSource(el) {
+    var tag = el.tagName;
+    if (tag === 'INPUT' && String(el.getAttribute('type') || '').toLowerCase() !== 'image') return '';
+    var attr = DESC_SRC_ATTR[tag];
+    var src = '';
+    if (attr) src = (el.getAttribute(attr) || '').trim();
+    else if (el.ownerSVGElement && tag.toLowerCase() === 'image') src = (el.getAttribute('href') || el.getAttribute('xlink:href') || '').trim();
+    else return '';
+    // Lazy loaders put a data: placeholder in src and the real file in data-src.
+    var lazy = (el.getAttribute('data-src') || '').trim();
+    if (lazy && (!src || /^data:/i.test(src))) src = lazy;
+    if (!src && tag === 'IMG') {
+      src = descFirstSrcsetUrl(el.getAttribute('srcset'));
+      // <picture><source srcset="…"><img></picture>: the img itself may carry
+      // no source at all; the first <source> candidate names the file.
+      var picture = el.parentElement;
+      if (!src && picture && picture.tagName === 'PICTURE' && picture.querySelector) {
+        var pictureSource = picture.querySelector('source[srcset]');
+        if (pictureSource) src = descFirstSrcsetUrl(pictureSource.getAttribute('srcset'));
+      }
+    }
+    if (!src && (tag === 'VIDEO' || tag === 'AUDIO')) {
+      var child = el.querySelector && el.querySelector('source[src]');
+      if (child) src = (child.getAttribute('src') || '').trim();
+      if (!src && tag === 'VIDEO') src = (el.getAttribute('poster') || '').trim();
+    }
+    return src;
+  }
+
+  // The file name a source points at: "team.jpg" for
+  // https://cdn.test/img/team.jpg?sig=…, "data:image/png" for an inline image.
+  function descSourceName(el) {
+    var src = descRawSource(el);
+    if (!src) return '';
+    var scrubbed = ctxScrubUrl(src);
+    if (!scrubbed) return '';
+    if (/^data:/i.test(scrubbed)) {
+      var media = scrubbed.slice(5).split(/[;,]/)[0];
+      return descClean('data:' + (media || 'unknown'), DESC_MAX_FILE);
+    }
+    if (/^blob:/i.test(scrubbed)) return 'blob';
+    var path = scrubbed.replace(/\?…$/, '').replace(/\/+$/, '');
+    var name = path.slice(path.lastIndexOf('/') + 1);
+    try { name = decodeURIComponent(name); } catch (ex) {}
+    if (!name || /^[a-z][a-z0-9+.-]*:$/i.test(name)) name = path;
+    return descClean(name, DESC_MAX_FILE);
+  }
+
+  function describeTextlessElement(el, label) {
+    var out = descClean(label, DESC_MAX_NAME) || 'element';
+    var name = ctxName(el);
+    name = name ? descClean(name, DESC_MAX_NAME) : '';
+    if (name && name !== out) out += ' "' + name + '"';
+    var file = descSourceName(el);
+    if (file && file !== name) out += ' (' + file + ')';
+    return out;
+  }
+
+  // Element text for a pinpoint target (primary or additional): the
+  // element's own text, or for a text-less element its description.
   function elementTargetText(el, label) {
     var text = capSelectionText((el.textContent || '').trim());
-    if (!text) text = capSelectionText('[element: ' + label + ']');
+    if (!text) text = capSelectionText('[element: ' + describeTextlessElement(el, label) + ']');
     return text;
   }
 
@@ -3299,10 +3487,10 @@
       if (!posted) clearPendingPin();
       return posted;
     }
-    var elText = capSelectionText((el.textContent || '').trim());
-    // Text-less elements (icon buttons, decorative chips, empty containers)
-    // are still annotatable: describe the element instead of quoting it.
-    if (!elText) elText = capSelectionText('[element: ' + pinpointHoverLabel(el) + ']');
+    // Text-less elements (images, icon buttons, decorative chips, empty
+    // containers) are still annotatable: describe the element instead of
+    // quoting it, naming WHICH one it is where the page says so.
+    var elText = elementTargetText(el, pinpointHoverLabel(el));
     var r = el.getBoundingClientRect();
     pendingSelection = { element: true };
     pendingRange = null;
@@ -4898,11 +5086,16 @@
 
   function onReady() {
     if (typeof ResizeObserver !== 'undefined' && document.body) {
-      new ResizeObserver(function() {
+      var resizeObserver = new ResizeObserver(function() {
         postResize();
         scheduleVimUiUpdate();
         schedulePinpointReconcile();
-      }).observe(document.body);
+      });
+      resizeObserver.observe(document.body);
+      // A collapsed margin changing moves body without resizing it; the root
+      // box does resize then. (An html{height:100%} root resizes with the
+      // frame instead, which re-measures the same height and posts nothing.)
+      resizeObserver.observe(document.documentElement);
     }
     watchPageMutations();
     // Armed is the default on both surfaces, and live sessions default to

package/components/html-viewer/bridge-script.ts

@@ -332,17 +332,89 @@ export const BRIDGE_SCRIPT = `(function() {
   });
 
   // --- Resize ---
-  var lastHeight = 0;
+  // The last child of el whose bottom margin could collapse through el's
+  // bottom edge: out-of-flow children (display:none, absolute/fixed, floats)
+  // never do, which also skips the bridge's own fixed overlay elements and a
+  // trailing script element.
+  function lastInFlowChild(el) {
+    for (var child = el.lastElementChild; child; child = child.previousElementSibling) {
+      var cs = window.getComputedStyle(child);
+      if (cs.display === 'none' || cs.display === 'contents') continue;
+      if (cs.position === 'absolute' || cs.position === 'fixed') continue;
+      if (cs.float && cs.float !== 'none') continue;
+      return child;
+    }
+    return null;
+  }
+
+  // Height the auto-sized frame needs to show the whole document.
+  // Not body.scrollHeight alone: when body has no top padding or border, a
+  // first child's top margin collapses THROUGH body and moves body's box down
+  // without making it taller (the same holds at the bottom), so the page was
+  // cut short by those margins. Not documentElement.scrollHeight either: it
+  // never reports less than the frame's own viewport, so the frame could grow
+  // but never shrink back, and an html{height:100%} page would pin it at
+  // whatever height it had. Instead body's box is placed in document
+  // coordinates (its top already includes a collapsed top margin), and the
+  // bottom margins that can collapse through body's bottom edge are added by
+  // walking the last in-flow child chain. Nothing here reads the frame's own
+  // height, so the measure cannot feed back on itself.
+  function measureContentHeight() {
+    var body = document.body;
+    var scrollY = window.pageYOffset || 0;
+    var bodyRect = body.getBoundingClientRect();
+    var bottom = Math.max(bodyRect.bottom, bodyRect.top + (body.clientTop || 0) + body.scrollHeight) + scrollY;
+    var el = body;
+    for (var depth = 0; el && depth < 64; depth++) {
+      var cs = window.getComputedStyle(el);
+      var marginBottom = parseFloat(cs.marginBottom) || 0;
+      if (marginBottom > 0) bottom = Math.max(bottom, el.getBoundingClientRect().bottom + scrollY + marginBottom);
+      // A child's bottom margin only collapses through a plain block parent
+      // with no bottom padding or border that does not clip (flex/grid
+      // containers, flow-root and scroll containers keep it inside).
+      if (cs.display !== 'block' && cs.display !== 'list-item') break;
+      if (cs.overflowY && cs.overflowY !== 'visible') break;
+      if ((parseFloat(cs.paddingBottom) || 0) > 0 || (parseFloat(cs.borderBottomWidth) || 0) > 0) break;
+      el = lastInFlowChild(el);
+    }
+    var rootStyle = window.getComputedStyle(document.documentElement);
+    bottom += (parseFloat(rootStyle.paddingBottom) || 0) + (parseFloat(rootStyle.borderBottomWidth) || 0);
+    return Math.max(0, Math.ceil(bottom));
+  }
+
+  // Feedback guard. Content sized by the frame itself (html,body{height:100%},
+  // min-height:100vh, a 100vh section) plus anything around it (a collapsed
+  // margin, body's own margin) always measures taller than the frame, so every
+  // grow would ask for another: the frame would grow forever. The first
+  // measure after the parent applied a GROW we asked for decides: if the page
+  // still overflows by at least as much as it did before the grow, it grew
+  // with the frame, and the frame stays where it is. Later content changes
+  // post as usual (and re-run the check on their own grow). Pure, so the
+  // test can drive it: returns the height to post, or null for none.
+  function nextResizeHeight(state, h, viewport) {
+    var applied = state.awaiting && Math.abs(viewport - state.last) <= 1;
+    if (applied) state.awaiting = false;
+    if (h === state.last) return null;
+    if (applied && state.excess > 0 && h > viewport && h - viewport >= state.excess - 1) {
+      state.last = h; // held: report nothing until the content measures differently
+      return null;
+    }
+    state.excess = h - viewport;
+    state.awaiting = true;
+    state.last = h;
+    return h;
+  }
+
+  var resizeState = { last: 0, excess: 0, awaiting: false };
   function postResize() {
     if (LIVE) return; // live surfaces render full-viewport; the parent ignores height
     if (!document.body) return;
-    var h = document.body.scrollHeight;
-    if (h !== lastHeight) {
-      lastHeight = h;
-      postToParent({ type: PREFIX + 'resize', height: h });
-    }
+    var h = nextResizeHeight(resizeState, measureContentHeight(), window.innerHeight);
+    if (h !== null) postToParent({ type: PREFIX + 'resize', height: h });
   }
   window.addEventListener('load', postResize);
+  // The frame resizing is what tells the guard its last grow was applied.
+  window.addEventListener('resize', postResize, { passive: true });
 
   // --- Selection ---
   var pendingSelection = null;
@@ -1144,6 +1216,10 @@ export const BRIDGE_SCRIPT = `(function() {
 
   // Floating label naming the element under the cursor (like the markdown overlay).
   var PINPOINT_LABELS = { H1:'Heading', H2:'Heading', H3:'Heading', H4:'Heading', H5:'Heading', H6:'Heading', P:'Paragraph', UL:'List', OL:'List', LI:'List item', A:'Link', BUTTON:'Button', IMG:'Image', TABLE:'Table', THEAD:'Table', TBODY:'Table', TR:'Row', TD:'Cell', TH:'Header cell', SECTION:'Section', NAV:'Navigation', HEADER:'Header', FOOTER:'Footer', ARTICLE:'Article', ASIDE:'Sidebar', BLOCKQUOTE:'Quote', PRE:'Code', CODE:'Code', FIGURE:'Figure', FIGCAPTION:'Caption', MAIN:'Main', FORM:'Form', INPUT:'Input', LABEL:'Label' };
+  // Media kinds name themselves only when the page gives no accessible name:
+  // unlike the semantic tags above, an aria-label on a <video> is a better
+  // label than "Video", and it keeps winning exactly as it did before.
+  var MEDIA_PINPOINT_LABELS = { VIDEO:'Video', AUDIO:'Audio', IFRAME:'Frame', CANVAS:'Canvas' };
 
   var MAX_HOVER_LABEL = 40;
   function truncateLabel(text) {
@@ -1179,6 +1255,8 @@ export const BRIDGE_SCRIPT = `(function() {
     if (known) return known;
     var aria = el.getAttribute && el.getAttribute('aria-label');
     if (aria && aria.trim()) return truncateLabel(aria.trim());
+    var media = MEDIA_PINPOINT_LABELS[el.tagName];
+    if (media) return media;
     var role = el.getAttribute && el.getAttribute('role');
     if (role && role.trim()) return truncateLabel(role.trim());
     var tokens = meaningfulClassTokens(el);
@@ -2844,6 +2922,25 @@ export const BRIDGE_SCRIPT = `(function() {
   function ctxScrubUrl(value) {
     var v = String(value).trim();
     if (/^javascript:/i.test(v)) return null;
+    // Srcdoc sessions serve a document's relative assets through the
+    // session's own asset route (/api/html-assets/<token>/<path>). The token
+    // means nothing outside this session; the path after it is the author's
+    // own, relative to the document, which is what an agent can find.
+    if (!LIVE) {
+      var asset = v.match(/^\\/api\\/html-assets\\/[^\\/?#]+\\/([^?#]*)/);
+      if (asset && asset[1]) {
+        // The route percent-encodes each segment; show the name the author
+        // wrote (jane doe.png, not jane%20doe.png). A malformed escape, or one
+        // that decodes to ? or # (which the query scrub below would cut), keeps
+        // the raw text.
+        var authored = asset[1];
+        try {
+          var decoded = decodeURIComponent(authored);
+          if (!/[?#]/.test(decoded)) authored = decoded;
+        } catch (ex) {}
+        v = authored + v.slice(asset[0].length);
+      }
+    }
     if (/^data:/i.test(v)) {
       var comma = v.indexOf(',');
       return (comma > 0 ? v.slice(0, Math.min(comma, 40)) : v.slice(0, 40)) + ',…';
@@ -3153,7 +3250,8 @@ export const BRIDGE_SCRIPT = `(function() {
   }
 
   // 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'];
+  // Mirrors ELEMENT_CONTEXT_SHED_ORDER in @plannotator/core/html-anchor.
+  var CTX_SHED_ORDER = ['outline', 'text', 'attrs', 'classes', 'path', 'heading', 'landmark', 'component', 'sourceName'];
 
   function buildElementContext(el, maxBytes) {
     if (!el || el.nodeType !== 1) return null;
@@ -3180,6 +3278,12 @@ export const BRIDGE_SCRIPT = `(function() {
       if (heading) context.heading = heading;
       var component = ctxComponent(el);
       if (component) context.component = component;
+      // The media file this element shows, resolved exactly as the composer
+      // quote resolves it (src, a lazy data-src, srcset, <picture>/<source>,
+      // poster; see descRawSource), so the exported heading can name the file
+      // even when the element has no usable src attribute.
+      var sourceName = descSourceName(el);
+      if (sourceName) context.sourceName = sourceName;
       if (LIVE) {
         context.page = { url: currentPageUrl() };
         var title = ctxCollapse(document.title, 200);
@@ -3292,11 +3396,95 @@ export const BRIDGE_SCRIPT = `(function() {
     }
   }
 
-  // Element text for an additional target: same capping and text-less
-  // description used by the primary element path in annotateElement.
+  // --- Text-less element descriptions ---
+  // A pinpoint on an element with no text quotes a description instead
+  // ("[element: …]"). The hover label alone ("Image") cannot tell one image
+  // from the next, so the description adds what identifies THIS element: its
+  // accessible name (aria-label, alt, title, ...) and, for media, the source
+  // file name. The source goes through the same scrub the element context
+  // uses (no query, no fragment, data: reduced to its media type). Square
+  // brackets become parentheses and double quotes single ones, so the whole
+  // description stays one "[element: …]" token the export recognizes.
+  var DESC_MAX_NAME = 80;
+  var DESC_MAX_FILE = 60;
+  var DESC_SRC_ATTR = { IMG: 'src', VIDEO: 'src', AUDIO: 'src', IFRAME: 'src', EMBED: 'src', SOURCE: 'src', TRACK: 'src', INPUT: 'src', OBJECT: 'data' };
+
+  function descClean(value, max) {
+    return ctxCollapse(String(value).replace(/\\[/g, '(').replace(/\\]/g, ')').replace(/"/g, "'"), max);
+  }
+
+  // Candidates are comma-separated ("a.png, b.png 2x"); the URL is the
+  // first candidate's first word. A data: URL carries its own comma, so it is
+  // taken up to whitespace instead.
+  function descFirstSrcsetUrl(value) {
+    var srcset = String(value || '').trim();
+    if (!srcset) return '';
+    return (/^data:/i.test(srcset) ? srcset : srcset.split(',')[0]).trim().split(/\\s+/)[0] || '';
+  }
+
+  function descRawSource(el) {
+    var tag = el.tagName;
+    if (tag === 'INPUT' && String(el.getAttribute('type') || '').toLowerCase() !== 'image') return '';
+    var attr = DESC_SRC_ATTR[tag];
+    var src = '';
+    if (attr) src = (el.getAttribute(attr) || '').trim();
+    else if (el.ownerSVGElement && tag.toLowerCase() === 'image') src = (el.getAttribute('href') || el.getAttribute('xlink:href') || '').trim();
+    else return '';
+    // Lazy loaders put a data: placeholder in src and the real file in data-src.
+    var lazy = (el.getAttribute('data-src') || '').trim();
+    if (lazy && (!src || /^data:/i.test(src))) src = lazy;
+    if (!src && tag === 'IMG') {
+      src = descFirstSrcsetUrl(el.getAttribute('srcset'));
+      // <picture><source srcset="…"><img></picture>: the img itself may carry
+      // no source at all; the first <source> candidate names the file.
+      var picture = el.parentElement;
+      if (!src && picture && picture.tagName === 'PICTURE' && picture.querySelector) {
+        var pictureSource = picture.querySelector('source[srcset]');
+        if (pictureSource) src = descFirstSrcsetUrl(pictureSource.getAttribute('srcset'));
+      }
+    }
+    if (!src && (tag === 'VIDEO' || tag === 'AUDIO')) {
+      var child = el.querySelector && el.querySelector('source[src]');
+      if (child) src = (child.getAttribute('src') || '').trim();
+      if (!src && tag === 'VIDEO') src = (el.getAttribute('poster') || '').trim();
+    }
+    return src;
+  }
+
+  // The file name a source points at: "team.jpg" for
+  // https://cdn.test/img/team.jpg?sig=…, "data:image/png" for an inline image.
+  function descSourceName(el) {
+    var src = descRawSource(el);
+    if (!src) return '';
+    var scrubbed = ctxScrubUrl(src);
+    if (!scrubbed) return '';
+    if (/^data:/i.test(scrubbed)) {
+      var media = scrubbed.slice(5).split(/[;,]/)[0];
+      return descClean('data:' + (media || 'unknown'), DESC_MAX_FILE);
+    }
+    if (/^blob:/i.test(scrubbed)) return 'blob';
+    var path = scrubbed.replace(/\\?…$/, '').replace(/\\/+$/, '');
+    var name = path.slice(path.lastIndexOf('/') + 1);
+    try { name = decodeURIComponent(name); } catch (ex) {}
+    if (!name || /^[a-z][a-z0-9+.-]*:$/i.test(name)) name = path;
+    return descClean(name, DESC_MAX_FILE);
+  }
+
+  function describeTextlessElement(el, label) {
+    var out = descClean(label, DESC_MAX_NAME) || 'element';
+    var name = ctxName(el);
+    name = name ? descClean(name, DESC_MAX_NAME) : '';
+    if (name && name !== out) out += ' "' + name + '"';
+    var file = descSourceName(el);
+    if (file && file !== name) out += ' (' + file + ')';
+    return out;
+  }
+
+  // Element text for a pinpoint target (primary or additional): the
+  // element's own text, or for a text-less element its description.
   function elementTargetText(el, label) {
     var text = capSelectionText((el.textContent || '').trim());
-    if (!text) text = capSelectionText('[element: ' + label + ']');
+    if (!text) text = capSelectionText('[element: ' + describeTextlessElement(el, label) + ']');
     return text;
   }
 
@@ -3535,10 +3723,10 @@ export const BRIDGE_SCRIPT = `(function() {
       if (!posted) clearPendingPin();
       return posted;
     }
-    var elText = capSelectionText((el.textContent || '').trim());
-    // Text-less elements (icon buttons, decorative chips, empty containers)
-    // are still annotatable: describe the element instead of quoting it.
-    if (!elText) elText = capSelectionText('[element: ' + pinpointHoverLabel(el) + ']');
+    // Text-less elements (images, icon buttons, decorative chips, empty
+    // containers) are still annotatable: describe the element instead of
+    // quoting it, naming WHICH one it is where the page says so.
+    var elText = elementTargetText(el, pinpointHoverLabel(el));
     var r = el.getBoundingClientRect();
     pendingSelection = { element: true };
     pendingRange = null;
@@ -5134,11 +5322,16 @@ export const BRIDGE_SCRIPT = `(function() {
 
   function onReady() {
     if (typeof ResizeObserver !== 'undefined' && document.body) {
-      new ResizeObserver(function() {
+      var resizeObserver = new ResizeObserver(function() {
         postResize();
         scheduleVimUiUpdate();
         schedulePinpointReconcile();
-      }).observe(document.body);
+      });
+      resizeObserver.observe(document.body);
+      // A collapsed margin changing moves body without resizing it; the root
+      // box does resize then. (An html{height:100%} root resizes with the
+      // frame instead, which re-measures the same height and posts nothing.)
+      resizeObserver.observe(document.documentElement);
     }
     watchPageMutations();
     // Armed is the default on both surfaces, and live sessions default to