From e7030755e9a9eb55791c40bae4068472e8cecbfb Mon Sep 17 00:00:00 2001
From: Trang Doan <doantranghp2000@gmail.com>
Date: Wed, 9 Sep 2026 16:28:32 -0400
Subject: [PATCH 1/5] ENG-1356 Add hover icon button to convert canvas images
 into discourse nodes

Hovering a tldraw image shape now shows a convert button that opens the
create node dialog with the type picker enabled and an image preview. The
existing right-click Convert To path is unchanged; its upload and
shape-replacement steps move into shared helpers used by both flows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/roam/src/components/ModifyNodeDialog.tsx |  15 +++
 apps/roam/src/components/canvas/Tldraw.tsx    |   4 +-
 .../canvas/convertShapeToDiscourseNode.ts     |  64 +++++++++++
 .../canvas/overlays/CanvasOverlays.tsx        |  10 ++
 .../canvas/overlays/ImageConvertOverlay.tsx   | 108 ++++++++++++++++++
 .../src/components/canvas/uiOverrides.tsx     |  58 +++-------
 .../content/roam/guides/using-the-canvas.mdx  |   6 +-
 7 files changed, 219 insertions(+), 46 deletions(-)
 create mode 100644 apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts
 create mode 100644 apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx
 create mode 100644 apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx

diff --git a/apps/roam/src/components/ModifyNodeDialog.tsx b/apps/roam/src/components/ModifyNodeDialog.tsx
index 06a0f9958..6cdc94e91 100644
--- a/apps/roam/src/components/ModifyNodeDialog.tsx
+++ b/apps/roam/src/components/ModifyNodeDialog.tsx
@@ -58,6 +58,7 @@ export type ModifyNodeDialogProps = {
     text: string;
     uid: string;
     action: string;
+    nodeType?: string;
   }) => Promise<void>;
   onClose: () => void;
 };
@@ -371,6 +372,7 @@ const ModifyNodeDialog = ({
             text: content.text,
             uid: content.uid,
             action: "create",
+            nodeType: selectedNodeType?.type,
           });
 
           onClose();
@@ -480,6 +482,7 @@ const ModifyNodeDialog = ({
           text: formattedTitle,
           uid: newPageUid,
           action: "create",
+          nodeType: selectedNodeType?.type,
         });
       } else {
         // Edit mode: update the existing block
@@ -515,6 +518,7 @@ const ModifyNodeDialog = ({
           text: updatedContent,
           uid: sourceBlockUid || content.uid,
           action: "edit",
+          nodeType: selectedNodeType?.type,
         });
       }
       onClose();
@@ -592,6 +596,17 @@ const ModifyNodeDialog = ({
             </Label>
           </div>
 
+          {imageUrl && (
+            <Label className="w-full">
+              Image
+              <img
+                src={imageUrl}
+                alt=""
+                className="mt-1 max-h-40 w-full rounded object-contain"
+              />
+            </Label>
+          )}
+
           {/* Referenced Node Input */}
           {referencedNode && !isContentLocked && mode === "create" && (
             <Label className="w-full">
diff --git a/apps/roam/src/components/canvas/Tldraw.tsx b/apps/roam/src/components/canvas/Tldraw.tsx
index 505833d02..fd2f12c89 100644
--- a/apps/roam/src/components/canvas/Tldraw.tsx
+++ b/apps/roam/src/components/canvas/Tldraw.tsx
@@ -53,7 +53,7 @@ import {
 } from "tldraw";
 import "tldraw/tldraw.css";
 import tldrawStyles from "./tldrawStyles";
-import { DragHandleOverlay } from "./overlays/DragHandleOverlay";
+import { CanvasOverlays } from "./overlays/CanvasOverlays";
 import { isDiscourseNodeShape } from "./canvasUtils";
 import getDiscourseNodes, { DiscourseNode } from "~/utils/getDiscourseNodes";
 import getDiscourseRelations, {
@@ -995,7 +995,7 @@ const TldrawCanvasShared = ({
   const editorComponents: TLEditorComponents = {
     ...defaultEditorComponents,
     OnTheCanvas: ToastListener,
-    InFrontOfTheCanvas: DragHandleOverlay,
+    InFrontOfTheCanvas: CanvasOverlays,
   };
   const customUiComponents: TLUiComponents = createUiComponents({
     allNodes,
diff --git a/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts b/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts
new file mode 100644
index 000000000..10ca8232d
--- /dev/null
+++ b/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts
@@ -0,0 +1,64 @@
+import { createShapeId, Editor, TLImageShape, TLShape } from "tldraw";
+import type { OnloadArgs } from "roamjs-components/types";
+import calcCanvasNodeSizeAndImg from "~/utils/calcCanvasNodeSizeAndImg";
+import { DISCOURSE_NODE_SHAPE_TYPE } from "./DiscourseNodeUtil";
+
+export const uploadImageShapeToRoam = async ({
+  editor,
+  shape,
+}: {
+  editor: Editor;
+  shape: TLImageShape;
+}): Promise<string | undefined> => {
+  const { assetId } = shape.props;
+  if (!assetId) return undefined;
+  const asset = editor.getAsset(assetId);
+  if (!asset || !asset.props.src) return undefined;
+  const file = await fetch(asset.props.src)
+    .then((r) => r.arrayBuffer())
+    .then((buf) => new File([buf], shape.id));
+  return window.roamAlphaAPI.util.uploadFile({ file });
+};
+
+export const replaceShapeWithDiscourseNode = async ({
+  editor,
+  extensionAPI,
+  shape,
+  nodeType,
+  text,
+  uid,
+}: {
+  editor: Editor;
+  extensionAPI: OnloadArgs["extensionAPI"];
+  shape: TLShape;
+  nodeType: string;
+  text: string;
+  uid: string;
+}): Promise<void> => {
+  const { x, y } = shape;
+  editor.deleteShapes([shape.id]);
+  const { h, w, imageUrl } = await calcCanvasNodeSizeAndImg({
+    nodeText: text,
+    extensionAPI,
+    nodeType,
+    uid,
+  });
+  editor.createShapes([
+    {
+      type: DISCOURSE_NODE_SHAPE_TYPE,
+      id: createShapeId(),
+      props: {
+        uid,
+        title: text,
+        h,
+        w,
+        imageUrl,
+        fontFamily: "sans",
+        size: "s",
+        nodeTypeId: nodeType,
+      },
+      x,
+      y,
+    },
+  ]);
+};
diff --git a/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx b/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx
new file mode 100644
index 000000000..4d61088de
--- /dev/null
+++ b/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx
@@ -0,0 +1,10 @@
+import React from "react";
+import { DragHandleOverlay } from "./DragHandleOverlay";
+import { ImageConvertOverlay } from "./ImageConvertOverlay";
+
+export const CanvasOverlays = () => (
+  <>
+    <DragHandleOverlay />
+    <ImageConvertOverlay />
+  </>
+);
diff --git a/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx b/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx
new file mode 100644
index 000000000..5188d8d3d
--- /dev/null
+++ b/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx
@@ -0,0 +1,108 @@
+import React, { useCallback, useState } from "react";
+import { Button, Icon } from "@blueprintjs/core";
+import { TLImageShape, useEditor, useValue } from "tldraw";
+import { useExtensionAPI } from "roamjs-components/components/ExtensionApiContext";
+import posthog from "posthog-js";
+import { renderModifyNodeDialog } from "~/components/ModifyNodeDialog";
+import { dispatchToastEvent } from "~/components/canvas/ToastListener";
+import {
+  replaceShapeWithDiscourseNode,
+  uploadImageShapeToRoam,
+} from "~/components/canvas/convertShapeToDiscourseNode";
+
+const BUTTON_INSET = 8;
+
+const isImageShape = (shape: unknown): shape is TLImageShape =>
+  !!shape && (shape as { type?: string }).type === "image";
+
+export const ImageConvertOverlay = () => {
+  const editor = useEditor();
+  const extensionAPI = useExtensionAPI();
+  const [uploading, setUploading] = useState(false);
+
+  const imageShape = useValue<TLImageShape | null>(
+    "imageConvertTarget",
+    () => {
+      if (!editor.isIn("select.idle")) return null;
+      const hovered = editor.getHoveredShape();
+      if (isImageShape(hovered)) return hovered;
+      const selected = editor.getOnlySelectedShape();
+      return isImageShape(selected) ? selected : null;
+    },
+    [editor],
+  );
+
+  const buttonPosition = useValue<{ left: number; top: number } | null>(
+    "imageConvertButtonPosition",
+    () => {
+      if (!imageShape) return null;
+      const bounds = editor.getShapePageBounds(imageShape.id);
+      if (!bounds) return null;
+      const vp = editor.pageToViewport({ x: bounds.minX, y: bounds.minY });
+      return { left: vp.x + BUTTON_INSET, top: vp.y + BUTTON_INSET };
+    },
+    [editor, imageShape?.id],
+  );
+
+  const openConvertDialog = useCallback(async () => {
+    if (!imageShape || !extensionAPI || uploading) return;
+    posthog.capture("Canvas: Image Convert Button Clicked");
+    setUploading(true);
+    try {
+      const src = await uploadImageShapeToRoam({ editor, shape: imageShape });
+      if (!src) {
+        dispatchToastEvent({
+          id: "tldraw-image-convert-no-asset",
+          title: "Could not read this image",
+          severity: "warning",
+        });
+        return;
+      }
+      renderModifyNodeDialog({
+        mode: "create",
+        initialValue: { text: "", uid: "" },
+        extensionAPI,
+        imageUrl: src,
+        onSuccess: async ({ text, uid, nodeType }) => {
+          const shape = editor.getShape(imageShape.id);
+          if (!shape || !nodeType) return;
+          await replaceShapeWithDiscourseNode({
+            editor,
+            extensionAPI,
+            shape,
+            nodeType,
+            text,
+            uid,
+          });
+        },
+        onClose: () => {},
+      });
+    } finally {
+      setUploading(false);
+    }
+  }, [editor, extensionAPI, imageShape, uploading]);
+
+  if (!buttonPosition) return null;
+
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }}>
+      <Button
+        small
+        className="absolute z-20 rounded border border-gray-300 bg-white shadow"
+        style={{
+          left: `${buttonPosition.left}px`,
+          top: `${buttonPosition.top}px`,
+          pointerEvents: "all",
+        }}
+        icon={<Icon icon="new-object" />}
+        loading={uploading}
+        title="Convert to discourse node"
+        onPointerDown={(e) => e.stopPropagation()}
+        onClick={(e) => {
+          e.stopPropagation();
+          void openConvertDialog();
+        }}
+      />
+    </div>
+  );
+};
diff --git a/apps/roam/src/components/canvas/uiOverrides.tsx b/apps/roam/src/components/canvas/uiOverrides.tsx
index 111ebae41..e009160d3 100644
--- a/apps/roam/src/components/canvas/uiOverrides.tsx
+++ b/apps/roam/src/components/canvas/uiOverrides.tsx
@@ -50,12 +50,14 @@ import { DiscourseContextType } from "./Tldraw";
 import { formatHexColor } from "~/components/settings/DiscourseNodeCanvasSettings";
 import {
   COLOR_ARRAY,
-  DISCOURSE_NODE_SHAPE_TYPE,
   getDiscourseNodeTypeId,
   isDiscourseNodeShape,
   type DiscourseNodeShape,
 } from "./DiscourseNodeUtil";
-import calcCanvasNodeSizeAndImg from "~/utils/calcCanvasNodeSizeAndImg";
+import {
+  replaceShapeWithDiscourseNode,
+  uploadImageShapeToRoam,
+} from "./convertShapeToDiscourseNode";
 import { AddReferencedNodeType } from "./DiscourseRelationShape/DiscourseRelationTool";
 import {
   DiscourseRelationShape,
@@ -171,8 +173,6 @@ export const getOnSelectForShape = ({
   editor: Editor;
   extensionAPI: OnloadArgs["extensionAPI"];
 }) => {
-  const { x, y } = shape;
-
   const openDialogAndCreateShape = ({
     initialText,
     imageUrl,
@@ -188,54 +188,26 @@ export const getOnSelectForShape = ({
       includeDefaultNodes: true,
       disableNodeTypeChange: true,
       imageUrl,
-      onSuccess: async ({ text, uid }) => {
-        editor.deleteShapes([shape.id]);
-
-        const {
-          h,
-          w,
-          imageUrl: nodeImageUrl,
-        } = await calcCanvasNodeSizeAndImg({
-          nodeText: text,
+      onSuccess: ({ text, uid }) =>
+        replaceShapeWithDiscourseNode({
+          editor,
           extensionAPI,
+          shape,
           nodeType,
+          text,
           uid,
-        });
-        editor.createShapes([
-          {
-            type: DISCOURSE_NODE_SHAPE_TYPE,
-            id: createShapeId(),
-            props: {
-              uid,
-              title: text,
-              h,
-              w,
-              imageUrl: nodeImageUrl,
-              fontFamily: "sans",
-              size: "s",
-              nodeTypeId: nodeType,
-            },
-            x,
-            y,
-          },
-        ]);
-      },
+        }),
       onClose: () => {},
     });
   };
 
   if (shape.type === "image") {
     return async () => {
-      const { assetId } = (shape as TLImageShape).props;
-      if (!assetId) return;
-      const asset = editor.getAsset(assetId);
-      if (!asset || !asset.props.src) return;
-      const file = await fetch(asset.props.src)
-        .then((r) => r.arrayBuffer())
-        .then((buf) => new File([buf], shape.id));
-      // this is a promise
-      // eslint-disable-next-line @typescript-eslint/await-thenable
-      const src = await window.roamAlphaAPI.util.uploadFile({ file });
+      const src = await uploadImageShapeToRoam({
+        editor,
+        shape: shape as TLImageShape,
+      });
+      if (!src) return;
       const initialText = nodeType === "blck-node" ? `![](${src})` : "";
 
       openDialogAndCreateShape({ initialText, imageUrl: src });
diff --git a/apps/website/content/roam/guides/using-the-canvas.mdx b/apps/website/content/roam/guides/using-the-canvas.mdx
index 4c3df7485..2b5f643cc 100644
--- a/apps/website/content/roam/guides/using-the-canvas.mdx
+++ b/apps/website/content/roam/guides/using-the-canvas.mdx
@@ -217,7 +217,11 @@ _sending query results to your canvas_
 
 ### Converting images or text into discourse nodes
 
-You can select images or text from your graph, a document, a file, or a webpage, copy them to your canvas, and convert them into discourse nodes. Right-click the image, select "Convert to...", then modify the title as needed.
+You can select images or text from your graph, a document, a file, or a webpage, copy them to your canvas, and convert them into discourse nodes.
+
+To convert an image, hover over it and click the convert icon that appears in its top-left corner. In the create node dialog, pick the node type, enter a title, and confirm. The image is replaced on the canvas by the new node, and the image is added to the node's page.
+
+You can also right-click an image or text shape and select "Convert to...", pick the node type, then modify the title as needed. Use this path to convert text shapes or to turn an image into a block.
 
 <Callout type="info" emoji="💡">
   Remember to enable the **Key Image** feature in Settings if you want to

From 0e3265d84d7ef451c4eb7a0c8565365cd08b954b Mon Sep 17 00:00:00 2001
From: Trang Doan <doantranghp2000@gmail.com>
Date: Wed, 9 Sep 2026 16:35:26 -0400
Subject: [PATCH 2/5] ENG-1356 Handle upload failures and locked images in the
 convert overlay

Skip locked image shapes, surface upload errors and unreplaced shapes as
toasts, and tighten docs wording around Key Image.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/roam/src/components/ModifyNodeDialog.tsx |  8 +++---
 .../canvas/overlays/CanvasOverlays.tsx        |  2 +-
 .../canvas/overlays/ImageConvertOverlay.tsx   | 27 ++++++++++++++-----
 .../content/roam/guides/using-the-canvas.mdx  |  4 +--
 4 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/apps/roam/src/components/ModifyNodeDialog.tsx b/apps/roam/src/components/ModifyNodeDialog.tsx
index 6cdc94e91..b56f5fcd8 100644
--- a/apps/roam/src/components/ModifyNodeDialog.tsx
+++ b/apps/roam/src/components/ModifyNodeDialog.tsx
@@ -597,14 +597,14 @@ const ModifyNodeDialog = ({
           </div>
 
           {imageUrl && (
-            <Label className="w-full">
-              Image
+            <div className="flex w-full flex-col gap-1">
+              <span>Image</span>
               <img
                 src={imageUrl}
                 alt=""
-                className="mt-1 max-h-40 w-full rounded object-contain"
+                className="max-h-40 w-full rounded object-contain"
               />
-            </Label>
+            </div>
           )}
 
           {/* Referenced Node Input */}
diff --git a/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx b/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx
index 4d61088de..452252aef 100644
--- a/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx
+++ b/apps/roam/src/components/canvas/overlays/CanvasOverlays.tsx
@@ -2,7 +2,7 @@ import React from "react";
 import { DragHandleOverlay } from "./DragHandleOverlay";
 import { ImageConvertOverlay } from "./ImageConvertOverlay";
 
-export const CanvasOverlays = () => (
+export const CanvasOverlays = (): JSX.Element => (
   <>
     <DragHandleOverlay />
     <ImageConvertOverlay />
diff --git a/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx b/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx
index 5188d8d3d..1a2dca7d0 100644
--- a/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx
+++ b/apps/roam/src/components/canvas/overlays/ImageConvertOverlay.tsx
@@ -1,6 +1,6 @@
 import React, { useCallback, useState } from "react";
 import { Button, Icon } from "@blueprintjs/core";
-import { TLImageShape, useEditor, useValue } from "tldraw";
+import { TLImageShape, TLShape, useEditor, useValue } from "tldraw";
 import { useExtensionAPI } from "roamjs-components/components/ExtensionApiContext";
 import posthog from "posthog-js";
 import { renderModifyNodeDialog } from "~/components/ModifyNodeDialog";
@@ -12,10 +12,10 @@ import {
 
 const BUTTON_INSET = 8;
 
-const isImageShape = (shape: unknown): shape is TLImageShape =>
-  !!shape && (shape as { type?: string }).type === "image";
+const isConvertibleImage = (shape?: TLShape | null): shape is TLImageShape =>
+  shape?.type === "image" && !shape.isLocked;
 
-export const ImageConvertOverlay = () => {
+export const ImageConvertOverlay = (): JSX.Element | null => {
   const editor = useEditor();
   const extensionAPI = useExtensionAPI();
   const [uploading, setUploading] = useState(false);
@@ -25,9 +25,9 @@ export const ImageConvertOverlay = () => {
     () => {
       if (!editor.isIn("select.idle")) return null;
       const hovered = editor.getHoveredShape();
-      if (isImageShape(hovered)) return hovered;
+      if (isConvertibleImage(hovered)) return hovered;
       const selected = editor.getOnlySelectedShape();
-      return isImageShape(selected) ? selected : null;
+      return isConvertibleImage(selected) ? selected : null;
     },
     [editor],
   );
@@ -65,7 +65,14 @@ export const ImageConvertOverlay = () => {
         imageUrl: src,
         onSuccess: async ({ text, uid, nodeType }) => {
           const shape = editor.getShape(imageShape.id);
-          if (!shape || !nodeType) return;
+          if (!shape || !nodeType) {
+            dispatchToastEvent({
+              id: "tldraw-image-convert-not-replaced",
+              title: "Node created, but the image could not be replaced",
+              severity: "warning",
+            });
+            return;
+          }
           await replaceShapeWithDiscourseNode({
             editor,
             extensionAPI,
@@ -77,6 +84,12 @@ export const ImageConvertOverlay = () => {
         },
         onClose: () => {},
       });
+    } catch (error) {
+      dispatchToastEvent({
+        id: "tldraw-image-convert-failed",
+        title: `Could not upload this image: ${String(error)}`,
+        severity: "error",
+      });
     } finally {
       setUploading(false);
     }
diff --git a/apps/website/content/roam/guides/using-the-canvas.mdx b/apps/website/content/roam/guides/using-the-canvas.mdx
index 2b5f643cc..6c2401367 100644
--- a/apps/website/content/roam/guides/using-the-canvas.mdx
+++ b/apps/website/content/roam/guides/using-the-canvas.mdx
@@ -219,9 +219,9 @@ _sending query results to your canvas_
 
 You can select images or text from your graph, a document, a file, or a webpage, copy them to your canvas, and convert them into discourse nodes.
 
-To convert an image, hover over it and click the convert icon that appears in its top-left corner. In the create node dialog, pick the node type, enter a title, and confirm. The image is replaced on the canvas by the new node, and the image is added to the node's page.
+To convert an image, hover over it and click the convert icon that appears in its top-left corner. In the create node dialog, pick the node type, enter a title, and confirm. The image is replaced on the canvas by the new node and, if **Key Image** is enabled for that node type, added to the node's page.
 
-You can also right-click an image or text shape and select "Convert to...", pick the node type, then modify the title as needed. Use this path to convert text shapes or to turn an image into a block.
+You can also right-click an image or text shape and select **Convert To**, pick the node type, then modify the title as needed. Use this path to convert text shapes or to turn an image into a block.
 
 <Callout type="info" emoji="💡">
   Remember to enable the **Key Image** feature in Settings if you want to

From 0fde61b17f73a3c0d2180e448ae6795a1e46056c Mon Sep 17 00:00:00 2001
From: Trang Doan <doantranghp2000@gmail.com>
Date: Wed, 9 Sep 2026 17:09:28 -0400
Subject: [PATCH 3/5] ENG-1356 Always add the converted image to the new node
 page

Image insertion was gated on the Key Image canvas setting for new pages
while the existing-node path added it unconditionally. Both conversion
flows now share one helper that always writes the image block and uses
Key Image only to pick the query-builder placeholder.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/roam/src/components/ModifyNodeDialog.tsx | 72 ++-----------------
 apps/roam/src/utils/createDiscourseNode.ts    | 55 +++++++-------
 .../content/roam/guides/using-the-canvas.mdx  |  6 +-
 3 files changed, 34 insertions(+), 99 deletions(-)

diff --git a/apps/roam/src/components/ModifyNodeDialog.tsx b/apps/roam/src/components/ModifyNodeDialog.tsx
index b56f5fcd8..332d40907 100644
--- a/apps/roam/src/components/ModifyNodeDialog.tsx
+++ b/apps/roam/src/components/ModifyNodeDialog.tsx
@@ -31,12 +31,12 @@ import {
   getNewDiscourseNodeText,
   getReferencedNodeInFormat,
 } from "~/utils/formatUtils";
-import createDiscourseNode from "~/utils/createDiscourseNode";
+import createDiscourseNode, {
+  handleImageCreation,
+} from "~/utils/createDiscourseNode";
 import { OnloadArgs } from "roamjs-components/types";
 import { render as renderToast } from "roamjs-components/components/Toast";
 import getPageUidByPageTitle from "roamjs-components/queries/getPageUidByPageTitle";
-import resolveQueryBuilderRef from "~/utils/resolveQueryBuilderRef";
-import runQuery from "~/utils/runQuery";
 import posthog from "posthog-js";
 
 export type ModifyNodeDialogMode = "create" | "edit";
@@ -274,66 +274,6 @@ const ModifyNodeDialog = ({
     onClose();
   }, [onClose]);
 
-  const addImageToPage = useCallback(
-    async ({
-      pageUid,
-      imageUrl,
-      configPageUid,
-      extensionAPI,
-    }: {
-      pageUid: string;
-      imageUrl: string;
-      configPageUid: string;
-      extensionAPI?: OnloadArgs["extensionAPI"];
-    }) => {
-      const discourseNodes = getDiscourseNodes();
-      const canvasSettings = Object.fromEntries(
-        discourseNodes.map((n) => [n.type, { ...n.canvasSettings }]),
-      );
-      const {
-        "query-builder-alias": qbAlias = "",
-        "key-image": isKeyImage = "",
-        "key-image-option": keyImageOption = "",
-      } = canvasSettings[configPageUid] || {};
-
-      const createOrUpdateImageBlock = async (imagePlaceholderUid?: string) => {
-        const imageMarkdown = `![](${imageUrl})`;
-        if (imagePlaceholderUid) {
-          await updateBlock({
-            uid: imagePlaceholderUid,
-            text: imageMarkdown,
-          });
-        } else {
-          await createBlock({
-            node: { text: imageMarkdown },
-            order: 0,
-            parentUid: pageUid,
-          });
-        }
-      };
-
-      if (!isKeyImage || !extensionAPI) {
-        await createOrUpdateImageBlock();
-        return;
-      }
-
-      if (keyImageOption === "query-builder") {
-        const parentUid = resolveQueryBuilderRef({ queryRef: qbAlias });
-        const results = await runQuery({
-          extensionAPI,
-          parentUid,
-          // due to query format
-          inputs: { NODETEXT: content.text, NODEUID: pageUid },
-        });
-        const imagePlaceholderUid = results.allProcessedResults[0]?.uid;
-        await createOrUpdateImageBlock(imagePlaceholderUid);
-      } else {
-        await createOrUpdateImageBlock();
-      }
-    },
-    [content.text],
-  );
-
   const onSubmit = async () => {
     if (!content.text.trim()) return;
     if (!selectedNodeType && !isContentLocked) {
@@ -359,11 +299,13 @@ const ModifyNodeDialog = ({
           if (imageUrl) {
             const pageUid = content.uid || getPageUidByPageTitle(content.text);
             if (pageUid) {
-              await addImageToPage({
+              await handleImageCreation({
                 pageUid,
-                imageUrl,
+                discourseNodes: getDiscourseNodes(),
                 configPageUid: selectedNodeType?.type || "",
+                imageUrl,
                 extensionAPI,
+                text: content.text,
               });
             }
           }
diff --git a/apps/roam/src/utils/createDiscourseNode.ts b/apps/roam/src/utils/createDiscourseNode.ts
index 92a28e198..f24535765 100644
--- a/apps/roam/src/utils/createDiscourseNode.ts
+++ b/apps/roam/src/utils/createDiscourseNode.ts
@@ -40,7 +40,8 @@ const stripTemplateUids = (nodes: InputTextNode[]): InputTextNode[] =>
     };
   });
 
-const handleImageCreation = async ({
+// Key Image only decides where the image block goes, never whether it is added
+export const handleImageCreation = async ({
   pageUid,
   discourseNodes,
   configPageUid,
@@ -54,7 +55,8 @@ const handleImageCreation = async ({
   imageUrl?: string;
   extensionAPI?: OnloadArgs["extensionAPI"];
   text: string;
-}) => {
+}): Promise<void> => {
+  if (!imageUrl) return;
   const canvasSettings = Object.fromEntries(
     discourseNodes.map((n) => [n.type, { ...n.canvasSettings }]),
   );
@@ -64,38 +66,29 @@ const handleImageCreation = async ({
     "key-image-option": keyImageOption = "",
   } = canvasSettings[configPageUid] || {};
 
-  if (isKeyImage && imageUrl) {
-    const createOrUpdateImageBlock = async (imagePlaceholderUid?: string) => {
-      const imageMarkdown = `![](${imageUrl})`;
-      if (imagePlaceholderUid) {
-        await updateBlock({
-          uid: imagePlaceholderUid,
-          text: imageMarkdown,
-        });
-      } else {
-        await createBlock({
-          node: { text: imageMarkdown },
-          order: 0,
-          parentUid: pageUid,
-        });
-      }
-    };
-
-    if (keyImageOption === "query-builder") {
-      if (!extensionAPI) return;
+  const imageMarkdown = `![](${imageUrl})`;
+  const usesQueryBuilderPlaceholder =
+    !!isKeyImage && keyImageOption === "query-builder" && !!extensionAPI;
 
-      const parentUid = resolveQueryBuilderRef({ queryRef: qbAlias });
-      const results = await runQuery({
-        extensionAPI,
-        parentUid,
-        inputs: { NODETEXT: text, NODEUID: pageUid },
-      });
-      const imagePlaceholderUid = results.allProcessedResults[0]?.uid;
-      await createOrUpdateImageBlock(imagePlaceholderUid);
-    } else {
-      await createOrUpdateImageBlock();
+  if (usesQueryBuilderPlaceholder) {
+    const parentUid = resolveQueryBuilderRef({ queryRef: qbAlias });
+    const results = await runQuery({
+      extensionAPI,
+      parentUid,
+      inputs: { NODETEXT: text, NODEUID: pageUid },
+    });
+    const imagePlaceholderUid = results.allProcessedResults[0]?.uid;
+    if (imagePlaceholderUid) {
+      await updateBlock({ uid: imagePlaceholderUid, text: imageMarkdown });
+      return;
     }
   }
+
+  await createBlock({
+    node: { text: imageMarkdown },
+    order: 0,
+    parentUid: pageUid,
+  });
 };
 
 export const createBlocksFromTemplate = async ({
diff --git a/apps/website/content/roam/guides/using-the-canvas.mdx b/apps/website/content/roam/guides/using-the-canvas.mdx
index 6c2401367..bb91f653e 100644
--- a/apps/website/content/roam/guides/using-the-canvas.mdx
+++ b/apps/website/content/roam/guides/using-the-canvas.mdx
@@ -219,13 +219,13 @@ _sending query results to your canvas_
 
 You can select images or text from your graph, a document, a file, or a webpage, copy them to your canvas, and convert them into discourse nodes.
 
-To convert an image, hover over it and click the convert icon that appears in its top-left corner. In the create node dialog, pick the node type, enter a title, and confirm. The image is replaced on the canvas by the new node and, if **Key Image** is enabled for that node type, added to the node's page.
+To convert an image, hover over it and click the convert icon that appears in its top-left corner. In the create node dialog, pick the node type, enter a title, and confirm. The image is replaced on the canvas by the new node and added to the node's page.
 
 You can also right-click an image or text shape and select **Convert To**, pick the node type, then modify the title as needed. Use this path to convert text shapes or to turn an image into a block.
 
 <Callout type="info" emoji="💡">
-  Remember to enable the **Key Image** feature in Settings if you want to
-  convert images to discourse nodes.
+  Enable the **Key Image** feature in Settings for a node type if you want its
+  canvas nodes to display the image.
 </Callout>
 
 <Image

From 72733d84a16c8bac40b138d37086faec9b7e3a97 Mon Sep 17 00:00:00 2001
From: Trang Doan <doantranghp2000@gmail.com>
Date: Wed, 9 Sep 2026 21:24:22 -0400
Subject: [PATCH 4/5] ENG-1356 Reuse the canvas asset URL instead of
 re-uploading the image

Dropped and pasted canvas files are already uploaded to Roam and stored as
the asset src, so conversion now reuses that URL and only uploads when the
src is a data or blob URL.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts b/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts
index 10ca8232d..13bd704ba 100644
--- a/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts
+++ b/apps/roam/src/components/canvas/convertShapeToDiscourseNode.ts
@@ -14,6 +14,8 @@ export const uploadImageShapeToRoam = async ({
   if (!assetId) return undefined;
   const asset = editor.getAsset(assetId);
   if (!asset || !asset.props.src) return undefined;
+  // Dropped and pasted files are already uploaded to Roam by the canvas handlers
+  if (asset.props.src.startsWith("https:")) return asset.props.src;
   const file = await fetch(asset.props.src)
     .then((r) => r.arrayBuffer())
     .then((buf) => new File([buf], shape.id));

From 71ef76484cd9e8d51b7bbf00f69d676af077b510 Mon Sep 17 00:00:00 2001
From: Trang Doan <doantranghp2000@gmail.com>
Date: Wed, 9 Sep 2026 21:34:50 -0400
Subject: [PATCH 5/5] ENG-1356 Match the dialog image preview to the Figma
 design

Use the same Label as the other fields so the Image caption is bold, and
render the preview at natural size flush left instead of centred.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/roam/src/components/ModifyNodeDialog.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/roam/src/components/ModifyNodeDialog.tsx b/apps/roam/src/components/ModifyNodeDialog.tsx
index 332d40907..9fcaefd1f 100644
--- a/apps/roam/src/components/ModifyNodeDialog.tsx
+++ b/apps/roam/src/components/ModifyNodeDialog.tsx
@@ -539,14 +539,14 @@ const ModifyNodeDialog = ({
           </div>
 
           {imageUrl && (
-            <div className="flex w-full flex-col gap-1">
-              <span>Image</span>
+            <Label className="w-full">
+              Image
               <img
                 src={imageUrl}
                 alt=""
-                className="max-h-40 w-full rounded object-contain"
+                className="mt-1 block max-h-40 max-w-full rounded"
               />
-            </div>
+            </Label>
           )}
 
           {/* Referenced Node Input */}