@agent-native/core 0.165.4 → 0.167.0

package/corpus/templates/design/app/pages/design-editor/code-layer-state.ts

@@ -506,11 +506,39 @@ export function camelCaseCssProperty(property: string): string {
   );
 }
 
+// The inspector reads font longhands, and a class-less element's computed
+// styles are discarded by refreshedComputedStyles — so an authored `font`
+// shorthand is the only place a family/size/weight can come from.
+function fontShorthandLonghands(value: string): Record<string, string> {
+  const match =
+    /^\s*(.*?)\s*(-?[\d.]+(?:px|r?em|%|pt)|x{1,2}-(?:small|large)|small|medium|large)\s*(?:\/\s*([^\s]+)\s*)?(\S.*)$/.exec(
+      value,
+    );
+  if (!match) return {};
+  const [, leading, size, lineHeight, family] = match;
+  const longhands: Record<string, string> = {
+    fontSize: size,
+    fontFamily: family.trim(),
+  };
+  if (lineHeight) longhands.lineHeight = lineHeight;
+  for (const token of leading.split(/\s+/).filter(Boolean)) {
+    if (/^(?:normal|italic|oblique)$/.test(token)) longhands.fontStyle = token;
+    else if (/^(?:\d{3}|bold|bolder|lighter)$/.test(token)) {
+      longhands.fontWeight = token;
+    } else if (/^small-caps$/.test(token)) longhands.fontVariant = token;
+  }
+  return longhands;
+}
+
 export function cssStyleAliases(
   styles: Record<string, string>,
 ): Record<string, string> {
   const result: Record<string, string> = {};
   for (const [property, value] of Object.entries(styles)) {
+    // Expanded in source order so a later explicit longhand still wins.
+    if (property === "font") {
+      Object.assign(result, fontShorthandLonghands(value));
+    }
     result[property] = value;
     if (property.includes("-")) {
       result[camelCaseCssProperty(property)] = value;

package/corpus/templates/design/app/pages/design-editor/commands/add-auto-layout.ts

@@ -282,7 +282,7 @@ export function runAddAutoLayout({
         }
       }
     }
-    applyLocalContentUpdate(nextContent, { skipPreview: true });
+    applyLocalContentUpdate(nextContent, { forcePreviewFullDocument: true });
     if (wrapperId) {
       const taggedProjection = buildCodeLayerProjection(nextContent);
       const wrapperNode = taggedProjection.nodes.find(
@@ -338,7 +338,7 @@ export function runAddAutoLayout({
         if (styled.result.status === "applied") nextContent = styled.content;
       }
     }
-    applyLocalContentUpdate(nextContent, { skipPreview: true });
+    applyLocalContentUpdate(nextContent, { forcePreviewFullDocument: true });
     if (wrapperId) {
       const projectionAfter = buildCodeLayerProjection(nextContent);
       const wrapperNode = projectionAfter.nodes.find(
@@ -412,5 +412,5 @@ export function runAddAutoLayout({
       nextContent = paddingPatch.content;
     }
   }
-  applyLocalContentUpdate(nextContent, { skipPreview: true });
+  applyLocalContentUpdate(nextContent, { forcePreviewFullDocument: true });
 }

package/corpus/templates/design/app/pages/design-editor/commands/align-selection.ts

@@ -66,8 +66,11 @@ export function runAlignSelection(
   }: AlignSelectionArgs,
   edge: DesignHotkeyAlignEdge,
 ) {
+  const abandon = (reason: string, data?: Record<string, unknown>) => {
+    trace("structure", "align-abandoned", { reason, edge, ...data });
+  };
   trace("structure", "align", { layers: selectedLayerIdsState.length });
-  if (!canEditDesign) return;
+  if (!canEditDesign) return abandon("read-only");
 
   // Overview, 2+ selected SCREENS: align each screen's frame geometry to
   // the selection's combined bounding box through the same
@@ -82,7 +85,11 @@ export function runAlignSelection(
       fileIds: files.map((file) => file.id),
     })
   ) {
-    if (overviewSelectedScreenIds.length < 2) return;
+    if (overviewSelectedScreenIds.length < 2) {
+      return abandon("overview: needs 2+ screens", {
+        selected: overviewSelectedScreenIds.length,
+      });
+    }
     const before = getCanvasFrameGeometry(designDataJsonRef.current);
     const screenRects: AlignableRect[] = [];
     overviewSelectedScreenIds.forEach((screenId) => {
@@ -100,7 +107,10 @@ export function runAlignSelection(
           : boardFileId === screenId
             ? boardFrameGeometry
             : undefined;
-      if (!fallbackGeometry) return;
+      if (!fallbackGeometry) {
+        abandon("overview: screen has no geometry", { screenId });
+        return;
+      }
       const geometry = { ...fallbackGeometry, ...before[screenId] };
       screenRects.push({
         id: screenId,
@@ -110,9 +120,13 @@ export function runAlignSelection(
         height: geometry.height,
       });
     });
-    if (screenRects.length < 2) return;
+    if (screenRects.length < 2) {
+      return abandon("overview: fewer than 2 measurable screens", {
+        measured: screenRects.length,
+      });
+    }
     const bounds = getFrameGroupBounds(screenRects);
-    if (!bounds) return;
+    if (!bounds) return abandon("no combined bounds for selection");
     const positions = computeAlignedPositions(
       screenRects,
       {
@@ -123,7 +137,9 @@ export function runAlignSelection(
       },
       edge,
     );
-    if (positions.size === 0) return;
+    if (positions.size === 0) {
+      return abandon("already aligned; nothing to move", { edge });
+    }
     const after = cloneCanvasFrameGeometry(before);
     positions.forEach((position, screenId) => {
       after[screenId] = { ...after[screenId]!, ...position };
@@ -133,22 +149,28 @@ export function runAlignSelection(
   }
 
   // Single-screen mode: in-screen DOM-node layers.
-  if (!activeFile) return;
+  if (!activeFile) return abandon("no active file");
   const baseContent = getFreshActiveContent();
   const nodeIds = getActiveFileSelectedNodeIds(baseContent);
-  if (nodeIds.length === 0) return;
+  if (nodeIds.length === 0) {
+    return abandon("selection has no nodes in the active file", {
+      selectedLayerIds: selectedLayerIdsState.length,
+    });
+  }
   const projection = buildCodeLayerProjection(baseContent);
   const nodesById = new Map(projection.nodes.map((node) => [node.id, node]));
   const selectedNodes = nodeIds
     .map((nodeId) => nodesById.get(nodeId))
     .filter((node): node is CodeLayerNode => Boolean(node));
-  if (selectedNodes.length === 0) return;
+  if (selectedNodes.length === 0) {
+    return abandon("selected ids resolve to no projection nodes", { nodeIds });
+  }
   const selectedRects = selectedNodes.map(rectFromCodeLayerNode);
 
   if (selectedRects.length >= 2) {
     // Multi-selection: align to the selection's own combined bbox.
     const bounds = getFrameGroupBounds(selectedRects);
-    if (!bounds) return;
+    if (!bounds) return abandon("no combined bounds for selection");
     const positions = computeAlignedPositions(
       selectedRects,
       {
@@ -159,7 +181,9 @@ export function runAlignSelection(
       },
       edge,
     );
-    if (positions.size === 0) return;
+    if (positions.size === 0) {
+      return abandon("already aligned; nothing to move", { edge });
+    }
     commitNodePositions(baseContent, positions);
     return;
   }
@@ -169,15 +193,21 @@ export function runAlignSelection(
   // Figma (there's nothing to align a lone top-level frame against).
   const soleNode = selectedNodes[0]!;
   const parentId = soleNode.parentId;
-  if (!parentId) return;
+  if (!parentId) {
+    return abandon("single selection has no parent to align against", {
+      nodeId: soleNode.id,
+    });
+  }
   const parentNode = nodesById.get(parentId);
-  if (!parentNode) return;
+  if (!parentNode) return abandon("parent id not in projection", { parentId });
   const parentRect = rectFromCodeLayerNode(parentNode);
   const positions = computeAlignedPositions(
     [selectedRects[0]!],
     { x: 0, y: 0, width: parentRect.width, height: parentRect.height },
     edge,
   );
-  if (positions.size === 0) return;
+  if (positions.size === 0) {
+    return abandon("already aligned; nothing to move", { edge });
+  }
   commitNodePositions(baseContent, positions);
 }

package/corpus/templates/design/app/pages/design-editor/commands/apply-local-content-update.ts

@@ -104,6 +104,12 @@ export function runApplyLocalContentUpdate(
   nextContent: string,
   options: {
     refreshPreview?: boolean;
+    /**
+     * Requires the caller to own the preview: it already patched the live
+     * iframe, or its target is not the rendered document. Set on a
+     * host-computed edit to the active screen and the canvas renders stale
+     * content until a reload.
+     */
     skipPreview?: boolean;
     forcePreviewFullDocument?: boolean;
     immediateSave?: boolean;
@@ -258,7 +264,7 @@ export function runApplyLocalContentUpdate(
   // couldn't run (bridge not registered for this surface yet, or an
   // explicit forceRefresh request).
   const replacedPreview = options.skipPreview
-    ? "applied"
+    ? "skipped-caller-owns-preview"
     : forceRefresh
       ? "unavailable"
       : replacePreviewContent(
@@ -268,10 +274,15 @@ export function runApplyLocalContentUpdate(
             ? { forceFullDocument: true }
             : undefined,
         );
-  if (
-    forceRefresh ||
-    previewContentReplaceNeedsRenderFallback(replacedPreview)
-  ) {
+  const renderFallback =
+    forceRefresh || previewContentReplaceNeedsRenderFallback(replacedPreview);
+  trace("persist", "preview", {
+    outcome: replacedPreview,
+    forceFullDocument: options.forcePreviewFullDocument === true,
+    renderFallback,
+    bytes: nextContent.length,
+  });
+  if (renderFallback) {
     setContentRenderRevision((revision) => revision + 1);
   }
   if (ydoc && isSynced) {

package/corpus/templates/design/app/pages/design-editor/commands/change-selected-z-index.ts

@@ -200,7 +200,7 @@ export function runChangeSelectedZIndex(
     zIndexFallback();
     return;
   }
-  applyLocalContentUpdate(patch.content, { skipPreview: true });
+  applyLocalContentUpdate(patch.content, { forcePreviewFullDocument: true });
   const movedNode = patch.projection.nodes.find(
     (n) =>
       n.dataAttributes["data-agent-native-node-id"] === targetId ||

package/corpus/templates/design/app/pages/design-editor/commands/frame-selection.ts

@@ -111,7 +111,7 @@ export function runFrameSelection({
           patch.result.wrapperNodeId,
       ) ?? wrapperNode;
   }
-  applyLocalContentUpdate(nextContent, { skipPreview: true });
+  applyLocalContentUpdate(nextContent, { forcePreviewFullDocument: true });
   if (wrapperNode) {
     setSelectedLayerIdsState([wrapperNode.id]);
     setSelectedElement(elementInfoFromCodeLayerNode(wrapperNode));

package/corpus/templates/design/app/pages/design-editor/commands/group-selection.ts

@@ -111,7 +111,7 @@ export function runGroupSelection({
     );
     return;
   }
-  applyLocalContentUpdate(patch.content, { skipPreview: true });
+  applyLocalContentUpdate(patch.content, { forcePreviewFullDocument: true });
   // Select the new wrapper node if the substrate reported its id.
   const wrapperId = patch.result.wrapperNodeId;
   if (wrapperId) {

package/corpus/templates/design/app/pages/design-editor/commands/nudge-selection.ts

@@ -180,7 +180,7 @@ export function runNudgeSelection(
       placement: intent.placement,
     } satisfies MoveNodeEditIntent);
     if (patch.result.status !== "applied") return;
-    applyLocalContentUpdate(patch.content, { skipPreview: true });
+    applyLocalContentUpdate(patch.content, { forcePreviewFullDocument: true });
     // A node with no stable `data-agent-native-node-id` has its id derived
     // from path/offset, and the move changes both — so the pre-move id
     // finds nothing and the selection has to be re-resolved by identity.

package/corpus/templates/design/app/pages/design-editor/commands/paste-selection.ts

@@ -2,6 +2,8 @@ import type { Dispatch, RefObject, SetStateAction } from "react";
 import { toast } from "sonner";
 import * as Y from "yjs";
 
+import { trace } from "@/components/design/design-trace";
+import { findCanvasIframeForScreen } from "@/components/design/multi-screen/iframe-targeting";
 import type {
   ElementInfo,
   RuntimeStructureInsertRequest,
@@ -21,9 +23,15 @@ import type { CanvasLayerClipboardEntry } from "@/pages/design-editor/command-ty
 import { isStandaloneHttpUrl } from "@/pages/design-editor/editor-state";
 import type { ContentHistoryChange } from "@/pages/design-editor/history";
 import { MAX_DESIGN_UNDO_STACK } from "@/pages/design-editor/history";
-import { resolvePastePlacementForSelection } from "@/pages/design-editor/paste-placement";
+import {
+  resolvePastePlacementForSelection,
+  resolvePasteSourceAnchor,
+} from "@/pages/design-editor/paste-placement";
 import type { DesignFile } from "@/pages/design-editor/types";
 
+/** Inset for a copy whose original parent is gone, so it lands on screen. */
+const ORPHANED_PASTE_INSET = 24;
+
 export interface PasteSelectionArgs {
   activeFile: DesignFile;
   applyFileContentUpdate: (
@@ -83,6 +91,7 @@ export interface PasteSelectionArgs {
     baseContent: string;
     nextContent: string;
     origin: ClipboardContentMutationOrigin;
+    baseSource?: "lineage" | "document";
   }) => ClipboardContentMutationPublication | null;
   refreshClipboardFromSystemClipboard: () => Promise<void>;
   remapMotionTracksForClone: (
@@ -153,10 +162,6 @@ export async function runPasteSelection(
   undoManagerRef.current?.stopCapturing();
   await refreshClipboardFromSystemClipboard();
   const entries = getCanvasClipboardEntries();
-  const targetFileId =
-    viewModeRef.current === "overview" && position && boardFileId
-      ? boardFileId
-      : activeFile?.id;
   if (entries.length === 0) {
     // No layer-level clipboard content — fall back to whole-screen paste
     // (U6) when the clipboard instead carries copied screen snapshots.
@@ -166,7 +171,35 @@ export async function runPasteSelection(
     }
     return;
   }
+  const sourceAnchor = position
+    ? null
+    : resolvePasteSourceAnchor({ entries, getContent: getScreenContent });
+  const activeSurfaceFileId =
+    viewModeRef.current === "overview" && position && boardFileId
+      ? boardFileId
+      : activeFile?.id;
+  // The board is an infinite canvas layer behind every screen, so a screen
+  // layer dropped on it renders under a frame at coordinates no camera or
+  // selection outline resolves. A keyboard paste goes back to its source.
+  const returnToSourceFileId =
+    sourceAnchor &&
+    activeSurfaceFileId === boardFileId &&
+    sourceAnchor.fileId !== boardFileId
+      ? sourceAnchor.fileId
+      : null;
+  const targetFileId = returnToSourceFileId ?? activeSurfaceFileId;
   if (!targetFileId || !canEditDesign) return;
+  if (!position && targetFileId === boardFileId && !sourceAnchor) {
+    trace("structure", "paste-refused", {
+      reason: "clipboard has no readable source file to return the copy to",
+      targetFileId,
+      entries: entries.length,
+    });
+    toast.error(t("designEditor.toasts.primitiveInsertFailed"), {
+      duration: 4000,
+    });
+    return;
+  }
   // The pending-local map is the synchronous write-through source for
   // same-task/repeated operations. React query/collab mirrors can lag one
   // render behind a just-completed paste even after its save is already
@@ -174,13 +207,39 @@ export async function runPasteSelection(
   // mirror makes its history `before` skip the first clone, so one undo
   // removes both. Prefer the pending snapshot exactly like primitive and
   // cross-screen structure writes do elsewhere in this editor.
+  const pendingBase =
+    pendingLocalFileContentsRef.current.get(targetFileId)?.content;
+  const lineageBase =
+    latestClipboardMutationContentRef.current.get(targetFileId)?.content;
+  // The lineage is NOT a content source: it advances only on a clipboard
+  // mutation, so after a delete it still describes the pre-delete document
+  // and rebasing there resurrects what was removed.
   const baseContent =
-    latestClipboardMutationContentRef.current.get(targetFileId)?.content ??
-    pendingLocalFileContentsRef.current.get(targetFileId)?.content ??
+    pendingBase ??
     (targetFileId === activeFile?.id
       ? getFreshActiveContent()
       : (getScreenContent(targetFileId) ?? ""));
-  if (!baseContent && targetFileId !== boardFileId) return;
+  trace("structure", "paste-base", {
+    targetFileId,
+    rebasedOn: pendingBase
+      ? "pending-local"
+      : targetFileId === activeFile?.id
+        ? "fresh-active"
+        : "screen-content",
+    bytes: baseContent.length,
+    lineageBytes: lineageBase?.length ?? null,
+    entries: entries.length,
+  });
+  if (!baseContent && targetFileId !== boardFileId) {
+    trace("structure", "paste-refused", {
+      reason: "destination file has no readable content",
+      targetFileId,
+    });
+    toast.error(t("designEditor.toasts.primitiveInsertFailed"), {
+      duration: 4000,
+    });
+    return;
+  }
   const layerHtmls = entries.map((entry) => entry.html);
   const styleSnapshots = entries.map((entry) => entry.portableStyleSnapshot);
   const managedStyleSnapshots = entries.map(
@@ -292,8 +351,18 @@ export async function runPasteSelection(
       baseContent,
       nextContent,
       origin: "clipboard-paste",
+      baseSource: "document",
     });
-    if (!clipboardMutation) return false;
+    if (!clipboardMutation) {
+      trace("structure", "paste-refused", {
+        reason: "clipboard lineage refused the publication",
+        targetFileId,
+      });
+      toast.error(t("designEditor.toasts.primitiveInsertFailed"), {
+        duration: 4000,
+      });
+      return false;
+    }
     if (nextContent !== baseContent) {
       // Capture the exact immutable pre-paste document here, before the
       // optimistic cache/collab mirrors can advance independently. The
@@ -335,7 +404,12 @@ export async function runPasteSelection(
   // Inside a frame, after an object — but always into normal flow: a
   // container is not a free canvas, so carrying the source's left/top
   // across drops the clone on top of the target's content.
-  if (!position && targetFileId !== boardFileId && selectedElement?.selector) {
+  if (
+    !position &&
+    !returnToSourceFileId &&
+    targetFileId !== boardFileId &&
+    selectedElement?.selector
+  ) {
     const selector = selectedCanvasSelector ?? selectedElement.selector;
     const decision = resolvePastePlacementForSelection({
       content: baseContent,
@@ -384,24 +458,56 @@ export async function runPasteSelection(
   const pastingIntoSourceScreen = entries.every(
     (entry) => entry.sourceFileId === targetFileId,
   );
+  const sourceParentSelectors =
+    sourceAnchor?.fileId === targetFileId ? sourceAnchor.parentSelectors : null;
+  // The copy is going to the screen root because its parent is gone. Its
+  // stored left/top belong to that parent, so reusing them can place it off
+  // the screen entirely; a fixed inset is always somewhere the user can see.
+  const rootFallbackPlacement =
+    sourceAnchor !== null &&
+    sourceAnchor.fileId === targetFileId &&
+    sourceParentSelectors === null;
   const viewportCenter = (() => {
+    const container = canvasContainerRef.current;
+    const factor = zoom / 100;
+    if (factor <= 0) return { x: 120, y: 120 };
     if (viewModeRef.current === "single") {
-      const iframe = canvasContainerRef.current?.querySelector<HTMLElement>(
+      const iframe = container?.querySelector<HTMLElement>(
         "[data-design-preview-iframe]",
       );
       if (iframe) {
         const iframeRect = iframe.getBoundingClientRect();
-        const factor = zoom / 100;
         return {
           x: Math.max(0, iframeRect.width / 2 / factor),
           y: Math.max(0, iframeRect.height / 2 / factor),
         };
       }
     }
-    const rect = canvasContainerRef.current?.getBoundingClientRect();
-    return rect
-      ? { x: Math.max(0, rect.width / 2), y: Math.max(0, rect.height / 2) }
-      : { x: 120, y: 120 };
+    // The container's rect is screen pixels; left/top are document pixels.
+    // Only the destination frame's own rect converts between them — the
+    // board's cannot, because its iframe is a render window, not its origin.
+    const frameRect =
+      targetFileId !== boardFileId
+        ? findCanvasIframeForScreen(
+            container,
+            targetFileId,
+          )?.getBoundingClientRect()
+        : null;
+    const containerRect = container?.getBoundingClientRect();
+    if (!frameRect || !containerRect) return { x: 120, y: 120 };
+    const clamp = (value: number, extent: number) =>
+      Math.max(0, Math.min(value, extent / factor));
+    return {
+      x: clamp(
+        (containerRect.left + containerRect.width / 2 - frameRect.left) /
+          factor,
+        frameRect.width,
+      ),
+      y: clamp(
+        (containerRect.top + containerRect.height / 2 - frameRect.top) / factor,
+        frameRect.height,
+      ),
+    };
   })();
   const positions = entries.map((_, index) => {
     const source = sourcePositions[index];
@@ -413,6 +519,12 @@ export async function runPasteSelection(
           }
         : { x: position.x + index * 16, y: position.y + index * 16 };
     }
+    if (rootFallbackPlacement) {
+      return {
+        x: ORPHANED_PASTE_INSET + cascadeOffset + index * 16,
+        y: ORPHANED_PASTE_INSET + cascadeOffset + index * 16,
+      };
+    }
     return source && pastingIntoSourceScreen
       ? {
           x: source.x + 10 + cascadeOffset,
@@ -427,8 +539,21 @@ export async function runPasteSelection(
     positions,
     styleSnapshots,
     managedStyleSnapshots,
+    ...(sourceParentSelectors
+      ? { targetSelectors: sourceParentSelectors, placement: "inside" as const }
+      : {}),
   });
-  if (!result) return;
+  if (!result) {
+    trace("structure", "paste-refused", {
+      reason: "destination document refused the clone",
+      targetFileId,
+      anchors: sourceParentSelectors?.length ?? 0,
+    });
+    toast.error(t("designEditor.toasts.primitiveInsertFailed"), {
+      duration: 4000,
+    });
+    return;
+  }
   if (!position) pasteCascadeRef.current += 1;
   if (!applyPasteContentUpdate(result.content)) return;
   remapMotionTracksForClone(result.nodeIdMap, targetFileId);

package/corpus/templates/design/app/pages/design-editor/commands/screen-visual-duplicate-change.ts

@@ -96,6 +96,7 @@ export function runScreenVisualDuplicateChange(
         ? [details.anchorSelector]
         : undefined,
     placement: details?.placement ?? "after",
+    preserveIncomingNodeIds: true,
   });
   if (!nextContent) {
     toast.error(t("designEditor.toasts.layerMoveFailed"), {

package/corpus/templates/design/app/pages/design-editor/commands/ungroup-selection.ts

@@ -150,7 +150,7 @@ export function runUngroupSelection({
     );
   }
 
-  applyLocalContentUpdate(content, { skipPreview: true });
+  applyLocalContentUpdate(content, { forcePreviewFullDocument: true });
 
   const finalProjection = buildCodeLayerProjection(content);
   const releasedNodes = finalProjection.nodes.filter((n) => {

package/corpus/templates/design/app/pages/design-editor/commands/visual-duplicate-change.ts

@@ -87,6 +87,7 @@ export function runVisualDuplicateChange(
         ? [details.anchorSelector]
         : undefined,
     placement: details?.placement ?? "after",
+    preserveIncomingNodeIds: true,
   });
   if (!nextContent) {
     toast.error(t("designEditor.toasts.layerMoveFailed"), {

package/corpus/templates/design/app/pages/design-editor/cross-screen-text-color.ts

@@ -110,12 +110,12 @@ export function shouldAdaptAutoTextColorForCrossScreenMove(params: {
  * treated as transparent so the walk keeps climbing instead of trusting a
  * near-invisible tint. A dark-class hint only counts when no color signal
  * was present on that element (a real color always wins over a guessed
- * class). No signal anywhere in the chain conservatively reports "light" so
- * the default-white heuristic can still fire and prevent invisible text.
+ * class). No signal anywhere in the chain yields null — distinct from a
+ * measured light surface, so each caller picks its own fallback.
  */
-export function resolveDestinationBackgroundLightness(
+export function resolveDestinationBackgroundLightnessOrNull(
   chain: ReadonlyArray<{ color: string | null } | { darkClassHint: boolean }>,
-): boolean {
+): boolean | null {
   for (const entry of chain) {
     if ("color" in entry && entry.color) {
       const rgba = parseCssColorExtended(entry.color);
@@ -130,7 +130,14 @@ export function resolveDestinationBackgroundLightness(
       return false;
     }
   }
-  return true;
+  return null;
+}
+
+/** Unreadable counts as light, so the default-white heuristic can still fire. */
+export function resolveDestinationBackgroundLightness(
+  chain: ReadonlyArray<{ color: string | null } | { darkClassHint: boolean }>,
+): boolean {
+  return resolveDestinationBackgroundLightnessOrNull(chain) ?? true;
 }
 
 // Cheap, best-effort utility-class signal for "this element's classes look
@@ -209,10 +216,11 @@ function collectDestinationBackgroundSignals(
  * dark-class-hint chain when no live document is available (e.g. the
  * destination screen isn't currently mounted).
  */
-export function destinationBackgroundIsLightForNode(
+/** null means "no readable signal", so callers can pick their own fallback. */
+export function destinationBackgroundLightness(
   element: Element,
   liveDoc?: Document | null,
-): boolean {
+): boolean | null {
   try {
     const liveElement =
       liveDoc && element.hasAttribute("data-agent-native-node-id")
@@ -223,12 +231,20 @@ export function destinationBackgroundIsLightForNode(
           )
         : null;
     const chain = collectDestinationBackgroundSignals(element, liveElement);
-    return resolveDestinationBackgroundLightness(chain);
+    return resolveDestinationBackgroundLightnessOrNull(chain);
   } catch {
-    return true;
+    // coercion-ok: null is the typed "unreadable" value callers branch on
+    return null;
   }
 }
 
+export function destinationBackgroundIsLightForNode(
+  element: Element,
+  liveDoc?: Document | null,
+): boolean {
+  return destinationBackgroundLightness(element, liveDoc) ?? true;
+}
+
 /**
  * Cross-screen counterpart to adaptAutoTextColorForNest — runs HOST-SIDE
  * after moveNodeBetweenDocuments has already re-parented the text node into

package/corpus/templates/design/app/pages/design-editor/editor-state.ts

@@ -21,6 +21,7 @@ export { isStandaloneHttpUrl };
 export type PreviewContentReplaceResult =
   | "applied"
   | "skipped-live-route"
+  | "skipped-caller-owns-preview"
   | "unavailable";
 
 export function previewContentReplaceNeedsRenderFallback(