feat: support TIFF images in DOCX rendering (#2284)

* feat: support TIFF images in DOCX rendering

TIFF images in DOCX files rendered as broken icons because browsers
cannot natively display image/tiff. Convert TIFF to PNG at import time
using utif2, following the existing EMF/WMF → SVG conversion pattern.

Closes #2064

* fix: enforce pixel limit before TIFF decode to prevent DoS

Reject TIFF images exceeding 100M pixels before allocating RGBA buffers
or canvas, preventing a malicious TIFF with extreme dimensions from
freezing or crashing the tab during import.

* fix: validate TIFF dimensions before decoding and correct .tif MIME type

Move MAX_PIXEL_COUNT check before UTIF.decodeImage/toRGBA8 so oversized
TIFFs are rejected before allocating the RGBA buffer.

Map .tif extension to image/tiff in Content_Types.xml generation to
avoid emitting the invalid MIME type image/tif.

* fix: read TIFF dimensions from raw IFD tags for pre-decode validation

UTIF.decode populates raw tag entries (t256/t257) but .width/.height
are only set after decodeImage. Read from raw tags so the pixel limit
guard works before the expensive decode step without rejecting valid
files.

* fix: address PR review feedback for TIFF support

- Use mimeTypeForExt mapping for .tif data URIs (image/tiff not image/tif)
- Remove unused size arg from convertTiffToPng call
- Add happy-path test asserting valid TIFF produces PNG data URI

* fix: clean up convertTiffToPng signature and add wiring test

- Remove unused Uint8Array/ArrayBufferView branches (only strings are passed)
- Add handleImageNode test verifying convertTiffToPng is called for .tif files

* test: add integration test for TIFF image loading pipeline

Adds a Playwright test that loads a minimal DOCX containing a TIFF image
and verifies the full pipeline: DocxZipper → convertTiffToPng → rendered PNG.

* refactor: replace utif2 with image-js/tiff and deduplicate DocxZipper constants

Replace unmaintained utif2 with actively maintained image-js/tiff for
TIFF decoding. Extract duplicated IMAGE_EXTS and MIME_TYPE_FOR_EXT
mappings in DocxZipper.js to module-level constants.

* fix: pre-decode size guard and 16-bit TIFF normalization

Use decode(buffer, { ignoreImageData: true }) to check dimensions
before allocating pixel data, preventing DoS from small compressed
TIFFs with huge dimensions. Normalize Uint16Array and Float32Array
pixel data to 8-bit for canvas compatibility.

* test: add TIFF MIME, fallback, and branch coverage tests; extract shared dataUriToArrayBuffer helper

Address remaining PR review feedback: add tests for .tif → image/tiff MIME mapping
(import data URI and export Content_Types), TIFF conversion failure fallback alt text,
greyscale/grey+alpha/Uint16/Float32 toRGBA branches, and extract duplicate data-URI-stripping
logic from metafile-converter and tiff-converter into shared dataUriToArrayBuffer in helpers.js.

* fix: revert to utif2 for TIFF decoding

image-js/tiff lacks support for PackBits, JPEG, and CCITT compression
formats commonly found in Word documents. utif2 handles all TIFF
compression types via its toRGBA8 pipeline. Updated tests to match
utif2 API (decode → decodeImage → toRGBA8).

* fix: prefer domEnvironment over global document in createCanvas

- createCanvas() now checks domEnvironment first, fixing silent failures
  in JSDOM environments where global document lacks canvas support
- Add dataUriToArrayBuffer unit tests covering all input branches and
  both throw paths
- Add explanatory comment for query-string module re-imports in tests

---------

Co-authored-by: G Pardhiv Varma <gpardhivvarma@gmail.com>

Author: caio-pizzol

packages/super-editor/package.json

@@ -101,6 +101,7 @@
     "remark-parse": "catalog:",
     "remark-stringify": "catalog:",
     "unified": "catalog:",
+    "utif2": "catalog:",
     "uuid": "catalog:",
     "vue": "catalog:",
     "xml-js": "catalog:"

packages/super-editor/src/core/DocxZipper.js

@@ -5,6 +5,12 @@ import { ensureXmlString, isXmlLike } from './encoding-helpers.js';
 import { DOCX } from '@superdoc/common';
 import { COMMENT_FILE_BASENAMES } from './super-converter/constants.js';
 
+/** Image file extensions recognized during import and export. */
+const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'bmp', 'tiff', 'tif', 'emf', 'wmf', 'svg', 'webp']);
+
+/** Map file extensions to correct MIME sub-types where they differ. */
+const MIME_TYPE_FOR_EXT = { tif: 'tiff' };
+
 /**
  * Class to handle unzipping and zipping of docx files
  */
@@ -63,19 +69,18 @@ class DocxZipper {
           const fileBase64 = await zipEntry.async('base64');
           let extension = this.getFileExtension(name)?.toLowerCase();
           // Only build data URIs for images; keep raw base64 for other binaries (e.g., xlsx)
-          const imageTypes = new Set(['png', 'jpg', 'jpeg', 'gif', 'bmp', 'tiff', 'emf', 'wmf', 'svg', 'webp']);
-
           // For unknown extensions (like .tmp), try to detect the image type from content
           let detectedType = null;
-          if (!imageTypes.has(extension) || extension === 'tmp') {
+          if (!IMAGE_EXTS.has(extension) || extension === 'tmp') {
             detectedType = detectImageType(fileBase64);
             if (detectedType) {
               extension = detectedType;
             }
           }
 
-          if (imageTypes.has(extension)) {
-            this.mediaFiles[name] = `data:image/${extension};base64,${fileBase64}`;
+          if (IMAGE_EXTS.has(extension)) {
+            const mimeSubtype = MIME_TYPE_FOR_EXT[extension] || extension;
+            this.mediaFiles[name] = `data:image/${mimeSubtype};base64,${fileBase64}`;
             const blob = await zipEntry.async('blob');
             const fileObj = new File([blob], name, { type: blob.type });
             const imageUrl = URL.createObjectURL(fileObj);
@@ -105,10 +110,9 @@ class DocxZipper {
    */
   async updateContentTypes(docx, media, fromJson, updatedDocs = {}) {
     const additionalPartNames = Object.keys(updatedDocs || {});
-    const imageExts = new Set(['png', 'jpg', 'jpeg', 'gif', 'bmp', 'tiff', 'emf', 'wmf', 'svg', 'webp']);
     const newMediaTypes = Object.keys(media)
       .map((name) => this.getFileExtension(name))
-      .filter((ext) => ext && imageExts.has(ext));
+      .filter((ext) => ext && IMAGE_EXTS.has(ext));
 
     const contentTypesPath = '[Content_Types].xml';
     let contentTypesXml;
@@ -131,7 +135,8 @@ class DocxZipper {
       if (defaultMediaTypes.includes(type)) continue;
       if (seenTypes.has(type)) continue;
 
-      const newContentType = `<Default Extension="${type}" ContentType="image/${type}"/>`;
+      const mime = MIME_TYPE_FOR_EXT[type] || type;
+      const newContentType = `<Default Extension="${type}" ContentType="image/${mime}"/>`;
       typesString += newContentType;
       seenTypes.add(type);
     }

packages/super-editor/src/core/DocxZipper.test.js

@@ -338,6 +338,64 @@ describe('DocxZipper - exportFromCollaborativeDocx media handling', () => {
   });
 });
 
+describe('DocxZipper - .tif MIME type mapping', () => {
+  it('produces image/tiff data URI for .tif files on import', async () => {
+    const zipper = new DocxZipper();
+    const zip = new JSZip();
+
+    const contentTypes = `<?xml version="1.0" encoding="UTF-8"?>
+      <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+        <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+        <Default Extension="xml" ContentType="application/xml"/>
+        <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+      </Types>`;
+    zip.file('[Content_Types].xml', contentTypes);
+    zip.file('word/document.xml', '<w:document/>');
+
+    // Arbitrary binary data stored as a .tif file
+    const tifData = new Uint8Array([0x49, 0x49, 0x2a, 0x00, 0x08, 0x00, 0x00, 0x00]);
+    zip.file('word/media/image1.tif', tifData);
+
+    const buf = await zip.generateAsync({ type: 'arraybuffer' });
+    await zipper.getDocxData(buf, false);
+
+    // Must use image/tiff, not image/tif
+    expect(zipper.mediaFiles['word/media/image1.tif']).toMatch(/^data:image\/tiff;base64,/);
+  });
+
+  it('writes image/tiff content type in [Content_Types].xml on export', async () => {
+    const zipper = new DocxZipper();
+
+    const contentTypes = `<?xml version="1.0" encoding="UTF-8"?>
+      <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+        <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+        <Default Extension="xml" ContentType="application/xml"/>
+        <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+      </Types>`;
+
+    const docx = [
+      { name: '[Content_Types].xml', content: contentTypes },
+      { name: 'word/document.xml', content: '<w:document/>' },
+    ];
+
+    const result = await zipper.updateZip({
+      docx,
+      updatedDocs: {},
+      media: { 'word/media/image1.tif': 'AAAA' },
+      fonts: {},
+      isHeadless: true,
+    });
+
+    const readBack = await new JSZip().loadAsync(result);
+    const updatedContentTypes = await readBack.file('[Content_Types].xml').async('string');
+
+    // Should contain Extension="tif" with ContentType="image/tiff"
+    expect(updatedContentTypes).toContain('Extension="tif"');
+    expect(updatedContentTypes).toContain('ContentType="image/tiff"');
+    expect(updatedContentTypes).not.toContain('ContentType="image/tif"');
+  });
+});
+
 describe('DocxZipper - .tmp image file detection', () => {
   it('detects and processes .tmp files with PNG signatures as PNG images', async () => {
     const zipper = new DocxZipper();

packages/super-editor/src/core/super-converter/helpers.js

@@ -33,6 +33,33 @@ function base64ToUint8Array(base64) {
   return bytes;
 }
 
+/**
+ * Convert a base64 string or data URI to an ArrayBuffer.
+ * Accepts ArrayBuffer, TypedArray, data URI, or raw base64 string.
+ *
+ * @param {string|ArrayBuffer|Uint8Array} data
+ * @returns {ArrayBuffer}
+ */
+function dataUriToArrayBuffer(data) {
+  if (data instanceof ArrayBuffer) return data;
+  if (ArrayBuffer.isView(data)) return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+
+  if (typeof data !== 'string') {
+    throw new Error('Unsupported data type for conversion to ArrayBuffer');
+  }
+
+  let base64 = data;
+  if (data.startsWith('data:')) {
+    const commaIndex = data.indexOf(',');
+    if (commaIndex === -1) {
+      throw new Error('Invalid data URI: missing base64 content');
+    }
+    base64 = data.substring(commaIndex + 1);
+  }
+
+  return base64ToUint8Array(base64).buffer;
+}
+
 // CSS pixels per inch; used to convert between Word's inch-based measurements and DOM pixels.
 const PIXELS_PER_INCH = 96;
 
@@ -720,5 +747,6 @@ export {
   resolveOpcTargetPath,
   computeCrc32Hex,
   base64ToUint8Array,
+  dataUriToArrayBuffer,
   detectImageType,
 };

packages/super-editor/src/core/super-converter/helpers.test.js

@@ -7,6 +7,7 @@ import {
   getArrayBufferFromUrl,
   computeCrc32Hex,
   base64ToUint8Array,
+  dataUriToArrayBuffer,
   detectImageType,
 } from './helpers.js';
 
@@ -385,6 +386,43 @@ describe('base64ToUint8Array', () => {
   });
 });
 
+describe('dataUriToArrayBuffer', () => {
+  it('returns the same ArrayBuffer when given an ArrayBuffer', () => {
+    const buf = new ArrayBuffer(4);
+    expect(dataUriToArrayBuffer(buf)).toBe(buf);
+  });
+
+  it('slices a TypedArray into a new ArrayBuffer', () => {
+    const bytes = new Uint8Array([10, 20, 30, 40]);
+    const result = dataUriToArrayBuffer(bytes);
+    expect(result).toBeInstanceOf(ArrayBuffer);
+    expect(Array.from(new Uint8Array(result))).toEqual([10, 20, 30, 40]);
+  });
+
+  it('decodes a data URI string', () => {
+    const bytes = new Uint8Array([11, 22, 33]);
+    const base64 = Buffer.from(bytes).toString('base64');
+    const result = dataUriToArrayBuffer(`data:image/tiff;base64,${base64}`);
+    expect(Array.from(new Uint8Array(result))).toEqual([11, 22, 33]);
+  });
+
+  it('decodes a raw base64 string', () => {
+    const bytes = new Uint8Array([55, 66, 77]);
+    const base64 = Buffer.from(bytes).toString('base64');
+    const result = dataUriToArrayBuffer(base64);
+    expect(Array.from(new Uint8Array(result))).toEqual([55, 66, 77]);
+  });
+
+  it('throws on a data URI missing the comma', () => {
+    expect(() => dataUriToArrayBuffer('data:image/png;base64')).toThrow('Invalid data URI');
+  });
+
+  it('throws on unsupported data types', () => {
+    expect(() => dataUriToArrayBuffer(12345)).toThrow('Unsupported data type');
+    expect(() => dataUriToArrayBuffer({})).toThrow('Unsupported data type');
+  });
+});
+
 describe('detectImageType', () => {
   it('detects PNG from magic bytes', () => {
     // PNG signature: 89 50 4E 47 0D 0A 1A 0A

packages/super-editor/src/core/super-converter/v3/handlers/w/p/helpers/legacy-handle-paragraph-node.test.js

@@ -13,12 +13,16 @@ vi.mock('@converter/v2/importer/index.js', () => ({
 }));
 
 // Simple and predictable conversion for positions
-vi.mock('@converter/helpers.js', () => ({
-  twipsToPixels: (twips) => (twips === undefined ? undefined : Number(twips) / 20),
-  twipsToInches: (twips) => (twips === undefined ? undefined : Number(twips) / 10),
-  twipsToLines: (twips) => (twips === undefined ? undefined : Number(twips) / 240),
-  pixelsToTwips: (pixels) => (pixels === undefined ? undefined : Math.round(Number(pixels) * 20)),
-}));
+vi.mock('@converter/helpers.js', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    twipsToPixels: (twips) => (twips === undefined ? undefined : Number(twips) / 20),
+    twipsToInches: (twips) => (twips === undefined ? undefined : Number(twips) / 10),
+    twipsToLines: (twips) => (twips === undefined ? undefined : Number(twips) / 240),
+    pixelsToTwips: (pixels) => (pixels === undefined ? undefined : Math.round(Number(pixels) * 20)),
+  };
+});
 
 import { handleParagraphNode } from './legacy-handle-paragraph-node.js';
 import { parseMarks, mergeTextNodes } from '@converter/v2/importer/index.js';

packages/super-editor/src/core/super-converter/v3/handlers/wp/helpers/decode-image-node-helpers.test.js

@@ -5,18 +5,22 @@ import {
 import * as helpers from '@converter/helpers.js';
 import * as annotationHelpers from '@converter/v3/handlers/w/sdt/helpers/translate-field-annotation.js';
 
-vi.mock('@converter/helpers.js', () => ({
-  emuToPixels: vi.fn((v) => v / 9525), // 1 emu ≈ 1/9525 px
-  pixelsToEmu: vi.fn((v) => v * 9525),
-  getTextIndentExportValue: vi.fn((v) => v),
-  inchesToTwips: vi.fn((v) => v),
-  linesToTwips: vi.fn((v) => v),
-  pixelsToEightPoints: vi.fn((v) => v),
-  pixelsToTwips: vi.fn((v) => v),
-  ptToTwips: vi.fn((v) => v),
-  rgbToHex: vi.fn(() => '#000000'),
-  degreesToRot: vi.fn((v) => v),
-}));
+vi.mock('@converter/helpers.js', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    emuToPixels: vi.fn((v) => v / 9525), // 1 emu ≈ 1/9525 px
+    pixelsToEmu: vi.fn((v) => v * 9525),
+    getTextIndentExportValue: vi.fn((v) => v),
+    inchesToTwips: vi.fn((v) => v),
+    linesToTwips: vi.fn((v) => v),
+    pixelsToEightPoints: vi.fn((v) => v),
+    pixelsToTwips: vi.fn((v) => v),
+    ptToTwips: vi.fn((v) => v),
+    rgbToHex: vi.fn(() => '#000000'),
+    degreesToRot: vi.fn((v) => v),
+  };
+});
 
 vi.mock('@converter/v3/handlers/w/sdt/helpers/translate-field-annotation.js', () => ({
   prepareTextAnnotation: vi.fn(() => ({ type: 'text', text: 'annotation' })),

packages/super-editor/src/core/super-converter/v3/handlers/wp/helpers/encode-image-node-helpers.js

@@ -8,6 +8,7 @@ import {
   extractCustomGeometry,
 } from './vector-shape-helpers';
 import { convertMetafileToSvg, isMetafileExtension, setMetafileDomEnvironment } from './metafile-converter.js';
+import { convertTiffToPng, isTiffExtension, setTiffDomEnvironment } from './tiff-converter.js';
 import {
   collectTextBoxParagraphs,
   preProcessTextBoxContent,
@@ -405,6 +406,22 @@ export function handleImageNode(node, params, isAnchor) {
     }
   }
 
+  // Convert TIFF images to PNG for display (browsers cannot render TIFF natively)
+  if (!wasConverted && isTiffExtension(extension)) {
+    const mediaData = converter?.media?.[path];
+    if (mediaData) {
+      if (converter?.domEnvironment) {
+        setTiffDomEnvironment(converter.domEnvironment);
+      }
+      const conversionResult = convertTiffToPng(mediaData);
+      if (conversionResult?.dataUri) {
+        finalSrc = conversionResult.dataUri;
+        finalExtension = conversionResult.format || 'png';
+        wasConverted = true;
+      }
+    }
+  }
+
   // For converted metafile images (EMF+/WMF+ placeholders), we want them to render
   // as block-level images, not inline. We use the original wrap type if available,
   // otherwise default to the original wrap settings.
@@ -416,8 +433,8 @@ export function handleImageNode(node, params, isAnchor) {
     // originalXml: carbonCopy(node),
     src: finalSrc,
     alt:
-      isMetafileExtension(extension) && !wasConverted
-        ? 'Unable to render EMF/WMF image'
+      (isMetafileExtension(extension) || isTiffExtension(extension)) && !wasConverted
+        ? 'Unable to render image'
         : docPr?.attributes?.name || 'Image',
     extension: finalExtension,
     // Store original path and extension for potential round-tripping

packages/super-editor/src/core/super-converter/v3/handlers/wp/helpers/encode-image-node-helpers.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { handleImageNode, getVectorShape } from './encode-image-node-helpers.js';
 import { emuToPixels, polygonToObj, rotToDegrees } from '@converter/helpers.js';
 import { extractFillColor, extractStrokeColor, extractStrokeWidth, extractLineEnds } from './vector-shape-helpers.js';
+import { convertTiffToPng } from './tiff-converter.js';
 
 vi.mock('@converter/helpers.js', async (importOriginal) => {
   const actual = await importOriginal();
@@ -21,6 +22,14 @@ vi.mock('./vector-shape-helpers.js', () => ({
   extractCustomGeometry: vi.fn(),
 }));
 
+vi.mock('./tiff-converter.js', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    convertTiffToPng: vi.fn(actual.convertTiffToPng),
+  };
+});
+
 describe('handleImageNode', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -221,6 +230,34 @@ describe('handleImageNode', () => {
     expect(result.attrs.size).toEqual({ width: 5, height: 6 }); // emuToPixels mocked
   });
 
+  it('calls convertTiffToPng for .tif images', () => {
+    convertTiffToPng.mockReturnValue({ dataUri: 'data:image/png;base64,fake', format: 'png' });
+    const node = makeNode();
+    const params = {
+      ...makeParams('media/photo.tif'),
+      converter: { media: { 'word/media/photo.tif': 'data:image/tiff;base64,AAAA' } },
+    };
+    const result = handleImageNode(node, params, false);
+
+    expect(convertTiffToPng).toHaveBeenCalledWith('data:image/tiff;base64,AAAA');
+    expect(result.attrs.src).toBe('data:image/png;base64,fake');
+    expect(result.attrs.extension).toBe('png');
+  });
+
+  it('returns alt text when convertTiffToPng returns null', () => {
+    convertTiffToPng.mockReturnValue(null);
+    const node = makeNode();
+    const params = {
+      ...makeParams('media/photo.tif'),
+      converter: { media: { 'word/media/photo.tif': 'data:image/tiff;base64,AAAA' } },
+    };
+    const result = handleImageNode(node, params, false);
+
+    expect(convertTiffToPng).toHaveBeenCalledWith('data:image/tiff;base64,AAAA');
+    expect(result.attrs.alt).toBe('Unable to render image');
+    expect(result.attrs.extension).toBe('tif');
+  });
+
   it('captures unhandled drawing children for passthrough preservation', () => {
     const node = makeNode();
     node.elements.push({
@@ -292,7 +329,7 @@ describe('handleImageNode', () => {
     const node = makeNode();
     const params = makeParams('media/pic.emf');
     const result = handleImageNode(node, params, false);
-    expect(result.attrs.alt).toBe('Unable to render EMF/WMF image');
+    expect(result.attrs.alt).toBe('Unable to render image');
     expect(result.attrs.extension).toBe('emf');
   });