From dd1d497cc6531c89ea054c7e3d0c3d6b749b3a00 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:18:40 -0700
Subject: [PATCH 1/7] feat(ui): load the HTML viewer bridge by URL with a
 protocol version and ready timeout

Add an opt-in bridgeScriptUrl prop to HtmlViewer: the srcdoc document then
loads the bridge through a classic <script src> in the exact position the
inline script occupies (one injection point, buildBridgeScriptTag, for both
paths). The bridge stamps BRIDGE_PROTOCOL_VERSION on its ready message; the
parent warns once on a missing or mismatched stamp and, on the URL path
only, shows an error banner and calls onBridgeUnavailable. A ready timeout
(bridgeReadyTimeoutMs, default 5000) covers a blocked or missing asset.

Plannotator passes nothing and keeps the inline literal on every surface;
no timer and no banner exist on the inline path. The simulated ready posts
in the existing DOM suites now carry the stamp the real bridge sends.
---
 .github/workflows/test.yml                    |   1 +
 .../HtmlViewer.bridgeAsset.test.tsx           | 192 ++++++++++++++++++
 .../ui/components/html-viewer/HtmlViewer.tsx  | 134 +++++++++++-
 .../html-viewer/HtmlViewer.vimHud.test.tsx    |   3 +-
 .../components/html-viewer/bridge-script.ts   |  14 +-
 .../html-viewer/htmlLiveProtocol.test.tsx     |  15 +-
 .../html-viewer/htmlPinpointProtocol.test.tsx |  17 +-
 packages/ui/components/html-viewer/index.ts   |  14 +-
 packages/ui/components/html-viewer/srcdoc.ts  |  49 ++++-
 .../html-viewer/useHtmlAnnotation.ts          |  37 ++++
 10 files changed, 456 insertions(+), 20 deletions(-)
 create mode 100644 packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 2504566ec..f4b90cdd7 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -86,6 +86,7 @@ jobs:
           packages/ui/components/html-viewer/htmlPinpointProtocol.test.tsx
           packages/ui/components/html-viewer/htmlLiveProtocol.test.tsx
           packages/ui/components/html-viewer/HtmlViewer.vimHud.test.tsx
+          packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx
           packages/ui/components/Viewer.vimMode.integration.test.tsx
           packages/ui/hooks/useVimSelection.test.tsx
           packages/ui/utils/codeHighlight.test.ts
diff --git a/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx b/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx
new file mode 100644
index 000000000..fca950c8e
--- /dev/null
+++ b/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx
@@ -0,0 +1,192 @@
+/**
+ * HtmlViewer on the `bridgeScriptUrl` path (DOM-gated).
+ *
+ * Guards: the srcdoc carries a `<script src>` instead of the inline literal
+ * only when the prop is set; a ready without the protocol stamp (a cached
+ * asset from an older package) produces one console warning naming both
+ * versions plus the surface's error banner and host callback; a missing
+ * ready within `bridgeReadyTimeoutMs` produces the timeout banner and a
+ * late ready clears it; and the inline path runs no timer and shows no
+ * banner, so Plannotator's surface is unchanged.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import React from 'react';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BRIDGE_PROTOCOL_VERSION, BRIDGE_SCRIPT } from './bridge-script';
+import type { BridgeUnavailableInfo } from './HtmlViewer';
+
+const hasDom = typeof document !== 'undefined';
+const htmlViewerModule = hasDom ? await import('./HtmlViewer') : null;
+
+const mountedRoots: Array<{ unmount: () => void }> = [];
+const originalWarn = console.warn;
+const originalError = console.error;
+
+afterEach(async () => {
+  console.warn = originalWarn;
+  console.error = originalError;
+  if (!hasDom) return;
+  await act(async () => {
+    for (const root of mountedRoots.splice(0)) root.unmount();
+  });
+  document.body.replaceChildren();
+});
+
+const ASSET_URL = 'https://host.example/assets/bridge-script.deadbeef.js';
+
+async function mount(props: {
+  bridgeScriptUrl?: string;
+  bridgeReadyTimeoutMs?: number;
+  onBridgeUnavailable?: (info: BridgeUnavailableInfo) => void;
+}) {
+  if (!htmlViewerModule) throw new Error('DOM test environment is not registered');
+  const HtmlViewer = htmlViewerModule.HtmlViewer;
+  // happy-dom parses the srcdoc and, with script file loading disabled,
+  // reports the <script src> as a NotSupportedError through console.error.
+  // That is the environment, not the viewer (a browser fetches the asset):
+  // keep it out of the test output. Restored in afterEach.
+  if (props.bridgeScriptUrl) console.error = () => {};
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  mountedRoots.push(root);
+  await act(async () => {
+    root.render(
+      <HtmlViewer
+        rawHtml="<html><head><title>t</title></head><body><p>Target</p></body></html>"
+        annotations={[]}
+        onAddAnnotation={() => {}}
+        onSelectAnnotation={() => {}}
+        selectedAnnotationId={null}
+        mode="selection"
+        inputMethod="pinpoint"
+        {...props}
+      />,
+    );
+  });
+  const iframe = host.querySelector<HTMLIFrameElement>('iframe');
+  if (!iframe?.contentWindow) throw new Error('HTML iframe missing');
+  const postedToIframe: Array<Record<string, unknown>> = [];
+  const realPost = iframe.contentWindow.postMessage.bind(iframe.contentWindow);
+  (iframe.contentWindow as unknown as { postMessage: (data: unknown) => void }).postMessage =
+    ((data: unknown, ...rest: unknown[]) => {
+      if (data && typeof data === 'object') postedToIframe.push(data as Record<string, unknown>);
+      return (realPost as (...args: unknown[]) => unknown)(data, ...rest);
+    }) as typeof iframe.contentWindow.postMessage;
+  const postReady = async (data: Record<string, unknown>) => {
+    await act(async () => {
+      window.dispatchEvent(new MessageEvent('message', { source: iframe.contentWindow, data }));
+    });
+  };
+  const banner = () => host.querySelector<HTMLElement>('[data-bridge-error]');
+  return { host, iframe, postReady, postedToIframe, banner };
+}
+
+function captureWarnings(): string[] {
+  const warnings: string[] = [];
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(' '));
+  };
+  return warnings;
+}
+
+const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+describe.if(hasDom)('HtmlViewer bridgeScriptUrl', () => {
+  test('the srcdoc loads the bridge by URL instead of inlining it', async () => {
+    const { iframe } = await mount({ bridgeScriptUrl: ASSET_URL });
+    const srcdoc = iframe.getAttribute('srcdoc') ?? '';
+    expect(srcdoc).toContain(`<script src="${ASSET_URL}"></script>`);
+    expect(srcdoc).not.toContain(BRIDGE_SCRIPT);
+    // The sandbox is unchanged by the delivery path.
+    expect(iframe.getAttribute('sandbox')).toBe('allow-scripts');
+  });
+
+  test('without the prop the srcdoc inlines the bridge, as before', async () => {
+    const { iframe, banner } = await mount({});
+    const srcdoc = iframe.getAttribute('srcdoc') ?? '';
+    expect(srcdoc).toContain(`<script>${BRIDGE_SCRIPT}</script>`);
+    expect(srcdoc).not.toContain('<script src=');
+    expect(banner()).toBeNull();
+  });
+
+  test('a stale asset (ready without the stamp) warns once naming both versions, shows the banner, and still honors the ready', async () => {
+    const warnings = captureWarnings();
+    const unavailable: BridgeUnavailableInfo[] = [];
+    const { postReady, postedToIframe, banner } = await mount({
+      bridgeScriptUrl: ASSET_URL,
+      onBridgeUnavailable: (info) => unavailable.push(info),
+    });
+    await postReady({ type: 'plannotator-bridge-ready' });
+
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toContain(`expects ${BRIDGE_PROTOCOL_VERSION}`);
+    expect(warnings[0]).toContain('reported none');
+    expect(warnings[0]).toContain(ASSET_URL);
+
+    const el = banner();
+    expect(el?.getAttribute('data-bridge-error')).toBe('version-mismatch');
+    expect(el?.getAttribute('role')).toBe('alert');
+    expect(el?.textContent).toContain(ASSET_URL);
+    expect(unavailable).toEqual([
+      { kind: 'version-mismatch', url: ASSET_URL, expectedVersion: BRIDGE_PROTOCOL_VERSION, reportedVersion: undefined },
+    ]);
+    // Not a refusal: the parent still configures the older bridge.
+    expect(postedToIframe.some((m) => m.type === 'plannotator-bridge-sync-annotations')).toBe(true);
+  });
+
+  test('a matching ready shows no banner and cancels the ready timer', async () => {
+    const warnings = captureWarnings();
+    const unavailable: BridgeUnavailableInfo[] = [];
+    const { postReady, banner } = await mount({
+      bridgeScriptUrl: ASSET_URL,
+      bridgeReadyTimeoutMs: 40,
+      onBridgeUnavailable: (info) => unavailable.push(info),
+    });
+    await postReady({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
+    await act(async () => { await wait(80); });
+    expect(warnings).toEqual([]);
+    expect(banner()).toBeNull();
+    expect(unavailable).toEqual([]);
+  });
+
+  test('no ready within bridgeReadyTimeoutMs shows the timeout banner; a late ready clears it', async () => {
+    const unavailable: BridgeUnavailableInfo[] = [];
+    const { postReady, banner } = await mount({
+      bridgeScriptUrl: ASSET_URL,
+      bridgeReadyTimeoutMs: 30,
+      onBridgeUnavailable: (info) => unavailable.push(info),
+    });
+    expect(banner()).toBeNull();
+    await act(async () => { await wait(70); });
+    const el = banner();
+    expect(el?.getAttribute('data-bridge-error')).toBe('timeout');
+    expect(el?.textContent).toContain('30 ms');
+    expect(el?.textContent).toContain(ASSET_URL);
+    expect(unavailable).toEqual([{ kind: 'timeout', url: ASSET_URL, timeoutMs: 30 }]);
+
+    await postReady({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
+    expect(banner()).toBeNull();
+  });
+
+  test('inline path: no timer, no banner, no callback; a stamp-less ready only warns', async () => {
+    const warnings = captureWarnings();
+    const unavailable: BridgeUnavailableInfo[] = [];
+    const { postReady, banner, postedToIframe } = await mount({
+      // A tiny timeout that would fire if the inline path ever armed a timer.
+      bridgeReadyTimeoutMs: 10,
+      onBridgeUnavailable: (info) => unavailable.push(info),
+    });
+    await act(async () => { await wait(50); });
+    expect(banner()).toBeNull();
+    expect(unavailable).toEqual([]);
+
+    await postReady({ type: 'plannotator-bridge-ready' });
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).not.toContain(ASSET_URL);
+    expect(banner()).toBeNull();
+    expect(unavailable).toEqual([]);
+    expect(postedToIframe.some((m) => m.type === 'plannotator-bridge-sync-annotations')).toBe(true);
+  });
+});
diff --git a/packages/ui/components/html-viewer/HtmlViewer.tsx b/packages/ui/components/html-viewer/HtmlViewer.tsx
index 56f217be8..92fcb2736 100644
--- a/packages/ui/components/html-viewer/HtmlViewer.tsx
+++ b/packages/ui/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,
@@ -131,6 +133,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 +255,29 @@ 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 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.
+   * 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 +320,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       maxAdditionalTargets,
       scrollBehavior,
       title = "HTML Plan Viewer",
+      bridgeScriptUrl,
+      bridgeReadyTimeoutMs = DEFAULT_BRIDGE_READY_TIMEOUT_MS,
+      onBridgeUnavailable,
     },
     ref,
   ) => {
@@ -320,6 +380,11 @@ 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.
+    const bridgeUrl = !liveMode && bridgeScriptUrl ? bridgeScriptUrl : undefined;
+    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 +392,35 @@ 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);
+    const readyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const onBridgeUnavailableRef = useRef(onBridgeUnavailable);
+    onBridgeUnavailableRef.current = onBridgeUnavailable;
+    useEffect(() => {
+      if (!bridgeUrl || srcdoc === undefined) return;
+      setBridgeError(null);
+      const url = bridgeUrl;
+      const timeoutMs = bridgeReadyTimeoutMs;
+      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, bridgeReadyTimeoutMs]);
+    useEffect(() => {
+      if (bridgeError) onBridgeUnavailableRef.current?.(bridgeError);
+    }, [bridgeError]);
 
     const handleResize = useCallback((height: number) => {
       if (liveMode) return; // live surfaces are full-viewport; height is ignored
@@ -516,6 +607,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 +1034,20 @@ 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 && (
+              <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"
+              >
+                {formatBridgeUnavailableMessage(bridgeError)}
+              </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. */}
diff --git a/packages/ui/components/html-viewer/HtmlViewer.vimHud.test.tsx b/packages/ui/components/html-viewer/HtmlViewer.vimHud.test.tsx
index cf75b5916..902c79994 100644
--- a/packages/ui/components/html-viewer/HtmlViewer.vimHud.test.tsx
+++ b/packages/ui/components/html-viewer/HtmlViewer.vimHud.test.tsx
@@ -3,6 +3,7 @@ import React from 'react';
 import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import { AnnotationType } from '../../types';
+import { BRIDGE_PROTOCOL_VERSION } from './bridge-script';
 
 const hasDom = typeof document !== 'undefined';
 const htmlViewerModule = hasDom ? await import('./HtmlViewer') : null;
@@ -66,7 +67,7 @@ describe.if(hasDom)('HtmlViewer Vim HUD bridge', () => {
       }));
     };
 
-    act(() => dispatchBridgeMessage({ type: 'plannotator-bridge-ready' }));
+    act(() => dispatchBridgeMessage({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION }));
     act(() => dispatchBridgeMessage({
       type: 'plannotator-bridge-unanchored',
       ids: ['removed-text'],
diff --git a/packages/ui/components/html-viewer/bridge-script.ts b/packages/ui/components/html-viewer/bridge-script.ts
index d82d7b0a6..9acc091f4 100644
--- a/packages/ui/components/html-viewer/bridge-script.ts
+++ b/packages/ui/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);
   }
diff --git a/packages/ui/components/html-viewer/htmlLiveProtocol.test.tsx b/packages/ui/components/html-viewer/htmlLiveProtocol.test.tsx
index f0867cb13..2dd5217a9 100644
--- a/packages/ui/components/html-viewer/htmlLiveProtocol.test.tsx
+++ b/packages/ui/components/html-viewer/htmlLiveProtocol.test.tsx
@@ -18,6 +18,7 @@ import React from 'react';
 import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import type { Annotation } from '../../types';
+import { BRIDGE_PROTOCOL_VERSION } from './bridge-script';
 
 const hasDom = typeof document !== 'undefined';
 const hookModule = hasDom ? await import('./useHtmlAnnotation') : null;
@@ -176,7 +177,7 @@ describe.if(hasDom)('live parent side (HtmlViewer with src + liveSession)', () =
     const { post, postedToIframe } = await mountLiveViewer({
       annotations: [],
     });
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/', token: LIVE_TOKEN });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/', token: LIVE_TOKEN });
     expect(postedToIframe.length).toBeGreaterThan(0);
     for (const posted of postedToIframe) {
       expect(posted.data.token).toBe(LIVE_TOKEN);
@@ -190,10 +191,10 @@ describe.if(hasDom)('live parent side (HtmlViewer with src + liveSession)', () =
   test('an unauthenticated ready is ignored; an authenticated one forwards its pageUrl', async () => {
     const pages: string[] = [];
     const { post, postedToIframe } = await mountLiveViewer({ onPageChange: (p) => pages.push(p) });
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/spoofed' }, LIVE_ORIGIN);
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/spoofed' }, LIVE_ORIGIN);
     expect(pages).toEqual([]);
     expect(postedToIframe.length).toBe(0);
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/dashboard?x=1', token: LIVE_TOKEN });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/dashboard?x=1', token: LIVE_TOKEN });
     expect(pages).toEqual(['/dashboard?x=1']);
   });
 
@@ -227,7 +228,7 @@ describe.if(hasDom)('live parent side (HtmlViewer with src + liveSession)', () =
       annotations: [pageAnn('on-home', '/'), pageAnn('on-about', '/about')],
       currentPageUrl: '/',
     });
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/', token: LIVE_TOKEN });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/', token: LIVE_TOKEN });
     const restores = postedToIframe.filter((p) => p.data.type === 'plannotator-bridge-find-and-mark');
     expect(restores.map((p) => p.data.id)).toEqual(['on-home']);
     // Numbering still ships the FULL list (global numbers across pages).
@@ -300,7 +301,7 @@ describe.if(hasDom)('live parent side (HtmlViewer with src + liveSession)', () =
         }));
       });
     };
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/' });
     await post({ type: 'plannotator-bridge-unanchored', ids: ['home-1'] });
     expect(received).toEqual([['home-1']]);
 
@@ -318,7 +319,7 @@ describe.if(hasDom)('live parent side (HtmlViewer with src + liveSession)', () =
 
   test('the Interact/Annotate mode is pushed on EVERY bridge ready, so it survives page-change reloads and bridge re-injection', async () => {
     const { post, postedToIframe } = await mountLiveViewer({ annotateModeActive: false });
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/', token: LIVE_TOKEN });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/', token: LIVE_TOKEN });
     const modePosts = () =>
       postedToIframe.filter((p) => p.data.type === 'plannotator-bridge-set-annotate-mode');
     expect(modePosts().length).toBe(1);
@@ -327,7 +328,7 @@ describe.if(hasDom)('live parent side (HtmlViewer with src + liveSession)', () =
     // again from a FRESH document: the mode must be re-established, not lost
     // to the fresh bridge's default.
     postedToIframe.length = 0;
-    await post({ type: 'plannotator-bridge-ready', pageUrl: '/about', token: LIVE_TOKEN });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION, pageUrl: '/about', token: LIVE_TOKEN });
     expect(modePosts().length).toBe(1);
     expect(modePosts()[0]!.data.active).toBe(false);
   });
diff --git a/packages/ui/components/html-viewer/htmlPinpointProtocol.test.tsx b/packages/ui/components/html-viewer/htmlPinpointProtocol.test.tsx
index fbf0399cc..ec8d6ed7a 100644
--- a/packages/ui/components/html-viewer/htmlPinpointProtocol.test.tsx
+++ b/packages/ui/components/html-viewer/htmlPinpointProtocol.test.tsx
@@ -14,6 +14,7 @@ import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import type { Annotation } from '../../types';
 import { AnnotationType } from '../../types';
+import { BRIDGE_PROTOCOL_VERSION } from './bridge-script';
 
 const hasDom = typeof document !== 'undefined';
 const hookModule = hasDom ? await import('./useHtmlAnnotation') : null;
@@ -431,7 +432,7 @@ describe.if(hasDom)('ordered saved-annotation sync (placed-marker numbering)', (
       await act(async () => {
         window.dispatchEvent(new MessageEvent('message', {
           source: iframe.contentWindow,
-          data: { type: 'plannotator-bridge-ready' },
+          data: { type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION },
         }));
       });
     };
@@ -1123,7 +1124,7 @@ describe.if(hasDom)('readOnly view-only contract', () => {
 
   test('readOnly still restores markers and syncs export-matching numbers on ready', async () => {
     const { post, postedToIframe } = await mountReadOnly([committed('ro-1'), committed('ro-2')]);
-    await post({ type: 'plannotator-bridge-ready' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
 
     const restores = postedToIframe.filter((m) => m.type === 'plannotator-bridge-find-and-mark');
     expect(restores.map((m) => m.id)).toEqual(['ro-1', 'ro-2']);
@@ -1141,14 +1142,14 @@ describe.if(hasDom)('readOnly view-only contract', () => {
   test('readOnly marker clicks still navigate via onSelectAnnotation', async () => {
     const selected: Array<string | null> = [];
     const { post } = await mountReadOnly([committed('ro-1')], (id) => selected.push(id));
-    await post({ type: 'plannotator-bridge-ready' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
     await post({ type: 'plannotator-bridge-mark-click', id: 'ro-1' });
     expect(selected).toEqual(['ro-1']);
   });
 
   test('readOnly ignores selection messages: no toolbar, no composer', async () => {
     const { post } = await mountReadOnly([committed('ro-1')]);
-    await post({ type: 'plannotator-bridge-ready' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
     await post({
       type: 'plannotator-bridge-selection',
       text: 'Read-only target',
@@ -1274,7 +1275,7 @@ describe.if(hasDom)('unanchored report (trust boundary + delivery)', () => {
         window.dispatchEvent(new MessageEvent('message', { source: iframe.contentWindow, data }));
       });
     };
-    const ready = () => post({ type: 'plannotator-bridge-ready' });
+    const ready = () => post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
     return { render, post, ready, added, postedToIframe };
   }
 
@@ -1407,7 +1408,7 @@ describe.if(hasDom)('unanchored report (trust boundary + delivery)', () => {
 
     // Host swapped: its list carries the server row only.
     await render([pageRow('srv-1')]);
-    await post({ type: 'plannotator-bridge-ready' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
     await post({ type: MSG, ids: [localId, 'srv-1'] });
     expect(received.at(-1)).toEqual(['srv-1']);
 
@@ -1467,7 +1468,7 @@ describe.if(hasDom)('Interact/Annotate mode on static (srcdoc) surfaces', () =>
 
   test('static surfaces default to Annotate armed: set-annotate-mode active:true rides every ready', async () => {
     const { post, postedToIframe } = await mountModeViewer();
-    await post({ type: 'plannotator-bridge-ready' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
     const modePosts = postedToIframe.filter((m) => m.type === 'plannotator-bridge-set-annotate-mode');
     expect(modePosts.length).toBe(1);
     expect(modePosts[0]!.active).toBe(true);
@@ -1475,7 +1476,7 @@ describe.if(hasDom)('Interact/Annotate mode on static (srcdoc) surfaces', () =>
 
   test('a host-driven Interact state is pushed instead of the default', async () => {
     const { post, postedToIframe } = await mountModeViewer({ annotateModeActive: false });
-    await post({ type: 'plannotator-bridge-ready' });
+    await post({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
     const modePosts = postedToIframe.filter((m) => m.type === 'plannotator-bridge-set-annotate-mode');
     expect(modePosts.length).toBe(1);
     expect(modePosts[0]!.active).toBe(false);
diff --git a/packages/ui/components/html-viewer/index.ts b/packages/ui/components/html-viewer/index.ts
index 6573a9a66..6c818c9df 100644
--- a/packages/ui/components/html-viewer/index.ts
+++ b/packages/ui/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,
diff --git a/packages/ui/components/html-viewer/srcdoc.ts b/packages/ui/components/html-viewer/srcdoc.ts
index 8715d65ab..f02e1d429 100644
--- a/packages/ui/components/html-viewer/srcdoc.ts
+++ b/packages/ui/components/html-viewer/srcdoc.ts
@@ -96,6 +96,46 @@ 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 and ordering relative
+   * to the page's own scripts are identical on both paths (parser-blocking in
+   * `<head>`, before the body). No `crossorigin` attribute is set: the srcdoc
+   * frame is an opaque origin, and a classic script needs no CORS to execute.
+   */
+  bridgeScriptUrl?: string;
+}
+
+/** 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 +144,7 @@ export function buildSrcdocInjection({
   isLight,
   hostTheme,
   diffActive,
+  bridgeScriptUrl,
 }: SrcdocInjectionOptions): string {
   const payload = buildThemeTokenPayload(tokens, hostTheme);
   let themeCSS = ":root {\n";
@@ -117,7 +158,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 +167,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;
diff --git a/packages/ui/components/html-viewer/useHtmlAnnotation.ts b/packages/ui/components/html-viewer/useHtmlAnnotation.ts
index 2e31c725c..5174da0ef 100644
--- a/packages/ui/components/html-viewer/useHtmlAnnotation.ts
+++ b/packages/ui/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;

From 3949e727289080aadfc8cb6e1f8a059a7513ea94 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:18:53 -0700
Subject: [PATCH 2/7] build(ui): generate the bridge asset and lite module at
 prepack

scripts/build-bridge-assets.ts derives two gitignored files from the source
module beside it: bridge-script.asset.js (byte-for-byte BRIDGE_SCRIPT, for
hosts that serve it as a hashed static file and pass its URL to HtmlViewer)
and bridge-script.lite.ts (the CSS, protocol version and live bootstrap with
the literal stubbed, an optional bundler alias target that drops the 185 KB
string from a host's viewer chunk). Both get exports subpaths and ship in the
tarball; bridgeAsset.test.ts regenerates them into a temp dir and compares
them to the module, pins the single injection point and the absence of any
CSP meta, and runs the real bridge in an isolated window to assert its ready
carries the stamp.
---
 .gitignore                                    |   3 +
 .../html-viewer/bridgeAsset.test.ts           | 199 ++++++++++++++++++
 packages/ui/package.json                      |   5 +-
 packages/ui/scripts/build-bridge-assets.ts    |  80 +++++++
 4 files changed, 286 insertions(+), 1 deletion(-)
 create mode 100644 packages/ui/components/html-viewer/bridgeAsset.test.ts
 create mode 100644 packages/ui/scripts/build-bridge-assets.ts

diff --git a/.gitignore b/.gitignore
index 1b5b2d2b8..ac5312dc7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -74,4 +74,7 @@ security-results/
 # @plannotator/ui CSS build artifacts (generated by prepack — not committed)
 packages/ui/styles.css
 packages/ui/styles.js
+# HTML viewer bridge assets, generated at prepack from bridge-script.ts
+packages/ui/components/html-viewer/bridge-script.asset.js
+packages/ui/components/html-viewer/bridge-script.lite.ts
 .wrangler/
diff --git a/packages/ui/components/html-viewer/bridgeAsset.test.ts b/packages/ui/components/html-viewer/bridgeAsset.test.ts
new file mode 100644
index 000000000..e990b62fa
--- /dev/null
+++ b/packages/ui/components/html-viewer/bridgeAsset.test.ts
@@ -0,0 +1,199 @@
+/**
+ * The bridge-as-asset seam, package side (no DOM registration needed):
+ *
+ * - the generated `bridge-script.asset.js` is byte-for-byte `BRIDGE_SCRIPT`
+ *   and the generated `bridge-script.lite.ts` carries the other exports
+ *   unchanged with the literal stubbed (a generator that drifts from the
+ *   source module would ship a bridge that disagrees with the parent);
+ * - the package manifest wires both files (exports subpaths, `files`,
+ *   `prepack`) so `bun pm pack` ships them and a `?url` import resolves;
+ * - the srcdoc injection has ONE bridge script element: inline by default,
+ *   `<script src>` on the URL path, with no `crossorigin` and no CSP meta;
+ * - the real bridge, executed in an isolated window, posts a `ready` that
+ *   carries `BRIDGE_PROTOCOL_VERSION`, and the parent's check accepts exactly
+ *   that and rejects a stamp-less ready (a stale asset).
+ */
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  ANNOTATION_HIGHLIGHT_CSS,
+  BRIDGE_PROTOCOL_VERSION,
+  BRIDGE_SCRIPT,
+  LIVE_BRIDGE_BOOTSTRAP,
+} from "./bridge-script";
+import {
+  BRIDGE_ASSET_DIR,
+  BRIDGE_ASSET_FILENAME,
+  BRIDGE_LITE_FILENAME,
+  writeBridgeAssets,
+} from "../../scripts/build-bridge-assets";
+import { buildBridgeScriptTag, buildSrcdocInjection, injectIntoHead } from "./srcdoc";
+import { checkBridgeProtocolVersion, formatBridgeProtocolWarning } from "./useHtmlAnnotation";
+
+const uiRoot = resolve(import.meta.dir, "../..");
+
+describe("generated bridge assets", () => {
+  test("the asset is byte-for-byte BRIDGE_SCRIPT and the lite module keeps every other export", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "plannotator-bridge-asset-"));
+    try {
+      const written = writeBridgeAssets(dir);
+      expect(written.map((p) => p.slice(dir.length + 1)).sort()).toEqual(
+        [BRIDGE_ASSET_FILENAME, BRIDGE_LITE_FILENAME].sort(),
+      );
+      const asset = readFileSync(join(dir, BRIDGE_ASSET_FILENAME));
+      expect(asset.equals(Buffer.from(BRIDGE_SCRIPT, "utf8"))).toBe(true);
+
+      // Determinism: a second run produces the same bytes.
+      writeBridgeAssets(dir);
+      expect(readFileSync(join(dir, BRIDGE_ASSET_FILENAME)).equals(asset)).toBe(true);
+
+      const lite = await import(join(dir, BRIDGE_LITE_FILENAME));
+      expect(lite.ANNOTATION_HIGHLIGHT_CSS).toBe(ANNOTATION_HIGHLIGHT_CSS);
+      expect(lite.LIVE_BRIDGE_BOOTSTRAP).toBe(LIVE_BRIDGE_BOOTSTRAP);
+      expect(lite.BRIDGE_PROTOCOL_VERSION).toBe(BRIDGE_PROTOCOL_VERSION);
+      expect(lite.BRIDGE_SCRIPT).toBe("");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // A stale local artifact (generated before a bridge edit) would ship a
+  // bridge that disagrees with the parent. Only checked when present: the
+  // files are gitignored and exist after `prepack`.
+  test.skipIf(!existsSync(join(BRIDGE_ASSET_DIR, BRIDGE_ASSET_FILENAME)))(
+    "an already-generated asset in the package matches the current source",
+    () => {
+      const asset = readFileSync(join(BRIDGE_ASSET_DIR, BRIDGE_ASSET_FILENAME), "utf8");
+      expect(asset === BRIDGE_SCRIPT).toBe(true);
+    },
+  );
+
+  test("the package manifest ships and exports both generated files", () => {
+    const pkg = JSON.parse(readFileSync(join(uiRoot, "package.json"), "utf8")) as {
+      exports: Record<string, string>;
+      files: string[];
+      scripts: Record<string, string>;
+    };
+    expect(pkg.exports[`./components/html-viewer/${BRIDGE_ASSET_FILENAME}`]).toBe(
+      `./components/html-viewer/${BRIDGE_ASSET_FILENAME}`,
+    );
+    expect(pkg.exports["./components/html-viewer/bridge-script.lite"]).toBe(
+      `./components/html-viewer/${BRIDGE_LITE_FILENAME}`,
+    );
+    // `files` covers components/ and nothing excludes the generated names.
+    expect(pkg.files).toContain("components");
+    expect(pkg.files.some((entry) => entry.startsWith("!") && /bridge-script/.test(entry))).toBe(false);
+    expect(pkg.scripts.prepack).toContain("build:bridge-assets");
+    // The generated directory is the source module's own directory.
+    expect(BRIDGE_ASSET_DIR).toBe(dirname(resolve(import.meta.dir, "bridge-script.ts")));
+  });
+});
+
+describe("srcdoc bridge script tag", () => {
+  const base = { tokens: {}, isLight: true, hostTheme: false, diffActive: false };
+
+  test("default (no URL): the inline literal, exactly one script element, no src", () => {
+    const injection = buildSrcdocInjection(base);
+    expect(injection.endsWith(`<script>${BRIDGE_SCRIPT}</script>`)).toBe(true);
+    expect(injection.split("<script").length - 1).toBe(1);
+    expect(buildBridgeScriptTag()).toBe(`<script>${BRIDGE_SCRIPT}</script>`);
+    // An empty string is "absent": a host misconfiguration must not produce
+    // <script src=""> (which would load the host page itself as a script).
+    expect(buildBridgeScriptTag("")).toBe(`<script>${BRIDGE_SCRIPT}</script>`);
+  });
+
+  test("URL path: a classic <script src> takes the inline script's place, without crossorigin", () => {
+    const url = "https://host.example/assets/bridge-script.abc123.js";
+    const injection = buildSrcdocInjection({ ...base, bridgeScriptUrl: url });
+    const inline = buildSrcdocInjection(base);
+    // Same prefix (the style block), same position: the tag replaces the
+    // inline element rather than being added beside it.
+    const stylePrefix = inline.slice(0, inline.indexOf("<script"));
+    expect(injection.startsWith(stylePrefix)).toBe(true);
+    expect(injection.slice(stylePrefix.length)).toBe(`<script src="${url}"></script>`);
+    expect(injection).not.toContain(BRIDGE_SCRIPT);
+    expect(injection).not.toContain("crossorigin");
+  });
+
+  test("the URL is attribute-escaped so it cannot break out of the tag", () => {
+    const tag = buildBridgeScriptTag('/b.js" onerror="alert(1)');
+    expect(tag).toBe('<script src="/b.js&quot; onerror=&quot;alert(1)"></script>');
+  });
+
+  test("the package adds no CSP meta to the srcdoc document on either path", () => {
+    const page = "<html><head><title>t</title></head><body><p>x</p></body></html>";
+    for (const bridgeScriptUrl of [undefined, "/assets/bridge.js"]) {
+      const doc = injectIntoHead(page, buildSrcdocInjection({ ...base, bridgeScriptUrl }));
+      expect(doc).not.toMatch(/<meta[^>]*http-equiv/i);
+    }
+    // Nor does the bridge itself write one at runtime.
+    expect(BRIDGE_SCRIPT).not.toMatch(/http-equiv/i);
+    expect(BRIDGE_SCRIPT).not.toMatch(/content-security-policy/i);
+  });
+});
+
+describe("bridge protocol version", () => {
+  /** Run the real bridge in an isolated happy-dom window whose `parent` is a
+   * spy, so the test sees exactly what a srcdoc frame would post. happy-dom
+   * is reached through the registrator's own dependency so no new package
+   * dependency is needed; the global document (if any) is untouched. */
+  async function runBridgeIsolated(): Promise<unknown[]> {
+    const registrator = Bun.resolveSync("@happy-dom/global-registrator", uiRoot);
+    const happyDom = Bun.resolveSync("happy-dom", dirname(registrator));
+    const { Window } = (await import(happyDom)) as { Window: new (o: { url: string }) => Record<string, unknown> };
+    const win = new Window({ url: "about:srcdoc" });
+    (win.document as { write: (s: string) => void }).write("<html><body><p>hi</p></body></html>");
+    const posted: unknown[] = [];
+    const parent = { postMessage: (message: unknown) => posted.push(message) };
+    const names = [
+      "window", "document", "parent", "top", "self", "globalThis", "location",
+      "ResizeObserver", "MutationObserver", "getComputedStyle", "requestAnimationFrame",
+      "cancelAnimationFrame", "setTimeout", "clearTimeout", "Node", "Element",
+      "HTMLElement", "performance", "getSelection", "navigator",
+    ];
+    const values = names.map((name) =>
+      name === "parent" ? parent
+        : name === "top" || name === "self" || name === "globalThis" ? win
+        : win[name],
+    );
+    try {
+      new Function(...names, BRIDGE_SCRIPT)(...values);
+    } finally {
+      const happy = win.happyDOM as { close?: () => Promise<void> } | undefined;
+      await happy?.close?.();
+    }
+    return posted;
+  }
+
+  test("the executed bridge posts a ready stamped with BRIDGE_PROTOCOL_VERSION", async () => {
+    const posted = await runBridgeIsolated();
+    const ready = posted.find(
+      (m) => typeof m === "object" && m !== null && (m as { type?: unknown }).type === "plannotator-bridge-ready",
+    ) as { protocolVersion?: unknown } | undefined;
+    expect(ready).toBeDefined();
+    expect(ready!.protocolVersion).toBe(BRIDGE_PROTOCOL_VERSION);
+    // The parent's check accepts the real bridge's ready as-is.
+    expect(checkBridgeProtocolVersion(ready).ok).toBe(true);
+  });
+
+  test("a stale asset's ready (no stamp, or another version) is a detected mismatch naming both versions", () => {
+    const stale = checkBridgeProtocolVersion({ type: "plannotator-bridge-ready" });
+    expect(stale).toEqual({ ok: false, expected: BRIDGE_PROTOCOL_VERSION, reported: undefined });
+    const other = checkBridgeProtocolVersion({
+      type: "plannotator-bridge-ready",
+      protocolVersion: BRIDGE_PROTOCOL_VERSION + 1,
+    });
+    expect(other.ok).toBe(false);
+    expect(other.reported).toBe(BRIDGE_PROTOCOL_VERSION + 1);
+    // Non-numeric stamps are not a version.
+    expect(checkBridgeProtocolVersion({ type: "plannotator-bridge-ready", protocolVersion: "1" }).ok).toBe(false);
+
+    const warning = formatBridgeProtocolWarning(other, "https://h/bridge.js");
+    expect(warning).toContain(`expects ${BRIDGE_PROTOCOL_VERSION}`);
+    expect(warning).toContain(`reported ${BRIDGE_PROTOCOL_VERSION + 1}`);
+    expect(warning).toContain("https://h/bridge.js");
+    expect(formatBridgeProtocolWarning(stale)).toContain("reported none");
+  });
+});
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 20e622b4a..30655491d 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -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",
@@ -109,6 +111,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"
   }
 }
diff --git a/packages/ui/scripts/build-bridge-assets.ts b/packages/ui/scripts/build-bridge-assets.ts
new file mode 100644
index 000000000..d121cc955
--- /dev/null
+++ b/packages/ui/scripts/build-bridge-assets.ts
@@ -0,0 +1,80 @@
+/**
+ * Generate the HTML viewer bridge assets that ship in the npm package.
+ *
+ * `components/html-viewer/bridge-script.ts` stays the source of truth: the
+ * Plannotator CLI and the Pi extension import its string exports under Bun,
+ * and the srcdoc path inlines `BRIDGE_SCRIPT` by default. This script derives
+ * two files from it at `prepack` (both gitignored, both deterministic):
+ *
+ * - `bridge-script.asset.js`: the bridge IIFE, byte-for-byte `BRIDGE_SCRIPT`,
+ *   for hosts that serve it as a hashed static asset and pass its URL to
+ *   `HtmlViewer` as `bridgeScriptUrl` (a Vite `?url` import of the package
+ *   subpath). The `.asset.js` name is deliberate: a plain `bridge-script.js`
+ *   beside `bridge-script.ts` would be picked FIRST by Vite's extension probe
+ *   for the package's own `./bridge-script` imports (`.js` precedes `.ts` in
+ *   `resolve.extensions`), which would break every consumer build.
+ * - `bridge-script.lite.ts`: an alias target with the same CSS, protocol
+ *   version and live bootstrap but `BRIDGE_SCRIPT = ""`, so a host on the URL
+ *   path can point its bundler's `./bridge-script` resolution at it and drop
+ *   the 185 KB literal from its viewer chunk. Optional; without the alias the
+ *   URL path still works, the literal is merely carried unused.
+ *
+ * `bridgeAsset.test.ts` regenerates both into a temp dir and compares them to
+ * the source exports, so a drift between the generator and the module fails
+ * the suite rather than shipping.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  ANNOTATION_HIGHLIGHT_CSS,
+  BRIDGE_PROTOCOL_VERSION,
+  BRIDGE_SCRIPT,
+  LIVE_BRIDGE_BOOTSTRAP,
+} from "../components/html-viewer/bridge-script";
+
+export const BRIDGE_ASSET_FILENAME = "bridge-script.asset.js";
+export const BRIDGE_LITE_FILENAME = "bridge-script.lite.ts";
+
+/** Where the assets live in the package (beside their source module). */
+export const BRIDGE_ASSET_DIR = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../components/html-viewer",
+);
+
+/** The runnable asset: exactly the inline string, no banner, no trailer. */
+export function renderBridgeAsset(): string {
+  return BRIDGE_SCRIPT;
+}
+
+/** The alias module: every export of `./bridge-script` except the literal. */
+export function renderBridgeLiteModule(): string {
+  return [
+    "// @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 = ${JSON.stringify(ANNOTATION_HIGHLIGHT_CSS)};`,
+    `export const BRIDGE_PROTOCOL_VERSION = ${JSON.stringify(BRIDGE_PROTOCOL_VERSION)};`,
+    'export const BRIDGE_SCRIPT = "";',
+    `export const LIVE_BRIDGE_BOOTSTRAP = ${JSON.stringify(LIVE_BRIDGE_BOOTSTRAP)};`,
+    "",
+  ].join("\n");
+}
+
+/** Write both files into `dir`; returns the paths written. */
+export function writeBridgeAssets(dir: string = BRIDGE_ASSET_DIR): string[] {
+  mkdirSync(dir, { recursive: true });
+  const asset = join(dir, BRIDGE_ASSET_FILENAME);
+  const lite = join(dir, BRIDGE_LITE_FILENAME);
+  writeFileSync(asset, renderBridgeAsset(), "utf8");
+  writeFileSync(lite, renderBridgeLiteModule(), "utf8");
+  return [asset, lite];
+}
+
+if (import.meta.main) {
+  for (const path of writeBridgeAssets()) {
+    console.log(`wrote ${path}`);
+  }
+}

From 48c06ccfa4e8a777adcd57e44f0795568c091e8c Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:18:53 -0700
Subject: [PATCH 3/7] test: pin the live proxy and the single-file bundles to
 the inline bridge

The live-app proxy keeps composing and injecting the inline bridge from its
own route on both transports and both runtimes, and never references the
srcdoc URL seam or the generated files. The built hook and review bundles
carry the bridge literal exactly once, as on main.
---
 .../shared/live-proxy-bridge-inline.test.ts   | 61 +++++++++++++++++++
 tests/entry-assets.test.ts                    | 15 +++++
 2 files changed, 76 insertions(+)
 create mode 100644 packages/shared/live-proxy-bridge-inline.test.ts

diff --git a/packages/shared/live-proxy-bridge-inline.test.ts b/packages/shared/live-proxy-bridge-inline.test.ts
new file mode 100644
index 000000000..bd743b7cc
--- /dev/null
+++ b/packages/shared/live-proxy-bridge-inline.test.ts
@@ -0,0 +1,61 @@
+/**
+ * Live app annotation is untouched by the HtmlViewer `bridgeScriptUrl` seam:
+ * the proxy keeps composing the INLINE bridge body it serves from its own
+ * route and injecting that route's tag into proxied HTML. A later change
+ * that routed the live path through the package asset (or its URL prop)
+ * would move a per-session token-bearing body onto a host-served file, so
+ * this pins the current shape at source level, on both transports and both
+ * runtimes' composers.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+// Relative on purpose: @plannotator/ui is not a dependency of shared; only the
+// CLI and Pi import the bridge module, and this test reads the same file.
+import { BRIDGE_SCRIPT, LIVE_BRIDGE_BOOTSTRAP } from "../ui/components/html-viewer/bridge-script";
+import {
+  LIVE_PROXY_BRIDGE_PATH,
+  LIVE_PROXY_BRIDGE_TAG,
+  composeLiveBridgeJs,
+} from "./live-proxy-core";
+
+const root = resolve(import.meta.dir, "../..");
+const read = (path: string) => readFileSync(resolve(root, path), "utf8");
+
+describe("live proxy bridge delivery", () => {
+  test("the proxy-served body carries the inline bridge verbatim", () => {
+    const body = composeLiveBridgeJs({
+      token: "tok",
+      editorOrigins: ["http://localhost:1"],
+      annotationCss: ".x{}",
+      bridgeBootstrap: LIVE_BRIDGE_BOOTSTRAP,
+      bridgeScript: BRIDGE_SCRIPT,
+    });
+    expect(body.endsWith(BRIDGE_SCRIPT)).toBe(true);
+    expect(body).toContain(LIVE_BRIDGE_BOOTSTRAP);
+    // The injected tag names the proxy's own route, never a host asset.
+    expect(LIVE_PROXY_BRIDGE_TAG).toBe(`<script src="${LIVE_PROXY_BRIDGE_PATH}"></script>`);
+    expect(LIVE_PROXY_BRIDGE_PATH).toBe("/__plannotator__/bridge.js");
+  });
+
+  test.each([
+    "packages/shared/live-proxy-core.ts",
+    "packages/shared/live-proxy-node.ts",
+    "packages/server/live-proxy.ts",
+    "packages/server/annotate.ts",
+    "apps/hook/server/index.ts",
+    "apps/pi-extension/plannotator-browser.ts",
+    "apps/pi-extension/server/serverAnnotate.ts",
+  ])("%s never references the srcdoc URL seam or the generated asset", (path) => {
+    const source = read(path);
+    expect(source).not.toContain("bridgeScriptUrl");
+    expect(source).not.toContain("bridge-script.asset");
+    expect(source).not.toContain("bridge-script.lite");
+  });
+
+  test("both runtimes still hand the inline string exports to the composer", () => {
+    expect(read("apps/hook/server/index.ts")).toContain("bridgeScript: BRIDGE_SCRIPT,");
+    expect(read("apps/pi-extension/plannotator-browser.ts")).toContain("bridgeScript: bridge.BRIDGE_SCRIPT,");
+    expect(read("packages/shared/live-proxy-core.ts")).toContain("+ sources.bridgeScript");
+  });
+});
diff --git a/tests/entry-assets.test.ts b/tests/entry-assets.test.ts
index b48750d68..1729f78ee 100644
--- a/tests/entry-assets.test.ts
+++ b/tests/entry-assets.test.ts
@@ -144,6 +144,21 @@ describe('review entry assets', () => {
     });
   }
 
+  // The HTML viewer bridge stays INLINE in Plannotator's bundles: the
+  // `bridgeScriptUrl` seam is host-only, so the built HTML must carry the
+  // bridge literal exactly once (the srcdoc injection's string constant),
+  // never zero (a `bridge-script.lite` alias leaking into an app build) and
+  // never twice (a second copy riding in through the generated asset). The
+  // marker is the bridge's test-introspection global, which appears once in
+  // the literal and nowhere else in either app.
+  for (const path of ['apps/hook/dist/index.html', 'apps/review/dist/index.html']) {
+    test.skipIf(!existsSync(resolve(root, path)))(`${path} inlines the HTML viewer bridge exactly once`, () => {
+      const html = readFileSync(resolve(root, path), 'utf8');
+      const literalCount = html.split('__plannotatorBridgeInternals').length - 1;
+      expect({ path, literalCount }).toEqual({ path, literalCount: 1 });
+    });
+  }
+
   test('nothing depends on highlight.js any more', () => {
     for (const manifest of ['packages/ui/package.json', 'packages/review-editor/package.json']) {
       expect(read(manifest)).not.toContain('highlight.js');

From 5737a7afab4db331c581dc83507657c2cb23a279 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:18:53 -0700
Subject: [PATCH 4/7] docs(ui): document the bridge-as-asset seam, host wiring,
 and CSP note

---
 packages/ui/HANDOFF.md | 51 +++++++++++++++++++++++++++++++++++++++++-
 packages/ui/README.md  | 12 ++++++++++
 2 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/packages/ui/HANDOFF.md b/packages/ui/HANDOFF.md
index 56fade0c8..a0aaf2821 100644
--- a/packages/ui/HANDOFF.md
+++ b/packages/ui/HANDOFF.md
@@ -471,12 +471,61 @@ Four modules that used to ride every document read for a host that bundles by ro
 
 3. **Identity: a generator slot, filled eagerly by Plannotator.** `utils/generateIdentity` no longer imports `unique-username-generator`. It holds a synchronous generator slot (`setIdentityGenerator`, `getIdentityGenerator`) with a built-in fallback that produces the same `adjective-noun-tater` shape from a 16 x 16 pool. `utils/identity-tater` registers the full dictionary as a side effect and is what Plannotator's entries import. A host with `identityProvider` never calls the generator and, with the static import gone, no longer ships the word lists; delete any dictionary shim. A host that wants the full dictionary without its own provider imports `@plannotator/ui/utils/identity-tater`, or passes its own `identityGenerator` to `configurePlannotatorUI`. The slot is synchronous on purpose: `configStore` persists the first generated name to the identity cookie during the first render-time settings read, so a name that arrived later would be a visible identity change.
 
-4. **What did not ship (deliberately).** The raw-HTML bridge script as a separately served asset and a lazy table popout are not in this release; both are tracked in the design record for a follow-up.
+4. **What did not ship (deliberately).** A lazy table popout is not in this release; it is tracked in the design record for a follow-up. The raw-HTML bridge script as a separately served asset shipped afterwards, see "HTML viewer bridge as an asset" below.
 
 Pinned by `utils/math.test.ts`, `components/MathBlock.firstPaint.test.tsx`, `utils/generateIdentity.test.ts`, `components/MermaidBlock.test.ts`, and the eager-entry and built-HTML marker guards in `tests/entry-assets.test.ts`.
 
 ---
 
+## HTML viewer bridge as an asset (unreleased)
+
+`HtmlViewer` injects a 185 KB bridge script (`BRIDGE_SCRIPT`, `components/html-viewer/bridge-script.ts`) into every srcdoc document it renders. For a host that bundles by route that literal rode in the viewer chunk and was re-parsed by the browser per document. This release adds an opt-in, `bridgeScriptUrl`, and leaves the default untouched: Plannotator passes nothing, every Plannotator surface (the annotate srcdoc path, the version diff, PR HTML artifacts, linked `.html` docs, the share portal) still inlines the string, the live-app proxy still serves the same inline bridge from its own `/__plannotator__/bridge.js` route, the Pi and OpenCode copies are built from the same code, and the single-file bundles carry the literal exactly once as before (`tests/entry-assets.test.ts` counts it; the A/B of a Plannotator HTML annotate session on a main build against this build found identical DOM, requests and console).
+
+**What the package ships.** `prepack` now also runs `scripts/build-bridge-assets.ts`, which derives two gitignored files beside the source module, both deterministic and both verified against the module's exports by `components/html-viewer/bridgeAsset.test.ts`:
+
+- `components/html-viewer/bridge-script.asset.js`: byte-for-byte `BRIDGE_SCRIPT`, the runnable IIFE. Export subpath `@plannotator/ui/components/html-viewer/bridge-script.asset.js`. The `.asset.js` name is deliberate: a plain `bridge-script.js` next to `bridge-script.ts` would be picked first by Vite's extension probe for the package's own `./bridge-script` imports and break every consumer build.
+- `components/html-viewer/bridge-script.lite.ts`: the same `ANNOTATION_HIGHLIGHT_CSS`, `BRIDGE_PROTOCOL_VERSION` and `LIVE_BRIDGE_BOOTSTRAP` with `BRIDGE_SCRIPT = ""`. Export subpath `@plannotator/ui/components/html-viewer/bridge-script.lite`. An alias target only (below).
+
+The TS module stays the source of truth because the Plannotator CLI and the Pi extension import its string exports under Bun.
+
+**Host wiring (Workspaces).** Serve the asset same-origin as a hashed file through a Vite `?url` import and pass the URL to the viewer:
+
+```ts
+import bridgeScriptUrl from "@plannotator/ui/components/html-viewer/bridge-script.asset.js?url";
+
+<HtmlViewer
+  rawHtml={html}
+  bridgeScriptUrl={bridgeScriptUrl}
+  bridgeReadyTimeoutMs={5000}          // default; the wait for `ready` per document load
+  onBridgeUnavailable={(info) => ...}  // { kind: 'timeout' | 'version-mismatch', url, ... }
+  ...
+/>
+```
+
+With the prop set, `buildSrcdocInjection` emits `<script src="…"></script>` in the exact position the inline `<script>` occupied (there is one injection point, `buildBridgeScriptTag` in `srcdoc.ts`, for both paths), so placement and ordering relative to the page's own scripts are unchanged: parser-blocking in `<head>`, bridge before body on both paths. The srcdoc is rebuilt on `rawHtml`, theme and diff changes and the browser then re-fetches the asset from cache, so serve it with normal immutable-asset cache headers. An empty string counts as absent (inline). The prop is ignored in live (`src`) mode, where the proxy injects the bridge.
+
+**CSP.** Confirmed by grep and pinned by test: the package never writes a CSP `<meta>` into the srcdoc document (the injection is one `<style>` and one `<script>`; an author-written CSP meta is still neutralized as before), and the bridge sets none at runtime. The srcdoc frame is an opaque origin, and a classic `<script src>` executes without CORS; no `crossorigin` attribute is set, so do not expect one. A `Content-Security-Policy` HTTP header on the host page IS inherited by the srcdoc document: a host with its own CSP must allow `script-src` for the origin the asset is served from (same-origin `'self'` in the wiring above). Note the asset form is easier under CSP than the inline form, which would need `'unsafe-inline'` or a nonce.
+
+**Protocol version.** `BRIDGE_PROTOCOL_VERSION` (exported from `components/html-viewer/bridge-script` and re-exported from `components/html-viewer`) is embedded in the bridge text and stamped on its `ready` message as `protocolVersion`. The parent (`checkBridgeProtocolVersion`, `HtmlViewer`'s ready branch) compares it: on the inline path and in live sessions the two sides come from one bundle and always match; on the URL path a cached asset from a previous package version answers with an older stamp, or none, and the viewer logs one console warning naming both versions, shows an error banner over the top of the frame (`[data-bridge-error="version-mismatch"]`, `role="alert"`; the page stays visible) and calls `onBridgeUnavailable`. The ready is still honored (an older bridge answers every message shape it knows), so this is a loud diagnostic, not a refusal. Bump the constant whenever a bridge message shape changes in a way an older bridge or parent would misread; a bump forces a warning against any not-yet-redeployed asset, which is the point.
+
+**Ready timeout.** On the URL path only, `bridgeReadyTimeoutMs` (default 5000) starts on each document load; with no `ready` in time the surface shows `[data-bridge-error="timeout"]` naming the URL and the wait, and `onBridgeUnavailable({ kind: 'timeout', url, timeoutMs })` fires. A late `ready` clears it. The inline path arms no timer and can never show a banner.
+
+**Dropping the literal from the host chunk (optional).** The URL path alone leaves the inline string in the chunk unused, because `srcdoc.ts` imports it statically (the default must stay synchronous). To remove it, alias the package's `./bridge-script` resolution to the generated lite module in your bundler; with Vite:
+
+```ts
+resolve: {
+  alias: [{ find: /\/bridge-script$/, replacement: "/bridge-script.lite" }],
+}
+```
+
+Under that alias an `HtmlViewer` rendered WITHOUT `bridgeScriptUrl` throws at render (`buildBridgeScriptTag` refuses to emit an empty inline script), so the misconfiguration cannot ship as a silently dead surface. Measured on the proof harness: the viewer chunk shrinks by the size of the literal (see the PR's REPORT.md).
+
+**Live app annotation is unaffected.** `packages/shared/live-proxy-bridge-inline.test.ts` pins at source level that both proxy transports and both runtimes' composers still ship the inline bridge from the proxy route and never reference `bridgeScriptUrl` or the generated files.
+
+Pinned by `components/html-viewer/bridgeAsset.test.ts` (generator bytes, manifest wiring, the single injection point, no CSP meta, the real bridge's stamped ready), `components/html-viewer/HtmlViewer.bridgeAsset.test.tsx` (URL srcdoc, stale-asset warning and banner, timeout and late ready, inline path unchanged), `packages/shared/live-proxy-bridge-inline.test.ts` and the bridge marker count in `tests/entry-assets.test.ts`.
+
+---
+
 ## Frozen markdown diff (0.28.0)
 
 One additive component for the Workspaces versions/approvals surface: `components/MarkdownDiff`, a theme-bridging shim over `@plannotator/markdown-editor@0.4.0`'s `MarkdownDiff` — a **frozen two-revision markdown comparison**. The newer revision renders as the real document (uncollapsed, full length); deletions are projected struck-through at their original positions; changed spans get character/word emphasis; a toolbar shows the change count with prev/next navigation; a clickable, keyboard-accessible overview rail and a changed-line gutter complete the review chrome. Every 0.27.0 surface is unchanged.
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 6d8f4f768..a3b9958ae 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -112,6 +112,18 @@ Everything a host needs around `HtmlViewer` to match Plannotator's HTML annotati
 
 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 (parser-blocking in `<head>`, before the page's own scripts), 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 an error banner in the surface (`onBridgeUnavailable` fires too); no `ready` within `bridgeReadyTimeoutMs` (default 5000) shows a timeout banner. 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. 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.

From e84fa14d8925bf88ded89a6866059642ffb88e8a Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:31:59 -0700
Subject: [PATCH 5/7] fix(ui): resolve bridgeScriptUrl against the parent
 document, arm the ready timer once, make the mismatch banner dismissible

The srcdoc injection lands at the end of the page's <head>, after any <base
href> the page declares, so a relative bridge URL written into the srcdoc
would resolve against an attacker-chosen base and load an attacker-served
bridge, defeating the version check. HtmlViewer now resolves the URL against
its own document.baseURI (resolveBridgeScriptUrl) before it is written;
pinned with a <base href> document on both the pure and the DOM suite.

The ready timer is armed once per document load and reads the timeout
through a ref, so a host changing bridgeReadyTimeoutMs after a successful
ready can no longer re-arm a timer nothing clears. The version-mismatch
banner gains a Dismiss button (the older bridge keeps working); the timeout
banner stays, since that surface is dead. Prop docs now say the tag lands at
the end of <head>, before the body.
---
 .../HtmlViewer.bridgeAsset.test.tsx           | 104 +++++++++++++++---
 .../ui/components/html-viewer/HtmlViewer.tsx  |  60 ++++++++--
 .../html-viewer/bridgeAsset.test.ts           |  26 ++++-
 packages/ui/components/html-viewer/srcdoc.ts  |  30 ++++-
 4 files changed, 187 insertions(+), 33 deletions(-)

diff --git a/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx b/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx
index fca950c8e..e960a1b67 100644
--- a/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx
+++ b/packages/ui/components/html-viewer/HtmlViewer.bridgeAsset.test.tsx
@@ -35,11 +35,16 @@ afterEach(async () => {
 
 const ASSET_URL = 'https://host.example/assets/bridge-script.deadbeef.js';
 
-async function mount(props: {
+type MountProps = {
   bridgeScriptUrl?: string;
   bridgeReadyTimeoutMs?: number;
   onBridgeUnavailable?: (info: BridgeUnavailableInfo) => void;
-}) {
+  rawHtml?: string;
+};
+
+const DEFAULT_HTML = "<html><head><title>t</title></head><body><p>Target</p></body></html>";
+
+async function mount(props: MountProps) {
   if (!htmlViewerModule) throw new Error('DOM test environment is not registered');
   const HtmlViewer = htmlViewerModule.HtmlViewer;
   // happy-dom parses the srcdoc and, with script file loading disabled,
@@ -51,20 +56,26 @@ async function mount(props: {
   document.body.appendChild(host);
   const root = createRoot(host);
   mountedRoots.push(root);
-  await act(async () => {
-    root.render(
-      <HtmlViewer
-        rawHtml="<html><head><title>t</title></head><body><p>Target</p></body></html>"
-        annotations={[]}
-        onAddAnnotation={() => {}}
-        onSelectAnnotation={() => {}}
-        selectedAnnotationId={null}
-        mode="selection"
-        inputMethod="pinpoint"
-        {...props}
-      />,
-    );
-  });
+  const render = async (next: MountProps) => {
+    await act(async () => {
+      root.render(
+        <HtmlViewer
+          rawHtml={next.rawHtml ?? DEFAULT_HTML}
+          annotations={[]}
+          onAddAnnotation={() => {}}
+          onSelectAnnotation={() => {}}
+          selectedAnnotationId={null}
+          mode="selection"
+          inputMethod="pinpoint"
+          bridgeScriptUrl={next.bridgeScriptUrl}
+          bridgeReadyTimeoutMs={next.bridgeReadyTimeoutMs}
+          onBridgeUnavailable={next.onBridgeUnavailable}
+        />,
+      );
+    });
+  };
+  await render(props);
+  const rerender = (patch: Partial<MountProps>) => render({ ...props, ...patch });
   const iframe = host.querySelector<HTMLIFrameElement>('iframe');
   if (!iframe?.contentWindow) throw new Error('HTML iframe missing');
   const postedToIframe: Array<Record<string, unknown>> = [];
@@ -80,7 +91,7 @@ async function mount(props: {
     });
   };
   const banner = () => host.querySelector<HTMLElement>('[data-bridge-error]');
-  return { host, iframe, postReady, postedToIframe, banner };
+  return { host, iframe, postReady, postedToIframe, banner, rerender };
 }
 
 function captureWarnings(): string[] {
@@ -103,6 +114,30 @@ describe.if(hasDom)('HtmlViewer bridgeScriptUrl', () => {
     expect(iframe.getAttribute('sandbox')).toBe('allow-scripts');
   });
 
+  test("a relative URL is resolved against the PARENT document, so a page's own <base href> cannot redirect it", async () => {
+    // happy-dom's document lives at about:blank; give the PARENT a real base
+    // the way a host page has one, and remove it afterwards.
+    const parentBase = document.createElement('base');
+    parentBase.setAttribute('href', 'http://host.test:4000/workspace/');
+    document.head.appendChild(parentBase);
+    try {
+      expect(document.baseURI).toBe('http://host.test:4000/workspace/');
+      const { iframe } = await mount({
+        bridgeScriptUrl: '/assets/bridge-script.deadbeef.js',
+        rawHtml: '<html><head><base href="https://attacker.example/"><title>t</title></head><body><p>x</p></body></html>',
+      });
+      const srcdoc = iframe.getAttribute('srcdoc') ?? '';
+      expect(srcdoc).toContain('<script src="http://host.test:4000/assets/bridge-script.deadbeef.js"></script>');
+      // The page's base tag still precedes the injected tag (end of <head>),
+      // which is exactly why the src must already be absolute.
+      expect(srcdoc.indexOf('<base href')).toBeLessThan(srcdoc.indexOf('<script src='));
+      expect(srcdoc).not.toContain('src="/assets/');
+      expect(srcdoc).not.toContain('attacker.example/assets');
+    } finally {
+      parentBase.remove();
+    }
+  });
+
   test('without the prop the srcdoc inlines the bridge, as before', async () => {
     const { iframe, banner } = await mount({});
     const srcdoc = iframe.getAttribute('srcdoc') ?? '';
@@ -170,6 +205,41 @@ describe.if(hasDom)('HtmlViewer bridgeScriptUrl', () => {
     expect(banner()).toBeNull();
   });
 
+  test('changing bridgeReadyTimeoutMs after a successful ready never re-arms the timer', async () => {
+    const unavailable: BridgeUnavailableInfo[] = [];
+    const { postReady, banner, rerender } = await mount({
+      bridgeScriptUrl: ASSET_URL,
+      bridgeReadyTimeoutMs: 5000,
+      onBridgeUnavailable: (info) => unavailable.push(info),
+    });
+    await postReady({ type: 'plannotator-bridge-ready', protocolVersion: BRIDGE_PROTOCOL_VERSION });
+    await rerender({ bridgeReadyTimeoutMs: 20 });
+    await act(async () => { await wait(80); });
+    expect(banner()).toBeNull();
+    expect(unavailable).toEqual([]);
+  });
+
+  test('the version-mismatch banner is dismissible; the timeout banner is not', async () => {
+    captureWarnings();
+    const unavailable: BridgeUnavailableInfo[] = [];
+    const { postReady, banner, host } = await mount({
+      bridgeScriptUrl: ASSET_URL,
+      onBridgeUnavailable: (info) => unavailable.push(info),
+    });
+    await postReady({ type: 'plannotator-bridge-ready' });
+    const dismiss = host.querySelector<HTMLButtonElement>('[data-bridge-error-dismiss]');
+    expect(dismiss).not.toBeNull();
+    await act(async () => { dismiss!.click(); });
+    expect(banner()).toBeNull();
+    // Dismissing hides the strip only: the host was told exactly once.
+    expect(unavailable.length).toBe(1);
+
+    const timedOut = await mount({ bridgeScriptUrl: ASSET_URL, bridgeReadyTimeoutMs: 20 });
+    await act(async () => { await wait(70); });
+    expect(timedOut.banner()?.getAttribute('data-bridge-error')).toBe('timeout');
+    expect(timedOut.host.querySelector('[data-bridge-error-dismiss]')).toBeNull();
+  });
+
   test('inline path: no timer, no banner, no callback; a stamp-less ready only warns', async () => {
     const warnings = captureWarnings();
     const unavailable: BridgeUnavailableInfo[] = [];
diff --git a/packages/ui/components/html-viewer/HtmlViewer.tsx b/packages/ui/components/html-viewer/HtmlViewer.tsx
index 92fcb2736..57bf87dc6 100644
--- a/packages/ui/components/html-viewer/HtmlViewer.tsx
+++ b/packages/ui/components/html-viewer/HtmlViewer.tsx
@@ -53,6 +53,7 @@ import {
   buildThemeTokenPayload,
   hasHostThemeOptIn,
   injectIntoHead,
+  resolveBridgeScriptUrl,
 } from "./srcdoc";
 
 const PREFIX = "plannotator-bridge-";
@@ -260,11 +261,16 @@ export interface HtmlViewerProps {
    * 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 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.
-   * Ignored in live (`src`) mode, where the proxy injects the bridge.
+   * 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;
   /**
@@ -381,7 +387,14 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     const hostTheme = useMemo(() => !liveMode && hasHostThemeOptIn(rawHtml), [liveMode, rawHtml]);
 
     // The URL path is srcdoc-only: live mode has the proxy inject the bridge.
-    const bridgeUrl = !liveMode && bridgeScriptUrl ? bridgeScriptUrl : undefined;
+    // 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;
 
@@ -401,14 +414,24 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     // 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 = bridgeReadyTimeoutMs;
+      const timeoutMs = bridgeReadyTimeoutMsRef.current;
       readyTimerRef.current = setTimeout(() => {
         readyTimerRef.current = null;
         setBridgeError({ kind: "timeout", url, timeoutMs });
@@ -417,8 +440,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         if (readyTimerRef.current !== null) clearTimeout(readyTimerRef.current);
         readyTimerRef.current = null;
       };
-    }, [bridgeUrl, srcdoc, bridgeReadyTimeoutMs]);
+    }, [bridgeUrl, srcdoc]);
     useEffect(() => {
+      setBridgeErrorDismissed(false);
       if (bridgeError) onBridgeUnavailableRef.current?.(bridgeError);
     }, [bridgeError]);
 
@@ -1038,14 +1062,28 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 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 && (
+            {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"
+                className="absolute inset-x-0 top-0 z-20 flex items-start gap-2 border-b border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive backdrop-blur-sm"
               >
-                {formatBridgeUnavailableMessage(bridgeError)}
+                <span className="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. */}
+                {bridgeError.kind === "version-mismatch" && (
+                  <button
+                    type="button"
+                    data-bridge-error-dismiss
+                    aria-label="Dismiss"
+                    className="shrink-0 rounded px-1.5 py-0.5 font-medium hover:bg-destructive/15 cursor-pointer"
+                    onClick={() => setBridgeErrorDismissed(true)}
+                  >
+                    Dismiss
+                  </button>
+                )}
               </div>
             )}
             {/* Live proxied-app mode navigates a real loopback origin: no
diff --git a/packages/ui/components/html-viewer/bridgeAsset.test.ts b/packages/ui/components/html-viewer/bridgeAsset.test.ts
index e990b62fa..56a01d72c 100644
--- a/packages/ui/components/html-viewer/bridgeAsset.test.ts
+++ b/packages/ui/components/html-viewer/bridgeAsset.test.ts
@@ -29,7 +29,12 @@ import {
   BRIDGE_LITE_FILENAME,
   writeBridgeAssets,
 } from "../../scripts/build-bridge-assets";
-import { buildBridgeScriptTag, buildSrcdocInjection, injectIntoHead } from "./srcdoc";
+import {
+  buildBridgeScriptTag,
+  buildSrcdocInjection,
+  injectIntoHead,
+  resolveBridgeScriptUrl,
+} from "./srcdoc";
 import { checkBridgeProtocolVersion, formatBridgeProtocolWarning } from "./useHtmlAnnotation";
 
 const uiRoot = resolve(import.meta.dir, "../..");
@@ -122,6 +127,25 @@ describe("srcdoc bridge script tag", () => {
     expect(tag).toBe('<script src="/b.js&quot; onerror=&quot;alert(1)"></script>');
   });
 
+  test("the URL resolves against the parent base, never the framed page's <base href>", () => {
+    const parent = "https://host.example/workspace/doc/42";
+    expect(resolveBridgeScriptUrl("/assets/bridge.abc.js", parent)).toBe("https://host.example/assets/bridge.abc.js");
+    expect(resolveBridgeScriptUrl("./bridge.js", parent)).toBe("https://host.example/workspace/doc/bridge.js");
+    expect(resolveBridgeScriptUrl("https://cdn.example/b.js", parent)).toBe("https://cdn.example/b.js");
+    // Unparsable input is passed through rather than thrown at render.
+    expect(resolveBridgeScriptUrl("http://[bad", "not a url")).toBe("http://[bad");
+
+    // A page carrying its own <base href> still precedes the injected tag
+    // (end of <head>); the resolved src is absolute and unaffected by it.
+    const page = '<html><head><base href="https://attacker.example/"><title>t</title></head><body></body></html>';
+    const doc = injectIntoHead(page, buildSrcdocInjection({
+      ...base,
+      bridgeScriptUrl: resolveBridgeScriptUrl("/assets/bridge.abc.js", parent),
+    }));
+    expect(doc).toContain('<script src="https://host.example/assets/bridge.abc.js"></script>');
+    expect(doc.indexOf("<base href")).toBeLessThan(doc.indexOf("<script src="));
+  });
+
   test("the package adds no CSP meta to the srcdoc document on either path", () => {
     const page = "<html><head><title>t</title></head><body><p>x</p></body></html>";
     for (const bridgeScriptUrl of [undefined, "/assets/bridge.js"]) {
diff --git a/packages/ui/components/html-viewer/srcdoc.ts b/packages/ui/components/html-viewer/srcdoc.ts
index f02e1d429..5333c605d 100644
--- a/packages/ui/components/html-viewer/srcdoc.ts
+++ b/packages/ui/components/html-viewer/srcdoc.ts
@@ -99,14 +99,36 @@ export interface SrcdocInjectionOptions {
   /**
    * 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 and ordering relative
-   * to the page's own scripts are identical on both paths (parser-blocking in
-   * `<head>`, before the body). No `crossorigin` attribute is set: the srcdoc
-   * frame is an opaque origin, and a classic script needs no CORS to execute.
+   * 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

From 6f1f363aae031b22d8720810002cad0c5d3476ab Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:31:59 -0700
Subject: [PATCH 6/7] docs(ui): label the bridge asset seam 0.33.0, fix
 placement wording, add CORP and base-href notes

Release label matches the neighbouring 0.32.0 headings after the version
bump; the tag is injected at the end of <head>, before the body, not before
the page's own scripts; hosts serving the asset with a same-origin CORP
(common with COEP) must relax it for the opaque-origin frame; the URL is
resolved against the parent document, never the framed page; the HANDOFF
notes BRIDGE_SCRIPT's first interpolation for the design record and points
at the PR description instead of a REPORT.md that does not ship.
---
 packages/ui/HANDOFF.md | 12 ++++++------
 packages/ui/README.md  |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/ui/HANDOFF.md b/packages/ui/HANDOFF.md
index a0aaf2821..a52a7c532 100644
--- a/packages/ui/HANDOFF.md
+++ b/packages/ui/HANDOFF.md
@@ -477,7 +477,7 @@ Pinned by `utils/math.test.ts`, `components/MathBlock.firstPaint.test.tsx`, `uti
 
 ---
 
-## HTML viewer bridge as an asset (unreleased)
+## HTML viewer bridge as an asset (0.33.0)
 
 `HtmlViewer` injects a 185 KB bridge script (`BRIDGE_SCRIPT`, `components/html-viewer/bridge-script.ts`) into every srcdoc document it renders. For a host that bundles by route that literal rode in the viewer chunk and was re-parsed by the browser per document. This release adds an opt-in, `bridgeScriptUrl`, and leaves the default untouched: Plannotator passes nothing, every Plannotator surface (the annotate srcdoc path, the version diff, PR HTML artifacts, linked `.html` docs, the share portal) still inlines the string, the live-app proxy still serves the same inline bridge from its own `/__plannotator__/bridge.js` route, the Pi and OpenCode copies are built from the same code, and the single-file bundles carry the literal exactly once as before (`tests/entry-assets.test.ts` counts it; the A/B of a Plannotator HTML annotate session on a main build against this build found identical DOM, requests and console).
 
@@ -502,13 +502,13 @@ import bridgeScriptUrl from "@plannotator/ui/components/html-viewer/bridge-scrip
 />
 ```
 
-With the prop set, `buildSrcdocInjection` emits `<script src="…"></script>` in the exact position the inline `<script>` occupied (there is one injection point, `buildBridgeScriptTag` in `srcdoc.ts`, for both paths), so placement and ordering relative to the page's own scripts are unchanged: parser-blocking in `<head>`, bridge before body on both paths. The srcdoc is rebuilt on `rawHtml`, theme and diff changes and the browser then re-fetches the asset from cache, so serve it with normal immutable-asset cache headers. An empty string counts as absent (inline). The prop is ignored in live (`src`) mode, where the proxy injects the bridge.
+With the prop set, `buildSrcdocInjection` emits `<script src="…"></script>` in the exact position the inline `<script>` occupied (there is one injection point, `buildBridgeScriptTag` in `srcdoc.ts`, for both paths), so placement is unchanged: at the end of `<head>`, before the body, on both paths (the page's head scripts run before the bridge, its body scripts after). The URL is resolved against the PARENT document (`resolveBridgeScriptUrl(url, document.baseURI)`) before it is written into the srcdoc, never against the framed page: the injection follows any `<base href>` the page declares, so a relative URL left unresolved would let a hostile document point the viewer at an attacker-served bridge and defeat the version check. The srcdoc is rebuilt on `rawHtml`, theme and diff changes and the browser then re-fetches the asset from cache, so serve it with normal immutable-asset cache headers. An empty string counts as absent (inline). The prop is ignored in live (`src`) mode, where the proxy injects the bridge.
 
-**CSP.** Confirmed by grep and pinned by test: the package never writes a CSP `<meta>` into the srcdoc document (the injection is one `<style>` and one `<script>`; an author-written CSP meta is still neutralized as before), and the bridge sets none at runtime. The srcdoc frame is an opaque origin, and a classic `<script src>` executes without CORS; no `crossorigin` attribute is set, so do not expect one. A `Content-Security-Policy` HTTP header on the host page IS inherited by the srcdoc document: a host with its own CSP must allow `script-src` for the origin the asset is served from (same-origin `'self'` in the wiring above). Note the asset form is easier under CSP than the inline form, which would need `'unsafe-inline'` or a nonce.
+**CSP.** Confirmed by grep and pinned by test: the package never writes a CSP `<meta>` into the srcdoc document (the injection is one `<style>` and one `<script>`; an author-written CSP meta is still neutralized as before), and the bridge sets none at runtime. The srcdoc frame is an opaque origin, and a classic `<script src>` executes without CORS; no `crossorigin` attribute is set, so do not expect one. A `Content-Security-Policy` HTTP header on the host page IS inherited by the srcdoc document: a host with its own CSP must allow `script-src` for the origin the asset is served from (same-origin `'self'` in the wiring above). Note the asset form is easier under CSP than the inline form, which would need `'unsafe-inline'` or a nonce. One more header to check: an asset served with `Cross-Origin-Resource-Policy: same-origin` (common with COEP) is blocked for the opaque-origin frame; serve the bridge asset with a CORP that admits cross-origin loads (`cross-origin`) or without CORP.
 
-**Protocol version.** `BRIDGE_PROTOCOL_VERSION` (exported from `components/html-viewer/bridge-script` and re-exported from `components/html-viewer`) is embedded in the bridge text and stamped on its `ready` message as `protocolVersion`. The parent (`checkBridgeProtocolVersion`, `HtmlViewer`'s ready branch) compares it: on the inline path and in live sessions the two sides come from one bundle and always match; on the URL path a cached asset from a previous package version answers with an older stamp, or none, and the viewer logs one console warning naming both versions, shows an error banner over the top of the frame (`[data-bridge-error="version-mismatch"]`, `role="alert"`; the page stays visible) and calls `onBridgeUnavailable`. The ready is still honored (an older bridge answers every message shape it knows), so this is a loud diagnostic, not a refusal. Bump the constant whenever a bridge message shape changes in a way an older bridge or parent would misread; a bump forces a warning against any not-yet-redeployed asset, which is the point.
+**Protocol version.** `BRIDGE_PROTOCOL_VERSION` (exported from `components/html-viewer/bridge-script` and re-exported from `components/html-viewer`) is embedded in the bridge text and stamped on its `ready` message as `protocolVersion`. Note for the design record's "current state": `BRIDGE_SCRIPT` now carries its first `${}` interpolation (that constant, evaluated at module load); it remains a plain string export with no per-session values, so the CLI, Pi and the live proxy consume it exactly as before. The parent (`checkBridgeProtocolVersion`, `HtmlViewer`'s ready branch) compares it: on the inline path and in live sessions the two sides come from one bundle and always match; on the URL path a cached asset from a previous package version answers with an older stamp, or none, and the viewer logs one console warning naming both versions, shows a dismissible error banner over the top of the frame (`[data-bridge-error="version-mismatch"]`, `role="alert"`, a `[data-bridge-error-dismiss]` button; the page stays visible) and calls `onBridgeUnavailable` once. The ready is still honored (an older bridge answers every message shape it knows), so this is a loud diagnostic, not a refusal. Bump the constant whenever a bridge message shape changes in a way an older bridge or parent would misread; a bump forces a warning against any not-yet-redeployed asset, which is the point.
 
-**Ready timeout.** On the URL path only, `bridgeReadyTimeoutMs` (default 5000) starts on each document load; with no `ready` in time the surface shows `[data-bridge-error="timeout"]` naming the URL and the wait, and `onBridgeUnavailable({ kind: 'timeout', url, timeoutMs })` fires. A late `ready` clears it. The inline path arms no timer and can never show a banner.
+**Ready timeout.** On the URL path only, `bridgeReadyTimeoutMs` (default 5000) is armed once per document load (URL or srcdoc change), read through a ref, so changing the prop after the bridge is ready never re-arms it; with no `ready` in time the surface shows `[data-bridge-error="timeout"]` naming the URL and the wait (not dismissible: the surface is dead), and `onBridgeUnavailable({ kind: 'timeout', url, timeoutMs })` fires. A late `ready` clears it. The inline path arms no timer and can never show a banner.
 
 **Dropping the literal from the host chunk (optional).** The URL path alone leaves the inline string in the chunk unused, because `srcdoc.ts` imports it statically (the default must stay synchronous). To remove it, alias the package's `./bridge-script` resolution to the generated lite module in your bundler; with Vite:
 
@@ -518,7 +518,7 @@ resolve: {
 }
 ```
 
-Under that alias an `HtmlViewer` rendered WITHOUT `bridgeScriptUrl` throws at render (`buildBridgeScriptTag` refuses to emit an empty inline script), so the misconfiguration cannot ship as a silently dead surface. Measured on the proof harness: the viewer chunk shrinks by the size of the literal (see the PR's REPORT.md).
+Under that alias an `HtmlViewer` rendered WITHOUT `bridgeScriptUrl` throws at render (`buildBridgeScriptTag` refuses to emit an empty inline script), so the misconfiguration cannot ship as a silently dead surface. Measured on the proof harness (PR #1398's description): the viewer chunk shrinks by the size of the literal, 557 kB to 371 kB (168 kB to 118 kB gzip).
 
 **Live app annotation is unaffected.** `packages/shared/live-proxy-bridge-inline.test.ts` pins at source level that both proxy transports and both runtimes' composers still ship the inline bridge from the proxy route and never reference `bridgeScriptUrl` or the generated files.
 
diff --git a/packages/ui/README.md b/packages/ui/README.md
index a3b9958ae..e022adb9a 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -122,7 +122,7 @@ import bridgeScriptUrl from "@plannotator/ui/components/html-viewer/bridge-scrip
 <HtmlViewer rawHtml={html} bridgeScriptUrl={bridgeScriptUrl} … />
 ```
 
-The srcdoc then carries one classic `<script src>` in the exact place the inline script sat (parser-blocking in `<head>`, before the page's own scripts), 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 an error banner in the surface (`onBridgeUnavailable` fires too); no `ready` within `bridgeReadyTimeoutMs` (default 5000) shows a timeout banner. 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. 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").
+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`
 

From c6d2e25d969c8ce66ea161d42893f03b0949c52a Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 27 Aug 2026 08:34:11 -0700
Subject: [PATCH 7/7] fix(ui): style the mismatch banner's dismiss control
 inline so the guides.show viewer stylesheet stays unchanged

The viewer build scans this file for utility classes; the button's new
classes changed the viewer CSS hash pinned in guide-viewer-manifest.ts.
Inline styles keep the stylesheet, and the manifest, as on main.
---
 packages/ui/components/html-viewer/HtmlViewer.tsx | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/ui/components/html-viewer/HtmlViewer.tsx b/packages/ui/components/html-viewer/HtmlViewer.tsx
index 57bf87dc6..59f8a9a3c 100644
--- a/packages/ui/components/html-viewer/HtmlViewer.tsx
+++ b/packages/ui/components/html-viewer/HtmlViewer.tsx
@@ -1067,18 +1067,21 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 role="alert"
                 data-print-hide
                 data-bridge-error={bridgeError.kind}
-                className="absolute inset-x-0 top-0 z-20 flex items-start gap-2 border-b border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive backdrop-blur-sm"
+                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 className="flex-1">{formatBridgeUnavailableMessage(bridgeError)}</span>
+                <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. */}
+                    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"
-                    className="shrink-0 rounded px-1.5 py-0.5 font-medium hover:bg-destructive/15 cursor-pointer"
+                    style={{ flexShrink: 0, borderRadius: 4, padding: "2px 6px", fontWeight: 500, cursor: "pointer", background: "transparent", border: "1px solid currentColor", color: "inherit" }}
                     onClick={() => setBridgeErrorDismissed(true)}
                   >
                     Dismiss