@plannotator/ui 0.32.0 → 0.33.0

package/README.md

@@ -54,7 +54,7 @@ Building your own tooltip and removing the built-in double-click reset are host-
 
 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).
+- **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`.
 
@@ -102,16 +102,28 @@ Requires `@plannotator/markdown-editor ^0.4.0` and `@plannotator/atomic-editor ^
 
 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.
-- **`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.
+- **`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).
+- **`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.
@@ -152,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 (currently `@plannotator/core` 0.25.0 with `@plannotator/ui` 0.32.0). 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").
+- 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/html-viewer/HtmlViewer.tsx

@@ -41,6 +41,8 @@ import { buildSyncNumbering } from "./annotationNumbering";
 import { mergeUnanchoredIds } from "./unanchored";
 import {
   MAX_PAGE_URL_LENGTH,
+  checkBridgeProtocolVersion,
+  formatBridgeProtocolWarning,
   rejectsLiveMessage,
   useHtmlAnnotation,
   type HtmlLiveSession,
@@ -51,6 +53,7 @@ import {
   buildThemeTokenPayload,
   hasHostThemeOptIn,
   injectIntoHead,
+  resolveBridgeScriptUrl,
 } from "./srcdoc";
 
 const PREFIX = "plannotator-bridge-";
@@ -131,6 +134,38 @@ function parseVimBridgeHelp(value: unknown): boolean | null {
 
 const MAX_VIM_COPY_TEXT_LENGTH = 2 * 1024 * 1024;
 
+/** Default wait for the bridge's `ready` on the `bridgeScriptUrl` path. */
+export const DEFAULT_BRIDGE_READY_TIMEOUT_MS = 5000;
+
+/**
+ * Why the bridge could not be established on the `bridgeScriptUrl` path.
+ * Never produced on the inline path (the bridge and the parent are one
+ * bundle there, and no ready timer runs).
+ */
+export type BridgeUnavailableInfo =
+  | {
+      kind: "timeout";
+      url: string;
+      /** The wait that elapsed without a `ready`. */
+      timeoutMs: number;
+    }
+  | {
+      kind: "version-mismatch";
+      url: string;
+      expectedVersion: number;
+      /** Absent when the ready carried no stamp (a pre-stamp asset). */
+      reportedVersion?: number;
+    };
+
+/** User-facing message for the in-surface error banner. */
+export function formatBridgeUnavailableMessage(info: BridgeUnavailableInfo): string {
+  if (info.kind === "timeout") {
+    return `Annotation tools did not load: the bridge script at ${info.url} sent no ready signal within ${info.timeoutMs} ms. The page is shown without annotation. Check that the URL is reachable and that your Content Security Policy allows script-src for that origin.`;
+  }
+  const reported = info.reportedVersion === undefined ? "no version" : `version ${info.reportedVersion}`;
+  return `Annotation tools may not work: this viewer expects bridge protocol version ${info.expectedVersion}, but the script at ${info.url} reported ${reported}. Serve the bridge-script asset from the same @plannotator/ui version as the viewer.`;
+}
+
 function parseVimBridgeCopy(value: unknown): string | null {
   return isRecord(value)
     && value.type === `${PREFIX}vim-copy`
@@ -221,6 +256,34 @@ export interface HtmlViewerProps {
   scrollBehavior?: 'smooth' | 'auto';
   /** Accessible iframe title. */
   title?: string;
+  /**
+   * Opt-in: load the annotation bridge into the srcdoc document through a
+   * classic `<script src>` from this URL (the package's generated
+   * `components/html-viewer/bridge-script.asset.js`, served by the host)
+   * instead of inlining the 185 KB script into every document. Absent (the
+   * default, and Plannotator's only path): inline, unchanged. The tag lands
+   * where the inline script does, at the end of `<head>`, before the body.
+   * The URL is resolved against THIS document's base (`document.baseURI`)
+   * before it is written, never against the framed page, so a page's own
+   * `<base href>` cannot redirect it. The srcdoc frame is an opaque origin,
+   * so the script needs no CORS and no `crossorigin` attribute is set; a CSP
+   * header on the host page is inherited by the frame and must allow
+   * `script-src` for the asset origin, and the asset must not be served with
+   * `Cross-Origin-Resource-Policy: same-origin`. Ignored in live (`src`)
+   * mode, where the proxy injects the bridge.
+   */
+  bridgeScriptUrl?: string;
+  /**
+   * How long to wait for the bridge's `ready` after each document load on
+   * the `bridgeScriptUrl` path before the surface shows an error state.
+   * Default 5000 ms. No timer runs on the inline path.
+   */
+  bridgeReadyTimeoutMs?: number;
+  /** The bridge could not be established on the `bridgeScriptUrl` path (no
+   *  ready within the timeout, or a protocol version mismatch). The surface
+   *  shows its own banner as well; this lets the host react (telemetry, a
+   *  retry affordance). Never called on the inline path. */
+  onBridgeUnavailable?: (info: BridgeUnavailableInfo) => void;
 }
 
 /**
@@ -263,6 +326,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       maxAdditionalTargets,
       scrollBehavior,
       title = "HTML Plan Viewer",
+      bridgeScriptUrl,
+      bridgeReadyTimeoutMs = DEFAULT_BRIDGE_READY_TIMEOUT_MS,
+      onBridgeUnavailable,
     },
     ref,
   ) => {
@@ -320,6 +386,18 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     // themselves); arbitrary HTML renders untouched, like a standalone tab.
     const hostTheme = useMemo(() => !liveMode && hasHostThemeOptIn(rawHtml), [liveMode, rawHtml]);
 
+    // The URL path is srcdoc-only: live mode has the proxy inject the bridge.
+    // Resolved against THIS document's base before it is written into the
+    // srcdoc, so a framed page's own <base href> can never re-anchor it.
+    const bridgeUrl = useMemo(
+      () => (!liveMode && bridgeScriptUrl
+        ? resolveBridgeScriptUrl(bridgeScriptUrl, document.baseURI)
+        : undefined),
+      [liveMode, bridgeScriptUrl],
+    );
+    const bridgeUrlRef = useRef(bridgeUrl);
+    bridgeUrlRef.current = bridgeUrl;
+
     const srcdoc = useMemo(() => {
       if (liveMode) return undefined; // src mode: the proxy injects the bridge
       const injection = buildSrcdocInjection({
@@ -327,9 +405,46 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         isLight: isLightTheme(),
         hostTheme,
         diffActive: !!diffActive,
+        bridgeScriptUrl: bridgeUrl,
       });
       return injectIntoHead(rawHtml, injection);
-    }, [liveMode, rawHtml, hostTheme, diffActive]);
+    }, [liveMode, rawHtml, hostTheme, diffActive, bridgeUrl]);
+
+    // Error state for the bridgeScriptUrl path only: the inline path never
+    // sets it (no timer, and a version mismatch there can only be a forged
+    // message, which is warned about and otherwise ignored).
+    const [bridgeError, setBridgeError] = useState<BridgeUnavailableInfo | null>(null);
+    // A version-mismatch banner is dismissible (the older bridge keeps
+    // working); reset whenever the error itself changes.
+    const [bridgeErrorDismissed, setBridgeErrorDismissed] = useState(false);
+    const readyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const onBridgeUnavailableRef = useRef(onBridgeUnavailable);
+    onBridgeUnavailableRef.current = onBridgeUnavailable;
+    // The timeout is read through a ref at arming time: the timer is armed
+    // once per document load (URL or srcdoc change), never re-armed by a
+    // later prop change, so a host adjusting bridgeReadyTimeoutMs after the
+    // bridge is ready can never produce a false timeout.
+    const bridgeReadyTimeoutMsRef = useRef(bridgeReadyTimeoutMs);
+    bridgeReadyTimeoutMsRef.current = bridgeReadyTimeoutMs;
+    useEffect(() => {
+      if (!bridgeUrl || srcdoc === undefined) return;
+      setBridgeError(null);
+      setBridgeErrorDismissed(false);
+      const url = bridgeUrl;
+      const timeoutMs = bridgeReadyTimeoutMsRef.current;
+      readyTimerRef.current = setTimeout(() => {
+        readyTimerRef.current = null;
+        setBridgeError({ kind: "timeout", url, timeoutMs });
+      }, timeoutMs);
+      return () => {
+        if (readyTimerRef.current !== null) clearTimeout(readyTimerRef.current);
+        readyTimerRef.current = null;
+      };
+    }, [bridgeUrl, srcdoc]);
+    useEffect(() => {
+      setBridgeErrorDismissed(false);
+      if (bridgeError) onBridgeUnavailableRef.current?.(bridgeError);
+    }, [bridgeError]);
 
     const handleResize = useCallback((height: number) => {
       if (liveMode) return; // live surfaces are full-viewport; height is ignored
@@ -516,6 +631,33 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         const live = liveSessionRef.current;
         if (live && rejectsLiveMessage(live, e.origin, e.data)) return;
         if (isBridgeReadyMessage(e.data)) {
+          // Protocol stamp: one console warning on drift, naming both
+          // versions. The ready is still honored (an older bridge answers
+          // every message shape it knows); on the bridgeScriptUrl path the
+          // surface additionally shows its error banner, because there the
+          // drift is a real deployment state (a cached asset from a previous
+          // package version) rather than a forged message.
+          const verdict = checkBridgeProtocolVersion(e.data);
+          const url = bridgeUrlRef.current;
+          if (!verdict.ok) {
+            console.warn(formatBridgeProtocolWarning(verdict, url));
+          }
+          if (url) {
+            if (readyTimerRef.current !== null) {
+              clearTimeout(readyTimerRef.current);
+              readyTimerRef.current = null;
+            }
+            setBridgeError(
+              verdict.ok
+                ? null
+                : {
+                    kind: "version-mismatch",
+                    url,
+                    expectedVersion: verdict.expected,
+                    reportedVersion: verdict.reported,
+                  },
+            );
+          }
           setIframeReadyVersion((version) => version + 1);
           setVimBridgePhase("inactive");
           setVimHudCommand(null);
@@ -916,6 +1058,37 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 {actionButtons}
               </div>
             )}
+            {/* bridgeScriptUrl path only: the bridge did not come up (no
+                ready within the timeout, or a stale asset's version). Floated
+                over the top of the iframe so it never changes the layout the
+                page renders in; the page itself stays visible. */}
+            {bridgeError && !bridgeErrorDismissed && (
+              <div
+                role="alert"
+                data-print-hide
+                data-bridge-error={bridgeError.kind}
+                className="absolute inset-x-0 top-0 z-20 border-b border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive backdrop-blur-sm"
+                style={{ display: "flex", alignItems: "flex-start", gap: 8 }}
+              >
+                <span style={{ flex: 1 }}>{formatBridgeUnavailableMessage(bridgeError)}</span>
+                {/* Only the mismatch state is dismissible: the older bridge
+                    still works there. A timeout leaves a dead surface, so
+                    that banner stays. Inline styles on purpose: hosts that
+                    build the guides.show viewer scan this file for utility
+                    classes, and this banner must not grow that stylesheet. */}
+                {bridgeError.kind === "version-mismatch" && (
+                  <button
+                    type="button"
+                    data-bridge-error-dismiss
+                    aria-label="Dismiss"
+                    style={{ flexShrink: 0, borderRadius: 4, padding: "2px 6px", fontWeight: 500, cursor: "pointer", background: "transparent", border: "1px solid currentColor", color: "inherit" }}
+                    onClick={() => setBridgeErrorDismissed(true)}
+                  >
+                    Dismiss
+                  </button>
+                )}
+              </div>
+            )}
             {/* Live proxied-app mode navigates a real loopback origin: no
                 sandbox (the user's own app needs cookies, storage, and
                 same-origin XHR) and no srcdoc. Srcdoc mode is unchanged. */}