@agent-native/core 0.129.1 → 0.130.0

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

@@ -168,6 +168,11 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       '[data-agent-native-empty-text-editing="true"] [data-agent-native-edit-overlay="selection"]{display:none!important}' +
       "[data-agent-native-text-editing]{outline:none!important;outline-offset:0!important}" +
       "[data-agent-native-edge-handle],[data-agent-native-edit-handle],[data-agent-native-rotate-handle]{transition:width 150ms ease-out,height 150ms ease-out,border-width 150ms ease-out,top 150ms ease-out,bottom 150ms ease-out,left 150ms ease-out,right 150ms ease-out}" +
+      // Locked layers get a neutral dashed hairline instead of an accent one:
+      // accent means "selected" everywhere else in the canvas chrome, and a
+      // locked layer is usually neither selected nor selectable. The width
+      // rides the chrome line scale so it stays one screen pixel at any zoom.
+      '[data-agent-native-runtime-locked="true"]{outline:calc(1px * var(--agent-native-editor-chrome-line-scale, 1)) dashed rgba(148,163,184,0.9)!important;outline-offset:0!important;cursor:not-allowed!important}' +
       "[data-agent-native-spacing-line]{position:absolute;display:none;pointer-events:none;border-radius:999px}" +
       "[data-agent-native-spacing-region]{position:absolute;display:none;box-sizing:border-box;pointer-events:auto;background-size:6px 6px}" +
       '[data-agent-native-spacing-region][data-orientation="vertical"]{cursor:ew-resize}' +
@@ -426,13 +431,168 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
   }
 
   /**
-   * React 19 development builds keep the exact jsxDEV call site on the host
-   * element's Fiber `_debugStack`, even though React does not emit that source
-   * location as a DOM attribute. Recover it without depending on React internals
-   * for mutations: this is read-only provenance used to identify the selected
-   * source file and line. Explicit data-source-* / data-loc attributes still
-   * win below, and production builds simply return undefined.
+   * Resolve a DOM element to the authored source site exposed by its framework
+   * dev runtime, read-only, so the editor and coding agent anchor to evidence
+   * instead of a selector guess. Explicit data-source-* / data-loc attributes
+   * still win at the call sites below.
+   *
+   * React tiers:
+   *   • React <=18 — the structured `_debugSource` fiber field (authored file,
+   *     line and column, emitted by the dev JSX transform).
+   *   • React 19 — `_debugSource` is gone; parse the `_debugStack` owner stack
+   *     captured at element creation.
+   * Vue's dev compiler exposes `vnode.props.__v_inspector`; Svelte's dev
+   * compiler exposes `element.__svelte_meta.loc`. Both are authored compiler
+   * coordinates. When a runtime omits its dev metadata, report WHY
+   * (`unavailableReason`) instead of guessing.
+   *
+   * `sourceFile`/`line`/`column` are the element's OWN authoring site (a button
+   * inside Card.jsx always resolves to Card.jsx). `owner*` is where the nearest
+   * enclosing component was instantiated — `<Card …>` in the parent — which is
+   * what separates a directly-authored instance from `.map()`-produced ones.
+   * All `.map()` siblings share one owner site, so `ownerKey` (their React key)
+   * is the only source-derived signal that tells them apart.
+   *
+   * TRAP: a `_debugStack` frame points into the file the dev server SERVES, so
+   * under a transforming dev server (Vite's React plugin, Next.js) its line is
+   * the transformed line, not the authored one — `_debugSource` and
+   * data-source-* attributes are authored coordinates. React 19 has ONLY the
+   * stack tier, so this is the common case, not the corner: on the React 19.2 +
+   * Vite 8 target an `<h1>` authored at line 13 reports as line 26. That is why
+   * every result carries `method`, and why nothing downstream may present a
+   * `debug-stack` position as the authored JSX line.
+   *
+   * Keep in sync with ../../../pages/design-editor/source-location.ts (the
+   * unit-tested parser) and source-location.bridge.ts; bridge files may not
+   * import, so the parsing is duplicated by hand.
    */
+  var PROVENANCE_NOISE_SEGMENTS: Record<string, true> = {
+    node_modules: true,
+    dist: true,
+    build: true,
+    ".next": true,
+    public: true,
+  };
+
+  function isProvenanceNoisePath(path: string): boolean {
+    var segments = path.split("/");
+    for (var i = 0; i < segments.length; i += 1) {
+      if (PROVENANCE_NOISE_SEGMENTS[segments[i]!]) return true;
+      if (segments[i] === "_next" && segments[i + 1] === "static") return true;
+    }
+    return false;
+  }
+
+  // webpack-internal:/// (webpack/Next.js/CRA), Vite's /@fs/ absolute serving,
+  // plain http(s) dev-server paths and file: URLs all reduce to one path here.
+  function resolveProvenanceFrameUrl(rawUrl: string): string | null {
+    if (rawUrl.indexOf("webpack-internal:///") === 0) {
+      var webpackPath = rawUrl
+        .slice("webpack-internal:///".length)
+        .replace(/^\.\//, "");
+      return webpackPath || null;
+    }
+    try {
+      var url = new URL(rawUrl);
+      var path = decodeURIComponent(url.pathname);
+      if (path.indexOf("/@fs/") === 0) {
+        path = path.slice("/@fs".length);
+      } else if (url.protocol !== "file:") {
+        path = path.replace(/^\/+/, "");
+      }
+      return path || null;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  var PROVENANCE_STACK_FRAME_RE =
+    /^\s*at\s+(?:([^\s(]+)\s+\()?([^()\s][^()]*?):(\d+):(\d+)\)?\s*$/;
+
+  function parseProvenanceStackFrame(lineText: string): {
+    sourceFile: string;
+    line: number;
+    column: number;
+    functionName?: string;
+  } | null {
+    var match = PROVENANCE_STACK_FRAME_RE.exec(lineText);
+    if (!match) return null;
+    var sourceFile = resolveProvenanceFrameUrl(match[2]!);
+    if (!sourceFile || isProvenanceNoisePath(sourceFile)) return null;
+    var line = parseInt(match[3]!, 10);
+    var column = parseInt(match[4]!, 10);
+    if (!isFinite(line) || !isFinite(column)) return null;
+    return {
+      sourceFile: sourceFile,
+      line: line,
+      column: column,
+      functionName: match[1] || undefined,
+    };
+  }
+
+  function fiberDebugLocation(fiber: any): {
+    sourceFile: string;
+    line: number;
+    column?: number;
+    functionName?: string;
+    structured: boolean;
+  } | null {
+    var source =
+      fiber._debugSource ||
+      (fiber._debugInfo && fiber._debugInfo.source) ||
+      (fiber.stateNode && fiber.stateNode._debugSource) ||
+      (fiber.elementType && fiber.elementType._debugSource);
+    if (source && source.fileName) {
+      return {
+        sourceFile: source.fileName,
+        line: source.lineNumber,
+        column: source.columnNumber,
+        structured: true,
+      };
+    }
+    var stack =
+      (fiber._debugStack && fiber._debugStack.stack) ||
+      (fiber._debugInfo && fiber._debugInfo.stack) ||
+      (fiber.stateNode &&
+        fiber.stateNode._debugStack &&
+        fiber.stateNode._debugStack.stack);
+    if (!stack) return null;
+    var lines = String(stack).split("\n");
+    for (var index = 0; index < lines.length; index += 1) {
+      var parsed = parseProvenanceStackFrame(lines[index]!);
+      if (parsed) {
+        return {
+          sourceFile: parsed.sourceFile,
+          line: parsed.line,
+          column: parsed.column,
+          functionName: parsed.functionName,
+          structured: false,
+        };
+      }
+    }
+    return null;
+  }
+
+  type FrameworkDebugProvenance = {
+    framework?: "react" | "vue" | "svelte";
+    sourceFile?: string;
+    line?: number;
+    column?: number;
+    component?: string;
+    ownerSourceFile?: string;
+    ownerLine?: number;
+    ownerColumn?: number;
+    ownerComponentName?: string;
+    ownerKey?: string;
+    // Which tier produced line/column. "debug-stack" is a TRANSFORMED position.
+    method?: "debug-source" | "debug-stack" | "vue-inspector" | "svelte-meta";
+    // Which tier produced ownerLine/ownerColumn. Tracked separately because an
+    // element can carry an authored data-source-* position while its owner site
+    // is only reachable through the (transformed) owner stack.
+    ownerMethod?: "debug-source" | "debug-stack";
+    unavailableReason?: "not-framework" | "no-debug-info";
+  };
+
   // Fiber debug stacks are immutable for the lifetime of a mounted host node.
   // Keep the relatively expensive Object.keys + owner walk off the snapshot
   // hot path after the first successful read. A WeakMap also means React can
@@ -440,58 +600,190 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
   // before a slow/Suspense hydration attaches Fiber to an existing DOM node.
   var reactDebugProvenanceCache =
     typeof WeakMap !== "undefined"
-      ? new WeakMap<Element, ReturnType<typeof reactDebugProvenance>>()
+      ? new WeakMap<Element, FrameworkDebugProvenance>()
       : null;
 
-  function reactDebugProvenance(el: Element):
-    | {
-        sourceFile: string;
-        line: number;
-        column?: number;
-        component?: string;
+  var REACT_FIBER_KEY_PREFIXES = [
+    "__reactFiber$",
+    "__reactInternalInstance$",
+    "__reactInternalFiberCurrent$",
+    "__reactInternalFiber$",
+  ];
+
+  function reactFiberOf(el: Element): any {
+    var keys = Object.keys(el);
+    for (var i = 0; i < keys.length; i += 1) {
+      for (var j = 0; j < REACT_FIBER_KEY_PREFIXES.length; j += 1) {
+        if (keys[i]!.indexOf(REACT_FIBER_KEY_PREFIXES[j]!) === 0) {
+          return (el as unknown as Record<string, any>)[keys[i]!];
+        }
       }
-    | undefined {
+    }
+    return null;
+  }
+
+  function reactDebugProvenance(el: Element): FrameworkDebugProvenance {
     var cached = reactDebugProvenanceCache?.get(el);
     if (cached !== undefined) return cached;
-    var fiberKey = Object.keys(el).find(function (key) {
-      return key.indexOf("__reactFiber$") === 0;
-    });
-    if (!fiberKey) return undefined;
-    var fiber = (el as unknown as Record<string, any>)[fiberKey];
+    // Deliberately no climb to an ancestor's fiber: this runs over every node
+    // in the runtime snapshot, and borrowing a parent's location would stamp a
+    // non-React node with a source line that is not its own.
+    var leafFiber = reactFiberOf(el);
+    if (!leafFiber) return { unavailableReason: "not-framework" };
+
+    var elementLocation: ReturnType<typeof fiberDebugLocation> = null;
+    var componentFiber: any = null;
+    var fiber = leafFiber;
     for (var depth = 0; fiber && depth < 12; depth += 1) {
-      var stack = String(fiber._debugStack?.stack || "");
-      var lines = stack.split("\n");
-      for (var index = 0; index < lines.length; index += 1) {
-        var lineText = lines[index];
-        var match = lineText.match(
-          /(?:\(|\s)(https?:\/\/[^\s)]+?):(\d+):(\d+)\)?\s*$/,
-        );
-        if (!match) continue;
-        try {
-          var sourceUrl = new URL(match[1]);
-          var pathname = decodeURIComponent(sourceUrl.pathname);
-          if (pathname.indexOf("/node_modules/") >= 0) continue;
-          var sourceFile =
-            pathname.indexOf("/@fs/") === 0
-              ? pathname.slice("/@fs".length)
-              : pathname.replace(/^\/+/, "");
-          if (!sourceFile) continue;
-          var componentMatch = lineText.match(/\bat\s+([^\s(]+)\s*\(/);
-          var provenance = {
-            sourceFile: sourceFile,
-            line: parseInt(match[2], 10),
-            column: parseInt(match[3], 10),
-            component: componentMatch ? componentMatch[1] : undefined,
+      if (!elementLocation) elementLocation = fiberDebugLocation(fiber);
+      if (
+        !componentFiber &&
+        fiber !== leafFiber &&
+        typeof fiber.type === "function"
+      ) {
+        componentFiber = fiber;
+      }
+      if (elementLocation && componentFiber) break;
+      fiber = fiber.return;
+    }
+    if (!elementLocation) {
+      return { framework: "react", unavailableReason: "no-debug-info" };
+    }
+
+    var componentName =
+      (componentFiber &&
+        componentFiber.type &&
+        (componentFiber.type.displayName || componentFiber.type.name)) ||
+      elementLocation.functionName ||
+      undefined;
+    var provenance: FrameworkDebugProvenance = {
+      framework: "react",
+      sourceFile: elementLocation.sourceFile,
+      line: elementLocation.line,
+      column: elementLocation.column,
+      component: componentName,
+      method: elementLocation.structured ? "debug-source" : "debug-stack",
+    };
+    if (componentFiber) {
+      var ownerLocation = fiberDebugLocation(componentFiber);
+      if (ownerLocation) {
+        provenance.ownerSourceFile = ownerLocation.sourceFile;
+        provenance.ownerLine = ownerLocation.line;
+        provenance.ownerColumn = ownerLocation.column;
+        provenance.ownerComponentName = componentName;
+        provenance.ownerMethod = ownerLocation.structured
+          ? "debug-source"
+          : "debug-stack";
+      }
+      if (typeof componentFiber.key === "string" && componentFiber.key) {
+        provenance.ownerKey = componentFiber.key;
+      }
+    }
+    reactDebugProvenanceCache?.set(el, provenance);
+    return provenance;
+  }
+
+  function parseFrameworkDataLoc(
+    value: string,
+  ): { sourceFile: string; line: number; column?: number } | null {
+    var lastColon = value.lastIndexOf(":");
+    if (lastColon < 0) return null;
+    var lastPart = value.slice(lastColon + 1);
+    if (!/^\d+$/.test(lastPart)) return null;
+    var beforeLast = value.slice(0, lastColon);
+    var previousColon = beforeLast.lastIndexOf(":");
+    var previousPart =
+      previousColon >= 0 ? beforeLast.slice(previousColon + 1) : "";
+    var hasColumn = /^\d+$/.test(previousPart);
+    var sourceFile = (
+      hasColumn ? beforeLast.slice(0, previousColon) : beforeLast
+    ).trim();
+    var line = parseInt(hasColumn ? previousPart : lastPart, 10);
+    var column = hasColumn ? parseInt(lastPart, 10) : undefined;
+    if (!sourceFile || !isFinite(line)) return null;
+    if (column !== undefined && !isFinite(column)) return null;
+    return { sourceFile: sourceFile, line: line, column: column };
+  }
+
+  function vueDebugProvenance(el: Element): FrameworkDebugProvenance | null {
+    var node: any = el;
+    var sawVue = false;
+    for (var depth = 0; node && depth < 8; depth += 1) {
+      var vnode = node.__vnode;
+      var component = node.__vueParentComponent;
+      if (vnode || component) sawVue = true;
+      var inspector =
+        vnode && vnode.props && typeof vnode.props.__v_inspector === "string"
+          ? vnode.props.__v_inspector
+          : null;
+      if (inspector) {
+        var parsed = parseFrameworkDataLoc(inspector);
+        if (parsed) {
+          var componentType =
+            (component && component.type) || (vnode && vnode.type);
+          return {
+            framework: "vue",
+            sourceFile: parsed.sourceFile,
+            line: parsed.line,
+            column: parsed.column,
+            component:
+              componentType &&
+              (componentType.name ||
+                componentType.__name ||
+                componentType.displayName),
+            method: "vue-inspector",
           };
-          reactDebugProvenanceCache?.set(el, provenance);
-          return provenance;
-        } catch (_error) {
-          // Ignore malformed/non-URL debug frames and keep walking owners.
         }
       }
-      fiber = fiber.return;
+      node = node.parentElement;
+    }
+    return sawVue
+      ? { framework: "vue", unavailableReason: "no-debug-info" }
+      : null;
+  }
+
+  function svelteDebugProvenance(el: Element): FrameworkDebugProvenance | null {
+    var node: any = el;
+    var sawSvelte = false;
+    for (var depth = 0; node && depth < 8; depth += 1) {
+      var meta = node.__svelte_meta;
+      if (meta) sawSvelte = true;
+      var loc = meta && meta.loc;
+      var sourceFile = loc && (loc.file || loc.filename);
+      var line = loc && Number(loc.line);
+      var column = loc && Number(loc.column);
+      if (sourceFile && isFinite(line)) {
+        return {
+          framework: "svelte",
+          sourceFile: String(sourceFile),
+          line: line,
+          column: isFinite(column) ? column : undefined,
+          component:
+            typeof meta.component === "string"
+              ? meta.component
+              : typeof meta.name === "string"
+                ? meta.name
+                : undefined,
+          method: "svelte-meta",
+        };
+      }
+      node = node.parentElement;
+    }
+    return sawSvelte
+      ? { framework: "svelte", unavailableReason: "no-debug-info" }
+      : null;
+  }
+
+  function frameworkDebugProvenance(el: Element): FrameworkDebugProvenance {
+    var react = reactDebugProvenance(el);
+    if (react.sourceFile || react.unavailableReason === "no-debug-info") {
+      return react;
     }
-    return undefined;
+    var vue = vueDebugProvenance(el);
+    if (vue) return vue;
+    var svelte = svelteDebugProvenance(el);
+    if (svelte) return svelte;
+    return { unavailableReason: "not-framework" };
   }
 
   var runtimeLayerSnapshotTimer: number | null = null;
@@ -533,8 +825,8 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
   function ensureRuntimeLayerNodeId(el: Element): string {
     var existing = el.getAttribute("data-agent-native-node-id")?.trim();
     if (existing) return existing;
-    var provenance = reactDebugProvenance(el);
-    var provenanceKey = provenance
+    var provenance = frameworkDebugProvenance(el);
+    var provenanceKey = provenance.sourceFile
       ? [
           provenance.sourceFile,
           provenance.line,
@@ -692,10 +984,18 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         ensureRuntimeLayerNodeId(sourceNode),
       );
       inlineSnapshotComputedStyle(sourceNode, cloneNode);
-      var provenance = reactDebugProvenance(sourceNode);
-      if (provenance) {
+      var provenance = frameworkDebugProvenance(sourceNode);
+      if (provenance.sourceFile) {
+        if (provenance.framework) {
+          cloneNode.setAttribute("data-source-framework", provenance.framework);
+        }
         cloneNode.setAttribute("data-source-file", provenance.sourceFile);
         cloneNode.setAttribute("data-source-line", String(provenance.line));
+        // Without this the projection would read a stack-derived (transformed)
+        // line back out through data-source-*, i.e. as an authored one.
+        if (provenance.method) {
+          cloneNode.setAttribute("data-source-method", provenance.method);
+        }
         if (provenance.column) {
           cloneNode.setAttribute(
             "data-source-column",
@@ -705,6 +1005,48 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         if (provenance.component) {
           cloneNode.setAttribute("data-component-name", provenance.component);
         }
+        if (provenance.ownerSourceFile) {
+          cloneNode.setAttribute(
+            "data-source-owner-file",
+            provenance.ownerSourceFile,
+          );
+          cloneNode.setAttribute(
+            "data-source-owner-line",
+            String(provenance.ownerLine),
+          );
+          if (provenance.ownerColumn) {
+            cloneNode.setAttribute(
+              "data-source-owner-column",
+              String(provenance.ownerColumn),
+            );
+          }
+          if (provenance.ownerComponentName) {
+            cloneNode.setAttribute(
+              "data-source-owner-component",
+              provenance.ownerComponentName,
+            );
+          }
+          // Same trap as data-source-method: without the owner's own tier the
+          // projection would read a stack-derived owner line as an authored one.
+          if (provenance.ownerMethod) {
+            cloneNode.setAttribute(
+              "data-source-owner-method",
+              provenance.ownerMethod,
+            );
+          }
+        }
+        // The only source-derived signal that separates `.map()` siblings,
+        // which all share one owner call site.
+        if (provenance.ownerKey) {
+          cloneNode.setAttribute("data-source-owner-key", provenance.ownerKey);
+        }
+      } else if (provenance.unavailableReason) {
+        // Absent must stay distinguishable from not-loaded-yet downstream, so
+        // record why this node has no location instead of dropping the fact.
+        cloneNode.setAttribute(
+          "data-source-unavailable",
+          provenance.unavailableReason,
+        );
       }
       nodeCount += 1;
     }
@@ -1502,19 +1844,13 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       });
     }
     // --- provenance: read explicit source-location attributes when present,
-    // then fall back to React's development-only jsxDEV Fiber stack. ---
-    var provenance:
-      | {
-          sourceFile?: string;
-          line?: number;
-          column?: number;
-          component?: string;
-        }
-      | undefined = undefined;
+    // then fall back to framework dev-runtime metadata. ---
+    var provenance: FrameworkDebugProvenance | undefined = undefined;
     var dataSourceFile = el.getAttribute("data-source-file");
     var dataSourceLine = el.getAttribute("data-source-line");
     var dataSourceColumn = el.getAttribute("data-source-column");
     var dataComponentName = el.getAttribute("data-component-name");
+    var dataSourceFramework = el.getAttribute("data-source-framework");
     var dataLoc = el.getAttribute("data-loc");
     // data-loc may encode "file:line:col" (Babel source plugin convention).
     // Only parse it when data-source-file is absent, to avoid double-reads.
@@ -1537,23 +1873,28 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         if (hasColumn) dataSourceColumn = lastPart;
       }
     }
-    if (!dataSourceFile) {
-      var reactProvenance = reactDebugProvenance(el);
-      if (reactProvenance) {
-        dataSourceFile = reactProvenance.sourceFile;
-        dataSourceLine = String(reactProvenance.line);
-        dataSourceColumn = reactProvenance.column
-          ? String(reactProvenance.column)
-          : null;
-        dataComponentName =
-          dataComponentName || reactProvenance.component || null;
-      }
+    // Always consult runtime metadata, even when a source plugin already
+    // stamped data-source-*. For React those attributes describe the element's
+    // OWN site and never the owner call site, which is the only thing that
+    // separates `.map()` siblings. The attribute tier still wins below.
+    var hadDataSourceFile = !!dataSourceFile;
+    var frameworkProvenance: FrameworkDebugProvenance =
+      frameworkDebugProvenance(el);
+    if (!hadDataSourceFile && frameworkProvenance.sourceFile) {
+      dataSourceFile = frameworkProvenance.sourceFile;
+      dataSourceLine = String(frameworkProvenance.line);
+      dataSourceColumn = frameworkProvenance.column
+        ? String(frameworkProvenance.column)
+        : null;
+      dataComponentName =
+        dataComponentName || frameworkProvenance.component || null;
     }
     if (
       dataSourceFile ||
       dataSourceLine ||
       dataSourceColumn ||
-      dataComponentName
+      dataComponentName ||
+      frameworkProvenance.unavailableReason
     ) {
       provenance = {};
       if (dataSourceFile) provenance.sourceFile = dataSourceFile;
@@ -1566,6 +1907,49 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         if (!isNaN(col)) provenance.column = col;
       }
       if (dataComponentName) provenance.component = dataComponentName;
+      // Which tier the line/column above actually came from. An attribute-borne
+      // location is authored by that transform's convention unless it says
+      // otherwise; a fiber one is only authored on the `_debugSource` tier.
+      if (dataSourceFile) {
+        var declaredMethod = el.getAttribute("data-source-method");
+        provenance.method =
+          declaredMethod === "debug-source" ||
+          declaredMethod === "debug-stack" ||
+          declaredMethod === "vue-inspector" ||
+          declaredMethod === "svelte-meta"
+            ? declaredMethod
+            : hadDataSourceFile
+              ? "data-attribute"
+              : frameworkProvenance.method || "data-attribute";
+      }
+      provenance.framework =
+        dataSourceFramework === "react" ||
+        dataSourceFramework === "vue" ||
+        dataSourceFramework === "svelte" ||
+        dataSourceFramework === "html"
+          ? dataSourceFramework
+          : hadDataSourceFile
+            ? frameworkProvenance.framework || "html"
+            : frameworkProvenance.framework;
+      if (frameworkProvenance.ownerSourceFile) {
+        provenance.ownerSourceFile = frameworkProvenance.ownerSourceFile;
+        provenance.ownerLine = frameworkProvenance.ownerLine;
+        provenance.ownerColumn = frameworkProvenance.ownerColumn;
+        provenance.ownerComponentName = frameworkProvenance.ownerComponentName;
+        // The owner's own tier: on a source-plugin element `method` is the
+        // attribute's authored position while this one is the owner stack's
+        // transformed line, so they must not share a single field.
+        provenance.ownerMethod = frameworkProvenance.ownerMethod;
+      }
+      if (frameworkProvenance.ownerKey) {
+        provenance.ownerKey = frameworkProvenance.ownerKey;
+      }
+      // Why there is no location, so the editor can say "this app exposes no
+      // debug info" instead of "still loading". Never alongside a resolved
+      // location — a plugin-stamped element on a non-React page has one.
+      if (!dataSourceFile && frameworkProvenance.unavailableReason) {
+        provenance.unavailableReason = frameworkProvenance.unavailableReason;
+      }
     }
     return {
       tagName: el.tagName.toLowerCase(),
@@ -2430,20 +2814,36 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     {
       requestId: string;
       el: Element;
-      target: { anchor: Element; placement: string; axis?: string };
-      origin: {
-        prevParent: Element;
-        prevNextSibling: Node | null;
-        // Inline position/left/top/right/bottom VALUES captured right before
-        // the optimistic reorder's stripAbsolutePositioningForFlowInsert ran
-        // (absent/undefined when that strip did not apply — e.g. an
-        // absolute-container drop, or a flow-reorder of an already-flow
-        // element with nothing to strip). Restored by the visual-structure-ack
-        // failure branch alongside the parent/sibling revert so a rejected
-        // move-node round-trip cannot leave the element stripped of its
-        // absolute positioning while stuck in the wrong parent.
-        prevInlinePositionStyles?: Record<string, string> | null;
-      } | null;
+      target: { anchor: Element; placement: string; axis?: string } | null;
+      origin:
+        | {
+            prevParent: Element;
+            prevNextSibling: Node | null;
+            // Inline position/left/top/right/bottom VALUES captured right before
+            // the optimistic reorder's stripAbsolutePositioningForFlowInsert ran
+            // (absent/undefined when that strip did not apply — e.g. an
+            // absolute-container drop, or a flow-reorder of an already-flow
+            // element with nothing to strip). Restored by the visual-structure-ack
+            // failure branch alongside the parent/sibling revert so a rejected
+            // move-node round-trip cannot leave the element stripped of its
+            // absolute positioning while stuck in the wrong parent.
+            prevInlinePositionStyles?: Record<string, string> | null;
+          }
+        // A host-driven insert has no previous position to restore: the
+        // element did not exist before this request, so a rejected/undone
+        // round-trip must REMOVE it. Restoring a prevParent it never had is
+        // what would leave an orphan node behind after Cmd+Z.
+        | { inserted: true }
+        // A host-driven delete. The DETACHED element is kept alive here so an
+        // undone deletion re-attaches the real node — with its live React
+        // state, listeners and children — instead of re-parsing a sanitized
+        // snapshot of what it used to look like.
+        | {
+            removed: true;
+            prevParent: Element;
+            prevNextSibling: Node | null;
+          }
+        | null;
     }
   > = {};
   var pendingShieldDrag: {
@@ -2677,7 +3077,12 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     );
   }
 
-  function applyHiddenSelectors(): void {
+  // Both layer states are painted here, from the one `layer-states` message,
+  // so every call site that re-runs after a runtime document swap restores
+  // hide AND lock together. Locked paints an attribute only; the hairline
+  // treatment lives in the editor chrome stylesheet so it is stripped from
+  // runtimeHeadHtmlWithoutEditorChrome and never reaches source or export.
+  function applyLayerStateSelectors(): void {
     document
       .querySelectorAll("[data-agent-native-runtime-hidden]")
       .forEach(function (el: HTMLElement) {
@@ -2704,6 +3109,18 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         });
       } catch (_err) {}
     });
+    document
+      .querySelectorAll("[data-agent-native-runtime-locked]")
+      .forEach(function (el) {
+        el.removeAttribute("data-agent-native-runtime-locked");
+      });
+    lockedSelectors.forEach(function (selector) {
+      try {
+        document.querySelectorAll(selector).forEach(function (el) {
+          el.setAttribute("data-agent-native-runtime-locked", "true");
+        });
+      } catch (_err) {}
+    });
   }
 
   function replaceRuntimeDocument(
@@ -2737,7 +3154,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
           ? selectorCandidates
           : [],
       };
-      applyHiddenSelectors();
+      applyLayerStateSelectors();
       refreshOverlays();
       return;
     }
@@ -2845,7 +3262,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
             currentMatch.remove();
           }
         }
-        applyHiddenSelectors();
+        applyLayerStateSelectors();
         selectedEl = null;
         if (nextMatch) {
           try {
@@ -2883,7 +3300,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     persistentNodes.forEach(function (node) {
       document.body.appendChild(node);
     });
-    applyHiddenSelectors();
+    applyLayerStateSelectors();
 
     selectedEl = null;
     clearHoverGate();
@@ -5283,6 +5700,18 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         if (match && !isLayerInteractionBlocked(match)) return match;
       } catch (_err) {}
     }
+    // Last resort: React re-creating a node drops its imperatively stamped
+    // "runtime-" id, and on a client-rendered screen that id is the host's ONLY
+    // identity for the element — so the miss dropped the whole edit while we
+    // still held the selection. ensureRuntimeLayerNodeId is deterministic over
+    // screen + provenance + structural path, so re-stamping restores the SAME id
+    // for the intended element and a different one for anything else.
+    if (selectedEl && document.documentElement.contains(selectedEl)) {
+      try {
+        ensureRuntimeLayerNodeId(selectedEl);
+        if (matchesExactSelectorList(selectedEl, candidates)) return selectedEl;
+      } catch (_err) {}
+    }
     return null;
   }
 
@@ -5464,8 +5893,30 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
   // is only safe when it identifies exactly one live element. Prefer the
   // runtime projection's stable source id and fall back to the selector only
   // when that id has no match at all.
-  function findUniqueRuntimeStructureTarget(selector, sourceId) {
+  function findUniqueRuntimeStructureTarget(selector, sourceId, pendingId?) {
     var matches = new Set<Element>();
+    // Pending ids are deliberately NOT part of the stable-id list below: they
+    // are minted per hit-test and only ever stamped on the live DOM, so they
+    // must not participate in stored-id resolution. They are still the only
+    // handle a cross-screen drop has on an id-less live anchor.
+    if (typeof pendingId === "string" && pendingId) {
+      try {
+        var pendingMatches = document.querySelectorAll(
+          '[data-an-pending-node-id="' + escapeAttribute(pendingId) + '"]',
+        );
+        if (pendingMatches.length === 1) {
+          var pendingMatch = pendingMatches[0];
+          if (
+            pendingMatch !== document.body &&
+            pendingMatch !== document.documentElement &&
+            !isOverlayElement(pendingMatch) &&
+            !isLayerInteractionBlocked(pendingMatch)
+          ) {
+            return pendingMatch;
+          }
+        }
+      } catch (_err) {}
+    }
     if (typeof sourceId === "string" && sourceId) {
       var attributes = [
         "data-agent-native-node-id",
@@ -5513,7 +5964,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     }
   }
 
-  function removeRuntimeTarget(selector, selectorCandidates) {
+  function removeRuntimeTarget(selector, selectorCandidates, requestId?) {
     var target = findRuntimeTarget(selector, selectorCandidates);
     if (
       !target ||
@@ -5521,6 +5972,23 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       target === document.documentElement
     )
       return false;
+    // A requestId means the host queued this deletion as a pending live edit
+    // and may undo it. Register it in the same pending-move table the drag
+    // path uses so the existing visual-structure-ack channel can put the node
+    // back; without it the ack arrives for an unknown id and Cmd+Z silently
+    // does nothing.
+    if (typeof requestId === "string" && requestId && target.parentElement) {
+      pendingStructureMoves[requestId] = {
+        requestId: requestId,
+        el: target,
+        target: null,
+        origin: {
+          removed: true,
+          prevParent: target.parentElement,
+          prevNextSibling: target.nextSibling,
+        },
+      };
+    }
     if (target.parentElement) target.parentElement.removeChild(target);
     // T23: the removed subtree may contain the active text-edit element —
     // its blur/keydown listeners are gone with it, so exit the session
@@ -8165,7 +8633,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     correctAbsoluteMemberClientPosition(el, desiredDropPoint);
   }
 
-  function postVisualStructureChange(el, target, origin) {
+  function postVisualStructureChange(el, target, origin, insertedHtml?) {
     if (!el || !target || !target.anchor) return;
     dndLog("post:structure-change", {
       el: getSelector(el),
@@ -8192,6 +8660,11 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         placement: target.placement,
         dropMode: target.dropMode || "flow-insert",
         forceFlowPositionOverride: Boolean(target.forceFlowPositionOverride),
+        // Present only when this node did not exist in the running app before
+        // the change. The host must NOT tell the coding agent to relocate an
+        // element the source file has never contained.
+        insertedHtml:
+          typeof insertedHtml === "string" ? insertedHtml : undefined,
         sourceRect: rectInfoForElement(el),
         anchorRect: rectInfoForElement(target.anchor),
         payload: getElementInfo(el),
@@ -11886,7 +12359,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         clearHoverGate();
         highlightOverlay.style.display = "none";
       }
-      applyHiddenSelectors();
+      applyLayerStateSelectors();
       return;
     }
     if (e.data.type === "runtime-structure-move") {
@@ -11949,6 +12422,147 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       postVisualStructureChange(runtimeSubject, runtimeTarget, runtimeOrigin);
       return;
     }
+    if (e.data.type === "runtime-structure-insert") {
+      var insertRequestId = e.data.requestId;
+      // An insert that silently returns loses the whole gesture with nothing
+      // on screen and nothing in the pending list — strictly worse than a
+      // no-op move, which at least leaves the element where it was. Always
+      // answer the host so it can surface the failure.
+      var rejectInsert = function (reason: string): void {
+        (window.parent as Window).postMessage(
+          {
+            type: "runtime-structure-insert-rejected",
+            screenId: designCanvasScreenId,
+            requestId: insertRequestId,
+            reason: reason,
+          },
+          "*",
+        );
+      };
+      if (readOnly) {
+        rejectInsert("read-only");
+        return;
+      }
+      var insertPlacement = String(e.data.placement || "");
+      if (
+        insertPlacement !== "before" &&
+        insertPlacement !== "after" &&
+        insertPlacement !== "inside"
+      ) {
+        rejectInsert("placement");
+        return;
+      }
+      var insertAnchor = findUniqueRuntimeStructureTarget(
+        String(e.data.anchorSelector || ""),
+        typeof e.data.anchorSourceId === "string" ? e.data.anchorSourceId : "",
+        typeof e.data.anchorPendingNodeId === "string"
+          ? e.data.anchorPendingNodeId
+          : "",
+      );
+      if (!insertAnchor) {
+        rejectInsert("anchor-unresolved");
+        return;
+      }
+      if (
+        (insertPlacement === "inside" &&
+          !isContainerDropTarget(insertAnchor)) ||
+        (insertPlacement !== "inside" && !insertAnchor.parentElement)
+      ) {
+        rejectInsert("placement-unavailable");
+        return;
+      }
+      var parsedInsertEl = parseNodeHtmlPreviewElement(
+        typeof e.data.html === "string" ? e.data.html : "",
+      );
+      if (
+        !parsedInsertEl ||
+        parsedInsertEl === document.body ||
+        parsedInsertEl.tagName === "BODY"
+      ) {
+        rejectInsert("html");
+        return;
+      }
+      var insertNodeId = parsedInsertEl.getAttribute(
+        "data-agent-native-node-id",
+      );
+      // Repeat drops of the same board primitive must not mint a second live
+      // element carrying the same node id: findUniqueRuntimeStructureTarget
+      // returns null on a duplicate id, which silently breaks every later
+      // move, ack, and undo for BOTH copies. Re-drag the existing node instead.
+      var existingInsertEl: Element | null = null;
+      if (insertNodeId) {
+        try {
+          existingInsertEl = document.querySelector(
+            '[data-agent-native-node-id="' +
+              escapeAttribute(insertNodeId) +
+              '"]',
+          );
+        } catch (_err) {}
+      }
+      if (existingInsertEl === insertAnchor) {
+        rejectInsert("anchor-is-subject");
+        return;
+      }
+      var insertTarget = {
+        anchor: insertAnchor,
+        placement: insertPlacement,
+        axis: parentFlowAxis(
+          insertPlacement === "inside"
+            ? insertAnchor
+            : insertAnchor.parentElement!,
+        ),
+        dropMode:
+          insertPlacement === "inside" &&
+          isAbsolutePrimitiveContainer(insertAnchor)
+            ? "absolute-container"
+            : "flow-insert",
+      };
+      if (existingInsertEl) {
+        if (existingInsertEl.contains(insertAnchor)) {
+          rejectInsert("anchor-inside-subject");
+          return;
+        }
+        var reinsertOrigin = {
+          prevParent: existingInsertEl.parentElement!,
+          prevNextSibling: existingInsertEl.nextSibling,
+          prevInlinePositionStyles:
+            snapshotInlinePositionStyles(existingInsertEl),
+        };
+        applyRuntimeReorder(existingInsertEl, insertTarget);
+        selectedEl = existingInsertEl;
+        positionOverlay(selectionOverlay, selectedEl);
+        refreshOverlays();
+        postVisualStructureChange(
+          existingInsertEl,
+          insertTarget,
+          reinsertOrigin,
+        );
+        return;
+      }
+      // The host bakes flow/absolute positioning into the markup before it
+      // gets here (it owns the drop point and the anchor rect), so the node
+      // goes in verbatim — no reorder rebasing on a never-laid-out element.
+      if (insertPlacement === "inside") {
+        insertAnchor.appendChild(parsedInsertEl);
+      } else {
+        insertAnchor.parentElement!.insertBefore(
+          parsedInsertEl,
+          insertPlacement === "before"
+            ? insertAnchor
+            : insertAnchor.nextSibling,
+        );
+      }
+      selectedEl = parsedInsertEl;
+      positionOverlay(selectionOverlay, selectedEl);
+      refreshOverlays();
+      postVisualStructureChange(
+        parsedInsertEl,
+        insertTarget,
+        { inserted: true },
+        parsedInsertEl.outerHTML,
+      );
+      return;
+    }
     if (e.data.type === "visual-structure-ack") {
       dndLog("ack", {
         requestId: e.data.requestId,
@@ -11957,8 +12571,40 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       var move = pendingStructureMoves[e.data.requestId];
       if (!move) return;
       delete pendingStructureMoves[e.data.requestId];
+      var moveWasInsert = Boolean(move.origin && "inserted" in move.origin);
+      var moveWasRemoval = Boolean(move.origin && "removed" in move.origin);
+      if (moveWasRemoval) {
+        // applied === true means the source now deletes it too, so the node
+        // stays gone and this entry is simply released. applied === false is
+        // the undo: re-attach the very element that was removed.
+        if (!e.data.applied && move.origin && "removed" in move.origin) {
+          var removedParent = move.origin.prevParent;
+          var removedNextSibling = move.origin.prevNextSibling;
+          if (
+            removedParent &&
+            removedParent.isConnected &&
+            !move.el.isConnected
+          ) {
+            removedParent.insertBefore(
+              move.el,
+              removedNextSibling &&
+                removedNextSibling.parentNode === removedParent
+                ? removedNextSibling
+                : null,
+            );
+            selectedEl = move.el;
+            positionOverlay(selectionOverlay, selectedEl);
+            postElementSelect(selectedEl);
+          }
+        }
+        refreshOverlays();
+        return;
+      }
       if (e.data.applied) {
-        if (move.el && move.el.isConnected) {
+        // An inserted node is already exactly where the host asked for it and
+        // has no pre-insert geometry to rebase; replaying the reorder would
+        // re-run the absolute/flow correction against its own current rect.
+        if (!moveWasInsert && move.el && move.el.isConnected && move.target) {
           applyRuntimeReorder(move.el, move.target);
           selectedEl = move.el;
           positionOverlay(selectionOverlay, selectedEl);
@@ -11974,10 +12620,18 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         // stripped of its absolute positioning — worse than doing nothing,
         // since it now renders at the flow position of a detached style
         // instead of either its original spot or the intended drop slot.
+        if (moveWasInsert) {
+          if (move.el && move.el.isConnected) move.el.remove();
+          if (selectedEl === move.el) selectedEl = null;
+          if (hoveredEl === move.el) hoveredEl = null;
+          refreshOverlays();
+          return;
+        }
         if (
           move.el &&
           move.el.isConnected &&
           move.origin &&
+          "prevParent" in move.origin &&
           move.origin.prevParent &&
           move.origin.prevParent.isConnected
         ) {
@@ -12018,7 +12672,11 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
       return;
     }
     if (e.data.type === "delete-element") {
-      removeRuntimeTarget(e.data.selector, e.data.selectorCandidates);
+      removeRuntimeTarget(
+        e.data.selector,
+        e.data.selectorCandidates,
+        e.data.requestId,
+      );
       return;
     }
     if (e.data.type === "set-text-content") {