@plannotator/ui 0.31.0 → 0.33.0

package/README.md

@@ -27,6 +27,9 @@ configurePlannotatorUI({
   skillCatalogTransport,       // skill-reference catalog for comment composers
   skillContentTransport,       // human-only skill contents for feedback injection
   serverSync,
+  webmcp,                      // browser-agent (WebMCP) provider policy: { enabled, namePrefix }
+  mathRendererLoader,          // how KaTeX loads when no renderer is registered before first math render
+  identityGenerator,           // sync generator behind the default "tater" name (no identityProvider)
 });
 ```
 
@@ -47,6 +50,16 @@ The sidebar/panel resize handle exposes seams for hosts that want different edge
 
 Building your own tooltip and removing the built-in double-click reset are host-side concerns (override `onDoubleClick` where you render the handle).
 
+### Lazy renderers and the eager entries (`utils/math`, `utils/generateIdentity`, `utils/mermaid`; 0.32.0)
+
+The Mermaid runtime, the Graphviz engine, KaTeX and the username dictionary are off the static import graph of `Viewer`, so a host that bundles by route does not download them for a plain markdown read. Graphviz needs nothing from you (the block imports the engine inside its render effect and shows the source fence until the SVG lands, as it always did). Mermaid, KaTeX and the dictionary sit behind synchronous slots:
+
+- **Math.** Without registration, a math node renders its TeX as text in the same wrapper (same `data-math-tex` / `data-math-display` / `aria-label` / class names), loads KaTeX via `import('katex')`, and re-renders typeset. To keep math typeset on the very first commit, as Plannotator does, add one line to your entry: `import "@plannotator/ui/utils/math-eager";`. To put KaTeX and its stylesheet on one lazy chunk instead, pass `mathRendererLoader`. The stylesheet remains your job either way (see "Consuming it", step 3). The default `import('katex')` is the only runtime mention of `katex` in the package and lives in `utils/math-default-loader` (0.33.0), called only while no loader is registered; a registered loader is never backfilled by it, though a default load already in flight at registration still fills the slot (pre-existing), so register the loader before the first math render. Chunk emission is static, so a bundler still emits that chunk (never requested) unless you alias the module away; see HANDOFF.md "Lazy renderers and eager entries" for the two-line alias.
+- **Mermaid.** Without registration, the first diagram on a page fetches the runtime through `import('mermaid')`; a failed import is dropped from the memo, re-attempted once after a short delay, and the error panel (with the source) offers Retry, which issues another fresh attempt. Plannotator keeps Mermaid eager by policy so it can never fail separately from the app: `import "@plannotator/ui/utils/mermaid-eager";` in your entry does the same for your bundle. Honest limit of any in-page retry: a browser records a failed module fetch in its module map for the page lifetime, so a fresh `import()` of the same chunk URL rejects without a request; the retry recovers failures after the fetch (engine instantiation, initialize) and hosts that version chunk URLs. A host that needs recovery from a failed first fetch uses versioned chunk URLs or a `vite:preloadError` reload at app level.
+- **Identity.** With an `identityProvider` the generator is never called and the word lists stay out of your bundle. Without one, default names come from a small built-in pool of the same `adjective-noun-tater` shape; `import "@plannotator/ui/utils/identity-tater";` registers the full dictionary, or pass your own `identityGenerator`.
+
+Plannotator's own entries import the eager modules (`math-eager` and `identity-tater` in both `packages/editor/App.tsx` and `packages/review-editor/App.tsx`; `mermaid-eager` in the plan editor only, since the review editor never renders a Mermaid block), which is what keeps its single-file builds byte-identical and its portal entry chunk shaped as before; `tests/entry-assets.test.ts` fails if any of them is dropped. See HANDOFF.md "Lazy renderers and eager entries".
+
 ### Markdown editor extensions + wiki links (`MarkdownEditor` / `InlineMarkdown`)
 
 - **`MarkdownEditor` takes CM6 extensions.** `extensions?: readonly Extension[]` (from `@codemirror/state`) is forwarded verbatim into the underlying editor — the seam for `wikiLinks(config)`, `y-codemirror.next` collab bindings, custom keymaps.
@@ -85,6 +98,49 @@ Requires `@plannotator/markdown-editor ^0.4.0` and `@plannotator/atomic-editor ^
 
 `components/html-viewer` is supported host surface as of 0.29.0: the overlay-projection annotation viewer for raw HTML (placed comment markers, pinpoint element anchors, shift-click multi-target comments). Its contract is **props plus the validated iframe message protocol** — not `configurePlannotatorUI()`, which only governs the backend surfaces around it. Drive the `annotations` prop (marker numbering derives from its array order); `readOnly` keeps markers painted and clickable while disabling all authoring. **0.29.0 also carries a breaking migration:** highlight.js is gone and `.hljs` selectors are inert — style code via the exported `pn-code` class (`CODE_BLOCK_CLASS` in `utils/codeHighlight`). See HANDOFF.md § "Raw-HTML annotation viewer + syntax-highlighting migration (0.29.0)" before upgrading from 0.28.0.
 
+#### HTML annotation parity seams (0.32.0)
+
+Everything a host needs around `HtmlViewer` to match Plannotator's HTML annotation experience, all additive and all defaulting to today's behavior. Requires `@plannotator/core` 0.25.0 (the `html-anchor` subpath), so install and publish core before ui:
+
+- **`projectHostThreads(threads, { openOnly?, documentLevel?, maxTargets? })`** and **`buildPersistedHtmlAnchor(source, { maxBytes?, maxTargets? })`** from `components/html-viewer` (pure, from `@plannotator/core/html-anchor`): project stored rows onto the `annotations` prop in the order that becomes the marker numbering, and trim a composed comment's anchor for persistence with cap drops and size drops reported separately. A row with nothing restorable projects as a document-level `GLOBAL_COMMENT` by default (`documentLevel: 'global'`, never reported as unanchored) or, with `documentLevel: 'unanchored'`, as a textless page `COMMENT` the unanchored report names. **HTML-only:** the projection carries `originalText`, `htmlAnchor` and `htmlAdditionalTargets`, and pins `blockId` to `""`, offsets to `0` and no `startMeta` / `endMeta`; on the markdown `Viewer` a projected `COMMENT` with quoted text still re-anchors by whole-document text search, but with `blockId` `""` and offsets `0` it loses export ordering (every such row sorts first and ties), the "lines N-M" location label, disambiguation when the same text repeats (first match wins), and the no-flash meta restore; a host that needs those carries `blockId`, the offsets and the web-highlighter metas in its own projection.
+- **`onUnanchoredChange`** is keyed to the bridge's restore (one complete report per document after the restore batch, the empty set included) and complete over the `annotations` prop: textless page rows are reported without being posted, and a locally minted id the host swapped out of its list is not. It replaces a host's `mark-applied` bookkeeping for the unanchored set; the local-to-server mark swap itself stays host-side. **Nothing is delivered before the bridge's first post-restore report for a document (per reload generation):** a prop-side change before that point does not fire the callback, so do not gate host state on a prop-side delivery arriving first; treat the first call as the restore's verdict.
+- **`hooks/useHtmlRefresh({ fetchSnapshot, onSnapshot, onUnanchored?, onResult? })`**: the refresh cycle with the stale-response and document-change guards, backend behind `fetchSnapshot`.
+- **`components/HtmlSurfaceControls`**: the eye / refresh / pen header controls with Plannotator's markup and `labels` overrides.
+- **`AnnotationPanel` `unanchoredIds`**: an "Unanchored" chip on the listed cards.
+- **`HtmlViewer` `scrollBehavior`** (`'auto'` for reduced motion) and **`maxAdditionalTargets`** (a product cap the bridge honors too). With the cap enforced upstream (bridge toggle, parent trust boundary on submit and on restore, `projectHostThreads` `maxTargets` on read), a composed comment never reaches the host with more targets than the cap, so a host's own cap-dropped handling (`capDroppedTargets` from `buildPersistedHtmlAnchor`, or a message-counting listener) is unreachable in normal operation; keep it only as a backstop for rows written by an older host build or by another writer. Byte-budget drops (`sizeDroppedTargets`) are a separate path and remain reachable.
+- An `ExternalAnnotationTransport` whose `subscribe` emits `snapshot` on a host push keeps `useExternalAnnotations` off its fallback poll.
+
+See HANDOFF.md § "HTML annotation parity seams".
+
+#### The bridge script as an asset (`bridgeScriptUrl`; 0.33.0)
+
+By default `HtmlViewer` inlines its 185 KB in-page bridge script into every srcdoc document. A host that serves the package's generated `components/html-viewer/bridge-script.asset.js` as a static file can pass its URL instead:
+
+```ts
+import bridgeScriptUrl from "@plannotator/ui/components/html-viewer/bridge-script.asset.js?url";
+
+<HtmlViewer rawHtml={html} bridgeScriptUrl={bridgeScriptUrl} … />
+```
+
+The srcdoc then carries one classic `<script src>` in the exact place the inline script sat (at the end of `<head>`, before the body), the browser caches the asset across documents, and the bridge's `ready` message carries `BRIDGE_PROTOCOL_VERSION`, which the viewer checks: a stale cached asset (no stamp, or another version) logs one console warning naming both versions and shows a dismissible error banner in the surface (`onBridgeUnavailable` fires too); no `ready` within `bridgeReadyTimeoutMs` (default 5000) shows a timeout banner. The URL is resolved against your document's base (`document.baseURI`) before it is written into the srcdoc, never against the framed page, so a page's own `<base href>` cannot redirect it. Plannotator passes nothing and stays inline; none of this runs on the inline path. **CSP:** the package sets no CSP `<meta>` in the srcdoc document, and the frame is an opaque origin so the classic script needs no CORS (no `crossorigin` is set), but a CSP delivered as a header on your page is inherited by the frame: allow `script-src` for the asset's origin. Because the frame is an opaque origin, an asset served with `Cross-Origin-Resource-Policy: same-origin` (common alongside COEP) is blocked; serve it with a CORP that admits cross-origin loads, or without CORP. To also drop the inline literal from your viewer chunk, alias the package's `./bridge-script` resolution to the generated `bridge-script.lite` module (see HANDOFF.md § "HTML viewer bridge as an asset").
+
+#### Also blessed in 0.32.0: `shortcuts` and `utils/inputMethod`
+
+- **`@plannotator/ui/shortcuts`**: the declarative keyboard-shortcut engine (`defineShortcutScope`, `useShortcutScope`) and the per-surface scopes, including `useHtmlAnnotateShortcuts` for the Mod+Shift+A Annotate/Interact chord on HTML surfaces. Pure React plus `utils/platform`; no backend.
+- **`@plannotator/ui/utils/inputMethod`**: `getInputMethod(surface)` / `saveInputMethod(method, surface)` / `refreshInputMethodStamp(method)`, the per-surface pinpoint-or-drag preference with its TTL, persisted through the `storageBackend` seam.
+
+### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
+
+The engine that lets a browser-integrated agent (Chrome/Edge WebMCP, `document.modelContext`) call in-page tools on a document surface. Feature-detected once; a browser without the API sees no registration, no DOM, no network, no timers. Seam: `configurePlannotatorUI({ webmcp: { enabled, namePrefix } })`, default enabled with the `plannotator.` prefix; pass `enabled: false` to keep a host page tool-free, or your own prefix to namespace the tools beside your own. There is deliberately no confirmation seam: the catalog is read-and-comment only (no approve / submit / close tools), and the agent may only edit or remove comments stamped `source: "browser-agent"`.
+
+- `modelContext.ts` is the only file that spells the spec surface (local structural types, no `webmcp-types` dependency). A spec rename is a one-file change.
+- `useToolset({ id, active, build, deps, hooks })` attaches a named tool set to the document registry; handlers read through refs, so re-renders never re-register, and `active: false` aborts every registration (what Plannotator's Settings opt-out drives).
+- `AnnotationChangeTracker` / `buildNudges` are pure (no DOM): per-annotation `seq`, tombstones, a per-tab watermark with `since` override, and the nudge vocabulary every response carries.
+- A host with its own document state builds the same adapter-driven catalog Plannotator uses (`packages/editor/webmcp/documentTools.ts`, `buildDocumentTools(adapter, state, options)`) over its own getters and actions; multi-document pages should register one set whose tools take `path` (the folder-session shape) rather than one set per viewer (duplicate names across sets are skipped with a warning, never replaced).
+- Never register tools inside an untrusted iframe: the raw-HTML viewer's `sandbox="allow-scripts"` frame and the live-app frame carry no `allow="tools"`, and that is what keeps a framed page from impersonating the host's tools.
+
+The one additive data-model change that rides with it: `Annotation.inReplyTo` (threaded replies; the panel indents them under the parent, the export nests them, share links drop them).
+
 ## Consuming it (e.g. from Workspaces)
 
 ```bash
@@ -108,7 +164,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on `@plannotator/core` (exact-version lockstep). Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Versioned in lockstep with the repo. Publish `core` then `ui`: build each tarball with **`bun pm pack`** (resolves `workspace:*` to the exact version at pack time), then **`npm publish *.tgz --provenance --access public`** — the repo's existing flow.
+- Versioned together (currently `@plannotator/ui` 0.33.0 on `@plannotator/core` 0.25.0). `core` is bumped only when something under `packages/core` changed, so `ui` can advance alone: 0.33.0 is such a release, published on the already available core 0.25.0. When both change, publish `core` then `ui`: build each tarball with **`bun pm pack`** (resolves `workspace:*` to the exact version at pack time, from `bun.lock`, so run `bun install` after a bump), then **`npm publish *.tgz --provenance --access public`** — the repo's existing flow (`--provenance` needs CI OIDC; local publishes drop it, see HANDOFF.md "Publishing & versioning").
 
 ## The one rule
 

package/components/AnnotationPanel.tsx

@@ -38,6 +38,52 @@ const TrashCardIcon = () => (
   </svg>
 );
 
+/**
+ * Order annotations so every reply follows its parent (replies among
+ * themselves stay in creation order). A reply whose parent is absent renders
+ * as a top-level card. Without any `inReplyTo` the input order is returned
+ * unchanged, so annotations without replies render exactly as before.
+ */
+export function threadReplies(sorted: Annotation[]): Array<{ annotation: Annotation; isReply: boolean }> {
+  if (!sorted.some((a) => a.inReplyTo)) return sorted.map((annotation) => ({ annotation, isReply: false }));
+  const ids = new Set(sorted.map((a) => a.id));
+  const byParent = new Map<string, Annotation[]>();
+  for (const a of sorted) {
+    if (a.inReplyTo && ids.has(a.inReplyTo) && a.inReplyTo !== a.id) {
+      const list = byParent.get(a.inReplyTo) ?? [];
+      list.push(a);
+      byParent.set(a.inReplyTo, list);
+    }
+  }
+  const out: Array<{ annotation: Annotation; isReply: boolean }> = [];
+  const emitted = new Set<string>();
+  const emit = (a: Annotation, isReply: boolean) => {
+    if (emitted.has(a.id)) return;
+    emitted.add(a.id);
+    out.push({ annotation: a, isReply });
+    for (const reply of byParent.get(a.id) ?? []) emit(reply, true);
+  };
+  for (const a of sorted) {
+    if (a.inReplyTo && ids.has(a.inReplyTo) && a.inReplyTo !== a.id) continue;
+    emit(a, false);
+  }
+  for (const a of sorted) emit(a, false);
+  return out;
+}
+
+/** Timeline position of an annotation: its own time, or its thread root's for replies. */
+function threadTs(annotation: Annotation, all: Annotation[]): number {
+  let current = annotation;
+  const seen = new Set<string>();
+  while (current.inReplyTo && !seen.has(current.id)) {
+    seen.add(current.id);
+    const parent = all.find((a) => a.id === current.inReplyTo);
+    if (!parent) break;
+    current = parent;
+  }
+  return current.createdA;
+}
+
 interface DirectEditsPanelItem {
   id: string;
   title?: string;
@@ -89,6 +135,10 @@ interface PanelProps {
   /** Embed only the timeline body in a host-owned stage. The host owns the
     *  title, close control, visible-viewport geometry, and focus boundary. */
   presentation?: 'panel' | 'embedded';
+  /** Ids of annotations with no live location in the document (e.g. the
+    *  HTML viewer's onUnanchoredChange report after a refresh). Matching
+    *  cards show a small "Unanchored" chip. Absent: no chip, DOM unchanged. */
+  unanchoredIds?: ReadonlySet<string>;
 }
 
 export const AnnotationPanel: React.FC<PanelProps> = ({
@@ -115,6 +165,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   renderCardFooter,
   readOnly = false,
   presentation = 'panel',
+  unanchoredIds,
 }) => {
   const isMobile = useIsMobile();
   const embedded = presentation === 'embedded';
@@ -123,10 +174,19 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   const listRef = useRef<HTMLDivElement>(null);
   const sortedAnnotations = [...annotations].sort((a, b) => a.createdA - b.createdA);
   const sortedCodeAnnotations = [...codeAnnotations].sort((a, b) => a.createdAt - b.createdAt);
+  // Replies (`inReplyTo`) thread under their parent: each reply is lifted to
+  // sit right after its parent (and the parent's earlier replies) at the
+  // parent's timeline position. With no replies the order is untouched.
+  const threadedAnnotations = threadReplies(sortedAnnotations);
   const timelineEntries = [
-    ...sortedAnnotations.map(annotation => ({ kind: 'plan' as const, ts: annotation.createdA, annotation })),
-    ...sortedCodeAnnotations.map(annotation => ({ kind: 'code' as const, ts: annotation.createdAt, annotation })),
-  ].sort((a, b) => a.ts - b.ts);
+    ...threadedAnnotations.map(({ annotation, isReply }) => ({ kind: 'plan' as const, ts: annotation.createdA, annotation, isReply })),
+    ...sortedCodeAnnotations.map(annotation => ({ kind: 'code' as const, ts: annotation.createdAt, annotation, isReply: false })),
+  ].sort((a, b) => {
+    const ta = a.kind === 'plan' ? threadTs(a.annotation, sortedAnnotations) : a.ts;
+    const tb = b.kind === 'plan' ? threadTs(b.annotation, sortedAnnotations) : b.ts;
+    if (ta !== tb) return ta - tb;
+    return a.ts - b.ts;
+  });
   const totalCount = annotations.length + codeAnnotations.length + (editorAnnotations?.length ?? 0);
 
   // Scroll selected annotation card into view
@@ -221,6 +281,25 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
           <>
             {timelineEntries.map(entry => (
               entry.kind === 'plan' ? (
+                entry.isReply ? (
+                  <div
+                    key={entry.annotation.id}
+                    data-annotation-reply="true"
+                    className="ml-3 border-l-2 border-border/40 pl-1.5"
+                  >
+                    <AnnotationCard
+                      annotation={entry.annotation}
+                      isSelected={selectedId === entry.annotation.id}
+                      isMe={isCurrentUser(entry.annotation.author)}
+                      onSelect={() => onSelect(entry.annotation.id)}
+                      onDelete={() => onDelete(entry.annotation.id)}
+                      onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
+                      readOnly={readOnly}
+                      footer={renderCardFooter?.(entry.annotation)}
+                      unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
+                    />
+                  </div>
+                ) : (
                 <AnnotationCard
                   key={entry.annotation.id}
                   annotation={entry.annotation}
@@ -231,7 +310,9 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
                   readOnly={readOnly}
                   footer={renderCardFooter?.(entry.annotation)}
+                  unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
                 />
+                )
               ) : (
                 <CodeAnnotationCard
                   key={entry.annotation.id}
@@ -458,7 +539,9 @@ const AnnotationCard: React.FC<{
   onEdit?: (updates: Partial<Annotation>) => void;
   readOnly?: boolean;
   footer?: React.ReactNode;
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer }) => {
+  /** The annotation has no live location in the document (host-reported). */
+  unanchored?: boolean;
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, unanchored = false }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -563,6 +646,15 @@ const AnnotationCard: React.FC<{
             {annotation.pageUrl}
           </span>
         )}
+        {unanchored && (
+          <span
+            data-annotation-unanchored="true"
+            className="text-[9px] px-1.5 py-0.5 rounded font-medium bg-muted text-muted-foreground"
+            title="This comment no longer matches a location in the document"
+          >
+            Unanchored
+          </span>
+        )}
         <span className="text-[10px] text-muted-foreground/50 truncate">
           {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdA)}
         </span>

package/components/AnnotationToolbar.tsx

@@ -2,20 +2,13 @@ import React, { useState, useEffect, useRef, useMemo } from "react";
 import { AnnotationType } from "../types";
 import { createPortal } from "react-dom";
 import { useDismissOnOutsideAndEscape } from "../hooks/useDismissOnOutsideAndEscape";
-import { type QuickLabel, getQuickLabels } from "../utils/quickLabels";
+import { type QuickLabel, getQuickLabels, THUMBS_UP_LABEL } from "../utils/quickLabels";
 import { copyTextToClipboard } from "../utils/clipboard";
 import { acquireTypeToCommentCapture } from "../shortcuts/plan-review/annotationMode.shortcuts";
 import { FloatingQuickLabelPicker } from "./FloatingQuickLabelPicker";
 
 type PositionMode = 'center-above' | 'top-right';
 
-const THUMBS_UP_LABEL: QuickLabel = {
-  id: 'thumbs-up',
-  emoji: '👍',
-  text: 'Looks good',
-  color: 'green',
-};
-
 const isEditableElement = (node: EventTarget | Element | null): boolean => {
   if (!(node instanceof Element)) return false;
   if (node.matches('input, textarea, select, [role="textbox"]')) return true;
@@ -34,9 +27,11 @@ interface AnnotationToolbarProps {
   onQuickLabel?: (label: QuickLabel) => void;
   /** Text to copy when the button is clicked */
   copyText?: string;
-  /** Comment-only surfaces (HTML / live-app viewer): hide the Delete action.
-   *  Markdown surfaces keep the full toolbar. Quick labels are already gated
-   *  by the presence of onQuickLabel. */
+  /** Comment-only surfaces (HTML / live-app viewer): hide the Delete action,
+   *  the quick-label picker, and the Alt+digit label shortcuts. A provided
+   *  onQuickLabel then renders ONLY the hardcoded 👍 "Looks good" button —
+   *  the one label affordance restored to these surfaces. Markdown surfaces
+   *  keep the full toolbar. */
   commentOnly?: boolean;
   /** Hide the copy button (set when a keyboard copy handler exists) */
   hideCopyButton?: boolean;
@@ -132,14 +127,17 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
         return;
       }
 
-      // Alt+N applies quick label (picker closed)
+      // Alt+N applies quick label (picker closed). Comment-only surfaces
+      // suppress this path: their only label affordance is the 👍 button.
       const isDigit = (e.code >= 'Digit1' && e.code <= 'Digit9') || e.code === 'Digit0';
       if (isDigit && !e.ctrlKey && !e.metaKey && e.altKey) {
         e.preventDefault();
-        const digit = parseInt(e.code.slice(5), 10);
-        const index = digit === 0 ? 9 : digit - 1;
-        if (index < quickLabels.length) {
-          onQuickLabel?.(quickLabels[index]);
+        if (!commentOnly) {
+          const digit = parseInt(e.code.slice(5), 10);
+          const index = digit === 0 ? 9 : digit - 1;
+          if (index < quickLabels.length) {
+            onQuickLabel?.(quickLabels[index]);
+          }
         }
         return;
       }
@@ -160,7 +158,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
       window.removeEventListener("keydown", handleKeyDown);
       releaseCapture();
     };
-  }, [onClose, onRequestComment, onQuickLabel, quickLabels, showQuickLabels]);
+  }, [onClose, onRequestComment, onQuickLabel, quickLabels, showQuickLabels, commentOnly]);
 
   useDismissOnOutsideAndEscape({
     enabled: !showQuickLabels,
@@ -238,20 +236,22 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
         />
         {onQuickLabel && (
           <>
-            <ToolbarButton
-              ref={zapButtonRef}
-              onClick={() => setShowQuickLabels(prev => !prev)}
-              icon={<ZapIcon />}
-              label="Quick label"
-              className={showQuickLabels ? "text-amber-500 bg-amber-500/10" : "text-amber-500 hover:bg-amber-500/10"}
-            />
+            {!commentOnly && (
+              <ToolbarButton
+                ref={zapButtonRef}
+                onClick={() => setShowQuickLabels(prev => !prev)}
+                icon={<ZapIcon />}
+                label="Quick label"
+                className={showQuickLabels ? "text-amber-500 bg-amber-500/10" : "text-amber-500 hover:bg-amber-500/10"}
+              />
+            )}
             <ToolbarButton
               onClick={() => onQuickLabel(THUMBS_UP_LABEL)}
               icon={<span className="block w-4 h-4 text-sm leading-4 text-center">👍</span>}
               label="Looks good"
               className="hover:bg-green-500/10"
             />
-            {showQuickLabels && zapButtonRef.current && (
+            {!commentOnly && showQuickLabels && zapButtonRef.current && (
               <FloatingQuickLabelPicker
                 anchorEl={zapButtonRef.current}
                 onSelect={(label) => {

package/components/CommentPopover.tsx

@@ -53,6 +53,14 @@ interface CommentPopoverProps {
   initialText?: string;
   /** Called on submit with comment text and optional images */
   onSubmit: (text: string, images?: ImageAttachment[]) => void;
+  /**
+   * One-click "Looks good" action (comment-only HTML/live surfaces, where
+   * pinpoint clicks open this composer directly and never see the selection
+   * toolbar's 👍). Renders a thumbs-up button in the footer; disabled once
+   * the user has typed or attached anything, so a click can never discard a
+   * draft. The parent owns annotation creation and closing.
+   */
+  onQuickLookGood?: () => void;
   /** Optional live draft observer for submit paths outside the popover. */
   onDraftChange?: (text: string, images?: ImageAttachment[]) => void;
   /** Called when popover is closed/cancelled */
@@ -148,6 +156,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   isGlobal,
   initialText = '',
   onSubmit,
+  onQuickLookGood,
   onDraftChange,
   onClose,
   draftKey,
@@ -521,6 +530,21 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     (allowEmptySubmit && initialText.trim().length > 0);
   const canAskAI = !!onAskAI && !askAIDisabled && text.trim().length > 0;
 
+  // Shared by both footers. Disabled once anything is typed or attached so a
+  // click can never discard a draft; with content present, Save is the path.
+  const quickLookGoodButton = onQuickLookGood ? (
+    <button
+      type="button"
+      onClick={onQuickLookGood}
+      disabled={hasUnsavedContent}
+      className="inline-flex items-center gap-1 px-2 py-1.5 text-xs font-medium rounded-md text-muted-foreground hover:text-foreground hover:bg-green-500/10 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+      title={hasUnsavedContent ? 'Clear the comment to use Looks good' : 'Add "Looks good" without typing'}
+    >
+      <span aria-hidden="true">👍</span>
+      Looks good
+    </button>
+  ) : null;
+
   if (mode === 'dialog') {
     return createPortal(
       <div
@@ -632,6 +656,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
               {!coarsePointer && (
                 <span className="text-[10px] text-muted-foreground">{submitHint}</span>
               )}
+              {quickLookGoodButton}
               {onAskAI && (
                 <button
                   onClick={handleAskAI}
@@ -781,6 +806,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           {!coarsePointer && (
             <span className="text-[10px] text-muted-foreground">{submitHint}</span>
           )}
+          {quickLookGoodButton}
           {onAskAI && (
             <button
               onClick={handleAskAI}

package/components/GraphvizBlock.tsx

@@ -1,6 +1,6 @@
 import React, { useRef, useState, useEffect, useCallback } from 'react';
 import { createPortal } from 'react-dom';
-import { instance } from '@viz-js/viz';
+import type { Viz } from '@viz-js/viz';
 import type { Block } from '../types';
 
 interface ViewBox {
@@ -14,13 +14,52 @@ const ZOOM_STEP = 0.25;
 const MIN_ZOOM = 0.25;
 const MAX_ZOOM = 8;
 
-let vizInstancePromise: ReturnType<typeof instance> | null = null;
-
-function getVizInstance() {
-  vizInstancePromise ??= instance();
+/**
+ * The Graphviz engine (about 1.2 MB of Emscripten JS) is imported inside the
+ * render effect, not statically, so a host that bundles by route only fetches
+ * it when a dot fence is on the page. WASM instantiation was already deferred
+ * to first render; in Plannotator's single-file builds the import is inlined
+ * and resolves in a microtask ahead of a render that was already asynchronous.
+ */
+const loadVizInstance = (): Promise<Viz> => import('@viz-js/viz').then((m) => m.instance());
+
+let vizLoader = loadVizInstance;
+let vizInstancePromise: Promise<Viz> | null = null;
+
+/**
+ * Delay before the one automatic re-attempt after a failed engine import.
+ * Only chunking hosts can fail here (a single-file build never fetches).
+ */
+let runtimeRetryDelayMs = 750;
+
+/**
+ * Memoized engine. A rejected load is dropped from the memo so the next call
+ * (the automatic re-attempt, a later mount, or the Retry button) issues a
+ * fresh import() instead of replaying the cached rejection.
+ */
+function getVizInstance(): Promise<Viz> {
+  if (!vizInstancePromise) {
+    const attempt = vizLoader().catch((err: unknown) => {
+      if (vizInstancePromise === attempt) vizInstancePromise = null;
+      throw err;
+    });
+    vizInstancePromise = attempt;
+  }
   return vizInstancePromise;
 }
 
+/** Test hook: stand in for the engine import and shorten the retry delay. */
+export function __setVizLoaderForTests(
+  loader: (() => Promise<Viz>) | undefined,
+  options?: { retryDelayMs?: number },
+): void {
+  vizLoader = loader ?? loadVizInstance;
+  vizInstancePromise = null;
+  runtimeRetryDelayMs = options?.retryDelayMs ?? 750;
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
 function parseViewBox(svgEl: SVGSVGElement): ViewBox | null {
   const raw = svgEl.getAttribute('viewBox');
   if (!raw) return null;
@@ -107,6 +146,11 @@ export const GraphvizBlock: React.FC<{ block: Block }> = ({ block }) => {
   const containerRef = useRef<HTMLDivElement>(null);
   const [svg, setSvg] = useState('');
   const [error, setError] = useState<string | null>(null);
+  // True when the failure was the engine import itself (a chunking host's
+  // fetch), which is the only failure a Retry can change; a dot syntax error
+  // keeps the panel exactly as it always was.
+  const [runtimeUnavailable, setRuntimeUnavailable] = useState(false);
+  const [retryToken, setRetryToken] = useState(0);
   const [showSource, setShowSource] = useState(false);
   const [isExpanded, setIsExpanded] = useState(false);
 
@@ -158,8 +202,28 @@ export const GraphvizBlock: React.FC<{ block: Block }> = ({ block }) => {
     let cancelled = false;
 
     const renderDiagram = async () => {
+      let viz: Viz;
+      try {
+        try {
+          viz = await getVizInstance();
+        } catch {
+          // Transient chunk failure on a chunking host: one automatic
+          // re-attempt with a fresh import() after a short delay. In a
+          // single-file build the first await never rejects, so this branch
+          // is unreachable there and the success path is unchanged.
+          await wait(runtimeRetryDelayMs);
+          if (cancelled) return;
+          viz = await getVizInstance();
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setRuntimeUnavailable(true);
+          setSvg('');
+        }
+        return;
+      }
       try {
-        const viz = await getVizInstance();
         const renderedSvg = await viz.renderString(block.content, { format: 'svg' });
         const cleaned = renderedSvg
           .replace(/ width="[^"]*"/, ' width="100%"')
@@ -177,10 +241,12 @@ export const GraphvizBlock: React.FC<{ block: Block }> = ({ block }) => {
           naturalBoundsRef.current = parseViewBoxFromMarkup(cleaned);
           setSvg(cleaned);
           setError(null);
+          setRuntimeUnavailable(false);
         }
       } catch (err) {
         if (!cancelled) {
           setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setRuntimeUnavailable(false);
           setSvg('');
         }
       }
@@ -191,7 +257,7 @@ export const GraphvizBlock: React.FC<{ block: Block }> = ({ block }) => {
     return () => {
       cancelled = true;
     };
-  }, [block.content]);
+  }, [block.content, retryToken]);
 
   useEffect(() => {
     zoomLevelRef.current = 1;
@@ -362,6 +428,19 @@ export const GraphvizBlock: React.FC<{ block: Block }> = ({ block }) => {
             <path strokeLinecap="round" strokeLinejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
           </svg>
           <span className="text-xs text-destructive font-medium">Graphviz Error</span>
+          {runtimeUnavailable && (
+            <button
+              type="button"
+              onClick={() => {
+                setError(null);
+                setRetryToken((token) => token + 1);
+              }}
+              className="ml-auto rounded-md border border-destructive/30 px-2 py-0.5 text-xs text-destructive hover:bg-destructive/10"
+              title="Retry loading the diagram renderer"
+            >
+              Retry
+            </button>
+          )}
         </div>
         <pre className="p-3 text-xs text-destructive/80 overflow-x-auto">{error}</pre>
         <pre className="p-3 text-xs text-muted-foreground bg-muted/30 border-t border-border/30 overflow-x-auto">