feat: set `appState.exportBackground` to `true` when exporting to `jpg` (#4342)

src/packages/excalidraw/CHANGELOG.md

@@ -13,6 +13,10 @@ Please add the latest change on the top under the correct section.
 
 ## Unreleased
 
+## Excalidraw API
+
+- [`exportToBlob`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#exportToBlob) now automatically sets `appState.exportBackground` to `true` if exporting to `image/jpeg` MIME type (to ensure that alpha channel is not compressed to black color).
+
 ### Features
 
 - #### BREAKING CHANGE

src/packages/excalidraw/README.md

@@ -828,6 +828,8 @@ import { exportToBlob } from "@excalidraw/excalidraw";
 
 Returns a promise which resolves with a [blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob). It internally uses [canvas.ToBlob](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob).
 
+Note: `appState.exportBackground` is always set to `true` if exporting to `image/jpeg` to ensure the alpha channel isn't compressed to black.
+
 #### `exportToSvg`
 
 **_Signature_**

src/packages/utils.ts

@@ -80,8 +80,6 @@ export const exportToBlob = async (
     quality?: number;
   },
 ): Promise<Blob | null> => {
-  const canvas = await exportToCanvas(opts);
-
   let { mimeType = MIME_TYPES.png, quality } = opts;
 
   if (mimeType === MIME_TYPES.png && typeof quality === "number") {
@@ -93,6 +91,18 @@ export const exportToBlob = async (
     mimeType = MIME_TYPES.jpg;
   }
 
+  if (mimeType === MIME_TYPES.jpg && !opts.appState?.exportBackground) {
+    console.warn(
+      `Defaulting "exportBackground" to "true" for "${MIME_TYPES.jpg}" mimeType`,
+    );
+    opts = {
+      ...opts,
+      appState: { ...opts.appState, exportBackground: true },
+    };
+  }
+
+  const canvas = await exportToCanvas(opts);
+
   quality = quality ? quality : /image\/jpe?g/.test(mimeType) ? 0.92 : 0.8;
 
   return new Promise((resolve) => {

src/tests/packages/utils.test.ts

@@ -42,6 +42,9 @@ describe("exportToBlob", () => {
         getDimensions: (width, height) => ({ width, height, scale: 1 }),
         // testing typo in MIME type (jpg → jpeg)
         mimeType: "image/jpg",
+        appState: {
+          exportBackground: true,
+        },
       });
       expect(blob?.type).toBe(MIME_TYPES.jpg);
     });