@agent-native/core 0.163.3 → 0.164.1

package/corpus/templates/design/app/pages/design-editor/commands/render-png-blob.ts

@@ -0,0 +1,200 @@
+import type { CanvasFrameGeometryById } from "@shared/canvas-frames";
+import { normalizeDesignSourceType } from "@shared/source-mode";
+
+import type { ExportSettingsValue } from "@/components/design/inspector";
+import type { ElementInfo } from "@/components/design/types";
+import type { OverviewScreen } from "@/pages/design-editor/derive/overview-screens";
+import {
+  getExportCompositeBounds,
+  resolveRasterExportScale,
+} from "@/pages/design-editor/export-capture";
+import type { PngCaptureScope } from "@/pages/design-editor/png-export-render";
+import {
+  PngCaptureError,
+  cropCanvasToRect,
+  renderExportDocumentCanvas,
+  resolveExportCropRect,
+} from "@/pages/design-editor/png-export-render";
+
+export interface RenderPngBlobArgs {
+  activeCanvasSourceType: "inline" | "localhost" | "fusion";
+  canEditDesign: boolean;
+  canvasFrameGeometryById: CanvasFrameGeometryById;
+  overviewScreens: OverviewScreen[];
+  resolvePngCaptureTarget: (scope: PngCaptureScope) => {
+    cropSelection: ElementInfo | readonly ElementInfo[] | null;
+    doc: Document;
+    iframe: HTMLIFrameElement;
+  };
+  selectedScreenIds: string[];
+  viewMode: "single" | "overview";
+}
+
+export async function runRenderPngBlob(
+  {
+    activeCanvasSourceType,
+    canEditDesign,
+    canvasFrameGeometryById,
+    overviewScreens,
+    resolvePngCaptureTarget,
+    selectedScreenIds,
+    viewMode,
+  }: RenderPngBlobArgs,
+  {
+    scope,
+    settings,
+    format = "png",
+  }: {
+    scope: PngCaptureScope;
+    settings?: Partial<ExportSettingsValue>;
+    format?: "png" | "jpg" | "webp";
+  },
+): Promise<Blob> {
+  const html2canvas = (await import("html2canvas")).default;
+  const requestedExportScale =
+    settings?.scale ?? Math.max(2, window.devicePixelRatio || 1);
+  let outputCanvas: HTMLCanvasElement;
+
+  if (
+    scope === "screens" &&
+    viewMode === "overview" &&
+    selectedScreenIds.length > 0
+  ) {
+    const captures = selectedScreenIds
+      .map((screenId, order) => {
+        const iframe = document.querySelector<HTMLIFrameElement>(
+          `iframe[data-design-preview-iframe][data-screen-iframe-id="${CSS.escape(screenId)}"]`,
+        );
+        if (!iframe) throw new PngCaptureError("no-preview");
+        let doc: Document | null = null;
+        try {
+          doc = iframe.contentDocument;
+          if (!doc?.documentElement) doc = null;
+        } catch {
+          doc = null;
+        }
+        if (!doc) {
+          const sourceType =
+            normalizeDesignSourceType(iframe.dataset.designSourceType) ??
+            activeCanvasSourceType;
+          if (sourceType !== "inline") {
+            throw new PngCaptureError("external-preview");
+          }
+          if (!canEditDesign) {
+            throw new PngCaptureError("read-only-preview");
+          }
+          throw new PngCaptureError("no-preview");
+        }
+        const screen = overviewScreens.find(
+          (candidate) => candidate.id === screenId,
+        );
+        const geometry = canvasFrameGeometryById[screenId] ?? {};
+        return {
+          doc,
+          frame: {
+            x: geometry.x ?? order * ((screen?.width ?? 1440) + 80),
+            y: geometry.y ?? 0,
+            width: Math.max(
+              1,
+              geometry.width ?? screen?.width ?? iframe.clientWidth,
+            ),
+            height: Math.max(
+              1,
+              geometry.height ?? screen?.height ?? iframe.clientHeight,
+            ),
+            rotation: geometry.rotation ?? 0,
+          },
+          iframe,
+          order,
+          z: geometry.z ?? order,
+        };
+      })
+      .sort((left, right) => left.z - right.z || left.order - right.order);
+    const bounds = getExportCompositeBounds(
+      captures.map((capture) => capture.frame),
+    );
+    if (!bounds) throw new PngCaptureError("no-preview");
+    const exportScale = resolveRasterExportScale({
+      width: bounds.width,
+      height: bounds.height,
+      requestedScale: requestedExportScale,
+    });
+    outputCanvas = document.createElement("canvas");
+    outputCanvas.width = Math.max(1, Math.ceil(bounds.width * exportScale));
+    outputCanvas.height = Math.max(1, Math.ceil(bounds.height * exportScale));
+    const context = outputCanvas.getContext("2d");
+    if (!context) throw new PngCaptureError("blob-failed");
+
+    for (const capture of captures) {
+      const rendered = await renderExportDocumentCanvas({
+        doc: capture.doc,
+        iframe: capture.iframe,
+        exportScale,
+        render: html2canvas,
+      });
+      const view = capture.doc.defaultView;
+      const viewportCanvas = cropCanvasToRect(
+        rendered.canvas,
+        {
+          x: view?.scrollX ?? 0,
+          y: view?.scrollY ?? 0,
+          width: Math.max(1, capture.iframe.clientWidth),
+          height: Math.max(1, capture.iframe.clientHeight),
+        },
+        rendered.scale,
+      );
+      const frame = capture.frame;
+      context.save();
+      context.translate(
+        (frame.x + frame.width / 2 - bounds.x) * exportScale,
+        (frame.y + frame.height / 2 - bounds.y) * exportScale,
+      );
+      context.rotate(((frame.rotation ?? 0) * Math.PI) / 180);
+      context.drawImage(
+        viewportCanvas ?? rendered.canvas,
+        (-frame.width / 2) * exportScale,
+        (-frame.height / 2) * exportScale,
+        frame.width * exportScale,
+        frame.height * exportScale,
+      );
+      context.restore();
+    }
+  } else {
+    const { cropSelection, doc, iframe } = resolvePngCaptureTarget(scope);
+    const rendered = await renderExportDocumentCanvas({
+      doc,
+      iframe,
+      exportScale: requestedExportScale,
+      render: html2canvas,
+    });
+    const cropRect = resolveExportCropRect(doc, cropSelection);
+    const cropped = cropRect
+      ? cropCanvasToRect(rendered.canvas, cropRect, rendered.scale)
+      : null;
+    // An element capture that silently widens to the whole document is a
+    // preview of something the user did not ask to export, and nothing
+    // downstream can tell it apart from a real one.
+    if (scope === "element" && !cropped) {
+      throw new PngCaptureError("no-preview");
+    }
+    // Render the whole page first, then crop, so ancestor backgrounds show
+    // through every selected frame exactly as they do on screen.
+    outputCanvas = cropped ?? rendered.canvas;
+  }
+  const mimeType =
+    format === "jpg"
+      ? "image/jpeg"
+      : format === "webp"
+        ? "image/webp"
+        : "image/png";
+  return await new Promise<Blob>((resolve, reject) => {
+    outputCanvas.toBlob(
+      (blob) => {
+        if (blob) resolve(blob);
+        else reject(new PngCaptureError("blob-failed"));
+      },
+      mimeType,
+      mimeType === "image/png" ? undefined : 0.95,
+    );
+  });
+}

package/corpus/templates/design/app/pages/design-editor/commands/save-file-content.ts

@@ -0,0 +1,207 @@
+import { useActionMutation } from "@agent-native/core/client/hooks";
+import { sourceContentHash } from "@shared/source-workspace";
+import type { QueryClient } from "@tanstack/react-query";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+
+import type { DesignSaveOutboxEntry } from "@/lib/design-save-outbox";
+import { updateFileResultPersistedContent } from "@/lib/design-save-outbox";
+import type { PatchProofState } from "@/pages/design-editor/command-types";
+import type { FileContentSaveRequest } from "@/pages/design-editor/editor-state";
+import { shouldClearLatestUnloadSave } from "@/pages/design-editor/editor-state";
+import {
+  classifyDesignSaveFailure,
+  designSaveErrorMessage,
+} from "@/pages/design-editor/save-failure";
+
+export interface SaveFileContentArgs {
+  acknowledgeOutboxEntry: (entry: DesignSaveOutboxEntry) => Promise<void>;
+  canEditDesignRef: RefObject<boolean>;
+  createFileSaveOutboxEntry: (
+    pending: FileContentSaveRequest,
+    expectedVersionHash?: string | undefined,
+  ) => DesignSaveOutboxEntry | null;
+  fileSaveChainsRef: RefObject<Record<string, Promise<void>>>;
+  journalOutboxEntry: (entry: DesignSaveOutboxEntry) => Promise<boolean>;
+  lastAckedFileContentHashRef: RefObject<Record<string, string>>;
+  latestFileSaveForUnloadRef: RefObject<Record<string, FileContentSaveRequest>>;
+  markPendingLocalFileContent: (
+    fileId: string,
+    content: string,
+    baseUpdatedAt?: string | null,
+  ) => void;
+  queryClient: QueryClient;
+  setPatchProof: Dispatch<SetStateAction<PatchProofState | null>>;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  updateFileMutation: ReturnType<
+    typeof useActionMutation<undefined, undefined, "update-file">
+  >;
+  warnChangesWillRetry: () => void;
+}
+
+export function runSaveFileContent(
+  {
+    acknowledgeOutboxEntry,
+    canEditDesignRef,
+    createFileSaveOutboxEntry,
+    fileSaveChainsRef,
+    journalOutboxEntry,
+    lastAckedFileContentHashRef,
+    latestFileSaveForUnloadRef,
+    markPendingLocalFileContent,
+    queryClient,
+    setPatchProof,
+    t,
+    updateFileMutation,
+    warnChangesWillRetry,
+  }: SaveFileContentArgs,
+  pending: FileContentSaveRequest,
+) {
+  if (!canEditDesignRef.current) return;
+  markPendingLocalFileContent(pending.id, pending.content);
+  // Stamp the CURRENTLY-known acked hash onto the object kept for the
+  // pagehide/unload keepalive only — that path has no "resolve at send
+  // time" luxury (unload can fire the instant this runs), so best-effort
+  // now is all it gets. Does NOT feed the real mutateAsync call below,
+  // which still re-resolves the hash fresh at send time; see that call's
+  // comment for why an already-set pending.expectedVersionHash must not
+  // be allowed to shadow a fresher ref read there.
+  latestFileSaveForUnloadRef.current[pending.id] =
+    pending.expectedVersionHash !== undefined
+      ? pending
+      : {
+          ...pending,
+          ...(lastAckedFileContentHashRef.current[pending.id]
+            ? {
+                expectedVersionHash:
+                  lastAckedFileContentHashRef.current[pending.id],
+              }
+            : {}),
+        };
+  const queuedOutboxEntry = createFileSaveOutboxEntry(
+    latestFileSaveForUnloadRef.current[pending.id],
+  );
+  if (queuedOutboxEntry) void journalOutboxEntry(queuedOutboxEntry);
+  const previous = fileSaveChainsRef.current[pending.id] ?? Promise.resolve();
+  const current = previous
+    .catch(() => {})
+    .then(async () => {
+      try {
+        // Resolve the optimistic-concurrency hash at SEND time (after any
+        // earlier chained save for this file has landed and refreshed the
+        // acked hash), not at queue time — the freshest ref value always
+        // wins here regardless of anything queue-time code may have
+        // stamped onto `pending` for the unload path above. Attached
+        // whenever a hash is known, on BOTH syncCollab true and false
+        // saves — see lastAckedFileContentHashRef's doc comment. Never
+        // invent a hash when one isn't known yet; omit as before.
+        const expectedVersionHash =
+          lastAckedFileContentHashRef.current[pending.id] ??
+          pending.expectedVersionHash;
+        const outboxEntry = createFileSaveOutboxEntry(
+          pending,
+          expectedVersionHash,
+        );
+        if (outboxEntry) await journalOutboxEntry(outboxEntry);
+        const result = await updateFileMutation.mutateAsync({
+          id: pending.id,
+          content: pending.content,
+          syncCollab: pending.syncCollab,
+          operationSource: pending.operationSource,
+          operationRevision: pending.operationRevision,
+          ...(expectedVersionHash ? { expectedVersionHash } : {}),
+        } as any);
+        const resultInfo = result as
+          | {
+              skippedStaleMirror?: boolean;
+              skippedStaleOperation?: boolean;
+              versionHash?: string;
+            }
+          | undefined;
+        const skippedStaleMirror = Boolean(resultInfo?.skippedStaleMirror);
+        // skippedStaleMirror: the server intentionally left the SQL
+        // mirror column untouched because our expectedVersionHash no
+        // longer matched the live collab text (a live editor moved past
+        // the base this write was computed from). The mirror was NOT
+        // updated to pending.content, so recording pending.content's hash
+        // as "acked" here would be wrong — it would make a later guarded
+        // save believe the server holds content it doesn't. Leave the
+        // previously-acked hash in place instead; the DB-reconcile effect
+        // (activeFile watcher) will pick up the true live content and
+        // refresh the acked hash from that.
+        if (!skippedStaleMirror) {
+          lastAckedFileContentHashRef.current[pending.id] =
+            resultInfo?.versionHash ?? sourceContentHash(pending.content);
+        }
+        const persistedContentMatches = updateFileResultPersistedContent(
+          resultInfo,
+          pending.content,
+        );
+        if (persistedContentMatches && outboxEntry) {
+          await acknowledgeOutboxEntry(outboxEntry);
+        } else if (!persistedContentMatches) {
+          // A stale/no-op save result is a source conflict, not a lost
+          // connection. Refetch below rebases the editor; never promise
+          // that simply reconnecting will save this obsolete snapshot.
+          queryClient.invalidateQueries({
+            queryKey: ["action", "get-design"],
+          });
+        }
+        if (
+          shouldClearLatestUnloadSave(
+            latestFileSaveForUnloadRef.current[pending.id],
+            pending,
+            !persistedContentMatches,
+          )
+        ) {
+          delete latestFileSaveForUnloadRef.current[pending.id];
+        }
+        setPatchProof((prev) =>
+          prev && prev.fileId === pending.id && prev.status === "queued"
+            ? { ...prev, status: "applied" }
+            : prev,
+        );
+      } catch (error) {
+        // Drop the (evidently wrong) acked hash so the failure is
+        // one-shot: the DB-reconcile effect pulls the fresh server
+        // content, and the next save proceeds unguarded from that
+        // rebased state instead of failing forever on a dead hash.
+        delete lastAckedFileContentHashRef.current[pending.id];
+        queryClient.invalidateQueries({
+          queryKey: ["action", "get-design"],
+        });
+        const failureKind = classifyDesignSaveFailure(error, navigator.onLine);
+        if (failureKind === "offline") {
+          warnChangesWillRetry();
+        } else if (
+          failureKind !== "intentional-abort" &&
+          failureKind !== "conflict"
+        ) {
+          // Conflicts already rebased above (acked-hash reset + get-design
+          // invalidation); a red toast for a routine rebase is just noise.
+          toast.error(
+            designSaveErrorMessage(error) ?? t("common.genericError"),
+            { id: `design-save-error:${pending.id}` },
+          );
+        }
+        setPatchProof((prev) =>
+          prev && prev.fileId === pending.id && prev.status === "queued"
+            ? {
+                ...prev,
+                status: "failed",
+                error:
+                  error instanceof Error
+                    ? error.message
+                    : t("common.genericError"),
+              }
+            : prev,
+        );
+      }
+    });
+  fileSaveChainsRef.current[pending.id] = current;
+  void current.finally(() => {
+    if (fileSaveChainsRef.current[pending.id] === current) {
+      delete fileSaveChainsRef.current[pending.id];
+    }
+  });
+}

package/corpus/templates/design/app/pages/design-editor/commands/screen-element-select.ts

@@ -0,0 +1,262 @@
+import type { CodeLayerProjection } from "@shared/code-layer";
+import {
+  applyVisualEdit,
+  ensureCodeLayerNodeIdsInHtml,
+} from "@shared/code-layer";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+
+import type {
+  ElementInfo,
+  ElementSelectionIntent,
+} from "@/components/design/types";
+import type { ClipboardContentMutationPublication } from "@/lib/clipboard-content-lineage";
+import {
+  canonicalizeElementInfoFromProjection,
+  resolveCodeLayerNodeFromElementInfo,
+} from "@/pages/design-editor/code-layer-state";
+import {
+  dedupeStringIds,
+  isScreenRootElementInfo,
+  shouldIgnoreOverviewLayerCreationEcho,
+} from "@/pages/design-editor/selection-state";
+import type { DesignTool, EditorMode } from "@/pages/design-editor/types";
+
+export interface ScreenElementSelectArgs {
+  activeBreakpointWidthStateRef: RefObject<number | undefined>;
+  applyFileContentUpdate: (
+    fileId: string,
+    nextContent: string,
+    options?: {
+      refreshPreview?: boolean;
+      skipPreview?: boolean;
+      forcePreviewFullDocument?: boolean;
+      persist?: boolean;
+      recordHistory?: boolean;
+      updatedAt?: string;
+      clipboardMutation?: ClipboardContentMutationPublication;
+    },
+  ) => void;
+  clearPendingOverviewLayerSelectionTimer: () => void;
+  focusDesignInspectorForSelection: () => void;
+  getCodeLayerProjectionForScreen: (
+    screenId: string,
+  ) => CodeLayerProjection | null;
+  getScreenContent: (screenId: string) => string;
+  handleBreakpointBarSelect: (widthPx: number | undefined) => void;
+  id: string | undefined;
+  pendingOverviewLayerSelectionRef: RefObject<string | null>;
+  pendingOverviewScreenSelectionRef: RefObject<string | null>;
+  selectedLayerIdsState: string[];
+  setActiveFileId: Dispatch<SetStateAction<string | null>>;
+  setActiveTool: Dispatch<SetStateAction<DesignTool>>;
+  setCreatedOverviewLayerSelection: Dispatch<
+    SetStateAction<{ screenId: string; layerId: string } | null>
+  >;
+  setHoveredElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setHoveredElementScreenId: Dispatch<SetStateAction<string | null>>;
+  setMode: Dispatch<SetStateAction<EditorMode>>;
+  setOverviewSelectedScreenIds: Dispatch<SetStateAction<string[]>>;
+  setSelectedElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setSelectedLayerIdsState: Dispatch<SetStateAction<string[]>>;
+  shouldPreserveBlockedOverviewLayerSelectionRef: RefObject<
+    (screenId: string) => boolean
+  >;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  viewModeRef: RefObject<"single" | "overview">;
+}
+
+export function runScreenElementSelect(
+  {
+    activeBreakpointWidthStateRef,
+    applyFileContentUpdate,
+    clearPendingOverviewLayerSelectionTimer,
+    focusDesignInspectorForSelection,
+    getCodeLayerProjectionForScreen,
+    getScreenContent,
+    handleBreakpointBarSelect,
+    id,
+    pendingOverviewLayerSelectionRef,
+    pendingOverviewScreenSelectionRef,
+    selectedLayerIdsState,
+    setActiveFileId,
+    setActiveTool,
+    setCreatedOverviewLayerSelection,
+    setHoveredElement,
+    setHoveredElementScreenId,
+    setMode,
+    setOverviewSelectedScreenIds,
+    setSelectedElement,
+    setSelectedLayerIdsState,
+    shouldPreserveBlockedOverviewLayerSelectionRef,
+    t,
+    viewModeRef,
+  }: ScreenElementSelectArgs,
+  screenId: string,
+  info: ElementInfo,
+  intent?: ElementSelectionIntent,
+  options: {
+    persistPendingNodeId?: boolean;
+    breakpointWidthPx?: number;
+  } = {},
+) {
+  const pendingLayerId = pendingOverviewLayerSelectionRef.current;
+  const pendingScreenId = pendingOverviewScreenSelectionRef.current;
+  const projection = getCodeLayerProjectionForScreen(screenId);
+  const canonical = projection
+    ? canonicalizeElementInfoFromProjection(projection, info)
+    : info;
+  const node = projection
+    ? resolveCodeLayerNodeFromElementInfo(projection, canonical)
+    : null;
+  if (
+    shouldIgnoreOverviewLayerCreationEcho({
+      pendingLayerId,
+      pendingScreenId,
+      screenId,
+      info: canonical,
+      resolvedLayerId: node?.id,
+      event: "select",
+    })
+  ) {
+    return;
+  }
+  pendingOverviewScreenSelectionRef.current = null;
+  pendingOverviewLayerSelectionRef.current = null;
+  clearPendingOverviewLayerSelectionTimer();
+  setCreatedOverviewLayerSelection(null);
+  if (
+    shouldPreserveBlockedOverviewLayerSelectionRef.current(screenId) &&
+    (isScreenRootElementInfo(canonical) ||
+      !node ||
+      selectedLayerIdsState.includes(node.id))
+  ) {
+    return;
+  }
+  // Node-id integrity (id-on-demand): AI-generated/duplicated screens
+  // frequently ship elements with a missing or empty-string
+  // `data-agent-native-node-id` — every id-keyed operation on that
+  // element (move/reorder, style commits that resolve a targetNode,
+  // motion tracks, scrub) then silently no-ops or throws "Node with
+  // data-agent-native-node-id=\"\" not found in sourceHtml". The bridge
+  // (editor-chrome.bridge.ts's getElementInfo) mints a durable
+  // `pendingNodeId` on the SELECTION payload whenever it can't resolve a
+  // stable id for the element (`!sourceId`) and exposes it as
+  // `canonical.pendingNodeId`; persist it as the element's real
+  // `data-agent-native-node-id` right now via the same deterministic,
+  // guarded write path every other edit uses (applyVisualEdit's new
+  // "attribute" intent + applyFileContentUpdate), so every subsequent
+  // id-keyed op against this element resolves normally afterward. This is
+  // more reliable than resolving through the host's own static-HTML
+  // projection (`node`, below) — the bridge already knows the live DOM
+  // element and its working selector candidates even when the host's
+  // positional-selector projection match drifts.
+  const pendingNodeId = (canonical as { pendingNodeId?: string }).pendingNodeId;
+  if (
+    options.persistPendingNodeId !== false &&
+    !isScreenRootElementInfo(canonical) &&
+    pendingNodeId &&
+    !canonical.sourceId &&
+    canonical.selector
+  ) {
+    const rawContent = getScreenContent(screenId);
+    if (rawContent) {
+      const result = applyVisualEdit(
+        rawContent,
+        {
+          kind: "attribute",
+          target: { selector: canonical.selector },
+          name: "data-agent-native-node-id",
+          value: pendingNodeId,
+        },
+        {
+          source: { kind: "design-file", designId: id, fileId: screenId },
+        },
+      );
+      if (result.result.status === "applied" && result.content !== rawContent) {
+        applyFileContentUpdate(screenId, result.content, {
+          recordHistory: false,
+        });
+      }
+    }
+  } else if (
+    options.persistPendingNodeId !== false &&
+    // Fallback sweep: an element the bridge didn't mint a pendingNodeId
+    // for (older bridge instance, or a node resolved only through the
+    // host's own projection) but that still lacks a stable id per the
+    // host's own projection match. Runs the whole-document stamp helper
+    // so any other id-less siblings pick up ids in the same pass too.
+    !isScreenRootElementInfo(canonical) &&
+    node &&
+    !node.dataAttributes["data-agent-native-node-id"]?.trim()
+  ) {
+    const rawContent = getScreenContent(screenId);
+    if (rawContent) {
+      const stamped = ensureCodeLayerNodeIdsInHtml(rawContent, {
+        source: { kind: "design-file", designId: id, fileId: screenId },
+      });
+      if (stamped.changed && stamped.content !== rawContent) {
+        applyFileContentUpdate(screenId, stamped.content, {
+          recordHistory: false,
+        });
+      }
+    }
+  }
+  // Known limitation: elements rendered from a `<template x-for>`
+  // repeater (common in AI-generated Alpine.js list/task UIs) have no
+  // per-instance static DOM node in the SOURCE HTML at all — neither
+  // resolveCodeLayerNodeFromElementInfo nor a selector-based
+  // applyVisualEdit resolution can find a unique per-instance node to
+  // stamp. Fixing that requires the code-layer projection itself to
+  // model `<template>` repeater children as selectable/attributable
+  // nodes, which is out of scope for this selection-time fix.
+  const additiveSelection = Boolean(
+    node &&
+    (intent?.additive ||
+      intent?.range ||
+      intent?.shiftKey ||
+      intent?.metaKey ||
+      intent?.ctrlKey),
+  );
+  setActiveFileId(screenId);
+  setSelectedElement(canonical);
+  setHoveredElement(null);
+  setHoveredElementScreenId(null);
+  if (node && additiveSelection) {
+    setSelectedLayerIdsState((current) => {
+      const removeExisting =
+        Boolean(intent?.metaKey || intent?.ctrlKey) &&
+        !intent?.shiftKey &&
+        current.includes(node.id);
+      if (removeExisting) {
+        const next = current.filter((layerId) => layerId !== node.id);
+        return next.length > 0 ? next : [node.id];
+      }
+      return dedupeStringIds([...current, node.id]);
+    });
+  } else {
+    setSelectedLayerIdsState(node ? [node.id] : []);
+  }
+  if (viewModeRef.current === "overview") {
+    setOverviewSelectedScreenIds([]);
+    // A responsive sub-frame now owns a full editor bridge, so selection
+    // carries its exact width into the edit scope. Primary-frame clicks
+    // still return to Base. This prevents two identical selectors in the
+    // base and responsive runtimes from racing for one global scope.
+    if (options.breakpointWidthPx !== undefined) {
+      handleBreakpointBarSelect(options.breakpointWidthPx);
+      const guidanceKey = `design-responsive-edit-guidance:${id}:${screenId}`;
+      if (window.localStorage.getItem(guidanceKey) !== "shown") {
+        window.localStorage.setItem(guidanceKey, "shown");
+        toast.info(t("designEditor.breakpointBar.scope.firstEditGuidance"), {
+          duration: 6000,
+        });
+      }
+    } else if (activeBreakpointWidthStateRef.current !== undefined) {
+      handleBreakpointBarSelect(undefined);
+    }
+  }
+  setActiveTool("move");
+  setMode("edit");
+  focusDesignInspectorForSelection();
+}