@agent-native/core 0.92.6 → 0.92.8

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -5,8 +5,21 @@ import {
   getDraftGeometryFromPoints,
 } from "@shared/canvas-math";
 import { ensureCodeLayerNodeIdsInHtml } from "@shared/code-layer";
+import {
+  appendPenNode,
+  clonePenPath,
+  closePenPath,
+  constrainPointTo45Degrees,
+  createCornerNode,
+  createSmoothNode,
+  isPenCloseTarget,
+  serializePenPath,
+  type PenPath,
+  type PenPoint,
+} from "@shared/pen-path";
 import { IconPlugConnectedX, IconRefresh } from "@tabler/icons-react";
 import { useRef, useEffect, useCallback, useMemo, useState } from "react";
+import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
 // NOTE: This wires up the NEW shared visual-editor DrawOverlay + comment-pin
@@ -23,7 +36,6 @@ import { cn } from "@/lib/utils";
 
 import { editorChromeBridgeScript } from "../../../.generated/bridge/editor-chrome.generated";
 import { embeddedWheelBridgeScript } from "../../../.generated/bridge/embedded-wheel.generated";
-import { hitTestBridgeScript } from "../../../.generated/bridge/hit-test.generated";
 import { motionPreviewBridgeScript } from "../../../.generated/bridge/motion-preview.generated";
 import { navBridgeScript } from "../../../.generated/bridge/nav.generated";
 import { shaderFillPreviewBridgeScript } from "../../../.generated/bridge/shader-fill-preview.generated";
@@ -31,7 +43,50 @@ import { shaderRuntimeBridgeScript } from "../../../.generated/bridge/shader-run
 import { tweakBridgeScript } from "../../../.generated/bridge/tweak.generated";
 import { zoomBridgeScript } from "../../../.generated/bridge/zoom.generated";
 import { isTrustedCanvasBridgeMessage } from "./bridge-security";
+import { submitDesignAnnotations } from "./design-canvas/annotation-submit";
+import {
+  getScreenContentPointFromClient,
+  getZoomToCursorScrollDelta,
+} from "./design-canvas/coordinate-transforms";
+import {
+  collapseDoubleClickPenAnchor,
+  type CreatePrimitiveSpec,
+  type CreationTool,
+} from "./design-canvas/creation";
+import { isElementInfoPayload } from "./design-canvas/element-payload";
+import {
+  embeddedContentOffsetStyle,
+  getEmbeddedFrameBackgroundStyle,
+  getEmbeddedFrameDocumentContent,
+  getEmbeddedIframeBackgroundColor,
+} from "./design-canvas/embedded-frame";
+import {
+  getDesignCanvasIframeSandbox,
+  getSnapshotRetryDelayMs,
+  resolveLiveEditPreviewUrl,
+  sanitizeLocalhostSourceSnapshotHtml,
+  shouldFetchExternalSourceSnapshot,
+  shouldUseIframeLoadReadyFallback,
+} from "./design-canvas/external-preview";
+import { isOsFileDragEvent } from "./design-canvas/file-drop";
+import { LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT } from "./design-canvas/hit-test";
+import type {
+  IframeContextMenuPayload,
+  IframeFigmaClipboardPastePayload,
+  IframeHotkeyPayload,
+} from "./design-canvas/iframe-events";
+import {
+  forwardEmbeddedCanvasPanMessage,
+  type EmbeddedCanvasPanSession,
+} from "./design-canvas/iframe-pan";
+import type { MotionTrackWire } from "./design-canvas/motion-types";
+import {
+  PENDING_TEXT_EDIT_TIMEOUT_MS,
+  routePendingTextEditKey,
+  schedulePendingTextEditActivation,
+} from "./design-canvas/pending-text-edit";
 import { DeviceFrame } from "./DeviceFrame";
+import { shapeClosingHandles } from "./multi-screen/draft-primitives";
 import type {
   ElementInfo,
   ElementSelectionIntent,
@@ -77,25 +132,6 @@ function isAllowedFusionOrigin(
   return host === "builder.io" || host.endsWith(".builder.io");
 }
 
-/**
- * Wire shape for a single motion track sent via the `motion-load-tracks`
- * postMessage. Matches the serialisable subset of `MotionTrack` from
- * `shared/motion-timeline.ts` without requiring an import at the UI layer.
- */
-export interface MotionTrackWire {
-  targetNodeId: string;
-  property: string;
-  /**
-   * Keyframes normalised to the TRACK's own span; `ease` accepts CSS timing
-   * functions plus `spring(bounce[, settle])` tokens and `linear(...)` lists.
-   */
-  keyframes: Array<{ t: number; value: string; ease?: string }>;
-  /** Track start offset within the timeline, ms (staggering). */
-  delayMs?: number;
-  /** Per-track animation span, ms. Omitted = whole timeline. */
-  durationMs?: number;
-}
-
 /**
  * Motion-preview bridge. Injected alongside the other bridge scripts so the
  * MotionDock's scrubbing preview works in ALL editor modes without writing
@@ -192,59 +228,6 @@ ${navBridgeScript}
 </script>
 `;
 
-/**
- * Lightweight hit-test bridge: injected into every screen srcdoc iframe so
- * MultiScreenCanvas can ask "what container is under this point?" during a
- * cross-screen drag without needing to synthesise DOM events.
- *
- * Protocol (parent → iframe via postMessage):
- *   { type: 'agent-native:hit-test', correlationId: string, x: number, y: number }
- *   where x/y are in this iframe's viewport coordinate space.
- *   When preview is true, the iframe also renders its local insertion guide.
- *   { type: 'agent-native:hit-test-preview-clear' } hides that guide.
- *
- * Reply (iframe → window.parent):
- *   { type: 'agent-native:hit-test-result', correlationId: string,
- *     anchorNodeId: string, placement: 'before'|'after'|'inside',
- *     axis: 'x'|'y',
- *     anchorRect: { left: number, top: number, width: number, height: number } }
- *
- * Reads DOM only — no mutations, no event interception. The container-drop and
- * placement logic is intentionally kept in sync with the corresponding helpers
- * inside editor-chrome.bridge.ts (search for "// keep in sync with
- * hit-test.bridge.ts" comments there).
- *
- * Source: app/components/design/bridge/hit-test.bridge.ts
- * Compiled: .generated/bridge/hit-test.generated.ts (run bridge/codegen.ts to update)
- */
-export const LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT = `
-<script data-agent-native-hit-test-bridge>
-${hitTestBridgeScript}
-</script>
-`;
-
-/**
- * Append the LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT into a complete HTML string.
- * Injects before </body> when present, before </html> as a fallback, or appends
- * at the end. This is the seam MultiScreenCanvas uses to add the hit-test
- * responder to each screen srcdoc without rebuilding the entire document.
- */
-export function appendHitTestResponder(html: string): string {
-  if (html.includes("</body>")) {
-    return html.replace(
-      "</body>", // i18n-ignore generated iframe HTML marker
-      LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT + "</body>", // i18n-ignore generated iframe HTML injection
-    );
-  }
-  if (html.includes("</html>")) {
-    return html.replace(
-      "</html>", // i18n-ignore generated iframe HTML marker
-      LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT + "</html>", // i18n-ignore generated iframe HTML injection
-    );
-  }
-  return html + LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT;
-}
-
 const EDITOR_BRIDGE_VAR_NAMES = [
   "--design-editor-accent-color",
   "--design-editor-accent-hover-color",
@@ -305,8 +288,10 @@ interface DesignCanvasProps {
   /**
    * The runtime source tier for this canvas.
    *
-   * - `"inline"` (default) — HTML/Alpine `srcdoc` iframe; same-origin null
-   *   origin; all bridge scripts injected by DesignCanvas.
+   * - `"inline"` (default) — HTML/Alpine `srcdoc` iframe; all bridge scripts
+   *   injected by DesignCanvas. Read-only frames get an opaque origin;
+   *   editable frames temporarily retain the parent origin for the live-DOM
+   *   editor features documented by getDesignCanvasIframeSandbox.
    * - `"localhost"` — `src=devServerUrl`; dev server is same-origin in most
    *   setups; bridge trust: origin must match parent or be "null".
    * - `"fusion"` — `src=builderHostedUrl`; cross-origin Builder-hosted app;
@@ -351,7 +336,9 @@ interface DesignCanvasProps {
    * For `"inline"` and `"localhost"` sources this prop is ignored.
    */
   fusionUrl?: string;
-  bridgeToken?: string;
+  /** Read-only localhost bridge credential. Filesystem write tokens never enter
+   * this browser component. */
+  previewToken?: string;
   zoom: number;
   onZoomChange?: (zoom: number) => void;
   deviceFrame: DeviceFrameType;
@@ -680,138 +667,6 @@ interface DesignCanvasProps {
   spacePanActive?: boolean;
 }
 
-/** Creation tools supported by the single-screen click-to-place overlay. */
-export type CreationTool =
-  | "rectangle"
-  | "ellipse"
-  | "line"
-  | "arrow"
-  | "text"
-  | "pen"
-  // Figma parity: the frame tool (F/A) used inside a focused screen places a
-  // bare container <div> (a nested "frame") instead of forcing a jump out to
-  // overview to draw a new screen.
-  | "frame";
-
-/**
- * Geometry payload emitted by the single-screen creation overlay. Coordinates
- * are always in screen-content space (see `activeCreationTool` doc above).
- *
- * - `rect` is present for rectangle/ellipse/text (a click uses a sensible
- *   default size; a drag uses the dragged bounds via
- *   `getDraftGeometryFromPoints`, matching MultiScreenCanvas).
- * - `points` is present for line/arrow (always exactly 2 points) and for a
- *   pen click (a single start point — see the deferred multi-click pen note
- *   on the overlay component itself).
- * - `fromClick` distinguishes a negligible-movement click (true) from a
- *   drag past the movement threshold (false), mirroring MultiScreenCanvas's
- *   own click-vs-drag draft creation semantics.
- */
-export interface CreatePrimitiveSpec {
-  tool: CreationTool;
-  rect?: { x: number; y: number; width: number; height: number };
-  points?: Array<{ x: number; y: number }>;
-  fromClick: boolean;
-}
-
-/**
- * Converts a pointer position in viewport (client) coordinates into
- * screen-content coordinates — the screen's own pixel coordinate system, as
- * used by `getDraftGeometryFromPoints` / `draftPrimitiveToInsert` in
- * MultiScreenCanvas.
- *
- * The iframe's rendered rect (`getBoundingClientRect()`) already reflects any
- * outer zoom `transform: scale(...)` wrapper, while `iframe.clientWidth` /
- * `iframe.clientHeight` are the raw (unscaled) layout size that equals the
- * screen's own content pixel dimensions. Dividing out that ratio undoes the
- * zoom scale, matching the scaleX/scaleY convention already used by the
- * `element-contextmenu` bridge handler below.
- */
-export function getScreenContentPointFromClient(
-  clientX: number,
-  clientY: number,
-  iframeRect: { left: number; top: number; width: number; height: number },
-  iframeContentSize: { width: number; height: number },
-): { x: number; y: number } {
-  const scaleX =
-    iframeContentSize.width > 0
-      ? iframeRect.width / iframeContentSize.width
-      : 1;
-  const scaleY =
-    iframeContentSize.height > 0
-      ? iframeRect.height / iframeContentSize.height
-      : 1;
-  return {
-    x: (clientX - iframeRect.left) / (scaleX || 1),
-    y: (clientY - iframeRect.top) / (scaleY || 1),
-  };
-}
-
-/**
- * Computes the scroll-container delta needed to keep a given viewport
- * (client) point anchored to the same content underneath it while zooming.
- *
- * This is the cursor-anchor math used by the `pinch-zoom-wheel` bridge
- * handler (forwarded from inside the iframe, since wheel events don't bubble
- * out of iframes — see `zoom.bridge.ts`) to mirror `usePinchZoom`'s own
- * zoom-to-cursor behavior for gestures that occur over the iframe itself.
- *
- * IMPORTANT — this math is only correct when the scaled layer's
- * `transform-origin` is `top left` (or equivalent), so that the layer's own
- * top-left corner is a fixed point in scroll-content space regardless of
- * zoom. If the scaled layer is instead centered via `transform-origin:
- * center center` plus flex/grid centering, the *painted* box re-centers
- * around the container's center on every zoom change — the flex-centering
- * repositions the *layout* box so its center lands at the container's
- * center, and `transform-origin: center` then scales around that already-
- * centered point. That is a well-defined anchor too, but it is NOT the one
- * this function (or usePinchZoom) computes, so cursor-following would drift.
- * See the long comment on the "none"-mode zoom layer in the component render
- * for how DesignCanvas keeps this invariant true while still looking
- * centered at rest.
- *
- * @param anchorClient The viewport point to keep stationary (e.g. cursor
- *   position converted from iframe-document space to viewport space).
- * @param containerRect The scroll container's `getBoundingClientRect()`.
- * @param scrollOffset The scroll container's current `{ scrollLeft,
- *   scrollTop }`.
- * @param zoomRatio `nextZoom / currentZoom` — how much the zoom is about to
- *   change by by (>1 zooming in, <1 zooming out).
- */
-export function getZoomToCursorScrollDelta(
-  anchorClient: { x: number; y: number },
-  containerRect: { left: number; top: number },
-  scrollOffset: { scrollLeft: number; scrollTop: number },
-  zoomRatio: number,
-): { dx: number; dy: number } {
-  const cx = anchorClient.x - containerRect.left + scrollOffset.scrollLeft;
-  const cy = anchorClient.y - containerRect.top + scrollOffset.scrollTop;
-  return {
-    dx: cx * (zoomRatio - 1),
-    dy: cy * (zoomRatio - 1),
-  };
-}
-
-/**
- * True when a drag event is carrying native OS files (e.g. dragged in from
- * Finder/Explorer) rather than an internal HTML5 DOM drag (element reorder,
- * the extensions-panel native-asset drag, etc). A real OS file drag always
- * includes the "Files" type in `dataTransfer.types` — reliably present during
- * dragenter/dragover even before drop, when `dataTransfer.files` itself is
- * empty for security reasons — so this is the correct check to gate
- * preventDefault()/overlay logic on, not `files.length`.
- */
-export function isOsFileDragEvent(event: {
-  dataTransfer: { types: readonly string[] | DOMStringList } | null;
-}): boolean {
-  const types = event.dataTransfer?.types;
-  if (!types) return false;
-  for (let i = 0; i < types.length; i += 1) {
-    if (types[i] === "Files") return true;
-  }
-  return false;
-}
-
 function getExternalPreviewUrl(content: string): string | null {
   const trimmed = content.trim();
   if (!/^https?:\/\//i.test(trimmed)) return null;
@@ -824,60 +679,12 @@ function getExternalPreviewUrl(content: string): string | null {
   }
 }
 
-function escapeHtmlAttribute(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/"/g, "&quot;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}
-
-function addSnapshotBaseHref(html: string, href: string): string {
-  if (!html.trim()) return html;
-  if (/<base\b/i.test(html)) return html;
-  const baseTag = `<base href="${escapeHtmlAttribute(href)}">`;
-  if (/<head\b[^>]*>/i.test(html)) {
-    return html.replace(/<head\b[^>]*>/i, (match) => `${match}${baseTag}`);
-  }
-  if (/<html\b[^>]*>/i.test(html)) {
-    return html.replace(
-      /<html\b[^>]*>/i,
-      (match) => `${match}<head>${baseTag}</head>`,
-    );
-  }
-  return `<!DOCTYPE html><html><head>${baseTag}<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head><body>${html}</body></html>`;
-}
-
-function prepareStaticSnapshotHtml(html: string, href: string): string {
-  const withBase = addSnapshotBaseHref(html, href);
-  if (typeof DOMParser === "undefined") {
-    return withBase.replace(/<script\b[^>]*>.*?<\/script>/gis, "");
-  }
-
-  const document = new DOMParser().parseFromString(withBase, "text/html");
-  document.querySelectorAll("script").forEach((script) => script.remove());
-  return `<!DOCTYPE html>${document.documentElement.outerHTML}`;
-}
-
 function snapshotEndpointUrl(bridgeUrl: string, previewUrl: string): string {
   const endpoint = new URL("/snapshot", bridgeUrl);
   endpoint.searchParams.set("url", previewUrl);
   return endpoint.toString();
 }
 
-export function liveEditEndpointUrl(
-  bridgeUrl: string,
-  previewUrl: string,
-  options?: { includeEditorBridge?: boolean },
-): string {
-  const endpoint = new URL("/live-edit", bridgeUrl);
-  endpoint.searchParams.set("url", previewUrl);
-  if (options?.includeEditorBridge === false) {
-    endpoint.searchParams.set("bridge", "0");
-  }
-  return endpoint.toString();
-}
-
 function originFromUrl(value: string | undefined): string | null {
   if (!value) return null;
   try {
@@ -920,215 +727,6 @@ function contentHash(value: string): string {
   return `${value.length}:${hash >>> 0}`;
 }
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
-function isFiniteRect(value: unknown): value is ElementInfo["boundingRect"] {
-  if (!isPlainRecord(value)) return false;
-  return (
-    Number.isFinite(value.x) &&
-    Number.isFinite(value.y) &&
-    Number.isFinite(value.width) &&
-    Number.isFinite(value.height)
-  );
-}
-
-export function isElementInfoPayload(value: unknown): value is ElementInfo {
-  if (!isPlainRecord(value)) return false;
-  return (
-    typeof value.tagName === "string" &&
-    Array.isArray(value.classes) &&
-    isPlainRecord(value.computedStyles) &&
-    isFiniteRect(value.boundingRect) &&
-    typeof value.isFlexChild === "boolean" &&
-    typeof value.isFlexContainer === "boolean"
-  );
-}
-
-/**
- * Exponential backoff delay (ms) for the localhost bridge snapshot auto-retry
- * loop, keyed by the zero-based retry attempt number (0 = first retry after
- * the initial failed fetch). Doubles each attempt starting at 1.5s, capped at
- * ~15s so a genuinely-down dev server settles into a slow, low-noise poll
- * instead of hammering the bridge every 1.5s forever.
- */
-const SNAPSHOT_RETRY_BASE_DELAY_MS = 1500;
-const SNAPSHOT_RETRY_MAX_DELAY_MS = 15000;
-export function getSnapshotRetryDelayMs(attempt: number): number {
-  const safeAttempt = Number.isFinite(attempt) ? Math.max(0, attempt) : 0;
-  const delay = SNAPSHOT_RETRY_BASE_DELAY_MS * 2 ** safeAttempt;
-  return Math.min(SNAPSHOT_RETRY_MAX_DELAY_MS, delay);
-}
-
-const TRANSPARENT_EMBEDDED_FRAME_STYLE =
-  "<style data-agent-native-transparent-frame>html,body{background:transparent!important;}body{background-color:transparent!important;}</style>";
-
-function embeddedFrameBackgroundStyle(background: string | undefined): string {
-  const trimmed = background?.trim();
-  if (!trimmed || /[;{}<>]/.test(trimmed)) return "";
-  return `<style data-agent-native-frame-background>html,body{background:${trimmed}!important;}body{background-color:${trimmed}!important;}</style>`;
-}
-
-export function getEmbeddedFrameBackgroundStyle(args: {
-  embeddedFrameBackground?: string;
-  transparentBackground?: boolean;
-}): string {
-  return args.transparentBackground
-    ? TRANSPARENT_EMBEDDED_FRAME_STYLE
-    : embeddedFrameBackgroundStyle(args.embeddedFrameBackground);
-}
-
-export function getEmbeddedIframeBackgroundColor(args: {
-  embeddedFrameBackground?: string;
-  transparentBackground?: boolean;
-}): string {
-  return args.transparentBackground
-    ? "transparent"
-    : (args.embeddedFrameBackground ?? "transparent");
-}
-
-/**
- * CSS rule that shifts embedded-frame (board) content so board-coordinate
- * (0,0) lands at the center of the board iframe's oversized surface.
- *
- * The selector is deliberately scoped to DIRECT `<body>` children only.
- * `translate` composes per element, so a blanket
- * `[data-agent-native-node-id]{translate:…}` rule shifted every NESTED
- * node-id-bearing descendant by the surface offset AGAIN (+65536px per
- * nesting level) — any board child nested inside another board primitive
- * rendered tens of thousands of px outside its parent (i.e. visually
- * vanished) even when its persisted parent-relative left/top were perfectly
- * correct, and every rect-based coordinate computation on nested board
- * content was poisoned by the extra offset.
- *
- * Scoping (rather than wrapping content in a single offset container) is the
- * robust fix here because board elements are DOCUMENTED direct `<body>`
- * children (see shared/board-file.ts module doc + emptyBoardHtml): every
- * creation path appends at body level (appendCanvasPrimitiveToHtml,
- * boardObjectEntryToHtmlFragment, moveNodeBetweenDocuments' body-append),
- * and several consumers key on that structure with `body > …` selectors
- * (BOARD_SURFACE_RENDER_STYLE) and depth-1 walks
- * (backfillBoardPrimitiveMarkers, getBoardContentLayerSignature). A wrapper
- * element would silently break all of those structural contracts.
- *
- * With this rule, the offset applies exactly once — to top-level board
- * elements — and nested children position purely via parent-relative
- * left/top inside their (absolutely positioned) parent, like any normal
- * CSS containing-block hierarchy.
- */
-function embeddedContentOffsetStyle(x: number, y: number): string {
-  if (x === 0 && y === 0) return "";
-  return `<style data-agent-native-content-offset>body > [data-agent-native-node-id]{translate:${Math.round(x)}px ${Math.round(y)}px;}</style>`;
-}
-
-function injectEmbeddedFrameStyle(content: string, style: string): string {
-  if (!style) return content;
-  if (/<\/head>/i.test(content)) {
-    return content.replace(/<\/head>/i, `${style}</head>`);
-  }
-  if (/<body\b/i.test(content)) {
-    return content.replace(/<body\b/i, `${style}<body`);
-  }
-  return `${style}${content}`;
-}
-
-export function getEmbeddedFrameDocumentContent(args: {
-  content: string;
-  embeddedFrameBackground?: string;
-  transparentBackground?: boolean;
-  contentOffsetX?: number;
-  contentOffsetY?: number;
-}): string {
-  const frameStyle = [
-    getEmbeddedFrameBackgroundStyle({
-      embeddedFrameBackground: args.embeddedFrameBackground,
-      transparentBackground: args.transparentBackground,
-    }),
-    embeddedContentOffsetStyle(
-      args.contentOffsetX ?? 0,
-      args.contentOffsetY ?? 0,
-    ),
-  ].join("");
-  return injectEmbeddedFrameStyle(args.content, frameStyle);
-}
-
-export interface IframeHotkeyPayload {
-  key: string;
-  code: string;
-  metaKey: boolean;
-  ctrlKey: boolean;
-  shiftKey: boolean;
-  altKey: boolean;
-  repeat: boolean;
-}
-
-export interface IframeFigmaClipboardPastePayload {
-  content: string;
-}
-
-export interface IframeContextMenuPayload {
-  clientX: number;
-  clientY: number;
-  viewportClientX?: number;
-  viewportClientY?: number;
-  info?: ElementInfo | null;
-}
-
-/**
- * Creation-race keystroke routing: after the host calls `beginTextEdit(nodeId)`
- * for a JUST-created text element, there is a window (persist round-trip +
- * bridge activation) where the browser focus still sits on the HOST document.
- * Keystrokes typed in that window used to fall into host keyboard shortcuts —
- * letters switched tools, digits zoomed, and Delete/Backspace DELETED the
- * selected layer/screen — while the characters themselves were silently lost.
- *
- * While a text edit is pending, every host keydown is routed through this
- * pure helper:
- * - printable characters are BUFFERED (replayed into the editable once the
- *   bridge reports the session active) and swallowed,
- * - Backspace edits the buffer, Delete/Enter/Tab/arrows are swallowed so they
- *   can never reach host layer-deletion/navigation,
- * - Escape clears the pending buffer (user aborted) and is swallowed,
- * - IME composition and Cmd/Ctrl chords (undo!) pass through untouched.
- *
- * Exported for unit tests (DesignCanvas.pending-text-edit.test.ts).
- */
-export type PendingTextEditKeyAction =
-  | { action: "buffer"; char: string }
-  | { action: "drop-last" }
-  | { action: "swallow" }
-  | { action: "clear-and-swallow" }
-  | { action: "pass" };
-
-export function routePendingTextEditKey(e: {
-  key: string;
-  metaKey?: boolean;
-  ctrlKey?: boolean;
-  altKey?: boolean;
-  isComposing?: boolean;
-}): PendingTextEditKeyAction {
-  if (e.isComposing) return { action: "pass" };
-  if (e.metaKey || e.ctrlKey) return { action: "pass" };
-  if (e.key === "Escape") return { action: "clear-and-swallow" };
-  if (e.key === "Backspace") return { action: "drop-last" };
-  if (
-    e.key === "Delete" ||
-    e.key === "Enter" ||
-    e.key === "Tab" ||
-    e.key.startsWith("Arrow")
-  ) {
-    return { action: "swallow" };
-  }
-  if (e.key.length === 1) return { action: "buffer", char: e.key };
-  return { action: "pass" };
-}
-
-/** How long a pending text edit may wait for bridge activation before the
- * keystroke routing above stands down (matches the bridge's own ~2s
- * begin-text-edit retry window, plus round-trip slack). */
-export const PENDING_TEXT_EDIT_TIMEOUT_MS = 3000;
-
 export function DesignCanvas({
   content,
   contentKey,
@@ -1137,7 +735,7 @@ export function DesignCanvas({
   externalSnapshotHtml,
   onExternalContentSnapshot,
   fusionUrl,
-  bridgeToken,
+  previewToken,
   zoom,
   onZoomChange,
   deviceFrame,
@@ -1209,6 +807,9 @@ export function DesignCanvas({
 }: DesignCanvasProps) {
   const t = useT();
   const iframeRef = useRef<HTMLIFrameElement>(null);
+  const embeddedCanvasPanSessionRef = useRef<EmbeddedCanvasPanSession | null>(
+    null,
+  );
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const zoomLayerRef = useRef<HTMLDivElement>(null);
   const zoomRef = useRef(zoom);
@@ -1246,6 +847,7 @@ export function DesignCanvas({
   // fallback for older/interact-mode documents that never inject the chrome
   // bridge and thus never post ready) and flush in order.
   const bridgeReadyRef = useRef(false);
+  const previousIframeDocumentIdentityRef = useRef<string | null>(null);
   const pendingOneShotMessagesRef = useRef<unknown[]>([]);
   const flushPendingOneShotMessages = useCallback(() => {
     const iframe = iframeRef.current;
@@ -1331,24 +933,34 @@ export function DesignCanvas({
       }),
     [boardSurface, contentKey, editMode, readOnly, screenId],
   );
-  const embeddedWheelBridgeForCurrentState = useMemo(
+  const embeddedGestureBridgeForCurrentState = useMemo(
     () =>
       EMBEDDED_WHEEL_BRIDGE_SCRIPT.replace(
         "__EMBEDDED_WHEEL_FORWARDING_ENABLED__",
         isEmbeddedFrame ? "true" : "false",
+      ).replace(
+        "__EMBEDDED_SPACE_KEY_FORWARDING_ENABLED__",
+        interactMode || readOnly ? "true" : "false",
       ),
-    [isEmbeddedFrame],
+    [interactMode, isEmbeddedFrame, readOnly],
   );
+  const includeLiveEditEditorChrome = !interactMode && !readOnly;
   const liveEditBridgeScript = useMemo(
     () =>
-      MOTION_PREVIEW_BRIDGE_SCRIPT +
-      SHADER_FILL_PREVIEW_BRIDGE_SCRIPT +
-      TWEAK_BRIDGE_SCRIPT +
-      ZOOM_BRIDGE_SCRIPT +
-      LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT +
-      embeddedWheelBridgeForCurrentState +
+      includeLiveEditEditorChrome
+        ? MOTION_PREVIEW_BRIDGE_SCRIPT +
+          SHADER_FILL_PREVIEW_BRIDGE_SCRIPT +
+          TWEAK_BRIDGE_SCRIPT +
+          ZOOM_BRIDGE_SCRIPT +
+          LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT +
+          embeddedGestureBridgeForCurrentState +
+          editorChromeBridgeForCurrentState
+        : embeddedGestureBridgeForCurrentState,
+    [
       editorChromeBridgeForCurrentState,
-    [editorChromeBridgeForCurrentState, embeddedWheelBridgeForCurrentState],
+      embeddedGestureBridgeForCurrentState,
+      includeLiveEditEditorChrome,
+    ],
   );
   const liveEditBridgeKey = useMemo(
     () => contentHash(liveEditBridgeScript),
@@ -1356,38 +968,52 @@ export function DesignCanvas({
   );
   const hasLiveEditExternalFrame =
     sourceType === "localhost" && Boolean(bridgeUrl && rawExternalPreviewUrl);
-  const usesLiveEditEditorBridge =
+  const hasAuthenticatedLiveEditExternalFrame =
+    hasLiveEditExternalFrame && Boolean(previewToken);
+  const usesLiveEditInjectedBridge =
     sourceType === "localhost" &&
-    Boolean(bridgeUrl && rawExternalPreviewUrl) &&
-    !interactMode &&
-    !readOnly;
+    Boolean(bridgeUrl && previewToken && rawExternalPreviewUrl);
+  const usesLiveEditEditorBridge =
+    usesLiveEditInjectedBridge && includeLiveEditEditorChrome;
   const liveEditBridgeRegistered =
-    usesLiveEditEditorBridge &&
+    usesLiveEditInjectedBridge &&
     registeredLiveEditBridgeKey === liveEditBridgeKey;
-  const requiresEditableExternalSnapshot = false;
-  const liveEditExternalPreviewUrl =
-    hasLiveEditExternalFrame &&
-    bridgeUrl &&
-    rawExternalPreviewUrl &&
-    interactMode
-      ? liveEditEndpointUrl(bridgeUrl, rawExternalPreviewUrl, {
-          includeEditorBridge: false,
-        })
-      : liveEditBridgeRegistered && bridgeUrl && rawExternalPreviewUrl
-        ? liveEditEndpointUrl(bridgeUrl, rawExternalPreviewUrl)
-        : null;
+  // The live iframe and the editable source model are deliberately separate:
+  // render exactly one authenticated /live-edit document while fetching
+  // /snapshot in parallel so DesignEditor patches real HTML rather than the
+  // persisted URL string. The snapshot never replaces the live iframe.
+  const requiresExternalSourceSnapshot = shouldFetchExternalSourceSnapshot({
+    sourceType,
+    bridgeUrl,
+    previewToken,
+    previewUrl: rawExternalPreviewUrl,
+    hasSnapshotConsumer: Boolean(onExternalContentSnapshot),
+  });
+  const liveEditExternalPreviewUrl = resolveLiveEditPreviewUrl({
+    sourceType,
+    bridgeUrl,
+    previewToken,
+    previewUrl: rawExternalPreviewUrl,
+    bridgeKey: liveEditBridgeKey,
+    registeredBridgeKey: registeredLiveEditBridgeKey,
+  });
   const iframeRenderContent =
-    activeExternalSnapshotHtml ??
-    (requiresEditableExternalSnapshot ? "" : renderedContent);
+    !hasAuthenticatedLiveEditExternalFrame && activeExternalSnapshotHtml
+      ? activeExternalSnapshotHtml
+      : renderedContent;
   const externalPreviewUrl =
     liveEditExternalPreviewUrl ??
-    (activeExternalSnapshotHtml || requiresEditableExternalSnapshot
+    (hasLiveEditExternalFrame
       ? null
-      : rawExternalPreviewUrl);
-  const waitingForEditableExternalSnapshot =
-    requiresEditableExternalSnapshot && !activeExternalSnapshotHtml;
+      : activeExternalSnapshotHtml
+        ? null
+        : rawExternalPreviewUrl);
+  // Source hydration is parallel and must never block or replace the one live
+  // iframe. Apply-to-source remains guarded until the callback has populated
+  // DesignEditor's source snapshot.
+  const waitingForEditableExternalSnapshot = false;
   const waitingForLiveEditBridge =
-    usesLiveEditEditorBridge && !liveEditBridgeRegistered;
+    usesLiveEditInjectedBridge && !liveEditBridgeRegistered;
   zoomRef.current = zoom;
   runtimeReplacementContentRef.current = runtimeReplacementContent;
   runtimeReplacementKeyRef.current = runtimeReplacementKey;
@@ -1400,7 +1026,7 @@ export function DesignCanvas({
   // it gets injected into the proxied preview. Re-runs only when the script
   // content (liveEditBridgeKey) or the bridge target changes.
   useEffect(() => {
-    if (!usesLiveEditEditorBridge || !bridgeUrl) {
+    if (!usesLiveEditInjectedBridge || !bridgeUrl || !previewToken) {
       setRegisteredLiveEditBridgeKey(null);
       return;
     }
@@ -1415,9 +1041,12 @@ export function DesignCanvas({
           method: "POST",
           headers: {
             "content-type": "application/json",
-            ...(bridgeToken ? { "x-bridge-token": bridgeToken } : {}),
+            "x-design-preview-token": previewToken,
           },
-          body: JSON.stringify({ script: liveEditBridgeScript }),
+          body: JSON.stringify({
+            script: liveEditBridgeScript,
+            bridgeKey: liveEditBridgeKey,
+          }),
         });
         if (!response.ok) {
           throw new Error(`Bridge registration failed (${response.status})`);
@@ -1435,18 +1064,19 @@ export function DesignCanvas({
     };
   }, [
     bridgeUrl,
-    bridgeToken,
     liveEditBridgeKey,
     liveEditBridgeScript,
-    usesLiveEditEditorBridge,
+    previewToken,
+    usesLiveEditInjectedBridge,
   ]);
 
   useEffect(() => {
     const previewUrl = rawExternalPreviewUrl;
     if (
-      !requiresEditableExternalSnapshot ||
+      !requiresExternalSourceSnapshot ||
       sourceType !== "localhost" ||
       !bridgeUrl ||
+      !previewToken ||
       !previewUrl
     ) {
       snapshotRetryAttemptRef.current = 0;
@@ -1456,17 +1086,12 @@ export function DesignCanvas({
       setExternalSnapshotState(null);
       return;
     }
-    if (externalSnapshotHtml) {
-      snapshotRetryAttemptRef.current = 0;
-      setExternalSnapshotState(null);
-      return;
-    }
     let cancelled = false;
     const controller = new AbortController();
     let retryTimer: number | undefined;
     const endpoint = snapshotEndpointUrl(bridgeUrl, previewUrl);
     const scheduleRetry = () => {
-      if (!requiresEditableExternalSnapshot || cancelled) return;
+      if (!requiresExternalSourceSnapshot || cancelled) return;
       const delay = getSnapshotRetryDelayMs(snapshotRetryAttemptRef.current);
       snapshotRetryAttemptRef.current += 1;
       retryTimer = window.setTimeout(() => {
@@ -1478,7 +1103,10 @@ export function DesignCanvas({
       try {
         const response = await fetch(endpoint, {
           method: "GET",
-          headers: { accept: "application/json" },
+          headers: {
+            accept: "application/json",
+            "x-design-preview-token": previewToken,
+          },
           signal: controller.signal,
         });
         const payload = (await response.json().catch(() => null)) as {
@@ -1502,8 +1130,10 @@ export function DesignCanvas({
           return;
         }
         const sourceUrl = payload.url || previewUrl;
-        const html = prepareStaticSnapshotHtml(payload.html ?? "", sourceUrl);
-        const stamped = ensureCodeLayerNodeIdsInHtml(html, {
+        const sourceHtml = sanitizeLocalhostSourceSnapshotHtml(
+          payload.html ?? "",
+        );
+        const stamped = ensureCodeLayerNodeIdsInHtml(sourceHtml, {
           source: {
             kind: "remote-url",
             sourceType: "localhost",
@@ -1540,11 +1170,11 @@ export function DesignCanvas({
     };
   }, [
     bridgeUrl,
-    externalSnapshotHtml,
     externalSnapshotRetryNonce,
     rawExternalPreviewUrl,
-    requiresEditableExternalSnapshot,
+    requiresExternalSourceSnapshot,
     sourceType,
+    previewToken,
   ]);
 
   // Manual retry (offline-state "Retry" button): reset the backoff so the
@@ -1666,6 +1296,13 @@ export function DesignCanvas({
   // never rebuilds srcdoc / reloads every screen iframe.
   const srcdoc = useMemo(() => {
     if (externalPreviewUrl) return undefined;
+    // Never boot the raw localhost URL (or an editor-enabled srcdoc) while
+    // the keyed live-edit bridge is still registering. The opaque placeholder
+    // stays behind the visible loading surface; the real iframe mounts once,
+    // directly at the authenticated proxied document.
+    if (waitingForLiveEditBridge) {
+      return '<!doctype html><html><head><meta charset="utf-8"></head><body></body></html>';
+    }
     const editorChromeBridge = interactMode
       ? ""
       : createEditorBridgeThemeScript(readEditorBridgeThemeVars()) +
@@ -1690,10 +1327,6 @@ export function DesignCanvas({
             "__DESIGN_CANVAS_BOARD_SURFACE__",
             boardSurface ? "true" : "false",
           );
-    const embeddedWheelBridge = EMBEDDED_WHEEL_BRIDGE_SCRIPT.replace(
-      "__EMBEDDED_WHEEL_FORWARDING_ENABLED__",
-      isEmbeddedFrame ? "true" : "false",
-    );
     // ALWAYS injected (like the other always-on bridges above) so
     // MultiScreenCanvas's cross-screen drag hit-testing
     // (agent-native:hit-test / agent-native:hit-test-result) resolves an
@@ -1708,7 +1341,7 @@ export function DesignCanvas({
       ZOOM_BRIDGE_SCRIPT +
       NAV_BRIDGE_SCRIPT +
       LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT +
-      embeddedWheelBridge +
+      embeddedGestureBridgeForCurrentState +
       editorChromeBridge;
     const frameContent = getEmbeddedFrameDocumentContent({
       content: iframeRenderContent,
@@ -1750,10 +1383,22 @@ export function DesignCanvas({
     embeddedFrame?.contentOffsetX,
     embeddedFrame?.contentOffsetY,
     embeddedFrameBackground,
+    embeddedGestureBridgeForCurrentState,
     iframeRenderContent,
     transparentBackground,
+    waitingForLiveEditBridge,
   ]);
 
+  const iframeDocumentIdentity = externalPreviewUrl
+    ? `src:${externalPreviewUrl}`
+    : waitingForLiveEditBridge
+      ? `live-edit-pending:${liveEditBridgeKey}`
+      : `srcdoc:${contentKey ?? ""}:${contentHash(srcdoc ?? "")}`;
+  if (previousIframeDocumentIdentityRef.current !== iframeDocumentIdentity) {
+    previousIframeDocumentIdentityRef.current = iframeDocumentIdentity;
+    bridgeReadyRef.current = false;
+  }
+
   // Listen for messages from the iframe
   useEffect(() => {
     function handleMessage(e: MessageEvent) {
@@ -1768,7 +1413,7 @@ export function DesignCanvas({
       // somehow shares our window reference still can't be trusted.
       const trusted =
         sourceType === "fusion"
-          ? iframeWindow != null &&
+          ? iframeWindow !== null &&
             e.source === iframeWindow &&
             isAllowedFusionOrigin(e.origin, fusionUrl)
           : isTrustedCanvasBridgeMessage({
@@ -2088,6 +1733,21 @@ export function DesignCanvas({
         }
         return;
       }
+      if (e.data.type === "embedded-canvas-pan") {
+        const iframe = iframeRef.current;
+        if (!iframe) return;
+        const result = forwardEmbeddedCanvasPanMessage({
+          data: e.data,
+          iframe,
+          hostWindow: window,
+          session: embeddedCanvasPanSessionRef.current,
+        });
+        embeddedCanvasPanSessionRef.current = result.session;
+        // The message type belongs exclusively to the gesture bridge. Even a
+        // malformed/reordered packet must not fall through to another bridge
+        // protocol handler after validation rejects it.
+        return;
+      }
       if (e.data.type === "embedded-canvas-wheel") {
         if (!isEmbeddedFrame) return;
         const iframe = iframeRef.current;
@@ -2211,6 +1871,13 @@ export function DesignCanvas({
   const replayIframeEditorState = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
+    iframe.contentWindow?.postMessage(
+      {
+        type: "embedded-canvas-pan-mode",
+        leftButtonEnabled: handToolActive || spacePanActive,
+      },
+      "*",
+    );
     iframe.contentWindow?.postMessage(
       { type: "tweak-values", values: tweakValues },
       "*",
@@ -2283,6 +1950,7 @@ export function DesignCanvas({
       );
     }
   }, [
+    handToolActive,
     hoveredSelector,
     hoveredSelectorCandidates,
     hiddenSelectors,
@@ -2295,6 +1963,7 @@ export function DesignCanvas({
     selectedSelectorCandidates,
     selectedSelectorGroups,
     shaderFillPreview,
+    spacePanActive,
     tweakValues,
   ]);
 
@@ -2309,6 +1978,22 @@ export function DesignCanvas({
     return () => iframe.removeEventListener("load", replayIframeEditorState);
   }, [replayIframeEditorState]);
 
+  // A real top-level focus loss (Cmd+Tab, switching windows, browser chrome)
+  // does not reliably produce pointercancel inside every browser's iframe.
+  // Explicitly reset the child bridge as well as the host-side packet session
+  // so the next middle/hand drag can always start cleanly after focus returns.
+  useEffect(() => {
+    const handleHostWindowBlur = () => {
+      embeddedCanvasPanSessionRef.current = null;
+      iframeRef.current?.contentWindow?.postMessage(
+        { type: "embedded-canvas-pan-cancel" },
+        "*",
+      );
+    };
+    window.addEventListener("blur", handleHostWindowBlur);
+    return () => window.removeEventListener("blur", handleHostWindowBlur);
+  }, []);
+
   // Fallback for documents that never inject the editor-chrome bridge (e.g.
   // interactMode, or an external-preview iframe where srcdoc is undefined):
   // those never post agent-native:editor-chrome-ready, so nothing would ever
@@ -2322,13 +2007,14 @@ export function DesignCanvas({
     const iframe = iframeRef.current;
     if (!iframe) return;
     function handleLoadReadyFallback() {
+      if (!shouldUseIframeLoadReadyFallback(usesLiveEditEditorBridge)) return;
       if (bridgeReadyRef.current) return;
       bridgeReadyRef.current = true;
       flushPendingOneShotMessages();
     }
     iframe.addEventListener("load", handleLoadReadyFallback);
     return () => iframe.removeEventListener("load", handleLoadReadyFallback);
-  }, [flushPendingOneShotMessages]);
+  }, [flushPendingOneShotMessages, usesLiveEditEditorBridge]);
 
   useEffect(() => {
     if (clearSelectionRequest === undefined) return;
@@ -2502,7 +2188,7 @@ export function DesignCanvas({
    * The bridge enters the same contenteditable text-editing path used on dblclick.
    */
   const beginTextEdit = useCallback(
-    (nodeId: string) => {
+    (nodeId: string, options?: { afterPointerGesture?: boolean }) => {
       const iframe = iframeRef.current;
       if (!iframe?.contentWindow || !nodeId) return;
       // Arm the creation-race keystroke buffer (see routePendingTextEditKey):
@@ -2517,11 +2203,16 @@ export function DesignCanvas({
           startedAt: Date.now(),
         };
       }
-      postOneShotBridgeMessage({
-        type: "begin-text-edit",
-        nodeId,
-        force: true,
-      });
+      schedulePendingTextEditActivation(
+        () => {
+          postOneShotBridgeMessage({
+            type: "begin-text-edit",
+            nodeId,
+            force: true,
+          });
+        },
+        { afterPointerGesture: options?.afterPointerGesture },
+      );
     },
     [postOneShotBridgeMessage],
   );
@@ -2623,7 +2314,11 @@ export function DesignCanvas({
 
   const lastStyleBaselineResetRequestRef = useRef<number | null>(null);
   useEffect(() => {
-    if (styleBaselineResetRequest == null) return;
+    if (
+      styleBaselineResetRequest === null ||
+      styleBaselineResetRequest === undefined
+    )
+      return;
     if (
       lastStyleBaselineResetRequestRef.current === styleBaselineResetRequest
     ) {
@@ -2919,7 +2614,9 @@ export function DesignCanvas({
   // the deviceFrame width so the caller can render the same source at an
   // explicit viewport width (e.g. 390 / 768 / 1280 side-by-side breakpoints).
   const resolvedWidth =
-    previewWidthPx != null ? `${previewWidthPx}px` : iframeWidth;
+    previewWidthPx !== null && previewWidthPx !== undefined
+      ? `${previewWidthPx}px`
+      : iframeWidth;
   const focusScrollSurface = useCallback(() => {
     const surface = scrollContainerRef.current;
     if (!surface || document.activeElement === surface) return;
@@ -2937,15 +2634,11 @@ export function DesignCanvas({
   // plain `mousemove`/`mouseup` window listeners for the drag's lifetime,
   // same pattern as its `installDragListeners(handleMouseMove, handlePanEnd)`.
   //
-  // These handlers live on the scroll container itself, so they fire for
-  // drags that start over the empty canvas background or the creation
-  // overlay (both real DOM nodes in this document). A drag that starts
-  // *inside* the iframe's own document does not reach these handlers —
-  // mousedown does not cross a same-origin/cross-document boundary any more
-  // than wheel events do (see the pinch-zoom-wheel bridge message above for
-  // the equivalent problem with wheel) — so panning from inside interactive
-  // iframe content is a follow-up that would need its own bridge message,
-  // not a gap introduced by this change.
+  // Drags that begin inside the iframe arrive through the generated embedded
+  // gesture bridge as a synthetic mousedown on the parent iframe element,
+  // followed by window mousemove/mouseup events. That deliberately reuses
+  // this exact path, keeping empty-canvas, inline HTML/Alpine, and localhost
+  // live-edit panning behavior identical without an iframe-local pan model.
   const [isPanningState, setIsPanningState] = useState(false);
 
   const handleScrollSurfaceMouseDown = useCallback(
@@ -2972,13 +2665,15 @@ export function DesignCanvas({
         scroll.scrollLeft -= dx;
         scroll.scrollTop -= dy;
       };
-      const handleMouseUp = () => {
+      const handlePanEnd = () => {
         setIsPanningState(false);
         window.removeEventListener("mousemove", handleMouseMove);
-        window.removeEventListener("mouseup", handleMouseUp);
+        window.removeEventListener("mouseup", handlePanEnd);
+        window.removeEventListener("blur", handlePanEnd);
       };
       window.addEventListener("mousemove", handleMouseMove);
-      window.addEventListener("mouseup", handleMouseUp);
+      window.addEventListener("mouseup", handlePanEnd);
+      window.addEventListener("blur", handlePanEnd);
     },
     [handToolActive, spacePanActive],
   );
@@ -3104,7 +2799,9 @@ export function DesignCanvas({
         // layer's own top-left corner stays a fixed point in scroll-content
         // space — is untouched. Base editing (previewWidthPx unset) keeps
         // the original inline-block full-width layout unchanged.
-        ...(previewWidthPx != null && !embeddedFrame
+        ...(previewWidthPx !== null &&
+        previewWidthPx !== undefined &&
+        !embeddedFrame
           ? {
               display: "block",
               marginLeft: "auto",
@@ -3114,36 +2811,14 @@ export function DesignCanvas({
       }}
     >
       <iframe
+        key={iframeDocumentIdentity}
         ref={iframeRef}
         src={externalPreviewUrl ?? undefined}
         srcDoc={externalPreviewUrl ? undefined : srcdoc}
-        sandbox={
-          externalPreviewUrl
-            ? "allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-same-origin"
-            : // NOTE(security): allow-same-origin is still present on this
-              // branch (the inline srcdoc iframe, where agent/user-generated
-              // design HTML executes) even though allow-scripts +
-              // allow-same-origin together defeat the sandbox in principle.
-              // This is a deliberate, currently-blocked tradeoff, not an
-              // oversight — see the long comment above DesignCanvasProps /
-              // sourceType for the security model, and the PNG/SVG export
-              // handlers in DesignEditor.tsx (handleDownloadPng /
-              // handleDownloadSvg). Those handlers read this same iframe's
-              // `contentDocument` directly and hand the LIVE document element
-              // to html2canvas, and read live CSSOM (getComputedStyle,
-              // doc.styleSheets) for SVG serialization. That cannot be
-              // expressed over the postMessage bridge without moving
-              // html2canvas execution and CSSOM-dependent serialization logic
-              // INTO the sandboxed iframe itself — a separate, larger rewrite,
-              // not a bridge-handler addition. All other former
-              // `contentDocument`/`contentWindow.document` reads on this
-              // iframe (e.g. text-edit-status) now go through bridge
-              // request/response postMessage handlers in
-              // editor-chrome.bridge.ts and no longer need allow-same-origin.
-              // Do not remove this flag until PNG/SVG export is rebuilt to run
-              // inside the iframe.
-              "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-same-origin"
-        }
+        sandbox={getDesignCanvasIframeSandbox({
+          externalPreview: Boolean(externalPreviewUrl),
+          readOnly,
+        })}
         data-design-preview-iframe
         data-screen-iframe-id={
           boardSurface ? undefined : (screenId ?? undefined)
@@ -3285,19 +2960,25 @@ export function DesignCanvas({
             "",
             instruction || "Apply these annotations to the design.",
           ];
-          try {
-            sendToDesignAgentChat({
-              message: lines.join("\n"),
-              submit: true,
-              openSidebar: true,
-            });
-          } catch (err) {
-            console.error("[DesignCanvas] failed to submit drawing:", err);
-          }
-          if (queuedAnnotationPins.length > 0) {
-            setPinSubmitSignal((signal) => signal + 1);
-          }
-          onExitDrawMode?.();
+          submitDesignAnnotations({
+            message: lines.join("\n"),
+            hasQueuedPins: queuedAnnotationPins.length > 0,
+            send: (message) => {
+              sendToDesignAgentChat({
+                message,
+                submit: true,
+                openSidebar: true,
+              });
+            },
+            markQueuedPinsSubmitted: () => {
+              setPinSubmitSignal((signal) => signal + 1);
+            },
+            exitDrawMode: () => onExitDrawMode?.(),
+            onError: (error) => {
+              console.error("[DesignCanvas] failed to submit drawing:", error);
+              toast.error(t("designEditor.toasts.annotationSendError"));
+            },
+          });
         }}
       />
     </div>
@@ -3492,6 +3173,17 @@ interface CreationDragState {
   moved: boolean;
 }
 
+interface SingleScreenPenGestureState {
+  pointerId: number;
+  originClient: { x: number; y: number };
+  anchor: PenPoint;
+  pathBefore: PenPath | null;
+  moved: boolean;
+  closing: boolean;
+}
+
+const SINGLE_SCREEN_PEN_HIT_RADIUS_PX = 10;
+
 interface SingleScreenCreationOverlayProps {
   tool: CreationTool;
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -3508,15 +3200,11 @@ interface SingleScreenCreationOverlayProps {
  * is treated as a drag (draws a rect/line via `getDraftGeometryFromPoints`,
  * the same helper MultiScreenCanvas uses for overview drafts); a
  * pointerdown→up with negligible movement is treated as a click (places a
- * default-sized primitive, or for pen, starts a path at that point).
- *
- * Deferred: multi-click pen path authoring. In single-screen mode a single
- * click emits `points: [point], fromClick: true` so the parent can start a
- * pen path (matching MultiScreenCanvas's click-to-start behavior), but there
- * is no in-overlay support yet for adding further anchor points before
- * committing — that's a follow-up once the parent's pen-path commit flow is
- * wired for single-screen. This intentionally never force-switches to
- * overview to get full pen authoring.
+ * default-sized primitive). Pen owns a stateful path until the user presses
+ * Enter/Escape, double-clicks, closes on the first anchor, or chooses another
+ * tool. Clicks add corner anchors; pointer drags add Bezier handles; primary
+ * undo/Delete/Backspace remove the latest active segment. This mirrors the
+ * overview pen workflow without forcing a mode switch.
  */
 function SingleScreenCreationOverlay({
   tool,
@@ -3525,6 +3213,14 @@ function SingleScreenCreationOverlay({
 }: SingleScreenCreationOverlayProps) {
   const [drag, setDrag] = useState<CreationDragState | null>(null);
   const dragRef = useRef<CreationDragState | null>(null);
+  const [penPath, setPenPath] = useState<PenPath | null>(null);
+  const penPathRef = useRef<PenPath | null>(null);
+  const [penGesturePreview, setPenGesturePreview] = useState<PenPath | null>(
+    null,
+  );
+  const penGestureRef = useRef<SingleScreenPenGestureState | null>(null);
+  const [penPointer, setPenPointer] = useState<PenPoint | null>(null);
+  const [penCloseHover, setPenCloseHover] = useState(false);
 
   const toContentPoint = useCallback(
     (clientX: number, clientY: number) => {
@@ -3539,6 +3235,91 @@ function SingleScreenCreationOverlay({
     [iframeRef],
   );
 
+  const penHitRadius = useCallback(() => {
+    const iframe = iframeRef.current;
+    const rect = iframe?.getBoundingClientRect();
+    if (!iframe || !rect || iframe.clientWidth <= 0) {
+      return SINGLE_SCREEN_PEN_HIT_RADIUS_PX;
+    }
+    const scale = rect.width / iframe.clientWidth;
+    return SINGLE_SCREEN_PEN_HIT_RADIUS_PX / (scale || 1);
+  }, [iframeRef]);
+
+  const updatePenPath = useCallback((nextPath: PenPath | null) => {
+    penPathRef.current = nextPath;
+    setPenPath(nextPath);
+  }, []);
+
+  const clearPenPath = useCallback(() => {
+    updatePenPath(null);
+    penGestureRef.current = null;
+    setPenGesturePreview(null);
+    setPenPointer(null);
+    setPenCloseHover(false);
+  }, [updatePenPath]);
+
+  const finishPenPath = useCallback(
+    (
+      path: PenPath | null = penPathRef.current,
+      options?: { preserveActiveTool?: boolean },
+    ) => {
+      const committed = path ? clonePenPath(path) : null;
+      clearPenPath();
+      if (!committed || committed.nodes.length < 2 || !onCreatePrimitive) {
+        return;
+      }
+      onCreatePrimitive({
+        tool: "pen",
+        points: committed.nodes.map((node) => node.point),
+        penPath: committed,
+        fromClick: false,
+        preserveActiveTool: options?.preserveActiveTool,
+      });
+    },
+    [clearPenPath, onCreatePrimitive],
+  );
+
+  const getPenAnchor = useCallback(
+    (clientX: number, clientY: number, shiftKey: boolean) => {
+      const point = toContentPoint(clientX, clientY);
+      const path = penPathRef.current;
+      const lastAnchor = path?.nodes[path.nodes.length - 1]?.point;
+      return shiftKey && lastAnchor
+        ? constrainPointTo45Degrees(lastAnchor, point)
+        : point;
+    },
+    [toContentPoint],
+  );
+
+  const updatePenPointer = useCallback(
+    (clientX: number, clientY: number, shiftKey: boolean) => {
+      const path = penPathRef.current;
+      if (!path || path.closed) {
+        setPenPointer(null);
+        setPenCloseHover(false);
+        return;
+      }
+      const rawPoint = toContentPoint(clientX, clientY);
+      const closeHover = isPenCloseTarget(path, rawPoint, penHitRadius());
+      setPenCloseHover(closeHover);
+      setPenPointer(
+        closeHover
+          ? path.nodes[0]!.point
+          : getPenAnchor(clientX, clientY, shiftKey),
+      );
+    },
+    [getPenAnchor, penHitRadius, toContentPoint],
+  );
+
+  const previousToolRef = useRef(tool);
+  useEffect(() => {
+    const previousTool = previousToolRef.current;
+    previousToolRef.current = tool;
+    if (previousTool === "pen" && tool !== "pen") {
+      finishPenPath(penPathRef.current, { preserveActiveTool: true });
+    }
+  }, [finishPenPath, tool]);
+
   const emit = useCallback(
     (state: CreationDragState) => {
       if (!onCreatePrimitive) return;
@@ -3559,17 +3340,8 @@ function SingleScreenCreationOverlay({
         return;
       }
 
-      if (activeTool === "pen") {
-        // Deferred: multi-click pen authoring (see component doc comment).
-        // A click starts a path; a drag is treated the same as a click for
-        // now — only the start point is emitted.
-        onCreatePrimitive({
-          tool: "pen",
-          points: [startContent],
-          fromClick: true,
-        });
-        return;
-      }
+      // Pen commits through finishPenPath after collecting multiple gestures.
+      if (activeTool === "pen") return;
 
       if (!moved) {
         const size = CREATION_DEFAULT_SIZE[activeTool];
@@ -3608,6 +3380,36 @@ function SingleScreenCreationOverlay({
   const handlePointerDown = useCallback(
     (e: React.PointerEvent<HTMLDivElement>) => {
       if (e.button !== 0) return;
+      if (tool === "pen") {
+        e.preventDefault();
+        e.stopPropagation();
+        const currentPath = penPathRef.current?.closed
+          ? null
+          : penPathRef.current;
+        const pathBefore = currentPath ? clonePenPath(currentPath) : null;
+        const rawPoint = toContentPoint(e.clientX, e.clientY);
+        const closing = isPenCloseTarget(pathBefore, rawPoint, penHitRadius());
+        const anchor = closing
+          ? pathBefore!.nodes[0]!.point
+          : getPenAnchor(e.clientX, e.clientY, e.shiftKey);
+        penGestureRef.current = {
+          pointerId: e.pointerId,
+          originClient: { x: e.clientX, y: e.clientY },
+          anchor,
+          pathBefore,
+          moved: false,
+          closing,
+        };
+        const initialPath = closing
+          ? closePenPath(pathBefore!)
+          : appendPenNode(pathBefore, createCornerNode(anchor));
+        updatePenPath(initialPath);
+        setPenGesturePreview(initialPath);
+        setPenPointer(null);
+        setPenCloseHover(closing);
+        e.currentTarget.setPointerCapture(e.pointerId);
+        return;
+      }
       const point = toContentPoint(e.clientX, e.clientY);
       const next: CreationDragState = {
         tool,
@@ -3621,11 +3423,49 @@ function SingleScreenCreationOverlay({
       setDrag(next);
       (e.target as HTMLElement).setPointerCapture(e.pointerId);
     },
-    [tool, toContentPoint],
+    [
+      finishPenPath,
+      getPenAnchor,
+      penHitRadius,
+      tool,
+      toContentPoint,
+      updatePenPath,
+    ],
   );
 
   const handlePointerMove = useCallback(
     (e: React.PointerEvent<HTMLDivElement>) => {
+      if (tool === "pen") {
+        const gesture = penGestureRef.current;
+        if (!gesture || gesture.pointerId !== e.pointerId) {
+          updatePenPointer(e.clientX, e.clientY, e.shiftKey);
+          return;
+        }
+        const moved =
+          gesture.moved ||
+          Math.hypot(
+            e.clientX - gesture.originClient.x,
+            e.clientY - gesture.originClient.y,
+          ) > CREATION_CLICK_MOVE_THRESHOLD_PX;
+        gesture.moved = moved;
+        const rawHandle = toContentPoint(e.clientX, e.clientY);
+        const handleOut = e.shiftKey
+          ? constrainPointTo45Degrees(gesture.anchor, rawHandle)
+          : rawHandle;
+        const nextPath = gesture.closing
+          ? shapeClosingHandles(gesture.pathBefore!, moved ? handleOut : null)
+          : appendPenNode(
+              gesture.pathBefore,
+              moved
+                ? createSmoothNode(gesture.anchor, handleOut, {
+                    breakSymmetry: e.altKey,
+                  })
+                : createCornerNode(gesture.anchor),
+            );
+        updatePenPath(nextPath);
+        setPenGesturePreview(nextPath);
+        return;
+      }
       const current = dragRef.current;
       if (!current || current.pointerId !== e.pointerId) return;
       // Movement threshold measured in client (viewport) space — a constant
@@ -3646,32 +3486,138 @@ function SingleScreenCreationOverlay({
       dragRef.current = next;
       setDrag(next);
     },
-    [toContentPoint],
+    [tool, toContentPoint, updatePenPath, updatePenPointer],
   );
 
   const handlePointerUp = useCallback(
     (e: React.PointerEvent<HTMLDivElement>) => {
+      if (tool === "pen") {
+        const gesture = penGestureRef.current;
+        if (!gesture || gesture.pointerId !== e.pointerId) return;
+        e.preventDefault();
+        e.stopPropagation();
+        const moved =
+          gesture.moved ||
+          Math.hypot(
+            e.clientX - gesture.originClient.x,
+            e.clientY - gesture.originClient.y,
+          ) > CREATION_CLICK_MOVE_THRESHOLD_PX;
+        const rawHandle = toContentPoint(e.clientX, e.clientY);
+        const handleOut = e.shiftKey
+          ? constrainPointTo45Degrees(gesture.anchor, rawHandle)
+          : rawHandle;
+        const nextPath = gesture.closing
+          ? shapeClosingHandles(gesture.pathBefore!, moved ? handleOut : null)
+          : appendPenNode(
+              gesture.pathBefore,
+              moved
+                ? createSmoothNode(gesture.anchor, handleOut, {
+                    breakSymmetry: e.altKey,
+                  })
+                : createCornerNode(gesture.anchor),
+            );
+        penGestureRef.current = null;
+        setPenGesturePreview(null);
+        setPenPointer(null);
+        setPenCloseHover(false);
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+          e.currentTarget.releasePointerCapture(e.pointerId);
+        }
+        if (gesture.closing) {
+          finishPenPath(nextPath);
+        } else {
+          updatePenPath(nextPath);
+        }
+        return;
+      }
       const current = dragRef.current;
       if (!current || current.pointerId !== e.pointerId) return;
       dragRef.current = null;
       setDrag(null);
       emit(current);
     },
-    [emit],
+    [emit, finishPenPath, tool, toContentPoint, updatePenPath],
   );
 
   const handlePointerCancel = useCallback(
     (e: React.PointerEvent<HTMLDivElement>) => {
+      if (tool === "pen") {
+        const gesture = penGestureRef.current;
+        if (!gesture || gesture.pointerId !== e.pointerId) return;
+        penGestureRef.current = null;
+        updatePenPath(gesture.pathBefore);
+        setPenGesturePreview(null);
+        setPenPointer(null);
+        setPenCloseHover(false);
+        return;
+      }
       const current = dragRef.current;
       if (!current || current.pointerId !== e.pointerId) return;
       dragRef.current = null;
       setDrag(null);
     },
-    [],
+    [tool, updatePenPath],
   );
 
+  useEffect(() => {
+    if (tool !== "pen") return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const path = penPathRef.current;
+      if (!path) return;
+      const target = event.target;
+      if (
+        target instanceof HTMLElement &&
+        (target.isContentEditable ||
+          target.tagName === "INPUT" ||
+          target.tagName === "TEXTAREA")
+      ) {
+        return;
+      }
+
+      const primary = event.metaKey || event.ctrlKey;
+      const undo =
+        primary && !event.shiftKey && event.key.toLowerCase() === "z";
+      const removeSegment =
+        !primary && (event.key === "Delete" || event.key === "Backspace");
+      if (undo || removeSegment) {
+        event.preventDefault();
+        event.stopPropagation();
+        event.stopImmediatePropagation();
+        if (penGestureRef.current) return;
+        const remainingNodes = path.nodes.slice(0, -1);
+        if (remainingNodes.length === 0) {
+          clearPenPath();
+        } else {
+          updatePenPath({ nodes: remainingNodes, closed: false });
+          setPenGesturePreview(null);
+          setPenPointer(null);
+          setPenCloseHover(false);
+        }
+        return;
+      }
+
+      if (primary || (event.key !== "Enter" && event.key !== "Escape")) {
+        return;
+      }
+      event.preventDefault();
+      event.stopPropagation();
+      event.stopImmediatePropagation();
+      finishPenPath(path);
+    };
+
+    window.addEventListener("keydown", handleKeyDown, true);
+    return () => window.removeEventListener("keydown", handleKeyDown, true);
+  }, [clearPenPath, finishPenPath, tool, updatePenPath]);
+
   const cursorClass = tool === "text" ? "cursor-text" : "cursor-crosshair";
   const isLineTool = tool === "line" || tool === "arrow";
+  const displayedPenPath =
+    penGesturePreview ??
+    (penPath && penPointer
+      ? penCloseHover
+        ? closePenPath(penPath)
+        : appendPenNode(penPath, createCornerNode(penPointer))
+      : penPath);
 
   // Live drag preview, converted back from screen-content space to the
   // overlay's own (unscaled, layout-space) coordinates. The overlay div is
@@ -3700,7 +3646,26 @@ function SingleScreenCreationOverlay({
       onPointerMove={handlePointerMove}
       onPointerUp={handlePointerUp}
       onPointerCancel={handlePointerCancel}
+      onDoubleClick={(event) => {
+        if (tool !== "pen" || !penPathRef.current) return;
+        event.preventDefault();
+        event.stopPropagation();
+        finishPenPath(collapseDoubleClickPenAnchor(penPathRef.current));
+      }}
+      onPointerLeave={() => {
+        if (tool === "pen" && !penGestureRef.current) {
+          setPenPointer(null);
+          setPenCloseHover(false);
+        }
+      }}
     >
+      {tool === "pen" && displayedPenPath ? (
+        <SingleScreenPenPathOverlay
+          path={displayedPenPath}
+          closeHover={penCloseHover}
+          iframeRef={iframeRef}
+        />
+      ) : null}
       {previewRect ? (
         <div
           data-creation-preview-rect
@@ -3733,3 +3698,115 @@ function SingleScreenCreationOverlay({
     </div>
   );
 }
+
+function SingleScreenPenPathOverlay({
+  path,
+  closeHover,
+  iframeRef,
+}: {
+  path: PenPath;
+  closeHover: boolean;
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+}) {
+  const iframe = iframeRef.current;
+  const rect = iframe?.getBoundingClientRect();
+  const renderedScale =
+    iframe && rect && iframe.clientWidth > 0
+      ? rect.width / iframe.clientWidth
+      : 1;
+  const chromeScale = 1 / (renderedScale || 1);
+  const anchorSize = 8 * chromeScale;
+  const handleSize = 6 * chromeScale;
+  const pathData = serializePenPath(path);
+
+  return (
+    <div
+      data-pen-path-overlay
+      className="pointer-events-none absolute inset-0 z-[90]"
+    >
+      <svg className="absolute inset-0 size-full overflow-visible">
+        {path.nodes.map((node, index) => (
+          <g key={`single-screen-pen-handles-${index}`}>
+            {node.handleIn ? (
+              <line
+                x1={node.point.x}
+                y1={node.point.y}
+                x2={node.handleIn.x}
+                y2={node.handleIn.y}
+                stroke="var(--design-editor-accent-color)"
+                strokeDasharray="3 3"
+                strokeWidth={Math.max(1, chromeScale)}
+              />
+            ) : null}
+            {node.handleOut ? (
+              <line
+                x1={node.point.x}
+                y1={node.point.y}
+                x2={node.handleOut.x}
+                y2={node.handleOut.y}
+                stroke="var(--design-editor-accent-color)"
+                strokeDasharray="3 3"
+                strokeWidth={Math.max(1, chromeScale)}
+              />
+            ) : null}
+          </g>
+        ))}
+        <path
+          d={pathData}
+          fill="none"
+          stroke="rgba(255,255,255,0.95)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth={5 * chromeScale}
+        />
+        <path
+          d={pathData}
+          fill="none"
+          stroke="var(--design-editor-accent-color)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth={2 * chromeScale}
+        />
+      </svg>
+      {path.nodes.map((node, index) => (
+        <span
+          key={`single-screen-pen-anchor-${index}`}
+          data-pen-anchor
+          className={cn(
+            "absolute rounded-[2px] border shadow-sm",
+            index === 0 && closeHover
+              ? "scale-125 border-[var(--design-editor-accent-color)] bg-[var(--design-editor-accent-color)] ring-4 ring-[var(--design-editor-selection-color)]"
+              : "border-[var(--design-editor-accent-color)] bg-[var(--design-editor-accent-contrast-color)]",
+          )}
+          style={{
+            left: node.point.x - anchorSize / 2,
+            top: node.point.y - anchorSize / 2,
+            width: anchorSize,
+            height: anchorSize,
+            borderWidth: Math.max(1, chromeScale),
+          }}
+        />
+      ))}
+      {path.nodes.flatMap((node, index) =>
+        [node.handleIn, node.handleOut].flatMap((handle, handleIndex) =>
+          handle
+            ? [
+                <span
+                  key={`single-screen-pen-handle-${index}-${handleIndex}`}
+                  data-pen-handle
+                  className="absolute rounded-full border border-[var(--design-editor-accent-color)] bg-background shadow-sm"
+                  style={{
+                    left: handle.x - handleSize / 2,
+                    top: handle.y - handleSize / 2,
+                    width: handleSize,
+                    height: handleSize,
+                    borderWidth: Math.max(1, chromeScale),
+                  }}
+                />,
+              ]
+            : [],
+        ),
+      )}
+    </div>
+  );
+}