@plannotator/ui 0.50.0 → 0.51.0

package/components/diagram/DiagramViewer.tsx

@@ -1,5 +1,5 @@
 import { lazy, Suspense, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
-import type { DiagramKind } from '@plannotator/core/diagram-anchor';
+import { buildDiagramAnchorValue, type DiagramAnchor, type DiagramKind, type DiagramTarget } from '@plannotator/core/diagram-anchor';
 import { cn } from '../../lib/utils';
 import { diagramFamilyOf } from '../../utils/diagram-anchor';
 import { diagramFinder, type DiagramTheme } from '../../utils/diagram-render';
@@ -33,6 +33,16 @@ const DiagramSourcePane = lazy(async () => ({ default: (await import('./DiagramS
  * Never `null` here — that would collapse the row back onto the canvas. */
 const PANE_CLASS = 'order-last min-h-0 shrink-0 basis-2/5 border-t border-border md:order-first md:w-80 md:basis-auto md:border-r md:border-t-0';
 
+/** A question typed in the composer, asked about the part instead of saved
+ * as a comment. The anchor is the one a comment there would carry (its
+ * `sourceLine` already in document lines). Resolve false (or throw) to keep
+ * the draft open; anything else closes it. */
+export type DiagramAskAI = (
+  question: string,
+  anchor: DiagramAnchor,
+  additionalTargets: readonly DiagramTarget[],
+) => boolean | void | Promise<boolean | void>;
+
 export interface DiagramViewerProps {
   readonly kind: DiagramKind;
   /** The diagram text. With `onSave` this is the saved baseline the pane's
@@ -42,6 +52,8 @@ export interface DiagramViewerProps {
   readonly comments: readonly DiagramComment[];
   /** A comment composed on a part. Absent: clicks open nothing. */
   readonly onCreateComment?: DiagramCreateComment;
+  /** Ask AI from the composer. Absent: the composer offers no Ask AI. */
+  readonly onAskAI?: DiagramAskAI;
   /** Save the pane's text. Absent: there is no Source pane. */
   readonly onSave?: (source: string) => Promise<SaveResult>;
   /** With `onSave`: show the pane read-only (no edit access). */
@@ -92,6 +104,7 @@ export function DiagramViewer({
   theme,
   comments,
   onCreateComment,
+  onAskAI,
   onSave,
   readOnlySource = false,
   sourceOpen = false,
@@ -177,6 +190,21 @@ export function DiagramViewer({
     if (!sourceOpen) cancelComposer();
   }, [cancelComposer, sourceOpen]);
 
+  // Ask AI asks about the part the draft is on; the host's handler decides
+  // whether the question was taken, and a taken question closes the draft
+  // exactly as the markdown composer closes.
+  const composerDraft = commentsState.composer;
+  const askFromComposer = useMemo(() => {
+    if (onAskAI === undefined || composerDraft === null || onCreateComment === undefined) return undefined;
+    return async (question: string): Promise<boolean> => {
+      const anchor = buildDiagramAnchorValue(composerDraft.primary.target, composerDraft.sourceLine);
+      const accepted = await onAskAI(question, anchor, composerDraft.additional.map((extra) => extra.target));
+      if (accepted === false) return false;
+      cancelComposer();
+      return true;
+    };
+  }, [cancelComposer, composerDraft, onAskAI, onCreateComment]);
+
   const overlay = useCallback(
     (handle: DiagramCanvasHandle) => (
       <DiagramOverlay
@@ -199,12 +227,13 @@ export function DiagramViewer({
               disabledReason={commentingDisabledReason}
               onSubmit={(text) => void commentsState.submit(text)}
               onCancel={commentsState.cancel}
+              onAskAI={askFromComposer}
             />
           )
         }
       />
     ),
-    [commentingDisabledReason, commentsState, onSelectComment, selectedCommentId, sourceDirty],
+    [askFromComposer, commentingDisabledReason, commentsState, onSelectComment, selectedCommentId, sourceDirty],
   );
 
   const showFallback = render.svgNode === null;

package/components/diagram/index.ts

@@ -6,7 +6,7 @@
  * `graphviz`, `mermaid`, `diagram-anchor`, `diagram-anchor-graphviz`,
  * `diagram-projection`).
  */
-export { DiagramViewer, type DiagramViewerProps } from './DiagramViewer';
+export { DiagramViewer, type DiagramAskAI, type DiagramViewerProps } from './DiagramViewer';
 export { DiagramPopout } from './DiagramPopout';
 export { DiagramPending, DiagramInlineSource, DiagramBlockPending } from './DiagramPending';
 export { isDiagramControlEvent, DIAGRAM_CONTROL_SELECTOR } from './diagramControls';

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

@@ -980,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) {
@@ -1015,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);
@@ -2680,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)) + ',…';
@@ -2989,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;
@@ -3016,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);
@@ -3128,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;
   }
 
@@ -3371,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;

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

@@ -1216,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) {
@@ -1251,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);
@@ -2916,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)) + ',…';
@@ -3225,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;
@@ -3252,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);
@@ -3364,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;
   }
 
@@ -3607,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;

package/components/html-viewer/useHtmlAnnotation.ts

@@ -477,8 +477,8 @@ export function useHtmlAnnotation({
   flashDraftTarget: (key: string) => void;
   /** Bumped after every target add/remove so the composer can refocus its textarea. */
   composerFocusToken: number;
-  /** Composer one-click "Looks good": submits the hardcoded positive label
-   *  with the same anchor and multi-select targets a typed comment would carry. */
+  /** Composer one-click 👍: submits the hardcoded positive label with the
+   *  same anchor and multi-select targets a typed comment would carry. */
   handleCommentLooksGood: () => void;
   /** Ids this module minted for locally created annotations (create-mark),
    *  for the unanchored union: a minted id the host never listed is a
@@ -910,8 +910,14 @@ export function useHtmlAnnotation({
     [getOrCreateAnchor],
   );
 
-  const handleCommentSubmit = useCallback(
-    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
+  // One commit path for everything the pinpoint composer submits (a typed
+  // comment or the one-click 👍), so both carry the same anchor, element
+  // context and multi-select targets.
+  const commitComposerDraft = useCallback(
+    (
+      body: Pick<Annotation, "text"> &
+        Partial<Pick<Annotation, "images" | "mentions" | "isQuickLabel" | "quickLabelTip">>,
+    ) => {
       if (!enabledRef.current) return;
       // Prefer the text captured when the popover opened — it can't be clobbered by
       // a later selection change or clear while the user is composing the comment.
@@ -939,14 +945,10 @@ export function useHtmlAnnotation({
         startOffset: 0,
         endOffset: 0,
         type: AnnotationType.COMMENT,
-        text: comment,
         originalText: text,
         author: getIdentity(),
         createdA: Date.now(),
-        images,
-        // Host capability: present only when a mentionSource was supplied AND
-        // a token survived, so a comment without one is unchanged.
-        ...(mentions && mentions.length > 0 ? { mentions } : {}),
+        ...body,
         htmlAnchor: pendingAnchorRef.current ?? undefined,
         elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,
@@ -961,53 +963,32 @@ export function useHtmlAnnotation({
     [post],
   );
 
-  // The composer's one-click "Looks good" (the restored thumbs-up for
-  // comment-only surfaces, where pinpoint clicks land straight in the
-  // composer and never see the selection toolbar). Mirrors
-  // handleCommentSubmit — same anchor, same multi-select targets — but
-  // emits the hardcoded positive label instead of typed prose.
-  const handleCommentLooksGood = useCallback(() => {
-    if (!enabledRef.current) return;
-    const text = commentPopoverRef.current?.selectedText || pendingTextRef.current;
-    if (!text) return;
-
-    const targets = draftTargetsRef.current;
-    const additionalTargets: HtmlAnnotationTarget[] | undefined =
-      targets.length > 1
-        ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
-            label: t.label,
-            text: t.text,
-            anchor: t.anchor ?? undefined,
-            ...(t.context ? { context: t.context } : {}),
-          }))
-        : undefined;
-
-    const id = nextHtmlAnnId();
-    mintedIdsRef.current.add(id);
-    post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
-    onAddRef.current?.({
-      id,
-      blockId: "",
-      startOffset: 0,
-      endOffset: 0,
-      type: AnnotationType.COMMENT,
-      text: THUMBS_UP_LABEL.text,
-      originalText: text,
-      isQuickLabel: true,
-      quickLabelTip: THUMBS_UP_LABEL.tip,
-      author: getIdentity(),
-      createdA: Date.now(),
-      htmlAnchor: pendingAnchorRef.current ?? undefined,
-      elementContext: pendingContextRef.current ?? undefined,
-      htmlAdditionalTargets: additionalTargets,
-    });
+  const handleCommentSubmit = useCallback(
+    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) =>
+      commitComposerDraft({
+        text: comment,
+        images,
+        // Host capability: present only when a mentionSource was supplied AND
+        // a token survived, so a comment without one is unchanged.
+        ...(mentions && mentions.length > 0 ? { mentions } : {}),
+      }),
+    [commitComposerDraft],
+  );
 
-    setCommentPopover(null);
-    setDraftTargets([]);
-    pendingTextRef.current = "";
-    pendingAnchorRef.current = null;
-    pendingContextRef.current = null;
-  }, [post]);
+  // The composer's one-click 👍. A pinpoint click opens this composer
+  // directly and never shows the selection toolbar, so without it a reviewer
+  // could not mark an element "looks good" in one click. Emits the same
+  // hardcoded positive label as the toolbar's 👍 (the only label comment-only
+  // surfaces may create), on the pinned element(s).
+  const handleCommentLooksGood = useCallback(
+    () =>
+      commitComposerDraft({
+        text: THUMBS_UP_LABEL.text,
+        isQuickLabel: true,
+        quickLabelTip: THUMBS_UP_LABEL.tip,
+      }),
+    [commitComposerDraft],
+  );
 
   const handleCommentClose = useCallback(() => {
     post({ type: `${PREFIX}cancel-selection` });