@agent-native/core 0.163.4 → 0.164.3

package/corpus/templates/design/app/pages/design-editor/commands/confirm-make-real.ts

@@ -0,0 +1,99 @@
+import { useActionMutation } from "@agent-native/core/client/hooks";
+import type { QueryClient } from "@tanstack/react-query";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+
+import type { DesignMigrationResult } from "@/components/design/editor/MakeRealDialog";
+import type { DesignDataOperation } from "@/pages/design-editor/data-operations";
+import { applyDesignDataOperations } from "@/pages/design-editor/data-operations";
+
+export interface ConfirmMakeRealArgs {
+  designDataJsonRef: RefObject<Record<string, unknown>>;
+  id: string | undefined;
+  migrateMutation: ReturnType<
+    typeof useActionMutation<
+      undefined,
+      undefined,
+      "migrate-inline-design-to-app"
+    >
+  >;
+  queryClient: QueryClient;
+  setMigrationResult: Dispatch<SetStateAction<DesignMigrationResult | null>>;
+  updateDesignMutation: ReturnType<
+    typeof useActionMutation<undefined, undefined, "update-design">
+  >;
+}
+
+export async function runConfirmMakeReal({
+  designDataJsonRef,
+  id,
+  migrateMutation,
+  queryClient,
+  setMigrationResult,
+  updateDesignMutation,
+}: ConfirmMakeRealArgs) {
+  if (!id) return;
+  try {
+    const result = await migrateMutation.mutateAsync({ designId: id } as any);
+    const r = result as any;
+    setMigrationResult({
+      branchName: r?.branchName,
+      url: r?.url,
+      versionId: r?.versionId,
+      seedFileCount: r?.seedFileCount,
+      status: r?.status,
+      projectId: r?.projectId,
+      cta: r?.cta,
+    });
+
+    // When the Builder agent accepted the job (status = "processing"),
+    // flip the design data to sourceType "fusion" so capability-gated
+    // panels (branches, deploy) light up on refresh.
+    if (r?.status === "processing" && r?.url) {
+      const dataOperations: DesignDataOperation[] = [
+        { op: "set", path: ["sourceType"], value: "fusion" },
+        { op: "set", path: ["fusionUrl"], value: r.url },
+        r.branchName === undefined
+          ? { op: "delete", path: ["fusionBranchName"] }
+          : {
+              op: "set",
+              path: ["fusionBranchName"],
+              value: r.branchName,
+            },
+        r.projectId === undefined
+          ? { op: "delete", path: ["fusionProjectId"] }
+          : {
+              op: "set",
+              path: ["fusionProjectId"],
+              value: r.projectId,
+            },
+      ];
+      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) };
+      });
+      updateDesignMutation.mutate({ id, dataOperations } as any, {
+        onSuccess: () => {
+          queryClient.invalidateQueries({
+            queryKey: ["action", "get-design"],
+          });
+        },
+        onError: () => {
+          queryClient.invalidateQueries({
+            queryKey: ["action", "get-design"],
+          });
+        },
+      });
+    } else if (r?.status === "not-configured") {
+      // Builder not connected — leave dialog open to show the CTA.
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Migration failed";
+    toast.error(message);
+  }
+}

package/corpus/templates/design/app/pages/design-editor/commands/copy-as-figma-svg.ts

@@ -0,0 +1,95 @@
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+
+import type {
+  LiveFigmaSvgSnapshot,
+  LiveFigmaSvgSource,
+} from "@/lib/figma-svg-copy";
+import {
+  FigmaSvgCopyError,
+  canCopyFigmaSvgToClipboard,
+  copyDesignAsFigmaSvg,
+} from "@/lib/figma-svg-copy";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface CopyAsFigmaSvgArgs {
+  activeFile: DesignFile;
+  figmaSvgExportingRef: RefObject<boolean>;
+  id: string | undefined;
+  resolveLiveFigmaSvgSnapshot: (
+    targetFileId: string | undefined,
+  ) => LiveFigmaSvgSnapshot | null;
+  resolveLiveFigmaSvgSource: (
+    targetFileId: string | undefined,
+  ) => LiveFigmaSvgSource | null;
+  selectedElementLayerId: string | null;
+  selectedScreenIds: string[];
+  setFigmaSvgExporting: Dispatch<SetStateAction<boolean>>;
+  t: (key: string, options?: Record<string, unknown>) => string;
+}
+
+export async function runCopyAsFigmaSvg({
+  activeFile,
+  figmaSvgExportingRef,
+  id,
+  resolveLiveFigmaSvgSnapshot,
+  resolveLiveFigmaSvgSource,
+  selectedElementLayerId,
+  selectedScreenIds,
+  setFigmaSvgExporting,
+  t,
+}: CopyAsFigmaSvgArgs) {
+  if (figmaSvgExportingRef.current) return;
+  if (!canCopyFigmaSvgToClipboard()) {
+    toast.error(t("designEditor.toasts.figmaSvgUnsupported"));
+    return;
+  }
+
+  figmaSvgExportingRef.current = true;
+  setFigmaSvgExporting(true);
+  try {
+    // The export action defaults to `filename: "index.html"` when no
+    // fileId is given -- that only happens to work for a design whose
+    // screen is literally named index.html. This context menu is shared
+    // between single-screen edit view and overview mode, so resolve the
+    // actual target screen the same way PNG export does (selectedScreenIds
+    // covers both: activeFile.id in single-screen view, the
+    // overview-selected screen id(s) in overview mode) instead of letting
+    // the action guess. Regression: "Copy as SVG" on any non-index.html
+    // screen failed with "Design file not found".
+    const targetFileId = activeFile?.id ?? selectedScreenIds[0] ?? undefined;
+    await copyDesignAsFigmaSvg(
+      {
+        designId: id,
+        fileId: targetFileId,
+        nodeId: selectedElementLayerId ?? undefined,
+      },
+      {
+        liveSource: resolveLiveFigmaSvgSource(targetFileId),
+        liveSnapshot: resolveLiveFigmaSvgSnapshot(targetFileId),
+      },
+    );
+    toast.success(t("designEditor.toasts.figmaSvgCopied"));
+  } catch (error) {
+    if (error instanceof FigmaSvgCopyError) {
+      const key =
+        error.code === "blocked"
+          ? "designEditor.toasts.figmaSvgBlocked"
+          : error.code === "unsupported"
+            ? "designEditor.toasts.figmaSvgUnsupported"
+            : error.code === "render-failed"
+              ? "designEditor.toasts.figmaSvgRenderError"
+              : "designEditor.toasts.figmaSvgWriteError";
+      toast.error(t(key));
+    } else {
+      toast.error(
+        error instanceof Error
+          ? error.message
+          : t("designEditor.toasts.figmaSvgExportError"),
+      );
+    }
+  } finally {
+    figmaSvgExportingRef.current = false;
+    setFigmaSvgExporting(false);
+  }
+}

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

@@ -0,0 +1,156 @@
+import type { CanvasFrameGeometryById } from "@shared/canvas-frames";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+
+import {
+  getDesignClipboardTrustToken,
+  plainTextFromDesignHtml,
+  writeDesignClipboard,
+} from "@/lib/design-clipboard";
+import type {
+  DesignClipboardPayload,
+  DesignClipboardScreenEntry,
+} from "@/lib/design-import";
+import { serializeDesignClipboardPayload } from "@/lib/design-import";
+import { resolveClipboardLayerSourceHtml } from "@/pages/design-editor/clipboard-layer-source";
+import { preserveClipboardLayerName } from "@/pages/design-editor/clone-and-pen-edit";
+import type {
+  CanvasLayerClipboardEntry,
+  LiveScreenSnapshot,
+  RuntimeLayerSnapshot,
+  SelectedCanvasLayerSnapshot,
+} from "@/pages/design-editor/command-types";
+import type { OverviewScreen } from "@/pages/design-editor/derive/overview-screens";
+import { shouldUseRuntimeLayerProjection } from "@/pages/design-editor/pending-edits";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface CopySelectionArgs {
+  canvasFrameGeometryById: CanvasFrameGeometryById;
+  copiedLayerEntriesRef: RefObject<CanvasLayerClipboardEntry[]>;
+  copiedLayerHtmlRef: RefObject<string | null>;
+  copiedScreenEntriesRef: RefObject<DesignClipboardScreenEntry[] | undefined>;
+  designSourceType: "inline" | "localhost" | "fusion";
+  files: DesignFile[];
+  getScreenContent: (screenId: string) => string;
+  getSelectedLayerSnapshots: () => SelectedCanvasLayerSnapshot[];
+  lastWrittenClipboardMarkerRef: RefObject<string | null>;
+  lastWrittenClipboardPlainTextRef: RefObject<string | null>;
+  liveScreenSnapshotsById: Record<string, LiveScreenSnapshot>;
+  overviewScreens: OverviewScreen[];
+  overviewSelectedScreenIds: string[];
+  pasteCascadeRef: RefObject<number>;
+  runtimeLayerSnapshotsById: Record<string, RuntimeLayerSnapshot>;
+  setHasCanvasClipboard: Dispatch<SetStateAction<boolean>>;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  viewModeRef: RefObject<"single" | "overview">;
+}
+
+export async function runCopySelection({
+  canvasFrameGeometryById,
+  copiedLayerEntriesRef,
+  copiedLayerHtmlRef,
+  copiedScreenEntriesRef,
+  designSourceType,
+  files,
+  getScreenContent,
+  getSelectedLayerSnapshots,
+  lastWrittenClipboardMarkerRef,
+  lastWrittenClipboardPlainTextRef,
+  liveScreenSnapshotsById,
+  overviewScreens,
+  overviewSelectedScreenIds,
+  pasteCascadeRef,
+  runtimeLayerSnapshotsById,
+  setHasCanvasClipboard,
+  t,
+  viewModeRef,
+}: CopySelectionArgs) {
+  const entries = getSelectedLayerSnapshots().map((snapshot) => ({
+    html: preserveClipboardLayerName(snapshot.html, snapshot.node.layerName),
+    rootNodeId: snapshot.rootNodeId,
+    sourceFileId: snapshot.sourceFileId,
+    portableStyleSnapshot: snapshot.portableStyleSnapshot,
+    managedStyleSnapshot: snapshot.managedStyleSnapshot,
+  }));
+  // Whole-screen copy (U6): getSelectedLayerSnapshots explicitly excludes
+  // file/screen ids from layer candidates, so selecting one or more whole
+  // screens/frames in the overview and pressing Cmd+C previously produced
+  // zero entries and silently no-opped, leaving the clipboard unchanged.
+  // Fall back to screen-level snapshots (full file content + geometry) when
+  // there is no deeper layer selection to copy.
+  const screens: DesignClipboardPayload["screens"] =
+    entries.length === 0 && viewModeRef.current === "overview"
+      ? overviewSelectedScreenIds
+          .map((screenId): DesignClipboardScreenEntry | null => {
+            const file = files.find((candidate) => candidate.id === screenId);
+            const runtimeProjectionEligible =
+              file &&
+              shouldUseRuntimeLayerProjection({
+                screen: overviewScreens.find(
+                  (screen) => screen.id === screenId,
+                ),
+                fallbackSourceType: designSourceType,
+                content: file.content ?? "",
+              });
+            const runtimeSnapshot = runtimeProjectionEligible
+              ? runtimeLayerSnapshotsById[screenId]
+              : undefined;
+            const content = resolveClipboardLayerSourceHtml({
+              runtimeProjectionEligible: Boolean(runtimeProjectionEligible),
+              runtimeSnapshot,
+              liveSnapshotHtml: liveScreenSnapshotsById[screenId]?.html,
+              storedContent: getScreenContent(screenId) ?? file?.content,
+            });
+            if (!file || typeof content !== "string") return null;
+            return {
+              filename: file.filename,
+              fileType: file.fileType,
+              content,
+              canvasFrame: canvasFrameGeometryById[screenId],
+            };
+          })
+          .filter((entry): entry is DesignClipboardScreenEntry =>
+            Boolean(entry),
+          )
+      : [];
+  if (entries.length === 0 && screens.length === 0) return false;
+  const copiedHtml =
+    entries.length > 0
+      ? entries.map((entry) => entry.html).join("\n")
+      : screens.map((screen) => screen.content).join("\n");
+  const plainText = plainTextFromDesignHtml(
+    entries.length > 0
+      ? entries.map((entry) => entry.html)
+      : screens.map((screen) => screen.content),
+  );
+  // The lossless layer payload stays in text/html while text/plain contains
+  // only readable content. This mirrors Figma's clipboard behavior: Design
+  // can round-trip structure across tabs without dumping source and marker
+  // data into ordinary text destinations.
+  const clipboardHtml = serializeDesignClipboardPayload(
+    copiedHtml,
+    {
+      version: 1,
+      entries,
+      screens,
+    },
+    getDesignClipboardTrustToken() ?? undefined,
+  );
+  copiedLayerEntriesRef.current = entries;
+  copiedScreenEntriesRef.current = screens;
+  copiedLayerHtmlRef.current = clipboardHtml;
+  lastWrittenClipboardMarkerRef.current = clipboardHtml;
+  lastWrittenClipboardPlainTextRef.current = plainText;
+  pasteCascadeRef.current = 0;
+  setHasCanvasClipboard(true);
+  try {
+    await writeDesignClipboard({ plainText, html: clipboardHtml });
+  } catch {
+    // The OS clipboard write failing is tolerated: the in-memory refs
+    // above are already populated, so in-app cut-then-paste still works.
+    // Only the true "nothing was captured at all" case (the early return
+    // above) should abort a cut (see U15).
+    toast.error(t("designEditor.toasts.clipboardBlocked"));
+  }
+  return true;
+}

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

@@ -0,0 +1,291 @@
+import { buildCodeLayerProjection } from "@shared/code-layer";
+import { shouldUseLiveFileContent } from "@shared/html-content";
+import type { QueryClient } from "@tanstack/react-query";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+import * as Y from "yjs";
+
+import type { CanvasPrimitiveInsert } from "@/components/design/multi-screen/types";
+import type { RuntimeStructureInsertRequest } from "@/components/design/types";
+import type { ClipboardContentMutationPublication } from "@/lib/clipboard-content-lineage";
+import {
+  appendCanvasPrimitiveToHtml,
+  blankScreenHtml,
+  extractCanvasPrimitiveHtml,
+  uniqueLayerId,
+} from "@/pages/design-editor/canvas-primitive-insert";
+import { parsePenPathFromSerializedD } from "@/pages/design-editor/canvas-primitives";
+import { setPenNodesAttributeOnElement } from "@/pages/design-editor/clone-and-pen-edit";
+import type { FileContentSaveRequest } from "@/pages/design-editor/editor-state";
+import { isStandaloneHttpUrl } from "@/pages/design-editor/editor-state";
+import type {
+  ContentHistoryEntry,
+  PendingTextCreationHistory,
+} from "@/pages/design-editor/history";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface CreatePrimitiveArgs {
+  activeContent: string;
+  activeFile: DesignFile;
+  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;
+  collabContentFileIdRef: RefObject<string | null>;
+  collabContentRef: RefObject<string | null>;
+  createFileContentSaveRequest: (
+    fileId: string,
+    content: string,
+    syncCollab: boolean,
+  ) => FileContentSaveRequest;
+  files: DesignFile[];
+  id: string | undefined;
+  isSynced: boolean;
+  markPendingLocalFileContent: (
+    fileId: string,
+    content: string,
+    baseUpdatedAt?: string | null,
+  ) => void;
+  pendingLocalFileContentsRef: RefObject<
+    Map<
+      string,
+      { content: string; startedAt: number; baseUpdatedAt?: string | null }
+    >
+  >;
+  pendingTextCreationHistoryRef: RefObject<PendingTextCreationHistory | null>;
+  pendingTextEditNodeIdRef: RefObject<string | null>;
+  queryClient: QueryClient;
+  recordContentHistoryEntry: (entry: ContentHistoryEntry) => void;
+  runtimeStructureInsertRevisionRef: RefObject<number>;
+  saveFileContent: (pending: FileContentSaveRequest) => void;
+  setRuntimeStructureInsertRequest: Dispatch<
+    SetStateAction<
+      (RuntimeStructureInsertRequest & { screenId: string }) | null
+    >
+  >;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  viewModeRef: RefObject<"single" | "overview">;
+  ydoc: Y.Doc | null;
+}
+
+export function runCreatePrimitive(
+  {
+    activeContent,
+    activeFile,
+    applyLocalContentUpdate,
+    boardFileId,
+    canEditDesign,
+    collabContentFileIdRef,
+    collabContentRef,
+    createFileContentSaveRequest,
+    files,
+    id,
+    isSynced,
+    markPendingLocalFileContent,
+    pendingLocalFileContentsRef,
+    pendingTextCreationHistoryRef,
+    pendingTextEditNodeIdRef,
+    queryClient,
+    recordContentHistoryEntry,
+    runtimeStructureInsertRevisionRef,
+    saveFileContent,
+    setRuntimeStructureInsertRequest,
+    t,
+    viewModeRef,
+    ydoc,
+  }: CreatePrimitiveArgs,
+  screenId: string,
+  primitive: CanvasPrimitiveInsert,
+) {
+  if (!canEditDesign) return false;
+  const targetFile = files.find((file) => file.id === screenId);
+  if (!targetFile) return false;
+  const pendingContent = pendingLocalFileContentsRef.current.get(
+    targetFile.id,
+  )?.content;
+  const storedContent = targetFile.content ?? "";
+  const baseContent =
+    pendingContent ??
+    (targetFile.id === activeFile?.id
+      ? (() => {
+          const liveContent =
+            ydoc && isSynced
+              ? ydoc.getText("content").toString()
+              : ((collabContentFileIdRef.current === activeFile.id
+                  ? collabContentRef.current
+                  : null) ?? activeContent);
+          return shouldUseLiveFileContent({
+            liveContent,
+            storedContent,
+            fileType: targetFile.fileType,
+          })
+            ? liveContent
+            : storedContent;
+        })()
+      : storedContent);
+  // A localhost screen's stored content is its route URL, not an editable
+  // document. Keep that URL intact and send one serialized primitive
+  // through the same live insert bridge used by board-to-screen drops.
+  // The bridge echo records the pending source handoff and owns the
+  // optimistic DOM/history lifecycle (selection, Layers, undo, and redo).
+  if (isStandaloneHttpUrl(baseContent)) {
+    const nodeId =
+      primitive.nodeId ?? uniqueLayerId(primitive.kind || "primitive");
+    const livePrimitive = { ...primitive, nodeId };
+    const temporaryDocument = appendCanvasPrimitiveToHtml(
+      blankScreenHtml("Live insert"),
+      livePrimitive,
+    );
+    if (!temporaryDocument) {
+      toast.error(t("designEditor.toasts.primitiveInsertFailed"));
+      return false;
+    }
+    const enrichedDocument =
+      primitive.kind === "path" && primitive.pathData
+        ? (() => {
+            const reconstructed = parsePenPathFromSerializedD(
+              primitive.pathData!,
+            );
+            return reconstructed
+              ? setPenNodesAttributeOnElement(
+                  temporaryDocument,
+                  nodeId,
+                  reconstructed,
+                )
+              : temporaryDocument;
+          })()
+        : temporaryDocument;
+    const insertedHtml = extractCanvasPrimitiveHtml(enrichedDocument, nodeId);
+    if (!insertedHtml) {
+      toast.error(t("designEditor.toasts.primitiveInsertFailed"));
+      return false;
+    }
+    pendingTextEditNodeIdRef.current =
+      primitive.kind === "text" ? nodeId : null;
+    runtimeStructureInsertRevisionRef.current += 1;
+    setRuntimeStructureInsertRequest({
+      requestId: runtimeStructureInsertRevisionRef.current,
+      screenId: targetFile.id,
+      html: insertedHtml,
+      anchor: { selector: "body" },
+      placement: "inside",
+    });
+    return nodeId;
+  }
+  const insertedContent = appendCanvasPrimitiveToHtml(baseContent, primitive, {
+    preserveNegativePosition: targetFile.id === boardFileId,
+    isBoardTarget: targetFile.id === boardFileId,
+  });
+  if (!insertedContent) {
+    toast.error(t("designEditor.toasts.primitiveInsertFailed"));
+    return false;
+  }
+  // Vector-edit foundations: stash the structured pen path (nodes +
+  // handles) alongside the flattened `d` so a later double-click/Enter
+  // can re-hydrate it into an editable path instead of only having the
+  // already-flattened curve. `primitive.pathData` is the only carrier of
+  // pen geometry that crosses the MultiScreenCanvas -> DesignEditor
+  // boundary for an OVERVIEW-drawn pen path (see
+  // parsePenPathFromSerializedD's doc comment for why this reconstructs
+  // rather than receives the structured path directly).
+  const nextContent =
+    primitive.kind === "path" && primitive.pathData && primitive.nodeId
+      ? (() => {
+          const reconstructed = parsePenPathFromSerializedD(
+            primitive.pathData!,
+          );
+          return reconstructed
+            ? setPenNodesAttributeOnElement(
+                insertedContent,
+                primitive.nodeId!,
+                reconstructed,
+              )
+            : insertedContent;
+        })()
+      : insertedContent;
+  const projectedNodeId = primitive.nodeId
+    ? buildCodeLayerProjection(nextContent).nodes.find(
+        (node) =>
+          node.dataAttributes["data-agent-native-node-id"] === primitive.nodeId,
+      )?.id
+    : null;
+
+  pendingTextCreationHistoryRef.current =
+    primitive.kind === "text" &&
+    primitive.nodeId &&
+    viewModeRef.current === "overview"
+      ? {
+          fileId: targetFile.id,
+          nodeId: primitive.nodeId,
+          before: baseContent,
+          created: nextContent,
+        }
+      : null;
+
+  if (targetFile.id === activeFile?.id) {
+    applyLocalContentUpdate(nextContent, {
+      forcePreviewFullDocument: true,
+      historyBeforeContent: baseContent,
+      immediateSave: true,
+    });
+  } else {
+    recordContentHistoryEntry({
+      fileId: targetFile.id,
+      before: baseContent,
+      after: nextContent,
+    });
+    // Stamp the server-clock base the same way applyFileContentUpdate
+    // does. Without it the reconcile effect reads the optimistic cache
+    // write below as a server acknowledgement and retires the pending
+    // entry immediately, leaving that cache the only carrier of the
+    // insert — so any get-design response already in flight (the board
+    // file's own lazy migration invalidates on success, so one usually
+    // is) overwrites it with pre-insert content and the primitive
+    // disappears from the canvas until a reload.
+    markPendingLocalFileContent(
+      targetFile.id,
+      nextContent,
+      targetFile.updatedAt,
+    );
+    queryClient.setQueryData(["action", "get-design", { id }], (old: any) => {
+      if (!old || typeof old !== "object" || !Array.isArray(old.files)) {
+        return old;
+      }
+      return {
+        ...old,
+        files: old.files.map((file: DesignFile) =>
+          file.id === targetFile.id ? { ...file, content: nextContent } : file,
+        ),
+      };
+    });
+    saveFileContent(
+      createFileContentSaveRequest(targetFile.id, nextContent, true),
+    );
+  }
+
+  const result = projectedNodeId ?? primitive.nodeId ?? true;
+
+  // Record the nodeId when a TEXT primitive is created so the next
+  // handlePrimitiveCreated (or handleBoardDrawPrimitive) can immediately
+  // enter text-edit mode — fixing the "click to add text should let me
+  // type immediately" bug. The ref is read once and cleared.
+  if (primitive.kind === "text") {
+    pendingTextEditNodeIdRef.current = primitive.nodeId ?? null;
+  } else {
+    pendingTextEditNodeIdRef.current = null;
+  }
+
+  return result;
+}