From 76356ed975567a323439cfbf3d2bd2103a29b4e9 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Tue, 16 Jun 2026 20:12:22 +0000
Subject: [PATCH 1/5] feat: proxy-bridge directive + touch drag recovery for
 prereview --external

- lvt-fx:proxy-bridge: relays the proxied page's nav (-> setProxyURL) and
  scroll (-> pin-layer transform) from the injected beacon; locates a region by
  posting a focus message into the iframe (navigate + scroll). Re-applies the
  pin-layer transform on every render (morphdom-wipe recovery).
- region-select gains a data-surface="page" branch (regionRectFromBox):
  converts a drawn box to document fractions via beacon scroll/doc metrics.
- attachBoxDragSelect: on touch pointers, finalize the region on
  pointercancel / lostpointercapture instead of discarding (iOS long-drag
  recovery); mouse/pen unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dom/directives.ts        | 252 ++++++++++++++++++++++++++++++++-
 livetemplate-client.ts   |   8 ++
 tests/directives.test.ts | 298 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 554 insertions(+), 4 deletions(-)

diff --git a/dom/directives.ts b/dom/directives.ts
index f803cb2..8c37cda 100644
--- a/dom/directives.ts
+++ b/dom/directives.ts
@@ -1660,6 +1660,15 @@ function attachBoxDragSelect(
   let startClientX = 0;
   let startClientY = 0;
   let pointerId = -1;
+  // pointerType + lastMove let us recover a TOUCH drag that iOS Safari
+  // cancels mid-gesture. iOS fires pointercancel / yanks pointer capture on
+  // long, fast touch-drags (it re-interprets them as a scroll/swipe), which
+  // would otherwise discard a large region the user deliberately drew. For
+  // touch we finalize WITH the last-known position instead of dropping it;
+  // mouse/pen keep the strict discard. (The area threshold in finalize still
+  // rejects an accidental tiny box, so a stray cancel can't create a region.)
+  let pointerType = "";
+  let lastMove: PointerEvent | null = null;
   // Capture the parent at pointerdown time so a server diff that moves
   // the host to a NEW parent mid-drag doesn't split the drag across
   // two positioning contexts. updateOverlay positions against this
@@ -1703,6 +1712,7 @@ function attachBoxDragSelect(
     pointerId = -1;
     dragParent = null;
     startRect = null;
+    lastMove = null;
     try {
       el.releasePointerCapture(capturedPointerId);
     } catch {
@@ -1820,6 +1830,8 @@ function attachBoxDragSelect(
     startClientX = e.clientX;
     startClientY = e.clientY;
     pointerId = e.pointerId;
+    pointerType = e.pointerType;
+    lastMove = e;
     dragParent = parent;
     startRect = el.getBoundingClientRect();
     let captureOk = false;
@@ -1915,6 +1927,7 @@ function attachBoxDragSelect(
       finalize(null, false);
       return;
     }
+    lastMove = e;
     updateOverlay(e);
   };
 
@@ -1929,7 +1942,9 @@ function attachBoxDragSelect(
 
   const onPointerCancel = (e: PointerEvent) => {
     if (e.pointerId !== pointerId) return;
-    finalize(e, false);
+    // iOS cancels long touch-drags it re-reads as a swipe; keep the region
+    // the user drew rather than dropping it (mouse/pen still discard).
+    finalize(e, pointerType === "touch");
   };
   // lostpointercapture handles the rare case where the platform yanks
   // capture (OS gesture, another setPointerCapture call). Guard on
@@ -1937,7 +1952,11 @@ function attachBoxDragSelect(
   // DIFFERENT pointer on the same element, and we mustn't cancel
   // our in-progress drag because of an unrelated release.
   const onLostCapture = (e: PointerEvent) => {
-    if (e.pointerId === pointerId) finalize(null, false);
+    if (e.pointerId !== pointerId) return;
+    // Same touch-recovery as pointercancel: finalize from the last move so a
+    // capture yank mid-touch-drag keeps the region instead of dropping it.
+    const m = lastMove;
+    finalize(pointerType === "touch" ? m : null, pointerType === "touch" && m !== null);
   };
 
   el.addEventListener("pointerdown", onPointerDown);
@@ -2068,6 +2087,178 @@ export function teardownRegionSelectForRoot(rootElement: Element): void {
   }
 }
 
+// proxyBridgeArmed mirrors the area/region-select singletons: one entry per
+// armed `lvt-fx:proxy-bridge` element, swept on disconnect. sync runs on every
+// render to re-apply the pin-layer transform morphdom wipes + relay a "locate
+// this annotation" request to the iframe.
+type ProxyBridgeEntry = BoxDragEntry & { sync: () => void };
+const proxyBridgeArmed = new Map<Element, ProxyBridgeEntry>();
+
+/**
+ * Apply proxy-bridge directives — the `--external` live-site bridge.
+ * `lvt-fx:proxy-bridge="<actionName>"` on the preview stage (the element
+ * wrapping the proxied `<iframe>` + the `[data-pin-layer]` overlay) listens
+ * for the beacon the proxy injects into the cross-origin page (see
+ * proxy.go). Each beacon message carries the page's scroll + document size:
+ *
+ *   - ANY message updates the shared PageMetrics (so the "page" region
+ *     resolver can convert a drawn box to document fractions) and re-pins the
+ *     saved annotations by sizing the pin layer to the document and
+ *     translating it by -scroll — a pure CSS transform, no server round-trip.
+ *   - a `nav` message additionally dispatches `<actionName>` with `{url}` so
+ *     the server swaps the visible annotation set for the new page.
+ *
+ * This is the only thing that reaches across the cross-origin boundary, and
+ * it's read-only (postMessage in, transform out) — we never touch the
+ * proxied page's DOM. Messages from any origin other than the iframe's are
+ * ignored.
+ *
+ * Idempotent + swept exactly like area/region-select.
+ */
+export function handleProxyBridgeDirectives(
+  rootElement: Element,
+  send: AreaSelectSendFn
+): void {
+  for (const [element, entry] of Array.from(proxyBridgeArmed)) {
+    if (!element.isConnected || !element.hasAttribute("lvt-fx:proxy-bridge")) {
+      entry.cleanup();
+    }
+  }
+  const matches = rootElement.querySelectorAll<HTMLElement>(
+    "[lvt-fx\\:proxy-bridge]"
+  );
+  if (matches.length === 0) return;
+  for (const el of matches) {
+    const action = el.getAttribute("lvt-fx:proxy-bridge");
+    if (!action) {
+      console.warn(
+        `lvt-fx:proxy-bridge requires an action name, got: ${JSON.stringify(action)}`
+      );
+      continue;
+    }
+    const existing = proxyBridgeArmed.get(el);
+    if (existing && existing.action === action) {
+      existing.updateSend(send);
+      existing.sync();
+      continue;
+    }
+    if (existing) existing.cleanup();
+    const entry = attachProxyBridge(el, action, send);
+    proxyBridgeArmed.set(el, entry);
+    entry.sync();
+  }
+}
+
+/**
+ * Cancel proxy-bridge listeners for every armed element under root.
+ * Mirror of teardownRegionSelectForRoot for the client disconnect lifecycle.
+ */
+export function teardownProxyBridgeForRoot(rootElement: Element): void {
+  for (const [element, entry] of Array.from(proxyBridgeArmed)) {
+    if (rootElement.contains(element)) {
+      entry.cleanup();
+    }
+  }
+}
+
+function attachProxyBridge(
+  el: HTMLElement,
+  action: string,
+  initialSend: AreaSelectSendFn
+): ProxyBridgeEntry {
+  let send = initialSend;
+  let lastURL: string | null = null;
+  let lastFocusToken: string | null = null;
+  const iframe = el.querySelector<HTMLIFrameElement>("iframe");
+  const pinLayer = el.querySelector<HTMLElement>("[data-pin-layer]");
+
+  // Only trust messages from the proxied iframe's own origin.
+  let expectedOrigin = "";
+  try {
+    if (iframe && iframe.src) expectedOrigin = new URL(iframe.src).origin;
+  } catch {
+    expectedOrigin = "";
+  }
+
+  // applyPinLayer sizes the pin layer to the document and slides it by -scroll
+  // so each marker (percentage-positioned by the server within this layer)
+  // tracks its spot on the page. These are INLINE styles set imperatively, so
+  // they must be re-applied after every server render too — morphdom diffs the
+  // pin-layer against the template (which has no inline style) and would
+  // otherwise wipe them, collapsing the layer until the next scroll. See sync().
+  const applyPinLayer = () => {
+    const m = pageBridgeMetrics;
+    if (pinLayer && m && m.docW > 0 && m.docH > 0) {
+      pinLayer.style.width = m.docW + "px";
+      pinLayer.style.height = m.docH + "px";
+      pinLayer.style.transform = `translate(${-m.scrollX}px, ${-m.scrollY}px)`;
+    }
+  };
+
+  const onMessage = (e: MessageEvent) => {
+    if (expectedOrigin && e.origin !== expectedOrigin) return;
+    const d = e.data;
+    if (!d || d.__prereview !== true) return;
+
+    pageBridgeMetrics = {
+      scrollX: Number(d.scrollX) || 0,
+      scrollY: Number(d.scrollY) || 0,
+      docW: Number(d.docW) || 0,
+      docH: Number(d.docH) || 0,
+    };
+    applyPinLayer();
+
+    if (d.type === "nav") {
+      const url = typeof d.url === "string" ? d.url : "";
+      if (url !== lastURL) {
+        lastURL = url;
+        send({ action, data: { url } });
+      }
+    }
+  };
+  window.addEventListener("message", onMessage);
+
+  // sync runs on EVERY server render (after morphdom). It (1) re-applies the
+  // pin-layer size/transform that morphdom just wiped, so a saved pin doesn't
+  // vanish until the next scroll, and (2) relays a "locate this annotation"
+  // request to the iframe: the server stamps el with data-focus-token (bumps
+  // each tap), data-focus-url (the annotation's page) and data-focus-y (0..1
+  // document fraction); on a changed token we postMessage the iframe, whose
+  // beacon navigates there if needed and scrolls the region into view. Posting
+  // INTO the iframe is allowed cross-origin (only reads are blocked).
+  const sync = () => {
+    applyPinLayer();
+    const token = el.getAttribute("data-focus-token");
+    if (!token || token === lastFocusToken) return;
+    lastFocusToken = token;
+    const win = iframe?.contentWindow;
+    if (!win) return;
+    const url = el.getAttribute("data-focus-url") || "";
+    const y = parseFloat(el.getAttribute("data-focus-y") || "");
+    try {
+      win.postMessage(
+        { __prereviewFocus: true, url, y: Number.isFinite(y) ? y : 0 },
+        expectedOrigin || "*"
+      );
+    } catch {
+      // contentWindow gone mid-navigation — the next render retries.
+    }
+  };
+
+  return {
+    action,
+    cleanup: () => {
+      window.removeEventListener("message", onMessage);
+      proxyBridgeArmed.delete(el);
+      pageBridgeMetrics = null;
+    },
+    updateSend: (s) => {
+      send = s;
+    },
+    sync,
+  };
+}
+
 function attachRegionSelect(
   el: HTMLElement,
   action: string,
@@ -2096,6 +2287,25 @@ function attachRegionSelect(
 }
 
 type LineRange = { from: number; to: number; side?: string };
+// A region on a live (cross-origin) proxied page: a rectangle in 0..1
+// DOCUMENT fractions (not the host-rect fractions the drag spine yields, and
+// not a line range — a live app has no source markers). Survives scroll
+// because it's anchored to the document, not the viewport.
+type RectPayload = { x: number; y: number; w: number; h: number };
+type RegionPayload = LineRange | RectPayload;
+
+// PageMetrics is the proxied page's scroll + document size, reported by the
+// injected beacon (proxy.go) via postMessage. External mode frames exactly
+// one proxied iframe, so a single module-level record is enough; the proxy
+// bridge writes it and the "page" region resolver reads it to convert a
+// drawn box (viewport space) into document fractions.
+type PageMetrics = {
+  scrollX: number;
+  scrollY: number;
+  docW: number;
+  docH: number;
+};
+let pageBridgeMetrics: PageMetrics | null = null;
 
 // previewIframeFor finds the iframe a region overlay covers. The overlay
 // is a sibling of its iframe inside a positioned wrapper and is rendered
@@ -2114,7 +2324,7 @@ function previewIframeFor(overlay: HTMLElement): HTMLIFrameElement | null {
 // resolveRegion hit-tests a drawn box (viewport coords) against the line-
 // bearing elements of the overlay's target surface, returning the source
 // line-range payload or null when the box hit nothing.
-function resolveRegion(el: HTMLElement, box: BoxDragResult): LineRange | null {
+function resolveRegion(el: HTMLElement, box: BoxDragResult): RegionPayload | null {
   const surface = el.getAttribute("data-surface");
   if (surface === "html") {
     const iframe = previewIframeFor(el);
@@ -2139,12 +2349,46 @@ function resolveRegion(el: HTMLElement, box: BoxDragResult): LineRange | null {
       readCodeRange
     );
   }
+  if (surface === "page") {
+    return regionRectFromBox(el, box);
+  }
   console.warn(
-    `lvt-fx:region-select: unknown data-surface ${JSON.stringify(surface)} (expected "html" or "code")`
+    `lvt-fx:region-select: unknown data-surface ${JSON.stringify(surface)} (expected "html", "code", or "page")`
   );
   return null;
 }
 
+// regionRectFromBox converts a box drawn over the live-site overlay (its
+// x/y/w/h are 0..1 fractions of the overlay's rendered rect, which equals the
+// iframe's VIEWPORT) into 0..1 fractions of the proxied page's DOCUMENT,
+// using the beacon-reported scroll + document size. The overlay is
+// cross-origin, so we can't read the iframe's DOM — these metrics are the
+// only bridge. Returns null when no metrics have arrived yet (no scroll/nav
+// beacon) or the overlay has no size, so a too-early drag is a harmless
+// no-op. Exported so unit tests exercise the real conversion math.
+export function regionRectFromBox(
+  el: HTMLElement,
+  box: BoxDragResult
+): RectPayload | null {
+  const m = pageBridgeMetrics;
+  if (!m || m.docW <= 0 || m.docH <= 0) return null;
+  const rect = el.getBoundingClientRect();
+  if (rect.width <= 0 || rect.height <= 0) return null;
+  const docLeft = m.scrollX + box.x * rect.width;
+  const docTop = m.scrollY + box.y * rect.height;
+  return {
+    x: clampUnit(docLeft / m.docW),
+    y: clampUnit(docTop / m.docH),
+    w: clampUnit((box.w * rect.width) / m.docW),
+    h: clampUnit((box.h * rect.height) / m.docH),
+  };
+}
+
+function clampUnit(n: number): number {
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n > 1 ? 1 : n;
+}
+
 // readHTMLRange reads a rendered-HTML block's source span from its
 // data-from / data-to attributes (data-to defaults to data-from).
 // Exported so unit tests exercise the real reader, not a copy.
diff --git a/livetemplate-client.ts b/livetemplate-client.ts
index 8570f88..1639a80 100644
--- a/livetemplate-client.ts
+++ b/livetemplate-client.ts
@@ -13,6 +13,7 @@ import {
   handleAutoClickDirectives,
   handleHighlightDirectives,
   handleIframeAutoHeightDirectives,
+  handleProxyBridgeDirectives,
   handleRegionSelectDirectives,
   handleScrollDirectives,
   handleShadowRootHydration,
@@ -20,6 +21,7 @@ import {
   handleURLHashDirective,
   teardownAreaSelectForRoot,
   teardownIframeAutoHeightForRoot,
+  teardownProxyBridgeForRoot,
   teardownRegionSelectForRoot,
   teardownURLHashForRoot,
   teardownAutoClickTimers,
@@ -675,6 +677,7 @@ export class LiveTemplateClient {
       teardownSpy(this.wrapperElement);
       teardownAreaSelectForRoot(this.wrapperElement);
       teardownRegionSelectForRoot(this.wrapperElement);
+      teardownProxyBridgeForRoot(this.wrapperElement);
       teardownIframeAutoHeightForRoot(this.wrapperElement);
       teardownURLHashForRoot(this.wrapperElement);
     }
@@ -2031,6 +2034,11 @@ export class LiveTemplateClient {
     // send-callback wiring; the overlay is parent light DOM so it works
     // on iOS (unlike the deleted in-iframe tap).
     handleRegionSelectDirectives(element, (message) => this.send(message));
+    // proxy-bridge is the --external live-site bridge: it relays the proxied
+    // page's nav (→ setProxyURL) and scroll (→ pin-layer transform, no server
+    // hop) from the cross-origin beacon. Same send-callback wiring; the only
+    // thing that reaches across the cross-origin boundary, read-only.
+    handleProxyBridgeDirectives(element, (message) => this.send(message));
     // iframe-autoheight sizes the sandboxed HTML-preview iframe to its
     // content (iframes don't size to content). Selection over the preview
     // is handled by a parent-document overlay (area/region-select), not
diff --git a/tests/directives.test.ts b/tests/directives.test.ts
index 7f811fe..0afa372 100644
--- a/tests/directives.test.ts
+++ b/tests/directives.test.ts
@@ -8,6 +8,9 @@ import {
   teardownIframeAutoHeightForRoot,
   handleRegionSelectDirectives,
   teardownRegionSelectForRoot,
+  handleProxyBridgeDirectives,
+  teardownProxyBridgeForRoot,
+  regionRectFromBox,
   lineRangeFromBox,
   readHTMLRange,
   readCodeRange,
@@ -1341,6 +1344,76 @@ describe("handleAreaSelectDirectives", () => {
     expect(parent.querySelector(".lvt-area-select-overlay")).toBeNull();
   });
 
+  // dispatchTouch mirrors dispatchPointer but marks the event pointerType=touch
+  // so the spine takes its iOS-recovery path (cancel/lost-capture → finalize).
+  function dispatchTouch(
+    el: HTMLElement,
+    type: "pointerdown" | "pointermove" | "pointercancel" | "lostpointercapture",
+    clientX: number,
+    clientY: number
+  ): void {
+    const e = new MouseEvent(type, { clientX, clientY, button: 0, bubbles: true });
+    Object.defineProperty(e, "pointerId", { value: 1 });
+    Object.defineProperty(e, "isPrimary", { value: true });
+    Object.defineProperty(e, "pointerType", { value: "touch" });
+    el.dispatchEvent(e);
+  }
+
+  it("touch pointercancel KEEPS the drawn region (iOS long touch-drag recovery)", () => {
+    const [target] = mountTarget(
+      "img",
+      { "lvt-fx:area-select": "selectImageArea" },
+      { left: 0, top: 0, width: 200, height: 200 }
+    );
+    const send = jest.fn();
+    handleAreaSelectDirectives(document.body, send);
+
+    // A large touch-drag that iOS cancels mid-gesture must still capture the
+    // region drawn so far — the opposite of the mouse pointercancel above.
+    dispatchTouch(target, "pointerdown", 20, 20);
+    dispatchTouch(target, "pointermove", 180, 180);
+    dispatchTouch(target, "pointercancel", 180, 180);
+
+    expect(send).toHaveBeenCalledTimes(1);
+    const msg = send.mock.calls[0][0];
+    expect(msg.data.w).toBeCloseTo(0.8, 5); // (180-20)/200
+    expect(msg.data.h).toBeCloseTo(0.8, 5);
+  });
+
+  it("touch lostpointercapture KEEPS the drawn region", () => {
+    const [target] = mountTarget(
+      "img",
+      { "lvt-fx:area-select": "selectImageArea" },
+      { left: 0, top: 0, width: 200, height: 200 }
+    );
+    const send = jest.fn();
+    handleAreaSelectDirectives(document.body, send);
+
+    dispatchTouch(target, "pointerdown", 20, 20);
+    dispatchTouch(target, "pointermove", 120, 100);
+    dispatchTouch(target, "lostpointercapture", 120, 100);
+
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(send.mock.calls[0][0].data.w).toBeCloseTo(0.5, 5); // (120-20)/200
+  });
+
+  it("a tiny touch cancel is still dropped (area threshold, no stray region)", () => {
+    const [target] = mountTarget(
+      "img",
+      { "lvt-fx:area-select": "selectImageArea" },
+      { left: 0, top: 0, width: 1000, height: 1000 }
+    );
+    const send = jest.fn();
+    handleAreaSelectDirectives(document.body, send);
+
+    // 8×8 px on a 1000×1000 host → below MIN_AREA_FRACTION in both dims.
+    dispatchTouch(target, "pointerdown", 10, 10);
+    dispatchTouch(target, "pointermove", 18, 18);
+    dispatchTouch(target, "pointercancel", 18, 18);
+
+    expect(send).not.toHaveBeenCalled();
+  });
+
   it("is idempotent across renders for the same action", () => {
     const [target] = mountTarget(
       "img",
@@ -2760,3 +2833,228 @@ describe("handleRegionSelectDirectives", () => {
     expect(() => teardownRegionSelectForRoot(document.body)).not.toThrow();
   });
 });
+
+describe("handleProxyBridgeDirectives (--external live-site bridge)", () => {
+  const ORIGIN = "http://127.0.0.1:7778";
+
+  // Build the preview stage: <stage lvt-fx:proxy-bridge="setProxyURL">
+  //   <iframe src=ORIGIN> <div data-pin-layer>
+  function makeStage(): {
+    stage: HTMLElement;
+    iframe: HTMLIFrameElement;
+    pin: HTMLElement;
+  } {
+    const stage = document.createElement("div");
+    stage.setAttribute("lvt-fx:proxy-bridge", "setProxyURL");
+    const iframe = document.createElement("iframe");
+    iframe.src = ORIGIN + "/";
+    const pin = document.createElement("div");
+    pin.setAttribute("data-pin-layer", "");
+    stage.appendChild(iframe);
+    stage.appendChild(pin);
+    document.body.appendChild(stage);
+    return { stage, iframe, pin };
+  }
+
+  function beacon(data: Record<string, unknown>, origin = ORIGIN): void {
+    window.dispatchEvent(new MessageEvent("message", { data, origin }));
+  }
+
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    jest.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    teardownProxyBridgeForRoot(document.body);
+    document.body.innerHTML = "";
+    jest.restoreAllMocks();
+  });
+
+  it("a nav beacon dispatches setProxyURL with the page url", () => {
+    const send = jest.fn();
+    makeStage();
+    handleProxyBridgeDirectives(document.body, send);
+
+    beacon({ __prereview: true, type: "nav", url: "/pricing", docW: 800, docH: 4000 });
+    expect(send).toHaveBeenCalledWith({ action: "setProxyURL", data: { url: "/pricing" } });
+  });
+
+  it("does not re-dispatch setProxyURL for the same url (dedup)", () => {
+    const send = jest.fn();
+    makeStage();
+    handleProxyBridgeDirectives(document.body, send);
+
+    beacon({ __prereview: true, type: "nav", url: "/pricing", docW: 800, docH: 4000 });
+    beacon({ __prereview: true, type: "scroll", scrollY: 50, docW: 800, docH: 4000 });
+    beacon({ __prereview: true, type: "nav", url: "/pricing", docW: 800, docH: 4000 });
+    expect(send).toHaveBeenCalledTimes(1);
+
+    beacon({ __prereview: true, type: "nav", url: "/dashboard", docW: 800, docH: 4000 });
+    expect(send).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-pins by sizing the pin layer to the document and translating by -scroll", () => {
+    const send = jest.fn();
+    const { pin } = makeStage();
+    handleProxyBridgeDirectives(document.body, send);
+
+    beacon({ __prereview: true, type: "scroll", scrollX: 0, scrollY: 120, docW: 800, docH: 4000 });
+    expect(pin.style.width).toBe("800px");
+    expect(pin.style.height).toBe("4000px");
+    expect(pin.style.transform).toBe("translate(0px, -120px)");
+  });
+
+  it("ignores messages from a foreign origin", () => {
+    const send = jest.fn();
+    const { pin } = makeStage();
+    handleProxyBridgeDirectives(document.body, send);
+
+    beacon({ __prereview: true, type: "nav", url: "/evil", docW: 9, docH: 9 }, "http://evil.example");
+    expect(send).not.toHaveBeenCalled();
+    expect(pin.style.transform).toBe("");
+  });
+
+  it("ignores non-prereview messages", () => {
+    const send = jest.fn();
+    makeStage();
+    handleProxyBridgeDirectives(document.body, send);
+
+    beacon({ type: "nav", url: "/x" });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("teardown removes the window listener (no dispatch after cleanup)", () => {
+    const send = jest.fn();
+    makeStage();
+    handleProxyBridgeDirectives(document.body, send);
+    teardownProxyBridgeForRoot(document.body);
+
+    beacon({ __prereview: true, type: "nav", url: "/after", docW: 1, docH: 1 });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("relays a focus request to the iframe only when the focus token changes", () => {
+    const { stage, iframe } = makeStage();
+    stage.setAttribute("data-focus-token", "1");
+    stage.setAttribute("data-focus-url", "/pricing");
+    stage.setAttribute("data-focus-y", "0.42");
+    const post = jest
+      .spyOn(iframe.contentWindow as Window, "postMessage")
+      .mockImplementation(() => {});
+
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    expect(post).toHaveBeenCalledWith(
+      { __prereviewFocus: true, url: "/pricing", y: 0.42 },
+      expect.any(String)
+    );
+
+    // Re-render with the SAME token → no repeat (avoids re-scrolling on every
+    // unrelated server render).
+    post.mockClear();
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    expect(post).not.toHaveBeenCalled();
+
+    // A new token (the user tapped Locate again) → relays again.
+    stage.setAttribute("data-focus-token", "2");
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    expect(post).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not relay a focus request when no focus token is set", () => {
+    const { iframe } = makeStage();
+    const post = jest
+      .spyOn(iframe.contentWindow as Window, "postMessage")
+      .mockImplementation(() => {});
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it("re-applies the pin-layer size/transform on re-render (morphdom-wipe recovery)", () => {
+    const { pin } = makeStage();
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    beacon({ __prereview: true, type: "scroll", scrollX: 0, scrollY: 100, docW: 800, docH: 4000 });
+    expect(pin.style.transform).toBe("translate(0px, -100px)");
+
+    // A server render re-renders the pin layer; morphdom diffs it against the
+    // template (no inline style) and wipes the imperative styles.
+    pin.removeAttribute("style");
+    expect(pin.style.transform).toBe("");
+
+    // The directive scan runs after morphdom and must restore them from the
+    // cached metrics — otherwise a saved pin vanishes until the next scroll.
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    expect(pin.style.width).toBe("800px");
+    expect(pin.style.height).toBe("4000px");
+    expect(pin.style.transform).toBe("translate(0px, -100px)");
+  });
+});
+
+describe("regionRectFromBox (viewport box → document fractions)", () => {
+  const ORIGIN = "http://127.0.0.1:7778";
+
+  function box(x: number, y: number, w: number, h: number) {
+    // regionRectFromBox only reads x/y/w/h; the rect fields are unused here.
+    return { left: 0, top: 0, right: 0, bottom: 0, x, y, w, h };
+  }
+
+  // Arm the bridge with given page metrics so the module-level PageMetrics is
+  // populated the same way production does (via a beacon message).
+  function armMetrics(m: { scrollX?: number; scrollY?: number; docW: number; docH: number }) {
+    const stage = document.createElement("div");
+    stage.setAttribute("lvt-fx:proxy-bridge", "setProxyURL");
+    const iframe = document.createElement("iframe");
+    iframe.src = ORIGIN + "/";
+    stage.appendChild(iframe);
+    document.body.appendChild(stage);
+    handleProxyBridgeDirectives(document.body, jest.fn());
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        origin: ORIGIN,
+        data: { __prereview: true, type: "scroll", scrollX: 0, scrollY: 0, ...m },
+      })
+    );
+  }
+
+  function overlay(width: number, height: number): HTMLElement {
+    const el = document.createElement("div");
+    el.getBoundingClientRect = jest.fn(
+      () => ({ width, height, left: 0, top: 0, right: width, bottom: height, x: 0, y: 0, toJSON() {} }) as DOMRect
+    );
+    return el;
+  }
+
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    jest.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    teardownProxyBridgeForRoot(document.body);
+    document.body.innerHTML = "";
+    jest.restoreAllMocks();
+  });
+
+  it("returns null when no metrics have arrived (too-early drag)", () => {
+    // No bridge armed → pageBridgeMetrics is null after teardown in afterEach.
+    expect(regionRectFromBox(overlay(1000, 500), box(0.1, 0.1, 0.2, 0.2))).toBeNull();
+  });
+
+  it("converts a viewport box to document fractions using scroll + doc size", () => {
+    // Overlay = iframe viewport 1000x500; document 1000x5000 scrolled 1000px.
+    // A box at y=0.2 of the viewport → docTop = 1000 + 0.2*500 = 1100 → 1100/5000 = 0.22.
+    armMetrics({ scrollY: 1000, docW: 1000, docH: 5000 });
+    const r = regionRectFromBox(overlay(1000, 500), box(0.1, 0.2, 0.3, 0.4));
+    expect(r).not.toBeNull();
+    expect(r!.x).toBeCloseTo((0 + 0.1 * 1000) / 1000, 5); // 0.1
+    expect(r!.y).toBeCloseTo((1000 + 0.2 * 500) / 5000, 5); // 0.22
+    expect(r!.w).toBeCloseTo((0.3 * 1000) / 1000, 5); // 0.3
+    expect(r!.h).toBeCloseTo((0.4 * 500) / 5000, 5); // 0.04
+  });
+
+  it("clamps document fractions into [0,1]", () => {
+    armMetrics({ scrollY: 4900, docW: 1000, docH: 5000 });
+    // docTop = 4900 + 0.9*500 = 5350 → 5350/5000 = 1.07 → clamps to 1.
+    const r = regionRectFromBox(overlay(1000, 500), box(0, 0.9, 0.5, 0.5));
+    expect(r!.y).toBe(1);
+    expect(r!.h).toBeLessThanOrEqual(1);
+  });
+});

From 082dab4c69948ec83465b7955ff37e639d3064f1 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Tue, 16 Jun 2026 20:19:12 +0000
Subject: [PATCH 2/5] fix(proxy-bridge): fail closed when the iframe origin
 can't be resolved
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address PR review: if `new URL(iframe.src).origin` can't resolve (missing/blank
src), reject every inbound postMessage instead of falling through, and never
broadcast the focus message to "*" — only to the resolved proxied origin. Warn
once on an unresolvable origin (should never happen — the server renders an
absolute src). +test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dom/directives.ts        | 16 +++++++++++++---
 tests/directives.test.ts | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/dom/directives.ts b/dom/directives.ts
index 8c37cda..566094c 100644
--- a/dom/directives.ts
+++ b/dom/directives.ts
@@ -2179,6 +2179,15 @@ function attachProxyBridge(
   } catch {
     expectedOrigin = "";
   }
+  // Fail closed: if the origin can't be resolved we can't trust any sender, so
+  // reject every inbound message (onMessage) and never broadcast outbound focus
+  // (sync). An unresolved origin should be impossible — the server always
+  // renders an absolute src — so warn if it happens.
+  if (!expectedOrigin) {
+    console.warn(
+      "lvt-fx:proxy-bridge: could not resolve the iframe origin; ignoring all postMessage traffic"
+    );
+  }
 
   // applyPinLayer sizes the pin layer to the document and slides it by -scroll
   // so each marker (percentage-positioned by the server within this layer)
@@ -2196,7 +2205,7 @@ function attachProxyBridge(
   };
 
   const onMessage = (e: MessageEvent) => {
-    if (expectedOrigin && e.origin !== expectedOrigin) return;
+    if (!expectedOrigin || e.origin !== expectedOrigin) return;
     const d = e.data;
     if (!d || d.__prereview !== true) return;
 
@@ -2232,13 +2241,14 @@ function attachProxyBridge(
     if (!token || token === lastFocusToken) return;
     lastFocusToken = token;
     const win = iframe?.contentWindow;
-    if (!win) return;
+    // No "*" fallback — only post to the resolved proxied origin (fail closed).
+    if (!win || !expectedOrigin) return;
     const url = el.getAttribute("data-focus-url") || "";
     const y = parseFloat(el.getAttribute("data-focus-y") || "");
     try {
       win.postMessage(
         { __prereviewFocus: true, url, y: Number.isFinite(y) ? y : 0 },
-        expectedOrigin || "*"
+        expectedOrigin
       );
     } catch {
       // contentWindow gone mid-navigation — the next render retries.
diff --git a/tests/directives.test.ts b/tests/directives.test.ts
index 0afa372..b2946db 100644
--- a/tests/directives.test.ts
+++ b/tests/directives.test.ts
@@ -2969,6 +2969,38 @@ describe("handleProxyBridgeDirectives (--external live-site bridge)", () => {
     expect(post).not.toHaveBeenCalled();
   });
 
+  it("fails closed when the iframe origin can't be resolved (no src)", () => {
+    // An iframe with no src → origin can't be resolved → reject all inbound
+    // messages (regardless of sender origin) and never broadcast focus.
+    const stage = document.createElement("div");
+    stage.setAttribute("lvt-fx:proxy-bridge", "setProxyURL");
+    const iframe = document.createElement("iframe"); // deliberately no src
+    const pin = document.createElement("div");
+    pin.setAttribute("data-pin-layer", "");
+    stage.appendChild(iframe);
+    stage.appendChild(pin);
+    document.body.appendChild(stage);
+
+    const send = jest.fn();
+    handleProxyBridgeDirectives(document.body, send);
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        data: { __prereview: true, type: "nav", url: "/x", docW: 1, docH: 1 },
+        origin: "http://anything.example",
+      })
+    );
+    expect(send).not.toHaveBeenCalled();
+
+    const post = jest
+      .spyOn(iframe.contentWindow as Window, "postMessage")
+      .mockImplementation(() => {});
+    stage.setAttribute("data-focus-token", "1");
+    stage.setAttribute("data-focus-url", "/x");
+    stage.setAttribute("data-focus-y", "0.5");
+    handleProxyBridgeDirectives(document.body, send);
+    expect(post).not.toHaveBeenCalled();
+  });
+
   it("re-applies the pin-layer size/transform on re-render (morphdom-wipe recovery)", () => {
     const { pin } = makeStage();
     handleProxyBridgeDirectives(document.body, jest.fn());

From 918376c1dd96bb29f4c221329eb70d1c3569cea7 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Wed, 17 Jun 2026 05:33:52 +0000
Subject: [PATCH 3/5] refactor(proxy-bridge): enforce single bridge + cover
 zero-area edge

PR review follow-ups (non-blocking): warn + ignore a second lvt-fx:proxy-bridge
(the module-level pageBridgeMetrics is shared, so a second would collide), and
add an explicit test that a lostpointercapture before any pointermove yields a
zero-area box the threshold rejects.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dom/directives.ts        | 10 ++++++++++
 tests/directives.test.ts | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/dom/directives.ts b/dom/directives.ts
index 566094c..950d6dd 100644
--- a/dom/directives.ts
+++ b/dom/directives.ts
@@ -2143,6 +2143,16 @@ export function handleProxyBridgeDirectives(
       continue;
     }
     if (existing) existing.cleanup();
+    // Enforce exactly one bridge: pageBridgeMetrics is a module-level singleton,
+    // so a second bridge would share it and the first cleanup() would null it,
+    // blinding the other. External mode renders one stage; a second is a bug
+    // (e.g. a transient double-render) — warn and ignore it rather than collide.
+    if (proxyBridgeArmed.size > 0) {
+      console.warn(
+        "lvt-fx:proxy-bridge: external mode expects exactly one bridge; ignoring an additional one (shared page metrics would collide)."
+      );
+      continue;
+    }
     const entry = attachProxyBridge(el, action, send);
     proxyBridgeArmed.set(el, entry);
     entry.sync();
diff --git a/tests/directives.test.ts b/tests/directives.test.ts
index b2946db..fcabe6b 100644
--- a/tests/directives.test.ts
+++ b/tests/directives.test.ts
@@ -1397,6 +1397,24 @@ describe("handleAreaSelectDirectives", () => {
     expect(send.mock.calls[0][0].data.w).toBeCloseTo(0.5, 5); // (120-20)/200
   });
 
+  it("touch lostpointercapture before any move dispatches nothing (zero-area)", () => {
+    // If capture is lost before a single pointermove, lastMove is the
+    // pointerdown event, so finalize sees a zero-area box — the threshold must
+    // reject it, not create a degenerate region.
+    const [target] = mountTarget(
+      "img",
+      { "lvt-fx:area-select": "selectImageArea" },
+      { left: 0, top: 0, width: 200, height: 200 }
+    );
+    const send = jest.fn();
+    handleAreaSelectDirectives(document.body, send);
+
+    dispatchTouch(target, "pointerdown", 50, 50);
+    dispatchTouch(target, "lostpointercapture", 50, 50);
+
+    expect(send).not.toHaveBeenCalled();
+  });
+
   it("a tiny touch cancel is still dropped (area threshold, no stray region)", () => {
     const [target] = mountTarget(
       "img",
@@ -2969,6 +2987,22 @@ describe("handleProxyBridgeDirectives (--external live-site bridge)", () => {
     expect(post).not.toHaveBeenCalled();
   });
 
+  it("arms exactly one bridge and ignores a second (shared-metrics guard)", () => {
+    const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    makeStage();
+    makeStage(); // a second stage — should be ignored
+    const send = jest.fn();
+    handleProxyBridgeDirectives(document.body, send);
+
+    // Only the first bridge is armed; the second triggers the warning.
+    expect(
+      warn.mock.calls.some((c) => String(c[0]).includes("exactly one bridge"))
+    ).toBe(true);
+    // A nav beacon still drives setProxyURL once (the single armed bridge).
+    beacon({ __prereview: true, type: "nav", url: "/p", docW: 1, docH: 1 });
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+
   it("fails closed when the iframe origin can't be resolved (no src)", () => {
     // An iframe with no src → origin can't be resolved → reject all inbound
     // messages (regardless of sender origin) and never broadcast focus.

From 86230a51610038795fdccb9f7cc97cff33038ead Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Wed, 17 Jun 2026 05:39:49 +0000
Subject: [PATCH 4/5] polish(proxy-bridge/drag): reset pointerType + clarify
 region coord frame

PR review nits (non-blocking): clear pointerType alongside lastMove in the drag
finalize/reset (symmetry; avoids a future unguarded read seeing stale state),
and document that regionRectFromBox's box fractions are overlay-relative, not
viewport-absolute.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dom/directives.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/dom/directives.ts b/dom/directives.ts
index 950d6dd..6cfd10c 100644
--- a/dom/directives.ts
+++ b/dom/directives.ts
@@ -1710,6 +1710,7 @@ function attachBoxDragSelect(
     const capturedPointerId = pointerId;
     const rect = startRect;
     pointerId = -1;
+    pointerType = "";
     dragParent = null;
     startRect = null;
     lastMove = null;
@@ -2394,6 +2395,11 @@ export function regionRectFromBox(
   if (!m || m.docW <= 0 || m.docH <= 0) return null;
   const rect = el.getBoundingClientRect();
   if (rect.width <= 0 || rect.height <= 0) return null;
+  // box.x/y/w/h are OVERLAY-RELATIVE fractions (0..1 of the overlay's own
+  // rect), not viewport-absolute — so the overlay's position on the page
+  // doesn't enter the math. The overlay covers the iframe's viewport, so
+  // box.x*rect.width is the in-viewport pixel offset; adding the beacon's
+  // scroll lifts it into iframe-DOCUMENT pixels, then ÷ doc size → fraction.
   const docLeft = m.scrollX + box.x * rect.width;
   const docTop = m.scrollY + box.y * rect.height;
   return {

From 0bb7674fb7a708749351e8b6ad609f3ca0ff4f55 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Wed, 17 Jun 2026 05:44:11 +0000
Subject: [PATCH 5/5] polish(proxy-bridge/drag): simplify lost-capture cond +
 guards/comments

Final PR-review nits (all non-blocking): drop the redundant `m !== null` from
onLostCapture (lastMove is non-null during a drag; finalize tolerates null),
note that clearing pageBridgeMetrics on cleanup is intentional, and reject a
non-positive box in the exported regionRectFromBox.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dom/directives.ts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/dom/directives.ts b/dom/directives.ts
index 6cfd10c..c8df9d3 100644
--- a/dom/directives.ts
+++ b/dom/directives.ts
@@ -1956,8 +1956,10 @@ function attachBoxDragSelect(
     if (e.pointerId !== pointerId) return;
     // Same touch-recovery as pointercancel: finalize from the last move so a
     // capture yank mid-touch-drag keeps the region instead of dropping it.
-    const m = lastMove;
-    finalize(pointerType === "touch" ? m : null, pointerType === "touch" && m !== null);
+    // (lastMove is non-null whenever a drag is active — set on pointerdown —
+    // and finalize tolerates a null event anyway, so no extra guard is needed.)
+    const touch = pointerType === "touch";
+    finalize(touch ? lastMove : null, touch);
   };
 
   el.addEventListener("pointerdown", onPointerDown);
@@ -2271,6 +2273,9 @@ function attachProxyBridge(
     cleanup: () => {
       window.removeEventListener("message", onMessage);
       proxyBridgeArmed.delete(el);
+      // Intentionally drop the shared metrics on teardown — keep this here:
+      // a stale rect from a torn-down bridge must not leak into a new one (the
+      // next beacon re-populates it). Do NOT hoist this out to "simplify".
       pageBridgeMetrics = null;
     },
     updateSend: (s) => {
@@ -2395,6 +2400,9 @@ export function regionRectFromBox(
   if (!m || m.docW <= 0 || m.docH <= 0) return null;
   const rect = el.getBoundingClientRect();
   if (rect.width <= 0 || rect.height <= 0) return null;
+  // The drag spine only ever hands us a positive box, but this is exported —
+  // reject a non-positive box rather than letting clampUnit collapse it to 0.
+  if (box.w <= 0 || box.h <= 0) return null;
   // box.x/y/w/h are OVERLAY-RELATIVE fractions (0..1 of the overlay's own
   // rect), not viewport-absolute — so the overlay's position on the page
   // doesn't enter the math. The overlay covers the iframe's viewport, so