@agent-native/core 0.163.3 → 0.164.1

package/corpus/templates/design/app/pages/design-editor/commands/pasted-image-files.ts

@@ -0,0 +1,209 @@
+import type { CanvasFrameGeometryById } from "@shared/canvas-frames";
+import type { RefObject } from "react";
+import { toast } from "sonner";
+
+import type { ClipboardContentMutationPublication } from "@/lib/clipboard-content-lineage";
+import { uniqueLayerId } from "@/pages/design-editor/canvas-primitive-insert";
+import { cloneHtmlLayerAtPosition } from "@/pages/design-editor/clone-and-pen-edit";
+import type { OverviewScreen } from "@/pages/design-editor/derive/overview-screens";
+import { escapeHtmlAttributeValue } from "@/pages/design-editor/dom-utils";
+import {
+  findScreenFrameAtCanvasPoint,
+  getAllScreenFrameEntries,
+} from "@/pages/design-editor/overview-camera";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface PastedImageFilesTarget {
+  fileId: string;
+  point: { x: number; y: number };
+}
+
+export interface PastedImageFilesArgs {
+  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;
+  boardFileId: string | undefined;
+  canEditDesign: boolean;
+  canvasContainerRef: RefObject<HTMLDivElement | null>;
+  canvasFrameGeometryById: CanvasFrameGeometryById;
+  getFreshActiveContent: () => string;
+  getScreenContent: (screenId: string) => string;
+  overviewScreens: OverviewScreen[];
+  overviewSelectedScreenIds: string[];
+  pasteCascadeRef: RefObject<number>;
+  selectInsertedLayers: (
+    screenId: string,
+    content: string,
+    rootNodeIds: string[],
+  ) => void;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  uploadImageFileForHtml: (file: File) => Promise<string>;
+  viewModeRef: RefObject<"single" | "overview">;
+  zoom: number;
+}
+
+export function runPastedImageFiles(
+  {
+    activeFile,
+    applyFileContentUpdate,
+    applyLocalContentUpdate,
+    boardFileId,
+    canEditDesign,
+    canvasContainerRef,
+    canvasFrameGeometryById,
+    getFreshActiveContent,
+    getScreenContent,
+    overviewScreens,
+    overviewSelectedScreenIds,
+    pasteCascadeRef,
+    selectInsertedLayers,
+    t,
+    uploadImageFileForHtml,
+    viewModeRef,
+    zoom,
+  }: PastedImageFilesArgs,
+  files: File[],
+  target?: PastedImageFilesTarget,
+) {
+  if (files.length === 0 || !canEditDesign) return false;
+
+  const insertFilesAtPoint = (
+    targetFileId: string,
+    localPoint: { x: number; y: number } | (() => { x: number; y: number }),
+  ) => {
+    void (async () => {
+      for (const file of files) {
+        const imageUrl = await uploadImageFileForHtml(file);
+        if (!imageUrl) continue;
+        const baseContent =
+          targetFileId === activeFile?.id
+            ? getFreshActiveContent()
+            : (getScreenContent(targetFileId) ?? "");
+        const resolvedPoint =
+          typeof localPoint === "function" ? localPoint() : localPoint;
+        const cascadeOffset = pasteCascadeRef.current * 16;
+        pasteCascadeRef.current += 1;
+        const nodeId = uniqueLayerId("pasted-image");
+        const html = `<img src="${imageUrl}" alt="${escapeHtmlAttributeValue(file.name || "Pasted image")}" data-agent-native-node-id="${nodeId}" data-agent-native-layer-name="Pasted image" style="position:absolute;width:320px;height:auto;" />`;
+        const nextContent = cloneHtmlLayerAtPosition(baseContent, html, {
+          x: resolvedPoint.x + cascadeOffset,
+          y: resolvedPoint.y + cascadeOffset,
+        });
+        if (!nextContent) {
+          toast.error(t("designEditor.toasts.duplicateElementFailed"));
+          continue;
+        }
+        if (targetFileId === activeFile?.id) {
+          applyLocalContentUpdate(nextContent, {
+            forcePreviewFullDocument: true,
+          });
+        } else {
+          applyFileContentUpdate(targetFileId, nextContent, {
+            forcePreviewFullDocument: true,
+          });
+        }
+        selectInsertedLayers(targetFileId, nextContent, [nodeId]);
+      }
+    })();
+  };
+
+  if (target) {
+    insertFilesAtPoint(target.fileId, target.point);
+    return true;
+  }
+
+  if (viewModeRef.current !== "overview") {
+    const targetFileId = activeFile?.id;
+    if (!targetFileId) return false;
+    const getCenter = () => {
+      const iframe = canvasContainerRef.current?.querySelector<HTMLElement>(
+        "[data-design-preview-iframe]",
+      );
+      if (iframe) {
+        const iframeRect = iframe.getBoundingClientRect();
+        const factor = zoom / 100;
+        return {
+          x: Math.max(0, iframeRect.width / 2 / factor),
+          y: Math.max(0, iframeRect.height / 2 / factor),
+        };
+      }
+      const rect = canvasContainerRef.current?.getBoundingClientRect();
+      return rect
+        ? {
+            x: Math.max(0, rect.width / 2),
+            y: Math.max(0, rect.height / 2),
+          }
+        : { x: 120, y: 120 };
+    };
+    insertFilesAtPoint(targetFileId, getCenter);
+    return true;
+  }
+
+  // Overview mode: resolve a canvas-space anchor point, then hit-test it
+  // against real screen frames.
+  if (!boardFileId) return false;
+  const frames = getAllScreenFrameEntries({
+    overviewScreens,
+    canvasFrameGeometryById,
+  });
+  const anchorCanvasPoint = (() => {
+    if (overviewSelectedScreenIds.length === 1) {
+      const screenId = overviewSelectedScreenIds[0]!;
+      const frame = frames.find((entry) => entry.id === screenId);
+      if (frame) {
+        return {
+          x: frame.geometry.x + frame.geometry.width / 2,
+          y: frame.geometry.y + frame.geometry.height / 2,
+        };
+      }
+    }
+    // Best-effort fallback (matches the prior single-image behavior):
+    // container-relative pixels as a stand-in canvas point. Overview pan/
+    // zoom camera state lives inside MultiScreenCanvas, not here, so this
+    // can't account for the live camera transform — see FINAL REPORT.
+    const rect = canvasContainerRef.current?.getBoundingClientRect();
+    return rect
+      ? { x: Math.max(0, rect.width / 2), y: Math.max(0, rect.height / 2) }
+      : { x: 120, y: 120 };
+  })();
+  const hitFrame = findScreenFrameAtCanvasPoint(
+    anchorCanvasPoint,
+    frames,
+    boardFileId,
+  );
+  const targetFileId = hitFrame?.id ?? boardFileId;
+  const localAnchor = hitFrame
+    ? {
+        x: anchorCanvasPoint.x - hitFrame.geometry.x,
+        y: anchorCanvasPoint.y - hitFrame.geometry.y,
+      }
+    : anchorCanvasPoint;
+
+  insertFilesAtPoint(targetFileId, localAnchor);
+  return true;
+}

package/corpus/templates/design/app/pages/design-editor/commands/persist-frame-geometry-save.ts

@@ -0,0 +1,113 @@
+import { tryCallActionKeepalive } from "@agent-native/core/client/hooks";
+import type { CanvasFrameGeometryById } from "@shared/canvas-frames";
+import type { QueryClient } from "@tanstack/react-query";
+import type { RefObject } from "react";
+
+import type { DesignSaveOutboxEntry } from "@/lib/design-save-outbox";
+import type {
+  DesignDataOperation,
+  PendingDesignDataOperations,
+} from "@/pages/design-editor/data-operations";
+import {
+  applyDesignDataOperations,
+  buildFrameGeometryDataOperations,
+  compactDesignDataOperations,
+  pendingDesignDataOperations,
+} from "@/pages/design-editor/data-operations";
+import { sanitizeCanvasFrameGeometryForPersist } from "@/pages/design-editor/geometry-persistence";
+
+export interface PersistFrameGeometrySaveArgs {
+  acknowledgeOutboxEntry: (entry: DesignSaveOutboxEntry) => Promise<void>;
+  boardFileId: string | undefined;
+  canEditDesignRef: RefObject<boolean>;
+  createFrameGeometryOutboxEntry: (
+    dataOperations: readonly DesignDataOperation[],
+    revision: number,
+  ) => DesignSaveOutboxEntry | null;
+  designDataJsonRef: RefObject<Record<string, unknown>>;
+  enqueueFrameGeometryDataSave: (
+    dataOperations: DesignDataOperation[],
+  ) => boolean;
+  frameGeometryOperationRevisionRef: RefObject<number>;
+  id: string | undefined;
+  journalOutboxEntry: (entry: DesignSaveOutboxEntry) => Promise<boolean>;
+  pendingFrameGeometryOperationsForUnloadRef: RefObject<PendingDesignDataOperations>;
+  queryClient: QueryClient;
+  warnChangesWillRetry: () => void;
+}
+
+export function runPersistFrameGeometrySave(
+  {
+    acknowledgeOutboxEntry,
+    boardFileId,
+    canEditDesignRef,
+    createFrameGeometryOutboxEntry,
+    designDataJsonRef,
+    enqueueFrameGeometryDataSave,
+    frameGeometryOperationRevisionRef,
+    id,
+    journalOutboxEntry,
+    pendingFrameGeometryOperationsForUnloadRef,
+    queryClient,
+    warnChangesWillRetry,
+  }: PersistFrameGeometrySaveArgs,
+  pending: {
+    geometryById: CanvasFrameGeometryById;
+    previousGeometry: CanvasFrameGeometryById;
+  },
+  keepalive = false,
+): boolean {
+  if (!id || !canEditDesignRef.current) return false;
+  // Geometry-persist guard: refuse absurd per-frame geometry (see
+  // sanitizeCanvasFrameGeometryForPersist) so a corrupted transient
+  // zoom basis can never shred the persisted layout. The board frame
+  // is exempt — its surface is a legitimate 131k square.
+  const { geometryById: safeGeometryById } =
+    sanitizeCanvasFrameGeometryForPersist(
+      pending.geometryById,
+      pending.previousGeometry,
+      boardFileId ? [boardFileId] : [],
+    );
+  const dataOperations = buildFrameGeometryDataOperations({
+    previousGeometry: pending.previousGeometry,
+    nextGeometry: safeGeometryById,
+    designData: designDataJsonRef.current,
+  });
+  if (keepalive) {
+    const combinedOperations = compactDesignDataOperations([
+      ...pendingDesignDataOperations(
+        pendingFrameGeometryOperationsForUnloadRef.current,
+      ),
+      ...dataOperations,
+    ]);
+    if (combinedOperations.length === 0) return true;
+    const operationRevision = frameGeometryOperationRevisionRef.current + 1;
+    frameGeometryOperationRevisionRef.current = operationRevision;
+    const entry = createFrameGeometryOutboxEntry(
+      combinedOperations,
+      operationRevision,
+    );
+    if (!entry) return false;
+    void journalOutboxEntry(entry);
+    const attempt = tryCallActionKeepalive(
+      "update-design",
+      entry.payload as any,
+    );
+    if (!attempt.accepted) return false;
+    void attempt.completion
+      .then(() => acknowledgeOutboxEntry(entry))
+      .catch(warnChangesWillRetry);
+    return true;
+  }
+  if (dataOperations.length === 0) return true;
+  const nextData = applyDesignDataOperations(
+    designDataJsonRef.current,
+    dataOperations,
+  );
+  designDataJsonRef.current = nextData;
+  queryClient.setQueryData(["action", "get-design", { id }], (old: any) => {
+    if (!old || typeof old !== "object") return old;
+    return { ...old, data: JSON.stringify(nextData) };
+  });
+  return enqueueFrameGeometryDataSave(dataOperations);
+}

package/corpus/templates/design/app/pages/design-editor/commands/persist-tweak-save.ts

@@ -0,0 +1,160 @@
+import { useActionMutation } from "@agent-native/core/client/hooks";
+import { tweakSelectionsHash } from "@shared/resolve-tweaks";
+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 type { PendingTweakSave } from "@/pages/design-editor/tweak-save";
+import {
+  classifyTweakSaveFailure,
+  clearCompletedTweakSave,
+  rebaseTweakSaveForSend,
+  retainLatestFailedTweakSave,
+} from "@/pages/design-editor/tweak-save";
+
+export interface PersistTweakSaveArgs {
+  acknowledgeOutboxEntry: (entry: DesignSaveOutboxEntry) => Promise<void>;
+  applyTweaksAsync: ReturnType<
+    typeof useActionMutation<undefined, undefined, "apply-tweaks">
+  >["mutateAsync"];
+  canEditDesignRef: RefObject<boolean>;
+  confirmedTweakSelectionsHashRef: RefObject<string>;
+  createTweakSaveOutboxEntry: (
+    pending: PendingTweakSave,
+  ) => DesignSaveOutboxEntry | null;
+  id: string | undefined;
+  journalTweakOutboxEntry: (entry: DesignSaveOutboxEntry) => Promise<boolean>;
+  pendingTweakSaveRef: RefObject<PendingTweakSave | null>;
+  queryClient: QueryClient;
+  setTweakSaveActive: Dispatch<SetStateAction<boolean>>;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  tweakSaveChainRef: RefObject<Promise<void>>;
+  tweakSaveInFlightRef: RefObject<boolean>;
+  tweakSaveRevisionRef: RefObject<number>;
+  warnChangesWillRetry: () => void;
+}
+
+export function runPersistTweakSave(
+  {
+    acknowledgeOutboxEntry,
+    applyTweaksAsync,
+    canEditDesignRef,
+    confirmedTweakSelectionsHashRef,
+    createTweakSaveOutboxEntry,
+    id,
+    journalTweakOutboxEntry,
+    pendingTweakSaveRef,
+    queryClient,
+    setTweakSaveActive,
+    t,
+    tweakSaveChainRef,
+    tweakSaveInFlightRef,
+    tweakSaveRevisionRef,
+    warnChangesWillRetry,
+  }: PersistTweakSaveArgs,
+  pending: PendingTweakSave,
+) {
+  if (!id || !canEditDesignRef.current) return;
+  const previous = tweakSaveChainRef.current;
+  const current = previous
+    .catch(() => {})
+    .then(async () => {
+      tweakSaveInFlightRef.current = true;
+      const sendPending = rebaseTweakSaveForSend(
+        pending,
+        confirmedTweakSelectionsHashRef.current,
+      );
+      const entry = createTweakSaveOutboxEntry(sendPending);
+      if (!entry) {
+        tweakSaveInFlightRef.current = false;
+        return;
+      }
+      const journaled = await journalTweakOutboxEntry(entry);
+      try {
+        const result = (await applyTweaksAsync(entry.payload as any)) as {
+          appliedTweaks?: Record<string, unknown>;
+          selectionsHash?: string;
+        };
+        const confirmedHash =
+          typeof result?.selectionsHash === "string"
+            ? result.selectionsHash
+            : tweakSelectionsHash(
+                result?.appliedTweaks ?? sendPending.selections,
+              );
+        confirmedTweakSelectionsHashRef.current = confirmedHash;
+        if (result?.appliedTweaks) {
+          queryClient.setQueryData(
+            ["action", "get-design", { id }],
+            (old: any) => {
+              if (!old || typeof old !== "object") return old;
+              let data: Record<string, unknown>;
+              try {
+                const parsed = JSON.parse(old.data ?? "{}");
+                data =
+                  parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                    ? parsed
+                    : {};
+              } catch {
+                return old;
+              }
+              return {
+                ...old,
+                data: JSON.stringify({
+                  ...data,
+                  tweakSelections: result.appliedTweaks,
+                }),
+              };
+            },
+          );
+        }
+        if (journaled) await acknowledgeOutboxEntry(entry);
+
+        const queuedAfterSuccess = clearCompletedTweakSave(
+          pendingTweakSaveRef.current,
+          pending.revision,
+        );
+        if (
+          queuedAfterSuccess &&
+          queuedAfterSuccess.revision > pending.revision
+        ) {
+          const rebasedQueued = rebaseTweakSaveForSend(
+            queuedAfterSuccess,
+            confirmedHash,
+          );
+          pendingTweakSaveRef.current = rebasedQueued;
+          const rebasedEntry = createTweakSaveOutboxEntry(rebasedQueued);
+          if (rebasedEntry) void journalTweakOutboxEntry(rebasedEntry);
+        } else {
+          pendingTweakSaveRef.current = queuedAfterSuccess;
+        }
+        if (tweakSaveRevisionRef.current === pending.revision) {
+          setTweakSaveActive(false);
+        }
+      } catch (error) {
+        pendingTweakSaveRef.current = retainLatestFailedTweakSave(
+          pendingTweakSaveRef.current,
+          sendPending,
+        );
+        if (tweakSaveRevisionRef.current === pending.revision) {
+          setTweakSaveActive(true);
+        }
+        const failureKind = classifyTweakSaveFailure(error, journaled);
+        if (failureKind === "conflict") {
+          toast.error(t("designEditor.toasts.tweakConflict"));
+        } else if (failureKind === "durable-retry") {
+          warnChangesWillRetry();
+        } else {
+          toast.error(t("designEditor.toasts.tweakSaveNotDurable"));
+        }
+      } finally {
+        tweakSaveInFlightRef.current = false;
+      }
+    });
+  tweakSaveChainRef.current = current;
+  void current.finally(() => {
+    if (tweakSaveChainRef.current === current) {
+      tweakSaveChainRef.current = Promise.resolve();
+    }
+  });
+}

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

@@ -0,0 +1,168 @@
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { flushSync } from "react-dom";
+
+import type { ElementInfo } from "@/components/design/types";
+import {
+  isTextEditSessionOutcome,
+  scheduleBeginTextEditForScreen,
+} from "@/pages/design-editor/text-edit-utils";
+import type { DesignTool, EditorMode } from "@/pages/design-editor/types";
+
+export interface PrimitiveCreatedArgs {
+  boardFileId: string | undefined;
+  clearPendingOverviewLayerSelectionTimer: () => void;
+  pendingEmptyTextEditRef: RefObject<{
+    screenId: string | null;
+    nodeId: string;
+    cancel: () => void;
+    settled: boolean;
+  } | null>;
+  pendingOverviewLayerSelectionRef: RefObject<string | null>;
+  pendingOverviewScreenSelectionRef: RefObject<string | null>;
+  pendingTextEditNodeIdRef: RefObject<string | null>;
+  removeEmptyTextNodeWithRetry: (
+    screenId: string | null,
+    nodeId: string,
+  ) => void;
+  setActiveFileId: Dispatch<SetStateAction<string | null>>;
+  setActiveTool: Dispatch<SetStateAction<DesignTool>>;
+  setCreatedOverviewLayerSelection: Dispatch<
+    SetStateAction<{ screenId: string; layerId: string } | null>
+  >;
+  setHoveredElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setMode: Dispatch<SetStateAction<EditorMode>>;
+  setOverviewSelectedScreenIds: Dispatch<SetStateAction<string[]>>;
+  setSelectedElement: Dispatch<SetStateAction<ElementInfo | null>>;
+  setSelectedLayerIdsState: Dispatch<SetStateAction<string[]>>;
+}
+
+export function runPrimitiveCreated(
+  {
+    boardFileId,
+    clearPendingOverviewLayerSelectionTimer,
+    pendingEmptyTextEditRef,
+    pendingOverviewLayerSelectionRef,
+    pendingOverviewScreenSelectionRef,
+    pendingTextEditNodeIdRef,
+    removeEmptyTextNodeWithRetry,
+    setActiveFileId,
+    setActiveTool,
+    setCreatedOverviewLayerSelection,
+    setHoveredElement,
+    setMode,
+    setOverviewSelectedScreenIds,
+    setSelectedElement,
+    setSelectedLayerIdsState,
+  }: PrimitiveCreatedArgs,
+  screenId: string,
+  nodeId: string,
+  options?: {
+    nextTool?: "move" | "pen";
+    preserveActiveTool?: boolean;
+  },
+) {
+  // B2/B4 fix: stay in overview mode after drawing a primitive.  The user
+  // drew a shape on the board — they should remain on the board with the
+  // new primitive selected, matching Figma behaviour.  We activate the
+  // target screen (so the layers panel shows its content) and select the
+  // new node, but do NOT switch to single/full view.
+  //
+  // Board guard (overview-zoom corruption fix): the board file is NOT a
+  // screen — it never appears in `overviewScreens` and has no
+  // `canvasFrames` entry, so activating it flipped the overview zoom
+  // basis onto double-fallback inputs (scale snapped to 0.25) while
+  // `explicitOverviewCanvasZoom` stayed pinned to the previous screen's
+  // scale — the displayed zoom showed garbage (observed: 10241.49%).
+  // For a board-created primitive we still select the node and honor the
+  // pending text-edit intent below (both are screen-id scoped and work
+  // for the board), but keep the previous active FILE and never put the
+  // board id into the overview screen-frame selection.
+  const isBoardTarget = Boolean(boardFileId && screenId === boardFileId);
+  pendingOverviewScreenSelectionRef.current = null;
+  pendingOverviewLayerSelectionRef.current = nodeId;
+  clearPendingOverviewLayerSelectionTimer();
+  flushSync(() => {
+    setCreatedOverviewLayerSelection({ screenId, layerId: nodeId });
+    if (!isBoardTarget) {
+      setActiveFileId(screenId);
+    }
+    setSelectedElement(null);
+    setHoveredElement(null);
+    setSelectedLayerIdsState([nodeId]);
+    // The new node is the selection; leaving its parent frame selected too
+    // hands Cmd+D and alt-drag to the screen-level duplicate instead.
+    setOverviewSelectedScreenIds([]);
+    if (!options?.preserveActiveTool) {
+      setActiveTool(options?.nextTool ?? "move");
+    }
+    setMode("edit");
+  });
+  // viewMode stays at "overview" — no setViewMode("single") call here.
+
+  // Immediately enter text-editing for newly created TEXT primitives. In
+  // overview mode the target iframe may become active and receive the
+  // inserted HTML over separate renders, so post directly to the target
+  // iframe with a few short retries instead of relying on a single global
+  // bridge callback.
+  const textNodeId = pendingTextEditNodeIdRef.current;
+  pendingTextEditNodeIdRef.current = null;
+  if (textNodeId) {
+    // Cancel any still-pending retry loop from a PREVIOUS text primitive
+    // (e.g. the user drew a second text box before the first one settled)
+    // before starting a new one, so stale timers can't fight over which
+    // node to clean up.
+    pendingEmptyTextEditRef.current?.cancel();
+    // Creation-race fast path: the retry loop below fires its FIRST
+    // begin-text-edit attempt at 180ms and its status-query round trips
+    // can leave a multi-second window where keystrokes still hit HOST
+    // shortcuts (Delete deleted the just-created text layer). The
+    // DesignCanvas runtime bridge's beginTextEdit (registered as
+    // window.__designCanvasBeginTextEdit by the active surface's canvas
+    // — the flushSync above just pointed activeFileId at this screenId
+    // for non-board targets) queues begin-text-edit through the
+    // bridge-ready one-shot queue AND arms the host keystroke buffer
+    // SYNCHRONOUSLY, so typing is captured from the very first keydown.
+    // Activation itself waits until the pointer gesture's trailing click:
+    // focusing during mouseup lets that click blur the empty editable one
+    // frame later, producing the visible caret blink and losing typing.
+    // Best-effort only: if the registered bridge still belongs to a
+    // different surface, its iframe no-ops on the unknown nodeId while
+    // the buffer still swallows destructive shortcuts, and the
+    // screen-id-scoped scheduleBeginTextEditForScreen loop below remains
+    // the authoritative per-iframe fallback (resolved through
+    // findCanvasIframeForScreen, so board-space text works too).
+    if (typeof window !== "undefined") {
+      const beginTextEditNow = (window as any).__designCanvasBeginTextEdit;
+      if (typeof beginTextEditNow === "function") {
+        beginTextEditNow(textNodeId, { afterPointerGesture: true });
+      }
+    }
+    const cancel = scheduleBeginTextEditForScreen(screenId, textNodeId, {
+      boardFileId,
+      onExhausted: (finalStatus) => {
+        const pending = pendingEmptyTextEditRef.current;
+        if (!pending || pending.nodeId !== textNodeId || pending.settled) {
+          return;
+        }
+        pending.settled = true;
+        if (isTextEditSessionOutcome(finalStatus)) return;
+        if (finalStatus === "no-iframe" || finalStatus === "no-reply") {
+          // Never reached an editing surface at all. That is a targeting
+          // defect, not the user declining to type, so make it audible —
+          // but the persisted document, not this outcome, still decides
+          // whether the node is empty and should go.
+          console.warn(
+            `[design] text edit never reached a surface for ${screenId}/${textNodeId} (${finalStatus})`,
+          );
+        }
+        removeEmptyTextNodeWithRetry(screenId, textNodeId);
+      },
+    });
+    pendingEmptyTextEditRef.current = {
+      screenId,
+      nodeId: textNodeId,
+      cancel,
+      settled: false,
+    };
+  }
+}