@plannotator/ui 0.29.1 → 0.30.0

package/components/AnnotationPanel.tsx

@@ -80,8 +80,11 @@ interface PanelProps {
     *  resolve UI). The panel stays presentation-only; clicks inside the slot
     *  do not select the card. Default: nothing rendered. */
   renderCardFooter?: (annotation: Annotation) => React.ReactNode;
-  /** Hide every mutation affordance (delete/edit, direct-edit discard, and host card footers).
-    *  Selection and scrolling still work. Default false — today's behavior. */
+  /** Hide every built-in mutation affordance (delete/edit, direct-edit
+    *  discard). The host footer slot still renders: its contents are
+    *  host-owned and may be read affordances (replies, links), so the host
+    *  gates what belongs in it. Selection and scrolling still work.
+    *  Default false — today's behavior. */
   readOnly?: boolean;
 }
 
@@ -207,7 +210,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   onDelete={() => onDelete(entry.annotation.id)}
                   onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
                   readOnly={readOnly}
-                  footer={readOnly ? undefined : renderCardFooter?.(entry.annotation)}
+                  footer={renderCardFooter?.(entry.annotation)}
                 />
               ) : (
                 <CodeAnnotationCard

package/components/html-viewer/HtmlViewer.tsx

@@ -172,6 +172,11 @@ export interface HtmlViewerProps {
   onAskAI?: CommentAskAIHandler;
   /** Disable every annotation mutation entry point while preserving reading and navigation. */
   readOnly?: boolean;
+  /** Reports the full set of annotation ids with no live representation on
+   *  the page (fail-closed anchors hide markers rather than guess). Called
+   *  with the complete current set whenever it changes, including back to
+   *  empty on recovery. Fires in readOnly mode too. */
+  onUnanchoredChange?: (ids: string[]) => void;
   /** Accessible iframe title. */
   title?: string;
 }
@@ -205,6 +210,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onToggleDiff,
       onAskAI,
       readOnly = false,
+      onUnanchoredChange,
       title = "HTML Plan Viewer",
     },
     ref,
@@ -294,6 +300,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       mode,
       onResize: handleResize,
       onBridgePointer: handleBridgePointer,
+      onUnanchoredChange,
     });
 
     const multiSelectActive = !readOnly && !!hook.commentPopover && hook.draftTargets.length > 0;

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

@@ -499,6 +499,7 @@ export const BRIDGE_SCRIPT = `(function() {
       annRecords = [];
       annNumbers = null; // stale synced numbers must not leak onto future records
       focusedAnnotationId = null;
+      restoreFailedIds.clear();
       renderAnnotationOverlay();
     }
 
@@ -1327,9 +1328,43 @@ export const BRIDGE_SCRIPT = `(function() {
     for (var i = annRecords.length - 1; i >= 0; i--) {
       if (annRecords[i].id === id) annRecords.splice(i, 1);
     }
+    restoreFailedIds['delete'](id);
     if (focusedAnnotationId === id) focusedAnnotationId = null;
   }
 
+  // Fail-closed transparency (host ask): markers for dead targets are
+  // omitted, never guessed — this names WHICH annotations currently have no
+  // live representation on the page (every target dead, or the restore never
+  // resolved anything) so the host can tell the user instead of letting them
+  // silently vanish. Emitted only when the set changes, and only from
+  // complete overlay passes — budget-starved passes reschedule themselves
+  // and would flap the set. restoreFailedIds carries total restore failures,
+  // whose records are removed and therefore invisible to the per-pass scan.
+  var lastUnanchoredKey = '[]';
+  var restoreFailedIds = new Set();
+  function emitUnanchored(deadRecordIds) {
+    var seen = new Set();
+    var combined = [];
+    for (var deadIndex = 0; deadIndex < deadRecordIds.length; deadIndex++) {
+      if (!seen.has(deadRecordIds[deadIndex])) {
+        seen.add(deadRecordIds[deadIndex]);
+        combined.push(deadRecordIds[deadIndex]);
+      }
+    }
+    restoreFailedIds.forEach(function(failedId) {
+      if (!seen.has(failedId)) {
+        seen.add(failedId);
+        combined.push(failedId);
+      }
+    });
+    combined.sort();
+    if (combined.length > 512) combined = combined.slice(0, 512);
+    var key = JSON.stringify(combined);
+    if (key === lastUnanchoredKey) return;
+    lastUnanchoredKey = key;
+    parent.postMessage({ type: PREFIX + 'unanchored', ids: combined }, '*');
+  }
+
   function validNormalizedPoint(p) {
     if (!p || typeof p.x !== 'number' || typeof p.y !== 'number') return null;
     if (!isFinite(p.x) || !isFinite(p.y)) return null;
@@ -1467,7 +1502,12 @@ export const BRIDGE_SCRIPT = `(function() {
         }
       }
     }
-    if (!record.targets.length) removeAnnRecord(id);
+    if (!record.targets.length) {
+      // The record is removed (nothing to retry), so the per-pass dead scan
+      // cannot see this id: track it separately for the unanchored report.
+      removeAnnRecord(id);
+      restoreFailedIds.add(id);
+    }
     // rAF-coalesced render (B3): restoring N annotations posts N
     // find-and-mark messages, and a synchronous render here made a batch
     // restore O(N^2) full overlay passes. The searches above stay
@@ -2094,10 +2134,17 @@ export const BRIDGE_SCRIPT = `(function() {
 
   function renderAnnotationOverlay() {
     var hasDraftRange = !!(pendingSelection && pendingRange);
-    if (!annRecords.length && !hasDraftRange && !overlayHostEl) return;
+    if (!annRecords.length && !hasDraftRange && !overlayHostEl) {
+      // Nothing to project, but total restore failures must still report:
+      // a session whose only annotations failed to restore never builds the
+      // overlay host, and silence here would hide exactly that case.
+      emitUnanchored([]);
+      return;
+    }
     ensureOverlayHost();
     beginDeadSearchPass();
     queuedHighlights.length = 0;
+    var unanchoredThisPass = [];
     var markers = [];
     // Fallback numbering by first-seen registration order — used only until
     // the parent's ordered sync arrives. Numbering NEVER derives from target
@@ -2111,6 +2158,20 @@ export const BRIDGE_SCRIPT = `(function() {
     for (var recordIndex = 0; recordIndex < annRecords.length; recordIndex++) {
       var record = annRecords[recordIndex];
       refreshRecordTargets(record);
+      // Live means connected/findable — clipped, offscreen, or style-hidden
+      // targets are still anchored (their content exists; it just isn't
+      // currently visible) and must not report as unanchored.
+      var recordAnchored = false;
+      for (var liveIndex = 0; liveIndex < record.targets.length; liveIndex++) {
+        var liveTarget = record.targets[liveIndex];
+        if (liveTarget.kind === 'element'
+          ? (liveTarget.element && liveTarget.element.isConnected)
+          : rangeAlive(liveTarget.range)) {
+          recordAnchored = true;
+          break;
+        }
+      }
+      if (!recordAnchored) unanchoredThisPass.push(record.id);
       var number = annNumbers && annNumbers.has(record.id)
         ? annNumbers.get(record.id)
         : fallbackNumbers.get(record.id);
@@ -2219,6 +2280,9 @@ export const BRIDGE_SCRIPT = `(function() {
     // record.
     flushQueuedHighlights();
     placeMarkers(markers);
+    // Budget-starved passes reschedule below and may still revive targets,
+    // so only a complete pass may update the unanchored report.
+    if (!deadSearchSkipped) emitUnanchored(unanchoredThisPass);
     // Eligible dead-target searches skipped for budget get a follow-up pass;
     // the loop terminates once every eligible target has been attempted at
     // the current generation (its failedGeneration then blocks it).

package/components/html-viewer/useHtmlAnnotation.ts

@@ -65,6 +65,7 @@ type BridgeMessage =
   | { type: `${typeof PREFIX}selection-rect`; rect: BridgeRect }
   | { type: `${typeof PREFIX}keytype`; key: string }
   | { type: `${typeof PREFIX}mark-click`; id: string }
+  | { type: `${typeof PREFIX}unanchored`; ids: string[] }
   | { type: `${typeof PREFIX}resize`; height: number };
 
 /** Dependencies and callbacks for the sandboxed HTML annotation bridge. */
@@ -84,6 +85,13 @@ export interface UseHtmlAnnotationOptions {
    *  held while the pointer lives in the sandbox). Drives the composer-yield
    *  fade in the host component. */
   onBridgePointer?: (x: number, y: number, shift: boolean) => void;
+  /** Reports the full set of annotation ids that currently have NO live
+   *  representation on the page — every target dead, or the restore never
+   *  resolved (fail-closed anchors hide markers rather than guess). Called
+   *  with the complete current set whenever it changes, including back to
+   *  empty on recovery. Delivered in readOnly mode too: view-only surfaces
+   *  are exactly where silently missing markers would go unnoticed. */
+  onUnanchoredChange?: (ids: string[]) => void;
 }
 
 function postToIframe(iframe: HTMLIFrameElement | null, msg: Record<string, unknown>) {
@@ -258,6 +266,18 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
       return typeof value.id === "string" && value.id.length <= 256
         ? { type: value.type, id: value.id }
         : null;
+    case `${PREFIX}unanchored`: {
+      // Bounded like the bridge's own emission (512 ids, 256 chars each); any
+      // out-of-contract entry rejects the whole report — the real bridge
+      // never sends one, so a violation means a forged message.
+      if (!Array.isArray(value.ids) || value.ids.length > 512) return null;
+      const unanchoredIds: string[] = [];
+      for (const entry of value.ids) {
+        if (typeof entry !== "string" || entry.length > 256) return null;
+        unanchoredIds.push(entry);
+      }
+      return { type: value.type, ids: unanchoredIds };
+    }
     case `${PREFIX}resize`:
       return typeof value.height === "number" && Number.isFinite(value.height)
         ? { type: value.type, height: value.height }
@@ -282,6 +302,7 @@ export function useHtmlAnnotation({
   mode,
   onResize,
   onBridgePointer,
+  onUnanchoredChange,
 }: UseHtmlAnnotationOptions): Omit<
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
@@ -328,6 +349,8 @@ export function useHtmlAnnotation({
   onAddRef.current = onAddAnnotation;
   const onSelectRef = useRef(onSelectAnnotation);
   onSelectRef.current = onSelectAnnotation;
+  const onUnanchoredChangeRef = useRef(onUnanchoredChange);
+  onUnanchoredChangeRef.current = onUnanchoredChange;
 
   const anchorRef = useRef<HTMLDivElement | null>(null);
 
@@ -411,7 +434,12 @@ export function useHtmlAnnotation({
 
       const type = message.type;
 
-      if (!enabledRef.current && type !== `${PREFIX}mark-click` && type !== `${PREFIX}resize`) {
+      if (
+        !enabledRef.current
+        && type !== `${PREFIX}mark-click`
+        && type !== `${PREFIX}unanchored`
+        && type !== `${PREFIX}resize`
+      ) {
         return;
       }
 
@@ -564,6 +592,10 @@ export function useHtmlAnnotation({
         onSelectRef.current?.(message.id);
       }
 
+      if (type === `${PREFIX}unanchored`) {
+        onUnanchoredChangeRef.current?.(message.ids);
+      }
+
       if (type === `${PREFIX}resize`) {
         onResize?.(message.height);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",