@plannotator/ui 0.31.0 → 0.32.0

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

@@ -339,6 +339,17 @@ export const BRIDGE_SCRIPT = `(function() {
   var pendingMultiTargets = []; // { key, el, anchor, label, text, box }
   var multiTargetSeq = 0;
   var MAX_MULTI_TARGETS = 16;
+  // Per-draft cap on additional targets: the parent may lower it on
+  // arm-multi-select ({ max }) to its product cap so the toggle stops where
+  // the saved annotation would. Never above MAX_MULTI_TARGETS; reset with
+  // the arm on every draft.
+  var multiSelectMax = MAX_MULTI_TARGETS;
+  function clampMultiSelectMax(value) {
+    if (typeof value !== 'number' || !isFinite(value)) return MAX_MULTI_TARGETS;
+    var whole = Math.floor(value);
+    if (whole < 0) return 0;
+    return whole > MAX_MULTI_TARGETS ? MAX_MULTI_TARGETS : whole;
+  }
   // Live mode clamps the INPUT METHOD to pinpoint (click = element). Text
   // drag-selection is a separate, always-on channel — see the mouseup handler
   // — so the clamp only decides what a plain click does, never whether text
@@ -637,6 +648,10 @@ export const BRIDGE_SCRIPT = `(function() {
         && e.data.key === pendingPinKey
       ) {
         multiSelectArmed = true;
+        // Optional product cap for THIS draft; absent keeps the bridge's own.
+        multiSelectMax = e.data.max === undefined
+          ? MAX_MULTI_TARGETS
+          : clampMultiSelectMax(e.data.max);
       }
     }
 
@@ -655,14 +670,25 @@ export const BRIDGE_SCRIPT = `(function() {
       // Selecting an annotation scrolls its first resolved target into view
       // and flashes the overlay focus highlight over EVERY rect of EVERY
       // target — never a class write on page elements, and never only the
-      // first fragment of a multi-paragraph selection.
-      scrollToAnnotation(e.data.id);
+      // first fragment of a multi-paragraph selection. The optional
+      // behavior lets the parent pass its reduced-motion preference across
+      // the boundary; absent means smooth, as before.
+      scrollToAnnotation(e.data.id, e.data.behavior === 'auto' ? 'auto' : 'smooth');
     }
 
     else if (type === PREFIX + 'focus-mark') {
       focusAnnotationRecord(typeof e.data.id === 'string' ? e.data.id : null, false);
     }
 
+    else if (type === PREFIX + 'report-unanchored') {
+      // The parent posted its restore batch and wants the complete set once
+      // the next complete overlay pass has run, even if the set is unchanged
+      // (empty included). Messages are processed in order, so the pass this
+      // schedules sees every find-and-mark posted before this request.
+      unanchoredReportRequested = true;
+      schedulePinpointReconcile();
+    }
+
     else if (type === PREFIX + 'set-input-method') {
       // Live mode clamps the input method to pinpoint (what a plain click
       // does); text drag-selection commenting stays live regardless.
@@ -1488,6 +1514,10 @@ export const BRIDGE_SCRIPT = `(function() {
   // whose records are removed and therefore invisible to the per-pass scan.
   var lastUnanchoredKey = '[]';
   var restoreFailedIds = new Set();
+  // Set by report-unanchored: the parent asks for the complete set after
+  // its restore batch, so the next COMPLETE pass emits even when the set
+  // did not change (an all-restored document reports its empty set once).
+  var unanchoredReportRequested = false;
   function emitUnanchored(deadRecordIds) {
     var seen = new Set();
     var combined = [];
@@ -1506,7 +1536,8 @@ export const BRIDGE_SCRIPT = `(function() {
     combined.sort();
     if (combined.length > 512) combined = combined.slice(0, 512);
     var key = JSON.stringify(combined);
-    if (key === lastUnanchoredKey) return;
+    if (key === lastUnanchoredKey && !unanchoredReportRequested) return;
+    unanchoredReportRequested = false;
     lastUnanchoredKey = key;
     // postToParent, not a raw '*' post: live sessions stamp the session
     // token and post only to the listed editor origins, and the parent
@@ -2495,7 +2526,7 @@ export const BRIDGE_SCRIPT = `(function() {
     }
   }
 
-  function scrollToAnnotation(id) {
+  function scrollToAnnotation(id, behavior) {
     var record = findAnnRecord(id);
     if (!record) return;
     beginDeadSearchPass(Infinity); // user-initiated one-shot: never budget-starved
@@ -2511,7 +2542,7 @@ export const BRIDGE_SCRIPT = `(function() {
       }
     }
     if (scrollEl) {
-      try { scrollEl.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (ex) {}
+      try { scrollEl.scrollIntoView({ behavior: behavior || 'smooth', block: 'center' }); } catch (ex) {}
     }
     focusAnnotationRecord(id, true);
   }
@@ -2693,6 +2724,7 @@ export const BRIDGE_SCRIPT = `(function() {
     pendingPinPoint = null;
     pendingPinViaPinpoint = false;
     multiSelectArmed = false;
+    multiSelectMax = MAX_MULTI_TARGETS;
     hidePinpointBox();
   }
 
@@ -2857,8 +2889,9 @@ export const BRIDGE_SCRIPT = `(function() {
         }
       }
     }
-    // Cap at the source: never grow the draft past the parent-side DTO cap.
-    if (pendingMultiTargets.length >= MAX_MULTI_TARGETS) return;
+    // Cap at the source: never grow the draft past the parent-side DTO cap
+    // (or the lower product cap the parent armed this draft with).
+    if (pendingMultiTargets.length >= multiSelectMax) return;
     var point = normalizePointInElement(el, clickPoint);
     if (anchor && point) anchor.point = point;
     var label = pinpointHoverLabel(el);
@@ -2961,6 +2994,7 @@ export const BRIDGE_SCRIPT = `(function() {
     // drafts (comment -> quick label) leaves a stale arm and the bridge
     // accumulates pins the saved annotation will not carry.
     multiSelectArmed = false;
+    multiSelectMax = MAX_MULTI_TARGETS;
     pendingPinEl = el;
     pendingPinAnchor = buildElementAnchor(el);
     pendingPinKey = makeTargetKey();

package/components/html-viewer/hostThreads.ts

@@ -0,0 +1,37 @@
+/**
+ * Host-side helpers for the raw-HTML viewer, re-exported from
+ * `@plannotator/core/html-anchor` with the package's `Annotation` type.
+ *
+ * `projectHostThreads` turns a host's stored rows into the `annotations`
+ * prop (output order == marker numbering); `buildPersistedHtmlAnchor` trims a
+ * composed comment's anchor to a bounded record the host can persist. Both
+ * are pure and dependency-free (they live in `@plannotator/core`).
+ */
+import {
+  projectHostThreads as projectHostThreadsCore,
+  type HostThread,
+  type ProjectHostThreadsOptions,
+} from "@plannotator/core/html-anchor";
+import type { Annotation } from "../../types";
+
+export {
+  buildPersistedHtmlAnchor,
+  type BuildPersistedHtmlAnchorOptions,
+  type HostThread,
+  type PersistedHtmlAnchor,
+  type PersistedHtmlAnchorResult,
+  type ProjectHostThreadsOptions,
+} from "@plannotator/core/html-anchor";
+
+/**
+ * Project stored host rows onto the viewer's `annotations` prop, in the
+ * host's order (which becomes the marker numbering). See the core function
+ * for the projection rules; the `type` literals it emits are the string
+ * values of `AnnotationType`, so the cast below is representation-exact.
+ */
+export function projectHostThreads(
+  threads: readonly HostThread[],
+  options?: ProjectHostThreadsOptions,
+): Annotation[] {
+  return projectHostThreadsCore(threads, options) as unknown as Annotation[];
+}

package/components/html-viewer/index.ts

@@ -1 +1,10 @@
 export { HtmlViewer, type HtmlViewerProps } from "./HtmlViewer";
+export {
+  buildPersistedHtmlAnchor,
+  projectHostThreads,
+  type BuildPersistedHtmlAnchorOptions,
+  type HostThread,
+  type PersistedHtmlAnchor,
+  type PersistedHtmlAnchorResult,
+  type ProjectHostThreadsOptions,
+} from "./hostThreads";

package/components/html-viewer/unanchored.ts

@@ -0,0 +1,47 @@
+import { AnnotationType, type Annotation } from "../../types";
+
+/**
+ * A page-anchored row the viewer can never post to the bridge: nothing to
+ * find it by (no quoted text, no element anchor, no additional target
+ * anchor). Document-level comments are excluded on purpose: a
+ * GLOBAL_COMMENT has no page location by design and is not "unanchored".
+ */
+export function isTextlessPageAnnotation(annotation: Annotation): boolean {
+  if (annotation.type === AnnotationType.GLOBAL_COMMENT) return false;
+  if (annotation.originalText) return false;
+  if (annotation.htmlAnchor) return false;
+  return !(annotation.htmlAdditionalTargets ?? []).some((target) => !!target.anchor);
+}
+
+/**
+ * The host-facing unanchored set: the bridge's report (ids with no live
+ * representation on the page) completed with what the bridge cannot see.
+ *
+ * - Textless page rows are added: they were never posted, so the bridge
+ *   cannot report them, yet they have no marker and no highlight.
+ * - An id this viewer minted for a locally created comment (`create-mark`)
+ *   that the host never carried in `annotations`, or has since swapped out
+ *   for its own id, is dropped: the host holds no card for it, so naming it
+ *   would be noise. Every other bridge id passes through untouched, so a
+ *   host that paints through the imperative handle keeps today's delivery.
+ *
+ * Sorted and deduplicated like the bridge's own emission. With no textless
+ * rows and no swapped-out minted ids the result is exactly the bridge list.
+ */
+export function mergeUnanchoredIds(input: {
+  bridgeIds: readonly string[];
+  annotations: readonly Annotation[];
+  createdIds: ReadonlySet<string>;
+}): string[] {
+  const known = new Set<string>();
+  for (const annotation of input.annotations) known.add(annotation.id);
+  const out = new Set<string>();
+  for (const id of input.bridgeIds) {
+    if (input.createdIds.has(id) && !known.has(id)) continue;
+    out.add(id);
+  }
+  for (const annotation of input.annotations) {
+    if (isTextlessPageAnnotation(annotation)) out.add(annotation.id);
+  }
+  return [...out].sort();
+}

package/components/html-viewer/useHtmlAnnotation.ts

@@ -1,6 +1,6 @@
 import { useState, useEffect, useCallback, useRef, type RefObject } from "react";
 import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type ImageAttachment } from "../../types";
-import type { QuickLabel } from "../../utils/quickLabels";
+import { THUMBS_UP_LABEL, type QuickLabel } from "../../utils/quickLabels";
 import { getIdentity } from "../../utils/identity";
 import type {
   ToolbarState,
@@ -18,6 +18,13 @@ function nextHtmlAnnId(): string {
   return `html-ann-${Date.now().toString(36)}-${(htmlAnnSeq++).toString(36)}`;
 }
 
+/** Ids minted by this module for locally created annotations (create-mark).
+ * Module-scoped like the sequence above: a host that swaps a local id for
+ * its own server id keeps the local mark until it removes it, and the
+ * unanchored union needs to recognise such ids whichever viewer instance
+ * minted them. Bounded: only ids from this page load, one entry per create. */
+const mintedHtmlAnnIds = new Set<string>();
+
 function htmlCommentDraftKey(
   text: string,
   anchor?: HtmlElementAnchor | null,
@@ -129,6 +136,20 @@ export interface UseHtmlAnnotationOptions {
    *  empty on recovery. Delivered in readOnly mode too: view-only surfaces
    *  are exactly where silently missing markers would go unnoticed. */
   onUnanchoredChange?: (ids: string[]) => void;
+  /** Product cap on additional (shift-click) targets per comment, 0..16.
+   *  Applied at the trust boundary, on submit, on restore, and carried to
+   *  the bridge on arm-multi-select so the in-page toggle stops at the
+   *  same number. Absent: the package's 16, and the arm message is unchanged. */
+  maxAdditionalTargets?: number;
+  /** scrollIntoView behavior for scroll-to (selecting an annotation).
+   *  Absent: smooth, as before; pass 'auto' to honor reduced motion. */
+  scrollBehavior?: 'smooth' | 'auto';
+}
+
+/** Clamp a host cap into the package's bound; anything unusable is the default. */
+export function resolveMaxAdditionalTargets(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return MAX_ADDITIONAL_TARGETS;
+  return Math.max(0, Math.min(MAX_ADDITIONAL_TARGETS, Math.floor(value)));
 }
 
 function postToIframe(
@@ -365,6 +386,8 @@ export function useHtmlAnnotation({
   onPageChange,
   onBridgePointer,
   onUnanchoredChange,
+  maxAdditionalTargets,
+  scrollBehavior,
 }: UseHtmlAnnotationOptions): Omit<
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
@@ -377,6 +400,13 @@ export function useHtmlAnnotation({
   flashDraftTarget: (key: string) => void;
   /** Bumped after every target add/remove so the composer can refocus its textarea. */
   composerFocusToken: number;
+  /** Composer one-click "Looks good": submits the hardcoded positive label
+   *  with the same anchor and multi-select targets a typed comment would carry. */
+  handleCommentLooksGood: () => void;
+  /** Ids this module minted for locally created annotations (create-mark),
+   *  for the unanchored union: a minted id the host never listed is a
+   *  swapped-out local mark, not a host row. Read-only, stable identity. */
+  createdAnnotationIds: ReadonlySet<string>;
 } {
   const [toolbarState, setToolbarState] = useState<ToolbarState | null>(null);
   const [commentPopover, setCommentPopover] = useState<CommentPopoverState | null>(null);
@@ -417,6 +447,12 @@ export function useHtmlAnnotation({
   liveRef.current = live ?? null;
   const onPageChangeRef = useRef(onPageChange);
   onPageChangeRef.current = onPageChange;
+  // 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));
+  maxTargetsRef.current = resolveMaxAdditionalTargets(maxAdditionalTargets);
+  const hostCapRef = useRef(maxAdditionalTargets !== undefined);
+  hostCapRef.current = maxAdditionalTargets !== undefined;
 
   const anchorRef = useRef<HTMLDivElement | null>(null);
 
@@ -577,6 +613,7 @@ export function useHtmlAnnotation({
             post({
               type: `${PREFIX}arm-multi-select`,
               key: message.targetKey,
+              ...(hostCapRef.current ? { max: maxTargetsRef.current } : {}),
             });
           }
         } else {
@@ -596,7 +633,7 @@ export function useHtmlAnnotation({
         if (
           commentPopoverRef.current
           && targets.length > 0
-          && targets.length < 1 + MAX_ADDITIONAL_TARGETS
+          && targets.length < 1 + maxTargetsRef.current
           && !targets.some((t) => t.key === message.key)
         ) {
           setDraftTargets([
@@ -712,6 +749,9 @@ export function useHtmlAnnotation({
       post({
         type: `${PREFIX}scroll-to`,
         id: selectedAnnotationId,
+        // Only an explicit host preference rides along; the default message
+        // is unchanged and the bridge scrolls smoothly as before.
+        ...(scrollBehavior ? { behavior: scrollBehavior } : {}),
       });
     } else {
       post({
@@ -719,7 +759,7 @@ export function useHtmlAnnotation({
         id: null,
       });
     }
-  }, [selectedAnnotationId, post]);
+  }, [selectedAnnotationId, post, scrollBehavior]);
 
   const handleAnnotate = useCallback(
     (type: AnnotationType) => {
@@ -728,6 +768,7 @@ export function useHtmlAnnotation({
       if (!text || type !== AnnotationType.DELETION) return;
 
       const id = nextHtmlAnnId();
+      mintedHtmlAnnIds.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "deletion" });
       onAddRef.current?.({
         id,
@@ -778,7 +819,7 @@ export function useHtmlAnnotation({
       const targets = draftTargetsRef.current;
       const additionalTargets: HtmlAnnotationTarget[] | undefined =
         targets.length > 1
-          ? targets.slice(1, 1 + MAX_ADDITIONAL_TARGETS).map((t) => ({
+          ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
               label: t.label,
               text: t.text,
               anchor: t.anchor ?? undefined,
@@ -786,6 +827,7 @@ export function useHtmlAnnotation({
           : undefined;
 
       const id = nextHtmlAnnId();
+      mintedHtmlAnnIds.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
@@ -810,6 +852,51 @@ export function useHtmlAnnotation({
     [post],
   );
 
+  // The composer's one-click "Looks good" (the restored thumbs-up for
+  // comment-only surfaces, where pinpoint clicks land straight in the
+  // composer and never see the selection toolbar). Mirrors
+  // handleCommentSubmit — same anchor, same multi-select targets — but
+  // emits the hardcoded positive label instead of typed prose.
+  const handleCommentLooksGood = useCallback(() => {
+    if (!enabledRef.current) return;
+    const text = commentPopoverRef.current?.selectedText || pendingTextRef.current;
+    if (!text) return;
+
+    const targets = draftTargetsRef.current;
+    const additionalTargets: HtmlAnnotationTarget[] | undefined =
+      targets.length > 1
+        ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
+            label: t.label,
+            text: t.text,
+            anchor: t.anchor ?? undefined,
+          }))
+        : undefined;
+
+    const id = nextHtmlAnnId();
+    mintedHtmlAnnIds.add(id);
+    post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
+    onAddRef.current?.({
+      id,
+      blockId: "",
+      startOffset: 0,
+      endOffset: 0,
+      type: AnnotationType.COMMENT,
+      text: THUMBS_UP_LABEL.text,
+      originalText: text,
+      isQuickLabel: true,
+      quickLabelTip: THUMBS_UP_LABEL.tip,
+      author: getIdentity(),
+      createdA: Date.now(),
+      htmlAnchor: pendingAnchorRef.current ?? undefined,
+      htmlAdditionalTargets: additionalTargets,
+    });
+
+    setCommentPopover(null);
+    setDraftTargets([]);
+    pendingTextRef.current = "";
+    pendingAnchorRef.current = null;
+  }, [post]);
+
   const handleCommentClose = useCallback(() => {
     post({ type: `${PREFIX}cancel-selection` });
     setCommentPopover(null);
@@ -846,6 +933,7 @@ export function useHtmlAnnotation({
       const text = pendingTextRef.current;
       if (!text) return;
       const id = nextHtmlAnnId();
+      mintedHtmlAnnIds.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
@@ -906,7 +994,7 @@ export function useHtmlAnnotation({
         const additionalAnchors = (ann.htmlAdditionalTargets ?? [])
           .map((t) => t.anchor)
           .filter((a): a is HtmlElementAnchor => !!a)
-          .slice(0, MAX_ADDITIONAL_TARGETS);
+          .slice(0, maxTargetsRef.current);
         post({
           type: `${PREFIX}find-and-mark`,
           id: ann.id,
@@ -931,6 +1019,7 @@ export function useHtmlAnnotation({
     handleToolbarClose,
     handleRequestComment,
     handleCommentSubmit,
+    handleCommentLooksGood,
     handleCommentClose,
     handleFloatingQuickLabel,
     handleQuickLabelPickerDismiss,
@@ -941,5 +1030,6 @@ export function useHtmlAnnotation({
     removeDraftTarget,
     flashDraftTarget,
     composerFocusToken,
+    createdAnnotationIds: mintedHtmlAnnIds,
   };
 }

package/configure.ts

@@ -8,6 +8,9 @@ import { setDraftTransport, type DraftTransport } from './hooks/useAnnotationDra
 import { setExternalAnnotationTransport, type ExternalAnnotationTransport } from './hooks/useExternalAnnotations';
 import { setAITransport, type AITransport } from './hooks/useAIChat';
 import { setSkillCatalogTransport, setSkillContentTransport, type SkillCatalogTransport, type SkillContentTransport } from './utils/skillCatalog';
+import { setWebMcpPolicy, type WebMcpPolicy } from './webmcp/policy';
+import { setMathRendererLoader, type MathRenderer, type MathRendererLoader } from './utils/math';
+import { setIdentityGenerator, type IdentityGenerator } from './utils/generateIdentity';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
@@ -31,6 +34,10 @@ export type {
   SkillCatalogTransport,
   SkillContentTransport,
   ServerSyncFn,
+  WebMcpPolicy,
+  MathRenderer,
+  MathRendererLoader,
+  IdentityGenerator,
 };
 
 type ExternalAnnotationBase = { id: string; source?: string };
@@ -56,6 +63,28 @@ export interface PlannotatorUIConfig {
   /** Human-only skill contents request for feedback injection. Default: `GET /api/skills/content?name=` on the page origin. */
   skillContentTransport?: SkillContentTransport;
   serverSync?: ServerSyncFn;
+  /**
+   * WebMCP provider policy: `{ enabled, namePrefix }`. Default: enabled
+   * whenever the browser exposes `document.modelContext`, with the
+   * `plannotator.` prefix. There is no confirmation seam because the catalog
+   * exposes nothing consequential: no tool decides, submits or closes.
+   */
+  webmcp?: WebMcpPolicy;
+  /**
+   * How the math renderer is loaded when no renderer is registered before the
+   * first math node renders. Default: `import('katex')` (JS only; the
+   * stylesheet stays the host's job). A host that wants KaTeX and its CSS on
+   * one lazy chunk passes a loader that imports both. Hosts that want math
+   * typeset on the first commit instead import `@plannotator/ui/utils/math-eager`.
+   */
+  mathRendererLoader?: MathRendererLoader;
+  /**
+   * Synchronous generator for the default "tater" display name, used only when
+   * no `identityProvider` is installed. Default: a small built-in pool of the
+   * same `adjective-noun-tater` shape. Plannotator registers the full
+   * dictionary by importing `@plannotator/ui/utils/identity-tater`.
+   */
+  identityGenerator?: IdentityGenerator;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -73,6 +102,9 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.skillCatalogTransport) setSkillCatalogTransport(config.skillCatalogTransport);
   if (config.skillContentTransport) setSkillContentTransport(config.skillContentTransport);
   if (config.serverSync) configStore.setServerSync(config.serverSync);
+  if (config.webmcp) setWebMcpPolicy(config.webmcp);
+  if (config.mathRendererLoader) setMathRendererLoader(config.mathRendererLoader);
+  if (config.identityGenerator) setIdentityGenerator(config.identityGenerator);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/hooks/useHtmlRefresh.ts

@@ -0,0 +1,149 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+
+/** What a host's `fetchSnapshot` resolves to. */
+export type HtmlRefreshSnapshot =
+  | { status: 'ok'; rawHtml: string }
+  | { status: 'missing' }
+  | { status: 'unavailable' };
+
+/** The outcome of one `refresh()` call, for host notifications (toasts). */
+export type HtmlRefreshResult = 'refreshed' | 'missing' | 'unavailable';
+
+export interface UseHtmlRefreshOptions {
+  /** Whether refresh is offered at all. Default true. */
+  enabled?: boolean;
+  /**
+   * Identity of the document under refresh (a path, an id). A change
+   * cancels any in-flight fetch and any pending restore acknowledgement, so
+   * a snapshot for the previous document can never land on the next one.
+   * `null` means no document: `canRefresh` is false. Omit it when the host
+   * has a single document.
+   */
+  documentKey?: string | null;
+  /** Fetch the current bytes of the document. Called with `documentKey`.
+   *  A rejection is treated as `{ status: 'unavailable' }`. */
+  fetchSnapshot: (documentKey: string | null) => Promise<HtmlRefreshSnapshot>;
+  /** Apply the refreshed bytes (the host owns the viewer's `rawHtml`). */
+  onSnapshot: (rawHtml: string) => void;
+  /**
+   * Once per refresh: the ids the remounted viewer could not re-anchor,
+   * possibly empty. Wire the viewer's `onUnanchoredChange` to the returned
+   * `reportAnnotationRestore`; only the first report after a refresh is
+   * forwarded, and only while the document and reload generation match.
+   */
+  onUnanchored?: (ids: string[]) => void;
+  /** The outcome of each `refresh()` call that reached a decision. */
+  onResult?: (result: HtmlRefreshResult) => void;
+}
+
+export interface UseHtmlRefreshReturn {
+  canRefresh: boolean;
+  isRefreshing: boolean;
+  /** Bumps after every applied snapshot. Key the viewer on it to remount. */
+  reloadGeneration: number;
+  refresh: () => Promise<void>;
+  /** Feed the viewer's `onUnanchoredChange` report here. */
+  reportAnnotationRestore: (missingIds: string[]) => void;
+}
+
+/**
+ * Re-fetch a rendered HTML document from the host's source and remount the
+ * viewer on it, keeping the annotations the viewer can still anchor.
+ *
+ * Backend-agnostic: the host supplies `fetchSnapshot` (Plannotator wraps its
+ * `/api/doc` read; a host with a document store passes its own read). The
+ * hook owns the guards: an in-flight fetch that is superseded by a newer
+ * refresh, or by a document change, is dropped before `onSnapshot`; the
+ * restore acknowledgement is armed per reload generation and consumed by
+ * the first viewer report for that generation.
+ */
+export function useHtmlRefresh({
+  enabled = true,
+  documentKey,
+  fetchSnapshot,
+  onSnapshot,
+  onUnanchored,
+  onResult,
+}: UseHtmlRefreshOptions): UseHtmlRefreshReturn {
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [reloadGeneration, setReloadGeneration] = useState(0);
+  const keyed = documentKey !== undefined;
+  const activeKey = keyed ? documentKey : null;
+  const activeKeyRef = useRef(activeKey);
+  const requestRef = useRef(0);
+  const reloadGenerationRef = useRef(0);
+  const restorePendingRef = useRef<{ key: string | null; generation: number } | null>(null);
+  const onUnanchoredRef = useRef(onUnanchored);
+  onUnanchoredRef.current = onUnanchored;
+  const onResultRef = useRef(onResult);
+  onResultRef.current = onResult;
+  const canRefresh = enabled && (!keyed || !!documentKey);
+
+  useLayoutEffect(() => {
+    if (activeKeyRef.current !== activeKey) {
+      requestRef.current += 1;
+      restorePendingRef.current = null;
+      setIsRefreshing(false);
+    }
+    activeKeyRef.current = activeKey;
+  }, [activeKey]);
+
+  const refresh = useCallback(async () => {
+    if (!canRefresh) return;
+
+    const requestKey = activeKey;
+    const requestId = ++requestRef.current;
+    setIsRefreshing(true);
+    try {
+      // A rejecting fetch is an unavailable snapshot: the host hears it
+      // through onResult like any other outcome, never as an unhandled
+      // rejection out of refresh().
+      let result: HtmlRefreshSnapshot;
+      try {
+        result = await fetchSnapshot(requestKey);
+      } catch {
+        result = { status: 'unavailable' };
+      }
+      if (requestId !== requestRef.current || activeKeyRef.current !== requestKey) return;
+
+      if (result.status === 'missing' || result.status === 'unavailable') {
+        onResultRef.current?.(result.status);
+        return;
+      }
+
+      onSnapshot(result.rawHtml);
+      const nextGeneration = reloadGenerationRef.current + 1;
+      reloadGenerationRef.current = nextGeneration;
+      // Armed until the remounted viewer's bridge reports its restore. The
+      // bridge emits "unanchored" only when the set CHANGES from its initial
+      // empty state, so a pass that restores everything never posts and this
+      // stays armed; that is harmless because the next refresh replaces it
+      // and a document change clears it.
+      restorePendingRef.current = { key: requestKey, generation: nextGeneration };
+      setReloadGeneration(nextGeneration);
+      onResultRef.current?.('refreshed');
+    } finally {
+      if (requestId === requestRef.current) setIsRefreshing(false);
+    }
+  }, [activeKey, canRefresh, fetchSnapshot, onSnapshot]);
+
+  const reportAnnotationRestore = useCallback((missingIds: string[]) => {
+    const pending = restorePendingRef.current;
+    if (
+      !pending ||
+      pending.key !== activeKeyRef.current ||
+      pending.generation !== reloadGenerationRef.current
+    ) return;
+
+    restorePendingRef.current = null;
+    onUnanchoredRef.current?.(missingIds);
+  }, []);
+
+  return {
+    canRefresh,
+    isRefreshing,
+    reloadGeneration,
+    refresh,
+    reportAnnotationRestore,
+  };
+}

package/hooks/useMathRenderer.ts

@@ -0,0 +1,30 @@
+import { useEffect, useSyncExternalStore } from 'react';
+import {
+  getMathRenderer,
+  loadMathRenderer,
+  subscribeMathRenderer,
+  type MathRenderer,
+} from '../utils/math';
+
+/**
+ * The registered math renderer, read synchronously during render.
+ *
+ * With the slot filled before mount (Plannotator: `utils/math-eager`) this
+ * returns KaTeX on the first render and the effect below is a no-op, so the
+ * typeset HTML is in the first commit. With the slot empty it returns `null`,
+ * kicks off `loadMathRenderer()` from an effect, and the subscription
+ * re-renders the caller once the renderer lands. A rejected load is left to
+ * the loader's retry contract; the caller keeps showing the TeX placeholder.
+ */
+export function useMathRenderer(): MathRenderer | null {
+  const renderer = useSyncExternalStore(subscribeMathRenderer, getMathRenderer, getMathRenderer);
+
+  useEffect(() => {
+    if (renderer) return;
+    loadMathRenderer().catch(() => {
+      /* placeholder stays; the next mount retries */
+    });
+  }, [renderer]);
+
+  return renderer;
+}