@plannotator/ui 0.32.0 → 0.34.0

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

@@ -0,0 +1,9 @@
+// @generated by scripts/build-bridge-assets.ts from ./bridge-script.ts. DO NOT EDIT.
+// Alias target for hosts on the HtmlViewer `bridgeScriptUrl` path: the same
+// annotation CSS, protocol version and live bootstrap as ./bridge-script, with
+// the inline bridge literal stubbed out so a bundler drops it from the viewer
+// chunk. Rendering an HtmlViewer WITHOUT bridgeScriptUrl under this alias throws.
+export const ANNOTATION_HIGHLIGHT_CSS = "\n/* Committed annotation visuals (highlight rectangles + numbered placed\n * markers) render inside a shadow-rooted fixed overlay host — see OVERLAY_CSS\n * in the bridge script. Nothing annotation-related is ever wrapped into or\n * styled onto the author's own elements. */\n/* Vim pinpoint target tint. The MOUSE pinpoint path no longer mutates author\n * elements — it draws the dedicated overlay box below — but keyboard (vim)\n * navigation keeps this class-based visual. */\n.plannotator-pinpoint-hover {\n  background-color: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.12) !important;\n  border-radius: 3px;\n  cursor: pointer !important;\n}\n/* SVG groups can't render a CSS background, so use a soft glow instead. */\n.plannotator-pinpoint-hover:is(g, svg) {\n  filter: drop-shadow(0 0 4px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.55));\n}\n/* Mouse pinpoint hover: a fixed-position outline box sized to the hovered\n * element's rect. Never a class/style write on the page's own elements. */\n[data-plannotator-pinpoint-box] {\n  position: fixed;\n  z-index: 2147483643;\n  pointer-events: none;\n  display: none;\n  box-sizing: border-box;\n  border: 2px solid oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.85);\n  border-radius: 5px;\n  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.06);\n}\n[data-plannotator-pinpoint-box].pn-pin-enter {\n  animation: pn-pinpoint-in 0.12s ease-out;\n}\n[data-plannotator-pinpoint-box][data-pinned] {\n  border-color: var(--pn-accent, #d97757);\n  background: oklch(from var(--pn-accent, #d97757) l c h / 0.08);\n}\n@keyframes pn-pinpoint-in {\n  from { opacity: 0; transform: scale(0.985); }\n  to { opacity: 1; transform: scale(1); }\n}\n/* Pinpoint mode affordance: crosshair everywhere. Placed markers live in the\n * shadow overlay and keep their own pointer cursor there. */\nbody[data-plannotator-pinpoint-cursor],\nbody[data-plannotator-pinpoint-cursor] * {\n  cursor: crosshair !important;\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-pinpoint-box].pn-pin-enter {\n    animation: none;\n  }\n}\n@media print {\n  /* Viewer overlays are review chrome, not page content: never bake pinpoint\n     boxes/labels or vim UI into a printed page. The outer app chrome is\n     print-hidden by print.css, but this CSS lives inside the iframe's own\n     document and must carry its own rule. The annotation overlay host carries\n     its own print rule inside its shadow root. */\n  [data-plannotator-pinpoint-box],\n  [data-plannotator-pinpoint-label],\n  [data-plannotator-vim-ui],\n  [data-plannotator-vim-cursor] {\n    display: none !important;\n  }\n}\n/* Print-parity layer: committed highlight rects re-projected into an\n * absolute-positioned light-DOM layer built on beforeprint and torn down on\n * afterprint (the fixed overlay cannot paginate). Guarded here so it can\n * never flash on screen even if an afterprint teardown is missed. */\n@media screen {\n  [data-plannotator-print-layer] {\n    display: none !important;\n  }\n}\nbody[data-plannotator-vim-focus-owner]:focus {\n  outline: none !important;\n}\n[data-plannotator-vim-cursor] {\n  position: fixed;\n  z-index: 2147483646;\n  width: 2px;\n  min-height: 1em;\n  border-radius: 2px;\n  background: var(--pn-focus-highlight, #4493f8);\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] {\n  position: fixed;\n  z-index: 2147483645;\n  inset: 0;\n  overflow: visible;\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill],\n[data-plannotator-vim-reticle] [data-vim-reticle-corner],\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  position: absolute;\n  top: 0;\n  left: 0;\n  will-change: transform;\n  transition: transform 90ms cubic-bezier(.22,1,.36,1);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill] {\n  width: 100px;\n  height: 100px;\n  transform-origin: 0 0;\n  border-radius: 8px;\n  background: rgba(167,139,250,.045);\n  box-shadow:\n    inset 0 0 0 1px rgba(196,181,253,.16),\n    0 0 42px rgba(139,92,246,.12);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner] {\n  width: 28px;\n  height: 28px;\n  border-color: #c4b5fd;\n  filter:\n    drop-shadow(0 0 6px rgba(167,139,250,.92))\n    drop-shadow(0 0 18px rgba(124,58,237,.42));\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-left\"] {\n  border-top: 3px solid;\n  border-left: 3px solid;\n  border-top-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-right\"] {\n  border-top: 3px solid;\n  border-right: 3px solid;\n  border-top-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-left\"] {\n  border-bottom: 3px solid;\n  border-left: 3px solid;\n  border-bottom-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-right\"] {\n  border-right: 3px solid;\n  border-bottom: 3px solid;\n  border-bottom-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  z-index: 1;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-width: 118px;\n  height: 30px;\n  max-width: min(280px, calc(100vw - 24px));\n  padding: 0 11px;\n  overflow: hidden;\n  border: 1px solid rgba(216,206,255,.42);\n  border-radius: 9px;\n  color: #f6f2ff;\n  background: rgba(18,14,28,.84);\n  box-shadow:\n    0 10px 28px rgba(0,0,0,.42),\n    0 0 20px rgba(139,92,246,.18);\n  backdrop-filter: blur(10px);\n  font: 700 10px/1 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .13em;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label]::before {\n  width: 7px;\n  height: 7px;\n  flex: 0 0 auto;\n  border-radius: 999px;\n  background: #c4b5fd;\n  box-shadow: 0 0 12px rgba(167,139,250,.94);\n  content: \"\";\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-vim-reticle] [data-vim-reticle-fill],\n  [data-plannotator-vim-reticle] [data-vim-reticle-corner],\n  [data-plannotator-vim-reticle] [data-vim-reticle-label] {\n    transition: none;\n  }\n}\n[data-plannotator-vim-badge] {\n  position: fixed;\n  z-index: 2147483647;\n  left: 50%;\n  bottom: 12px;\n  transform: translateX(-50%);\n  padding: 4px 9px;\n  border: 1px solid color-mix(in srgb, var(--pn-focus-highlight, #4493f8) 35%, transparent);\n  border-radius: 6px;\n  background: color-mix(in srgb, var(--pn-background, #111) 94%, transparent);\n  color: var(--pn-focus-highlight, #4493f8);\n  box-shadow: 0 4px 18px rgba(0,0,0,.25);\n  font: 700 10px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .04em;\n  pointer-events: none;\n}\n";
+export const BRIDGE_PROTOCOL_VERSION = 1;
+export const BRIDGE_SCRIPT = "";
+export const LIVE_BRIDGE_BOOTSTRAP = "(function() {\n  var config = window.__plannotatorLiveConfig;\n  if (!config || typeof config.css !== 'string') return;\n  try {\n    var style = document.createElement('style');\n    style.setAttribute('data-plannotator-live-css', '');\n    style.appendChild(document.createTextNode(config.css));\n    (document.head || document.documentElement).appendChild(style);\n  } catch (ex) {}\n})();";

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

@@ -210,6 +210,18 @@ body[data-plannotator-vim-focus-owner]:focus {
 }
 `;
 
+/**
+ * Bridge protocol version. Stamped on the bridge's `ready` message
+ * (`protocolVersion`) and compared by the parent (HtmlViewer) against this
+ * same constant. Bump it whenever a message shape changes in a way an older
+ * bridge or an older parent would misread. The inline srcdoc path and the
+ * live proxy always ship the bridge from the same bundle as the parent, so
+ * they match by construction; the check exists for hosts that serve the
+ * generated `bridge-script.asset.js` separately (`bridgeScriptUrl`), where a
+ * cached asset from a previous package version can outlive the parent code.
+ */
+export const BRIDGE_PROTOCOL_VERSION = 1;
+
 export const BRIDGE_SCRIPT = `(function() {
   var PREFIX = 'plannotator-bridge-';
 
@@ -4572,7 +4584,7 @@ export const BRIDGE_SCRIPT = `(function() {
     // pinpoint: show the cursor affordance immediately instead of waiting for
     // the parent's first set-input-method/set-annotate-mode round trip.
     updatePinpointCursor();
-    var readyMsg = { type: PREFIX + 'ready' };
+    var readyMsg = { type: PREFIX + 'ready', protocolVersion: ${BRIDGE_PROTOCOL_VERSION} };
     if (LIVE) readyMsg.pageUrl = currentPageUrl();
     postToParent(readyMsg);
   }

package/components/html-viewer/index.ts

@@ -1,4 +1,16 @@
-export { HtmlViewer, type HtmlViewerProps } from "./HtmlViewer";
+export {
+  DEFAULT_BRIDGE_READY_TIMEOUT_MS,
+  HtmlViewer,
+  formatBridgeUnavailableMessage,
+  type BridgeUnavailableInfo,
+  type HtmlViewerProps,
+} from "./HtmlViewer";
+export { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
+export {
+  checkBridgeProtocolVersion,
+  formatBridgeProtocolWarning,
+  type BridgeProtocolVerdict,
+} from "./useHtmlAnnotation";
 export {
   buildPersistedHtmlAnchor,
   projectHostThreads,

package/components/html-viewer/srcdoc.ts

@@ -96,6 +96,68 @@ export interface SrcdocInjectionOptions {
   hostTheme: boolean;
   /** The version-diff view is showing (rawHtml is htmlDiff output). */
   diffActive: boolean;
+  /**
+   * Load the bridge through a classic `<script src>` from this URL instead of
+   * inlining `BRIDGE_SCRIPT`. Absent or empty: inline, exactly as before. The
+   * tag takes the inline script's place, so placement is identical on both
+   * paths: at the end of `<head>`, before the body (head scripts of the page
+   * run first, body scripts after the bridge). No `crossorigin` attribute is
+   * set: the srcdoc frame is an opaque origin, and a classic script needs no
+   * CORS to execute. Callers must pass an ABSOLUTE URL (see
+   * {@link resolveBridgeScriptUrl}): the framed page may carry its own
+   * `<base href>`, which precedes the injected tag and would re-anchor a
+   * relative URL onto an attacker-chosen origin.
+   */
+  bridgeScriptUrl?: string;
+}
+
+/**
+ * Resolve a host-supplied bridge URL against the PARENT document (its
+ * `document.baseURI`), never against the framed page. The injection lands at
+ * the end of the page's `<head>`, after any `<base href>` the page declares,
+ * so a relative URL written into the srcdoc would resolve against that base:
+ * a hostile document could point the viewer at an attacker-served bridge and
+ * defeat the version check. Resolving here pins the URL before it is written.
+ * An unparsable input is returned unchanged (nothing loads, the ready timeout
+ * reports it) rather than throwing during render.
+ */
+export function resolveBridgeScriptUrl(bridgeScriptUrl: string, parentBaseUrl: string): string {
+  try {
+    return new URL(bridgeScriptUrl, parentBaseUrl).href;
+  } catch {
+    return bridgeScriptUrl;
+  }
+}
+
+/** Escape a string for a double-quoted HTML attribute value. */
+function escapeAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * The bridge `<script>` element, the ONE injection point for both delivery
+ * paths. Inline is the default and Plannotator's only path; the URL form is
+ * the opt-in for hosts that serve the generated `bridge-script.asset.js`.
+ */
+export function buildBridgeScriptTag(bridgeScriptUrl?: string): string {
+  if (bridgeScriptUrl) {
+    return `<script src="${escapeAttribute(bridgeScriptUrl)}"></script>`;
+  }
+  if (!BRIDGE_SCRIPT) {
+    // Only reachable when a host aliased `./bridge-script` to the generated
+    // `bridge-script.lite` module (which stubs the inline literal) and then
+    // rendered an HtmlViewer without `bridgeScriptUrl`: an empty inline
+    // script would be a silently dead surface, so fail loudly instead.
+    throw new Error(
+      "@plannotator/ui HtmlViewer: the inline bridge script is stubbed out "
+        + "(bridge-script.lite alias) but no bridgeScriptUrl was passed.",
+    );
+  }
+  return `<script>${BRIDGE_SCRIPT}</script>`;
 }
 
 /** The `<style>` + `<script>` block spliced into the document's head. */
@@ -104,6 +166,7 @@ export function buildSrcdocInjection({
   isLight,
   hostTheme,
   diffActive,
+  bridgeScriptUrl,
 }: SrcdocInjectionOptions): string {
   const payload = buildThemeTokenPayload(tokens, hostTheme);
   let themeCSS = ":root {\n";
@@ -117,7 +180,7 @@ export function buildSrcdocInjection({
     themeCSS += `:root { color-scheme: ${isLight ? "light" : "dark"}; }\n`;
   }
   const diffCSS = diffActive ? DIFF_HIGHLIGHT_CSS : "";
-  return `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style><script>${BRIDGE_SCRIPT}</script>`;
+  return `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style>${buildBridgeScriptTag(bridgeScriptUrl)}`;
 }
 
 /**
@@ -126,6 +189,12 @@ export function buildSrcdocInjection({
  * script and disables annotation entirely. The iframe `sandbox` attribute is
  * the security boundary for the annotate surface; the page's CSP was written
  * for its standalone context, so it is removed before injection.
+ *
+ * The package itself never adds a CSP `<meta>` to the srcdoc document (the
+ * injection is one `<style>` and one `<script>`), so nothing here blocks a
+ * `<script src>` on the URL path. A CSP delivered as an HTTP header on the
+ * HOST page is inherited by the srcdoc document, and the host must allow
+ * `script-src` for the origin the asset is served from.
  */
 const META_CSP_RE =
   /<meta\s[^>]*http-equiv\s*=\s*["']?\s*content-security-policy\s*["']?[^>]*\/?>/gi;

package/components/html-viewer/useHtmlAnnotation.ts

@@ -8,9 +8,46 @@ import type {
   QuickLabelPickerState,
   UseAnnotationHighlighterReturn,
 } from "../../hooks/useAnnotationHighlighter";
+import { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
 
 const PREFIX = "plannotator-bridge-";
 
+/** Outcome of comparing a bridge `ready` message's stamp with this parent. */
+export interface BridgeProtocolVerdict {
+  ok: boolean;
+  /** The version this parent bundle speaks (`BRIDGE_PROTOCOL_VERSION`). */
+  expected: number;
+  /** The version the bridge reported; `undefined` when the ready carried none
+   *  (a bridge asset built before the stamp existed, or a forged message). */
+  reported: number | undefined;
+}
+
+/**
+ * Compare a `ready` message against the parent's protocol version. A missing
+ * stamp counts as a mismatch: the only way it can be absent is a bridge asset
+ * older than the parent (or a page forging the message), which is exactly
+ * the drift this check exists to name.
+ */
+export function checkBridgeProtocolVersion(data: unknown): BridgeProtocolVerdict {
+  const raw = isRecord(data) ? data.protocolVersion : undefined;
+  const reported = typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+  return {
+    ok: reported === BRIDGE_PROTOCOL_VERSION,
+    expected: BRIDGE_PROTOCOL_VERSION,
+    reported,
+  };
+}
+
+/** The one console warning a mismatch produces; names both versions. */
+export function formatBridgeProtocolWarning(
+  verdict: BridgeProtocolVerdict,
+  bridgeScriptUrl?: string,
+): string {
+  const reported = verdict.reported === undefined ? "none" : String(verdict.reported);
+  const source = bridgeScriptUrl ? `the bridge script at ${bridgeScriptUrl}` : "the bridge script";
+  return `[plannotator] HTML bridge protocol version mismatch: this viewer expects ${verdict.expected}, ${source} reported ${reported}. Serve the bridge-script asset from the same @plannotator/ui version as the viewer.`;
+}
+
 // Collision-proof annotation ids. `Date.now()` alone repeats within a millisecond,
 // so two quick annotations could share a data-bind-id and clobber each other.
 let htmlAnnSeq = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -11,6 +11,8 @@
     "./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",
@@ -46,6 +48,7 @@
     "print.css",
     "styles.css",
     "plannotator.webp",
+    "HANDOFF.md",
     "!**/*.test.ts",
     "!**/*.test.tsx",
     "!test-setup"
@@ -109,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"
   }
 }