@hienlh/ppm 0.22.11 → 0.23.1

package/src/services/design/bridge/bridge-layout-screenshot.ts

@@ -0,0 +1,106 @@
+import type { BridgeApi } from "./bridge-core.ts";
+
+/**
+ * The picture half of the canvas self-check, drawn inside the design frame by the screenshot
+ * library the parent handed over (`modern-screenshot`, which re-renders the DOM through an
+ * SVG `foreignObject`). No headless browser is involved: the canvas the user has open is
+ * the renderer.
+ *
+ * The result is at most 1280px wide and 2400px tall and at most 400 KB, as a JPEG: quality
+ * drops first, then the size. Web fonts and images from CDNs may come out substituted,
+ * because the frame may fetch its own design files only; the note says so. Shipped as source
+ * (`ppm.lib`), so nothing here may reference this module's scope.
+ */
+
+export interface ScreenshotLib {
+  createContext(node: Node, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  domToCanvas(context: Record<string, unknown>): Promise<HTMLCanvasElement>;
+  destroyContext(context: Record<string, unknown>): void;
+}
+
+export interface CanvasShot {
+  dataUrl: string;
+  width: number;
+  height: number;
+  note: string;
+}
+
+export async function captureScreenshot(ppm: BridgeApi, shot: ScreenshotLib): Promise<CanvasShot> {
+  const win = ppm.win;
+  const doc = ppm.doc;
+  const de = doc.documentElement;
+  const MAX_W = 1280, MAX_H = 2400, MAX_BYTES = 400 * 1024;
+  const width = de.clientWidth || win.innerWidth;
+  const scale = Math.min(1, MAX_W / Math.max(1, width));
+  const paint = (el: Element): string => win.getComputedStyle(el).backgroundColor;
+  const clear = (c: string): boolean => !c || c === "transparent" || /rgba\(.*,\s*0\)$/.test(c);
+  const bg = !clear(paint(de)) ? paint(de) : doc.body && !clear(paint(doc.body)) ? paint(doc.body) : "#ffffff";
+  // The copy is styled with resolved values, and for a grid container those list implicit
+  // tracks as if they were explicit, which moves every `-1` line and re-places the items:
+  // the broken grid this check exists for would come out as a different layout. So each
+  // grid's authored template (Typed OM, where available) rides along on an attribute and is
+  // put back on the copy.
+  const MARK = "data-ppm-shot-grid";
+  const marked: Element[] = [];
+  const all = doc.body ? doc.body.getElementsByTagName("*") : [];
+  for (let i = 0; i < all.length && i < 8000; i++) {
+    const el = all[i] as Element & { computedStyleMap?: () => { get(name: string): unknown } };
+    if (typeof el.computedStyleMap !== "function") break;
+    const d = win.getComputedStyle(el).display;
+    if (d !== "grid" && d !== "inline-grid") continue;
+    const map = el.computedStyleMap();
+    el.setAttribute(MARK, String(map.get("grid-template-columns")) + "|" + String(map.get("grid-template-rows")));
+    marked.push(el);
+  }
+  const restoreTemplate = (clone: Node): void => {
+    const c = clone as HTMLElement;
+    if (c.nodeType !== 1 || !c.hasAttribute(MARK)) return;
+    const parts = (c.getAttribute(MARK) || "").split("|");
+    c.removeAttribute(MARK);
+    if (parts[0] && parts[0] !== "none") c.style.setProperty("grid-template-columns", parts[0]);
+    if (parts[1] && parts[1] !== "none") c.style.setProperty("grid-template-rows", parts[1]);
+  };
+  let rendered: HTMLCanvasElement;
+  try {
+    const context = await shot.createContext(de, {
+      scale, backgroundColor: bg, timeout: 6000, onCloneEachNode: restoreTemplate,
+      filter: (node: Node) => !((node as Element).localName && /^ppm-design-/.test((node as Element).localName)),
+    });
+    // The library reads default styles from a hidden iframe of its own. Inside the sandboxed
+    // design every nested frame gets a fresh opaque origin, so reading that iframe throws a
+    // cross-origin error; a stand-in with no window makes it inline every computed style
+    // instead (a larger SVG, the same picture).
+    context.sandbox = { contentWindow: null, remove() { /* nothing was attached */ } };
+    try {
+      rendered = await shot.domToCanvas(context);
+    } finally {
+      try { shot.destroyContext(context); } catch (e) { /* only frees caches */ }
+    }
+  } finally {
+    for (let i = 0; i < marked.length; i++) marked[i]!.removeAttribute(MARK);
+  }
+  const notes = ["Re-drawn from the page's DOM; web fonts and images from CDNs may look different."];
+  let w = rendered.width, h = Math.min(rendered.height, MAX_H);
+  if (rendered.height > MAX_H) notes.push("Only the top " + Math.round(MAX_H / scale) + "px of the page are shown.");
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const out = doc.createElement("canvas");
+    out.width = Math.max(1, Math.round(w));
+    out.height = Math.max(1, Math.round(h));
+    const ctx = out.getContext("2d");
+    if (!ctx) throw new Error("no 2d canvas");
+    ctx.fillStyle = bg;
+    ctx.fillRect(0, 0, out.width, out.height);
+    ctx.drawImage(rendered, 0, 0, rendered.width * (w / rendered.width), rendered.height * (w / rendered.width));
+    const qualities = [0.82, 0.68, 0.55, 0.42];
+    for (let q = 0; q < qualities.length; q++) {
+      const dataUrl = out.toDataURL("image/jpeg", qualities[q]);
+      const bytes = Math.floor((dataUrl.length - dataUrl.indexOf(",") - 1) * 3 / 4);
+      if (bytes <= MAX_BYTES && dataUrl.indexOf("data:image/jpeg;base64,") === 0) {
+        return { dataUrl, width: out.width, height: out.height, note: notes.join(" ") };
+      }
+    }
+    w *= 0.7;
+    h *= 0.7;
+  }
+  throw new Error("the screenshot stayed over 400 KB");
+}

package/src/services/design/bridge/bridge-nav-guard.ts

@@ -0,0 +1,61 @@
+import type { BridgeApi } from "./bridge-core.ts";
+
+/**
+ * Keeps the design frame from navigating itself away.
+ *
+ * The sandbox stops top-level navigation, popups and form posts (`form-action 'none'`), but
+ * a sandboxed frame may still navigate *itself*: a link, or `location.href = "https://…"`.
+ * That both leaks data in the URL and replaces the design with a foreign page that then
+ * owns the iframe's `contentWindow`. So:
+ *  - a capture-phase `click`/`auxclick` on any link that would leave the current document
+ *    is cancelled and reported as `navigate-blocked`; in-page `#anchor` links still work;
+ *  - where the Navigation API exists, a cancelable cross-document `navigate` is cancelled
+ *    too, which covers script-driven navigation. A reload of the same URL is allowed.
+ * Elsewhere, a script-driven navigation still gets through; the parent notices within 3 s
+ * because no `ready` with the current nonce arrives, and reloads the canvas.
+ *
+ * Shipped as source like the core, so it may only use what it is handed in `ppm`.
+ */
+export function installNavGuard(ppm: BridgeApi): void {
+  const win = ppm.win;
+  const doc = ppm.doc;
+  const withoutHash = (href: string): string => href.split("#")[0]!;
+
+  function report(href: string): void {
+    // `javascript:` links are a common "button that looks like a link"; nothing leaves the
+    // document, so there is nothing worth reporting.
+    if (!/^javascript:/i.test(href)) ppm.post("navigate-blocked", { href: String(href).slice(0, 2048) });
+  }
+
+  function onLinkActivation(event: MouseEvent): void {
+    const target = event.target as Element | null;
+    if (!target || typeof target.closest !== "function") return;
+    const link = target.closest("a[href], area[href]");
+    if (!link) return;
+    const raw = link.getAttribute("href") || "";
+    let url: URL;
+    try {
+      url = new URL(raw, doc.baseURI);
+    } catch (e) {
+      event.preventDefault();
+      return;
+    }
+    if (url.hash && withoutHash(url.href) === withoutHash(win.location.href)) return;
+    event.preventDefault();
+    report(url.protocol === "javascript:" ? raw : url.href);
+  }
+
+  win.addEventListener("click", onLinkActivation, true);
+  win.addEventListener("auxclick", onLinkActivation, true);
+
+  const navigation = (win as unknown as { navigation?: EventTarget }).navigation;
+  if (navigation && typeof navigation.addEventListener === "function") {
+    navigation.addEventListener("navigate", (event: Event) => {
+      const e = event as Event & { hashChange?: boolean; destination?: { url: string; sameDocument: boolean } };
+      if (!e.cancelable || e.hashChange || !e.destination || e.destination.sameDocument) return;
+      if (e.destination.url === win.location.href) return;
+      e.preventDefault();
+      report(e.destination.url);
+    });
+  }
+}

package/src/services/design/bridge/bridge-picker-overlay.ts

@@ -0,0 +1,54 @@
+/**
+ * The picker's outline boxes, drawn inside the design frame.
+ *
+ * They live in a closed shadow root on a host appended to `<html>`, with `pointer-events:
+ * none` and the highest z-index: never an event target, out of reach of page CSS, and never
+ * part of the markup a picked element is described with. The host is re-attached if the
+ * page's own script removes it. Shipped as source (`ppm.lib.createPickerOverlay`), so it
+ * may only use what it is handed.
+ */
+
+export interface PickerOverlay {
+  host: HTMLElement;
+  /** Place the dashed (`outline`) or solid (`selection`) box over `el`, or hide it. */
+  show(which: "outline" | "selection", el: Element | null): void;
+}
+
+export function createPickerOverlay(doc: Document): PickerOverlay {
+  const host = doc.createElement("ppm-design-overlay");
+  host.setAttribute("aria-hidden", "true");
+  const props: Array<[string, string]> = [
+    ["position", "fixed"], ["top", "0"], ["left", "0"], ["width", "0"], ["height", "0"], ["display", "block"],
+    ["overflow", "visible"], ["pointer-events", "none"], ["z-index", "2147483647"], ["margin", "0"], ["padding", "0"],
+  ];
+  for (const [name, value] of props) host.style.setProperty(name, value, "important");
+  const root = host.attachShadow({ mode: "closed" });
+  const box = (border: string, fill: string): HTMLElement => {
+    const el = doc.createElement("div");
+    el.style.cssText = "position:fixed;display:none;box-sizing:border-box;pointer-events:none;border-radius:2px;"
+      + "border:" + border + ";background:" + fill + ";";
+    root.appendChild(el);
+    return el;
+  };
+  const boxes = {
+    outline: box("2px dashed #2563eb", "rgba(37,99,235,0.08)"),
+    selection: box("2px solid #2563eb", "rgba(37,99,235,0.14)"),
+  };
+  return {
+    host,
+    show(which, el) {
+      if (!host.isConnected && doc.documentElement) doc.documentElement.appendChild(host);
+      const b = boxes[which];
+      if (!el || !el.isConnected) {
+        b.style.display = "none";
+        return;
+      }
+      const r = el.getBoundingClientRect();
+      b.style.left = r.left + "px";
+      b.style.top = r.top + "px";
+      b.style.width = Math.max(2, r.width) + "px";
+      b.style.height = Math.max(2, r.height) + "px";
+      b.style.display = "block";
+    },
+  };
+}

package/src/services/design/bridge/bridge-picker.ts

@@ -0,0 +1,174 @@
+import type { BridgeApi } from "./bridge-core.ts";
+
+/**
+ * Element picking inside the design frame, for pinned comments.
+ *
+ * While the parent has the picker on, the pointer outlines what it is over and a click
+ * selects it. On touch a first tap outlines, a second tap on the same element selects,
+ * and a 500 ms long-press selects and asks for the comment composer (`element-menu`).
+ *
+ * The outline is drawn by `ppm.lib.createPickerOverlay` (a closed shadow root that is
+ * never an event target), re-created with every document.
+ *
+ * Picking must not also *use* the page: clicks, presses, drags and selections are swallowed
+ * in the capture phase on `window`. The bridge is the first script in `<head>`, and this
+ * feature is installed before the nav guard, so these listeners run before anything else.
+ *
+ * The long-press is disarmed on `touchmove` past 10 px, on `touchend` and on `touchcancel`:
+ * once the browser takes the gesture for a scroll it fires `touchcancel` and delivers no
+ * further move or end, and a timer left armed would open the composer over a list the
+ * finger is already scrolling.
+ *
+ * Shipped as source, so it may only use what it is handed in `ppm`.
+ */
+export function installPicker(ppm: BridgeApi): void {
+  const win = ppm.win;
+  const doc = ppm.doc;
+  const LONG_PRESS_MS = 500;
+  const MOVE_TOLERANCE = 10;
+  // Mouse events a browser synthesises after a tap arrive within this window of the touch.
+  const TOUCH_WINDOW_MS = 800;
+
+  let on = false;
+  let outlined: Element | null = null;
+  let selected: Element | null = null;
+  let press: { target: Element; x: number; y: number; timer: number; fired: boolean } | null = null;
+  let lastTouchAt = -Infinity;
+  let swallowClicksUntil = -Infinity;
+  let overlay: ReturnType<typeof ppm.lib.createPickerOverlay> | null = null;
+
+  function draw(): void {
+    if (!outlined && !selected && !overlay) return;
+    if (!overlay) overlay = ppm.lib.createPickerOverlay(doc);
+    overlay.show("outline", on && outlined !== selected ? outlined : null);
+    overlay.show("selection", selected);
+  }
+
+  let drawQueued = false;
+  function redrawSoon(): void {
+    if (drawQueued || (!outlined && !selected)) return;
+    drawQueued = true;
+    const run = (): void => {
+      drawQueued = false;
+      draw();
+      // The parent places its action bar from the selection's rect, so it needs the new one.
+      if (selected && selected.isConnected) ppm.post("select", { el: ppm.lib.describeElement(selected, ppm) });
+    };
+    if (typeof win.requestAnimationFrame === "function") win.requestAnimationFrame(run);
+    else win.setTimeout(run, 16);
+  }
+
+  function pick(target: EventTarget | null): Element | null {
+    const el = target as Element | null;
+    if (!el || el.nodeType !== 1 || el === doc.documentElement) return null;
+    return overlay && el === overlay.host ? null : el;
+  }
+
+  function outline(el: Element | null): void {
+    if (el === outlined) return;
+    outlined = el;
+    draw();
+    if (!el) {
+      ppm.post("hover", { el: null });
+      return;
+    }
+    const r = el.getBoundingClientRect();
+    ppm.post("hover", { el: { tag: el.localName.toLowerCase(), rect: { x: r.left, y: r.top, w: r.width, h: r.height } } });
+  }
+
+  function select(el: Element, openComposer: boolean): void {
+    selected = el;
+    outlined = null;
+    draw();
+    ppm.post(openComposer ? "element-menu" : "select", { el: ppm.lib.describeElement(el, ppm) });
+  }
+
+  function disarm(): void {
+    if (press) win.clearTimeout(press.timer);
+    press = null;
+  }
+
+  function setOn(next: boolean): void {
+    on = next;
+    if (!on) {
+      disarm();
+      outlined = null;
+      draw();
+    }
+  }
+
+  const swallow = (event: Event): void => {
+    if (!on) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+
+  win.addEventListener("click", (event: MouseEvent) => {
+    if (!on) return;
+    swallow(event);
+    const now = Date.now();
+    if (now < swallowClicksUntil) return;
+    const el = pick(event.target);
+    if (!el) return;
+    if (now - lastTouchAt > TOUCH_WINDOW_MS) select(el, false);
+    else if (el === outlined) select(el, false);
+    else outline(el);
+  }, true);
+  const swallowed = ["mousedown", "mouseup", "pointerdown", "pointerup", "dblclick", "auxclick", "contextmenu", "submit", "selectstart", "dragstart"];
+  for (const type of swallowed) win.addEventListener(type, swallow, true);
+
+  win.addEventListener("mousemove", (event: MouseEvent) => {
+    if (!on || Date.now() - lastTouchAt < TOUCH_WINDOW_MS) return;
+    outline(pick(event.target));
+  }, { capture: true, passive: true });
+
+  win.addEventListener("touchstart", (event: TouchEvent) => {
+    if (!on) return;
+    lastTouchAt = Date.now();
+    disarm();
+    const target = pick(event.target);
+    const t = event.touches && event.touches[0];
+    if (!target || (event.touches && event.touches.length > 1)) return;
+    const entry = { target, x: t ? t.clientX : 0, y: t ? t.clientY : 0, timer: 0, fired: false };
+    entry.timer = win.setTimeout(() => {
+      entry.fired = true;
+      select(entry.target, true);
+    }, LONG_PRESS_MS);
+    press = entry;
+  }, { capture: true, passive: true });
+  win.addEventListener("touchmove", (event: TouchEvent) => {
+    const t = event.touches && event.touches[0];
+    if (!press || !t) return;
+    if (Math.abs(t.clientX - press.x) > MOVE_TOLERANCE || Math.abs(t.clientY - press.y) > MOVE_TOLERANCE) disarm();
+  }, { capture: true, passive: true });
+  win.addEventListener("touchend", () => {
+    lastTouchAt = Date.now();
+    // The click that follows a completed long-press is not a tap.
+    if (press && press.fired) swallowClicksUntil = lastTouchAt + TOUCH_WINDOW_MS;
+    disarm();
+  }, { capture: true, passive: true });
+  win.addEventListener("touchcancel", disarm, { capture: true, passive: true });
+
+  win.addEventListener("keydown", (event: KeyboardEvent) => {
+    if (!on || event.key !== "Escape") return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    setOn(false);
+    ppm.post("picker-exit");
+  }, true);
+
+  // Capture, so a scrolling container inside the page moves the outline too.
+  win.addEventListener("scroll", redrawSoon, { capture: true, passive: true });
+  win.addEventListener("resize", redrawSoon, { passive: true });
+
+  ppm.on("picker", (m) => setOn(m.on === true));
+  ppm.on("select-parent", () => {
+    const parent = selected && selected.parentElement;
+    if (parent && parent !== doc.documentElement) select(parent, false);
+  });
+  ppm.on("clear-selection", () => {
+    selected = null;
+    outlined = null;
+    draw();
+  });
+}

package/src/services/design/bridge/bridge-pins.ts

@@ -0,0 +1,157 @@
+import type { BridgeApi } from "./bridge-core.ts";
+import type { CommentAnchor } from "../../../shared/design-comment-types.ts";
+
+/**
+ * Where each pinned comment's element is, reported to the parent as `pins-rects`.
+ *
+ * The parent sends the open comments' anchors (`pins-set`); each is resolved here, against
+ * the document as it actually is — by id while the gen still matches, otherwise by text
+ * quote (`ppm.lib.resolveAnchor`). A pin found by quote under the current gen is reported
+ * with its new id and `reanchored: true`, which the parent turns into a request the server
+ * re-checks against the source; nothing is written from here.
+ *
+ * Rects are the elements' viewport boxes, re-sent (rAF-throttled, and only when something
+ * moved) on scroll, resize, element resize and DOM mutation. A mutation also re-resolves,
+ * after a short debounce, the pins whose element is gone or was never found — a page that
+ * renders its content from a script only has the element some time after `ready`.
+ *
+ * Shipped as source, so it may only use what it is handed in `ppm`.
+ */
+export function installPins(ppm: BridgeApi): void {
+  const win = ppm.win as Window & typeof globalThis;
+  const doc = ppm.doc;
+  const MAX_CANDIDATES = 3000;
+  const gen = /^[0-9a-f]{16}$/.test(ppm.boot.gen) ? ppm.boot.gen : null;
+
+  interface Found {
+    el: Element | null;
+    ppmId: number | null;
+    gen: string | null;
+    reanchored: boolean;
+  }
+  let pins: Array<{ id: string; anchor: CommentAnchor }> = [];
+  let found = new Map<string, Found>();
+  let lastSent = "";
+
+  function resolve(onlyMissing: boolean): void {
+    const byTag: Record<string, { els: Element[]; infos: ReturnType<typeof ppm.lib.anchorOf>[] }> = {};
+    const candidates = (tag: string) => {
+      if (byTag[tag]) return byTag[tag]!;
+      const list = doc.getElementsByTagName(tag);
+      const els: Element[] = [];
+      for (let i = 0; i < list.length && els.length < MAX_CANDIDATES; i++) {
+        if (list[i]!.localName.toLowerCase() === tag) els.push(list[i]!);
+      }
+      byTag[tag] = { els, infos: els.map((el) => ppm.lib.anchorOf(el, ppm)) };
+      return byTag[tag]!;
+    };
+    const next = new Map<string, Found>();
+    for (const pin of pins) {
+      const a = pin.anchor;
+      const prev = found.get(pin.id);
+      if (onlyMissing && prev && prev.el && prev.el.isConnected) {
+        next.set(pin.id, prev);
+        continue;
+      }
+      const direct = a.ppmId !== null && a.gen !== null && a.gen === gen ? ppm.byId(a.ppmId) : null;
+      if (direct && direct.localName.toLowerCase() === a.tag) {
+        next.set(pin.id, { el: direct, ppmId: a.ppmId, gen: a.gen, reanchored: false });
+        continue;
+      }
+      const c = candidates(a.tag);
+      const r = ppm.lib.resolveAnchor(a, c.infos, gen, ppm.lib.diceSimilarity);
+      if (r.status === "orphaned") {
+        next.set(pin.id, { el: null, ppmId: a.ppmId, gen: a.gen, reanchored: false });
+        continue;
+      }
+      const info = c.infos[r.index]!;
+      // Only an element with an id, under a known gen, is something the server can check.
+      const movable = info.ppmId !== null && gen !== null && (info.ppmId !== a.ppmId || gen !== a.gen);
+      next.set(pin.id, {
+        el: c.els[r.index]!, ppmId: movable ? info.ppmId : a.ppmId, gen: movable ? gen : a.gen, reanchored: movable,
+      });
+    }
+    found = next;
+    observeElements();
+  }
+
+  function report(): void {
+    const out = pins.map((pin) => {
+      const f = found.get(pin.id);
+      const el = f && f.el && f.el.isConnected ? f.el : null;
+      const r = el ? el.getBoundingClientRect() : null;
+      return {
+        id: pin.id,
+        rect: r ? { x: r.left, y: r.top, w: r.width, h: r.height } : null,
+        ppmId: f ? f.ppmId : pin.anchor.ppmId,
+        gen: f ? f.gen : pin.anchor.gen,
+        reanchored: !!(f && f.reanchored),
+      };
+    });
+    const key = JSON.stringify(out);
+    if (key === lastSent) return;
+    lastSent = key;
+    ppm.post("pins-rects", { pins: out });
+  }
+
+  let reportQueued = false;
+  function reportSoon(): void {
+    if (reportQueued || pins.length === 0) return;
+    reportQueued = true;
+    const run = (): void => {
+      reportQueued = false;
+      report();
+    };
+    if (typeof win.requestAnimationFrame === "function") win.requestAnimationFrame(run);
+    else win.setTimeout(run, 16);
+  }
+
+  let resolveTimer = 0;
+  function resolveMissingSoon(): void {
+    let missing = false;
+    found.forEach((f) => {
+      if (!f.el || !f.el.isConnected) missing = true;
+    });
+    if (!missing || resolveTimer) return;
+    resolveTimer = win.setTimeout(() => {
+      resolveTimer = 0;
+      resolve(true);
+      reportSoon();
+    }, 300);
+  }
+
+  const resizes = typeof win.ResizeObserver === "function" ? new win.ResizeObserver(reportSoon) : null;
+  function observeElements(): void {
+    if (!resizes) return;
+    resizes.disconnect();
+    if (doc.documentElement) resizes.observe(doc.documentElement);
+    found.forEach((f) => {
+      if (f.el) resizes.observe(f.el);
+    });
+  }
+
+  if (typeof win.MutationObserver === "function" && doc.documentElement) {
+    new win.MutationObserver(() => {
+      if (pins.length === 0) return;
+      reportSoon();
+      resolveMissingSoon();
+    }).observe(doc.documentElement, { subtree: true, childList: true, characterData: true, attributes: true });
+  }
+  win.addEventListener("scroll", reportSoon, { capture: true, passive: true });
+  win.addEventListener("resize", reportSoon, { passive: true });
+  win.addEventListener("load", reportSoon);
+
+  ppm.on("pins-set", (m) => {
+    // Validated by the parent before sending; a page script forging this message can only
+    // mislead its own frame, so a malformed entry is just dropped.
+    const list = Array.isArray(m.pins) ? (m.pins as Array<{ id: string; anchor: CommentAnchor }>).slice(0, 500) : [];
+    pins = list.filter((p) => p && typeof p.id === "string" && p.anchor && typeof p.anchor.tag === "string"
+      && p.anchor.quote && typeof p.anchor.quote.exact === "string");
+    found = new Map();
+    // The parent may have forgotten what it was told; always answer a new set.
+    lastSent = "";
+    resolve(false);
+    if (pins.length === 0) ppm.post("pins-rects", { pins: [] });
+    else reportSoon();
+  });
+}

package/src/services/design/bridge/bridge-script.ts

@@ -0,0 +1,104 @@
+import { installBridgeCore, type BridgeApi, type BridgeLib } from "./bridge-core.ts";
+import { installNavGuard } from "./bridge-nav-guard.ts";
+import { installPicker } from "./bridge-picker.ts";
+import { installPins } from "./bridge-pins.ts";
+import { installTweaks } from "./bridge-tweaks.ts";
+import { installTransform } from "./bridge-transform.ts";
+import { anchorOf, cssPathOf, describeElement, domTreeAccess, elementQuote } from "./bridge-element-info.ts";
+import { diceSimilarity, resolveAnchor } from "./bridge-anchor-resolve.ts";
+import { createPickerOverlay } from "./bridge-picker-overlay.ts";
+import { applyDrag, formatPx, parseTranslate, zoneAt } from "./bridge-transform-math.ts";
+import { createTransformOverlay } from "./bridge-transform-overlay.ts";
+import { createTransformStyle } from "./bridge-transform-style.ts";
+import { installSlidesExtract } from "./bridge-extract-slides.ts";
+import { extractTextRuns, mergeTextRuns, parseCssColor } from "./bridge-extract-text.ts";
+import { blockItems, cssRotation } from "./bridge-extract-blocks.ts";
+import { imageDataUrl } from "./bridge-extract-images.ts";
+import { checkLabel, gridImplicitFindings } from "./bridge-layout-grid.ts";
+import { boxFindings } from "./bridge-layout-boxes.ts";
+import { captureScreenshot } from "./bridge-layout-screenshot.ts";
+import { installLayoutCheck } from "./bridge-layout-check.ts";
+
+/**
+ * The bridge script injected as the first child of a design document's `<head>`.
+ *
+ * Each feature is a real, typed, tested function shipped as its own source through
+ * `toString()` (Bun hands back the type-stripped JavaScript), rather than a second copy
+ * kept inside a template literal. Features are called through an array, never by name, so
+ * a bundler renaming a function cannot break the assembly; each one receives everything
+ * it needs in `ppm`. Later features append themselves to {@link BRIDGE_FEATURES}.
+ *
+ * Shared helpers travel the same way as {@link BRIDGE_LIB}, installed as `ppm.lib` under
+ * the string keys written here, before any feature runs.
+ */
+
+export type BridgeFeature = (ppm: BridgeApi) => void;
+
+export const BRIDGE_LIB: BridgeLib = {
+  elementQuote, domTreeAccess, cssPathOf, anchorOf, describeElement, diceSimilarity, resolveAnchor, createPickerOverlay,
+  parseTranslate, formatPx, applyDrag, zoneAt, createTransformOverlay, createTransformStyle,
+  parseCssColor, mergeTextRuns, extractTextRuns, cssRotation, blockItems, imageDataUrl,
+  checkLabel, gridImplicitFindings, boxFindings, captureScreenshot,
+};
+
+export const BRIDGE_FEATURES: readonly BridgeFeature[] = [
+  // First of all: every event on the move/resize handles is consumed here, before the picker
+  // would select the handles themselves and before the page sees a click.
+  installTransform,
+  // Ahead of the nav guard: while picking, a click on a link selects it and must not also
+  // be reported as a blocked navigation.
+  installPicker,
+  installPins,
+  installNavGuard,
+  installTweaks,
+  installSlidesExtract,
+  installLayoutCheck,
+];
+
+export function assembleBridge(features: readonly BridgeFeature[], lib: Partial<BridgeLib> = BRIDGE_LIB): string {
+  const list = features.map((feature) => `(${feature.toString()})`).join(",\n");
+  const helpers = Object.entries(lib)
+    .map(([name, fn]) => `${JSON.stringify(name)}: (${(fn as () => void).toString()})`)
+    .join(",\n");
+  return `(function (window) {
+"use strict";
+var ppm = (${installBridgeCore.toString()})(window);
+var lib = {${helpers}};
+for (var name in lib) ppm.lib[name] = lib[name];
+var features = [${list}];
+for (var i = 0; i < features.length; i++) {
+  try { features[i](ppm); } catch (e) { ppm.issue("error", "bridge feature failed: " + (e && e.message)); }
+}
+ppm.start();
+})(window);`;
+}
+
+export const BRIDGE_JS = assembleBridge(BRIDGE_FEATURES);
+
+// Inside a <script> element the HTML tokenizer ends the element at the first `</script`,
+// and `<!--` / `<script` switch it into escaped states. Fail at startup, not in a browser.
+if (/<\/script|<!--|<script/i.test(BRIDGE_JS)) {
+  throw new Error("The design bridge contains a sequence that would break out of its <script> element");
+}
+
+const escapeAttr = (value: string): string =>
+  value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+export interface BridgeTagInput {
+  nonce: string | null;
+  gen: string;
+  cssGens: Record<string, string>;
+  /** The HTML file's path relative to the design folder. */
+  file: string;
+  instrumented: boolean;
+}
+
+/**
+ * The `<script>` element. Per-load values travel as attributes the core reads and removes,
+ * so the script body is one constant and nothing request-derived is ever inside it.
+ */
+export function bridgeTag(input: BridgeTagInput): string {
+  return `<script data-ppm-bridge="1" data-nonce="${escapeAttr(input.nonce ?? "")}" data-gen="${escapeAttr(input.gen)}"`
+    + ` data-css-gens="${escapeAttr(JSON.stringify(input.cssGens))}" data-file="${escapeAttr(input.file)}"`
+    + ` data-instrumented="${input.instrumented ? "1" : "0"}">${BRIDGE_JS}</script>`;
+}