@agent-native/core 0.149.1 → 0.149.3

package/corpus/templates/design/AGENTS.md

@@ -6,9 +6,7 @@ exports through actions against the shared SQL state.
 
 ## Skills
 
-Keep this file essential — it is loaded into the agent's context every turn.
-Real depth lives in `.agents/skills/`; read the relevant skill before deeper
-work in that area.
+Read the relevant skill before deeper work in that area.
 
 - `design-generation` — 5-phase generation flow, aesthetic quality bar, code
   layers/code workspace, editor extensions, breakpoints/screen
@@ -23,19 +21,11 @@ work in that area.
 - `design-review-feedback` — persisted, element-anchored review comments to a
   verified close, one root thread at a time.
 - `export-handoff` — HTML/PNG/SVG/ZIP/code and coding-handoff export.
-- `visual-edit` — editing a real local app visually (localhost bridge, Code
-  tab, reprompt write boundary).
 - `full-app-build` — design source modes and flag-gated fusion-backed full app
   building.
 - `shader-fills` — code-backed GLSL shader fills/effects.
-- `sharing` — design and design-system visibility/grants.
-- `frontend-design`, `shadcn-ui` for UI; `actions`, `delegate-to-agent`,
-  `security`, `self-modifying-code` for framework patterns.
-
-Before building common workspace or agent UI, read `agent-native-toolkit` to
-inventory existing public kits and installed package seams. Use
-`customizing-agent-native` for the configure → compose → eject → propose seam
-ladder.
+- `capture-learnings` — record a user preference or correction so it outlives
+  the thread.
 
 ## Actions
 
@@ -58,10 +48,9 @@ ladder.
 - Use the app actions for designs, files, versions, design systems, variants,
   export, and sharing. Do not write design rows directly with SQL.
 - A message beginning with `[Reprompt selection]` is preview-only: the only
-  mutation path is `propose-node-rewrite`; never call a content writer. See
-  `visual-edit`'s "Select And Reprompt". `[Selection question]` is read-only:
-  answer about the captured element and subtree without calling
-  content-writing actions.
+  mutation path is `propose-node-rewrite`; never call a content writer.
+  `[Selection question]` is read-only: answer about the captured element and
+  subtree without calling content-writing actions.
 - Call `view-screen` before editing a specific design if the current design or
   selected file is not already clear from context.
 - Generated files must be complete, standalone HTML (Alpine.js + Tailwind CDN)
@@ -75,8 +64,6 @@ ladder.
   promise lossless Figma import/export.
 - Persist useful work early: create/update the design and files as soon as a
   coherent candidate exists, then iterate.
-- In dev, call actions with `pnpm action <name>`; in production, call the
-  native tool.
 - For shared prototype feedback, use the persisted review actions — read
   `design-review-feedback` for the loop.
 - Follow linked design-system tokens and `customInstructions` whenever
@@ -105,5 +92,10 @@ ladder.
   see `design-generation`.
 - `design-reprompt-pending:<designId>:<fileId>` /
   `design-reprompt-proposal:<designId>:<fileId>:<repromptId>` — the
-  compare-and-set reprompt request/proposal pair; see `visual-edit`'s
-  "Select And Reprompt" for the full lifecycle.
+  compare-and-set reprompt request/proposal pair. Both must be present and
+  matched before `propose-node-rewrite`; a stale pair is never applied.
+
+## Source Changes
+
+Before building common workspace or agent UI, read `agent-native-toolkit`; read
+`customizing-agent-native` before adapting shared UI.

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

@@ -4444,6 +4444,18 @@ export function DesignCanvas({
             readOnly,
           })}
           data-design-preview-iframe
+          onLoad={(event) => {
+            // The bridge logs into the IFRAME console and cannot read
+            // import.meta.env, so dev has to switch it on from out here.
+            if (!import.meta.env?.DEV) return;
+            try {
+              const win = event.currentTarget.contentWindow as
+                | (Window & { __DND_DEBUG?: boolean })
+                | null;
+              if (win) win.__DND_DEBUG = true;
+              // coercion-ok: a cross-origin preview exposes no contentWindow
+            } catch {}
+          }}
           {...{
             [SESSION_REPLAY_IFRAME_ATTRIBUTE]: !externalPreviewUrl
               ? ""

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

@@ -1782,6 +1782,9 @@ const LayerRow = memo(function LayerRow({
   // doing so.
   const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === "Enter" || event.key === " " || event.key === "Space") {
+      // Figma drills into the selection on Enter and walks up on Shift+Enter;
+      // re-selecting an already-selected row here would swallow both.
+      if (event.key === "Enter" && isSelected) return;
       event.preventDefault();
       if (!selectable) return;
       onSelect(node.id, {
@@ -1797,12 +1800,21 @@ const LayerRow = memo(function LayerRow({
       onStartRename(node);
       return;
     }
-    if (event.key === "ArrowRight" && hasChildren && !isExpanded) {
+    // Only the PLAIN chord toggles the chevron: Shift+Arrow is Figma's big
+    // nudge and every modified arrow belongs to the canvas hotkeys below.
+    const plainArrow =
+      !event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey;
+    if (
+      plainArrow &&
+      event.key === "ArrowRight" &&
+      hasChildren &&
+      !isExpanded
+    ) {
       event.preventDefault();
       onToggleExpanded(node.id, true);
       return;
     }
-    if (event.key === "ArrowLeft" && hasChildren && isExpanded) {
+    if (plainArrow && event.key === "ArrowLeft" && hasChildren && isExpanded) {
       event.preventDefault();
       onToggleExpanded(node.id, false);
       return;
@@ -2077,17 +2089,22 @@ const LayerRow = memo(function LayerRow({
         >
           {activeDrop === "before" ? (
             <span
+              data-layer-drop-indicator="before"
               className="pointer-events-none absolute right-2 top-0 z-10 h-px bg-[var(--design-editor-accent-color)]"
               style={{ left: rowIndent(depth) }}
             />
           ) : null}
           {activeDrop === "after" ? (
             <span
+              data-layer-drop-indicator="after"
               className="pointer-events-none absolute bottom-0 right-2 z-10 h-px bg-[var(--design-editor-accent-color)]"
               style={{ left: rowIndent(depth) }}
             />
           ) : null}
           <div
+            data-layer-drop-indicator={
+              activeDrop === "inside" ? "inside" : undefined
+            }
             className={cn(
               "group flex h-7 w-max min-w-full items-center gap-1 rounded-[5px] pr-1 text-[12px] bg-[var(--design-editor-panel-bg)]",
               activeDrop === "inside" &&

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

@@ -51,6 +51,7 @@ import {
   IconHandClick,
   IconPlus,
 } from "@tabler/icons-react";
+import { useTheme } from "next-themes";
 import {
   memo,
   useRef,
@@ -89,6 +90,7 @@ import {
 } from "./design-canvas/content-size-report";
 import { appendHitTestResponder } from "./design-canvas/hit-test";
 import { withLocalRuntimes } from "./design-canvas/local-runtime";
+import { roundGeo, trace } from "./design-trace";
 import { DesignCanvas } from "./DesignCanvas";
 import { dndHostLog } from "./dnd-debug";
 import {
@@ -473,6 +475,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   onPrimitiveCreated,
   onPrimitiveReparent,
   onCreateScreenFrame,
+  frameToolDraws = "frame",
   onDeleteSelection,
   onNudgeSelection,
   onZoomChange,
@@ -522,6 +525,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   onDropFiles,
   cameraCommand,
 }: MultiScreenCanvasProps) {
+  const { resolvedTheme } = useTheme();
   const t = useT();
   const surfaceRef = useRef<HTMLDivElement>(null);
   const [pan, setPan] = useState({ x: 0, y: 0 });
@@ -641,6 +645,17 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       height: surfaceSize.height / scale,
     };
   }, [canvasZoom, pan.x, pan.y, surfaceSize.height, surfaceSize.width]);
+  // The board iframe cannot read the host's CSS vars, so the themed canvas
+  // colour has to be resolved out here or the board stays dark in light mode.
+  const boardSurfaceBackground = useMemo(() => {
+    if (typeof window === "undefined") return BOARD_SURFACE_BACKGROUND;
+    const themed = window
+      .getComputedStyle(document.documentElement)
+      .getPropertyValue("--design-editor-canvas-bg")
+      .trim();
+    return themed || BOARD_SURFACE_BACKGROUND;
+  }, [resolvedTheme]);
+
   const boardSurfaceRenderGeometry = useMemo(() => {
     if (!boardFrameGeometry) return undefined;
     const focusGeometry = boardSurfaceFocusPoint
@@ -692,8 +707,14 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       html: boardSurfaceHtml,
       logicalGeometry: boardFrameGeometry,
       viewport: boardStaticPreviewViewport,
+      background: boardSurfaceBackground,
     });
-  }, [boardSurfaceHtml, boardFrameGeometry, boardStaticPreviewViewport]);
+  }, [
+    boardSurfaceHtml,
+    boardFrameGeometry,
+    boardStaticPreviewViewport,
+    boardSurfaceBackground,
+  ]);
   const showBoardStaticPreview = Boolean(
     boardFrameGeometry &&
     boardSurfaceRenderGeometry &&
@@ -2189,6 +2210,25 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       const sourceIsBoard = sourceScreenId === boardFileId;
       setCrossScreenSourceIsBoard(sourceIsBoard);
       const target = getFrameEntryAtPoint(boardPoint);
+      trace("drop", "resolve-target", {
+        pointerInCanvasUnits: {
+          x: Math.round(boardPoint.x),
+          y: Math.round(boardPoint.y),
+        },
+        hitFrame: target?.id ?? null,
+        sourceScreen: sourceScreenId,
+        sourceIsBoard,
+        frames: Object.entries(frameGeometryRef.current ?? {}).map(
+          ([id, g]: [string, any]) =>
+            `${id.slice(0, 6)} @ ${Math.round(g.x)},${Math.round(g.y)} ${Math.round(g.width)}x${Math.round(g.height)}`,
+        ),
+        verdict:
+          target && target.id !== sourceScreenId
+            ? "will drop into that frame"
+            : target
+              ? "hit the SOURCE frame, so no cross-screen move"
+              : "NO frame under the pointer — drop cannot resolve a screen",
+      });
       if (target && target.id !== sourceScreenId) {
         const nextTarget = { id: target.id, geometry: target.geometry };
         if (crossScreenTargetRef.current?.id !== nextTarget.id) {
@@ -2261,6 +2301,29 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       const hasIdentifier = !!(payload.selector || payload.sourceId);
       if (!hasIdentifier || !sourceScreenId) return;
       if (!lastBoardPoint) return;
+      // No candidate means the pointer never left the source screen, so the
+      // bridge already handled it as an in-place reorder. Falling back to the
+      // board here re-persists the move against a file that does not contain
+      // the element, which fails to resolve and silently discards the drop.
+      const sourceFrameGeometry = frameGeometryRef.current?.[sourceScreenId];
+      const droppedInsideSourceScreen =
+        !candidate &&
+        !!sourceFrameGeometry &&
+        lastBoardPoint.x >= sourceFrameGeometry.x &&
+        lastBoardPoint.x <= sourceFrameGeometry.x + sourceFrameGeometry.width &&
+        lastBoardPoint.y >= sourceFrameGeometry.y &&
+        lastBoardPoint.y <= sourceFrameGeometry.y + sourceFrameGeometry.height;
+      if (droppedInsideSourceScreen) return;
+      trace("drop", "finalize", {
+        candidate: candidate?.id ?? null,
+        sourceScreen: sourceScreenId,
+        droppedInsideSourceScreen,
+        outcome: droppedInsideSourceScreen
+          ? "discarded — pointer never left the source screen"
+          : candidate
+            ? "moving into candidate"
+            : "no candidate; falling back to the board",
+      });
       const targetCandidate =
         candidate ??
         (boardFileId && sourceScreenId !== boardFileId && boardFrameGeometry
@@ -2927,6 +2990,14 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           const viewportWidth = iframe?.clientWidth || metadata.width;
           const viewportHeight = iframe?.clientHeight || metadata.height;
           const infos = await requestSelectableElementInfos(entry.id);
+          // entry.geometry.height trails the measured auto-height, and an
+          // independent y-scale off it squashes every child rect.
+          const contentScale =
+            entry.geometry.width / Math.max(1, viewportWidth);
+          const renderedFrame = {
+            ...entry.geometry,
+            height: viewportHeight * contentScale,
+          };
           return infos.map((info) => ({
             screenId: entry.id,
             info,
@@ -2937,7 +3008,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
                 width: info.boundingRect.width,
                 height: info.boundingRect.height,
               },
-              entry.geometry,
+              renderedFrame,
               { width: viewportWidth, height: viewportHeight },
             ),
             frameGeometry: entry.geometry,
@@ -3718,11 +3789,27 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             getScreenMetadata?.(targetScreen),
           )
         : undefined;
+      // Metadata defaults to 1280x2560 while the renderer lays the iframe out
+      // at the frame's own size; trusting metadata scales every drawn
+      // primitive by metadataWidth/frameWidth. Same precedence as the marquee.
+      const targetIframe = targetScreen
+        ? surfaceRef.current?.querySelector<HTMLIFrameElement>(
+            `[data-screen-iframe-id="${CSS.escape(getActiveScreenIframeId(targetScreen))}"]`,
+          )
+        : null;
+      const measuredMetadata =
+        targetMetadata && targetIframe?.clientWidth && targetIframe.clientHeight
+          ? {
+              ...targetMetadata,
+              width: targetIframe.clientWidth,
+              height: targetIframe.clientHeight,
+            }
+          : targetMetadata;
 
       const localPrimitive = draftPrimitiveToInsert(
         draft,
         targetFrame.geometry,
-        targetMetadata,
+        measuredMetadata,
       );
       const persisted = onCreatePrimitive(targetFrame.id, localPrimitive);
       if (!persisted) {
@@ -4436,6 +4523,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         // originating screen.
         if (
           state.tool === "frame" &&
+          frameToolDraws === "screen" &&
           !state.originFrameId &&
           onCreateScreenFrame
         ) {
@@ -4459,9 +4547,19 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
                 0,
               )
             : null;
-          onCreateScreenFrame(
-            clampFrameGeometryToViewport(draftGeometry, viewportBounds),
+          const screenGeometry = clampFrameGeometryToViewport(
+            draftGeometry,
+            viewportBounds,
           );
+          trace("screen", "create-from-frame-tool", {
+            why: "frame tool started on empty canvas, so it becomes a SCREEN",
+            drawn: roundGeo(draftGeometry),
+            committed: roundGeo(screenGeometry),
+            clamped:
+              Math.round(draftGeometry.x) !== Math.round(screenGeometry.x) ||
+              Math.round(draftGeometry.y) !== Math.round(screenGeometry.y),
+          });
+          onCreateScreenFrame(screenGeometry);
           if (activeTool === undefined) {
             setLocalActiveTool("move");
           }
@@ -4469,6 +4567,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           finishDrag();
           return;
         }
+        trace("draw", "commit-primitive", {
+          tool: state.tool,
+          startedInScreen: state.originFrameId ?? "(empty canvas → board)",
+        });
         const nextDraft = createDraftPrimitive({
           tool: state.tool,
           start: state.originCanvas,
@@ -4503,6 +4605,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       activeTool,
       commitDraftPrimitive,
       finishDrag,
+      frameToolDraws,
       getCanvasPoint,
       getFrameEntryAtPoint,
       installDragListeners,
@@ -7474,6 +7577,11 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   const chromeScale = scale > 0 ? 1 / scale : 1;
   const showPixelGrid = canvasZoom >= PIXEL_GRID_ZOOM;
   const effectiveTool = normalizeCanvasTool(activeTool ?? localActiveTool);
+  const lastTracedToolRef = useRef<string | null>(null);
+  if (lastTracedToolRef.current !== effectiveTool) {
+    lastTracedToolRef.current = effectiveTool;
+    trace("tool", "active-tool", { tool: effectiveTool });
+  }
   useEffect(() => {
     effectiveToolRef.current = effectiveTool;
   }, [effectiveTool]);
@@ -7624,7 +7732,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         metadata.previewUrl ?? getPreviewUrl(screen.content)
       );
       const autoHeight =
-        isInlineScreen && measuredPrimaryHeight
+        isInlineScreen && measuredPrimaryHeight && !metadata.heightPinned
           ? Math.max(
               deviceViewportFloorForWidth(metadata.width),
               rawGeometry.height ?? 0,
@@ -8055,7 +8163,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
                   zoom={100}
                   deviceFrame="none"
                   boardSurface
-                  embeddedFrameBackground={BOARD_SURFACE_BACKGROUND}
+                  embeddedFrameBackground={boardSurfaceBackground}
                   embeddedFrame={{
                     viewportWidth: Math.max(1, Math.round(boardW)),
                     viewportHeight: Math.max(1, Math.round(boardH)),

package/corpus/templates/design/app/components/design/bridge/editor-chrome.bridge.ts

@@ -2749,6 +2749,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
 
   var passiveSelectionEls: Element[] = [];
   var passiveSelectionOverlays: HTMLElement[] = [];
+  // Figma draws ONE bounding box with handles around a multi-selection; the
+  // per-element overlays above are the thin outlines inside it.
+  var multiSelectionBoundsOverlay: HTMLElement | null = null;
   var activeMarqueeSelection: {
     startX: number;
     startY: number;
@@ -3042,7 +3045,6 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       style === "soft"
         ? "position:fixed;pointer-events:none;z-index:99996;border:1px solid color-mix(in srgb,var(--design-editor-accent-color) 64%,transparent);background:color-mix(in srgb,var(--design-editor-accent-color) 5%,transparent);display:none;box-sizing:border-box;"
         : "position:fixed;pointer-events:none;z-index:99996;border:1.5px solid var(--design-editor-accent-color);background:transparent;display:none;box-sizing:border-box;";
-    if (style !== "soft") appendPassiveSelectionHandles(overlay);
     document.body.appendChild(overlay);
     return overlay;
   }
@@ -3088,6 +3090,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       passiveSelectionOverlays.push(overlay);
       positionOverlay(overlay, el);
     });
+    // Selection changes do not go through refreshOverlays, so the combined
+    // bounds must be recomputed here too.
+    positionMultiSelectionBounds();
   }
 
   function preservePreviousSelectedElementForShiftClick(
@@ -4536,6 +4541,70 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     return true;
   }
 
+  function ensureMultiSelectionBoundsOverlay(): HTMLElement {
+    if (multiSelectionBoundsOverlay) return multiSelectionBoundsOverlay;
+    var overlay = document.createElement("div");
+    overlay.setAttribute("data-agent-native-edit-overlay", "multi-selection");
+    overlay.setAttribute("data-agent-native-multi-selection-bounds", "true");
+    overlay.style.cssText =
+      "position:fixed;pointer-events:none;z-index:99996;border:1.5px solid var(--design-editor-accent-color);background:transparent;display:none;box-sizing:border-box;";
+    appendPassiveSelectionHandles(overlay);
+    document.body.appendChild(overlay);
+    multiSelectionBoundsOverlay = overlay;
+    return overlay;
+  }
+
+  function positionMultiSelectionBounds(): void {
+    var members: Element[] = [];
+    if (selectedEl && document.documentElement.contains(selectedEl)) {
+      members.push(selectedEl);
+    }
+    passiveSelectionEls.forEach(function (el) {
+      if (el && document.documentElement.contains(el)) members.push(el);
+    });
+    if (members.length < 2 || selectionChromeHidden) {
+      if (multiSelectionBoundsOverlay) {
+        multiSelectionBoundsOverlay.style.display = "none";
+      }
+      return;
+    }
+    var rects = members.map(function (el) {
+      return (el as HTMLElement).getBoundingClientRect();
+    });
+    var left = Math.min.apply(
+      null,
+      rects.map(function (r) {
+        return r.left;
+      }),
+    );
+    var top = Math.min.apply(
+      null,
+      rects.map(function (r) {
+        return r.top;
+      }),
+    );
+    var right = Math.max.apply(
+      null,
+      rects.map(function (r) {
+        return r.right;
+      }),
+    );
+    var bottom = Math.max.apply(
+      null,
+      rects.map(function (r) {
+        return r.bottom;
+      }),
+    );
+    var overlay = ensureMultiSelectionBoundsOverlay();
+    overlay.style.display = "block";
+    overlay.style.transform = "none";
+    overlay.style.left = left + "px";
+    overlay.style.top = top + "px";
+    overlay.style.width = Math.max(0, right - left) + "px";
+    overlay.style.height = Math.max(0, bottom - top) + "px";
+    scalePassiveSelectionOverlay(overlay);
+  }
+
   function positionOverlay(overlay: HTMLElement, el: Element): void {
     if (!el || !document.documentElement.contains(el)) {
       overlay.style.display = "none";
@@ -4603,6 +4672,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       var overlay = passiveSelectionOverlays[index];
       if (overlay) positionOverlay(overlay, el);
     });
+    positionMultiSelectionBounds();
     positionGradientOverlay();
     syncOverlayObservers();
   }
@@ -5000,10 +5070,12 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       if (isOverlayElement(target)) continue;
       if (isLayerInteractionBlocked(target)) {
         lastEditorPointWasBlocked = true;
+        dndLog("select:blocked", { el: getSelector(target) });
         return null;
       }
       return target;
     }
+    dndLog("select:nothing-at-point", { x: clientX, y: clientY });
     return null;
   }
 
@@ -7285,12 +7357,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       el.getAttribute("data-agent-native-primitive") ||
       ""
     ).toLowerCase();
-    if (
-      primitive !== "rectangle" &&
-      primitive !== "rect" &&
-      primitive !== "frame"
-    )
-      return false;
+    // Frames adopt; a rectangle is a vector shape and never becomes a
+    // container (same contract appendCanvasPrimitiveToHtml enforces on draw).
+    if (primitive !== "frame") return false;
     var cs = window.getComputedStyle(el);
     return cs.position === "absolute" || cs.position === "fixed";
   }
@@ -7685,6 +7754,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     if (!el || el === document.documentElement) return false;
     if (isOverlayElement(el) || isLayerInteractionBlocked(el)) return false;
     if (el === document.body) return true;
+    // Figma's shape primitives are vectors; only a frame adopts children.
+    var primitiveKind = el.getAttribute("data-an-primitive");
+    if (primitiveKind && primitiveKind !== "frame") return false;
     var tag = (el.tagName || "").toLowerCase();
     // Reject leaf/text tags — they cannot accept children
     if (
@@ -12519,6 +12591,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       } else {
         positionOverlay(selectionOverlay, target);
       }
+      // The combined box spans selectedEl plus the passive selection, so a
+      // host-driven change leaves it on the previous geometry without this.
+      positionMultiSelectionBounds();
       if (hoveredEl === selectedEl) highlightOverlay.style.display = "none";
       // A host-driven selection (e.g. picking a layer in the Layers panel)
       // only ever moved the overlay above — it never sent the rich

package/corpus/templates/design/app/components/design/design-trace.ts

@@ -0,0 +1,120 @@
+// Interaction trace, on by default in dev. From the top-frame console:
+// `__DESIGN_TRACE = false` silences it; `__designTrace.dump()` prints the
+// whole story to copy; `.clear()` and `.only("drop")` narrow it.
+declare global {
+  interface Window {
+    __DESIGN_TRACE?: boolean;
+    __designTrace?: {
+      dump: () => string;
+      clear: () => void;
+      only: (area?: string) => void;
+      entries: () => TraceEntry[];
+    };
+  }
+}
+
+export type TraceArea =
+  | "tool"
+  | "draw"
+  | "screen"
+  | "select"
+  | "drag"
+  | "drop"
+  | "persist"
+  | "structure"
+  | "history";
+
+export interface TraceEntry {
+  t: number;
+  area: TraceArea;
+  event: string;
+  data?: unknown;
+}
+
+const MAX_ENTRIES = 2000;
+const entries: TraceEntry[] = [];
+let areaFilter: string | undefined;
+let startedAt = 0;
+
+function enabled(): boolean {
+  if (typeof window === "undefined") return false;
+  if (window.__DESIGN_TRACE === false) return false;
+  return window.__DESIGN_TRACE === true || import.meta.env?.DEV === true;
+}
+
+function ensureControls(): void {
+  if (typeof window === "undefined" || window.__designTrace) return;
+  window.__designTrace = {
+    entries: () => entries.slice(),
+    clear: () => {
+      entries.length = 0;
+      startedAt = 0;
+    },
+    only: (area?: string) => {
+      areaFilter = area;
+    },
+    dump: () =>
+      entries
+        .map((e) => {
+          const body = e.data === undefined ? "" : ` ${safeJson(e.data)}`;
+          return `+${String(e.t).padStart(6)}ms [${e.area}:${e.event}]${body}`;
+        })
+        .join("\n"),
+  };
+}
+
+/** Never let a circular ref or a DOM node break a gesture. */
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, (_key, v) =>
+      v instanceof Element ? v.tagName.toLowerCase() : v,
+    );
+  } catch {
+    return String(value);
+  }
+}
+
+export function trace(area: TraceArea, event: string, data?: unknown): void {
+  if (!enabled()) return;
+  try {
+    ensureControls();
+    const now = Date.now();
+    if (!startedAt) startedAt = now;
+    const entry: TraceEntry = { t: now - startedAt, area, event, data };
+    entries.push(entry);
+    if (entries.length > MAX_ENTRIES) entries.shift();
+    if (areaFilter && areaFilter !== area) return;
+    const tag = `%c[${area}:${event}]`;
+    const style = "font-weight:bold";
+    if (data === undefined) console.log(tag, style);
+    else console.log(tag, style, data);
+    // coercion-ok: diagnostics must never break the interaction they observe
+  } catch {}
+}
+
+/** Short, stable label for an element in a trace line. */
+export function traceEl(el: Element | null | undefined): string | null {
+  if (!el) return null;
+  const id = el.getAttribute?.("data-agent-native-node-id");
+  const name = el.getAttribute?.("data-agent-native-layer-name");
+  const primitive = el.getAttribute?.("data-an-primitive");
+  const tag = el.tagName?.toLowerCase() ?? "?";
+  return [
+    tag,
+    primitive && `(${primitive})`,
+    name && `"${name}"`,
+    id && `#${id}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+/** Compact geometry for a trace line. */
+export function roundGeo(g: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}): string {
+  return `${Math.round(g.x)},${Math.round(g.y)} ${Math.round(g.width)}x${Math.round(g.height)}`;
+}

package/corpus/templates/design/app/components/design/dnd-debug.ts

@@ -15,7 +15,8 @@ declare global {
 
 export function dndHostLog(phase: string, data?: unknown): void {
   if (typeof window === "undefined") return;
-  if (!window.__DND_DEBUG) return;
+  if (window.__DND_DEBUG === false) return;
+  if (!window.__DND_DEBUG && !import.meta.env?.DEV) return;
   try {
     const tag = `%c[dnd:host:${phase}]`;
     const style = "color:#0ea5e9;font-weight:bold";