@plannotator/ui 0.52.0 → 0.53.0

package/components/html-viewer/HtmlViewer.tsx

@@ -3,6 +3,7 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -14,7 +15,7 @@ import {
   isVimSelectionActionId,
   type VimSelectionHudContext,
 } from "../../shortcuts";
-import type { Annotation, EditorMode, ImageAttachment, InputMethod } from "../../types";
+import type { Annotation, EditorMode, HostDraft, ImageAttachment, InputMethod } from "../../types";
 import { AnnotationType } from "../../types";
 import { copyTextPreservingFocus } from "../../utils/clipboard";
 import { elementIdentityForAskAI } from "../../utils/parser";
@@ -181,6 +182,9 @@ function parseVimBridgeCopy(value: unknown): string | null {
 }
 
 /** Inputs for the sandboxed raw-HTML viewer and its parent-side annotation UI. */
+/** The fewest milliseconds between two honored `step` messages from the page. */
+export const STEP_MESSAGE_MIN_INTERVAL_MS = 150;
+
 export interface HtmlViewerProps {
   rawHtml: string;
   /** Live proxied-app mode: render `src` (no sandbox, no srcdoc) instead of
@@ -228,6 +232,13 @@ export interface HtmlViewerProps {
   /** Mod+Shift+X pressed while focus lived inside the iframe: show/hide the
    *  host's floating tools over the page. The host owns that state. */
   onToolsToggle?: () => void;
+  /** A plain `]` (1) or `[` (-1) pressed inside the page while the surface is
+   *  armed (Annotate) and the page's focus is not in a text field: the host's
+   *  next / previous file (the Inbox steps through a thread's attachments).
+   *  The bridge forwards nothing in Interact, and the page still gets the
+   *  key. Honored only while the frame holds focus, and at most once per
+   *  STEP_MESSAGE_MIN_INTERVAL_MS. Absent: the message is ignored, as before. */
+  onStep?: (dir: 1 | -1) => void;
   /** Opt-in Vim-style keyboard selection. Default false for compatibility. */
   vimModeEnabled?: boolean;
   /** Replace the iframe-local compact badge with the shared live key HUD. */
@@ -325,6 +336,27 @@ export interface HtmlViewerProps {
    * warning). Meaningless on the inline path, which never shows a strip.
    */
   bridgeErrorDisplay?: "banner" | "none";
+  /**
+   * Opt-in host capability: the composer handed to the host (see
+   * `HostDraft`). A text selection reports `intent: 'selection'` and a pin
+   * `intent: 'compose'` with the element's label, instead of opening the
+   * toolbar or the composer; the selection clearing reports null. With it the
+   * handle's `stepPin` moves a pinned draft to the element around it or back
+   * in. The host saves the comment and draws it through `annotations` /
+   * `applySharedAnnotations`. Ignored when `readOnly`. Absent → unchanged.
+   */
+  onHostDraft?: (draft: HostDraft | null) => void;
+  /**
+   * Opt-in host capability for a native shell whose web view decides every
+   * navigation itself (the Inbox surface in the iPhone app). A link the
+   * person taps in Interact opens as a new window (`window.open`, the sandbox
+   * gains `allow-popups`) instead of being reported through the frame
+   * protocol (`onOpenLink` does not fire for it); the host's web view hands
+   * that window to its own delegate, which decides it. A scripted click opens
+   * nothing. In-page `#` links still scroll here, and an armed pinpoint tap
+   * still pins. Absent → unchanged.
+   */
+  hostNavigates?: boolean;
 }
 
 /**
@@ -351,6 +383,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onAnnotateModeExit,
       onAnnotateModeToggle,
       onToolsToggle,
+      onStep,
       vimModeEnabled = false,
       vimHudEnabled = false,
       vimHudKeyPanelEnabled = true,
@@ -377,6 +410,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       bridgeReadyTimeoutMs = DEFAULT_BRIDGE_READY_TIMEOUT_MS,
       onBridgeUnavailable,
       bridgeErrorDisplay = "banner",
+      onHostDraft,
+      hostNavigates = false,
     },
     ref,
   ) => {
@@ -411,6 +446,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     onAnnotateModeToggleRef.current = onAnnotateModeToggle;
     const onToolsToggleRef = useRef(onToolsToggle);
     onToolsToggleRef.current = onToolsToggle;
+    const onStepRef = useRef(onStep);
+    onStepRef.current = onStep;
+    // The step message is honored only while the host has the surface armed.
+    const annotateModeActiveRef = useRef(annotateModeActive);
+    annotateModeActiveRef.current = annotateModeActive;
+    const lastStepAtRef = useRef(0);
 
     /** Single choke point for direct-to-bridge posts: live sessions get the
      *  token + concrete targetOrigin, srcdoc keeps "*" and no token. */
@@ -613,6 +654,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onUnanchoredChange: handleBridgeUnanchored,
       maxAdditionalTargets,
       scrollBehavior,
+      onHostDraft: readOnly ? undefined : onHostDraft,
     });
     createdIdsRef.current = hook.createdAnnotationIds;
 
@@ -682,7 +724,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       [hook.draftTargets],
     );
 
-    useEffect(() => {
+    // Registered in the commit that inserts the iframe (a layout effect), so
+    // the bridge's `ready` can never arrive before anyone listens: a passive
+    // effect can run after a fast srcdoc frame has already posted it, and a
+    // lost ready leaves the bridge unconfigured for good (seen on a Linux
+    // WebKit runner, the Inbox surface's proof).
+    useLayoutEffect(() => {
       function handler(e: MessageEvent<unknown>) {
         if (e.source !== iframeRef.current?.contentWindow) return;
         // Live sessions verify origin + token before reading anything.
@@ -748,6 +795,20 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
           onToolsToggleRef.current?.();
           return;
         }
+        if (isRecord(e.data) && e.data.type === `${PREFIX}step`) {
+          // The page itself can post this message, so it is honored only for
+          // a key the person pressed: the frame holds focus, the surface is
+          // armed, and at most one step per STEP_MESSAGE_MIN_INTERVAL_MS (a
+          // page cannot push itself out of view by posting in a loop).
+          const dir = e.data.dir;
+          if (!annotateModeActiveRef.current || (dir !== 1 && dir !== -1)) return;
+          if (document.activeElement !== iframeRef.current) return;
+          const now = Date.now();
+          if (now - lastStepAtRef.current < STEP_MESSAGE_MIN_INTERVAL_MS) return;
+          lastStepAtRef.current = now;
+          onStepRef.current?.(dir);
+          return;
+        }
         const vimCopy = parseVimBridgeCopy(e.data);
         if (vimCopy !== null) {
           const iframe = iframeRef.current;
@@ -916,6 +977,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       );
     }, [iframeReadyVersion, annotateModeActive]);
 
+    // A native host decides link navigations itself (`hostNavigates`).
+    useEffect(() => {
+      if (iframeReadyVersion === 0 || !hostNavigates) return;
+      postToBridge({ type: `${PREFIX}set-host-navigates`, active: true });
+    }, [iframeReadyVersion, hostNavigates]);
+
     // Parent-side Esc rung: with focus outside the iframe the bridge never
     // sees the keydown. Any open composer/toolbar/picker still closes first —
     // their state is read from this render's closure, so an Esc that closed
@@ -1012,6 +1079,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       // Shared/draft restores respect the live page filter too.
       applySharedAnnotations: (anns: Annotation[]) =>
         hook.applyAnnotations(forCurrentPage(anns)),
+      stepPin: (direction: "parent" | "child") =>
+        postToBridge({ type: `${PREFIX}step-pin`, direction }),
+      revealPin: () => postToBridge({ type: `${PREFIX}reveal-pin` }),
     }));
 
     const handleGlobalCommentSubmit = useCallback(
@@ -1166,7 +1236,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 same-origin XHR) and no srcdoc. Srcdoc mode is unchanged. */}
             <iframe
               ref={iframeRef}
-              {...(src ? { src } : { srcDoc: srcdoc, sandbox: "allow-scripts" })}
+              {...(src ? { src } : { srcDoc: srcdoc, sandbox: "allow-scripts" + (hostNavigates ? " allow-popups" : "") })}
               style={{
                 width: "100%",
                 height: fullViewport ? "100%" : `${iframeHeight}px`,

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

@@ -225,6 +225,8 @@
   // marker buttons keep their own clicks. BOTH surface kinds start ARMED —
   // Esc (or the header pen) drops to Interact.
   var annotateModeActive = true;
+  // A native host decides link navigations itself (HtmlViewer hostNavigates).
+  var hostNavigates = false;
   function updatePinpointCursor() {
     if (!document.body) return;
     if (annotateModeActive && currentInputMethod === 'pinpoint') {
@@ -530,6 +532,21 @@
       flashMultiTarget(typeof e.data.key === 'string' ? e.data.key : '');
     }
 
+    else if (type === PREFIX + 'step-pin') {
+      // A host's Parent or Child (a phone's comment sheet): move the pinned
+      // draft to the element around it, or back in. Re-pins through
+      // annotateElement, so the parent sees an ordinary pinpoint selection.
+      stepPin(e.data.direction === 'child' ? 'child' : 'parent');
+    }
+
+    else if (type === PREFIX + 'reveal-pin') {
+      // A host whose own panel covers the page's lower part (a phone's comment
+      // sheet) shrank the frame: bring the pinned draft back into view.
+      if (pendingPinEl && pendingPinEl.isConnected) {
+        try { pendingPinEl.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (ex) {}
+      }
+    }
+
     else if (type === PREFIX + 'scroll-to') {
       // Selecting an annotation scrolls its first resolved target into view
       // and flashes the overlay focus highlight over EVERY rect of EVERY
@@ -573,6 +590,10 @@
       if (vimEnabled) updateVimUi();
     }
 
+    else if (type === PREFIX + 'set-host-navigates') {
+      hostNavigates = e.data.active === true;
+    }
+
     else if (type === PREFIX + 'set-annotate-mode') {
       var nextAnnotateActive = e.data.active === true;
       if (nextAnnotateActive !== annotateModeActive) {
@@ -3524,6 +3545,41 @@
     });
   }
 
+  // Parent and Child for a pinned draft. The trail holds the elements stepped
+  // out of, so Child goes back the way Parent came; past it, Child takes the
+  // first element child. A new pin by click starts a new trail.
+  var pinStepTrail = [];
+  var steppingPin = false;
+  function stepPin(direction) {
+    if (!pendingPinEl || !pendingPinEl.isConnected) return;
+    var from = pendingPinEl;
+    var next = null;
+    if (direction === 'parent') {
+      var up = from.parentElement;
+      if (up && up !== document.body && up !== document.documentElement) next = up;
+    } else {
+      var back = pinStepTrail[pinStepTrail.length - 1];
+      if (back && back.isConnected && from.contains(back)) next = back;
+      else {
+        for (var child = from.firstElementChild; child; child = child.nextElementSibling) {
+          if (isViewerOverlayNode(child)) continue;
+          if (/^(SCRIPT|STYLE|TEMPLATE|NOSCRIPT)$/.test(child.tagName)) continue;
+          next = child;
+          break;
+        }
+      }
+    }
+    if (!next) return;
+    var trail = pinStepTrail.slice();
+    if (direction === 'parent') trail.push(from);
+    else if (trail[trail.length - 1] === next) trail.pop();
+    else trail = [];
+    steppingPin = true;
+    try { annotateElement(next, undefined, pendingPinViaPinpoint, null); }
+    finally { steppingPin = false; }
+    pinStepTrail = trail;
+  }
+
   // Pin an element: select its text if possible (so a <mark> can wrap it), else
   // post its text + box directly so the toolbar still anchors (e.g. an SVG node,
   // whose <text> doesn't select like HTML text). Either way the element stays
@@ -3531,6 +3587,7 @@
   // rides along so the annotation can restore to this exact element later.
   function annotateElement(el, modeOverride, viaPinpoint, clickPoint) {
     if (!el) return false;
+    if (!steppingPin) pinStepTrail = [];
     pinpointHover = null;
     hidePinpointLabel();
     clearMultiTargets(); // a new primary starts a fresh draft
@@ -3666,6 +3723,16 @@
         return;
       }
       e.preventDefault();
+      // A native host decides links itself: a person's tap opens the link as a
+      // new window, which the host's web view hands to its own delegate (the
+      // frame never navigates; the host page's CSP would refuse it anyway).
+      if (hostNavigates) {
+        if (e.isTrusted && !(annotateModeActive && currentInputMethod === 'pinpoint')) {
+          var target = (e.target && e.target.closest) ? e.target.closest('a,area') : null;
+          try { window.open(target && target.href ? target.href : raw, '_blank', 'noopener'); } catch (ex) {}
+        }
+        return;
+      }
       // Armed pinpoint: the click belongs to annotation, and the capture-phase
       // pinpoint handler below is about to pin this element. Navigation is
       // already suppressed above, which is all this surface owes the click.
@@ -3766,6 +3833,25 @@
     postToParent({ type: PREFIX + message });
   }, true);
 
+  // A plain ] or [ while armed (Annotate): the host may step to its next or
+  // previous file (the Inbox steps through a thread's attachments). Never in
+  // Interact (the page owns its keys), never while the page's focus is in a
+  // text field, with a modifier, on auto-repeat or mid-composition. The page
+  // still receives the key; a host without a step handler ignores the
+  // message. Capture phase, like the chords above.
+  document.addEventListener('keydown', function(e) {
+    if (e.key !== ']' && e.key !== '[') return;
+    if (!annotateModeActive || vimEnabled) return;
+    if (e.metaKey || e.ctrlKey || e.altKey || e.repeat || e.isComposing) return;
+    var t = e.target;
+    if (t && t.nodeType === 1) {
+      var tag = t.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || t.isContentEditable) return;
+      if (t.closest && t.closest('[contenteditable]:not([contenteditable="false"])')) return;
+    }
+    postToParent({ type: PREFIX + 'step', dir: e.key === ']' ? 1 : -1 });
+  }, true);
+
   // Author opt-in: a plain click on any element tagged [data-annotate] pops the
   // toolbar — no pinpoint mode. Lets an HTML doc (e.g. a flow graph) wire its own
   // nodes to Plannotator's toolbar. Bubble phase so the page's own click handlers

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

@@ -461,6 +461,8 @@ export const BRIDGE_SCRIPT = `(function() {
   // marker buttons keep their own clicks. BOTH surface kinds start ARMED —
   // Esc (or the header pen) drops to Interact.
   var annotateModeActive = true;
+  // A native host decides link navigations itself (HtmlViewer hostNavigates).
+  var hostNavigates = false;
   function updatePinpointCursor() {
     if (!document.body) return;
     if (annotateModeActive && currentInputMethod === 'pinpoint') {
@@ -766,6 +768,21 @@ export const BRIDGE_SCRIPT = `(function() {
       flashMultiTarget(typeof e.data.key === 'string' ? e.data.key : '');
     }
 
+    else if (type === PREFIX + 'step-pin') {
+      // A host's Parent or Child (a phone's comment sheet): move the pinned
+      // draft to the element around it, or back in. Re-pins through
+      // annotateElement, so the parent sees an ordinary pinpoint selection.
+      stepPin(e.data.direction === 'child' ? 'child' : 'parent');
+    }
+
+    else if (type === PREFIX + 'reveal-pin') {
+      // A host whose own panel covers the page's lower part (a phone's comment
+      // sheet) shrank the frame: bring the pinned draft back into view.
+      if (pendingPinEl && pendingPinEl.isConnected) {
+        try { pendingPinEl.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (ex) {}
+      }
+    }
+
     else if (type === PREFIX + 'scroll-to') {
       // Selecting an annotation scrolls its first resolved target into view
       // and flashes the overlay focus highlight over EVERY rect of EVERY
@@ -809,6 +826,10 @@ export const BRIDGE_SCRIPT = `(function() {
       if (vimEnabled) updateVimUi();
     }
 
+    else if (type === PREFIX + 'set-host-navigates') {
+      hostNavigates = e.data.active === true;
+    }
+
     else if (type === PREFIX + 'set-annotate-mode') {
       var nextAnnotateActive = e.data.active === true;
       if (nextAnnotateActive !== annotateModeActive) {
@@ -3760,6 +3781,41 @@ export const BRIDGE_SCRIPT = `(function() {
     });
   }
 
+  // Parent and Child for a pinned draft. The trail holds the elements stepped
+  // out of, so Child goes back the way Parent came; past it, Child takes the
+  // first element child. A new pin by click starts a new trail.
+  var pinStepTrail = [];
+  var steppingPin = false;
+  function stepPin(direction) {
+    if (!pendingPinEl || !pendingPinEl.isConnected) return;
+    var from = pendingPinEl;
+    var next = null;
+    if (direction === 'parent') {
+      var up = from.parentElement;
+      if (up && up !== document.body && up !== document.documentElement) next = up;
+    } else {
+      var back = pinStepTrail[pinStepTrail.length - 1];
+      if (back && back.isConnected && from.contains(back)) next = back;
+      else {
+        for (var child = from.firstElementChild; child; child = child.nextElementSibling) {
+          if (isViewerOverlayNode(child)) continue;
+          if (/^(SCRIPT|STYLE|TEMPLATE|NOSCRIPT)$/.test(child.tagName)) continue;
+          next = child;
+          break;
+        }
+      }
+    }
+    if (!next) return;
+    var trail = pinStepTrail.slice();
+    if (direction === 'parent') trail.push(from);
+    else if (trail[trail.length - 1] === next) trail.pop();
+    else trail = [];
+    steppingPin = true;
+    try { annotateElement(next, undefined, pendingPinViaPinpoint, null); }
+    finally { steppingPin = false; }
+    pinStepTrail = trail;
+  }
+
   // Pin an element: select its text if possible (so a <mark> can wrap it), else
   // post its text + box directly so the toolbar still anchors (e.g. an SVG node,
   // whose <text> doesn't select like HTML text). Either way the element stays
@@ -3767,6 +3823,7 @@ export const BRIDGE_SCRIPT = `(function() {
   // rides along so the annotation can restore to this exact element later.
   function annotateElement(el, modeOverride, viaPinpoint, clickPoint) {
     if (!el) return false;
+    if (!steppingPin) pinStepTrail = [];
     pinpointHover = null;
     hidePinpointLabel();
     clearMultiTargets(); // a new primary starts a fresh draft
@@ -3902,6 +3959,16 @@ export const BRIDGE_SCRIPT = `(function() {
         return;
       }
       e.preventDefault();
+      // A native host decides links itself: a person's tap opens the link as a
+      // new window, which the host's web view hands to its own delegate (the
+      // frame never navigates; the host page's CSP would refuse it anyway).
+      if (hostNavigates) {
+        if (e.isTrusted && !(annotateModeActive && currentInputMethod === 'pinpoint')) {
+          var target = (e.target && e.target.closest) ? e.target.closest('a,area') : null;
+          try { window.open(target && target.href ? target.href : raw, '_blank', 'noopener'); } catch (ex) {}
+        }
+        return;
+      }
       // Armed pinpoint: the click belongs to annotation, and the capture-phase
       // pinpoint handler below is about to pin this element. Navigation is
       // already suppressed above, which is all this surface owes the click.
@@ -4002,6 +4069,25 @@ export const BRIDGE_SCRIPT = `(function() {
     postToParent({ type: PREFIX + message });
   }, true);
 
+  // A plain ] or [ while armed (Annotate): the host may step to its next or
+  // previous file (the Inbox steps through a thread's attachments). Never in
+  // Interact (the page owns its keys), never while the page's focus is in a
+  // text field, with a modifier, on auto-repeat or mid-composition. The page
+  // still receives the key; a host without a step handler ignores the
+  // message. Capture phase, like the chords above.
+  document.addEventListener('keydown', function(e) {
+    if (e.key !== ']' && e.key !== '[') return;
+    if (!annotateModeActive || vimEnabled) return;
+    if (e.metaKey || e.ctrlKey || e.altKey || e.repeat || e.isComposing) return;
+    var t = e.target;
+    if (t && t.nodeType === 1) {
+      var tag = t.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || t.isContentEditable) return;
+      if (t.closest && t.closest('[contenteditable]:not([contenteditable="false"])')) return;
+    }
+    postToParent({ type: PREFIX + 'step', dir: e.key === ']' ? 1 : -1 });
+  }, true);
+
   // Author opt-in: a plain click on any element tagged [data-annotate] pops the
   // toolbar — no pinpoint mode. Lets an HTML doc (e.g. a flow graph) wire its own
   // nodes to Plannotator's toolbar. Bubble phase so the page's own click handlers

package/components/html-viewer/useHtmlAnnotation.ts

@@ -1,5 +1,5 @@
-import { useState, useEffect, useCallback, useRef, type RefObject } from "react";
-import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type HtmlElementContext, type ImageAttachment } from "../../types";
+import { useState, useEffect, useLayoutEffect, useCallback, useRef, type RefObject } from "react";
+import { AnnotationType, type Annotation, type EditorMode, type HostDraft, type HtmlAnnotationTarget, type HtmlElementAnchor, type HtmlElementContext, type ImageAttachment } from "../../types";
 import { THUMBS_UP_LABEL, type QuickLabel } from "../../utils/quickLabels";
 import { getIdentity } from "../../utils/identity";
 import type {
@@ -199,6 +199,10 @@ export interface UseHtmlAnnotationOptions {
   /** scrollIntoView behavior for scroll-to (selecting an annotation).
    *  Absent: smooth, as before; pass 'auto' to honor reduced motion. */
   scrollBehavior?: 'smooth' | 'auto';
+  /** The composer handed to the host (see `HostDraft` and HtmlViewer's
+   *  `onHostDraft`): a selection or a pin reports a draft instead of opening
+   *  the toolbar or the composer. Absent: unchanged. */
+  onHostDraft?: (draft: HostDraft | null) => void;
 }
 
 /** Clamp a host cap into the package's bound; anything unusable is the default. */
@@ -465,6 +469,7 @@ export function useHtmlAnnotation({
   onUnanchoredChange,
   maxAdditionalTargets,
   scrollBehavior,
+  onHostDraft,
 }: UseHtmlAnnotationOptions): Omit<
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
@@ -536,6 +541,10 @@ export function useHtmlAnnotation({
   onPageChangeRef.current = onPageChange;
   const onLinkClickRef = useRef(onLinkClick);
   onLinkClickRef.current = onLinkClick;
+  const onHostDraftRef = useRef(onHostDraft);
+  onHostDraftRef.current = onHostDraft;
+  // The id of the draft the host holds, so a stale cancel cannot drop a newer one.
+  const hostDraftIdRef = useRef<string | null>(null);
   // The effective cap and whether the host set one: only an explicit cap
   // rides on arm-multi-select, so an unconfigured viewer posts today's message.
   const maxTargetsRef = useRef(resolveMaxAdditionalTargets(maxAdditionalTargets));
@@ -628,7 +637,9 @@ export function useHtmlAnnotation({
     [iframeRef, getOrCreateAnchor],
   );
 
-  useEffect(() => {
+  // A layout effect, like HtmlViewer's own listener: listening from the
+  // commit that inserts the iframe, before its document can post anything.
+  useLayoutEffect(() => {
     function handler(e: MessageEvent<unknown>) {
       if (e.source !== iframeRef.current?.contentWindow) return;
       // Live sessions verify origin + session token BEFORE parsing. The
@@ -659,6 +670,39 @@ export function useHtmlAnnotation({
         pendingAnchorRef.current = message.anchor ?? null;
         pendingContextRef.current = message.context ?? null;
         setDraftTargets([]); // a new selection always starts a fresh draft
+        const reportDraft = onHostDraftRef.current;
+        if (reportDraft) {
+          // The host composes: HTML is comment-only, so every selection or
+          // pin is a comment draft, and nothing of ours opens.
+          const id = nextHtmlAnnId();
+          hostDraftIdRef.current = id;
+          reportDraft({
+            annotation: {
+              id,
+              blockId: "",
+              startOffset: 0,
+              endOffset: 0,
+              type: AnnotationType.COMMENT,
+              text: "",
+              originalText: message.text,
+              author: getIdentity(),
+              createdA: Date.now(),
+              htmlAnchor: message.anchor,
+              elementContext: message.context,
+            },
+            intent: message.pinpoint ? "compose" : "selection",
+            label: message.targetLabel,
+            cancel: () => {
+              if (hostDraftIdRef.current !== id) return;
+              hostDraftIdRef.current = null;
+              post({ type: `${PREFIX}cancel-selection` });
+              pendingTextRef.current = "";
+              pendingAnchorRef.current = null;
+              pendingContextRef.current = null;
+            },
+          });
+          return;
+        }
         const anchor = positionAnchor(message.rect);
         if (!anchor) return;
 
@@ -754,6 +798,10 @@ export function useHtmlAnnotation({
       }
 
       if (type === `${PREFIX}selection-clear`) {
+        if (onHostDraftRef.current && hostDraftIdRef.current) {
+          hostDraftIdRef.current = null;
+          onHostDraftRef.current(null);
+        }
         setToolbarState(null);
         // Keep the captured text alive while a comment/quick-label is open: the user
         // is composing, and the selection collapsing or scrolling out of view must

package/components/icons/AgentIcons.tsx

@@ -19,14 +19,16 @@ export function CodexIcon({ className }: { className?: string }) {
   return <img src={CODEX_DATA_URI} className={className} alt="" aria-hidden="true" draggable={false} />;
 }
 
-// Pi brand mark — path data from packages/ui/components/ProviderIcons.tsx's
-// PiIcon (itself extracted from apps/marketing/public/assets/icon-pi.svg).
-// currentColor so it adapts to theme, like OpenCodeIcon below.
+// Pi brand mark: the pi.dev logo (https://pi.dev/logo.svg), the same paths as
+// ProviderIcons.tsx's PiIcon and apps/marketing/public/assets/icon-pi.svg. Its
+// own three colours in every theme; the viewBox crops pi.dev's 800-unit canvas
+// to the mark plus an even margin so it sits level with the other marks.
 export function PiIcon({ className }: { className?: string }) {
   return (
-    <svg viewBox="0 0 800 800" className={className} xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
-      <path fill="currentColor" fillRule="evenodd" d="M165.29 165.29H517.36V400H400V517.36H282.65V634.72H165.29ZM282.65 282.65V400H400V282.65Z" />
-      <path fill="currentColor" d="M517.36 400H634.72V634.72H517.36Z" />
+    <svg viewBox="130 130 540 540" className={className} xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
+      <path fill="#F09082" d="M165.29 165.29H517.36V400H400V282.65H165.29Z" />
+      <path fill="#4D9ABF" d="M165.29 282.65H282.65V400H400V517.36H282.65V634.72H165.29Z" />
+      <path fill="#F1BE58" d="M517.36 400H634.72V634.72H517.36Z" />
     </svg>
   );
 }
@@ -34,7 +36,7 @@ export function PiIcon({ className }: { className?: string }) {
 // GitHub Copilot brand mark — path from the official agent icon set
 // (welcome.developers.workers.dev/icons/agents/copilot); the dark/light
 // variants there differ only by fill, so one currentColor component covers
-// both themes, like PiIcon/OpenCodeIcon.
+// both themes, like OpenCodeIcon.
 export function CopilotIcon({ className }: { className?: string }) {
   return (
     <svg viewBox="0 0 256 208" className={className} xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">