@plannotator/ui 0.24.0 → 0.25.0

package/components/html-viewer/HtmlViewer.tsx

@@ -17,39 +17,16 @@ import { CommentPopover, type CommentAskAIHandler } from "../CommentPopover";
 import { FloatingQuickLabelPicker } from "../FloatingQuickLabelPicker";
 import type { ViewerHandle } from "../Viewer";
 import { useHtmlAnnotation } from "./useHtmlAnnotation";
-import { ANNOTATION_HIGHLIGHT_CSS, BRIDGE_SCRIPT } from "./bridge-script";
+import {
+  THEME_TOKENS,
+  buildSrcdocInjection,
+  buildThemeTokenPayload,
+  hasHostThemeOptIn,
+  injectIntoHead,
+} from "./srcdoc";
 
 const PREFIX = "plannotator-bridge-";
 
-const THEME_TOKENS = [
-  "--background",
-  "--foreground",
-  "--card",
-  "--card-foreground",
-  "--primary",
-  "--primary-foreground",
-  "--secondary",
-  "--secondary-foreground",
-  "--muted",
-  "--muted-foreground",
-  "--accent",
-  "--accent-foreground",
-  "--destructive",
-  "--destructive-foreground",
-  "--success",
-  "--success-foreground",
-  "--warning",
-  "--warning-foreground",
-  "--border",
-  "--input",
-  "--ring",
-  "--code-bg",
-  "--focus-highlight",
-  "--font-sans",
-  "--font-mono",
-  "--radius",
-] as const;
-
 function readThemeTokens(): Record<string, string> {
   const style = getComputedStyle(document.documentElement);
   const tokens: Record<string, string> = {};
@@ -124,26 +101,19 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       contextText: string;
     } | null>(null);
 
-    const srcdoc = useMemo(() => {
-      const tokens = readThemeTokens();
-      let themeCSS = ":root {\n";
-      for (const [key, val] of Object.entries(tokens)) {
-        themeCSS += `  ${key}: ${val};\n`;
-      }
-      themeCSS += "}\n";
-      if (isLightTheme()) themeCSS += ":root { color-scheme: light; }\n:root.light, :root { }\n";
+    // Host theming is opt-in per document (Plannotator-generated artifacts tag
+    // themselves); arbitrary HTML renders untouched, like a standalone tab.
+    const hostTheme = useMemo(() => hasHostThemeOptIn(rawHtml), [rawHtml]);
 
-      // Version-diff highlights: htmlDiff wraps changed text in <ins>/<del>.
-      const diffCSS =
-        "ins{background:#e6ffec;color:#0a7d33;text-decoration:none;border-radius:2px;box-shadow:0 0 0 1px #abf2bc inset}" +
-        "del{background:#ffebe9;color:#b31d28;text-decoration:line-through;border-radius:2px;box-shadow:0 0 0 1px #ffc1bc inset}";
-      const injection = `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style><script>${BRIDGE_SCRIPT}</script>`;
-      const headClose = rawHtml.indexOf("</head>");
-      if (headClose !== -1) {
-        return rawHtml.slice(0, headClose) + injection + rawHtml.slice(headClose);
-      }
-      return injection + rawHtml;
-    }, [rawHtml]);
+    const srcdoc = useMemo(() => {
+      const injection = buildSrcdocInjection({
+        tokens: readThemeTokens(),
+        isLight: isLightTheme(),
+        hostTheme,
+        diffActive: !!diffActive,
+      });
+      return injectIntoHead(rawHtml, injection);
+    }, [rawHtml, hostTheme, diffActive]);
 
     const handleResize = useCallback((height: number) => {
       setIframeHeight(height);
@@ -189,9 +159,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     useEffect(() => {
       if (!iframeReady) return;
       function sendTheme() {
-        const tokens = readThemeTokens();
         iframeRef.current?.contentWindow?.postMessage(
-          { type: `${PREFIX}theme`, tokens, isLight: isLightTheme() },
+          {
+            type: `${PREFIX}theme`,
+            tokens: buildThemeTokenPayload(readThemeTokens(), hostTheme),
+            isLight: isLightTheme(),
+            hostTheme,
+          },
           "*",
         );
       }
@@ -202,7 +176,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         attributeFilter: ["class", "style"],
       });
       return () => observer.disconnect();
-    }, [iframeReady]);
+    }, [iframeReady, hostTheme]);
 
     useImperativeHandle(ref, () => ({
       removeHighlight: hook.removeHighlight,

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

@@ -9,6 +9,11 @@
  * No external dependencies.
  */
 
+/**
+ * Reads only viewer-namespaced \`--pn-*\` variables (with fallbacks): arbitrary
+ * documents may define bare token names like \`--accent\` for themselves, and the
+ * viewer must never depend on — or collide with — the author's namespace.
+ */
 export const ANNOTATION_HIGHLIGHT_CSS = `
 .annotation-highlight {
   border-radius: 2px;
@@ -17,33 +22,33 @@ export const ANNOTATION_HIGHLIGHT_CSS = `
   cursor: pointer;
 }
 .annotation-highlight.deletion {
-  background: oklch(from var(--destructive, #c0392b) l c h / 0.35);
+  background: oklch(from var(--pn-destructive, #c0392b) l c h / 0.35);
   text-decoration: line-through;
-  text-decoration-color: var(--destructive, #c0392b);
+  text-decoration-color: var(--pn-destructive, #c0392b);
   text-decoration-thickness: 2px;
 }
 .annotation-highlight.comment {
   background: oklch(0.70 0.18 60 / 0.3);
-  border-bottom: 2px solid var(--accent, #d97757);
+  border-bottom: 2px solid var(--pn-accent, #d97757);
 }
 .annotation-highlight.focused {
-  background: oklch(from var(--focus-highlight, #4493f8) l c h / 0.45) !important;
-  box-shadow: 0 0 8px oklch(from var(--focus-highlight, #4493f8) l c h / 0.4);
-  border-bottom: 2px solid var(--focus-highlight, #4493f8);
+  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.45) !important;
+  box-shadow: 0 0 8px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.4);
+  border-bottom: 2px solid var(--pn-focus-highlight, #4493f8);
   filter: none;
 }
 .annotation-highlight:hover {
   filter: brightness(1.2);
 }
 .plannotator-pinpoint-hover {
-  outline: 2px solid var(--focus-highlight, #4493f8) !important;
+  outline: 2px solid var(--pn-focus-highlight, #4493f8) !important;
   outline-offset: 1px;
   cursor: crosshair !important;
 }
 /* SVG nodes can't take a CSS outline — stroke their shapes instead. */
 .plannotator-pinpoint-hover rect, .plannotator-pinpoint-hover path,
 .plannotator-pinpoint-hover circle, .plannotator-pinpoint-hover ellipse, .plannotator-pinpoint-hover polygon {
-  stroke: var(--focus-highlight, #4493f8) !important; stroke-width: 2.5px !important;
+  stroke: var(--pn-focus-highlight, #4493f8) !important; stroke-width: 2.5px !important;
 }
 `;
 
@@ -51,15 +56,23 @@ export const BRIDGE_SCRIPT = `(function() {
   var PREFIX = 'plannotator-bridge-';
 
   // --- Theme ---
+  // The author owns this document. Unless it opted in to host theming
+  // (hostTheme), only viewer-namespaced --pn-* properties may be written to its
+  // root, and its class list is never touched.
   window.addEventListener('message', function(e) {
     if (!e.data || e.data.type !== PREFIX + 'theme') return;
     var root = document.documentElement;
-    var tokens = e.data.tokens;
+    var tokens = e.data.tokens || {};
+    var hostTheme = !!e.data.hostTheme;
     for (var key in tokens) {
-      if (tokens.hasOwnProperty(key)) root.style.setProperty(key, tokens[key]);
+      if (!tokens.hasOwnProperty(key)) continue;
+      if (!hostTheme && key.indexOf('--pn-') !== 0) continue;
+      root.style.setProperty(key, tokens[key]);
+    }
+    if (hostTheme) {
+      root.classList.remove('light');
+      if (e.data.isLight) root.classList.add('light');
     }
-    root.classList.remove('light');
-    if (e.data.isLight) root.classList.add('light');
   });
 
   // --- Resize ---
@@ -244,7 +257,7 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!pinpointLabelEl) {
       pinpointLabelEl = document.createElement('div');
       pinpointLabelEl.setAttribute('data-plannotator-pinpoint-label', '');
-      pinpointLabelEl.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:none;font:600 11px/1.3 system-ui,-apple-system,sans-serif;padding:2px 7px;border-radius:5px;background:var(--focus-highlight,#4493f8);color:#fff;white-space:nowrap;box-shadow:0 1px 5px rgba(0,0,0,.35);';
+      pinpointLabelEl.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:none;font:600 11px/1.3 system-ui,-apple-system,sans-serif;padding:2px 7px;border-radius:5px;background:var(--pn-focus-highlight,#4493f8);color:#fff;white-space:nowrap;box-shadow:0 1px 5px rgba(0,0,0,.35);';
       document.body.appendChild(pinpointLabelEl);
     }
     return pinpointLabelEl;

package/components/html-viewer/srcdoc.ts

@@ -0,0 +1,130 @@
+/**
+ * Srcdoc injection builder for the HTML viewer.
+ *
+ * Product rule: arbitrary HTML must render exactly as it would in a plain
+ * browser tab. The viewer never writes into the document's namespace — no bare
+ * CSS custom properties, no classes on the author's root, no `color-scheme`,
+ * no styling of author elements. Host theme tokens are pushed under the
+ * viewer-owned `--pn-*` prefix, which the annotation CSS reads.
+ *
+ * Documents that WANT to follow the host theme (e.g. Plannotator-generated
+ * artifacts) opt in with `<meta name="plannotator-theme" content="host">`,
+ * which re-enables the bare-token push, the `light` class on their root, and
+ * `color-scheme` sync — for that document only.
+ *
+ * Pure string logic (no DOM) so the rendering-neutrality contract is unit-testable.
+ */
+import { ANNOTATION_HIGHLIGHT_CSS, BRIDGE_SCRIPT } from "./bridge-script";
+
+export const THEME_TOKENS = [
+  "--background",
+  "--foreground",
+  "--card",
+  "--card-foreground",
+  "--primary",
+  "--primary-foreground",
+  "--secondary",
+  "--secondary-foreground",
+  "--muted",
+  "--muted-foreground",
+  "--accent",
+  "--accent-foreground",
+  "--destructive",
+  "--destructive-foreground",
+  "--success",
+  "--success-foreground",
+  "--warning",
+  "--warning-foreground",
+  "--border",
+  "--input",
+  "--ring",
+  "--code-bg",
+  "--focus-highlight",
+  "--font-sans",
+  "--font-mono",
+  "--radius",
+] as const;
+
+/** Viewer-owned namespace for properties injected into the document. */
+export const PN_TOKEN_PREFIX = "--pn-";
+
+/**
+ * Version-diff highlights. htmlDiff tags the <ins>/<del> it generates with
+ * this class so author-written <ins>/<del> markup is never restyled.
+ */
+export const DIFF_HIGHLIGHT_CSS =
+  "ins.plannotator-diff{background:#e6ffec;color:#0a7d33;text-decoration:none;border-radius:2px;box-shadow:0 0 0 1px #abf2bc inset}" +
+  "del.plannotator-diff{background:#ffebe9;color:#b31d28;text-decoration:line-through;border-radius:2px;box-shadow:0 0 0 1px #ffc1bc inset}";
+
+/**
+ * True when the document opts in to following the host theme via
+ * `<meta name="plannotator-theme" content="host">` (attribute order/quoting agnostic).
+ */
+export function hasHostThemeOptIn(rawHtml: string): boolean {
+  const metas = rawHtml.match(/<meta\b[^>]*>/gi);
+  if (!metas) return false;
+  return metas.some(
+    (tag) =>
+      /\bname\s*=\s*["']?plannotator-theme["']?/i.test(tag) &&
+      /\bcontent\s*=\s*["']?host["']?/i.test(tag),
+  );
+}
+
+/**
+ * Build the theme properties to write into the document. Bare host token names
+ * (`--muted`, `--background`, …) collide with author variables, so they are
+ * remapped to `--pn-*`; the originals ride along only for host-theme documents.
+ */
+export function buildThemeTokenPayload(
+  tokens: Record<string, string>,
+  hostTheme: boolean,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const [key, val] of Object.entries(tokens)) {
+    payload[PN_TOKEN_PREFIX + key.slice(2)] = val;
+    if (hostTheme) payload[key] = val;
+  }
+  return payload;
+}
+
+export interface SrcdocInjectionOptions {
+  /** Host theme tokens, keyed by bare name (as read from the host root). */
+  tokens: Record<string, string>;
+  /** Whether the host is currently in its light theme. */
+  isLight: boolean;
+  /** Document opted in to host theming (see {@link hasHostThemeOptIn}). */
+  hostTheme: boolean;
+  /** The version-diff view is showing (rawHtml is htmlDiff output). */
+  diffActive: boolean;
+}
+
+/** The `<style>` + `<script>` block spliced into the document's head. */
+export function buildSrcdocInjection({
+  tokens,
+  isLight,
+  hostTheme,
+  diffActive,
+}: SrcdocInjectionOptions): string {
+  const payload = buildThemeTokenPayload(tokens, hostTheme);
+  let themeCSS = ":root {\n";
+  for (const [key, val] of Object.entries(payload)) {
+    themeCSS += `  ${key}: ${val};\n`;
+  }
+  themeCSS += "}\n";
+  // Host-theme documents mirror the host's light/dark; arbitrary documents keep
+  // their own color-scheme resolution (document + OS), like a standalone tab.
+  if (hostTheme) {
+    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>`;
+}
+
+/** Splice the injection just before `</head>`, or prepend when there is none. */
+export function injectIntoHead(rawHtml: string, injection: string): string {
+  const headClose = rawHtml.indexOf("</head>");
+  if (headClose !== -1) {
+    return rawHtml.slice(0, headClose) + injection + rawHtml.slice(headClose);
+  }
+  return injection + rawHtml;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",