@agent-native/core 0.129.1 → 0.130.0

package/corpus/templates/design/app/pages/design-editor/pending-live-edit-unload-guard.ts

@@ -0,0 +1,27 @@
+import { useEffect } from "react";
+
+export function preventPendingLiveEditUnload(event: BeforeUnloadEvent): void {
+  event.preventDefault();
+  event.returnValue = "";
+}
+
+/**
+ * Pending localhost edits live in the iframe preview and its in-memory
+ * undo/redo stacks. A hard reload cannot restore that complete session safely,
+ * so keep the native browser confirmation attached only while those edits
+ * exist. Clearing the pending state after Apply or explicit discard removes
+ * the listener on the next render.
+ */
+export function usePendingLiveEditUnloadGuard(hasPendingEdits: boolean): void {
+  useEffect(() => {
+    if (!hasPendingEdits) return;
+    window.addEventListener("beforeunload", preventPendingLiveEditUnload, {
+      capture: true,
+    });
+    return () => {
+      window.removeEventListener("beforeunload", preventPendingLiveEditUnload, {
+        capture: true,
+      });
+    };
+  }, [hasPendingEdits]);
+}

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

@@ -5,6 +5,7 @@ import type { PendingLiveStructureEdit } from "./pending-edits";
 
 export type RuntimeStructureVerificationFailure =
   | "missing-subject"
+  | "subject-still-present"
   | "missing-anchor"
   | "wrong-parent"
   | "wrong-order"
@@ -30,6 +31,15 @@ export function verifyPendingStructureRuntime(
     edit.selector,
     edit.sourceId ?? undefined,
   );
+  // A removal proves itself by ABSENCE. Running it through the anchor/order
+  // checks below would report "missing-subject" for the exact outcome it
+  // asked for, and the apply flow would sit in awaiting-runtime until it
+  // timed out on a source write that actually succeeded.
+  if (edit.removed) {
+    return subject
+      ? { ok: false, failure: "subject-still-present" }
+      : { ok: true };
+  }
   if (!subject) return { ok: false, failure: "missing-subject" };
   const anchor = resolveCodeLayerNodeFromBridge(
     projection,

package/corpus/templates/design/app/pages/design-editor/react-semantic-handoff.ts

@@ -7,6 +7,12 @@
  * coding agent, which can inspect the surrounding program before editing it.
  */
 
+import {
+  type ElementProvenanceMethod,
+  sourcePositionPrecision,
+  type SourcePositionPrecision,
+} from "@shared/source-mode";
+
 export type ReactSourceScope =
   | "single-instance"
   | "repeated-render"
@@ -20,19 +26,65 @@ export interface ReactSourceAnchor {
   sourceFile?: string;
   line?: number;
   column?: number;
+  /**
+   * Tier that produced line/column. On React 19 it is `debug-stack`, whose
+   * position is the dev server's TRANSFORMED output, not the authored JSX —
+   * see `sourcePositionPrecision`. Absent means the tier was never reported.
+   */
+  method?: ElementProvenanceMethod;
   component?: string;
+  /**
+   * Where the nearest enclosing component was INSTANTIATED (`<Card …>` in the
+   * parent), as opposed to `sourceFile`/`line`/`column` above, which are the
+   * element's own authoring site. For a mapped instance this is the only
+   * location that names the call site the agent has to edit.
+   */
+  ownerRelPath?: string;
+  ownerSourceFile?: string;
+  ownerLine?: number;
+  ownerColumn?: number;
+  ownerComponent?: string;
+  /**
+   * Tier that produced ownerLine/ownerColumn. Distinct from `method`: a
+   * source-plugin element carries an authored position while its owner site
+   * comes from the transformed React 19 owner stack.
+   */
+  ownerMethod?: ElementProvenanceMethod;
+  /**
+   * React key of the nearest component instance. `.map()`-produced siblings
+   * share one authored call site, so line/column plus runtimeMultiplicity says
+   * "one of N instances" while this says WHICH one.
+   */
+  ownerKey?: string;
   runtimeMultiplicity?: number;
   reason?: string;
   scope?: ReactSourceScope;
 }
 
+/**
+ * An anchor with a complete, path-safe location. "Exact" here means every
+ * field is present and validated — NOT that line/column are the authored JSX
+ * coordinates. `positionPrecision` is the field that says which.
+ */
 export interface ExactReactSourceAnchor {
   id: string;
   relPath: string;
   sourceFile: string;
   line: number;
   column: number;
+  /** "transformed" = the dev server's line, approximate against the source. */
+  positionPrecision: SourcePositionPrecision;
+  method?: ElementProvenanceMethod;
   component?: string;
+  ownerRelPath?: string;
+  ownerSourceFile?: string;
+  ownerLine?: number;
+  ownerColumn?: number;
+  ownerComponent?: string;
+  ownerMethod?: ElementProvenanceMethod;
+  /** Precision of ownerLine/ownerColumn; absent when there is no owner site. */
+  ownerPositionPrecision?: SourcePositionPrecision;
+  ownerKey?: string;
   runtimeMultiplicity: number;
   reason?: string;
   scope: ReactSourceScope;
@@ -175,6 +227,7 @@ export interface BuildRuntimeReactLayerStateHandoffInput {
 export type RuntimeStructureMoveExecutionMode =
   | "source-edit"
   | "screen-bridge"
+  | "screen-bridge-insert"
   | "semantic-handoff";
 
 export function resolveRuntimeStructureMoveExecutionMode(input: {
@@ -182,7 +235,37 @@ export function resolveRuntimeStructureMoveExecutionMode(input: {
   targetRuntimeOnly: boolean;
   sourceScreenId: string;
   targetScreenId: string;
+  /**
+   * The DESTINATION screen renders a live localhost app. Node-level
+   * `runtimeOnly` cannot stand in for this: a live drop anchor usually has no
+   * stored layer owner at all, so both `runtimeOnly` flags read false and the
+   * move looks like an ordinary source edit — except the destination's stored
+   * "content" is the bridge URL, so that edit writes an HTML document over the
+   * URL and never reaches the running DOM.
+   */
+  targetScreenIsLive?: boolean;
+  /**
+   * The SUBJECT comes off the board surface, whose primitives are loose markup
+   * with no screen of their own. Only that route may be reinterpreted as an
+   * insert: dropping a real screen's element into a live app is a MOVE, and
+   * turning it into an insert would duplicate the element while leaving the
+   * original in its source screen.
+   */
+  sourceScreenIsBoard?: boolean;
 }): RuntimeStructureMoveExecutionMode {
+  if (
+    input.targetScreenIsLive &&
+    input.sourceScreenIsBoard &&
+    input.sourceScreenId !== input.targetScreenId &&
+    !input.subjectRuntimeOnly
+  ) {
+    return "screen-bridge-insert";
+  }
+  // A live destination has no editable stored document, so any other move into
+  // one belongs to the coding agent — never to the stored-source path, which
+  // would write an HTML document over the destination's bridge URL.
+  if (input.targetScreenIsLive && input.sourceScreenId !== input.targetScreenId)
+    return "semantic-handoff";
   if (!input.subjectRuntimeOnly && !input.targetRuntimeOnly)
     return "source-edit";
   if (
@@ -219,19 +302,68 @@ function safeRelativePath(value: string | undefined): string | null {
   return normalized;
 }
 
+/**
+ * Owner-site fields, path-redacted exactly like the element location. The
+ * owner position carries its OWN precision: a source-plugin element has an
+ * authored `method` while its owner line comes from the transformed React 19
+ * owner stack, so reusing `positionPrecision` here would overstate it.
+ * `ownerComponent`/`ownerKey` survive an unsafe owner path — they are not
+ * locations, and the key is what separates `.map()` siblings.
+ */
+function ownerAnchorFields(anchor: ReactSourceAnchor) {
+  const ownerPath =
+    safeRelativePath(anchor.ownerRelPath) ??
+    safeRelativePath(anchor.ownerSourceFile);
+  const hasOwnerPosition =
+    !!ownerPath &&
+    Number.isInteger(anchor.ownerLine) &&
+    (anchor.ownerLine ?? 0) > 0;
+  return {
+    ...(hasOwnerPosition
+      ? {
+          ownerRelPath: ownerPath,
+          ownerSourceFile:
+            safeRelativePath(anchor.ownerSourceFile) ?? ownerPath,
+          ownerLine: anchor.ownerLine!,
+          ownerPositionPrecision: sourcePositionPrecision(anchor.ownerMethod),
+          ...(Number.isInteger(anchor.ownerColumn) &&
+          (anchor.ownerColumn ?? 0) > 0
+            ? { ownerColumn: anchor.ownerColumn }
+            : {}),
+          ...(anchor.ownerMethod ? { ownerMethod: anchor.ownerMethod } : {}),
+        }
+      : {}),
+    ...(bounded(anchor.ownerComponent, MAX_COMPONENT_LENGTH)
+      ? { ownerComponent: bounded(anchor.ownerComponent, MAX_COMPONENT_LENGTH) }
+      : {}),
+    ...(bounded(anchor.ownerKey, MAX_ID_LENGTH)
+      ? { ownerKey: bounded(anchor.ownerKey, MAX_ID_LENGTH) }
+      : {}),
+  };
+}
+
+/** What prompt serialization emits: the anchor plus its honest precision. */
+export type RedactedReactSourceAnchor = ReactSourceAnchor & {
+  positionPrecision: SourcePositionPrecision;
+};
+
 /**
  * Bound an optional live-preview anchor for prompt serialization. Absolute
  * Fiber paths are replaced by the bridge-safe relPath when available, or
  * omitted when no safe project-relative path has been resolved yet.
+ *
+ * `positionPrecision` always ships with the coordinates: a reader that sees
+ * `line` without it would take a React 19 stack line for the authored one.
  */
 export function redactReactSourceAnchor(
   anchor: ReactSourceAnchor | undefined,
-): ReactSourceAnchor | undefined {
+): RedactedReactSourceAnchor | undefined {
   if (!anchor) return undefined;
   const relPath = safeRelativePath(anchor.relPath);
   const sourceFile = safeRelativePath(anchor.sourceFile);
   const canonicalPath = relPath ?? sourceFile;
   return {
+    positionPrecision: sourcePositionPrecision(anchor.method),
     ...(bounded(anchor.id, MAX_ID_LENGTH)
       ? { id: bounded(anchor.id, MAX_ID_LENGTH) }
       : {}),
@@ -247,9 +379,11 @@ export function redactReactSourceAnchor(
     ...(Number.isInteger(anchor.column) && (anchor.column ?? 0) > 0
       ? { column: anchor.column }
       : {}),
+    ...(anchor.method ? { method: anchor.method } : {}),
     ...(bounded(anchor.component, MAX_COMPONENT_LENGTH)
       ? { component: bounded(anchor.component, MAX_COMPONENT_LENGTH) }
       : {}),
+    ...ownerAnchorFields(anchor),
     ...(Number.isInteger(anchor.runtimeMultiplicity) &&
     (anchor.runtimeMultiplicity ?? 0) > 0
       ? { runtimeMultiplicity: anchor.runtimeMultiplicity }
@@ -307,9 +441,12 @@ function exactAnchor(
     sourceFile: sourceFile ?? canonicalPath,
     line: anchor.line!,
     column: anchor.column!,
+    positionPrecision: sourcePositionPrecision(anchor.method),
+    ...(anchor.method ? { method: anchor.method } : {}),
     ...(bounded(anchor.component, MAX_COMPONENT_LENGTH)
       ? { component: bounded(anchor.component, MAX_COMPONENT_LENGTH) }
       : {}),
+    ...ownerAnchorFields(anchor),
     runtimeMultiplicity:
       Number.isInteger(anchor.runtimeMultiplicity) &&
       (anchor.runtimeMultiplicity ?? 0) > 0
@@ -392,8 +529,11 @@ export function buildReactSemanticHandoff(
     input.runtimeRelationship.targetAnchorId,
     MAX_ID_LENGTH,
   );
+  // An insert's subject is new markup, not an existing runtime node, so it has
+  // no source anchor to reference. Every other operation acts on something
+  // that already exists in the program and must name it.
   if (
-    subjectAnchorIds.length === 0 ||
+    (input.operation !== "insert" && subjectAnchorIds.length === 0) ||
     subjectAnchorIds.some((id) => !id || !anchorIds.has(id)) ||
     (targetAnchorId !== undefined && !anchorIds.has(targetAnchorId))
   ) {
@@ -498,10 +638,29 @@ export function buildReactSemanticHandoff(
       },
       instructions: [
         "Read every target file and verify each source anchor against the surrounding React control flow before editing.",
+        // React 19's only tier is the owner stack, so this branch is the norm
+        // on a modern dev server, not an edge case.
+        ...(sourceAnchors.some(
+          (anchor) =>
+            anchor.positionPrecision !== "authored" ||
+            (anchor.ownerPositionPrecision !== undefined &&
+              anchor.ownerPositionPrecision !== "authored"),
+        )
+          ? [
+              `Do not trust line/column on any anchor whose positionPrecision is not "authored", nor ownerLine/ownerColumn whose ownerPositionPrecision is not "authored" — the two tiers are reported separately and can differ on the same anchor. A "transformed" position is the dev server's own output coordinates (React 19 exposes only an owner stack), and an "unknown" one never reported its tier; on those, treat the file and component as the reliable part and locate the element by its JSX shape, then re-derive the real line from the file you read.`,
+            ]
+          : []),
         "Use semantic source edits; do not apply a generic AST reparent, group, or wrapper transform.",
         "Obtain human write consent and write through the local bridge with expectedVersionHash from the corresponding read and requireExpectedVersionHash: true.",
         "If a version hash conflicts, re-read the source and re-plan instead of overwriting it.",
         "Keep the live preview pending until HMR renders and confirms the intended runtime relationship.",
+        ...(sourceAnchors.some(
+          (anchor) => anchor.ownerKey || anchor.ownerRelPath,
+        )
+          ? [
+              "An anchor's ownerRelPath/ownerLine is where the enclosing component was INSTANTIATED — for a mapped instance, the `.map()` call site — while relPath/line is the element's own JSX inside that component; edit whichever one the change actually belongs to. ownerKey is the React key of the selected instance, not a third location: its siblings share that one call site, so decide whether the change belongs to the data behind that key or to every instance rendered from it.",
+            ]
+          : []),
       ],
     },
   };
@@ -509,7 +668,7 @@ export function buildReactSemanticHandoff(
 
 /** Build the safe coding-agent packet for a runtime Layers-panel move that a
  * screen-scoped StructureMove bridge cannot execute. Both runtime endpoints
- * must already have exact compiler provenance; the generic builder rejects
+ * must already have complete compiler provenance; the generic builder rejects
  * either missing/unsafe anchor rather than guessing from a selector. */
 export function buildRuntimeReactStructureMoveHandoff(
   input: BuildRuntimeReactStructureMoveHandoffInput,
@@ -529,8 +688,8 @@ export function buildRuntimeReactStructureMoveHandoff(
     operation,
     desiredChange:
       input.placement === "inside"
-        ? `Move the runtime React subject from screen "${sourceScreenId}" inside the exact target anchor in screen "${targetScreenId}" while preserving the intended visual order and behavior.`
-        : `Move the runtime React subject from screen "${sourceScreenId}" ${input.placement} the exact target anchor in screen "${targetScreenId}" while preserving the intended visual order and behavior.`,
+        ? `Move the runtime React subject from screen "${sourceScreenId}" inside the target anchor in screen "${targetScreenId}" while preserving the intended visual order and behavior.`
+        : `Move the runtime React subject from screen "${sourceScreenId}" ${input.placement} the target anchor in screen "${targetScreenId}" while preserving the intended visual order and behavior.`,
     sourceAnchors: [subjectAnchor, targetAnchor],
     runtimeRelationship: {
       kind: input.placement,
@@ -541,14 +700,14 @@ export function buildRuntimeReactStructureMoveHandoff(
       screenId: targetScreenId,
       sourceScreenId,
       targetScreenId,
-      description: `Runtime React ${operation} from screen "${sourceScreenId}" to screen "${targetScreenId}" with placement "${input.placement}". Verify both exact source anchors and their surrounding control flow before editing either file.`,
+      description: `Runtime React ${operation} from screen "${sourceScreenId}" to screen "${targetScreenId}" with placement "${input.placement}". Verify both source anchors and their surrounding control flow before editing either file.`,
     },
     versionHashes: [],
   });
 }
 
 /** Build the safe coding-agent packet for a runtime-only layer state toggle.
- * The exact JSX host element receives durable source metadata which survives
+ * The JSX host element receives durable source metadata which survives
  * HMR and is preserved by the runtime Layers snapshot. This is deliberately a
  * semantic handoff: compiler provenance identifies the opening element, but no
  * generic AST transform is authorized to mutate the source. */
@@ -566,8 +725,8 @@ export function buildRuntimeReactLayerStateHandoff(
   const attributeName = `data-agent-native-${input.state}`;
   const subjectAnchor = { ...input.subjectAnchor, id: "subject" };
   const desiredChange = input.enabled
-    ? `Set ${attributeName}="true" on the exact JSX host element for this runtime layer. Keep it as durable source metadata; do not replace it with a transient DOM mutation, CSS-only workaround, or wrapper.`
-    : `Remove the ${attributeName} attribute from the exact JSX host element for this runtime layer. Do not replace it with a transient DOM mutation, CSS-only workaround, or wrapper.`;
+    ? `Set ${attributeName}="true" on the JSX host element for this runtime layer. Keep it as durable source metadata; do not replace it with a transient DOM mutation, CSS-only workaround, or wrapper.`
+    : `Remove the ${attributeName} attribute from the JSX host element for this runtime layer. Do not replace it with a transient DOM mutation, CSS-only workaround, or wrapper.`;
 
   return buildReactSemanticHandoff({
     operation: "set-layer-state",

package/corpus/templates/design/app/pages/design-editor/responsive-interact.ts

@@ -1,5 +1,5 @@
 /**
- * Pure data/logic for the full-screen Interact mode's device chrome bar
+ * Pure data/logic for the responsive Interact mode's device chrome bar
  * (ResponsiveInteractBar). Modeled on builder-internal's
  * ResponsiveEditingMode/responsive-device-presets, adapted to this app's
  * shadcn chrome. Kept separate from DEVICE_FRAME_VIEWPORTS in
@@ -50,7 +50,9 @@ export const INTERACT_DEVICE_PRESETS: InteractDevicePreset[] = [
   },
 ];
 
-export const DEFAULT_INTERACT_DEVICE_PRESET = INTERACT_DEVICE_PRESETS[1]!;
+export const DEFAULT_INTERACT_DEVICE_PRESET = INTERACT_DEVICE_PRESETS.find(
+  (preset) => preset.category === "desktop",
+)!;
 
 export function findInteractDevicePreset(
   name: string,
@@ -58,8 +60,44 @@ export function findInteractDevicePreset(
   return INTERACT_DEVICE_PRESETS.find((preset) => preset.name === name);
 }
 
+export function resolveInteractDeviceForScreen(screen?: {
+  width?: number | null;
+  height?: number | null;
+}): InteractDevicePreset {
+  const width =
+    typeof screen?.width === "number" &&
+    Number.isFinite(screen.width) &&
+    screen.width > 0
+      ? Math.round(screen.width)
+      : DEFAULT_INTERACT_DEVICE_PRESET.width;
+  const height =
+    typeof screen?.height === "number" &&
+    Number.isFinite(screen.height) &&
+    screen.height > 0
+      ? Math.round(screen.height)
+      : DEFAULT_INTERACT_DEVICE_PRESET.height;
+  const preset = INTERACT_DEVICE_PRESETS.find(
+    (candidate) =>
+      candidate.category !== "custom" &&
+      candidate.width === width &&
+      candidate.height === height,
+  );
+  return (
+    preset ?? {
+      name: INTERACT_CUSTOM_DEVICE_NAME,
+      category: "custom",
+      width,
+      height,
+    }
+  );
+}
+
+export function formatInteractZoom(zoom: number): string {
+  return Number.isFinite(zoom) ? zoom.toFixed(1) : "100.0";
+}
+
 /**
- * Auto-fit zoom for the full-screen device box, ported from
+ * Auto-fit zoom for the responsive device box, ported from
  * builder-internal's ResponsiveEditingMode effect (~lines 155-174): only
  * zooms DOWN so the device fits the available chrome area, never zooms in
  * past 100% just because there's extra room. Steps to the nearest 5 and

package/corpus/templates/design/app/pages/design-editor/screen-command-utils.ts

@@ -42,6 +42,10 @@ export function designEditorCommandFromSearchParams(
   const rawZoom = searchParams.get("zoom");
   const zoom = rawZoom !== null ? Number(rawZoom) : NaN;
   const tool = normalizeDesignTool(searchParams.get("tool"));
+  // `single` is the URL spelling for the responsive Interact surface. There
+  // is no focused editing view, so even an older URL without mode=interact
+  // must enter Interact directly instead of reviving the removed Full view.
+  const mode = editorView === "single" ? "interact" : undefined;
   if (
     editorView !== "overview" &&
     editorView !== "single" &&
@@ -76,6 +80,7 @@ export function designEditorCommandFromSearchParams(
     command.zoom = FOCUSED_SCREEN_ZOOM;
   }
   if (tool) command.tool = tool;
+  if (mode) command.mode = mode;
   return command;
 }
 

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

@@ -148,6 +148,38 @@ export function isScreenRootElementInfo(info: ElementInfo | null | undefined) {
   return tagName === "BODY" || tagName === "HTML";
 }
 
+/**
+ * Whether a plain Delete in overview mode targets an ELEMENT inside a screen
+ * rather than the screen frames themselves. MultiScreenCanvas keeps the owning
+ * screen in its `selectedIds` while an element inside it is selected (frame
+ * z-order and "topmost screen" depend on that), so Delete reaches the editor as
+ * "delete these screens" even when the real selection is one node. The more
+ * specific target wins — the same precedence shouldSuppressFrameSelectionBox
+ * already applies to the selection chrome.
+ *
+ * Layer ids are filtered the way getSelectedLayerSnapshots filters its
+ * candidates: a screen's own file-id row and the `__`-prefixed pseudo rows are
+ * screen/frame selections, not element selections.
+ */
+export function overviewDeleteTargetsElement(args: {
+  selectedElement: ElementInfo | null | undefined;
+  selectedLayerIds: readonly string[];
+  fileIds: readonly string[];
+}): boolean {
+  const fileIds = new Set(args.fileIds);
+  if (
+    args.selectedLayerIds.some(
+      (layerId) =>
+        layerId && !layerId.startsWith("__") && !fileIds.has(layerId),
+    )
+  ) {
+    return true;
+  }
+  return Boolean(
+    args.selectedElement && !isScreenRootElementInfo(args.selectedElement),
+  );
+}
+
 export function shouldMirrorSelectedElementToAgentChat(
   info: ElementInfo | null | undefined,
 ): info is ElementInfo {
@@ -307,24 +339,21 @@ export function getSidebarCodeLayerSelectionState(args: {
   overviewSelectedScreenIds: string[];
   screenFileIds?: string[];
 }) {
-  const {
-    currentViewMode,
-    ownerFileId,
-    overviewSelectedScreenIds,
-    screenFileIds,
-  } = args;
+  const { ownerFileId, overviewSelectedScreenIds, screenFileIds } = args;
   const ownerScreenId =
     ownerFileId && (!screenFileIds || screenFileIds.includes(ownerFileId))
       ? ownerFileId
       : null;
   return {
-    viewMode: currentViewMode,
-    overviewSelectedScreenIds:
-      currentViewMode === "overview" && ownerScreenId
-        ? [ownerScreenId]
-        : currentViewMode === "overview" && ownerFileId
-          ? []
-          : overviewSelectedScreenIds,
+    // Layer selection is an editing action, so it always targets the infinite
+    // canvas. Keeping `single` here let the Layers rail turn Interact into the
+    // removed focused Edit view when the handler subsequently set mode=edit.
+    viewMode: "overview" as const,
+    overviewSelectedScreenIds: ownerScreenId
+      ? [ownerScreenId]
+      : ownerFileId
+        ? []
+        : overviewSelectedScreenIds,
   };
 }