@plannotator/ui 0.31.0 → 0.33.0

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;
+}

package/hooks/useSharing.ts

@@ -8,7 +8,7 @@
  * - Tracking whether current session is from a shared link
  */
 
-import React, { useState, useEffect, useCallback, useRef } from 'react';
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import { Annotation, type ImageAttachment } from '../types';
 import {
   type SharePayload,
@@ -104,6 +104,7 @@ export function useSharing(
   setRawHtml?: (h: string) => void,
   setShareHtml?: (h: string) => void,
   setRenderAs?: (m: 'markdown' | 'html') => void,
+  contentRevision = 0,
 ): UseSharingResult {
   const [isSharedSession, setIsSharedSession] = useState(false);
   const [isLoadingShared, setIsLoadingShared] = useState(true);
@@ -115,6 +116,23 @@ export function useSharing(
   const [pendingSharedAnnotations, setPendingSharedAnnotations] = useState<Annotation[] | null>(null);
   const [sharedGlobalAttachments, setSharedGlobalAttachments] = useState<ImageAttachment[] | null>(null);
   const [shareLoadError, setShareLoadError] = useState('');
+  // Identity token for in-flight share requests: a new token invalidates any
+  // response still on the wire. Content inputs only — resolveRawHtmlForShare
+  // is deliberately NOT a dependency: its identity changes when it caches the
+  // portable HTML mid-request (App memoizes it on shareHtml), and listing it
+  // would make the first short-link generation on an HTML session discard its
+  // own result. HTML refreshes invalidate through contentRevision instead.
+  const shareRequestContext = useMemo(() => ({}), [
+    markdown,
+    annotations,
+    globalAttachments,
+    shareBaseUrl,
+    pasteApiUrl,
+    rawHtml,
+    contentRevision,
+  ]);
+  const latestShareRequestContextRef = useRef(shareRequestContext);
+  latestShareRequestContextRef.current = shareRequestContext;
 
   const clearPendingSharedAnnotations = useCallback(() => {
     setPendingSharedAnnotations(null);
@@ -257,16 +275,19 @@ export function useSharing(
 
   // Generate share URL when markdown or annotations change
   const refreshShareUrl = useCallback(async () => {
+    const requestContext = shareRequestContext;
     try {
       const url = await generateShareUrl(markdown, annotations, globalAttachments, shareBaseUrl, rawHtml);
+      if (latestShareRequestContextRef.current !== requestContext) return;
       setShareUrl(url ?? '');
       setShareUrlSize(url ? formatUrlSize(url) : '');
     } catch (e) {
+      if (latestShareRequestContextRef.current !== requestContext) return;
       console.error('Failed to generate share URL:', e);
       setShareUrl('');
       setShareUrlSize('');
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, rawHtml]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, rawHtml, shareRequestContext]);
 
   // Auto-refresh share URL when dependencies change
   useEffect(() => {
@@ -280,9 +301,10 @@ export function useSharing(
   useEffect(() => {
     if (isSharedSession) { isSharedRef.current = true; return; }
     if (isSharedRef.current) { isSharedRef.current = false; return; }
+    setIsGeneratingShortUrl(false);
     setShortShareUrl('');
     setShortUrlError('');
-  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession]);
+  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession, contentRevision]);
 
   /**
    * Generate a short URL via the paste service.
@@ -295,6 +317,7 @@ export function useSharing(
 
     setIsGeneratingShortUrl(true);
     setShortUrlError('');
+    const requestContext = shareRequestContext;
 
     try {
       const htmlForShare = rawHtml
@@ -308,6 +331,8 @@ export function useSharing(
         htmlForShare,
       );
 
+      if (latestShareRequestContextRef.current !== requestContext) return null;
+
       if (result) {
         setShortShareUrl(result.shortUrl);
         return result.shortUrl;
@@ -317,13 +342,14 @@ export function useSharing(
         return null;
       }
     } catch (e) {
+      if (latestShareRequestContextRef.current !== requestContext) return null;
       setShortShareUrl('');
       setShortUrlError(e instanceof Error ? e.message : 'Failed to generate short URL');
       return null;
     } finally {
-      setIsGeneratingShortUrl(false);
+      if (latestShareRequestContextRef.current === requestContext) setIsGeneratingShortUrl(false);
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare, shareRequestContext]);
 
   // Import annotations from a teammate's share URL (supports both hash-based and short /p/<id> URLs)
   const importFromShareUrl = useCallback(async (url: string): Promise<ImportResult> => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -11,12 +11,15 @@
     "./components/ImageAnnotator": "./components/ImageAnnotator/index.tsx",
     "./components/html-viewer": "./components/html-viewer/index.ts",
     "./components/html-viewer/bridge-script": "./components/html-viewer/bridge-script.ts",
+    "./components/html-viewer/bridge-script.asset.js": "./components/html-viewer/bridge-script.asset.js",
+    "./components/html-viewer/bridge-script.lite": "./components/html-viewer/bridge-script.lite.ts",
     "./components/sidebar/*": "./components/sidebar/*.tsx",
     "./components/plan-diff/*": "./components/plan-diff/*.tsx",
     "./utils/*": "./utils/*.ts",
     "./lib/*": "./lib/*.ts",
     "./hooks/*": "./hooks/*.ts",
     "./shortcuts": "./shortcuts/index.ts",
+    "./webmcp": "./webmcp/index.ts",
     "./config": "./config/index.ts",
     "./configure": "./configure.ts",
     "./theme-modes": "./components/themeModes.tsx",
@@ -32,6 +35,7 @@
     "lib",
     "shortcuts",
     "utils",
+    "webmcp",
     "assets",
     "themes",
     "sprite_package_additional",
@@ -44,6 +48,7 @@
     "print.css",
     "styles.css",
     "plannotator.webp",
+    "HANDOFF.md",
     "!**/*.test.ts",
     "!**/*.test.tsx",
     "!test-setup"
@@ -69,7 +74,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.2",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.24.0",
+    "@plannotator/core": "0.25.0",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
@@ -107,6 +112,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "build:css": "vite build --config vite.css.config.ts && rm -f styles.js",
-    "prepack": "bun run build:css"
+    "build:bridge-assets": "bun run scripts/build-bridge-assets.ts",
+    "prepack": "bun run build:css && bun run build:bridge-assets"
   }
 }