@agent-native/core 0.163.4 → 0.164.3

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

@@ -0,0 +1,279 @@
+import type { CodeLayerNode } from "@shared/code-layer";
+import { buildCodeLayerProjection } from "@shared/code-layer";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+import * as Y from "yjs";
+
+import { trace } from "@/components/design/design-trace";
+import type { ElementInfo } from "@/components/design/types";
+import type { ClipboardContentMutationPublication } from "@/lib/clipboard-content-lineage";
+import {
+  extractLayerPosition,
+  getElementOuterHtml,
+  insertClonedHtmlLayer,
+  insertClonedHtmlLayers,
+} from "@/pages/design-editor/clone-and-pen-edit";
+import {
+  codeLayerSelectorAliases,
+  elementInfoFromCodeLayerNode,
+} from "@/pages/design-editor/code-layer-state";
+import type { SelectedCanvasLayerSnapshot } from "@/pages/design-editor/command-types";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface DuplicateSelectionArgs {
+  activeFile: DesignFile;
+  applyFileContentUpdate: (
+    fileId: string,
+    nextContent: string,
+    options?: {
+      refreshPreview?: boolean;
+      skipPreview?: boolean;
+      forcePreviewFullDocument?: boolean;
+      persist?: boolean;
+      recordHistory?: boolean;
+      updatedAt?: string;
+      clipboardMutation?: ClipboardContentMutationPublication;
+    },
+  ) => void;
+  applyLocalContentUpdate: (
+    nextContent: string,
+    options?: {
+      refreshPreview?: boolean;
+      skipPreview?: boolean;
+      forcePreviewFullDocument?: boolean;
+      immediateSave?: boolean;
+      persist?: boolean;
+      recordHistory?: boolean;
+      historyBeforeContent?: string;
+      updatedAt?: string;
+      clipboardMutation?: ClipboardContentMutationPublication;
+    },
+  ) => void;
+  canEditDesign: boolean;
+  files: DesignFile[];
+  getFreshActiveContent: () => string;
+  getScreenContent: (screenId: string) => string;
+  getSelectedLayerSnapshots: () => SelectedCanvasLayerSnapshot[];
+  handleDuplicateScreen: (
+    screenId: string,
+    request?: { canvasPosition?: { x: number; y: number } },
+  ) => void;
+  lastDuplicateTransformRef: RefObject<{
+    rootNodeIds: string[];
+    dx: number;
+    dy: number;
+  } | null>;
+  overviewSelectedScreenIds: string[];
+  remapMotionTracksForClone: (
+    nodeIdMap: Map<string, string>,
+    targetFileId: string,
+  ) => void;
+  selectedCanvasSelector: string;
+  selectedElement: ElementInfo | null;
+  selectedLayerIdsState: string[];
+  setOverviewSelectedScreenIds: Dispatch<SetStateAction<string[]>>;
+  setSelectedElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setSelectedLayerIdsState: Dispatch<SetStateAction<string[]>>;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  undoManagerRef: RefObject<Y.UndoManager | null>;
+  viewModeRef: RefObject<"single" | "overview">;
+}
+
+export function runDuplicateSelection({
+  activeFile,
+  applyFileContentUpdate,
+  applyLocalContentUpdate,
+  canEditDesign,
+  files,
+  getFreshActiveContent,
+  getScreenContent,
+  getSelectedLayerSnapshots,
+  handleDuplicateScreen,
+  lastDuplicateTransformRef,
+  overviewSelectedScreenIds,
+  remapMotionTracksForClone,
+  selectedCanvasSelector,
+  selectedElement,
+  selectedLayerIdsState,
+  setOverviewSelectedScreenIds,
+  setSelectedElement,
+  setSelectedLayerIdsState,
+  t,
+  undoManagerRef,
+  viewModeRef,
+}: DuplicateSelectionArgs) {
+  trace("structure", "duplicate-selection", {
+    canEdit: canEditDesign,
+    selectedLayers: selectedLayerIdsState.length,
+  });
+  if (!canEditDesign) return;
+  // U19: duplicate is a discrete one-shot action — see the matching note
+  // in handlePasteSelection.
+  undoManagerRef.current?.stopCapturing();
+  const snapshots = getSelectedLayerSnapshots();
+  if (snapshots.length > 0) {
+    const selectedIds: string[] = [];
+    const selectedScreenIds: string[] = [];
+    let lastActiveNode: CodeLayerNode | null = null;
+
+    // U7: replay the last recorded move delta when duplicating the exact
+    // same selection again (e.g. dup, drag it, dup again repeats the same
+    // offset — matching Figma). Otherwise an absolutely-positioned source
+    // duplicates with zero offset (lands exactly in place) instead of the
+    // previous unconditional stripRootPosition cascade.
+    const currentSourceIds = snapshots
+      .map((snapshot) => snapshot.rootNodeId ?? snapshot.node.id)
+      .sort();
+    const repeatTransform =
+      lastDuplicateTransformRef.current &&
+      lastDuplicateTransformRef.current.rootNodeIds.length ===
+        currentSourceIds.length &&
+      lastDuplicateTransformRef.current.rootNodeIds.every(
+        (id, index) => id === currentSourceIds[index],
+      )
+        ? lastDuplicateTransformRef.current
+        : null;
+    const nextDuplicateRootNodeIds: string[] = [];
+
+    for (const file of files) {
+      const group = snapshots.filter(
+        (snapshot) => snapshot.sourceFileId === file.id,
+      );
+      if (group.length === 0) continue;
+      let content = getScreenContent(file.id);
+      const insertedRootNodeIds: string[] = [];
+      for (const snapshot of [...group].sort(
+        (a, b) => b.sourceIndex - a.sourceIndex,
+      )) {
+        const projection = buildCodeLayerProjection(content);
+        const anchorNode =
+          projection.nodes.find(
+            (node) =>
+              node.id === snapshot.node.id ||
+              node.dataAttributes["data-agent-native-node-id"] ===
+                snapshot.rootNodeId,
+          ) ?? snapshot.node;
+        const sourcePosition = extractLayerPosition(snapshot.html);
+        const result = insertClonedHtmlLayers(content, [snapshot.html], {
+          targetSelectors: codeLayerSelectorAliases(anchorNode),
+          placement: "after",
+          // Absolutely-positioned board items land exactly in place (or at
+          // the replayed delta); only in-flow elements (no left/top) use
+          // stripRootPosition so they join the document as a plain sibling.
+          stripRootPosition: !sourcePosition,
+          positions: sourcePosition
+            ? [
+                {
+                  x: sourcePosition.x + (repeatTransform?.dx ?? 0),
+                  y: sourcePosition.y + (repeatTransform?.dy ?? 0),
+                },
+              ]
+            : undefined,
+        });
+        if (!result) continue;
+        content = result.content;
+        insertedRootNodeIds.unshift(...result.rootNodeIds);
+        // U14: duplicate keeps the clone's animation.
+        remapMotionTracksForClone(result.nodeIdMap, file.id);
+      }
+      if (insertedRootNodeIds.length === 0) continue;
+      applyFileContentUpdate(file.id, content, {
+        forcePreviewFullDocument: true,
+        refreshPreview: false,
+      });
+      selectedScreenIds.push(file.id);
+      const finalProjection = buildCodeLayerProjection(content);
+      insertedRootNodeIds.forEach((rootNodeId) => {
+        const insertedNode = finalProjection.nodes.find(
+          (node) =>
+            node.id === rootNodeId ||
+            node.dataAttributes["data-agent-native-node-id"] === rootNodeId,
+        );
+        if (!insertedNode) return;
+        selectedIds.push(insertedNode.id);
+        nextDuplicateRootNodeIds.push(
+          insertedNode.dataAttributes["data-agent-native-node-id"] ??
+            insertedNode.id,
+        );
+        if (file.id === activeFile?.id) lastActiveNode = insertedNode;
+      });
+    }
+
+    if (selectedIds.length > 0) {
+      setSelectedLayerIdsState(selectedIds);
+      setSelectedElement(
+        lastActiveNode ? elementInfoFromCodeLayerNode(lastActiveNode) : null,
+      );
+      if (viewModeRef.current === "overview") {
+        setOverviewSelectedScreenIds(selectedScreenIds);
+      }
+      // Track this duplicate as the new "last duplicate" so a subsequent
+      // drag-then-Cmd+D can record/replay a delta against it. Preserve the
+      // previous delta across repeated Cmd+D so chained duplicates (no drag
+      // in between) keep applying the same recorded offset, matching Figma.
+      lastDuplicateTransformRef.current = {
+        rootNodeIds: [...nextDuplicateRootNodeIds].sort(),
+        dx: repeatTransform?.dx ?? 0,
+        dy: repeatTransform?.dy ?? 0,
+      };
+      return;
+    }
+  }
+
+  if (selectedElement?.selector) {
+    const baseContent = getFreshActiveContent();
+    const html = getElementOuterHtml(baseContent, selectedElement.selector);
+    if (!html) {
+      toast.error(t("designEditor.toasts.duplicateElementFailed"));
+      return;
+    }
+    // B7 fix: duplicate inserts the clone as an in-flow sibling right AFTER
+    // the original — not as an absolutely-positioned body child.  Strip
+    // position/left/top so it joins normal document flow.
+    const selector = selectedCanvasSelector ?? selectedElement.selector;
+    const strippedHtml = (() => {
+      try {
+        const parser = new DOMParser();
+        const tmp = parser.parseFromString(
+          `<template>${html}</template>`,
+          "text/html",
+        );
+        const root =
+          tmp.querySelector("template")?.content.firstElementChild ??
+          tmp.body.firstElementChild;
+        if (root && root instanceof HTMLElement) {
+          root.style.position = "";
+          root.style.left = "";
+          root.style.top = "";
+          root.style.right = "";
+          root.style.bottom = "";
+        }
+        return root?.outerHTML ?? html;
+      } catch {
+        return html;
+      }
+    })();
+    const nextContent = insertClonedHtmlLayer(baseContent, strippedHtml, {
+      targetSelectors: [selector],
+      placement: "after",
+    });
+    if (nextContent) {
+      applyLocalContentUpdate(nextContent, {
+        forcePreviewFullDocument: true,
+      });
+    } else {
+      toast.error(t("designEditor.toasts.duplicateElementFailed"));
+    }
+    return;
+  }
+  // U17: duplicate every selected screen, not just the active one — a
+  // multi-screen overview selection (no deeper layer focus) previously
+  // silently duplicated only activeFile.id and dropped the rest.
+  const screenIdsToDuplicate =
+    viewModeRef.current === "overview" && overviewSelectedScreenIds.length > 1
+      ? overviewSelectedScreenIds
+      : activeFile
+        ? [activeFile.id]
+        : [];
+  screenIdsToDuplicate.forEach((screenId) => handleDuplicateScreen(screenId));
+}

package/corpus/templates/design/app/pages/design-editor/commands/editor-paste.ts

@@ -0,0 +1,81 @@
+import type { RefObject } from "react";
+
+import { isDesignHotkeyEditableTarget } from "@/hooks/useDesignHotkeys";
+import { readDesignClipboardPayloadFromDataTransfer } from "@/lib/design-clipboard";
+import type { DesignClipboardPayload } from "@/lib/design-import";
+import { getFigmaClipboardContent } from "@/lib/design-import";
+
+export interface EditorPasteArgs {
+  adoptDesignClipboardPayload: (
+    payload: DesignClipboardPayload,
+    markerText: string,
+    plainText?: string,
+  ) => void;
+  canEditDesign: boolean;
+  handlePasteSelection: (position?: { x: number; y: number }) => Promise<void>;
+  handlePastedImageFiles: (files: File[]) => boolean;
+  hasCanvasClipboard: boolean;
+  importFigmaClipboardIntoDesign: (content: string) => Promise<void>;
+  lastWrittenClipboardMarkerRef: RefObject<string | null>;
+  lastWrittenClipboardPlainTextRef: RefObject<string | null>;
+}
+
+export function runEditorPaste(
+  {
+    adoptDesignClipboardPayload,
+    canEditDesign,
+    handlePasteSelection,
+    handlePastedImageFiles,
+    hasCanvasClipboard,
+    importFigmaClipboardIntoDesign,
+    lastWrittenClipboardMarkerRef,
+    lastWrittenClipboardPlainTextRef,
+  }: EditorPasteArgs,
+  event: ClipboardEvent,
+) {
+  if (event.defaultPrevented) return;
+  if (isDesignHotkeyEditableTarget(event.target)) return;
+  // U8/paste-multi: collect every pasted image file, not just the first —
+  // see handlePastedImageFiles' doc comment for the full rationale.
+  const imageFiles = Array.from(event.clipboardData?.items ?? [])
+    .filter((item) => item.kind === "file" && item.type.startsWith("image/"))
+    .map((item) => item.getAsFile())
+    .filter((file): file is File => Boolean(file));
+  if (imageFiles.length > 0 && canEditDesign) {
+    if (handlePastedImageFiles(imageFiles)) {
+      event.preventDefault();
+      return;
+    }
+  }
+  const figmaContent = getFigmaClipboardContent(event.clipboardData);
+  if (figmaContent) {
+    event.preventDefault();
+    void importFigmaClipboardIntoDesign(figmaContent);
+    return;
+  }
+  if (!canEditDesign) return;
+  // The native paste event reflects the current clipboard synchronously.
+  // New copies carry their lossless marker in text/html; text/plain remains
+  // readable. The helper also accepts legacy markers from text/plain.
+  const clipboardResult = readDesignClipboardPayloadFromDataTransfer(
+    event.clipboardData,
+  );
+  if (
+    clipboardResult &&
+    clipboardResult.markerText !== lastWrittenClipboardMarkerRef.current
+  ) {
+    adoptDesignClipboardPayload(
+      clipboardResult.payload,
+      clipboardResult.markerText,
+      clipboardResult.plainText,
+    );
+  }
+  const clipboardPlainText = event.clipboardData?.getData("text/plain") ?? "";
+  const matchesInMemoryClipboard =
+    lastWrittenClipboardPlainTextRef.current !== null &&
+    clipboardPlainText === lastWrittenClipboardPlainTextRef.current;
+  if (clipboardResult || (hasCanvasClipboard && matchesInMemoryClipboard)) {
+    event.preventDefault();
+    void handlePasteSelection();
+  }
+}

package/corpus/templates/design/app/pages/design-editor/commands/enter-hotkey.ts

@@ -0,0 +1,155 @@
+import type { CodeLayerNode, CodeLayerTreeNode } from "@shared/code-layer";
+import { buildCodeLayerProjection } from "@shared/code-layer";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+
+import { getOverviewEnterTarget } from "@/pages/design-editor/selection-state";
+import { scheduleBeginTextEditForScreen } from "@/pages/design-editor/text-edit-utils";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface EnterHotkeyArgs {
+  SINGLE_MODE_TEXT_TAGS: Set<string>;
+  activeFile: DesignFile;
+  activeFileId: string | null;
+  boardFileId: string | undefined;
+  codeLayerOwnerByNodeIdRef: RefObject<
+    Map<
+      string,
+      {
+        fileId: string;
+        node: CodeLayerNode;
+        tree: CodeLayerTreeNode[];
+        runtimeOnly: boolean;
+      }
+    >
+  >;
+  enterVectorEditForSelection: (owner: {
+    fileId: string;
+    node: CodeLayerNode;
+  }) => boolean;
+  getProjectionContentForScreen: (screenId: string) => string;
+  overviewSelectedScreenIds: string[];
+  selectCodeLayerNodesForHotkey: (
+    fileId: string,
+    nodes: CodeLayerNode[],
+    expandedIds?: readonly string[],
+  ) => boolean;
+  selectedLayerIdsState: string[];
+  setActiveFileId: Dispatch<SetStateAction<string | null>>;
+  setSelectedLayerIdsState: Dispatch<SetStateAction<string[]>>;
+  viewMode: "single" | "overview";
+}
+
+export function runEnterHotkey({
+  SINGLE_MODE_TEXT_TAGS,
+  activeFile,
+  activeFileId,
+  boardFileId,
+  codeLayerOwnerByNodeIdRef,
+  enterVectorEditForSelection,
+  getProjectionContentForScreen,
+  overviewSelectedScreenIds,
+  selectCodeLayerNodesForHotkey,
+  selectedLayerIdsState,
+  setActiveFileId,
+  setSelectedLayerIdsState,
+  viewMode,
+}: EnterHotkeyArgs) {
+  if (viewMode !== "overview") {
+    if (selectedLayerIdsState.length === 1) {
+      const layerId = selectedLayerIdsState[0]!;
+      const owner = codeLayerOwnerByNodeIdRef.current.get(layerId);
+      if (owner && owner.fileId === (activeFile?.id ?? activeFileId)) {
+        const isTextNode =
+          SINGLE_MODE_TEXT_TAGS.has(owner.node.tag) ||
+          owner.node.dataAttributes["data-an-primitive"] === "text";
+        if (isTextNode) {
+          const nodeAttrId =
+            owner.node.dataAttributes["data-agent-native-node-id"] ??
+            owner.node.id;
+          scheduleBeginTextEditForScreen(owner.fileId, nodeAttrId, {
+            boardFileId,
+          });
+          return;
+        }
+        const childNodes = owner.node.children
+          .map(
+            (childId) => codeLayerOwnerByNodeIdRef.current.get(childId)?.node,
+          )
+          .filter((node): node is CodeLayerNode => Boolean(node));
+        if (
+          selectCodeLayerNodesForHotkey(owner.fileId, childNodes, [
+            owner.node.id,
+          ])
+        ) {
+          return;
+        }
+      }
+    }
+    return;
+  }
+  // P5/vector-edit: Enter on a single selected committed pen path (has
+  // data-an-pen-nodes — see setPenNodesAttributeOnElement) enters vector
+  // edit mode instead of drilling into the owning screen. Vector edit's
+  // overlay only exists on MultiScreenCanvas (overview), so this
+  // deliberately only fires here — see enterVectorEditForSelection's doc
+  // comment for the single-screen deferral.
+  if (selectedLayerIdsState.length === 1) {
+    const layerId = selectedLayerIdsState[0]!;
+    const owner = codeLayerOwnerByNodeIdRef.current.get(layerId);
+    const penNodesAttr = owner?.node.dataAttributes["data-an-pen-nodes"];
+    if (owner && penNodesAttr && enterVectorEditForSelection(owner)) {
+      return;
+    }
+    // Figma parity: Enter on a selected TEXT layer always begins inline
+    // text editing, in overview mode too — not just single-screen mode
+    // (see the T22 branch above). Reuses the exact same owner lookup /
+    // SINGLE_MODE_TEXT_TAGS / data-an-primitive==="text" classification
+    // and scheduleBeginTextEditForScreen path; only the screen-drill
+    // fallback below is skipped when the selected layer is text.
+    if (owner) {
+      const isTextNode =
+        SINGLE_MODE_TEXT_TAGS.has(owner.node.tag) ||
+        owner.node.dataAttributes["data-an-primitive"] === "text";
+      if (isTextNode) {
+        const nodeAttrId =
+          owner.node.dataAttributes["data-agent-native-node-id"] ??
+          owner.node.id;
+        scheduleBeginTextEditForScreen(owner.fileId, nodeAttrId, {
+          boardFileId,
+        });
+        return;
+      }
+      const childNodes = owner.node.children
+        .map((childId) => codeLayerOwnerByNodeIdRef.current.get(childId)?.node)
+        .filter((node): node is CodeLayerNode => Boolean(node));
+      if (
+        selectCodeLayerNodesForHotkey(owner.fileId, childNodes, [owner.node.id])
+      ) {
+        return;
+      }
+    }
+  }
+  const target = getOverviewEnterTarget({
+    activeFileId: activeFile?.id ?? activeFileId,
+    overviewSelectedScreenIds,
+  });
+  if (!target) return;
+  // Ground-truth Figma: Enter on a screen/container selects ALL of its
+  // direct children (not just the first) in addition to drilling in.
+  // rootNodeIds from the screen's own code-layer projection are exactly
+  // its direct children (nodes with no parent, i.e. direct children of
+  // <body>) — the same ids setSelectedLayerIdsState already accepts
+  // elsewhere (e.g. after insert/paste).
+  const targetProjection = buildCodeLayerProjection(
+    getProjectionContentForScreen(target),
+  );
+  if (targetProjection.rootNodeIds.length > 0) {
+    setSelectedLayerIdsState(targetProjection.rootNodeIds);
+  }
+  // Drill-in selects the screen's children and stays on the infinite canvas.
+  // It used to also switch to a focused single-screen view — that view no
+  // longer exists (the only two views are the canvas and the responsive
+  // interactive one), and routing this through the focused view now would
+  // land the user in Interact, where there is no selection at all.
+  setActiveFileId(target);
+}

package/corpus/templates/design/app/pages/design-editor/commands/enter-single-screen.ts

@@ -0,0 +1,168 @@
+import type { CanvasFrameGeometryById } from "@shared/canvas-frames";
+import type { PenPath } from "@shared/pen-path";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+
+import { getScreenPreviewViewport } from "@/components/design/multi-screen/frame-geometry";
+import type { ElementInfo } from "@/components/design/types";
+import type { OverviewScreen } from "@/pages/design-editor/derive/overview-screens";
+import { resolveScreenEntryZoom } from "@/pages/design-editor/overview-camera";
+import {
+  DEFAULT_INTERACT_DEVICE_PRESET,
+  resolveInteractDeviceForScreen,
+} from "@/pages/design-editor/responsive-interact";
+import type { DesignTool, EditorMode } from "@/pages/design-editor/types";
+import { FOCUSED_SCREEN_ZOOM } from "@/pages/design-editor/types";
+
+export interface EnterSingleScreenArgs {
+  activeFileId: string | null;
+  canvasFrameGeometryById: CanvasFrameGeometryById;
+  clearPendingOverviewLayerSelectionTimer: () => void;
+  overviewScreens: OverviewScreen[];
+  pendingOverviewLayerSelectionRef: RefObject<string | null>;
+  pendingOverviewScreenSelectionRef: RefObject<string | null>;
+  runEditorViewTransition: (update: () => void) => void;
+  screenZoomByIdRef: RefObject<Map<string, number>>;
+  setActiveFileId: Dispatch<SetStateAction<string | null>>;
+  setActiveTool: Dispatch<SetStateAction<DesignTool>>;
+  setCreatedOverviewLayerSelection: Dispatch<
+    SetStateAction<{ screenId: string; layerId: string } | null>
+  >;
+  setDrawMode: Dispatch<SetStateAction<boolean>>;
+  setHoveredElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setInteractDeviceName: Dispatch<SetStateAction<string>>;
+  setInteractDeviceSize: Dispatch<
+    SetStateAction<{ width: number; height: number }>
+  >;
+  setMode: Dispatch<SetStateAction<EditorMode>>;
+  setPinMode: Dispatch<SetStateAction<boolean>>;
+  setScreenZoom: Dispatch<SetStateAction<number>>;
+  setSelectedElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setVectorEditingState: Dispatch<
+    SetStateAction<{ screenId: string; nodeId: string; path: PenPath } | null>
+  >;
+  setViewMode: Dispatch<SetStateAction<"single" | "overview">>;
+  viewModeRef: RefObject<"single" | "overview">;
+}
+
+export interface EnterSingleScreenOptions {
+  mode?: EditorMode;
+}
+
+export function runEnterSingleScreen(
+  {
+    activeFileId,
+    canvasFrameGeometryById,
+    clearPendingOverviewLayerSelectionTimer,
+    overviewScreens,
+    pendingOverviewLayerSelectionRef,
+    pendingOverviewScreenSelectionRef,
+    runEditorViewTransition,
+    screenZoomByIdRef,
+    setActiveFileId,
+    setActiveTool,
+    setCreatedOverviewLayerSelection,
+    setDrawMode,
+    setHoveredElement,
+    setInteractDeviceName,
+    setInteractDeviceSize,
+    setMode,
+    setPinMode,
+    setScreenZoom,
+    setSelectedElement,
+    setVectorEditingState,
+    setViewMode,
+    viewModeRef,
+  }: EnterSingleScreenArgs,
+  fileId?: string | null,
+  options?: EnterSingleScreenOptions,
+) {
+  const entryMode = options?.mode ?? "interact";
+  const targetFileId = fileId ?? activeFileId;
+  const targetScreen = targetFileId
+    ? overviewScreens.find((screen) => screen.id === targetFileId)
+    : undefined;
+  const targetMetadataSize = targetScreen
+    ? {
+        width: targetScreen.width ?? DEFAULT_INTERACT_DEVICE_PRESET.width,
+        height: targetScreen.height ?? DEFAULT_INTERACT_DEVICE_PRESET.height,
+      }
+    : undefined;
+  const targetViewport =
+    targetFileId && targetMetadataSize
+      ? getScreenPreviewViewport(targetMetadataSize, {
+          width:
+            canvasFrameGeometryById[targetFileId]?.width ??
+            targetMetadataSize.width,
+          height:
+            canvasFrameGeometryById[targetFileId]?.height ??
+            targetMetadataSize.height,
+        })
+      : undefined;
+  const nextInteractDevice = resolveInteractDeviceForScreen(
+    targetViewport
+      ? {
+          width: targetViewport.viewportWidth,
+          height: targetViewport.viewportHeight,
+        }
+      : undefined,
+  );
+  if (
+    viewModeRef.current === "single" &&
+    (!fileId || fileId === activeFileId)
+  ) {
+    if (fileId && fileId === activeFileId) {
+      // Re-focusing the screen that's already active is a deliberate
+      // "reset view" affordance (e.g. re-clicking the same screen's
+      // Interact button) — reset to the default zoom rather than
+      // restoring the remembered one, mirroring the previous behavior.
+      setScreenZoom(FOCUSED_SCREEN_ZOOM);
+    }
+    // The early return used to swallow a requested mode change, so
+    // re-clicking a screen after closing Interact left it in whatever
+    // mode it had drifted to instead of reopening the responsive view.
+    setMode(entryMode);
+    setInteractDeviceName(nextInteractDevice.name);
+    setInteractDeviceSize({
+      width: nextInteractDevice.width,
+      height: nextInteractDevice.height,
+    });
+    return;
+  }
+  viewModeRef.current = "single";
+  pendingOverviewScreenSelectionRef.current = null;
+  pendingOverviewLayerSelectionRef.current = null;
+  clearPendingOverviewLayerSelectionTimer();
+  setCreatedOverviewLayerSelection(null);
+  // P5/vector-edit: MultiScreenCanvas (the only place the vectorEdit
+  // overlay renders) unmounts on leaving overview, so an active
+  // vector-edit session has nothing left to render into — clear it
+  // rather than leaving a stale/orphaned session in memory that would
+  // resurface if the user returns to overview later.
+  setVectorEditingState(null);
+  // Per-screen zoom memory: restore the target screen's last-remembered
+  // zoom (recorded by the screenZoomByIdRef effect above) instead of
+  // always resetting to FOCUSED_SCREEN_ZOOM, so leaving and re-entering a
+  // screen preserves where the user left off. Falls back to
+  // FOCUSED_SCREEN_ZOOM for a screen's first visit.
+  const restoredZoom = resolveScreenEntryZoom(
+    targetFileId,
+    screenZoomByIdRef.current,
+    FOCUSED_SCREEN_ZOOM,
+  );
+  runEditorViewTransition(() => {
+    if (fileId) setActiveFileId(fileId);
+    setDrawMode(false);
+    setPinMode(false);
+    setMode(entryMode);
+    setSelectedElement(null);
+    setHoveredElement(null);
+    setActiveTool("move");
+    setScreenZoom(restoredZoom);
+    setInteractDeviceName(nextInteractDevice.name);
+    setInteractDeviceSize({
+      width: nextInteractDevice.width,
+      height: nextInteractDevice.height,
+    });
+    setViewMode("single");
+  });
+}