@agent-native/core 0.165.4 → 0.167.0

package/corpus/templates/design/app/pages/DesignSystemSetup.tsx

@@ -21,7 +21,6 @@ import {
   IconPhoto,
   IconComponents,
   IconCheck,
-  IconChevronDown,
   IconExternalLink,
 } from "@tabler/icons-react";
 import { useState, useCallback, useRef, useMemo, useEffect } from "react";
@@ -38,7 +37,6 @@ import {
   pollDecodeJobStatus,
   type DecodeJobStatus,
 } from "@/lib/builder-design-system-upload";
-import { cn } from "@/lib/utils";
 
 interface GitHubLink {
   id: string;
@@ -55,7 +53,13 @@ interface UploadedFile {
   textContent?: string;
 }
 
-type OtherSource = "brand" | "code" | "files" | "existing" | "notes";
+type OtherSource =
+  | "brand"
+  | "code"
+  | "design-md"
+  | "files"
+  | "existing"
+  | "notes";
 
 interface BuilderIndexResult {
   ok: boolean;
@@ -91,6 +95,8 @@ interface BuilderIndexInput {
   designMd?: string;
 }
 
+const MAX_INLINE_DESIGN_MD_BYTES = 2 * 1024 * 1024;
+
 export default function DesignSystemSetup() {
   const t = useT();
   const navigate = useNavigate();
@@ -105,6 +111,7 @@ export default function DesignSystemSetup() {
   const [githubPaths, setGithubPaths] = useState("");
   const [githubLinks, setGithubLinks] = useState<GitHubLink[]>([]);
   const [codeFiles, setCodeFiles] = useState<UploadedFile[]>([]);
+  const [designMdFiles, setDesignMdFiles] = useState<UploadedFile[]>([]);
   const [docFiles, setDocFiles] = useState<UploadedFile[]>([]);
   const [imageFiles, setImageFiles] = useState<UploadedFile[]>([]);
   const [assets, setAssets] = useState<UploadedFile[]>([]);
@@ -119,6 +126,8 @@ export default function DesignSystemSetup() {
   const imageInputRef = useRef<HTMLInputElement>(null);
   const assetInputRef = useRef<HTMLInputElement>(null);
   const codeInputRef = useRef<HTMLInputElement>(null);
+  const designMdInputRef = useRef<HTMLInputElement>(null);
+  const designMdUploadGenerationRef = useRef(0);
   const appliedSourceIdRef = useRef<string | null>(null);
 
   const { data: designsData } = useActionQuery<{
@@ -264,6 +273,7 @@ export default function DesignSystemSetup() {
       githubUrl.trim() ||
       githubLinks.length > 0 ||
       codeFiles.length > 0 ||
+      designMdFiles.length > 0 ||
       builderIndexResult ||
       docFiles.length > 0 ||
       imageFiles.length > 0 ||
@@ -279,6 +289,7 @@ export default function DesignSystemSetup() {
     githubUrl,
     githubLinks,
     codeFiles,
+    designMdFiles,
     builderIndexResult,
     docFiles,
     imageFiles,
@@ -390,6 +401,48 @@ export default function DesignSystemSetup() {
     [readTextFiles],
   );
 
+  const handleDesignMdUpload = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const files = e.target.files;
+      if (!files) return;
+      const file = files[0];
+      e.target.value = "";
+      if (!file) return;
+      const uploadGeneration = ++designMdUploadGenerationRef.current;
+      setDesignMdFiles([]);
+      if (!isDesignMdFile({ name: file.name })) {
+        setValidationError(t("designSystemSetup.errors.chooseDesignMd"));
+        return;
+      }
+      if (file.size > MAX_INLINE_DESIGN_MD_BYTES) {
+        setValidationError(t("designSystemSetup.errors.designMdTooLarge"));
+        return;
+      }
+      const uploadedFile: UploadedFile = {
+        id: crypto.randomUUID(),
+        name: file.name,
+        type: file.type || "text/markdown",
+        size: file.size,
+      };
+      file
+        .text()
+        .then((text) => {
+          if (designMdUploadGenerationRef.current !== uploadGeneration) {
+            return;
+          }
+          setDesignMdFiles([{ ...uploadedFile, textContent: text }]);
+          setValidationError(null);
+        })
+        .catch(() => {
+          if (designMdUploadGenerationRef.current !== uploadGeneration) {
+            return;
+          }
+          setValidationError(t("designSystemSetup.errors.readDesignMd"));
+        });
+    },
+    [t],
+  );
+
   const handleDocUpload = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
       if (!e.target.files) return;
@@ -487,6 +540,7 @@ export default function DesignSystemSetup() {
       normalizedGithubLinks.length > 0 &&
       normalizedWebsiteUrls.length === 0 &&
       codeFiles.length === 0 &&
+      designMdFiles.length === 0 &&
       !builderIndexResult &&
       docFiles.length === 0 &&
       imageFiles.length === 0 &&
@@ -521,11 +575,53 @@ export default function DesignSystemSetup() {
     }
 
     const readableCodeFiles = codeFiles.filter((f) => f.textContent);
-    const designMdFiles = readableCodeFiles.filter(isDesignMdFile);
+    const codeDesignMdFiles = readableCodeFiles.filter(isDesignMdFile);
     const builderCodeFiles = readableCodeFiles.filter(
       (file) => !isDesignMdFile(file),
     );
     const unreadableCodeFiles = codeFiles.filter((f) => !f.textContent);
+    const readableDesignMdFiles = designMdFiles.filter(
+      (file) => file.textContent,
+    );
+
+    if (designMdFiles.length > 0 && readableDesignMdFiles.length === 0) {
+      setValidationError(t("designSystemSetup.errors.readDesignMd"));
+      return;
+    }
+
+    const isDesignMdOnlySource =
+      readableDesignMdFiles.length > 0 &&
+      normalizedGithubLinks.length === 0 &&
+      normalizedWebsiteUrls.length === 0 &&
+      codeFiles.length === 0 &&
+      !builderIndexResult &&
+      docFiles.length === 0 &&
+      imageFiles.length === 0 &&
+      assets.length === 0 &&
+      !selectedProjectId;
+
+    if (isDesignMdOnlySource) {
+      setValidationError(null);
+      try {
+        await indexSystemMutation.mutateAsync({
+          projectName: companyInfo.trim() || undefined,
+          description:
+            [notes.trim(), customInstructions.trim()]
+              .filter(Boolean)
+              .join("\n\n") || undefined,
+          designMd: readableDesignMdFiles[0]?.textContent,
+        });
+        toast.success(t("designSystemSetup.designMdIndexStarted"));
+        navigate("/design-systems");
+      } catch (error) {
+        setValidationError(
+          error instanceof Error
+            ? error.message
+            : t("designSystemSetup.errors.designMdIndex"),
+        );
+      }
+      return;
+    }
 
     const parts: string[] = [];
     parts.push(
@@ -569,11 +665,11 @@ export default function DesignSystemSetup() {
           );
         }
       }
-      if (designMdFiles.length > 0) {
+      if (codeDesignMdFiles.length > 0) {
         parts.push(
-          `\n## Optional design.md (${designMdFiles.length} file${designMdFiles.length === 1 ? "" : "s"})\nPass this content as the \`designMd\` argument to \`index-design-system-with-builder\` alongside any Figma/code sources:`,
+          `\n## Optional design.md (${codeDesignMdFiles.length} file${codeDesignMdFiles.length === 1 ? "" : "s"})\nPass this content as the \`designMd\` argument to \`index-design-system-with-builder\` alongside any Figma/code sources:`,
         );
-        for (const f of designMdFiles) {
+        for (const f of codeDesignMdFiles) {
           parts.push(
             `\n### ${f.name}\n\`\`\`md\n${f.textContent!.slice(0, 5000)}\n\`\`\``,
           );
@@ -586,6 +682,17 @@ export default function DesignSystemSetup() {
       }
     }
 
+    if (designMdFiles.length > 0) {
+      parts.push(
+        `\n## design.md\nPass this content as the \`designMd\` argument to \`index-design-system-with-builder\` alongside any Figma/code sources:`,
+      );
+      for (const f of readableDesignMdFiles) {
+        parts.push(
+          `\n### ${f.name}\n\`\`\`md\n${f.textContent!.slice(0, 5000)}\n\`\`\``,
+        );
+      }
+    }
+
     if (builderIndexResult) {
       parts.push(
         `\n## Connect Figma: Builder-Indexed Figma File\nBuilder DSI indexing has already started.\n- Design system: ${builderIndexResult.designSystemId}\n- Local selectable design system: ${builderIndexResult.localDesignSystemId ?? "(not returned)"}\n- Project: ${builderIndexResult.projectId}\n- Job: ${builderIndexResult.jobId}\n- URL: ${builderIndexResult.builderUrl}\n\nUse Builder as the source of truth for indexed tokens, assets, components, and guidance. Do not call \`create-design-system\` again for this Builder-indexed source.`,
@@ -680,6 +787,7 @@ export default function DesignSystemSetup() {
     githubPaths,
     githubLinks,
     codeFiles,
+    designMdFiles,
     builderIndexResult,
     docFiles,
     imageFiles,
@@ -782,6 +890,14 @@ export default function DesignSystemSetup() {
                   selected={sourcePanel === "other" && otherSource === "code"}
                   onClick={() => selectOtherSource("code")}
                 />
+                <SourceChoice
+                  icon={IconFileDescription}
+                  title={t("designSystemSetup.sections.designMd.title")}
+                  selected={
+                    sourcePanel === "other" && otherSource === "design-md"
+                  }
+                  onClick={() => selectOtherSource("design-md")}
+                />
                 <SourceChoice
                   icon={IconFileDescription}
                   title={t("designSystemSetup.sections.designFiles.title")}
@@ -1103,6 +1219,45 @@ export default function DesignSystemSetup() {
               </div>
             </Section>
 
+            {/* Import design.md guidance directly into Builder DSI. */}
+            <Section
+              title={t("designSystemSetup.sections.designMd.title")}
+              description={t("designSystemSetup.sections.designMd.description")}
+              hidden={sourcePanel !== "other" || otherSource !== "design-md"}
+              hideHeading
+              id="design-system-design-md-source"
+              className="rounded-lg border border-border bg-card p-4"
+            >
+              <button
+                type="button"
+                onClick={() => designMdInputRef.current?.click()}
+                className="w-full rounded-xl border border-dashed border-border bg-card p-8 text-center hover:border-foreground/15 cursor-pointer"
+              >
+                <div className="flex flex-col items-center gap-2">
+                  <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-primary/10">
+                    <IconFileDescription className="size-6 text-primary" />
+                  </div>
+                  <p className="text-sm font-medium text-foreground/90">
+                    {t("designSystemSetup.designMdUpload")}
+                  </p>
+                  <p className="text-xs text-muted-foreground/70">
+                    {t("designSystemSetup.designMdHelp")}
+                  </p>
+                </div>
+              </button>
+              <input
+                ref={designMdInputRef}
+                type="file"
+                accept=".md,.mdx"
+                onChange={handleDesignMdUpload}
+                className="hidden"
+              />
+              <FileList
+                files={designMdFiles}
+                onRemove={() => setDesignMdFiles([])}
+              />
+            </Section>
+
             {/* Design Files */}
             <Section
               title={t("designSystemSetup.sections.designFiles.title")}
@@ -1507,7 +1662,7 @@ function formatSize(bytes: number): string {
   return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
 
-function isDesignMdFile(file: UploadedFile): boolean {
+function isDesignMdFile(file: Pick<UploadedFile, "name">): boolean {
   const name = file.name.split(/[\\/]/).pop()?.toLowerCase() ?? file.name;
   return name === "design.md" || name === "design.mdx";
 }

package/corpus/templates/design/app/pages/Index.tsx

@@ -42,6 +42,7 @@ import { useState, useRef, useCallback, useEffect, useMemo } from "react";
 import { useNavigate, Link, useSearchParams } from "react-router";
 import { toast } from "sonner";
 
+import { trace } from "@/components/design/design-trace";
 import PromptPopover from "@/components/editor/PromptDialog";
 import type {
   PromptTemplateOption,
@@ -624,8 +625,24 @@ export default function Index() {
           skipQuestions: pendingOptions?.skipQuestions,
           ...options,
         });
+        // Rejecting here is what lets PromptPopover restore the typed prompt.
+        // Navigating first strands the user in an empty editor with no error.
+        try {
+          await ready;
+        } catch (error) {
+          clearPendingGeneration(id);
+          setNewDesignHandoffPending(false);
+          trace("persist", "create-design-failed", {
+            id,
+            designSystemId,
+            message: error instanceof Error ? error.message : String(error),
+          });
+          toast.error(t("home.failedToCreateDesign"));
+          throw error;
+        }
       }
 
+      trace("persist", "new-design-handoff", { id, designSystemId });
       setNewDesignHandoffPending(true);
       navigate(`/design/${id}`);
     },

package/corpus/templates/design/app/pages/design-editor/canvas-primitive-insert.ts

@@ -9,11 +9,12 @@ import type { CanvasPrimitiveInsert } from "@/components/design/multi-screen/typ
 
 import {
   CANVAS_TEXT_DEFAULT_FONT_FAMILY,
+  defaultCanvasFrameFill,
   defaultCanvasTextColor,
 } from "./canvas-primitives";
 import {
   BOARD_TEXT_AUTO_COLOR_MARKER,
-  destinationBackgroundIsLightForNode,
+  destinationBackgroundLightness,
 } from "./cross-screen-text-color";
 import { escapeHtmlAttributeValue, escapeHtmlText } from "./dom-utils";
 import { isStandaloneHttpUrl } from "./editor-state";
@@ -219,8 +220,9 @@ function absoluteRect(
     ) {
       continue;
     }
-    originX += read(ancestor.style.left) ?? 0;
-    originY += read(ancestor.style.top) ?? 0;
+    const inset = inlineBorderInset(ancestor);
+    originX += (read(ancestor.style.left) ?? 0) + inset.x;
+    originY += (read(ancestor.style.top) ?? 0) + inset.y;
   }
   return { x: originX + x, y: originY + y, w, h };
 }
@@ -230,12 +232,20 @@ function absoluteRect(
  * `data-an-primitive="frame"` adopts. Bounds come from inline geometry
  * because this document is parsed, never laid out.
  */
+/** Inline border widths, which an absolute child's offsets resolve inside of. */
+function inlineBorderInset(element: Element): { x: number; y: number } {
+  const style = (element as HTMLElement).style;
+  const read = (value: string) => {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  };
+  return { x: read(style.borderLeftWidth), y: read(style.borderTopWidth) };
+}
+
 function deepestFrameContaining(
   root: Element,
   x: number,
   y: number,
-  w: number,
-  h: number,
 ): { element: Element; x: number; y: number } | null {
   const contained = Array.from(
     root.querySelectorAll('[data-an-primitive="frame"]'),
@@ -248,11 +258,14 @@ function deepestFrameContaining(
         element: Element;
         rect: { x: number; y: number; w: number; h: number };
       } =>
+        // Nest on the origin, as Figma does. Requiring the whole box to fit
+        // drops a click-created text (default width) out to the root, where
+        // it overlaps the frame it looks like it belongs to.
         candidate.rect !== null &&
         x >= candidate.rect.x &&
         y >= candidate.rect.y &&
-        x + w <= candidate.rect.x + candidate.rect.w &&
-        y + h <= candidate.rect.y + candidate.rect.h,
+        x <= candidate.rect.x + candidate.rect.w &&
+        y <= candidate.rect.y + candidate.rect.h,
     )
     .sort((a, b) => a.rect.w * a.rect.h - b.rect.w * b.rect.h);
   const best = contained[0];
@@ -288,8 +301,14 @@ export function appendCanvasPrimitiveToHtml(
     const layerName = primitiveLayerName(primitive);
     // Resolved once so every primitive kind nests identically, and so text can
     // pick a fill that is legible against its actual container.
-    const host = deepestFrameContaining(doc.body, left, top, width, height);
+    const host = deepestFrameContaining(doc.body, left, top);
     const hostOrBody: Element = host?.element ?? doc.body;
+    // An absolute child resolves against the host's PADDING box, while
+    // host.x/host.y are its border-box origin — so a bordered frame shifts
+    // everything dropped into it by the border width.
+    const hostBorder = host ? inlineBorderInset(host.element) : { x: 0, y: 0 };
+    const hostLeft = host ? left - host.x - hostBorder.x : left;
+    const hostTop = host ? top - host.y - hostBorder.y : top;
 
     if (
       primitive.kind === "path" ||
@@ -398,8 +417,8 @@ export function appendCanvasPrimitiveToHtml(
         "style",
         [
           "position:absolute",
-          `left:${left}px`,
-          `top:${top}px`,
+          `left:${hostLeft}px`,
+          `top:${hostTop}px`,
           `width:${width}px`,
           `height:${height}px`,
           "overflow:visible",
@@ -441,8 +460,8 @@ export function appendCanvasPrimitiveToHtml(
         "style",
         [
           "position:absolute",
-          `left:${left}px`,
-          `top:${top}px`,
+          `left:${hostLeft}px`,
+          `top:${hostTop}px`,
           `width:${width}px`,
           `height:${height}px`,
           "overflow:visible",
@@ -464,8 +483,8 @@ export function appendCanvasPrimitiveToHtml(
     // glyph. Read by treeTypeForNode in shared/code-layer.ts.
     element.setAttribute("data-an-primitive", primitive.kind);
     element.style.position = "absolute";
-    element.style.left = `${left}px`;
-    element.style.top = `${top}px`;
+    element.style.left = `${hostLeft}px`;
+    element.style.top = `${hostTop}px`;
     if (!(primitive.kind === "text" && primitive.autoSize)) {
       element.style.width = `${width}px`;
       element.style.height = `${height}px`;
@@ -482,19 +501,12 @@ export function appendCanvasPrimitiveToHtml(
       primitive.kind === "rectangle" ? "rect" : primitive.kind,
     );
     if (primitive.kind === "frame") {
-      // A committed frame is a BARE container <div> — no default fill,
-      // border, or radius — so the markup this code-first editor emits stays
-      // clean (a Figma frame reads as unstyled structure, and a dashed
-      // border/tint baked into the design's real HTML would be styling
-      // pollution). This deliberately diverges from the draft PREVIEW's
-      // faint-tint/dashed look (canvas-primitive-style.ts), which is editor
-      // affordance chrome during the drag; on commit the new frame is
-      // immediately selected, so its bounds stay visible via selection
-      // chrome instead. Explicit user-chosen fill/stroke still applies.
+      // A committed frame carries a real surface, not the draft preview's
+      // dashed tint (editor chrome, canvas-primitive-style.ts): selection
+      // chrome only covers the frame while it stays selected, and a bare
+      // container is invisible the moment it is not.
       // overflow:hidden matches Figma frames clipping their content.
-      if (primitive.fill) {
-        element.style.background = primitive.fill;
-      }
+      element.style.background = primitive.fill ?? defaultCanvasFrameFill();
       if (
         primitive.stroke !== undefined ||
         primitive.strokeWidth !== undefined
@@ -516,9 +528,13 @@ export function appendCanvasPrimitiveToHtml(
       // "currentColor" so text still inherits their theme.
       // Measure the frame the text actually lands in: a dark frame on a light
       // page would otherwise keep currentColor and render invisible.
+      // isBoardTarget only says which surface is behind the text, and the
+      // board is not always dark — a measured background always wins.
+      const measuredLightness = destinationBackgroundLightness(hostOrBody);
       const autoTextNeedsLightFill =
-        options?.isBoardTarget === true ||
-        !destinationBackgroundIsLightForNode(hostOrBody);
+        measuredLightness === null
+          ? options?.isBoardTarget === true
+          : !measuredLightness;
       const resolvedTextColor =
         primitive.fill ?? defaultCanvasTextColor(autoTextNeedsLightFill);
       element.style.color = resolvedTextColor;
@@ -560,10 +576,6 @@ export function appendCanvasPrimitiveToHtml(
       element.style.borderRadius = canonical.borderRadius;
     }
 
-    if (host) {
-      element.style.left = `${left - host.x}px`;
-      element.style.top = `${top - host.y}px`;
-    }
     hostOrBody.appendChild(element);
     return `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
   } catch {

package/corpus/templates/design/app/pages/design-editor/canvas-primitives.ts

@@ -222,6 +222,16 @@ export function defaultCanvasTextColor(isBoardTarget: boolean): string {
   return isBoardTarget ? "#ffffff" : "currentColor";
 }
 
+/**
+ * A committed frame needs a surface of its own: once deselected, a bare
+ * container is indistinguishable from empty canvas, and so is the next one
+ * drawn beside it. White on every destination, as in Figma.
+ */
+export function defaultCanvasFrameFill(): string {
+  // guard:allow-raw-color — written into the user's design HTML, where the editor's theme tokens do not exist
+  return "#ffffff";
+}
+
 /** Default font stack for board-drawn text — Inter with the app's standard
  * system-font fallback chain, matching the rest of the editor's UI type
  * instead of the browser's serif default for an unstyled <div>. */

package/corpus/templates/design/app/pages/design-editor/clone-and-pen-edit.ts

@@ -12,7 +12,10 @@ import {
 } from "@/lib/design-clipboard-managed-styles";
 
 import { uniqueLayerId } from "./canvas-primitive-insert";
-import { reassignClonedAuthoredIds } from "./clone-idrefs";
+import {
+  reassignClonedAuthoredIds,
+  reassignClonedSourceIdentity,
+} from "./clone-idrefs";
 import { queryUniqueSelector } from "./dom-utils";
 import { isStandaloneHttpUrl } from "./editor-state";
 import {
@@ -184,10 +187,27 @@ function setRootLayerPosition(
   host.style.bottom = "";
 }
 
+/**
+ * Keep an incoming node id the destination does not already use, so a clone
+ * the caller already rendered stays addressable by the id it carries.
+ */
+function claimClonedNodeId(
+  previousId: string | null,
+  fallbackPrefix: string,
+  reservedNodeIds: Set<string> | null,
+): string {
+  if (!reservedNodeIds || !previousId || reservedNodeIds.has(previousId)) {
+    return uniqueLayerId(fallbackPrefix);
+  }
+  reservedNodeIds.add(previousId);
+  return previousId;
+}
+
 function prepareClonedHtmlLayer(
   doc: Document,
   layerHtml: string,
   styleSnapshot?: PortableStyleSnapshot,
+  reservedNodeIds: Set<string> | null = null,
 ): {
   element: Element;
   rootNodeId: string;
@@ -215,13 +235,21 @@ function prepareClonedHtmlLayer(
   }
   const nodeIdMap = new Map<string, string>();
   const previousRootNodeId = clone.getAttribute("data-agent-native-node-id");
-  const rootNodeId = uniqueLayerId("copy");
+  const rootNodeId = claimClonedNodeId(
+    previousRootNodeId,
+    "copy",
+    reservedNodeIds,
+  );
   clone.setAttribute("data-agent-native-node-id", rootNodeId);
   if (previousRootNodeId) nodeIdMap.set(previousRootNodeId, rootNodeId);
   Array.from(clone.querySelectorAll("[data-agent-native-node-id]")).forEach(
     (node) => {
       const previousChildId = node.getAttribute("data-agent-native-node-id");
-      const nextChildId = uniqueLayerId("copy-child");
+      const nextChildId = claimClonedNodeId(
+        previousChildId,
+        "copy-child",
+        reservedNodeIds,
+      );
       node.setAttribute("data-agent-native-node-id", nextChildId);
       if (previousChildId) nodeIdMap.set(previousChildId, nextChildId);
     },
@@ -234,6 +262,7 @@ function prepareClonedHtmlLayer(
   // happens to match first (typically the ORIGINAL, not the new copy),
   // silently misapplying edits meant for the duplicate.
   reassignClonedAuthoredIds(clone, () => uniqueLayerId("copy-id"));
+  reassignClonedSourceIdentity(clone, () => uniqueLayerId("copy-child"));
   return { element: clone, rootNodeId, nodeIdMap };
 }
 
@@ -345,6 +374,13 @@ export function insertClonedHtmlLayers(
     managedStyleSnapshots?: Array<
       DesignClipboardManagedStyleSnapshot | null | undefined
     >;
+    /**
+     * The layer html describes an element the caller has ALREADY rendered
+     * under these ids. Re-minting them strands that element: every later
+     * message addresses an id the document lacks, and the fuzzy resolver
+     * behind it lands on the node the clone was copied from.
+     */
+    preserveIncomingNodeIds?: boolean;
   } = {},
 ): {
   content: string;
@@ -365,11 +401,19 @@ export function insertClonedHtmlLayers(
     const fragment = doc.createDocumentFragment();
     const rootNodeIds: string[] = [];
     const nodeIdMap = new Map<string, string>();
+    const reservedNodeIds = options.preserveIncomingNodeIds
+      ? new Set(
+          Array.from(doc.querySelectorAll("[data-agent-native-node-id]"))
+            .map((node) => node.getAttribute("data-agent-native-node-id"))
+            .filter((value): value is string => Boolean(value)),
+        )
+      : null;
     layerHtmls.forEach((layerHtml, index) => {
       const prepared = prepareClonedHtmlLayer(
         doc,
         layerHtml,
         options.styleSnapshots?.[index] ?? undefined,
+        reservedNodeIds,
       );
       if (!prepared) return;
       const position = options.positions?.[index];
@@ -447,6 +491,7 @@ export function insertClonedHtmlLayer(
     targetSelectors: string[];
     anchorSelectors?: string[];
     placement?: "before" | "after" | "inside";
+    preserveIncomingNodeIds?: boolean;
   },
 ): string | null {
   return (
@@ -454,6 +499,7 @@ export function insertClonedHtmlLayer(
       targetSelectors: options.targetSelectors,
       anchorSelectors: options.anchorSelectors,
       placement: options.placement,
+      preserveIncomingNodeIds: options.preserveIncomingNodeIds,
     })?.content ?? null
   );
 }

package/corpus/templates/design/app/pages/design-editor/clone-idrefs.ts

@@ -12,6 +12,16 @@ const SPACE_SEPARATED_IDREF_ATTRIBUTES = [
 const SINGLE_IDREF_ATTRIBUTES = ["for", "form", "list"] as const;
 const FRAGMENT_REFERENCE_ATTRIBUTES = ["href", "xlink:href"] as const;
 
+// Lookups test every stable id attribute, so re-stamping
+// `data-agent-native-node-id` does not shadow an inherited one.
+// `data-source-file`/`-line`/`-column` are provenance, not identity — keep them.
+const INHERITED_SOURCE_IDENTITY_ATTRIBUTES = [
+  "data-code-layer-id",
+  "data-layer-id",
+  "data-builder-id",
+  "data-loc",
+] as const;
+
 function allElements(root: Element): Element[] {
   return [root, ...Array.from(root.querySelectorAll("*"))];
 }
@@ -111,3 +121,24 @@ export function reassignClonedAuthoredIds(
 
   return idMap;
 }
+
+/**
+ * Replace a cloned subtree's inherited source identity with fresh node ids, so
+ * edits and deletes addressed to the clone cannot resolve to the original.
+ */
+export function reassignClonedSourceIdentity(
+  root: Element,
+  createNodeId: () => string,
+): void {
+  for (const element of allElements(root)) {
+    let inheritedIdentity = false;
+    for (const attribute of INHERITED_SOURCE_IDENTITY_ATTRIBUTES) {
+      if (!element.hasAttribute(attribute)) continue;
+      element.removeAttribute(attribute);
+      inheritedIdentity = true;
+    }
+    if (!inheritedIdentity) continue;
+    if (element.hasAttribute("data-agent-native-node-id")) continue;
+    element.setAttribute("data-agent-native-node-id", createNodeId());
+  }
+}