@agent-native/core 0.129.1 → 0.130.0

package/corpus/templates/design/app/pages/design-editor/pending-edits.ts

@@ -15,6 +15,7 @@ import {
   utilityStem,
 } from "@shared/responsive-classes";
 import {
+  type ElementProvenanceUnavailableReason,
   normalizeDesignSourceType,
   type DesignSourceType,
 } from "@shared/source-mode";
@@ -23,6 +24,7 @@ import type { ElementInfo } from "@/components/design/types";
 
 import {
   buildReactSemanticHandoff,
+  buildRuntimeReactLayerStateHandoff,
   redactReactSourceAnchor,
   type ReactSourceAnchor,
   type ReactSourceScope,
@@ -35,6 +37,19 @@ export interface PendingVisualStyleEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  /**
+   * The selector/node id the canvas bridge reported, kept when the host
+   * canonicalized the selection onto its source projection
+   * (canonicalElementInfoForCodeLayerNode). A localhost screen runs two
+   * disjoint node-id namespaces: the injected bridge stamps `runtime-…` ids on
+   * the live document, while the host stamps `an-…` ids on the source html it
+   * fetched separately. Only this pair addresses the running app, so every
+   * replay into the live frame must prefer it. Absent for inline/snapshot
+   * screens, where the bridge reuses the ids already in the document and the
+   * two pairs are the same value.
+   */
+  runtimeSelector?: string | null;
+  runtimeSourceId?: string | null;
   sourceAnchor?: ReactSourceAnchor;
   tagName?: string | null;
   classes: string[];
@@ -72,7 +87,7 @@ export interface PendingVisualStyleEdit {
   };
 }
 
-function pendingLiveTextEditKey(edit: PendingLiveTextEdit): string {
+function pendingLiveEditSubjectKey(edit: PendingLiveNonStyleEdit): string {
   return `${edit.screenId}:${edit.sourceId?.trim() || edit.selector.trim()}`;
 }
 
@@ -82,14 +97,56 @@ export function mergePendingLiveNonStyleEdits(
   const merged: PendingLiveNonStyleEdit[] = [];
   for (const edit of edits) {
     if (edit.kind === "structure") {
+      // Deleting a node this session INSERTED nets to zero in source: the
+      // markup was never written there. Queuing both would hand the coding
+      // agent markup to add plus a node to delete, and an apply that runs the
+      // insert can resurrect exactly what the user deleted. Both entries stay
+      // on the undo stack, so undoing the delete re-queues the insertion.
+      const supersededInsertIndex = edit.removed
+        ? merged.findIndex(
+            (candidate) =>
+              candidate.kind === "structure" &&
+              Boolean(candidate.insertedHtml) &&
+              pendingLiveEditSubjectKey(candidate) ===
+                pendingLiveEditSubjectKey(edit),
+          )
+        : -1;
+      if (supersededInsertIndex !== -1) {
+        merged.splice(supersededInsertIndex, 1);
+        continue;
+      }
       merged.push(edit);
       continue;
     }
-    const nextKey = pendingLiveTextEditKey(edit);
+    if (edit.kind === "layer-state") {
+      const nextKey = `${pendingLiveEditSubjectKey(edit)}:${edit.state}`;
+      const index = merged.findIndex(
+        (candidate) =>
+          candidate.kind === "layer-state" &&
+          `${pendingLiveEditSubjectKey(candidate)}:${candidate.state}` ===
+            nextKey,
+      );
+      if (index === -1) {
+        merged.push(edit);
+        continue;
+      }
+      const previous = merged[index] as PendingLiveLayerStateEdit;
+      if (previous.originalEnabled === edit.enabled) {
+        merged.splice(index, 1);
+        continue;
+      }
+      merged[index] = {
+        ...previous,
+        ...edit,
+        originalEnabled: previous.originalEnabled,
+      };
+      continue;
+    }
+    const nextKey = pendingLiveEditSubjectKey(edit);
     const index = merged.findIndex(
       (candidate) =>
         candidate.kind === "text" &&
-        pendingLiveTextEditKey(candidate) === nextKey,
+        pendingLiveEditSubjectKey(candidate) === nextKey,
     );
     if (index === -1) {
       merged.push(edit);
@@ -113,7 +170,7 @@ export function pendingLiveTextUndoRevertValue(
   const currentForTarget = currentEdits.find(
     (edit): edit is PendingLiveTextEdit =>
       edit.kind === "text" &&
-      pendingLiveTextEditKey(edit) === pendingLiveTextEditKey(nextEdit),
+      pendingLiveEditSubjectKey(edit) === pendingLiveEditSubjectKey(nextEdit),
   );
   return currentForTarget
     ? { value: currentForTarget.value, html: currentForTarget.html }
@@ -137,6 +194,46 @@ export interface PendingLiveTextEdit {
   updatedAt: number;
 }
 
+export interface PendingLiveLayerStateEdit {
+  kind: "layer-state";
+  screenId: string;
+  filename: string;
+  screenName: string;
+  layerId: string;
+  selector: string;
+  sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
+  tagName?: string | null;
+  classes: string[];
+  state: "hidden" | "locked";
+  enabled: boolean;
+  originalEnabled: boolean;
+  updatedAt: number;
+}
+
+export function pendingLiveLayerStateUndoRevertValue(
+  currentEdits: readonly PendingLiveNonStyleEdit[],
+  nextEdit: PendingLiveLayerStateEdit,
+): boolean {
+  const currentForTarget = currentEdits.find(
+    (edit): edit is PendingLiveLayerStateEdit =>
+      edit.kind === "layer-state" &&
+      edit.state === nextEdit.state &&
+      pendingLiveEditSubjectKey(edit) === pendingLiveEditSubjectKey(nextEdit),
+  );
+  return currentForTarget?.enabled ?? nextEdit.originalEnabled;
+}
+
+export function shouldRedoPendingLiveNonStyleBeforeStyle(
+  styleEntry: { edit: { updatedAt: number } } | undefined,
+  nonStyleEntry: { edit: { updatedAt: number } } | undefined,
+): boolean {
+  return Boolean(
+    nonStyleEntry &&
+    (!styleEntry || nonStyleEntry.edit.updatedAt < styleEntry.edit.updatedAt),
+  );
+}
+
 export interface PendingLiveStructureEdit {
   kind: "structure";
   screenId: string;
@@ -148,6 +245,13 @@ export interface PendingLiveStructureEdit {
   anchorSelector: string;
   anchorSourceId?: string | null;
   anchorSourceAnchor?: ReactSourceAnchor;
+  /**
+   * Project-relative route module reported by the localhost manifest. A
+   * top-level canvas insert targets the live document body, which intentionally
+   * has no framework element provenance; this keeps Apply bounded to the route
+   * source without inventing a fake body line/column.
+   */
+  routeSourceFile?: string;
   placement: "before" | "after" | "inside";
   /** Runtime layout semantics captured at drop time. These are required for
    * the coding agent to distinguish a flow/auto-layout insertion from an
@@ -156,6 +260,20 @@ export interface PendingLiveStructureEdit {
   forceFlowPositionOverride?: boolean;
   sourceRect?: { x: number; y: number; width: number; height: number };
   anchorRect?: { x: number; y: number; width: number; height: number };
+  /**
+   * Markup this edit ADDED to the running app. Present only for a drop whose
+   * subject had no counterpart in the screen's source, so the coding agent
+   * must insert this markup rather than relocate an existing element.
+   */
+  insertedHtml?: string;
+  /**
+   * This edit DELETED the subject from the running app. A removal has no
+   * anchor — `anchorSelector`/`placement` carry no meaning for it — so every
+   * consumer that pairs a subject with a target (the semantic handoff, the
+   * source-path collection before apply, runtime verification) must branch on
+   * this instead of reading anchor fields that were never captured.
+   */
+  removed?: true;
   requestId?: string;
   updatedAt: number;
 }
@@ -258,6 +376,18 @@ function sourcePathRelativeToRoot(args: {
   return normalizeResolvablePath(relative)?.value;
 }
 
+export function projectRelativeSourcePath(args: {
+  sourceFile?: string;
+  rootPath?: string;
+}): string | undefined {
+  const sourceFile = args.sourceFile?.trim();
+  if (!sourceFile) return undefined;
+  return sourcePathRelativeToRoot({
+    sourceFile,
+    rootPath: args.rootPath,
+  });
+}
+
 export function reactSourceAnchorForPendingEdit(args: {
   info?: Pick<ElementInfo, "provenance" | "sourceId" | "selector"> | null;
   id?: string;
@@ -278,6 +408,13 @@ export function reactSourceAnchorForPendingEdit(args: {
     sourceFile,
     rootPath: args.rootPath,
   });
+  const ownerSourceFile = provenance.ownerSourceFile?.trim();
+  const ownerRelPath = ownerSourceFile
+    ? sourcePathRelativeToRoot({
+        sourceFile: ownerSourceFile,
+        rootPath: args.rootPath,
+      })
+    : undefined;
   return {
     id:
       args.id?.trim() ||
@@ -291,7 +428,26 @@ export function reactSourceAnchorForPendingEdit(args: {
     ...(relPath ? { relPath } : {}),
     line: provenance.line,
     column: provenance.column,
+    // Which tier produced line/column, so no consumer can read a React 19
+    // owner-stack (transformed) position as the authored JSX line.
+    ...(provenance.method ? { method: provenance.method } : {}),
     component: provenance.component,
+    // The nearest component's INSTANTIATION site — the `.map()` call site for a
+    // mapped instance. Dropping it here is what left the handoff unable to say
+    // where a mapped sibling actually comes from.
+    ...(ownerSourceFile ? { ownerSourceFile } : {}),
+    ...(ownerRelPath ? { ownerRelPath } : {}),
+    ...(provenance.ownerLine ? { ownerLine: provenance.ownerLine } : {}),
+    ...(provenance.ownerColumn ? { ownerColumn: provenance.ownerColumn } : {}),
+    ...(provenance.ownerComponentName
+      ? { ownerComponent: provenance.ownerComponentName }
+      : {}),
+    // The owner's own tier: a data-attribute element can still owe its owner
+    // line to a transformed owner stack.
+    ...(provenance.ownerMethod ? { ownerMethod: provenance.ownerMethod } : {}),
+    // Every `.map()` sibling shares one call site, so runtimeMultiplicity alone
+    // cannot say WHICH instance was selected; the React key can.
+    ...(provenance.ownerKey ? { ownerKey: provenance.ownerKey } : {}),
     runtimeMultiplicity,
     ...(args.reason?.trim() ? { reason: args.reason.trim() } : {}),
     scope:
@@ -299,8 +455,26 @@ export function reactSourceAnchorForPendingEdit(args: {
   };
 }
 
+/**
+ * Why an anchor could not be built: a runtime that reports it exposes no
+ * source locations at all is a permanent answer, not a slow one. Returns
+ * undefined when nothing has reported a reason yet — that case is still
+ * "loading", and callers must not present it as unsupported.
+ */
+export function reactSourceAnchorUnavailableReason(
+  infos: ReadonlyArray<Pick<ElementInfo, "provenance"> | null | undefined>,
+): ElementProvenanceUnavailableReason | undefined {
+  for (const info of infos) {
+    const provenance = info?.provenance;
+    if (provenance?.sourceFile) continue;
+    if (provenance?.unavailableReason) return provenance.unavailableReason;
+  }
+  return undefined;
+}
+
 export type PendingLiveNonStyleEdit =
   | PendingLiveTextEdit
+  | PendingLiveLayerStateEdit
   | PendingLiveStructureEdit;
 export type PendingVisualStyleUndoEntry = {
   edit: PendingVisualStyleEdit;
@@ -316,10 +490,59 @@ export type PendingLiveStructureUndoEntry = {
   kind: "structure";
   edit: PendingLiveStructureEdit;
 };
+export type PendingLiveLayerStateUndoEntry = {
+  kind: "layer-state";
+  edit: PendingLiveLayerStateEdit;
+  revertEnabled: boolean;
+};
 export type PendingLiveNonStyleUndoEntry =
   | PendingLiveTextUndoEntry
+  | PendingLiveLayerStateUndoEntry
   | PendingLiveStructureUndoEntry;
 
+/**
+ * Project-relative source files that must be read before this edit can be
+ * handed off. A removal has no anchor, and an INSERT has no subject — its
+ * markup exists in no source file yet — so demanding both paths rejected every
+ * insert as "anchors still loading". `null` means a path this edit does need
+ * has not resolved yet, which is the only honest "not ready" answer.
+ */
+export function pendingStructureEditSourcePaths(
+  edit: PendingLiveStructureEdit,
+): string[] | null {
+  const required = [
+    ...(edit.insertedHtml ? [] : [edit.sourceAnchor?.relPath]),
+    ...(edit.removed
+      ? []
+      : [
+          edit.anchorSourceAnchor?.relPath ??
+            (edit.insertedHtml ? edit.routeSourceFile : undefined),
+        ]),
+  ];
+  if (required.some((path) => !path)) return null;
+  return required as string[];
+}
+
+export type PendingStructureRedoCommand =
+  | { kind: "delete" }
+  | { kind: "insert"; html: string }
+  | { kind: "move" };
+
+/**
+ * Which runtime command replays this edit. Undoing an insert REMOVED the node,
+ * so replaying it as a move would address an element that is no longer in the
+ * document and the bridge would return silently — a redo that reports success
+ * and does nothing.
+ */
+export function pendingStructureRedoCommand(
+  edit: PendingLiveStructureEdit,
+): PendingStructureRedoCommand {
+  if (edit.removed) return { kind: "delete" };
+  return edit.insertedHtml
+    ? { kind: "insert", html: edit.insertedHtml }
+    : { kind: "move" };
+}
+
 export function pendingLiveStructureEditsMatch(
   left: PendingLiveStructureEdit,
   right: PendingLiveStructureEdit,
@@ -331,6 +554,7 @@ export function pendingLiveStructureEditsMatch(
     left.anchorSelector === right.anchorSelector &&
     (left.anchorSourceId ?? "") === (right.anchorSourceId ?? "") &&
     left.placement === right.placement &&
+    Boolean(left.removed) === Boolean(right.removed) &&
     left.dropMode === right.dropMode &&
     Boolean(left.forceFlowPositionOverride) ===
       Boolean(right.forceFlowPositionOverride)
@@ -427,20 +651,27 @@ export function originalStylesForPendingVisualEdit(
   );
 }
 
+export type PendingVisualStyleRevertPatch = PendingVisualStyleRuntimePatch & {
+  interactionState?: InteractionState;
+};
+
 export function buildPendingVisualStyleRevertPatches(
   edits: readonly PendingVisualStyleEdit[],
-): Array<{
-  screenId: string;
-  selector: string;
-  sourceId?: string | null;
-  styles: Record<string, string>;
-  interactionState?: InteractionState;
-}> {
+): PendingVisualStyleRevertPatch[] {
   return edits
     .map((edit) => ({
       screenId: edit.screenId,
       selector: edit.selector,
       sourceId: edit.sourceId,
+      // Carried, not resolved: consumers replay into the live frame (prefer the
+      // runtime pair) and into the source projection (prefer the canonical
+      // one), so the patch has to keep both.
+      ...(edit.runtimeSelector
+        ? { runtimeSelector: edit.runtimeSelector }
+        : {}),
+      ...(edit.runtimeSourceId
+        ? { runtimeSourceId: edit.runtimeSourceId }
+        : {}),
       styles: edit.originalStyles,
       ...(edit.interactionState
         ? { interactionState: edit.interactionState }
@@ -449,13 +680,101 @@ export function buildPendingVisualStyleRevertPatches(
     .filter((patch) => Object.keys(patch.styles).length > 0);
 }
 
-export function getPendingVisualStylePropertyCount(
+export type PendingVisualStyleRuntimePatch = {
+  screenId: string;
+  selector: string;
+  sourceId?: string | null;
+  runtimeSelector?: string | null;
+  runtimeSourceId?: string | null;
+  styles: Record<string, string>;
+};
+
+function nodeIdSelector(nodeId: string): string {
+  return `[data-agent-native-node-id="${nodeId
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')}"]`;
+}
+
+/**
+ * How a pending edit addresses the RUNNING document. The runtime pair wins
+ * because a localhost screen's canonical selector/sourceId name nodes in the
+ * host's source projection, which the live frame has never seen. Candidates
+ * stay a runtime-first superset so nothing that used to resolve stops
+ * resolving, and an inline screen — which records no runtime pair — produces
+ * byte-identical output to the canonical-only list.
+ */
+export function runtimeStyleTarget(target: {
+  selector: string;
+  sourceId?: string | null;
+  runtimeSelector?: string | null;
+  runtimeSourceId?: string | null;
+}): { selector: string; nodeId: string | null; selectorCandidates: string[] } {
+  const selector = target.runtimeSelector?.trim() || target.selector;
+  const nodeId = target.runtimeSourceId?.trim() || target.sourceId || null;
+  return {
+    selector,
+    nodeId,
+    selectorCandidates: [
+      ...new Set(
+        [
+          selector,
+          target.selector,
+          nodeId ? nodeIdSelector(nodeId) : "",
+          target.sourceId ? nodeIdSelector(target.sourceId) : "",
+        ].filter(Boolean),
+      ),
+    ],
+  };
+}
+
+export type SendPendingVisualStyleRuntimeProperty = (
+  screenId: string,
+  selector: string,
+  property: string,
+  value: string,
+  options: {
+    selectorCandidates: string[];
+    nodeId?: string | null;
+  },
+) => boolean;
+
+/**
+ * Forward, undo, and redo all use this exact per-property runtime channel.
+ * The screen id is part of the command boundary so a retained/remounted
+ * overview iframe cannot accidentally receive history intended for another
+ * screen.
+ */
+export function replayPendingVisualStyleRuntimePatch(
+  patch: PendingVisualStyleRuntimePatch,
+  sendProperty: SendPendingVisualStyleRuntimeProperty,
+): boolean {
+  const entries = Object.entries(patch.styles);
+  if (entries.length === 0) return false;
+  const target = runtimeStyleTarget(patch);
+  // No candidate at all is not "apply it to the obvious element": the bridge
+  // falls back to its own current selection when the candidate list is empty,
+  // so an unaddressable revert would silently restyle whatever happens to be
+  // selected. Report failure and let the caller surface it.
+  if (target.selectorCandidates.length === 0) return false;
+  return entries.every(([property, value]) =>
+    sendProperty(patch.screenId, target.selector, property, value, {
+      selectorCandidates: target.selectorCandidates,
+      nodeId: target.nodeId,
+    }),
+  );
+}
+
+/**
+ * Badge number on the Apply bar: how many user-meaningful updates Apply would
+ * hand to the agent. A style edit is already coalesced by screen, target, and
+ * interaction state, so counting its individual CSS declarations inflates one
+ * inspector gesture into several apparent updates.
+ */
+export function getPendingVisualEditCount(
   edits: readonly PendingVisualStyleEdit[],
+  liveEdits: readonly PendingLiveNonStyleEdit[] = [],
 ): number {
-  return edits.reduce(
-    (count, edit) => count + Object.keys(edit.styles).length,
-    0,
-  );
+  return edits.length + liveEdits.length;
 }
 
 export function shouldBlockPendingVisualStyleNavigation(args: {
@@ -469,6 +788,22 @@ export function shouldBlockPendingVisualStyleNavigation(args: {
   );
 }
 
+/**
+ * Inserted markup is the only unbounded field in the pending-edit payload, and
+ * that payload is JSON.stringified straight into an agent prompt. Truncation is
+ * reported so the agent never mistakes a cut-off tree for the whole node.
+ */
+const MAX_INSERTED_HTML_LENGTH = 4_000;
+
+function boundedInsertedHtml(html: string): {
+  value: string;
+  truncated: boolean;
+} {
+  return html.length > MAX_INSERTED_HTML_LENGTH
+    ? { value: html.slice(0, MAX_INSERTED_HTML_LENGTH), truncated: true }
+    : { value: html, truncated: false };
+}
+
 export function formatPendingVisualStylePrompt(args: {
   designId?: string | null;
   designTitle?: string | null;
@@ -528,34 +863,59 @@ export function formatPendingVisualStylePrompt(args: {
         html: edit.html,
       };
     }
+    if (edit.kind === "layer-state") {
+      const semanticHandoff = edit.sourceAnchor
+        ? buildRuntimeReactLayerStateHandoff({
+            subjectAnchor: edit.sourceAnchor,
+            screenId: edit.screenId,
+            state: edit.state,
+            enabled: edit.enabled,
+          })
+        : null;
+      return {
+        kind: edit.kind,
+        screenId: edit.screenId,
+        filename: edit.filename,
+        screenName: edit.screenName,
+        selector: edit.selector,
+        sourceId: edit.sourceId ?? null,
+        sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
+        tagName: edit.tagName ?? null,
+        classes: edit.classes,
+        state: edit.state,
+        enabled: edit.enabled,
+        attributeName: `data-agent-native-${edit.state}`,
+        ...(semanticHandoff?.ok
+          ? { semanticHandoff: semanticHandoff.handoff }
+          : {}),
+      };
+    }
     const subjectAnchor = edit.sourceAnchor
       ? { ...edit.sourceAnchor, id: "subject" }
       : undefined;
     const targetAnchor = edit.anchorSourceAnchor
       ? { ...edit.anchorSourceAnchor, id: "target" }
       : undefined;
-    const semanticHandoff =
-      subjectAnchor && targetAnchor
+    // An insert's subject is markup that does not exist in the program yet, so
+    // it has no source anchor and cannot be described as a move. Telling the
+    // agent to relocate an element the file has never contained is worse than
+    // reporting nothing.
+    const insertedHtml = edit.insertedHtml
+      ? boundedInsertedHtml(edit.insertedHtml)
+      : undefined;
+    const semanticHandoff = edit.removed
+      ? subjectAnchor
         ? buildReactSemanticHandoff({
-            operation: edit.placement === "inside" ? "reparent" : "move",
-            desiredChange: [
-              `Move the selected runtime element ${edit.placement} the target runtime element.`,
-              edit.dropMode === "flow-insert"
-                ? `The drop is a flow/auto-layout insertion${edit.forceFlowPositionOverride ? "; remove authored absolute positioning so the moved element participates in the target container's layout" : "; preserve normal flow participation"}.`
-                : edit.dropMode === "absolute-container"
-                  ? "The target is an absolute-positioning container; preserve absolute positioning and rebase the moved element's visual offset from sourceRect into the target anchorRect coordinate space."
-                  : "Preserve the runtime layout behavior observed in the preview.",
-            ].join(" "),
-            sourceAnchors: [subjectAnchor, targetAnchor],
+            operation: "remove",
+            desiredChange:
+              "Delete the selected runtime element from the source that renders it. The live preview already shows it gone; remove its markup (and anything that exists only to render it) without disturbing sibling layout or behavior.",
+            sourceAnchors: [subjectAnchor],
             runtimeRelationship: {
-              kind: edit.placement,
+              kind: "remove",
               subjectAnchorIds: ["subject"],
-              targetAnchorId: "target",
               screenId: edit.screenId,
-              description: `${edit.selector} ${edit.placement} ${edit.anchorSelector}`,
+              description: `remove ${edit.selector}`,
             },
-            // The packet intentionally starts without a hash: its execution
-            // contract requires read-local-file before every write.
             versionHashes: [],
           })
         : {
@@ -563,9 +923,71 @@ export function formatPendingVisualStylePrompt(args: {
             rejection: {
               code: "missing-source-provenance" as const,
               reason:
-                "Exact subject and target source anchors were not both available for this React structure edit.",
+                "The removed element's source anchor was not available for this runtime deletion.",
             },
-          };
+          }
+      : insertedHtml
+        ? targetAnchor
+          ? buildReactSemanticHandoff({
+              operation: "insert",
+              desiredChange: [
+                `Add the new markup in insertedHtml ${edit.placement} the target runtime element.`,
+                insertedHtml.truncated
+                  ? "The markup below was truncated for prompt size; read the running preview or ask before writing it verbatim."
+                  : "The markup is already positioned for the drop point.",
+                edit.dropMode === "absolute-container"
+                  ? "The target is an absolute-positioning container; keep the inline left/top offsets."
+                  : "This is a flow/auto-layout insertion; the markup carries no absolute positioning.",
+              ].join(" "),
+              sourceAnchors: [targetAnchor],
+              runtimeRelationship: {
+                kind: edit.placement,
+                subjectAnchorIds: [],
+                targetAnchorId: "target",
+                screenId: edit.screenId,
+                description: `insert ${edit.selector} ${edit.placement} ${edit.anchorSelector}`,
+              },
+              versionHashes: [],
+            })
+          : {
+              ok: false as const,
+              rejection: {
+                code: "missing-source-provenance" as const,
+                reason:
+                  "The insertion target's source anchor was not available for this runtime insert.",
+              },
+            }
+        : subjectAnchor && targetAnchor
+          ? buildReactSemanticHandoff({
+              operation: edit.placement === "inside" ? "reparent" : "move",
+              desiredChange: [
+                `Move the selected runtime element ${edit.placement} the target runtime element.`,
+                edit.dropMode === "flow-insert"
+                  ? `The drop is a flow/auto-layout insertion${edit.forceFlowPositionOverride ? "; remove authored absolute positioning so the moved element participates in the target container's layout" : "; preserve normal flow participation"}.`
+                  : edit.dropMode === "absolute-container"
+                    ? "The target is an absolute-positioning container; preserve absolute positioning and rebase the moved element's visual offset from sourceRect into the target anchorRect coordinate space."
+                    : "Preserve the runtime layout behavior observed in the preview.",
+              ].join(" "),
+              sourceAnchors: [subjectAnchor, targetAnchor],
+              runtimeRelationship: {
+                kind: edit.placement,
+                subjectAnchorIds: ["subject"],
+                targetAnchorId: "target",
+                screenId: edit.screenId,
+                description: `${edit.selector} ${edit.placement} ${edit.anchorSelector}`,
+              },
+              // The packet intentionally starts without a hash: its execution
+              // contract requires read-local-file before every write.
+              versionHashes: [],
+            })
+          : {
+              ok: false as const,
+              rejection: {
+                code: "missing-source-provenance" as const,
+                reason:
+                  "Exact subject and target source anchors were not both available for this React structure edit.",
+              },
+            };
     return {
       kind: edit.kind,
       screenId: edit.screenId,
@@ -574,16 +996,33 @@ export function formatPendingVisualStylePrompt(args: {
       selector: edit.selector,
       sourceId: edit.sourceId ?? null,
       sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
-      anchorSelector: edit.anchorSelector,
-      anchorSourceId: edit.anchorSourceId ?? null,
-      anchorSourceAnchor: redactReactSourceAnchor(edit.anchorSourceAnchor),
-      placement: edit.placement,
+      // A removal has no anchor; emitting empty anchor fields alongside a
+      // meaningless placement reads as a half-captured move.
+      ...(edit.removed
+        ? { removed: true as const }
+        : {
+            anchorSelector: edit.anchorSelector,
+            anchorSourceId: edit.anchorSourceId ?? null,
+            anchorSourceAnchor: redactReactSourceAnchor(
+              edit.anchorSourceAnchor,
+            ),
+            placement: edit.placement,
+          }),
       ...(edit.dropMode ? { dropMode: edit.dropMode } : {}),
+      ...(edit.routeSourceFile
+        ? { routeSourceFile: edit.routeSourceFile }
+        : {}),
       ...(edit.forceFlowPositionOverride
         ? { forceFlowPositionOverride: true }
         : {}),
       ...(edit.sourceRect ? { sourceRect: edit.sourceRect } : {}),
       ...(edit.anchorRect ? { anchorRect: edit.anchorRect } : {}),
+      ...(insertedHtml
+        ? {
+            insertedHtml: insertedHtml.value,
+            ...(insertedHtml.truncated ? { insertedHtmlTruncated: true } : {}),
+          }
+        : {}),
       ...(semanticHandoff.ok
         ? { semanticHandoff: semanticHandoff.handoff }
         : { semanticHandoffFailure: semanticHandoff.rejection }),
@@ -600,7 +1039,7 @@ export function formatPendingVisualStylePrompt(args: {
       ? `Active localhost connection id: "${args.localhostConnectionId}".`
       : "",
     "",
-    "Use the Design source tools to make the source match the current live canvas preview. Read each target screen, resolve source ids/selectors through the code-layer projection, then apply the style, text, and structure changes with focused source edits. Preserve layout, behavior, and unrelated styling.",
+    "Use the Design source tools to make the source match the current live canvas preview. Read each target screen, resolve source ids/selectors through the code-layer projection, then apply the style, text, layer-state, and structure changes with focused source edits. Preserve layout, behavior, and unrelated styling.",
     hasReactSourceAnchors
       ? "React sourceAnchor fields are source provenance; runtime source ids and selectors are correlation hints only. For a single-instance leaf text, literal className/class, or flat literal style-object edit, call apply-visual-edit with source.kind=local-file plus designId, connectionId, the verified project-relative path, and target.sourceAnchor. First omit persist and inspect proposedDiff; then retry with persist=true only when the diff matches the preview. That write still requires human localhost consent and exact version-hash concurrency. Verify every file, line, column, component, and surrounding control flow before editing. Never use a generic AST reparent, group, wrapper, breakpoint, dynamic expression, repeated render, or shared component transform through this path. For semantic structure edits, follow the embedded semanticHandoff packet and use this exact guarded sequence: read-local-file, capture its versionHash, obtain human write consent, write-local-file with expectedVersionHash and requireExpectedVersionHash: true, then keep the preview pending until HMR proves the intended runtime relationship. On a version conflict, re-read and re-plan; never overwrite blindly."
       : "",
@@ -610,13 +1049,29 @@ export function formatPendingVisualStylePrompt(args: {
     hasBreakpointScopedEdits
       ? "Edits that carry a `breakpoint` field were made while a narrower breakpoint frame was active: apply them as width-scoped overrides (apply-visual-edit with `activeFrameWidthPx` set to breakpoint.activeWidthPx), NOT as base writes — base values must keep rendering at wider viewports. When breakpoint.editScope is `only`, confine the override to breakpoint.activeWidthPx through breakpoint.upperBoundPx; otherwise use the normal desktop-down cascade."
       : "",
+    (args.liveEdits ?? []).some(
+      (edit) => edit.kind === "structure" && edit.removed,
+    )
+      ? "Structure edits carrying `removed: true` are DELETIONS, not moves: the element is already gone from the live preview and must be deleted from the source that renders it. Do not re-create it, and do not read its absent anchor as a half-captured move."
+      : "",
+    (args.liveEdits ?? []).some(
+      (edit) =>
+        edit.kind === "structure" &&
+        Boolean(edit.insertedHtml) &&
+        Boolean(edit.routeSourceFile) &&
+        !edit.anchorSourceAnchor,
+    )
+      ? "A live insert with `routeSourceFile` but no `anchorSourceAnchor` was drawn directly on the screen frame, so its runtime target is the document body rather than a framework-owned element. Treat `routeSourceFile` as the bounded source target, inspect that route's root markup/component, and add `insertedHtml` as a top-level positioned child that matches the live preview. Do not fabricate a body source line or write outside that file unless the route delegates its root markup and you can verify the exact delegated source."
+      : "",
     args.edits.some((edit) => edit.interactionState)
       ? "Edits that carry an `interactionState` field are pseudo-class overrides, not base styles. Apply each property only to that exact state (`hover`, `focus`, `focus-visible`, `active`, or `disabled`) while preserving the element's default styling and its other states."
       : "",
     "",
     "Pending style edits:",
     JSON.stringify(editPayload, null, 2),
-    liveEditPayload.length > 0 ? "Pending text/structure edits:" : "",
+    liveEditPayload.length > 0
+      ? "Pending text/layer-state/structure edits:"
+      : "",
     liveEditPayload.length > 0 ? JSON.stringify(liveEditPayload, null, 2) : "",
   ]
     .filter((line) => line !== "")