BloomBooks · nabalone · Jan 6, 2026
diff --git a/src/BloomBrowserUI/bookEdit/js/CanvasElementManager.ts b/src/BloomBrowserUI/bookEdit/js/CanvasElementManager.ts
@@ -529,6 +529,7 @@ export class CanvasElementManager {
         const bloomCanvases: HTMLElement[] = this.getAllBloomCanvasesOnPage();
 
         bloomCanvases.forEach((bloomCanvas) => {
+            this.setupBackgroundImageAttributes(bloomCanvas);
             this.adjustCanvasElementsForCurrentLanguage(bloomCanvas);
             this.ensureCanvasElementsIntersectParent(bloomCanvas);
             // image containers are already set by CSS to overflow:hidden, so they
@@ -6728,15 +6729,6 @@ export class CanvasElementManager {
             newImg.classList.remove("bloom-imageLoadError");
             newImgContainer.appendChild(newImg);
 
-            // Set level so Comical will consider the new canvas element to be under the existing ones.
-            const canvasElementElements = Array.from(
-                bloomCanvas.getElementsByClassName(kCanvasElementClass),
-            ) as HTMLElement[];
-            CanvasElementManager.putBubbleBefore(
-                bgCanvasElement,
-                canvasElementElements,
-                1,
-            );
             bgCanvasElement.style.visibility = "none"; // hide it until we adjust its shape and position
             // consistent with level, we want it in front of the (new, placeholder) background image
             // and behind the other canvas elements.
@@ -6772,12 +6764,31 @@ export class CanvasElementManager {
             "src",
             oldBgImage?.getAttribute("src") ?? "placeHolder.png",
         );
-        this.adjustBackgroundImageSize(bloomCanvas, bgCanvasElement, true);
-        bgCanvasElement.style.visibility = ""; // now we can show it, if it was new and hidden
-        SetupMetadataButton(bloomCanvas);
-        if (oldBgImage) {
-            oldBgImage.remove();
+        this.setupBackgroundImageAttributes(bloomCanvas, bgCanvasElement);
+    }
+
+    public setupBackgroundImageAttributes(
+        bloomCanvas: HTMLElement,
+        bgElement?: HTMLElement,
+    ) {
+        if (!bgElement) {
+            bgElement = bloomCanvas.getElementsByClassName(
+                kBackgroundImageClass,
+            )[0] as HTMLElement;
         }
+        if (bgElement.getAttribute("data-bubble")) {
+            return; // setup has already been done (data-bubble is added by putBubbleBefore)
+        }
+        // Newly added background image element has not yet been given its size
+        this.adjustBackgroundImageSize(bloomCanvas, bgElement, false);
+        // Set level so Comical will consider the new canvas element to be under the existing ones.
+        CanvasElementManager.putBubbleBefore(
+            bgElement,
+            Array.from(
+                bloomCanvas.getElementsByClassName(kCanvasElementClass),
+            ) as HTMLElement[],
+            1,
+        );
     }
 
     // Adjust the levels of all the bubbles of all the listed canvas elements so that

diff --git a/src/BloomBrowserUI/bookEdit/js/origami.ts b/src/BloomBrowserUI/bookEdit/js/origami.ts
@@ -507,12 +507,18 @@ function makeImageOrCanvasFieldClickHandler(
     const container = clickedElement.closest(".split-pane-component-inner");
     addUndoPoint();
     const bloomCanvas = $(
-        `<div class='bloom-canvas bloom-leadingElement'${
+        `<div class='bloom-canvas bloom-has-canvas-element bloom-leadingElement'${
             isCanvasClick ? ` data-tool-id='${kCanvasToolId}'` : ""
         }></div>`,
     );
+    const canvasElement = $(
+        "<div class='bloom-canvas-element bloom-backgroundImage' style='width:100%; height:100%;'></div>",
+    );
+    const imageContainer = $("<div class='bloom-imageContainer'></div>");
     const image = $("<img src='placeHolder.png'/>");
-    bloomCanvas.append(image);
+    imageContainer.append(image);
+    canvasElement.append(imageContainer);
+    bloomCanvas.append(canvasElement);
     SetupImage(image); // Must attach it first so event handler gets added to parent
     container.append(bloomCanvas);
     clickedElement.closest(".selector-links").remove();

diff --git a/src/BloomBrowserUI/placeHolderImages.less b/src/BloomBrowserUI/placeHolderImages.less
@@ -20,26 +20,11 @@
     .image-placeholder-background();
 }
 
-// When previewing templates in the Collection Tab, and also when in Change Layout mode in the Edit tab,
-// img elements may not be wrapped in canvas-element divs (see BL-15514). Also below.
-.preview:not([data-l1]), //  Real books always have a data-l1 attribute added
-.origami-layout-mode {
-    .bloom-canvas:not(:has(.bloom-canvas-element)):has(
-            img[src*="placeHolder.png"]
-        ) {
-        .image-placeholder-background();
-    }
-}
-
 // Use the easel placeholder instead of the usual flower placeholder for the background image whenever there is data-tool-id="canvas"
 // (there are no legacy-style templates that should have the easel icon)
 .bloom-canvas[data-tool-id="canvas"]
     .bloom-backgroundImage.bloom-canvas-element:has(
         img[src*="placeHolder.png"]
-    ),
-.origami-layout-mode
-    .bloom-canvas[data-tool-id="canvas"]:not(:has(.bloom-canvas-element)):has(
-        img[src*="placeHolder.png"]
     ) {
     background-image: @canvas-placeholder;
 }

diff --git a/src/BloomExe/Book/Book.cs b/src/BloomExe/Book/Book.cs
@@ -2640,7 +2640,7 @@ private void FixUrlEncodedCoverImageIfNeeded()
                 "//body/div[@id='bloomDataDiv']/div[@data-book='coverImage']"
             );
             if (node == null)
-                return; // shouldn't happen, but nothing to fix if it does.
+                return;
             var text = node.InnerText;
             if (
                 !String.IsNullOrWhiteSpace(text)

diff --git a/src/content/templates/bloom-foundation-mixins.pug b/src/content/templates/bloom-foundation-mixins.pug
@@ -116,9 +116,10 @@ mixin field-version1(placeholder)
 //- and sized when the page opens in our editor.
 mixin image
 	- requireZeroArguments('image', arguments);
-	.bloom-canvas&attributes(attributes)
-		img(src="placeHolder.png", width=attributes.initialImageWidth)
-		block
+	.bloom-canvas.bloom-has-canvas-element&attributes(attributes)
+		.bloom-canvas-element.bloom-backgroundImage(style="width:100%; height:100%;")
+			.bloom-imageContainer
+				img(src="placeHolder.png") 
 
 mixin video
 	- requireZeroArguments('video', arguments);

diff --git a/src/content/templates/template books/Activity/Activity.pug b/src/content/templates/template books/Activity/Activity.pug
@@ -51,6 +51,7 @@ html
 		//-Slider: +page("Word Picture Slider Activity", "An interactive page where the user chooses pictures to match words.").customPage.bloom-ignoreForReaderStats.bloom-interactive-page.no-margin-page.numberedPage#3325A8B6-EA15-4FB7-9F8D-271D7B3C8D58(data-page='extra' data-analyticscategories="drag-game" data-activity="drag-word-chooser-slider" data-tool-id="game" data-feature="game")
 		//- 	.split-pane-component-inner
 		//- 		//- there's a background image that fills the page. Todo: find a good one that doesn't take much space for a demo
+				// TODO Note: we have since made changes to the image mixins; check the behavior here 
 		//- 		+image
 		//- 			//- this div is moved to the bottom of the page and stretched to fill it by the javascript
 		//- 			//- then we copy images into it and allow them to be slid around.

diff --git a/src/content/templates/template books/Digital Comic Book/Digital Comic Book.htm b/src/content/templates/template books/Digital Comic Book/Digital Comic Book.htm
@@ -209,10 +209,18 @@
                         data-book="bookTitle"
                     ></div>
                 </div>
-                <div class="bloom-canvas">
-                    <img data-book="coverImage" src="placeHolder.png" />
+                <div class="bloom-canvas bloom-has-canvas-element">
+                    <div
+                        class="bloom-canvas-element bloom-backgroundImage"
+                        style="width: 100%; height: 100%"
+                    >
+                        <div class="bloom-imageContainer">
+                            <img data-book="coverImage" src="placeHolder.png" />
+                        </div>
+                    </div>
                 </div>
                 <div class="bottomBlock"></div>
+                `
             </div>
         </div>
 
@@ -240,8 +248,15 @@
 
             <div class="marginBox">
                 <div class="split-pane-component-inner">
-                    <div title="" class="bloom-canvas">
-                        <img src="placeHolder.png" alt="" />
+                    <div title="" class="bloom-canvas bloom-has-canvas-element">
+                        <div
+                            class="bloom-canvas-element bloom-backgroundImage"
+                            style="width: 100%; height: 100%"
+                        >
+                            <div class="bloom-imageContainer">
+                                <img src="placeHolder.png" />
+                            </div>
+                        </div>
                     </div>
                 </div>
             </div>

diff --git a/src/content/templates/template books/Games/Games.html b/src/content/templates/template books/Games/Games.html
@@ -193,9 +193,15 @@
                     </div>
                 </div>
 
-                <div class="bloom-canvas">
-                    <img data-book="coverImage" src="placeHolder.png" alt="" />
-
+                <div class="bloom-canvas bloom-has-canvas-element">
+                    <div
+                        class="bloom-canvas-element bloom-backgroundImage"
+                        style="width: 100%; height: 100%"
+                    >
+                        <div class="bloom-imageContainer">
+                            <img data-book="coverImage" src="placeHolder.png" />
+                        </div>
+                    </div>
                     <div
                         class="bloom-translationGroup bloom-imageDescription bloom-trailingElement"
                         data-default-languages="auto"

diff --git a/src/content/templates/template books/Paper Comic Book/Paper Comic Book.htm b/src/content/templates/template books/Paper Comic Book/Paper Comic Book.htm
@@ -183,8 +183,15 @@
                         data-book="bookTitle"
                     ></div>
                 </div>
-                <div class="bloom-canvas">
-                    <img data-book="coverImage" src="placeHolder.png" />
+                <div class="bloom-canvas bloom-has-canvas-element">
+                    <div
+                        class="bloom-canvas-element bloom-backgroundImage"
+                        style="width: 100%; height: 100%"
+                    >
+                        <div class="bloom-imageContainer">
+                            <img data-book="coverImage" src="placeHolder.png" />
+                        </div>
+                    </div>
                 </div>
                 <div class="bottomBlock"></div>
             </div>
@@ -214,12 +221,18 @@
 
             <div class="marginBox">
                 <div class="split-pane-component-inner">
-                    <div title="" class="bloom-canvas">
-                        <img
-                            class="bloom-imageObjectFit-cover"
-                            src="placeHolder.png"
-                            alt=""
-                        />
+                    <div class="bloom-canvas bloom-has-canvas-element">
+                        <div
+                            class="bloom-canvas-element bloom-backgroundImage"
+                            style="width: 100%; height: 100%"
+                        >
+                            <div class="bloom-imageContainer">
+                                <img
+                                    class="bloom-imageObjectFit-cover"
+                                    src="placeHolder.png"
+                                />
+                            </div>
+                        </div>
                     </div>
                 </div>
             </div>
@@ -252,14 +265,19 @@
                 <div class="split-pane-component-inner">
                     <div
                         title="placeHolder.png 6.58 KB 341 x 335 52 DPI (should be 300-600) Bit Depth: 32"
-                        class="bloom-canvas"
+                        class="bloom-canvas bloom-has-canvas-element"
                     >
-                        <img
-                            class="bloom-imageObjectFit-cover"
-                            src="placeHolder.png"
-                            alt=""
-                        />
-
+                        <div
+                            class="bloom-canvas-element bloom-backgroundImage"
+                            style="width: 100%; height: 100%"
+                        >
+                            <div class="bloom-imageContainer">
+                                <img
+                                    class="bloom-imageObjectFit-cover"
+                                    src="placeHolder.png"
+                                />
+                            </div>
+                        </div>
                         <div
                             class="bloom-canvas-element ui-resizable ui-draggable bloom-allowAutoShrink"
                             style="

diff --git a/src/content/templates/template books/Wall Calendar/Wall Calendar.pug b/src/content/templates/template books/Wall Calendar/Wall Calendar.pug
@@ -17,8 +17,10 @@ mixin field-classOnChild(internalClass)
 
 mixin image-largePage
 	- requireZeroArguments('image', arguments);
-	.bloom-canvas(style="opacity: 1; overflow: hidden;")
-		img(src="placeHolder.png", width=attributes.initialImageWidth)
+	.bloom-canvas.bloom-has-canvas-element(style="opacity: 1; overflow: hidden;")
+		.bloom-canvas-element.bloom-backgroundImage(style="width:100%; height:100%;")
+			.bloom-imageContainer
+				img(src="placeHolder.png")
 		block
 
 html

diff --git a/src/content/templates/template books/preview-xmatter-mixins.pug b/src/content/templates/template books/preview-xmatter-mixins.pug
@@ -23,8 +23,10 @@ mixin preview-cover-contents
 	.bottomBlock
 
 mixin preview-cover-image
-	.bloom-canvas
-		img(data-book="coverImage", src="placeHolder.png")
+	.bloom-canvas.bloom-has-canvas-element
+		.bloom-canvas-element.bloom-backgroundImage(style="width:100%; height:100%;")
+			.bloom-imageContainer
+				img(data-book="coverImage", src="placeHolder.png")
 
 mixin preview-outsideFrontCover
 	// FRONT COVER

diff --git a/src/content/templates/xMatter/TemplateStarter-XMatter/TemplateStarter-XMatter.pug b/src/content/templates/xMatter/TemplateStarter-XMatter/TemplateStarter-XMatter.pug
@@ -9,9 +9,11 @@ html
 		+stylesheets('TemplateStarter-XMatter.css')
 	body
 		+page-cover('Image For Thumbnail')(data-export='front-matter-cover', data-xmatter-page='frontCover')&attributes(attributes).frontCover.outsideFrontCover#36e4a8d9-c61c-496d-9f37-2cc274d28b34
-			.bloom-canvas
+			.bloom-canvas.bloom-has-canvas-element
 				label.bubble Simple line drawings look best. Instead of using this page, you can also make your own thumbnail.png file and set it to Read-only so Bloom doesn't write over it.
-				img(src='placeHolder.png' data-book='coverImage')
+				.bloom-canvas-element.bloom-backgroundImage(style="width:100%; height:100%;")
+					.bloom-imageContainer
+						img(data-book="coverImage", src="placeHolder.png")
 
 		+page-xmatter("About").bloom-frontMatter(data-export='front-matter-about',data-xmatter-page="about")#26e4a8d9-c61c-496d-9f37-2cc274d28b32
 			| Template Title

diff --git a/src/content/templates/xMatter/bloom-xmatter-mixins.pug b/src/content/templates/xMatter/bloom-xmatter-mixins.pug
@@ -154,11 +154,10 @@ mixin standard-cover-contents
 //- because the cover image description needs to have a data-book attribute
 //- so that the contents will survive changes to xmatter (and updates in bringBookUpToDate)
 mixin standard-cover-image
-	.bloom-canvas
-		//- We're using the old structure with the img a direct child of the bloom-canvas,
-		//- because we can't set the right size of the new background-image structure until
-		//- we've loaded the page into a browser.
-		img(data-book="coverImage", src="placeHolder.png")&attributes(attributes)
+	.bloom-canvas.bloom-has-canvas-element
+		.bloom-canvas-element.bloom-backgroundImage(style="width:100%; height:100%;")
+			.bloom-imageContainer
+				img(data-book="coverImage", src="placeHolder.png")&attributes(attributes)
 		+field-cover-image("auto").bloom-imageDescription.bloom-trailingElement
 
 mixin field-cover-image(languages)

diff --git a/...tter/project-specific/Afghan-Children-Read-Common/Afghan-Children-Read-XMatter-mixins.pug b/...tter/project-specific/Afghan-Children-Read-Common/Afghan-Children-Read-XMatter-mixins.pug
@@ -92,7 +92,7 @@ mixin afg-outsideFrontCover(langForBubbles)
 					+field-prototypeDeclaredExplicity("V").levelInfo
 						+hint-bubble(langForBubbles,'معلومات صنف، سمستر و سویه','د ټولگی، سمستر او سویي معلومات','Grade, Semester, and Level Information, in {lang}')
 						+editable(kLanguageForPrototypeOnly).Cover-Default-style.bloom-padForOverflow(data-book='levelInformation')
-
+		//- Note: we have since made changes to the image handling; check the behavior here if we revive this pug file.
 		.bloom-canvas.bloom-background-image-in-style-attr(data-book='coverImage', style="background-image:url('placeHolder.png')")
 
 		//- 2 columns: first for an optional logo, then text content
@@ -134,6 +134,7 @@ mixin afg-titlePage(langForBubbles)
 		.topBlock
 			+title-page-branding-top-left
 			.topContent.bishmallah
+				//- Note: we have since made changes to the image mixins; check the behavior here if we revive this pug file.
 				+image-xmatter('bishmallah')
 		+field-prototypeDeclaredExplicity("V")#titlePageTitleBlock
 			label.bubble Book title in {lang}

diff --git a/...fic/Afghan-Children-Read-Dari-Device-XMatter/Afghan-Children-Read-Dari-Device-XMatter.pug b/...fic/Afghan-Children-Read-Dari-Device-XMatter/Afghan-Children-Read-Dari-Device-XMatter.pug
@@ -1,4 +1,6 @@
 include ../Afghan-Children-Read-Dari-XMatter/Dari-XMatter-mixins.pug
+//- Note: we have since made changes to the image mixins which could affect behavior here if we revive this pug file.
+
 
 doctype html
 html

diff --git a/.../project-specific/Afghan-Children-Read-Dari-XMatter/Afghan-Children-Read-Dari-XMatter.pug b/.../project-specific/Afghan-Children-Read-Dari-XMatter/Afghan-Children-Read-Dari-XMatter.pug
@@ -1,4 +1,5 @@
 include Dari-XMatter-mixins.pug
+//- Note: we have since made changes to the image mixins which could affect behavior here if we revive this pug file.
 
 doctype html
 html

diff --git a/...Afghan-Children-Read-Pashto-Device-XMatter/Afghan-Children-Read-Pashto-Device-XMatter.pug b/...Afghan-Children-Read-Pashto-Device-XMatter/Afghan-Children-Read-Pashto-Device-XMatter.pug
@@ -1,4 +1,5 @@
 include ../Afghan-Children-Read-Pashto-XMatter/Pashto-XMatter-mixins.pug
+//- Note: we have since made changes to the image mixins which could affect behavior here if we revive this pug file.
 
 doctype html
 html

diff --git a/...ject-specific/Afghan-Children-Read-Pashto-XMatter/Afghan-Children-Read-Pashto-XMatter.pug b/...ject-specific/Afghan-Children-Read-Pashto-XMatter/Afghan-Children-Read-Pashto-XMatter.pug
@@ -1,4 +1,5 @@
 include Pashto-XMatter-mixins.pug
+//- Note: we have since made changes to the image mixins which could affect behavior here if we revive this pug file.
 
 doctype html
 html

diff --git a/...tent/templates/xMatter/project-specific/Kyrgyzstan2020-XMatter/Kyrgyzstan2020-XMatter.pug b/...tent/templates/xMatter/project-specific/Kyrgyzstan2020-XMatter/Kyrgyzstan2020-XMatter.pug
@@ -1,3 +1,5 @@
+//- Note: we have since made changes to the image mixins which could affect behavior here if we revive this pug file.
+
 extends ../../Traditional-XMatter/Traditional-XMatter.pug
 
 mixin divider