@plannotator/ui 0.40.0 → 0.41.0

package/components/diagram/useDiagramViewport.ts

@@ -0,0 +1,156 @@
+import { useCallback, useEffect, useRef, useState, type RefObject } from 'react';
+import type { ScreenRect } from '../../utils/diagram-projection';
+
+/**
+ * The canvas viewport: a translate plus a scale on the wrapper around the
+ * rendered svg (zoom, pan and fit are the primary interaction). Every
+ * constant below is a design constant with its reason, never a cap on what
+ * a person may do with the diagram.
+ */
+
+/** Zoom range. Below 0.1 a 1000px diagram is a 100px smudge and the rings
+ * collapse onto each other; above 8 a node label is a screenful. The
+ * range keeps the render legible and the transform finite. */
+export const ZOOM_MIN = 0.1;
+export const ZOOM_MAX = 8;
+/** One key press or one corner-control click. 1.25 needs four presses to
+ * double, which is fine-grained enough to land on a node. */
+export const ZOOM_STEP = 1.25;
+/** Wheel zoom: factor = exp(-deltaY * sensitivity). One 100px notch is
+ * about 1.22x, close to ZOOM_STEP so keys and wheel feel the same. */
+export const WHEEL_ZOOM_SENSITIVITY = 0.002;
+/** The distance a pointer must travel before a press becomes a pan. Under
+ * it, releasing is a click on the part beneath (the pinpoint). */
+export const DRAG_THRESHOLD_PX = 4;
+/** The same threshold for a finger, which wobbles more than a mouse: a tap
+ * that drifts a few pixels must still be a tap. */
+export const TOUCH_DRAG_THRESHOLD_PX = 10;
+/** Fit leaves this much air on every side of the host so the outermost
+ * node and its ring never touch the edge; the badge (a 20px disc at the
+ * node's top-right corner) stays inside it. */
+export const FIT_PADDING_PX = 24;
+
+export interface Viewport {
+  readonly x: number;
+  readonly y: number;
+  readonly scale: number;
+}
+
+export interface ContentSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+const IDENTITY: Viewport = { x: 0, y: 0, scale: 1 };
+
+function clampScale(scale: number): number {
+  return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, scale));
+}
+
+export function useDiagramViewport(
+  hostRef: RefObject<HTMLElement | null>,
+  content: ContentSize | null,
+): {
+  readonly viewport: Viewport;
+  readonly fit: () => void;
+  readonly zoomBy: (factor: number, clientX?: number, clientY?: number) => void;
+  readonly panBy: (dx: number, dy: number) => void;
+  readonly panIntoView: (rect: ScreenRect) => void;
+} {
+  const [viewport, setViewport] = useState<Viewport>(IDENTITY);
+  const contentRef = useRef(content);
+  contentRef.current = content;
+  // Whether the person zoomed or panned since the last fit. While true, a
+  // new render (the draft preview) or a host resize (the Source pane
+  // opening, the window) keeps their view; a fit (the key, the control, a
+  // first arrival) clears it.
+  const adjustedRef = useRef(false);
+
+  const fit = useCallback(() => {
+    const host = hostRef.current;
+    const size = contentRef.current;
+    if (host === null || size === null || size.width <= 0 || size.height <= 0) {
+      setViewport(IDENTITY);
+      return;
+    }
+    const rect = host.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) {
+      // No layout (a hidden tab, happy-dom): identity until a size arrives.
+      setViewport(IDENTITY);
+      return;
+    }
+    const availableWidth = Math.max(1, rect.width - FIT_PADDING_PX * 2);
+    const availableHeight = Math.max(1, rect.height - FIT_PADDING_PX * 2);
+    const scale = clampScale(Math.min(availableWidth / size.width, availableHeight / size.height));
+    adjustedRef.current = false;
+    setViewport({
+      x: (rect.width - size.width * scale) / 2,
+      y: (rect.height - size.height * scale) / 2,
+      scale,
+    });
+  }, [hostRef]);
+
+  // Fit on arrival and on every new content size (a first render, a
+  // re-render with a different bounding box) and on host resize (the
+  // Source pane opening, the window), unless the person has zoomed or
+  // panned since the last fit: then their view stands until they fit again.
+  useEffect(() => {
+    if (!adjustedRef.current) fit();
+    const host = hostRef.current;
+    if (host === null || typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(() => {
+      if (!adjustedRef.current) fit();
+    });
+    observer.observe(host);
+    return () => observer.disconnect();
+  }, [fit, hostRef, content]);
+
+  const zoomBy = useCallback(
+    (factor: number, clientX?: number, clientY?: number) => {
+      const host = hostRef.current;
+      adjustedRef.current = true;
+      setViewport((current) => {
+        const scale = clampScale(current.scale * factor);
+        if (scale === current.scale) return current;
+        const rect = host?.getBoundingClientRect();
+        // Zoom about the pointer when given, else the host's center, so
+        // the part under the cursor stays under the cursor.
+        const px = clientX !== undefined && rect ? clientX - rect.left : (rect?.width ?? 0) / 2;
+        const py = clientY !== undefined && rect ? clientY - rect.top : (rect?.height ?? 0) / 2;
+        const ratio = scale / current.scale;
+        return {
+          x: px - (px - current.x) * ratio,
+          y: py - (py - current.y) * ratio,
+          scale,
+        };
+      });
+    },
+    [hostRef],
+  );
+
+  const panBy = useCallback((dx: number, dy: number) => {
+    adjustedRef.current = true;
+    setViewport((current) => ({ ...current, x: current.x + dx, y: current.y + dy }));
+  }, []);
+
+  const panIntoView = useCallback(
+    (target: ScreenRect) => {
+      const host = hostRef.current;
+      if (host === null) return;
+      const rect = host.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return;
+      const inside =
+        target.left >= 0 &&
+        target.top >= 0 &&
+        target.left + target.width <= rect.width &&
+        target.top + target.height <= rect.height;
+      if (inside) return;
+      const dx = rect.width / 2 - (target.left + target.width / 2);
+      const dy = rect.height / 2 - (target.top + target.height / 2);
+      setViewport((current) => ({ ...current, x: current.x + dx, y: current.y + dy }));
+    },
+    [hostRef],
+  );
+
+  return { viewport, fit, zoomBy, panBy, panIntoView };
+}

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

@@ -157,8 +157,10 @@
     if (!document.body) return;
     if (annotateModeActive && currentInputMethod === 'pinpoint') {
       document.body.setAttribute('data-plannotator-pinpoint-cursor', '');
+      if (!LIVE) document.body.setAttribute('data-plannotator-frame-inert', '');
     } else {
       document.body.removeAttribute('data-plannotator-pinpoint-cursor');
+      document.body.removeAttribute('data-plannotator-frame-inert');
     }
   }
   var pinpointHover = null;
@@ -688,11 +690,34 @@
       var svgGroup = node.closest('g');
       if (svgGroup) node = svgGroup;
     }
+    node = preferInertFrameAt(node, x, y);
     node = promoteTinyTarget(node);
     if (node === document.body || node === document.documentElement) return null;
     return node;
   }
 
+  // While frames are pointer-transparent (armed pinpoint, srcdoc sessions),
+  // hit-testing passes THROUGH an embedded document to the container painted
+  // behind it — so a click on an embed would pin its wrapper div. The embed is
+  // what the reviewer is pointing at and what the anchor must name, so a point
+  // inside a frame's own rect resolves to that frame. Bounded to the frames
+  // inside the element already resolved, so it costs nothing on ordinary pages.
+  var FRAME_SELECTOR = 'iframe,frame,embed,object';
+  function framesArePointerInert() {
+    return !LIVE && annotateModeActive && currentInputMethod === 'pinpoint';
+  }
+  function preferInertFrameAt(node, x, y) {
+    if (!framesArePointerInert() || !node.querySelectorAll) return node;
+    if (node.matches && node.matches(FRAME_SELECTOR)) return node;
+    var frames = node.querySelectorAll(FRAME_SELECTOR);
+    for (var i = 0; i < frames.length && i < 64; i++) {
+      var r = frames[i].getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) continue;
+      if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return frames[i];
+    }
+    return node;
+  }
+
   // Last-position reuse: a pointer that moved under 2px within 16ms resolves
   // to the cached element instead of re-hit-testing. The scroll reconcile
   // invalidates this cache — same point, different element after a scroll.

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

@@ -3,7 +3,7 @@
 // annotation CSS, protocol version and live bootstrap as ./bridge-script, with
 // the inline bridge literal stubbed out so a bundler drops it from the viewer
 // chunk. Rendering an HtmlViewer WITHOUT bridgeScriptUrl under this alias throws.
-export const ANNOTATION_HIGHLIGHT_CSS = "\n/* Committed annotation visuals (highlight rectangles + numbered placed\n * markers) render inside a shadow-rooted fixed overlay host — see OVERLAY_CSS\n * in the bridge script. Nothing annotation-related is ever wrapped into or\n * styled onto the author's own elements. */\n/* Vim pinpoint target tint. The MOUSE pinpoint path no longer mutates author\n * elements — it draws the dedicated overlay box below — but keyboard (vim)\n * navigation keeps this class-based visual. */\n.plannotator-pinpoint-hover {\n  background-color: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.12) !important;\n  border-radius: 3px;\n  cursor: pointer !important;\n}\n/* SVG groups can't render a CSS background, so use a soft glow instead. */\n.plannotator-pinpoint-hover:is(g, svg) {\n  filter: drop-shadow(0 0 4px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.55));\n}\n/* Mouse pinpoint hover: a fixed-position outline box sized to the hovered\n * element's rect. Never a class/style write on the page's own elements. */\n[data-plannotator-pinpoint-box] {\n  position: fixed;\n  z-index: 2147483643;\n  pointer-events: none;\n  display: none;\n  box-sizing: border-box;\n  border: 2px solid oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.85);\n  border-radius: 5px;\n  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.06);\n}\n[data-plannotator-pinpoint-box].pn-pin-enter {\n  animation: pn-pinpoint-in 0.12s ease-out;\n}\n[data-plannotator-pinpoint-box][data-pinned] {\n  border-color: var(--pn-accent, #d97757);\n  background: oklch(from var(--pn-accent, #d97757) l c h / 0.08);\n}\n@keyframes pn-pinpoint-in {\n  from { opacity: 0; transform: scale(0.985); }\n  to { opacity: 1; transform: scale(1); }\n}\n/* Pinpoint mode affordance: crosshair everywhere. Placed markers live in the\n * shadow overlay and keep their own pointer cursor there. */\nbody[data-plannotator-pinpoint-cursor],\nbody[data-plannotator-pinpoint-cursor] * {\n  cursor: crosshair !important;\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-pinpoint-box].pn-pin-enter {\n    animation: none;\n  }\n}\n@media print {\n  /* Viewer overlays are review chrome, not page content: never bake pinpoint\n     boxes/labels or vim UI into a printed page. The outer app chrome is\n     print-hidden by print.css, but this CSS lives inside the iframe's own\n     document and must carry its own rule. The annotation overlay host carries\n     its own print rule inside its shadow root. */\n  [data-plannotator-pinpoint-box],\n  [data-plannotator-pinpoint-label],\n  [data-plannotator-vim-ui],\n  [data-plannotator-vim-cursor] {\n    display: none !important;\n  }\n}\n/* Print-parity layer: committed highlight rects re-projected into an\n * absolute-positioned light-DOM layer built on beforeprint and torn down on\n * afterprint (the fixed overlay cannot paginate). Guarded here so it can\n * never flash on screen even if an afterprint teardown is missed. */\n@media screen {\n  [data-plannotator-print-layer] {\n    display: none !important;\n  }\n}\nbody[data-plannotator-vim-focus-owner]:focus {\n  outline: none !important;\n}\n[data-plannotator-vim-cursor] {\n  position: fixed;\n  z-index: 2147483646;\n  width: 2px;\n  min-height: 1em;\n  border-radius: 2px;\n  background: var(--pn-focus-highlight, #4493f8);\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] {\n  position: fixed;\n  z-index: 2147483645;\n  inset: 0;\n  overflow: visible;\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill],\n[data-plannotator-vim-reticle] [data-vim-reticle-corner],\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  position: absolute;\n  top: 0;\n  left: 0;\n  will-change: transform;\n  transition: transform 90ms cubic-bezier(.22,1,.36,1);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill] {\n  width: 100px;\n  height: 100px;\n  transform-origin: 0 0;\n  border-radius: 8px;\n  background: rgba(167,139,250,.045);\n  box-shadow:\n    inset 0 0 0 1px rgba(196,181,253,.16),\n    0 0 42px rgba(139,92,246,.12);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner] {\n  width: 28px;\n  height: 28px;\n  border-color: #c4b5fd;\n  filter:\n    drop-shadow(0 0 6px rgba(167,139,250,.92))\n    drop-shadow(0 0 18px rgba(124,58,237,.42));\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-left\"] {\n  border-top: 3px solid;\n  border-left: 3px solid;\n  border-top-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-right\"] {\n  border-top: 3px solid;\n  border-right: 3px solid;\n  border-top-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-left\"] {\n  border-bottom: 3px solid;\n  border-left: 3px solid;\n  border-bottom-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-right\"] {\n  border-right: 3px solid;\n  border-bottom: 3px solid;\n  border-bottom-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  z-index: 1;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-width: 118px;\n  height: 30px;\n  max-width: min(280px, calc(100vw - 24px));\n  padding: 0 11px;\n  overflow: hidden;\n  border: 1px solid rgba(216,206,255,.42);\n  border-radius: 9px;\n  color: #f6f2ff;\n  background: rgba(18,14,28,.84);\n  box-shadow:\n    0 10px 28px rgba(0,0,0,.42),\n    0 0 20px rgba(139,92,246,.18);\n  backdrop-filter: blur(10px);\n  font: 700 10px/1 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .13em;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label]::before {\n  width: 7px;\n  height: 7px;\n  flex: 0 0 auto;\n  border-radius: 999px;\n  background: #c4b5fd;\n  box-shadow: 0 0 12px rgba(167,139,250,.94);\n  content: \"\";\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-vim-reticle] [data-vim-reticle-fill],\n  [data-plannotator-vim-reticle] [data-vim-reticle-corner],\n  [data-plannotator-vim-reticle] [data-vim-reticle-label] {\n    transition: none;\n  }\n}\n[data-plannotator-vim-badge] {\n  position: fixed;\n  z-index: 2147483647;\n  left: 50%;\n  bottom: 12px;\n  transform: translateX(-50%);\n  padding: 4px 9px;\n  border: 1px solid color-mix(in srgb, var(--pn-focus-highlight, #4493f8) 35%, transparent);\n  border-radius: 6px;\n  background: color-mix(in srgb, var(--pn-background, #111) 94%, transparent);\n  color: var(--pn-focus-highlight, #4493f8);\n  box-shadow: 0 4px 18px rgba(0,0,0,.25);\n  font: 700 10px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .04em;\n  pointer-events: none;\n}\n";
+export const ANNOTATION_HIGHLIGHT_CSS = "\n/* Committed annotation visuals (highlight rectangles + numbered placed\n * markers) render inside a shadow-rooted fixed overlay host — see OVERLAY_CSS\n * in the bridge script. Nothing annotation-related is ever wrapped into or\n * styled onto the author's own elements. */\n/* Vim pinpoint target tint. The MOUSE pinpoint path no longer mutates author\n * elements — it draws the dedicated overlay box below — but keyboard (vim)\n * navigation keeps this class-based visual. */\n.plannotator-pinpoint-hover {\n  background-color: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.12) !important;\n  border-radius: 3px;\n  cursor: pointer !important;\n}\n/* SVG groups can't render a CSS background, so use a soft glow instead. */\n.plannotator-pinpoint-hover:is(g, svg) {\n  filter: drop-shadow(0 0 4px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.55));\n}\n/* Mouse pinpoint hover: a fixed-position outline box sized to the hovered\n * element's rect. Never a class/style write on the page's own elements. */\n[data-plannotator-pinpoint-box] {\n  position: fixed;\n  z-index: 2147483643;\n  pointer-events: none;\n  display: none;\n  box-sizing: border-box;\n  border: 2px solid oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.85);\n  border-radius: 5px;\n  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.06);\n}\n[data-plannotator-pinpoint-box].pn-pin-enter {\n  animation: pn-pinpoint-in 0.12s ease-out;\n}\n[data-plannotator-pinpoint-box][data-pinned] {\n  border-color: var(--pn-accent, #d97757);\n  background: oklch(from var(--pn-accent, #d97757) l c h / 0.08);\n}\n@keyframes pn-pinpoint-in {\n  from { opacity: 0; transform: scale(0.985); }\n  to { opacity: 1; transform: scale(1); }\n}\n/* Pinpoint mode affordance: crosshair everywhere. Placed markers live in the\n * shadow overlay and keep their own pointer cursor there. */\nbody[data-plannotator-pinpoint-cursor],\nbody[data-plannotator-pinpoint-cursor] * {\n  cursor: crosshair !important;\n}\n/* Armed pinpoint over an EMBEDDED local document: the embed is one element\n * from the outer page's point of view, and the bridge is never injected into a\n * nested frame, so a click inside it would simply vanish into another document.\n * Making frames transparent to the pointer while armed is what lets that click\n * pin the <iframe>/<embed>/<object> itself. Interact (Esc, the header pen or\n * Mod+Shift+A) restores native interaction inside the embed — which is also\n * the only state a link inside it can be followed from.\n * Live-app sessions never set this attribute: they annotate a real app whose\n * own nested frames belong to it. */\nbody[data-plannotator-frame-inert] :is(iframe, frame, embed, object) {\n  pointer-events: none !important;\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-pinpoint-box].pn-pin-enter {\n    animation: none;\n  }\n}\n@media print {\n  /* Viewer overlays are review chrome, not page content: never bake pinpoint\n     boxes/labels or vim UI into a printed page. The outer app chrome is\n     print-hidden by print.css, but this CSS lives inside the iframe's own\n     document and must carry its own rule. The annotation overlay host carries\n     its own print rule inside its shadow root. */\n  [data-plannotator-pinpoint-box],\n  [data-plannotator-pinpoint-label],\n  [data-plannotator-vim-ui],\n  [data-plannotator-vim-cursor] {\n    display: none !important;\n  }\n}\n/* Print-parity layer: committed highlight rects re-projected into an\n * absolute-positioned light-DOM layer built on beforeprint and torn down on\n * afterprint (the fixed overlay cannot paginate). Guarded here so it can\n * never flash on screen even if an afterprint teardown is missed. */\n@media screen {\n  [data-plannotator-print-layer] {\n    display: none !important;\n  }\n}\nbody[data-plannotator-vim-focus-owner]:focus {\n  outline: none !important;\n}\n[data-plannotator-vim-cursor] {\n  position: fixed;\n  z-index: 2147483646;\n  width: 2px;\n  min-height: 1em;\n  border-radius: 2px;\n  background: var(--pn-focus-highlight, #4493f8);\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] {\n  position: fixed;\n  z-index: 2147483645;\n  inset: 0;\n  overflow: visible;\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill],\n[data-plannotator-vim-reticle] [data-vim-reticle-corner],\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  position: absolute;\n  top: 0;\n  left: 0;\n  will-change: transform;\n  transition: transform 90ms cubic-bezier(.22,1,.36,1);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill] {\n  width: 100px;\n  height: 100px;\n  transform-origin: 0 0;\n  border-radius: 8px;\n  background: rgba(167,139,250,.045);\n  box-shadow:\n    inset 0 0 0 1px rgba(196,181,253,.16),\n    0 0 42px rgba(139,92,246,.12);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner] {\n  width: 28px;\n  height: 28px;\n  border-color: #c4b5fd;\n  filter:\n    drop-shadow(0 0 6px rgba(167,139,250,.92))\n    drop-shadow(0 0 18px rgba(124,58,237,.42));\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-left\"] {\n  border-top: 3px solid;\n  border-left: 3px solid;\n  border-top-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-right\"] {\n  border-top: 3px solid;\n  border-right: 3px solid;\n  border-top-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-left\"] {\n  border-bottom: 3px solid;\n  border-left: 3px solid;\n  border-bottom-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-right\"] {\n  border-right: 3px solid;\n  border-bottom: 3px solid;\n  border-bottom-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  z-index: 1;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-width: 118px;\n  height: 30px;\n  max-width: min(280px, calc(100vw - 24px));\n  padding: 0 11px;\n  overflow: hidden;\n  border: 1px solid rgba(216,206,255,.42);\n  border-radius: 9px;\n  color: #f6f2ff;\n  background: rgba(18,14,28,.84);\n  box-shadow:\n    0 10px 28px rgba(0,0,0,.42),\n    0 0 20px rgba(139,92,246,.18);\n  backdrop-filter: blur(10px);\n  font: 700 10px/1 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .13em;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label]::before {\n  width: 7px;\n  height: 7px;\n  flex: 0 0 auto;\n  border-radius: 999px;\n  background: #c4b5fd;\n  box-shadow: 0 0 12px rgba(167,139,250,.94);\n  content: \"\";\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-vim-reticle] [data-vim-reticle-fill],\n  [data-plannotator-vim-reticle] [data-vim-reticle-corner],\n  [data-plannotator-vim-reticle] [data-vim-reticle-label] {\n    transition: none;\n  }\n}\n[data-plannotator-vim-badge] {\n  position: fixed;\n  z-index: 2147483647;\n  left: 50%;\n  bottom: 12px;\n  transform: translateX(-50%);\n  padding: 4px 9px;\n  border: 1px solid color-mix(in srgb, var(--pn-focus-highlight, #4493f8) 35%, transparent);\n  border-radius: 6px;\n  background: color-mix(in srgb, var(--pn-background, #111) 94%, transparent);\n  color: var(--pn-focus-highlight, #4493f8);\n  box-shadow: 0 4px 18px rgba(0,0,0,.25);\n  font: 700 10px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .04em;\n  pointer-events: none;\n}\n";
 export const BRIDGE_PROTOCOL_VERSION = 1;
 export const BRIDGE_SCRIPT = "";
 export const LIVE_BRIDGE_BOOTSTRAP = "(function() {\n  var config = window.__plannotatorLiveConfig;\n  if (!config || typeof config.css !== 'string') return;\n  try {\n    var style = document.createElement('style');\n    style.setAttribute('data-plannotator-live-css', '');\n    style.appendChild(document.createTextNode(config.css));\n    (document.head || document.documentElement).appendChild(style);\n  } catch (ex) {}\n})();";

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

@@ -60,6 +60,18 @@ body[data-plannotator-pinpoint-cursor],
 body[data-plannotator-pinpoint-cursor] * {
   cursor: crosshair !important;
 }
+/* Armed pinpoint over an EMBEDDED local document: the embed is one element
+ * from the outer page's point of view, and the bridge is never injected into a
+ * nested frame, so a click inside it would simply vanish into another document.
+ * Making frames transparent to the pointer while armed is what lets that click
+ * pin the <iframe>/<embed>/<object> itself. Interact (Esc, the header pen or
+ * Mod+Shift+A) restores native interaction inside the embed — which is also
+ * the only state a link inside it can be followed from.
+ * Live-app sessions never set this attribute: they annotate a real app whose
+ * own nested frames belong to it. */
+body[data-plannotator-frame-inert] :is(iframe, frame, embed, object) {
+  pointer-events: none !important;
+}
 @media (prefers-reduced-motion: reduce) {
   [data-plannotator-pinpoint-box].pn-pin-enter {
     animation: none;
@@ -381,8 +393,10 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!document.body) return;
     if (annotateModeActive && currentInputMethod === 'pinpoint') {
       document.body.setAttribute('data-plannotator-pinpoint-cursor', '');
+      if (!LIVE) document.body.setAttribute('data-plannotator-frame-inert', '');
     } else {
       document.body.removeAttribute('data-plannotator-pinpoint-cursor');
+      document.body.removeAttribute('data-plannotator-frame-inert');
     }
   }
   var pinpointHover = null;
@@ -912,11 +926,34 @@ export const BRIDGE_SCRIPT = `(function() {
       var svgGroup = node.closest('g');
       if (svgGroup) node = svgGroup;
     }
+    node = preferInertFrameAt(node, x, y);
     node = promoteTinyTarget(node);
     if (node === document.body || node === document.documentElement) return null;
     return node;
   }
 
+  // While frames are pointer-transparent (armed pinpoint, srcdoc sessions),
+  // hit-testing passes THROUGH an embedded document to the container painted
+  // behind it — so a click on an embed would pin its wrapper div. The embed is
+  // what the reviewer is pointing at and what the anchor must name, so a point
+  // inside a frame's own rect resolves to that frame. Bounded to the frames
+  // inside the element already resolved, so it costs nothing on ordinary pages.
+  var FRAME_SELECTOR = 'iframe,frame,embed,object';
+  function framesArePointerInert() {
+    return !LIVE && annotateModeActive && currentInputMethod === 'pinpoint';
+  }
+  function preferInertFrameAt(node, x, y) {
+    if (!framesArePointerInert() || !node.querySelectorAll) return node;
+    if (node.matches && node.matches(FRAME_SELECTOR)) return node;
+    var frames = node.querySelectorAll(FRAME_SELECTOR);
+    for (var i = 0; i < frames.length && i < 64; i++) {
+      var r = frames[i].getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) continue;
+      if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return frames[i];
+    }
+    return node;
+  }
+
   // Last-position reuse: a pointer that moved under 2px within 16ms resolves
   // to the cached element instead of re-hit-testing. The scroll reconcile
   // invalidates this cache — same point, different element after a scroll.

package/hooks/useAnnotationHighlighter.ts

@@ -1036,6 +1036,11 @@ export function useAnnotationHighlighter({
 
     anns.forEach(ann => {
       if (ann.type === AnnotationType.GLOBAL_COMMENT) return;
+      // A comment on a rendered diagram part has no text anchor: the
+      // diagram overlay restores it against its render and reports its own
+      // verdict, so it is neither attempted nor unanchored here (the same
+      // rule the raw-HTML pinpoints follow on their surface).
+      if (ann.diagramAnchor) return;
       attempted.push(ann.id);
 
       // Skip if already highlighted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -10,6 +10,8 @@
     "./components/goal-setup/*": "./components/goal-setup/*.tsx",
     "./components/ImageAnnotator": "./components/ImageAnnotator/index.tsx",
     "./components/html-viewer": "./components/html-viewer/index.ts",
+    "./components/diagram": "./components/diagram/index.ts",
+    "./components/diagram/*": "./components/diagram/*.tsx",
     "./components/html-viewer/bridge-script": "./components/html-viewer/bridge-script.ts",
     "./components/html-viewer/bridge-script.asset.js": "./components/html-viewer/bridge-script.asset.js",
     "./components/html-viewer/bridge-script.lite": "./components/html-viewer/bridge-script.lite.ts",
@@ -74,11 +76,11 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.6",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.3",
+    "@plannotator/core": "0.25.4",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
-    "@viz-js/viz": "^3.29.0",
+    "@viz-js/viz": "3.30.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "diff": "^8.0.4",