@agent-native/core 0.92.10 → 0.92.12

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

@@ -14,6 +14,7 @@ import {
   createSmoothNode,
   isPenCloseTarget,
   serializePenPath,
+  translatePenPath,
   type PenPath,
   type PenPoint,
 } from "@shared/pen-path";
@@ -31,7 +32,7 @@ import {
   CanvasCommentPins,
   type CanvasPin,
 } from "@/components/visual-editor";
-import { sendToDesignAgentChat } from "@/lib/agent-chat";
+import { sendToDesignAgentChatAndConfirm } from "@/lib/agent-chat";
 import { cn } from "@/lib/utils";
 
 import { editorChromeBridgeScript } from "../../../.generated/bridge/editor-chrome.generated";
@@ -43,6 +44,7 @@ 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 { captureAnnotatedScreenshot } from "./design-canvas/annotation-snapshot";
 import { submitDesignAnnotations } from "./design-canvas/annotation-submit";
 import {
   getScreenContentPointFromClient,
@@ -55,6 +57,7 @@ import {
 } from "./design-canvas/creation";
 import { isElementInfoPayload } from "./design-canvas/element-payload";
 import {
+  embeddedContentOffsetCss,
   embeddedContentOffsetStyle,
   getEmbeddedFrameBackgroundStyle,
   getEmbeddedFrameDocumentContent,
@@ -91,6 +94,7 @@ import type {
   ElementInfo,
   ElementSelectionIntent,
   DeviceFrameType,
+  RuntimeStructureMoveRequest,
 } from "./types";
 
 /**
@@ -320,6 +324,10 @@ interface DesignCanvasProps {
     status?: number;
     contentType?: string;
   }) => void;
+  onRuntimeLayerSnapshot?: (snapshot: {
+    html: string;
+    nodeCount: number;
+  }) => void;
   /**
    * Explicit Builder-hosted app URL for fusion source rendering.
    *
@@ -381,6 +389,8 @@ interface DesignCanvasProps {
     requestId: number;
     acks: Array<{ requestId: string; applied: boolean }>;
   } | null;
+  /** One-shot host request to optimistically move a runtime-only layer. */
+  runtimeStructureMoveRequest?: RuntimeStructureMoveRequest | null;
   embeddedFrameBackground?: string;
   transparentBackground?: boolean;
   editorChromeScaleX?: number;
@@ -432,8 +442,10 @@ interface DesignCanvasProps {
       anchorSourceId?: string;
       requestId?: string;
       dropMode?: "flow-insert" | "absolute-container";
+      forceFlowPositionOverride?: boolean;
       sourceRect?: { x: number; y: number; width: number; height: number };
       anchorRect?: { x: number; y: number; width: number; height: number };
+      anchorElementInfo?: ElementInfo;
     },
   ) => boolean | "pending" | void;
   onVisualDuplicateChange?: (
@@ -452,6 +464,20 @@ interface DesignCanvasProps {
   drawMode?: boolean;
   /** Called when the user exits draw mode (X / Escape / after Send). */
   onExitDrawMode?: () => void;
+  /**
+   * Bumped by the parent exactly when the user deliberately discards the
+   * current annotation batch (the same moment `onExitDrawMode` fires from
+   * the overlay's own X button or a confirmed Send). SharedDrawOverlay only
+   * clears its strokes/text annotations when this changes — NOT merely
+   * because `drawMode` toggled off for some other reason (switching tools,
+   * views, or side panels) — so unsent annotation work survives an
+   * unrelated exit instead of being silently discarded.
+   */
+  drawOverlayResetSignal?: number;
+  /** Keeps the active focused overlay bitmap alive across mode/view hides. */
+  retainDrawOverlayWhenHidden?: boolean;
+  /** Reports focused annotation delivery state so global Escape stays inert too. */
+  onAnnotationSendingChange?: (sending: boolean) => void;
   /** Whether comment-pin drop mode is active. */
   pinMode?: boolean;
   /**
@@ -685,6 +711,120 @@ function snapshotEndpointUrl(bridgeUrl: string, previewUrl: string): string {
   return endpoint.toString();
 }
 
+function healthEndpointUrl(bridgeUrl: string): string {
+  return new URL("/health", bridgeUrl).toString();
+}
+
+/**
+ * Classifies a suspected `unknown-bridge-key` failure on the localhost
+ * live-edit bridge, based on a `/health` probe fired when the
+ * "agent-native:editor-chrome-ready" handshake hasn't arrived in time.
+ *
+ * The bridge mints a fresh `bridgeInstanceId` every time its process boots
+ * (see `startDesignConnectBridge` in packages/core/src/cli/design-connect.ts)
+ * and echoes it on `/health`, on a successful `/live-edit-bridge`
+ * registration, and on the "unknown bridge key" 409 from `/live-edit`. The
+ * 409 itself is usually unreadable here: the live iframe navigates directly
+ * to the bridge's `/live-edit` URL (a real cross-origin request), so this
+ * component can't inspect the response body or status code the way a
+ * same-origin `fetch` could. Instead, callers probe `/health` — a route that
+ * never requires the preview token — and pass its `bridgeInstanceId` in as
+ * `responseBridgeInstanceId`.
+ *
+ * - Different id than what we last registered with ⇒ the bridge PROCESS
+ *   restarted (crash, machine sleep/wake, manual restart) since our last
+ *   successful registration. That's not a caller bug: silently re-POST the
+ *   same script/key and reload the frame with no user-facing error
+ *   ("reregister").
+ * - Same id ⇒ the process that accepted our registration is still running
+ *   and reachable — the iframe just hasn't finished loading yet (e.g. a
+ *   6-10s cold dev-server compile), NOT a genuine failure. Callers must NOT
+ *   tear the iframe down for this outcome: re-arm the ready-handshake
+ *   watchdog with a longer wait instead ("escalate") — see
+ *   handleSuspectedBridgeRestart's escalation loop, which only gives up and
+ *   shows a (non-destructive) error after a generous total ceiling.
+ * - No id at all (missing from either side) ⇒ inconclusive — `/health`
+ *   responded but we can't confirm process identity either way. Treat this
+ *   like a real, unresolved failure and surface the existing error/Retry UI
+ *   ("error").
+ *
+ * Deliberately NOT exported: every other pure helper in this file
+ * (getExternalPreviewUrl, snapshotEndpointUrl, buildEditorChromeBridgeScript,
+ * contentHash, isAllowedFusionOrigin, originFromUrl, ...) stays module-private
+ * so DesignCanvas.tsx keeps exporting only the DesignCanvas component itself
+ * — see DesignCanvas.refreshBoundary.test.ts, which guards the Fast Refresh
+ * boundary this file relies on given how often it's edited during live design
+ * sessions. Its decision logic is covered by behavioral tests in
+ * DesignCanvas.bridge-restart.test.tsx instead of a direct unit import.
+ */
+function classifyLiveEditHealthProbe(
+  cachedBridgeInstanceId: string | null | undefined,
+  responseBridgeInstanceId: string | null | undefined,
+): "reregister" | "escalate" | "error" {
+  if (!cachedBridgeInstanceId || !responseBridgeInstanceId) return "error";
+  return cachedBridgeInstanceId === responseBridgeInstanceId
+    ? "escalate"
+    : "reregister";
+}
+
+// Grace period after the live-edit bridge is (re)registered and the real
+// iframe document is mounted before a missing "agent-native:editor-chrome-ready"
+// handshake is treated as a suspected bridge restart rather than an in-flight
+// page load. Generous relative to typical localhost load times so a slow but
+// healthy dev server is never misdiagnosed as restarted.
+const LIVE_EDIT_READY_TIMEOUT_MS = 4000;
+// Caps the silent auto-reregister loop below so a pathological bridge that
+// keeps minting a new bridgeInstanceId on every probe (or that never manages
+// to actually register) can't retry forever without ever surfacing an error.
+const MAX_LIVE_EDIT_RESTART_ATTEMPTS = 3;
+// When a /health probe confirms the SAME bridgeInstanceId as last registered
+// (bridge process healthy, page just slow to post ready), each re-arm of the
+// watchdog waits longer than the last — 4s, 8s, 16s — capped here so the
+// backoff doesn't grow unbounded on a very long-running compile.
+const LIVE_EDIT_SAME_INSTANCE_MAX_REARM_DELAY_MS = 16_000;
+// Total cumulative time to keep silently re-arming on a same-instance-id
+// "still healthy" response before finally surfacing a non-destructive error
+// affordance. Generous relative to even a slow cold dev-server compile so a
+// genuinely-loading page is never misdiagnosed as failed; a legitimately
+// long compile that finishes after this point still clears the error the
+// moment the ready handshake arrives (see the message-handler branch below).
+const LIVE_EDIT_SAME_INSTANCE_ERROR_CEILING_MS = 48_000;
+
+// Successful bridge registrations belong to the localhost bridge process,
+// not to one React DesignCanvas instance. Overview -> Full view currently
+// replaces the overview canvas component with a focused canvas component; a
+// component-local registration flag made that transition mount an empty
+// srcdoc first and then replace it with the live URL after an identical POST.
+// Keep a deliberately short handoff cache so the focused instance can mount
+// the already-registered live document exactly once. A stale entry during
+// HMR is harmless: the ready watchdog probes the bridge instance and silently
+// re-registers, while the ready-gated fallback below prevents blank content.
+const LIVE_EDIT_REGISTRATION_HANDOFF_TTL_MS = 30_000;
+const liveEditRegistrationHandoff = new Map<string, number>();
+
+function liveEditRegistrationHandoffKey(
+  bridgeUrl: string | undefined,
+  bridgeKey: string,
+): string | null {
+  if (!bridgeUrl) return null;
+  try {
+    return `${new URL(bridgeUrl).origin}|${bridgeKey}`;
+  } catch {
+    return null;
+  }
+}
+
+function hasRecentLiveEditRegistration(key: string | null): boolean {
+  if (!key) return false;
+  const registeredAt = liveEditRegistrationHandoff.get(key);
+  if (registeredAt === undefined) return false;
+  if (Date.now() - registeredAt <= LIVE_EDIT_REGISTRATION_HANDOFF_TTL_MS) {
+    return true;
+  }
+  liveEditRegistrationHandoff.delete(key);
+  return false;
+}
+
 function originFromUrl(value: string | undefined): string | null {
   if (!value) return null;
   try {
@@ -701,6 +841,9 @@ function buildEditorChromeBridgeScript(args: {
   editorChromeScaleY: number;
   screenId: string;
   boardSurface: boolean;
+  contentOffsetX: number;
+  contentOffsetY: number;
+  runtimeLayerSnapshotEnabled: boolean;
 }) {
   return (
     createEditorBridgeThemeScript(readEditorBridgeThemeVars()) +
@@ -716,6 +859,18 @@ function buildEditorChromeBridgeScript(args: {
         "__DESIGN_CANVAS_BOARD_SURFACE__",
         args.boardSurface ? "true" : "false",
       )
+      .replace(
+        "__DESIGN_CANVAS_CONTENT_OFFSET_X__",
+        String(Math.round(args.contentOffsetX)),
+      )
+      .replace(
+        "__DESIGN_CANVAS_CONTENT_OFFSET_Y__",
+        String(Math.round(args.contentOffsetY)),
+      )
+      .replace(
+        "__RUNTIME_LAYER_SNAPSHOT_ENABLED__",
+        args.runtimeLayerSnapshotEnabled ? "true" : "false",
+      )
   );
 }
 
@@ -727,6 +882,29 @@ function contentHash(value: string): string {
   return `${value.length}:${hash >>> 0}`;
 }
 
+/**
+ * Safely reads an embedded screen iframe's own internal document scroll
+ * position, in the iframe's own unscaled content pixels — the same units
+ * `getScreenContentPointFromClient`'s `scrollOffset` param folds in. Inline
+ * (srcdoc) screens are same-origin, so the happy path below is the common
+ * case, but externally-hosted localhost/fusion previews can be cross-origin,
+ * and `contentWindow.scrollX`/`scrollY` THROWS (it is not merely
+ * `undefined`) when accessed cross-origin. Always degrade to `{0, 0}` rather
+ * than letting that throw escape into a render or event handler.
+ */
+function readIframeScrollOffset(iframe: HTMLIFrameElement | null | undefined): {
+  left: number;
+  top: number;
+} {
+  try {
+    const win = iframe?.contentWindow;
+    if (!win) return { left: 0, top: 0 };
+    return { left: win.scrollX || 0, top: win.scrollY || 0 };
+  } catch {
+    return { left: 0, top: 0 };
+  }
+}
+
 export function DesignCanvas({
   content,
   contentKey,
@@ -734,6 +912,7 @@ export function DesignCanvas({
   bridgeUrl,
   externalSnapshotHtml,
   onExternalContentSnapshot,
+  onRuntimeLayerSnapshot,
   fusionUrl,
   previewToken,
   zoom,
@@ -747,6 +926,7 @@ export function DesignCanvas({
   styleBaselineResetRequest,
   textRevertRequest,
   structureAckRequest,
+  runtimeStructureMoveRequest,
   embeddedFrameBackground,
   transparentBackground = false,
   editorChromeScaleX = 1,
@@ -773,6 +953,9 @@ export function DesignCanvas({
   tweakValues,
   drawMode,
   onExitDrawMode,
+  drawOverlayResetSignal,
+  retainDrawOverlayWhenHidden = false,
+  onAnnotationSendingChange,
   pinMode,
   commentPinsHidden,
   selectedSelector,
@@ -847,6 +1030,8 @@ 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 [readyIframeDocumentIdentity, setReadyIframeDocumentIdentity] =
+    useState<string | null>(null);
   const previousIframeDocumentIdentityRef = useRef<string | null>(null);
   const pendingOneShotMessagesRef = useRef<unknown[]>([]);
   const flushPendingOneShotMessages = useCallback(() => {
@@ -861,8 +1046,11 @@ export function DesignCanvas({
   const postOneShotBridgeMessage = useCallback((message: unknown) => {
     const iframe = iframeRef.current;
     const win = iframe?.contentWindow;
-    if (!win) return false;
-    if (!bridgeReadyRef.current) {
+    // A one-shot prop can arrive in the same render that first creates the
+    // iframe. Keep it queued even when the ref/contentWindow is not attached
+    // yet; otherwise the effect records its request id as handled and the
+    // command is lost permanently before the bridge can announce readiness.
+    if (!win || !bridgeReadyRef.current) {
       pendingOneShotMessagesRef.current.push(message);
       return true;
     }
@@ -872,6 +1060,12 @@ export function DesignCanvas({
   const [renderedContent, setRenderedContent] = useState(content);
   const [annotationPins, setAnnotationPins] = useState<CanvasPin[]>([]);
   const [pinSubmitSignal, setPinSubmitSignal] = useState(0);
+  // True while a drawing send is capturing/compositing/uploading the
+  // annotated screenshot (see design-canvas/annotation-snapshot.ts). Drives
+  // SharedDrawOverlay's busy Send state so a slow capture can't be triggered
+  // twice from the same drawing.
+  const [annotationCaptureBusy, setAnnotationCaptureBusy] = useState(false);
+  const annotationCaptureBusyRef = useRef(false);
   const [fetchedExternalSnapshot, setFetchedExternalSnapshot] = useState<{
     url: string;
     html: string;
@@ -891,6 +1085,83 @@ export function DesignCanvas({
   // manual retry click (see handleManualSnapshotRetry) so the next failure
   // starts the backoff over rather than continuing to climb.
   const snapshotRetryAttemptRef = useRef(0);
+  // Mirrors the snapshot fetch's own retry/error state above: the
+  // /live-edit-bridge registration POST used to have no retry/backoff or
+  // error surface at all — a transient failure (dev server hiccup, brief
+  // network blip) left registeredLiveEditBridgeKey stuck at null forever,
+  // which pins waitingForLiveEditBridge true and the user stares at
+  // "Preparing live editor..." with no explanation and no way to recover
+  // short of reloading the whole page.
+  const bridgeRegistrationRetryAttemptRef = useRef(0);
+  const [bridgeRegistrationRetryNonce, setBridgeRegistrationRetryNonce] =
+    useState(0);
+  const [bridgeRegistrationError, setBridgeRegistrationError] = useState<{
+    bridgeKey: string;
+    message: string;
+  } | null>(null);
+  // Cache of the bridgeInstanceId returned by the client's LAST successful
+  // /live-edit-bridge registration POST (see the registration effect below).
+  // Compared against a later /health probe's bridgeInstanceId to tell "the
+  // bridge process restarted since we registered" apart from "the same
+  // process really doesn't know this key" — see classifyLiveEditHealthProbe
+  // above.
+  const bridgeInstanceIdRef = useRef<string | null>(null);
+  // A destructive watchdog outcome replaces the live iframe with the neutral
+  // pending document. The live document can still have queued its ready
+  // handshake immediately before that replacement; once unmounted, its
+  // WindowProxy no longer equals iframeRef.current.contentWindow and would be
+  // rejected by the normal bridge trust check. Preserve exactly that retired
+  // generation so its late ready can restore the matching bridge key. Both
+  // source-window identity and bridge-key identity must match, preventing a
+  // stale document from reviving a different screen/script generation.
+  const lateLiveEditReadyRecoveryRef = useRef<{
+    source: Window;
+    bridgeKey: string;
+    registrationHandoffKey: string | null;
+  } | null>(null);
+  // Guards the auto-reregister probe below against overlapping runs and bounds
+  // how many times it will silently retry before giving up and surfacing the
+  // existing error/Retry UI (MAX_LIVE_EDIT_RESTART_ATTEMPTS). This budget is
+  // specific to the "reregister" (different bridgeInstanceId, genuine bridge
+  // restart) loop — the same-instance-id "escalate" loop below has its own,
+  // separate ceiling and does not consume this budget.
+  const liveEditRestartInFlightRef = useRef(false);
+  const liveEditRestartAttemptRef = useRef(0);
+  // Same-instance-id ("escalate") loop state: how long we've cumulatively
+  // waited on THIS bridge key while /health keeps confirming the bridge
+  // process is healthy, the current per-arm wait, and the pending re-arm
+  // timer (so it can be cancelled on ready/unmount/key-change). See
+  // handleSuspectedBridgeRestart and classifyLiveEditHealthProbe above.
+  const liveEditSameInstanceElapsedMsRef = useRef(0);
+  const liveEditSameInstanceDelayRef = useRef(LIVE_EDIT_READY_TIMEOUT_MS);
+  const liveEditSameInstanceRearmTimerRef = useRef<number | undefined>(
+    undefined,
+  );
+  // Non-destructive counterpart to bridgeRegistrationError: shown as an
+  // overlay error/Retry card WITHOUT nulling registeredLiveEditBridgeKey, so
+  // the still-loading iframe is never torn down while it's shown. Only set
+  // once the same-instance-id escalation loop above exceeds its ceiling; a
+  // late ready handshake clears it (see the message-handler branch below).
+  const [
+    liveEditSameInstanceStalledError,
+    setLiveEditSameInstanceStalledError,
+  ] = useState<{
+    bridgeKey: string;
+    message: string;
+  } | null>(null);
+  // Set on unmount so the async /health probe (and its escalation re-arm
+  // timer) never touches state after this component is gone.
+  const isUnmountedRef = useRef(false);
+  useEffect(
+    () => () => {
+      isUnmountedRef.current = true;
+      if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+        window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+        liveEditSameInstanceRearmTimerRef.current = undefined;
+      }
+    },
+    [],
+  );
   const onExternalContentSnapshotRef = useRef(onExternalContentSnapshot);
   const isEmbeddedFrame = Boolean(embeddedFrame);
   // Resolve the URL to render in the iframe:
@@ -912,6 +1183,10 @@ export function DesignCanvas({
     }
     return getExternalPreviewUrl(renderedContent);
   }, [fusionUrl, renderedContent, sourceType]);
+  const runtimeLayerSnapshotEnabled =
+    sourceType === "localhost" &&
+    Boolean(rawExternalPreviewUrl) &&
+    Boolean(onRuntimeLayerSnapshot);
   const activeExternalSnapshotHtml =
     externalSnapshotHtml ??
     (fetchedExternalSnapshot?.url === rawExternalPreviewUrl
@@ -921,6 +1196,21 @@ export function DesignCanvas({
   // registered with the localhost bridge via a large POST, so folding live zoom
   // in would re-fire the registration effect on every zoom tick. Live scale is
   // pushed separately over the `set-editor-chrome-scale` postMessage below.
+  //
+  // readOnly and editMode are ALSO intentionally excluded from the deps below
+  // (only read for their FIRST-render baked value) — mirroring the srcdoc
+  // useMemo's own "readOnly and editMode are intentionally NOT deps" comment
+  // for inline screens further down this file. Before this fix, this memo
+  // (unlike the inline srcdoc one) DID list them as deps: every readOnly/
+  // editMode change rebuilt this script, which changed liveEditBridgeKey
+  // (its contentHash), which is embedded in the localhost iframe's `src` via
+  // resolveLiveEditPreviewUrl — so a routine Edit ⇄ Preview toggle (or a
+  // canEditDesign permission flip) forced a real cross-origin navigation of
+  // the embedded dev-server iframe, losing its in-app route/scroll/state.
+  // Live readOnly/editMode changes flow through the set-read-only and
+  // set-text-editing-enabled postMessages (see the useEffects below) exactly
+  // like the inline path, so no live-update behavior is lost by removing
+  // them here.
   const editorChromeBridgeForCurrentState = useMemo(
     () =>
       buildEditorChromeBridgeScript({
@@ -930,19 +1220,24 @@ export function DesignCanvas({
         editorChromeScaleY: 1,
         screenId: screenId ?? contentKey ?? "",
         boardSurface,
+        contentOffsetX: embeddedFrame?.contentOffsetX ?? 0,
+        contentOffsetY: embeddedFrame?.contentOffsetY ?? 0,
+        runtimeLayerSnapshotEnabled,
       }),
-    [boardSurface, contentKey, editMode, readOnly, screenId],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [boardSurface, contentKey, runtimeLayerSnapshotEnabled, screenId],
   );
+  // Keep the installed gesture script identical between overview and focused
+  // mode. The live flags are posted below; baking `isEmbeddedFrame` into the
+  // script changed the bridge key during Full view and defeated the
+  // registration handoff cache, forcing an avoidable iframe navigation.
   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",
-      ),
-    [interactMode, isEmbeddedFrame, readOnly],
+        "false",
+      ).replace("__EMBEDDED_SPACE_KEY_FORWARDING_ENABLED__", "false"),
+    [],
   );
   const includeLiveEditEditorChrome = !interactMode && !readOnly;
   const liveEditBridgeScript = useMemo(
@@ -966,6 +1261,10 @@ export function DesignCanvas({
     () => contentHash(liveEditBridgeScript),
     [liveEditBridgeScript],
   );
+  const registrationHandoffKey = liveEditRegistrationHandoffKey(
+    bridgeUrl,
+    liveEditBridgeKey,
+  );
   const hasLiveEditExternalFrame =
     sourceType === "localhost" && Boolean(bridgeUrl && rawExternalPreviewUrl);
   const hasAuthenticatedLiveEditExternalFrame =
@@ -975,9 +1274,14 @@ export function DesignCanvas({
     Boolean(bridgeUrl && previewToken && rawExternalPreviewUrl);
   const usesLiveEditEditorBridge =
     usesLiveEditInjectedBridge && includeLiveEditEditorChrome;
+  const effectiveRegisteredLiveEditBridgeKey =
+    registeredLiveEditBridgeKey ??
+    (hasRecentLiveEditRegistration(registrationHandoffKey)
+      ? liveEditBridgeKey
+      : null);
   const liveEditBridgeRegistered =
     usesLiveEditInjectedBridge &&
-    registeredLiveEditBridgeKey === liveEditBridgeKey;
+    effectiveRegisteredLiveEditBridgeKey === liveEditBridgeKey;
   // 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
@@ -995,7 +1299,7 @@ export function DesignCanvas({
     previewToken,
     previewUrl: rawExternalPreviewUrl,
     bridgeKey: liveEditBridgeKey,
-    registeredBridgeKey: registeredLiveEditBridgeKey,
+    registeredBridgeKey: effectiveRegisteredLiveEditBridgeKey,
   });
   const iframeRenderContent =
     !hasAuthenticatedLiveEditExternalFrame && activeExternalSnapshotHtml
@@ -1024,16 +1328,45 @@ export function DesignCanvas({
 
   // Register the editor bridge script with the localhost live-edit bridge so
   // it gets injected into the proxied preview. Re-runs only when the script
-  // content (liveEditBridgeKey) or the bridge target changes.
+  // content (liveEditBridgeKey) or the bridge target changes (or a retry —
+  // auto or manual — bumps bridgeRegistrationRetryNonce).
+  //
+  // Mirrors the external-source-snapshot fetch effect's own retry/backoff:
+  // a transient failure used to leave registeredLiveEditBridgeKey stuck at
+  // null forever (console.warn only, no retry, no error UI), pinning
+  // waitingForLiveEditBridge true with no way to recover short of a full
+  // page reload.
   useEffect(() => {
     if (!usesLiveEditInjectedBridge || !bridgeUrl || !previewToken) {
+      bridgeRegistrationRetryAttemptRef.current = 0;
+      liveEditRestartAttemptRef.current = 0;
+      liveEditSameInstanceElapsedMsRef.current = 0;
+      liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+      if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+        window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+        liveEditSameInstanceRearmTimerRef.current = undefined;
+      }
       setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError(null);
+      setLiveEditSameInstanceStalledError(null);
+      lateLiveEditReadyRecoveryRef.current = null;
       return;
     }
     let cancelled = false;
+    let retryTimer: number | undefined;
     setRegisteredLiveEditBridgeKey((current) =>
       current === liveEditBridgeKey ? current : null,
     );
+    const scheduleRetry = () => {
+      if (cancelled) return;
+      const delay = getSnapshotRetryDelayMs(
+        bridgeRegistrationRetryAttemptRef.current,
+      );
+      bridgeRegistrationRetryAttemptRef.current += 1;
+      retryTimer = window.setTimeout(() => {
+        setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+      }, delay);
+    };
     void (async () => {
       const endpoint = new URL("/live-edit-bridge", bridgeUrl).toString();
       try {
@@ -1051,25 +1384,320 @@ export function DesignCanvas({
         if (!response.ok) {
           throw new Error(`Bridge registration failed (${response.status})`);
         }
-        if (!cancelled) setRegisteredLiveEditBridgeKey(liveEditBridgeKey);
+        const payload = (await response.json().catch(() => null)) as {
+          bridgeInstanceId?: string;
+        } | null;
+        if (payload && typeof payload.bridgeInstanceId === "string") {
+          // Cache the instance id from THIS successful registration so a
+          // later suspected-restart probe (see handleSuspectedBridgeRestart)
+          // can tell a genuinely restarted bridge process apart from the same
+          // process rejecting a stale key.
+          bridgeInstanceIdRef.current = payload.bridgeInstanceId;
+        }
+        if (cancelled) return;
+        bridgeRegistrationRetryAttemptRef.current = 0;
+        if (registrationHandoffKey) {
+          liveEditRegistrationHandoff.set(registrationHandoffKey, Date.now());
+        }
+        // liveEditRestartAttemptRef is intentionally NOT reset here: a
+        // successful registration POST only proves the bridge accepted the
+        // script, not that the live document actually loaded it (that's what
+        // the ready-handshake watchdog below still has to confirm). Resetting
+        // the restart budget on every registration success — rather than only
+        // on a genuine agent-native:editor-chrome-ready — would let a
+        // pathological bridge that keeps minting a new bridgeInstanceId
+        // reregister forever, defeating MAX_LIVE_EDIT_RESTART_ATTEMPTS.
+        setBridgeRegistrationError(null);
+        lateLiveEditReadyRecoveryRef.current = null;
+        setRegisteredLiveEditBridgeKey(liveEditBridgeKey);
       } catch (error) {
         if (!cancelled) {
+          if (registrationHandoffKey) {
+            liveEditRegistrationHandoff.delete(registrationHandoffKey);
+          }
           console.warn("live-edit bridge registration failed", error);
           setRegisteredLiveEditBridgeKey(null);
+          setBridgeRegistrationError({
+            bridgeKey: liveEditBridgeKey,
+            message: error instanceof Error ? error.message : String(error),
+          });
+          scheduleRetry();
         }
       }
     })();
     return () => {
       cancelled = true;
+      if (retryTimer) window.clearTimeout(retryTimer);
     };
   }, [
+    bridgeRegistrationRetryNonce,
     bridgeUrl,
     liveEditBridgeKey,
     liveEditBridgeScript,
     previewToken,
+    registrationHandoffKey,
     usesLiveEditInjectedBridge,
   ]);
 
+  // A liveEditBridgeKey change means the registered script content changed
+  // (different screen, mode, or scale bake) — a completely new registration
+  // target. Reset the reregister-attempt budget and the same-instance-id
+  // escalation state (elapsed wait, backoff delay, pending re-arm timer, and
+  // any stalled-error card) so a previous screen's exhausted retries/backoff
+  // never leak into this new screen's fresh watchdog cycle. Deliberately
+  // separate from the watchdog-arm effect below, which resets the escalation
+  // state on every successful (re)registration INCLUDING same-key reregister
+  // cycles — liveEditRestartAttemptRef must NOT reset on those, or the
+  // MAX_LIVE_EDIT_RESTART_ATTEMPTS budget it guards would never trip (see
+  // that effect's own comment).
+  useEffect(() => {
+    liveEditRestartAttemptRef.current = 0;
+    liveEditSameInstanceElapsedMsRef.current = 0;
+    liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+    if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+      window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+      liveEditSameInstanceRearmTimerRef.current = undefined;
+    }
+    setLiveEditSameInstanceStalledError(null);
+    lateLiveEditReadyRecoveryRef.current = null;
+  }, [liveEditBridgeKey]);
+
+  // Manual retry (offline-state "Retry" button): reset the backoff so the
+  // user-initiated attempt fires immediately, mirroring
+  // handleManualSnapshotRetry below. Also clears the non-destructive
+  // same-instance-id stalled-error card and its escalation state, since a
+  // manual retry (from either error card) should start every counter fresh.
+  const handleManualBridgeRegistrationRetry = useCallback(() => {
+    bridgeRegistrationRetryAttemptRef.current = 0;
+    liveEditRestartAttemptRef.current = 0;
+    liveEditSameInstanceElapsedMsRef.current = 0;
+    liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+    if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+      window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+      liveEditSameInstanceRearmTimerRef.current = undefined;
+    }
+    setLiveEditSameInstanceStalledError(null);
+    setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+  }, []);
+
+  // The registered iframe's `src` is a real cross-origin navigation straight
+  // to the bridge's authenticated /live-edit URL, so this component can never
+  // read that response's status or body (a 409 "unknown-bridge-key" looks
+  // identical to any other document from here). What IS observable is
+  // whether the editor-chrome bridge's "agent-native:editor-chrome-ready"
+  // handshake (see the message handler below) arrives within a reasonable
+  // window after we mounted the real document. A healthy load posts ready
+  // almost immediately; a 409 never injects the bridge script at all, so
+  // ready never arrives. Treat a stuck non-ready state as a suspected restart
+  // and settle it with a /health probe instead of guessing from the error UI.
+  const handleSuspectedBridgeRestart = useCallback(async () => {
+    if (!bridgeUrl || !previewToken) return;
+    if (liveEditRestartInFlightRef.current) return;
+    liveEditRestartInFlightRef.current = true;
+    try {
+      const response = await fetch(healthEndpointUrl(bridgeUrl));
+      const payload = (await response.json().catch(() => null)) as {
+        bridgeInstanceId?: string;
+      } | null;
+      if (isUnmountedRef.current) return;
+      const responseBridgeInstanceId =
+        payload && typeof payload.bridgeInstanceId === "string"
+          ? payload.bridgeInstanceId
+          : null;
+      const decision = classifyLiveEditHealthProbe(
+        bridgeInstanceIdRef.current,
+        responseBridgeInstanceId,
+      );
+      if (decision === "reregister") {
+        if (
+          liveEditRestartAttemptRef.current >= MAX_LIVE_EDIT_RESTART_ATTEMPTS
+        ) {
+          if (registrationHandoffKey) {
+            liveEditRegistrationHandoff.delete(registrationHandoffKey);
+          }
+          const lateReadySource = iframeRef.current?.contentWindow;
+          lateLiveEditReadyRecoveryRef.current = lateReadySource
+            ? {
+                source: lateReadySource,
+                bridgeKey: liveEditBridgeKey,
+                registrationHandoffKey,
+              }
+            : null;
+          setRegisteredLiveEditBridgeKey(null);
+          setBridgeRegistrationError({
+            bridgeKey: liveEditBridgeKey,
+            message: t("designCanvas.localBridge.confirmationRetryExhausted"),
+          });
+          return;
+        }
+        liveEditRestartAttemptRef.current += 1;
+        if (registrationHandoffKey) {
+          liveEditRegistrationHandoff.delete(registrationHandoffKey);
+        }
+        // The bridge process restarted since our last registration — silently
+        // re-POST the same script/key and reload the frame. Resetting
+        // registeredLiveEditBridgeKey (without setting an error) re-arms the
+        // "Preparing live editor..." placeholder — the same neutral state
+        // already shown on first connect — and bumping the retry nonce
+        // re-triggers the registration effect above.
+        bridgeInstanceIdRef.current = responseBridgeInstanceId;
+        setRegisteredLiveEditBridgeKey(null);
+        setBridgeRegistrationError(null);
+        setLiveEditSameInstanceStalledError(null);
+        // A genuine restart makes any same-instance-id wait we'd accumulated
+        // against the OLD process meaningless — reset the escalation clock so
+        // the fresh document this reregister produces gets the full ceiling,
+        // not whatever was left over from the previous one.
+        liveEditSameInstanceElapsedMsRef.current = 0;
+        liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+        if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+          window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+          liveEditSameInstanceRearmTimerRef.current = undefined;
+        }
+        setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+        return;
+      }
+      if (decision === "escalate") {
+        // Same bridge process, still healthy and reachable — the page is
+        // just slow (e.g. a cold dev-server compile), not actually failing.
+        // Do NOT touch registeredLiveEditBridgeKey or bridgeRegistrationError
+        // here: that would tear down the still-legitimately-loading iframe
+        // (the regression this fix addresses). Re-arm with a longer wait
+        // instead, up to a generous total ceiling, before finally surfacing a
+        // separate NON-destructive error card that leaves the iframe alone.
+        liveEditSameInstanceElapsedMsRef.current +=
+          liveEditSameInstanceDelayRef.current;
+        if (
+          liveEditSameInstanceElapsedMsRef.current >=
+          LIVE_EDIT_SAME_INSTANCE_ERROR_CEILING_MS
+        ) {
+          setLiveEditSameInstanceStalledError({
+            bridgeKey: liveEditBridgeKey,
+            message: t("designCanvas.localBridge.connectionNotConfirmed"),
+          });
+          return;
+        }
+        const nextDelay = Math.min(
+          liveEditSameInstanceDelayRef.current * 2,
+          LIVE_EDIT_SAME_INSTANCE_MAX_REARM_DELAY_MS,
+        );
+        liveEditSameInstanceDelayRef.current = nextDelay;
+        if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+          window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+        }
+        liveEditSameInstanceRearmTimerRef.current = window.setTimeout(() => {
+          liveEditSameInstanceRearmTimerRef.current = undefined;
+          if (isUnmountedRef.current || bridgeReadyRef.current) return;
+          void handleSuspectedBridgeRestart();
+        }, nextDelay);
+        return;
+      }
+      // decision === "error": no bridgeInstanceId on one or both sides, so we
+      // can't confirm the same-process-still-healthy story above. Treat this
+      // as a genuine, unresolved failure and surface the existing
+      // (destructive) error/Retry UI instead of looping forever.
+      if (registrationHandoffKey) {
+        liveEditRegistrationHandoff.delete(registrationHandoffKey);
+      }
+      const lateReadySource = iframeRef.current?.contentWindow;
+      lateLiveEditReadyRecoveryRef.current = lateReadySource
+        ? {
+            source: lateReadySource,
+            bridgeKey: liveEditBridgeKey,
+            registrationHandoffKey,
+          }
+        : null;
+      setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError({
+        bridgeKey: liveEditBridgeKey,
+        message: t("designCanvas.localBridge.connectionNotConfirmed"),
+      });
+    } catch (error) {
+      if (isUnmountedRef.current) return;
+      // /health itself is unreachable (network error / thrown before a
+      // response) — the dev server process is actually down, not just slow.
+      // This destructive path (tear down + surface the error) is justified.
+      if (registrationHandoffKey) {
+        liveEditRegistrationHandoff.delete(registrationHandoffKey);
+      }
+      const lateReadySource = iframeRef.current?.contentWindow;
+      lateLiveEditReadyRecoveryRef.current = lateReadySource
+        ? {
+            source: lateReadySource,
+            bridgeKey: liveEditBridgeKey,
+            registrationHandoffKey,
+          }
+        : null;
+      setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError({
+        bridgeKey: liveEditBridgeKey,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      liveEditRestartInFlightRef.current = false;
+    }
+  }, [bridgeUrl, liveEditBridgeKey, previewToken, registrationHandoffKey, t]);
+
+  // Manual retry for the NON-destructive same-instance-id stalled card only
+  // (see liveEditSameInstanceStalledError below): unlike
+  // handleManualBridgeRegistrationRetry, registeredLiveEditBridgeKey was
+  // never nulled here, so bumping bridgeRegistrationRetryNonce would not
+  // reschedule a fresh watchdog probe (liveEditBridgeRegistered never flips
+  // false→true to rearm that effect). Reset the backoff and probe /health
+  // again directly instead.
+  const handleManualLiveEditSameInstanceRetry = useCallback(() => {
+    liveEditSameInstanceElapsedMsRef.current = 0;
+    liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+    if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+      window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+      liveEditSameInstanceRearmTimerRef.current = undefined;
+    }
+    setLiveEditSameInstanceStalledError(null);
+    void handleSuspectedBridgeRestart();
+  }, [handleSuspectedBridgeRestart]);
+
+  // Arm the ready-handshake watchdog whenever the real authenticated live-edit
+  // document is (re)mounted in editor-chrome mode (the only mode that ever
+  // posts agent-native:editor-chrome-ready — see usesLiveEditEditorBridge).
+  // liveEditBridgeRegistered flips false→true on every fresh mount (including
+  // the reregister cycle above), so this effect reliably rearms each time.
+  //
+  // NOTE: deliberately does NOT reset the same-instance-id escalation refs
+  // (liveEditSameInstance*) here even though this effect conceptually marks a
+  // fresh mount: handleSuspectedBridgeRestart depends on `t`, whose identity
+  // is not guaranteed stable across renders (see useT), so this effect's own
+  // dependency array can cause it to re-run on unrelated re-renders — not
+  // only on a genuine fresh mount. Resetting escalation state here would
+  // then race with (and can clobber) the very state update that triggered
+  // that extra re-render, e.g. immediately wiping the non-destructive stalled
+  // error the moment it's set. The escalation refs are instead reset from
+  // known-good, less-churny signals: the liveEditBridgeKey-keyed effect below
+  // (genuinely new script/screen) and the "reregister" branch inside
+  // handleSuspectedBridgeRestart itself (genuine bridge-process restart).
+  useEffect(() => {
+    if (
+      !usesLiveEditEditorBridge ||
+      !liveEditBridgeRegistered ||
+      !externalPreviewUrl
+    ) {
+      return;
+    }
+    let cancelled = false;
+    const timer = window.setTimeout(() => {
+      if (cancelled || bridgeReadyRef.current) return;
+      void handleSuspectedBridgeRestart();
+    }, LIVE_EDIT_READY_TIMEOUT_MS);
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [
+    usesLiveEditEditorBridge,
+    liveEditBridgeRegistered,
+    externalPreviewUrl,
+    handleSuspectedBridgeRestart,
+  ]);
+
   useEffect(() => {
     const previewUrl = rawExternalPreviewUrl;
     if (
@@ -1326,7 +1954,16 @@ export function DesignCanvas({
           .replace(
             "__DESIGN_CANVAS_BOARD_SURFACE__",
             boardSurface ? "true" : "false",
-          );
+          )
+          .replace(
+            "__DESIGN_CANVAS_CONTENT_OFFSET_X__",
+            String(Math.round(embeddedFrame?.contentOffsetX ?? 0)),
+          )
+          .replace(
+            "__DESIGN_CANVAS_CONTENT_OFFSET_Y__",
+            String(Math.round(embeddedFrame?.contentOffsetY ?? 0)),
+          )
+          .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "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
@@ -1380,8 +2017,6 @@ export function DesignCanvas({
     externalPreviewUrl,
     interactMode,
     isEmbeddedFrame,
-    embeddedFrame?.contentOffsetX,
-    embeddedFrame?.contentOffsetY,
     embeddedFrameBackground,
     embeddedGestureBridgeForCurrentState,
     iframeRenderContent,
@@ -1398,11 +2033,22 @@ export function DesignCanvas({
     previousIframeDocumentIdentityRef.current = iframeDocumentIdentity;
     bridgeReadyRef.current = false;
   }
+  const liveEditDocumentPending =
+    usesLiveEditEditorBridge &&
+    Boolean(externalPreviewUrl) &&
+    readyIframeDocumentIdentity !== iframeDocumentIdentity;
+  const liveEditTransitionFallbackHtml = liveEditDocumentPending
+    ? activeExternalSnapshotHtml
+    : undefined;
 
   // Listen for messages from the iframe
   useEffect(() => {
     function handleMessage(e: MessageEvent) {
       const iframeWindow = iframeRef.current?.contentWindow;
+      const lateReadyRecovery =
+        e.data?.type === "agent-native:editor-chrome-ready"
+          ? lateLiveEditReadyRecoveryRef.current
+          : null;
       // For fusion sources the Builder-hosted app is cross-origin, so the strict
       // `origin === parentOrigin` check can never match. We still require window
       // identity (the message must come from our own iframe window, not any
@@ -1411,7 +2057,7 @@ export function DesignCanvas({
       // *.builder.io family) before relaxing the origin check. If the origin is
       // not on the allowlist we keep the strict check so a hostile frame that
       // somehow shares our window reference still can't be trusted.
-      const trusted =
+      const trustedCurrentFrame =
         sourceType === "fusion"
           ? iframeWindow !== null &&
             e.source === iframeWindow &&
@@ -1428,12 +2074,80 @@ export function DesignCanvas({
                     )
                   : [],
             });
+      const trustedLateLiveEditReady =
+        sourceType === "localhost" &&
+        lateReadyRecovery !== null &&
+        lateReadyRecovery.bridgeKey === liveEditBridgeKey &&
+        isTrustedCanvasBridgeMessage({
+          source: e.source,
+          origin: e.origin,
+          iframeWindow: lateReadyRecovery.source,
+          parentOrigin: window.location.origin,
+          allowedOrigins: [originFromUrl(bridgeUrl)].filter(
+            (origin): origin is string => Boolean(origin),
+          ),
+        });
+      const trusted = trustedCurrentFrame || trustedLateLiveEditReady;
       if (!trusted) {
         return;
       }
       if (!e.data || !e.data.type) return;
+      if (e.data.type === "agent-native:runtime-layer-snapshot") {
+        const payload = e.data.payload;
+        if (
+          payload &&
+          typeof payload.html === "string" &&
+          payload.html.length <= 2_000_000 &&
+          Number.isFinite(payload.nodeCount)
+        ) {
+          onRuntimeLayerSnapshot?.({
+            html: payload.html,
+            nodeCount: Math.max(0, Math.floor(payload.nodeCount)),
+          });
+        }
+        return;
+      }
       if (e.data.type === "agent-native:editor-chrome-ready") {
+        if (trustedLateLiveEditReady && lateReadyRecovery) {
+          // This handshake belongs to the one retired live document saved by
+          // the destructive watchdog path, not the pending iframe now in the
+          // DOM. Restore its exact registration generation and let the newly
+          // mounted live document send the normal ready signal; do not mark
+          // the pending document ready or flush one-shot messages into it.
+          lateLiveEditReadyRecoveryRef.current = null;
+          if (lateReadyRecovery.registrationHandoffKey) {
+            liveEditRegistrationHandoff.set(
+              lateReadyRecovery.registrationHandoffKey,
+              Date.now(),
+            );
+          }
+          setBridgeRegistrationError((current) =>
+            current?.bridgeKey === lateReadyRecovery.bridgeKey ? null : current,
+          );
+          setRegisteredLiveEditBridgeKey(lateReadyRecovery.bridgeKey);
+          return;
+        }
+        lateLiveEditReadyRecoveryRef.current = null;
         bridgeReadyRef.current = true;
+        setReadyIframeDocumentIdentity(iframeDocumentIdentity);
+        // A confirmed ready handshake proves this bridgeInstanceId/key pair
+        // is genuinely live — clear the suspected-restart attempt counter so
+        // a later transient hiccup gets the full retry budget again instead
+        // of inheriting an already-elevated count from an unrelated earlier
+        // load.
+        liveEditRestartAttemptRef.current = 0;
+        // A late ready handshake wins even after the same-instance-id
+        // escalation loop gave up and showed its non-destructive error card:
+        // cancel any pending re-arm timer, reset the backoff, and clear the
+        // error so the now-loaded iframe (which was never torn down) reads
+        // as fully connected.
+        if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+          window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+          liveEditSameInstanceRearmTimerRef.current = undefined;
+        }
+        liveEditSameInstanceElapsedMsRef.current = 0;
+        liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+        setLiveEditSameInstanceStalledError(null);
         flushPendingOneShotMessages();
         return;
       }
@@ -1577,8 +2291,13 @@ export function DesignCanvas({
               sourceId,
               anchorSourceId,
               dropMode,
+              forceFlowPositionOverride:
+                e.data.forceFlowPositionOverride === true,
               sourceRect,
               anchorRect,
+              anchorElementInfo: isElementInfoPayload(e.data.anchorPayload)
+                ? e.data.anchorPayload
+                : undefined,
             },
           );
           if (requestId && applied !== "pending") {
@@ -1705,11 +2424,39 @@ export function DesignCanvas({
               ? iframeRect.height / iframe.clientHeight
               : 1;
           onIframeContextMenu?.({
+            screenId:
+              typeof e.data.screenId === "string" ? e.data.screenId : undefined,
             clientX,
             clientY,
             viewportClientX: (iframeRect?.left ?? 0) + clientX * scaleX,
             viewportClientY: (iframeRect?.top ?? 0) + clientY * scaleY,
             info: e.data.payload ?? null,
+            layerCandidates: Array.isArray(e.data.layerCandidates)
+              ? e.data.layerCandidates
+                  .filter(
+                    (candidate: unknown) =>
+                      candidate &&
+                      typeof candidate === "object" &&
+                      isElementInfoPayload(
+                        (candidate as { info?: unknown }).info,
+                      ),
+                  )
+                  .map((candidate: any, index: number) => ({
+                    key:
+                      typeof candidate.key === "string"
+                        ? candidate.key
+                        : `layer-hit-${index}`,
+                    label:
+                      typeof candidate.label === "string"
+                        ? candidate.label.slice(0, 80)
+                        : "Layer",
+                    screenId:
+                      typeof e.data.screenId === "string"
+                        ? e.data.screenId
+                        : undefined,
+                    info: candidate.info,
+                  }))
+              : [],
           });
         }
         return;
@@ -1842,6 +2589,7 @@ export function DesignCanvas({
     return () => window.removeEventListener("message", handleMessage);
   }, [
     onElementSelect,
+    onRuntimeLayerSnapshot,
     onElementMarqueeSelect,
     onElementHover,
     onClearSelection,
@@ -1863,6 +2611,7 @@ export function DesignCanvas({
     isEmbeddedFrame,
     sourceType,
     bridgeUrl,
+    liveEditBridgeKey,
     fusionUrl,
     flushPendingOneShotMessages,
     postOneShotBridgeMessage,
@@ -2127,6 +2876,66 @@ export function DesignCanvas({
     postOneShotBridgeMessage,
   ]);
 
+  // Overview/focused placement is presentation state, not document identity.
+  // Update gesture routing in place so entering Full view reuses the same
+  // registered bridge key instead of rebuilding the injected script.
+  useEffect(() => {
+    postOneShotBridgeMessage({
+      type: "embedded-canvas-gesture-mode",
+      wheelEnabled: isEmbeddedFrame,
+      spaceKeyForwardingEnabled: interactMode || readOnly,
+    });
+  }, [interactMode, isEmbeddedFrame, postOneShotBridgeMessage, readOnly]);
+
+  // The board iframe is a finite paint window over an infinite logical
+  // canvas. Re-centering that window must update its CSS/bridge coordinate
+  // offset in place; rebuilding srcdoc here would reload the iframe, flash,
+  // and discard transient Alpine state on every chunk crossing.
+  const embeddedContentOffsetX = embeddedFrame?.contentOffsetX ?? 0;
+  const embeddedContentOffsetY = embeddedFrame?.contentOffsetY ?? 0;
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const applyOffset = () => {
+      try {
+        const doc = iframe.contentDocument;
+        if (doc) {
+          const css = embeddedContentOffsetCss(
+            embeddedContentOffsetX,
+            embeddedContentOffsetY,
+          );
+          let style = doc.querySelector<HTMLStyleElement>(
+            "style[data-agent-native-content-offset]",
+          );
+          if (!css) {
+            style?.remove();
+          } else {
+            if (!style) {
+              style = doc.createElement("style");
+              style.setAttribute("data-agent-native-content-offset", "");
+              (doc.head ?? doc.documentElement).appendChild(style);
+            }
+            style.textContent = css;
+          }
+        }
+      } catch {
+        // Cross-origin localhost/fusion frames are updated only through their
+        // own bridge below; direct document access is intentionally optional.
+      }
+      iframe.contentWindow?.postMessage(
+        {
+          type: "set-content-offset",
+          x: embeddedContentOffsetX,
+          y: embeddedContentOffsetY,
+        },
+        "*",
+      );
+    };
+    applyOffset();
+    iframe.addEventListener("load", applyOffset);
+    return () => iframe.removeEventListener("load", applyOffset);
+  }, [embeddedContentOffsetX, embeddedContentOffsetY]);
+
   // Sync readOnly to the bridge IN-PLACE via postMessage so switching the active
   // surface (board ↔ screen) does not rebuild srcdoc / reload the iframe.
   // The initial baked __READ_ONLY__ placeholder covers first paint; subsequent
@@ -2372,6 +3181,27 @@ export function DesignCanvas({
     }
   }, [postOneShotBridgeMessage, structureAckRequest]);
 
+  const lastRuntimeStructureMoveRequestIdRef = useRef<number | null>(null);
+  useEffect(() => {
+    if (!runtimeStructureMoveRequest) return;
+    if (
+      lastRuntimeStructureMoveRequestIdRef.current ===
+      runtimeStructureMoveRequest.requestId
+    ) {
+      return;
+    }
+    lastRuntimeStructureMoveRequestIdRef.current =
+      runtimeStructureMoveRequest.requestId;
+    postOneShotBridgeMessage({
+      type: "runtime-structure-move",
+      subjectSelector: runtimeStructureMoveRequest.subject.selector,
+      subjectSourceId: runtimeStructureMoveRequest.subject.sourceId,
+      anchorSelector: runtimeStructureMoveRequest.anchor.selector,
+      anchorSourceId: runtimeStructureMoveRequest.anchor.sourceId,
+      placement: runtimeStructureMoveRequest.placement,
+    });
+  }, [postOneShotBridgeMessage, runtimeStructureMoveRequest]);
+
   /**
    * Send a motion-preview scrub tick to the iframe.  `t` is the normalised
    * playhead position in [0, 1].  Tracks must have been loaded first via the
@@ -2747,10 +3577,13 @@ export function DesignCanvas({
       const rect = iframe?.getBoundingClientRect();
       const screenContentPoint =
         iframe && rect
-          ? getScreenContentPointFromClient(e.clientX, e.clientY, rect, {
-              width: iframe.clientWidth,
-              height: iframe.clientHeight,
-            })
+          ? getScreenContentPointFromClient(
+              e.clientX,
+              e.clientY,
+              rect,
+              { width: iframe.clientWidth, height: iframe.clientHeight },
+              readIframeScrollOffset(iframe),
+            )
           : { x: e.clientX, y: e.clientY };
       onDropFiles(files, { screenContentPoint, screenId });
     },
@@ -2810,6 +3643,21 @@ export function DesignCanvas({
           : null),
       }}
     >
+      {liveEditTransitionFallbackHtml ? (
+        <iframe
+          data-live-edit-transition-fallback
+          srcDoc={liveEditTransitionFallbackHtml}
+          sandbox=""
+          aria-hidden="true"
+          tabIndex={-1}
+          className="pointer-events-none absolute inset-0 block h-full w-full border-0 bg-transparent"
+          style={{
+            background: iframeBackgroundColor,
+            backgroundColor: iframeBackgroundColor,
+          }}
+          title=""
+        />
+      ) : null}
       <iframe
         key={iframeDocumentIdentity}
         ref={iframeRef}
@@ -2829,7 +3677,10 @@ export function DesignCanvas({
             ? "localhost" // inferred — content is a URL
             : "inline")
         }
-        className="block h-full w-full border-0 bg-transparent"
+        className={cn(
+          "relative block h-full w-full border-0 bg-transparent",
+          liveEditTransitionFallbackHtml && "pointer-events-none opacity-0",
+        )}
         style={{
           background: iframeBackgroundColor,
           backgroundColor: iframeBackgroundColor,
@@ -2868,9 +3719,84 @@ export function DesignCanvas({
           </div>
         </div>
       ) : null}
-      {waitingForEditableExternalSnapshot || waitingForLiveEditBridge ? (
+      {liveEditSameInstanceStalledError?.bridgeKey === liveEditBridgeKey ? (
+        // Non-destructive counterpart to the registration-failure card below:
+        // the same-instance-id escalation loop in handleSuspectedBridgeRestart
+        // hit its ceiling, but /health confirmed the bridge process is still
+        // the one we registered with — registeredLiveEditBridgeKey was never
+        // nulled, so the iframe underneath is still the real, still-loading
+        // document rather than the blank placeholder. Render as a small
+        // floating banner (not an opaque full-cover overlay like the cards
+        // below) so that still-loading iframe stays visible, and a late
+        // agent-native:editor-chrome-ready handshake clears this card (see
+        // the message-handler branch above) even after this point.
+        <div className="pointer-events-none absolute inset-x-0 bottom-4 z-10 flex justify-center px-4">
+          <div className="pointer-events-auto flex max-w-[28rem] flex-col items-center gap-2 rounded-md border bg-card px-4 py-3 shadow-sm">
+            <div className="flex items-center gap-1.5 font-medium text-foreground">
+              <IconPlugConnectedX className="size-4 shrink-0 text-destructive" />
+              {
+                "Live editor connection failed" /* i18n-ignore local dev bridge same-instance stall title, mirrors the registration-failure card's copy */
+              }
+            </div>
+            <div className="text-xs text-muted-foreground">
+              {
+                "Is the local dev server still running?" /* i18n-ignore local dev bridge same-instance stall subtitle */
+              }
+            </div>
+            <div className="w-full truncate rounded bg-muted px-2 py-1 font-mono text-[11px] text-muted-foreground">
+              {liveEditSameInstanceStalledError.message}
+            </div>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={handleManualLiveEditSameInstanceRetry}
+            >
+              <IconRefresh className="size-3.5" />
+              {"Retry" /* i18n-ignore local dev bridge retry button */}
+            </Button>
+          </div>
+        </div>
+      ) : null}
+      {waitingForEditableExternalSnapshot ||
+      waitingForLiveEditBridge ||
+      (liveEditDocumentPending && !liveEditTransitionFallbackHtml) ? (
         <div className="pointer-events-auto absolute inset-0 z-10 flex items-center justify-center bg-background/85 px-4 text-center text-sm text-muted-foreground">
-          {waitingForLiveEditBridge ? (
+          {waitingForLiveEditBridge &&
+          bridgeRegistrationError?.bridgeKey === liveEditBridgeKey ? (
+            // Mirrors the snapshot-fetch offline card below: a stuck
+            // registration used to look identical to ordinary "still
+            // registering" with no explanation and no way to recover short
+            // of a full page reload. Only shown for the CURRENT
+            // liveEditBridgeKey — a stale error from a previous script
+            // revision must not linger after content/mode changes move on
+            // to registering a new one.
+            <div className="pointer-events-auto flex max-w-[28rem] flex-col items-center gap-2 rounded-md border bg-card px-4 py-3 shadow-sm">
+              <div className="flex items-center gap-1.5 font-medium text-foreground">
+                <IconPlugConnectedX className="size-4 shrink-0 text-destructive" />
+                {
+                  "Live editor connection failed" /* i18n-ignore local dev bridge registration failure title */
+                }
+              </div>
+              <div className="text-xs text-muted-foreground">
+                {
+                  "Is the local dev server still running?" /* i18n-ignore local dev bridge registration failure subtitle */
+                }
+              </div>
+              <div className="w-full truncate rounded bg-muted px-2 py-1 font-mono text-[11px] text-muted-foreground">
+                {bridgeRegistrationError.message}
+              </div>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={handleManualBridgeRegistrationRetry}
+              >
+                <IconRefresh className="size-3.5" />
+                {"Retry" /* i18n-ignore local dev bridge retry button */}
+              </Button>
+            </div>
+          ) : waitingForLiveEditBridge ? (
             <div className="max-w-[28rem] rounded-md border bg-card px-4 py-3 shadow-sm">
               {
                 "Preparing live editor..." /* i18n-ignore transient localhost live-edit bridge loading state */
@@ -2923,11 +3849,16 @@ export function DesignCanvas({
       {/* Draw-to-prompt overlay — sits over the iframe, NOT inside it. */}
       <SharedDrawOverlay
         visible={!!drawMode}
+        clearSignal={drawOverlayResetSignal}
+        scopeKey={screenId}
+        retainSurfaceWhenHidden={retainDrawOverlayWhenHidden}
         canvasInteractive={!pinMode}
         queuedAnnotationCount={queuedAnnotationPins.length}
         zoom={zoom}
+        sending={annotationCaptureBusy}
         onClose={() => onExitDrawMode?.()}
         onSend={(annotations, instruction, canvasSize) => {
+          if (annotationCaptureBusyRef.current) return;
           const summary = annotations
             .map((a) =>
               a.type === "path"
@@ -2960,25 +3891,70 @@ export function DesignCanvas({
             "",
             instruction || "Apply these annotations to the design.",
           ];
-          submitDesignAnnotations({
-            message: lines.join("\n"),
-            hasQueuedPins: queuedAnnotationPins.length > 0,
-            send: (message) => {
-              sendToDesignAgentChat({
+          const message = lines.join("\n");
+          const hasQueuedPins = queuedAnnotationPins.length > 0;
+
+          // Best-effort: render the annotated screen + composited drawing as
+          // ONE image the agent can see (see design-canvas/annotation-snapshot.ts),
+          // then send it alongside the existing text summary in the same chat
+          // turn. Never blocks or drops the annotation — any capture failure
+          // (no Chromium in hosted deploys, network blip, upload not
+          // configured, timeout) silently resolves to `null` and the message
+          // still goes out text-only, exactly as it did before this feature.
+          annotationCaptureBusyRef.current = true;
+          setAnnotationCaptureBusy(true);
+          onAnnotationSendingChange?.(true);
+          captureAnnotatedScreenshot({
+            designId,
+            fileId: screenId,
+            sourceType:
+              sourceType ?? (externalPreviewUrl ? "localhost" : "inline"),
+            annotations,
+            canvasSize,
+          })
+            .catch(() => null)
+            .then((imageUrl) =>
+              submitDesignAnnotations({
                 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"));
-            },
-          });
+                hasQueuedPins,
+                // Ack-confirmed send: only exit draw mode / mark pins
+                // submitted once the message is CONFIRMED to have reached
+                // the chat (became a visible turn). A fire-and-forget send
+                // here would let the overlay tear down and the pins clear
+                // even when delivery is silently dropped — e.g. no LLM/agent
+                // engine configured, or the panel never finished mounting —
+                // discarding the user's drawing with no way to retry it.
+                send: async (message) => {
+                  const result = await sendToDesignAgentChatAndConfirm({
+                    message,
+                    images: imageUrl ? [imageUrl] : undefined,
+                    submit: true,
+                    openSidebar: true,
+                  });
+                  if (!result.delivered) {
+                    throw new Error(
+                      `Annotation message was not delivered to the agent chat (${result.reason ?? "unknown"})`,
+                    );
+                  }
+                },
+                markQueuedPinsSubmitted: () => {
+                  setPinSubmitSignal((signal) => signal + 1);
+                },
+                exitDrawMode: () => onExitDrawMode?.(),
+                onError: (error) => {
+                  console.error(
+                    "[DesignCanvas] failed to submit drawing:",
+                    error,
+                  );
+                  toast.error(t("designEditor.toasts.annotationSendError"));
+                },
+              }),
+            )
+            .finally(() => {
+              annotationCaptureBusyRef.current = false;
+              setAnnotationCaptureBusy(false);
+              onAnnotationSendingChange?.(false);
+            });
         }}
       />
     </div>
@@ -3222,15 +4198,28 @@ function SingleScreenCreationOverlay({
   const [penPointer, setPenPointer] = useState<PenPoint | null>(null);
   const [penCloseHover, setPenCloseHover] = useState(false);
 
+  // Returns the click/pointer point in SCREEN-CONTENT (document-absolute)
+  // coordinates — the same "screen's own pixel coordinate system" contract
+  // `onCreatePrimitive` documents, which already folds in the embedded
+  // screen's own internal scroll (see `getScreenContentPointFromClient`).
+  // Anything that renders these points directly as this overlay's own CSS
+  // position (the drag/line preview below, and `SingleScreenPenPathOverlay`)
+  // must convert back to overlay-local (viewport-relative) coordinates by
+  // subtracting the same scroll offset — the overlay itself never scrolls
+  // with the embedded screen's internal document, it only tracks the
+  // iframe's host-page box.
   const toContentPoint = useCallback(
     (clientX: number, clientY: number) => {
       const iframe = iframeRef.current;
       const rect = iframe?.getBoundingClientRect();
       if (!iframe || !rect) return { x: clientX, y: clientY };
-      return getScreenContentPointFromClient(clientX, clientY, rect, {
-        width: iframe.clientWidth,
-        height: iframe.clientHeight,
-      });
+      return getScreenContentPointFromClient(
+        clientX,
+        clientY,
+        rect,
+        { width: iframe.clientWidth, height: iframe.clientHeight },
+        readIframeScrollOffset(iframe),
+      );
     },
     [iframeRef],
   );
@@ -3524,7 +4513,7 @@ function SingleScreenCreationOverlay({
           e.currentTarget.releasePointerCapture(e.pointerId);
         }
         if (gesture.closing) {
-          finishPenPath(nextPath);
+          finishPenPath(nextPath, { preserveActiveTool: true });
         } else {
           updatePenPath(nextPath);
         }
@@ -3602,7 +4591,7 @@ function SingleScreenCreationOverlay({
       event.preventDefault();
       event.stopPropagation();
       event.stopImmediatePropagation();
-      finishPenPath(path);
+      finishPenPath(path, { preserveActiveTool: true });
     };
 
     window.addEventListener("keydown", handleKeyDown, true);
@@ -3623,19 +4612,49 @@ function SingleScreenCreationOverlay({
   // overlay's own (unscaled, layout-space) coordinates. The overlay div is
   // sized to the iframe's layout box (via inset-0 on a wrapper that already
   // matches iframe.clientWidth/Height 1:1 before the outer zoom transform),
-  // so screen-content coordinates ARE this overlay's local coordinates —
-  // no extra scale conversion is needed for the preview's own CSS position.
+  // so screen-content coordinates equal this overlay's local coordinates
+  // when the screen is unscrolled — no extra scale conversion is needed for
+  // the preview's own CSS position. When the embedded screen IS scrolled,
+  // `drag.startContent`/`currentContent` (from `toContentPoint`) carry that
+  // scroll baked in (screen-content space is document-absolute, per
+  // `onCreatePrimitive`'s contract), but this overlay div never scrolls with
+  // the iframe's internal document — it only tracks the iframe's fixed host-
+  // page box — so the scroll must be subtracted back out here to keep the
+  // live preview aligned under the cursor.
+  const previewScrollOffset = readIframeScrollOffset(iframeRef.current);
+  const toOverlayLocal = (point: { x: number; y: number }) => ({
+    x: point.x - previewScrollOffset.left,
+    y: point.y - previewScrollOffset.top,
+  });
   const previewRect =
     drag && drag.moved && !isLineTool && tool !== "pen"
-      ? getDraftGeometryFromPoints(drag.startContent, drag.currentContent, {
-          minWidth: tool === "text" ? 24 : 8,
-          minHeight: tool === "text" ? 18 : 8,
-        })
+      ? getDraftGeometryFromPoints(
+          toOverlayLocal(drag.startContent),
+          toOverlayLocal(drag.currentContent),
+          {
+            minWidth: tool === "text" ? 24 : 8,
+            minHeight: tool === "text" ? 18 : 8,
+          },
+        )
       : null;
   const previewLine =
     drag && drag.moved && isLineTool
-      ? { start: drag.startContent, end: drag.currentContent }
+      ? {
+          start: toOverlayLocal(drag.startContent),
+          end: toOverlayLocal(drag.currentContent),
+        }
       : null;
+  // Same overlay-local conversion for the live pen path — its anchors/
+  // handles are stored in screen-content (document-absolute) space via
+  // `toContentPoint`/`getPenAnchor`, but `SingleScreenPenPathOverlay` renders
+  // them directly as this overlay's own (unscrolled) SVG/CSS coordinates.
+  const displayedPenPathOverlay = displayedPenPath
+    ? translatePenPath(
+        displayedPenPath,
+        -previewScrollOffset.left,
+        -previewScrollOffset.top,
+      )
+    : null;
 
   return (
     <div
@@ -3659,9 +4678,9 @@ function SingleScreenCreationOverlay({
         }
       }}
     >
-      {tool === "pen" && displayedPenPath ? (
+      {tool === "pen" && displayedPenPathOverlay ? (
         <SingleScreenPenPathOverlay
-          path={displayedPenPath}
+          path={displayedPenPathOverlay}
           closeHover={penCloseHover}
           iframeRef={iframeRef}
         />