@agent-native/core 0.84.1 → 0.84.3

package/corpus/core/src/client/sse-event-processor.ts

@@ -18,6 +18,8 @@ export type ContentPart =
       argsText: string;
       args: Record<string, string>;
       result?: string;
+      isError?: boolean;
+      completedSideEffect?: boolean;
       mcpApp?: AgentMcpAppPayload;
       chatUI?: ActionChatUIConfig;
       activity?: boolean;
@@ -45,6 +47,8 @@ export interface SSEEvent {
   label?: string;
   input?: Record<string, string>;
   result?: string;
+  isError?: boolean;
+  completedSideEffect?: boolean;
   mcpApp?: AgentMcpAppPayload;
   chatUI?: ActionChatUIConfig;
   /** Stable key the client echoes back in `approvedToolCalls` to approve a
@@ -80,21 +84,34 @@ export type AgentAutoContinueReason =
 
 export type AgentActivityTrailEntry = { label: string; tool?: string };
 
+export interface AgentAutoContinueErrorInfo {
+  message: string;
+  details?: string;
+  errorCode?: string;
+  recoverable?: boolean;
+  upgradeUrl?: string;
+}
+
 const INTERRUPTED_TOOL_RESULT =
   "Interrupted before this tool returned a result.";
+const INTERRUPTED_ACTIVITY_RESULT = "Stopped before this action started.";
 
 export function settleInterruptedToolCalls(
   content: ContentPart[],
   result = INTERRUPTED_TOOL_RESULT,
+  options?: { includeActivity?: boolean; activityResult?: string },
 ): boolean {
   let changed = false;
   for (const part of content) {
     if (
       part.type === "tool-call" &&
       part.result === undefined &&
-      part.activity !== true
+      (part.activity !== true || options?.includeActivity === true)
     ) {
-      part.result = result;
+      part.result =
+        part.activity === true
+          ? (options?.activityResult ?? INTERRUPTED_ACTIVITY_RESULT)
+          : result;
       changed = true;
     }
   }
@@ -105,17 +122,20 @@ export class AgentAutoContinueSignal extends Error {
   readonly reason: AgentAutoContinueReason;
   readonly maxIterations?: number;
   readonly activityTrail: AgentActivityTrailEntry[];
+  readonly errorInfo?: AgentAutoContinueErrorInfo;
 
   constructor(options: {
     reason: AgentAutoContinueReason;
     maxIterations?: number;
     activityTrail?: AgentActivityTrailEntry[];
+    errorInfo?: AgentAutoContinueErrorInfo;
   }) {
     super(`Agent run needs automatic continuation: ${options.reason}`);
     this.name = "AgentAutoContinueSignal";
     this.reason = options.reason;
     this.maxIterations = options.maxIterations;
     this.activityTrail = options.activityTrail ?? [];
+    this.errorInfo = options.errorInfo;
   }
 }
 
@@ -342,6 +362,7 @@ export function processEvent(
   autoContinue?: {
     reason: AgentAutoContinueReason;
     maxIterations?: number;
+    errorInfo?: AgentAutoContinueErrorInfo;
   };
 } {
   if (ev.type === "clear") {
@@ -508,6 +529,10 @@ export function processEvent(
       const part = content[doneIdx];
       if (part.type === "tool-call") {
         part.result = ev.result ?? "";
+        if (ev.isError !== undefined) part.isError = ev.isError;
+        if (ev.completedSideEffect !== undefined) {
+          part.completedSideEffect = ev.completedSideEffect;
+        }
         if (ev.mcpApp) part.mcpApp = ev.mcpApp;
         if (ev.chatUI) part.chatUI = ev.chatUI;
       }
@@ -598,7 +623,7 @@ export function processEvent(
         }),
       );
     }
-    settleInterruptedToolCalls(content);
+    settleInterruptedToolCalls(content, undefined, { includeActivity: true });
     content.push({
       type: "text",
       text: formatChatErrorText(errMsg, undefined, errorCode),
@@ -665,6 +690,7 @@ export function processEvent(
       (ev.errorCode === "run_timeout" && ev.recoverable) ||
       isAutoRecoverableError(ev, errMsg)
     ) {
+      const normalized = normalizeChatError(errMsg, ev.errorCode);
       return {
         action: "auto_continue",
         autoContinue: {
@@ -676,6 +702,15 @@ export function processEvent(
                   errMsg.toLowerCase().includes("timeout")
                 ? "run_timeout"
                 : "stream_ended",
+          errorInfo: {
+            message: normalized.message,
+            ...(ev.details || normalized.details
+              ? { details: ev.details ?? normalized.details }
+              : {}),
+            ...(ev.errorCode ? { errorCode: ev.errorCode } : {}),
+            recoverable: ev.recoverable ?? true,
+            ...(ev.upgradeUrl ? { upgradeUrl: ev.upgradeUrl } : {}),
+          },
         },
       };
     }
@@ -700,7 +735,7 @@ export function processEvent(
         }),
       );
     }
-    settleInterruptedToolCalls(content);
+    settleInterruptedToolCalls(content, undefined, { includeActivity: true });
     content.push({
       type: "text",
       text: formatChatErrorText(errMsg, ev.upgradeUrl, ev.errorCode),
@@ -824,6 +859,13 @@ export async function* readSSEStream(
             label: runningToolLabel(tool),
             tool,
           });
+        } else if (ev.type === "tool_done") {
+          const tool = ev.tool ?? "unknown";
+          for (let i = activityTrail.length - 1; i >= 0; i--) {
+            if (activityTrail[i]?.tool === tool) {
+              activityTrail.splice(i, 1);
+            }
+          }
         }
 
         const { action, result, autoContinue } = processEvent(

package/corpus/core/src/templates/workspace-core/.agents/skills/reliable-mutations/SKILL.md

@@ -2,9 +2,9 @@
 name: reliable-mutations
 description: >-
   How the agent must perform writes so they actually persist under the hosted
-  ~40s run budget. Use whenever you create, update, delete, or batch-write app
-  data — especially "do this for many items" loops, or any task where the user
-  expects N things to end up saved.
+  foreground run budget and long-running background handoffs. Use whenever you
+  create, update, delete, or batch-write app data — especially "do this for many
+  items" loops, or any task where the user expects N things to end up saved.
 ---
 
 # Reliable Mutations
@@ -18,15 +18,12 @@ tool ✓ alone.
 
 ## Why
 
-Hosted agent runs have a ~40s soft budget (it exists to hand off cleanly under
-the upstream gateway/function walls — it is correct and is not raisable; see the
-durable-agent-runs design doc). When you loop many sequential writes inside one
-turn, the budget can cut you off mid-loop. The run resumes in a new chunk, but
-the resume often re-does earlier steps instead of advancing, so the loop churns
-and the *saved* result ends up partial — or empty — even though each individual
-tool call appeared to succeed. The user gets told "done" while the data says
-otherwise. One atomic call commits or fails as a unit; verification turns a
-hopeful ✓ into a fact.
+Hosted foreground agent runs have a short soft budget so they can hand off
+cleanly under synchronous serverless walls. Durable background runs get a much
+longer budget, but they still should not rely on loops of many small writes:
+continuations can retry the same intent and leave partial state if each item is
+committed separately. One atomic call commits or fails as a unit; verification
+turns a hopeful ✓ into a fact.
 
 ## How
 
@@ -34,11 +31,12 @@ hopeful ✓ into a fact.
    many, set all, bulk update), pass the full batch in one call so it commits
    atomically. Check the action surface for a batch/plural form before reaching
    for a loop.
-2. **Do not loop many small writes under the run budget.** A sequence of N
-   per-item writes in one turn will race the ~40s cutoff and can leave partial
-   or no state. If no batch action exists, that is a gap in the action layer —
-   add or extend an action that accepts the batch (see the `actions` skill)
-   rather than papering over it with a loop.
+2. **Do not loop many small writes under any run budget.** A sequence of N
+   per-item writes can still leave partial or no state when a foreground run
+   hands off, a background run continues, or an upstream provider fails. If no
+   batch action exists, that is a gap in the action layer — add or extend an
+   action that accepts the batch (see the `actions` skill) rather than papering
+   over it with a loop.
 3. **Verify the end state after writing.** Re-read the data (a list/read action,
    a count query) and confirm the result matches intent — the right number of
    rows, the expected ids/fields. Do this before you tell the user it worked.

package/corpus/templates/analytics/AGENTS.md

@@ -137,7 +137,7 @@ details live in `.agents/skills/`.
   name the metrics and the server generates the validated SQL/config for every
   panel in ONE fast call. Do NOT hand-author big `update-dashboard` configs
   panel-by-panel or loop `update-dashboard` — streaming a giant multi-panel
-  argument inside the ~40s budget fails and thrashes. Unknown metric keys are
+  argument across timeout boundaries fails and thrashes. Unknown metric keys are
   skipped and reported; per-panel SQL validates independently; existing
   dashboards append by default (`overwrite: true` replaces). Report the returned
   `panelCount` as proof-of-done.

package/corpus/templates/design/actions/apply-motion-edit.ts

@@ -20,7 +20,7 @@ import {
   getRequestOrgId,
   getRequestUserEmail,
 } from "@agent-native/core/server/request-context";
-import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { assertAccess } from "@agent-native/core/sharing";
 import { and, desc, eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
@@ -70,6 +70,33 @@ const trackSchema = z.object({
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+export function resolveMotionTimelineInsertOwnership(args: {
+  requestUserEmail?: string | null;
+  requestOrgId?: string | null;
+  designOwnerEmail?: unknown;
+  designOrgId?: unknown;
+}): { ownerEmail: string; orgId: string | null } {
+  const ownerEmail =
+    nonEmptyString(args.requestUserEmail) ??
+    nonEmptyString(args.designOwnerEmail);
+
+  if (!ownerEmail) throw new Error("no authenticated user");
+
+  return {
+    ownerEmail,
+    orgId:
+      nonEmptyString(args.requestOrgId) ?? nonEmptyString(args.designOrgId),
+  };
+}
+
+export function canPatchManagedMotionCss(content: string): boolean {
+  return /<\s*(?:!doctype|[a-z][a-z0-9:-]*(?:\s|>|\/>))/i.test(content);
+}
+
 async function persistFileContent(
   fileId: string,
   designId: string,
@@ -179,16 +206,13 @@ export default defineAction({
     includeContent,
     currentContent: currentContentInput,
   }) => {
-    await assertAccess("design", designId, "editor");
+    const access = await assertAccess("design", designId, "editor");
 
     const db = getDb();
     const now = new Date().toISOString();
 
     // ── 1. Resolve the target design file ──────────────────────────────────
-    const conditions = [
-      accessFilter(schema.designs, schema.designShares),
-      eq(schema.designFiles.designId, designId),
-    ];
+    const conditions = [eq(schema.designFiles.designId, designId)];
     if (fileIdInput) {
       conditions.push(eq(schema.designFiles.id, fileIdInput));
     } else {
@@ -256,7 +280,10 @@ export default defineAction({
     });
 
     // ── 3. Inject the managed CSS block into the HTML ───────────────────────
-    const patchedContent = injectManagedMotionCss(currentContent, css);
+    const contentPatched = canPatchManagedMotionCss(currentContent);
+    const patchedContent = contentPatched
+      ? injectManagedMotionCss(currentContent, css)
+      : currentContent;
     const bytesBefore = currentContent.length;
     const bytesAfter = patchedContent.length;
 
@@ -303,11 +330,18 @@ export default defineAction({
       if (existingForSource) {
         existingTimelineId = existingForSource.id;
       } else {
-        // Insert new row — derive ownership from the request context (same
-        // pattern as create-design-state and other create actions).
-        insertOwnerEmail = getRequestUserEmail() ?? null;
-        if (!insertOwnerEmail) throw new Error("no authenticated user");
-        insertOrgId = getRequestOrgId() ?? null;
+        // Insert new row — derive ownership from the request context, falling
+        // back to the already-authorized design owner for local/public editor
+        // sessions that do not carry an authenticated request user.
+        const insertOwnership = resolveMotionTimelineInsertOwnership({
+          requestUserEmail: getRequestUserEmail(),
+          requestOrgId: getRequestOrgId(),
+          designOwnerEmail: (access.resource as { ownerEmail?: unknown })
+            .ownerEmail,
+          designOrgId: (access.resource as { orgId?: unknown }).orgId,
+        });
+        insertOwnerEmail = insertOwnership.ownerEmail;
+        insertOrgId = insertOwnership.orgId;
       }
     }
 
@@ -352,12 +386,9 @@ export default defineAction({
     // Written after the row so a SQL failure here leaves the timeline row
     // accurate (correct tracks + hash) and the stale HTML can be recompiled on
     // the next apply-motion-edit call via compiledHash drift detection.
-    const updatedAt = await persistFileContent(
-      fileId,
-      designId,
-      patchedContent,
-      now,
-    );
+    const updatedAt = contentPatched
+      ? await persistFileContent(fileId, designId, patchedContent, now)
+      : now;
 
     return {
       timelineId: resolvedTimelineId,
@@ -371,6 +402,7 @@ export default defineAction({
       bytesAfter,
       bytesDelta: bytesAfter - bytesBefore,
       persisted: true,
+      contentPatched,
       patchedContent: includeContent ? patchedContent : undefined,
     };
   },

package/corpus/templates/design/actions/get-motion-timeline.ts

@@ -1,6 +1,6 @@
 import { defineAction } from "@agent-native/core";
 import { getText, hasCollabState } from "@agent-native/core/collab";
-import { accessFilter } from "@agent-native/core/sharing";
+import { assertAccess } from "@agent-native/core/sharing";
 import { and, desc, eq } from "drizzle-orm";
 import { z } from "zod";
 
@@ -67,13 +67,8 @@ async function readManagedCssForSource(args: {
       content: schema.designFiles.content,
     })
     .from(schema.designFiles)
-    .innerJoin(
-      schema.designs,
-      eq(schema.designFiles.designId, schema.designs.id),
-    )
     .where(
       and(
-        accessFilter(schema.designs, schema.designShares),
         eq(schema.designFiles.designId, args.designId),
         eq(schema.designFiles.id, args.sourceRef),
       ),
@@ -124,12 +119,11 @@ export default defineAction({
       ),
   }),
   run: async ({ designId, timelineId, sourceRef }) => {
+    await assertAccess("design", designId, "viewer");
+
     const db = getDb();
 
-    const conditions = [
-      accessFilter(schema.designs, schema.designShares),
-      eq(schema.motionTimeline.designId, designId),
-    ];
+    const conditions = [eq(schema.motionTimeline.designId, designId)];
 
     if (timelineId) {
       conditions.push(eq(schema.motionTimeline.id, timelineId));
@@ -151,10 +145,6 @@ export default defineAction({
         updatedAt: schema.motionTimeline.updatedAt,
       })
       .from(schema.motionTimeline)
-      .innerJoin(
-        schema.designs,
-        eq(schema.motionTimeline.designId, schema.designs.id),
-      )
       .where(and(...conditions))
       .orderBy(desc(schema.motionTimeline.updatedAt))
       .limit(timelineId ? 1 : 100);

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

@@ -333,6 +333,13 @@ interface DesignCanvasProps {
     contentOffsetY?: number;
   };
   boardSurface?: boolean;
+  /**
+   * Optional live document replacement channel. When paired with
+   * `runtimeReplacementKey`, this lets callers update iframe DOM through the
+   * editor bridge without changing `srcDoc` and reloading the iframe.
+   */
+  runtimeReplacementContent?: string;
+  runtimeReplacementKey?: string;
   embeddedFrameBackground?: string;
   transparentBackground?: boolean;
   editorChromeScaleX?: number;
@@ -367,6 +374,7 @@ interface DesignCanvasProps {
   onElementDblClickText?: (info: ElementInfo) => void;
   onIframeHotkey?: (event: IframeHotkeyPayload) => void;
   onIframeContextMenu?: (event: IframeContextMenuPayload) => void;
+  onEditorDragStateChange?: (active: boolean) => void;
   onVisualStructureChange?: (
     selector: string,
     anchorSelector: string,
@@ -376,6 +384,9 @@ interface DesignCanvasProps {
       sourceId?: string;
       anchorSourceId?: string;
       requestId?: string;
+      dropMode?: "flow-insert" | "absolute-container";
+      sourceRect?: { x: number; y: number; width: number; height: number };
+      anchorRect?: { x: number; y: number; width: number; height: number };
     },
   ) => boolean | void;
   onVisualDuplicateChange?: (
@@ -571,6 +582,26 @@ function injectEmbeddedFrameStyle(content: string, style: string): string {
   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;
@@ -602,6 +633,8 @@ export function DesignCanvas({
   deviceFrame,
   embeddedFrame,
   boardSurface = false,
+  runtimeReplacementContent,
+  runtimeReplacementKey,
   embeddedFrameBackground,
   transparentBackground = false,
   editorChromeScaleX = 1,
@@ -621,6 +654,7 @@ export function DesignCanvas({
   onElementDblClickText,
   onIframeHotkey,
   onIframeContextMenu,
+  onEditorDragStateChange,
   onVisualStructureChange,
   onVisualDuplicateChange,
   tweakValues,
@@ -652,6 +686,9 @@ export function DesignCanvas({
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const zoomRef = useRef(zoom);
   const previousContentKeyRef = useRef(contentKey);
+  const runtimeReplacementContentRef = useRef(runtimeReplacementContent);
+  const runtimeReplacementKeyRef = useRef(runtimeReplacementKey);
+  const lastRuntimeReplacementKeyRef = useRef(runtimeReplacementKey);
   const [renderedContent, setRenderedContent] = useState(content);
   const [annotationPins, setAnnotationPins] = useState<CanvasPin[]>([]);
   const [pinSubmitSignal, setPinSubmitSignal] = useState(0);
@@ -707,6 +744,8 @@ export function DesignCanvas({
   const waitingForEditableExternalSnapshot =
     requiresEditableExternalSnapshot && !activeExternalSnapshotHtml;
   zoomRef.current = zoom;
+  runtimeReplacementContentRef.current = runtimeReplacementContent;
+  runtimeReplacementKeyRef.current = runtimeReplacementKey;
 
   useEffect(() => {
     onExternalContentSnapshotRef.current = onExternalContentSnapshot;
@@ -819,6 +858,7 @@ export function DesignCanvas({
   useEffect(() => {
     if (previousContentKeyRef.current !== contentKey) {
       previousContentKeyRef.current = contentKey;
+      lastRuntimeReplacementKeyRef.current = runtimeReplacementKey;
       setRenderedContent(content);
     }
     // Same-screen visual edits are already applied optimistically inside the
@@ -826,7 +866,7 @@ export function DesignCanvas({
     // reloads the iframe, flashes unstyled content, and drops selection. Only a
     // content-key change (screen switch / explicit remount) should replace the
     // iframe document here; the bridge replays inspector state after that load.
-  }, [content, contentKey]);
+  }, [content, contentKey, runtimeReplacementKey]);
 
   usePinchZoom({
     containerRef: scrollContainerRef,
@@ -879,6 +919,20 @@ export function DesignCanvas({
       NAV_BRIDGE_SCRIPT +
       embeddedWheelBridge +
       editorChromeBridge;
+    const frameContent = getEmbeddedFrameDocumentContent({
+      content: iframeRenderContent,
+      embeddedFrameBackground,
+      transparentBackground,
+      contentOffsetX: embeddedFrame?.contentOffsetX ?? 0,
+      contentOffsetY: embeddedFrame?.contentOffsetY ?? 0,
+    });
+    if (frameContent.includes("</body>")) {
+      return frameContent.replace("</body>", bridgeToInject + "</body>"); // i18n-ignore generated iframe HTML injection
+    }
+    if (frameContent.includes("</html>")) {
+      return frameContent.replace("</html>", bridgeToInject + "</html>"); // i18n-ignore generated iframe HTML injection
+    }
+    // No body/html tags — wrap it
     const frameStyle = [
       getEmbeddedFrameBackgroundStyle({
         embeddedFrameBackground,
@@ -889,17 +943,6 @@ export function DesignCanvas({
         embeddedFrame?.contentOffsetY ?? 0,
       ),
     ].join("");
-    const frameContent = injectEmbeddedFrameStyle(
-      iframeRenderContent,
-      frameStyle,
-    );
-    if (frameContent.includes("</body>")) {
-      return frameContent.replace("</body>", bridgeToInject + "</body>"); // i18n-ignore generated iframe HTML injection
-    }
-    if (frameContent.includes("</html>")) {
-      return frameContent.replace("</html>", bridgeToInject + "</html>"); // i18n-ignore generated iframe HTML injection
-    }
-    // No body/html tags — wrap it
     return `<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${frameStyle}</head><body>${iframeRenderContent}${bridgeToInject}</body></html>`;
     // editorChromeScaleX/Y are intentionally NOT deps: they only seed the initial
     // baked chrome scale. Live zoom updates flow through the set-editor-chrome-scale
@@ -968,6 +1011,10 @@ export function DesignCanvas({
       if (e.data.type === "element-hover") {
         onElementHover(e.data.payload);
       }
+      if (e.data.type === "agent-native:editor-drag-state") {
+        onEditorDragStateChange?.(Boolean(e.data.active));
+        return;
+      }
       if (e.data.type === "visual-style-change") {
         const selector = String(e.data.selector || "");
         const styles =
@@ -1001,6 +1048,39 @@ export function DesignCanvas({
           typeof e.data.anchorSourceId === "string"
             ? e.data.anchorSourceId
             : undefined;
+        const dropMode =
+          e.data.dropMode === "flow-insert" ||
+          e.data.dropMode === "absolute-container"
+            ? e.data.dropMode
+            : undefined;
+        const sourceRect =
+          e.data.sourceRect &&
+          typeof e.data.sourceRect === "object" &&
+          Number.isFinite(e.data.sourceRect.x) &&
+          Number.isFinite(e.data.sourceRect.y) &&
+          Number.isFinite(e.data.sourceRect.width) &&
+          Number.isFinite(e.data.sourceRect.height)
+            ? {
+                x: Number(e.data.sourceRect.x),
+                y: Number(e.data.sourceRect.y),
+                width: Number(e.data.sourceRect.width),
+                height: Number(e.data.sourceRect.height),
+              }
+            : undefined;
+        const anchorRect =
+          e.data.anchorRect &&
+          typeof e.data.anchorRect === "object" &&
+          Number.isFinite(e.data.anchorRect.x) &&
+          Number.isFinite(e.data.anchorRect.y) &&
+          Number.isFinite(e.data.anchorRect.width) &&
+          Number.isFinite(e.data.anchorRect.height)
+            ? {
+                x: Number(e.data.anchorRect.x),
+                y: Number(e.data.anchorRect.y),
+                width: Number(e.data.anchorRect.width),
+                height: Number(e.data.anchorRect.height),
+              }
+            : undefined;
         if (
           (selector || sourceId) &&
           (anchorSelector || anchorSourceId) &&
@@ -1017,6 +1097,9 @@ export function DesignCanvas({
               requestId,
               sourceId,
               anchorSourceId,
+              dropMode,
+              sourceRect,
+              anchorRect,
             },
           );
           if (requestId) {
@@ -1209,6 +1292,7 @@ export function DesignCanvas({
     onElementDblClickText,
     onIframeHotkey,
     onIframeContextMenu,
+    onEditorDragStateChange,
     onVisualStructureChange,
     onVisualDuplicateChange,
     onZoomChange,
@@ -1519,6 +1603,66 @@ export function DesignCanvas({
     [],
   );
 
+  const replaceRuntimeContentInPlace = useCallback(
+    (nextContent: string) => {
+      if (externalPreviewUrl) return false;
+      return replacePreviewContent(
+        getEmbeddedFrameDocumentContent({
+          content: nextContent,
+          embeddedFrameBackground,
+          transparentBackground,
+          contentOffsetX: embeddedFrame?.contentOffsetX ?? 0,
+          contentOffsetY: embeddedFrame?.contentOffsetY ?? 0,
+        }),
+        null,
+        [],
+        { forceFullDocument: true },
+      );
+    },
+    [
+      embeddedFrame?.contentOffsetX,
+      embeddedFrame?.contentOffsetY,
+      embeddedFrameBackground,
+      externalPreviewUrl,
+      replacePreviewContent,
+      transparentBackground,
+    ],
+  );
+
+  useEffect(() => {
+    if (
+      runtimeReplacementKey === undefined ||
+      runtimeReplacementContent === undefined ||
+      lastRuntimeReplacementKeyRef.current === runtimeReplacementKey
+    ) {
+      return;
+    }
+    if (replaceRuntimeContentInPlace(runtimeReplacementContent)) {
+      lastRuntimeReplacementKeyRef.current = runtimeReplacementKey;
+    }
+  }, [
+    replaceRuntimeContentInPlace,
+    runtimeReplacementContent,
+    runtimeReplacementKey,
+  ]);
+
+  const runtimeReplacementEnabled = runtimeReplacementKey !== undefined;
+  useEffect(() => {
+    if (!runtimeReplacementEnabled) return;
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const replaceLatestRuntimeContent = () => {
+      const nextContent = runtimeReplacementContentRef.current;
+      if (nextContent === undefined) return;
+      if (replaceRuntimeContentInPlace(nextContent)) {
+        lastRuntimeReplacementKeyRef.current = runtimeReplacementKeyRef.current;
+      }
+    };
+    iframe.addEventListener("load", replaceLatestRuntimeContent);
+    return () =>
+      iframe.removeEventListener("load", replaceLatestRuntimeContent);
+  }, [replaceRuntimeContentInPlace, runtimeReplacementEnabled]);
+
   const deleteRuntimeElement = useCallback(
     (selector?: string | null, candidates?: string[]) => {
       const iframe = iframeRef.current;

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

@@ -449,15 +449,14 @@ export function MotionDock({
 
         {/* Dock toolbar */}
         <div className="flex h-8 shrink-0 items-center gap-1 border-b border-border px-2">
-          {/* Collapse toggle. The label and nearby space are part of the target. */}
+          {/* Collapse toggle. The rail owns the visible Motion label. */}
           <button
             type="button"
-            className="-ml-1 flex h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-1.5 !text-[11px] font-medium uppercase tracking-wide text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:ring-1 focus-visible:ring-[var(--design-editor-accent-color)]"
+            className="-ml-1 flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:ring-1 focus-visible:ring-[var(--design-editor-accent-color)]"
             onClick={() => setOpen(false)}
             aria-label="Collapse motion dock"
           >
             <IconChevronDown className="size-3.5" />
-            <span>Motion</span>
           </button>
 
           <>