From b78794f9ccdb59ee8e57366bda7c8e0c8eab7f44 Mon Sep 17 00:00:00 2001 From: Akanshu Singh Date: Wed, 5 Aug 2026 13:39:01 +0530 Subject: [PATCH 1/6] fix: Fixes HEIC uploads hanging indefinitely when ImageDecoder stalls --- packages/upload-media/src/canvas-utils.ts | 31 +++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/packages/upload-media/src/canvas-utils.ts b/packages/upload-media/src/canvas-utils.ts index ad2dee96e368ae..6d1d5fb8b66b2b 100644 --- a/packages/upload-media/src/canvas-utils.ts +++ b/packages/upload-media/src/canvas-utils.ts @@ -5,6 +5,16 @@ import { getFileBasename } from './utils'; import { parseHeic } from './heic-parser'; import { getHeicUnsupportedMessage } from './heic-support'; +/** + * Some platforms (e.g. Windows without the HEVC extension) have + * ImageDecoder.isTypeSupported() optimistically report HEIC support based on + * container-format detection alone. When the underlying platform codec isn't + * actually available, decoder.decode() doesn't reject, it just never settles. + * This timeout guards against that by force-closing the decoder, which per + * the WebCodecs spec rejects any of its pending decode() calls. + */ +const IMAGE_DECODER_TIMEOUT = 3000; + /** * Converts an image file to JPEG using the browser's native decoder and canvas. * @@ -69,7 +79,17 @@ export async function canvasConvertToJpeg( data: file.stream(), } ); try { - const { image: videoFrame } = await decoder.decode(); + const { image: videoFrame } = await Promise.race( [ + decoder.decode(), + new Promise< never >( ( _resolve, reject ) => { + setTimeout( () => { + decoder.close(); + reject( + new Error( 'ImageDecoder decode timed out' ) + ); + }, IMAGE_DECODER_TIMEOUT ); + } ), + ] ); try { const canvas = new OffscreenCanvas( videoFrame.displayWidth, @@ -94,8 +114,15 @@ export async function canvasConvertToJpeg( } finally { videoFrame.close(); } + } catch { + // decode() rejected, timed out, or the platform doesn't + // actually support the codec. Fall through to strategy 3. } finally { - decoder.close(); + try { + decoder.close(); + } catch { + // Already closed by the timeout handler above. + } } } } From 66ea844147dc6417dab8d2d6eb24d1b18dc4f801 Mon Sep 17 00:00:00 2001 From: Akanshu Singh Date: Thu, 6 Aug 2026 12:30:26 +0530 Subject: [PATCH 2/6] fix: Fixes empty file type issue in OS that lacks OS-Level codec --- packages/upload-media/src/store/constants.ts | 10 ++++++++++ .../upload-media/src/store/private-actions.ts | 20 ++++++++++++++++--- packages/upload-media/src/utils.ts | 18 +++++++++++++++++ 3 files changed, 45 insertions(+), 3 deletions(-) diff --git a/packages/upload-media/src/store/constants.ts b/packages/upload-media/src/store/constants.ts index 0ca15590a01318..b82f83f11febb0 100644 --- a/packages/upload-media/src/store/constants.ts +++ b/packages/upload-media/src/store/constants.ts @@ -55,3 +55,13 @@ export const HEIC_MIME_TYPES: readonly string[] = [ 'image/heic', 'image/heif', ] as const; + +/** + * HEIC/HEIF file extensions. + * + * Used as a fallback when the browser can't report a MIME type at all + * (`file.type === ''`), which happens for HEIC files on platforms that lack + * the OS-level codec needed to identify the format (e.g. Windows without the + * HEVC Video Extension). + */ +export const HEIC_EXTENSIONS: readonly string[] = [ 'heic', 'heif' ] as const; diff --git a/packages/upload-media/src/store/private-actions.ts b/packages/upload-media/src/store/private-actions.ts index 401305d74841ec..1ecdb7fe4454fb 100644 --- a/packages/upload-media/src/store/private-actions.ts +++ b/packages/upload-media/src/store/private-actions.ts @@ -19,6 +19,7 @@ import { convertBlobToFile, isAnimatedGif, renameFile, + hasFileExtension, } from '../utils'; import { canvasConvertToJpeg } from '../canvas-utils'; import { getHeicUnsupportedMessage } from '../heic-support'; @@ -28,7 +29,11 @@ import { exceedsClientProcessingMemory, } from '../feature-detection'; import { getImageDimensions } from '../get-image-dimensions'; -import { CLIENT_SIDE_SUPPORTED_MIME_TYPES, HEIC_MIME_TYPES } from './constants'; +import { + CLIENT_SIDE_SUPPORTED_MIME_TYPES, + HEIC_MIME_TYPES, + HEIC_EXTENSIONS, +} from './constants'; import { StubFile } from '../stub-file'; import { ErrorCode, UploadError } from '../upload-error'; import { debug, measure } from './utils/debug-logger'; @@ -834,11 +839,20 @@ export function prepareItem( id: QueueItemId ) { let heicJpeg: File | null = null; - const isImage = file.type.startsWith( 'image/' ); + // Browsers report an empty file.type for HEIC files on platforms that + // lack the OS-level HEVC codec needed to identify the format (e.g. + // Windows without the HEVC Video Extension). Fall back to sniffing the + // file extension so these files still reach the HEIC handling below + // instead of silently uploading as an undecodable, unconverted file. + const isHeicByExtension = + ! file.type && hasFileExtension( file.name, HEIC_EXTENSIONS ); + + const isImage = file.type.startsWith( 'image/' ) || isHeicByExtension; const isVipsSupported = CLIENT_SIDE_SUPPORTED_MIME_TYPES.includes( file.type ); - const isHeic = HEIC_MIME_TYPES.includes( file.type ); + const isHeic = + HEIC_MIME_TYPES.includes( file.type ) || isHeicByExtension; // Gate very large images out of client-side processing. wasm-vips is // capped at 1 GiB of memory, so high-megapixel images, especially diff --git a/packages/upload-media/src/utils.ts b/packages/upload-media/src/utils.ts index 3e55229d7ebc98..0f4151122d4283 100644 --- a/packages/upload-media/src/utils.ts +++ b/packages/upload-media/src/utils.ts @@ -83,6 +83,24 @@ export function getFileExtension( file: string ): string | null { return file.includes( '.' ) ? file.split( '.' ).pop() || null : null; } +/** + * Checks whether a file name has one of the given extensions. + * + * Case-insensitive, since filesystems and cameras don't agree on casing + * (e.g. "IMG_1234.HEIC"). + * + * @param name File name. + * @param extensions Extensions to match against, without the leading dot. + * @return Whether the file name ends in one of the given extensions. + */ +export function hasFileExtension( + name: string, + extensions: readonly string[] +): boolean { + const extension = getFileExtension( name )?.toLowerCase(); + return !! extension && extensions.includes( extension ); +} + /** * Returns file basename without extension. * From 67c16e51f901d360715e595565d5239b7946a57b Mon Sep 17 00:00:00 2001 From: Akanshu Singh Date: Thu, 6 Aug 2026 12:38:40 +0530 Subject: [PATCH 3/6] feat: Captures timeoutId and clear in the finally --- packages/upload-media/src/canvas-utils.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/upload-media/src/canvas-utils.ts b/packages/upload-media/src/canvas-utils.ts index 6d1d5fb8b66b2b..14e51d7b36e6db 100644 --- a/packages/upload-media/src/canvas-utils.ts +++ b/packages/upload-media/src/canvas-utils.ts @@ -78,11 +78,12 @@ export async function canvasConvertToJpeg( type: file.type, data: file.stream(), } ); + let timeoutId: ReturnType< typeof setTimeout > | undefined; try { const { image: videoFrame } = await Promise.race( [ decoder.decode(), new Promise< never >( ( _resolve, reject ) => { - setTimeout( () => { + timeoutId = setTimeout( () => { decoder.close(); reject( new Error( 'ImageDecoder decode timed out' ) @@ -118,6 +119,7 @@ export async function canvasConvertToJpeg( // decode() rejected, timed out, or the platform doesn't // actually support the codec. Fall through to strategy 3. } finally { + clearTimeout( timeoutId ); try { decoder.close(); } catch { From 9991048d65ece51262d90c997475b4f02668a651 Mon Sep 17 00:00:00 2001 From: Aki Hamano Date: Mon, 10 Aug 2026 16:38:03 +0900 Subject: [PATCH 4/6] fix: Detect untyped HEIC uploads from the file header instead of the extension Co-Authored-By: Claude --- packages/upload-media/src/store/constants.ts | 10 -- .../upload-media/src/store/private-actions.ts | 20 ++-- .../upload-media/src/test/is-heic-buffer.ts | 45 ++++++++ packages/upload-media/src/utils.ts | 103 +++++++++++++++--- 4 files changed, 138 insertions(+), 40 deletions(-) create mode 100644 packages/upload-media/src/test/is-heic-buffer.ts diff --git a/packages/upload-media/src/store/constants.ts b/packages/upload-media/src/store/constants.ts index b82f83f11febb0..0ca15590a01318 100644 --- a/packages/upload-media/src/store/constants.ts +++ b/packages/upload-media/src/store/constants.ts @@ -55,13 +55,3 @@ export const HEIC_MIME_TYPES: readonly string[] = [ 'image/heic', 'image/heif', ] as const; - -/** - * HEIC/HEIF file extensions. - * - * Used as a fallback when the browser can't report a MIME type at all - * (`file.type === ''`), which happens for HEIC files on platforms that lack - * the OS-level codec needed to identify the format (e.g. Windows without the - * HEVC Video Extension). - */ -export const HEIC_EXTENSIONS: readonly string[] = [ 'heic', 'heif' ] as const; diff --git a/packages/upload-media/src/store/private-actions.ts b/packages/upload-media/src/store/private-actions.ts index 8e97f27f1e005e..2cc632b3f81f19 100644 --- a/packages/upload-media/src/store/private-actions.ts +++ b/packages/upload-media/src/store/private-actions.ts @@ -7,8 +7,8 @@ import { cloneFile, convertBlobToFile, isAnimatedGif, + isHeicBuffer, renameFile, - hasFileExtension, } from '../utils'; import { canvasConvertToJpeg } from '../canvas-utils'; import { getHeicUnsupportedMessage } from '../heic-support'; @@ -18,11 +18,7 @@ import { exceedsClientProcessingMemory, } from '../feature-detection'; import { getImageDimensions } from '../get-image-dimensions'; -import { - CLIENT_SIDE_SUPPORTED_MIME_TYPES, - HEIC_MIME_TYPES, - HEIC_EXTENSIONS, -} from './constants'; +import { CLIENT_SIDE_SUPPORTED_MIME_TYPES, HEIC_MIME_TYPES } from './constants'; import { StubFile } from '../stub-file'; import { ErrorCode, UploadError } from '../upload-error'; import { debug, measure } from './utils/debug-logger'; @@ -831,17 +827,17 @@ export function prepareItem( id: QueueItemId ) { // Browsers report an empty file.type for HEIC files on platforms that // lack the OS-level HEVC codec needed to identify the format (e.g. // Windows without the HEVC Video Extension). Fall back to sniffing the - // file extension so these files still reach the HEIC handling below + // file header so these files still reach the HEIC handling below // instead of silently uploading as an undecodable, unconverted file. - const isHeicByExtension = - ! file.type && hasFileExtension( file.name, HEIC_EXTENSIONS ); + const isHeicByContent = + ! file.type && + isHeicBuffer( await file.slice( 0, 64 ).arrayBuffer() ); - const isImage = file.type.startsWith( 'image/' ) || isHeicByExtension; + const isImage = file.type.startsWith( 'image/' ) || isHeicByContent; const isVipsSupported = CLIENT_SIDE_SUPPORTED_MIME_TYPES.includes( file.type ); - const isHeic = - HEIC_MIME_TYPES.includes( file.type ) || isHeicByExtension; + const isHeic = HEIC_MIME_TYPES.includes( file.type ) || isHeicByContent; // Gate very large images out of client-side processing. wasm-vips is // capped at 1 GiB of memory, so high-megapixel images, especially diff --git a/packages/upload-media/src/test/is-heic-buffer.ts b/packages/upload-media/src/test/is-heic-buffer.ts new file mode 100644 index 00000000000000..1865bc786f818f --- /dev/null +++ b/packages/upload-media/src/test/is-heic-buffer.ts @@ -0,0 +1,45 @@ +import { isHeicBuffer } from '../utils'; + +/** + * Builds a minimal ISOBMFF File Type Box. + * + * @param brands Major brand, followed by any compatible brands. + * @return ArrayBuffer of a synthetic file header. + */ +function buildFtyp( ...brands: string[] ): ArrayBuffer { + const [ majorBrand, ...compatibleBrands ] = brands; + // "ftyp", the major brand, the zeroed minor version, the compatible brands. + const box = `ftyp${ majorBrand }\0\0\0\0${ compatibleBrands.join( '' ) }`; + return new Uint8Array( [ + // Box size, including these four bytes. + 0x00, + 0x00, + 0x00, + 4 + box.length, + ...[ ...box ].map( ( c ) => c.charCodeAt( 0 ) ), + ] ).buffer; +} + +describe( 'isHeicBuffer', () => { + it( 'returns false for a buffer with no File Type Box', () => { + expect( + isHeicBuffer( + new Uint8Array( [ 0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10 ] ).buffer + ) + ).toBe( false ); + } ); + + it( 'returns true for a HEIC major brand', () => { + expect( isHeicBuffer( buildFtyp( 'heic' ) ) ).toBe( true ); + } ); + + it( 'returns true for a HEIC compatible brand', () => { + expect( isHeicBuffer( buildFtyp( 'mif1', 'miaf', 'heic' ) ) ).toBe( + true + ); + } ); + + it( 'returns false for AVIF, which declares the generic HEIF brand', () => { + expect( isHeicBuffer( buildFtyp( 'avif', 'mif1' ) ) ).toBe( false ); + } ); +} ); diff --git a/packages/upload-media/src/utils.ts b/packages/upload-media/src/utils.ts index 7453023217e8e8..d046bd2d9c3cd6 100644 --- a/packages/upload-media/src/utils.ts +++ b/packages/upload-media/src/utils.ts @@ -80,24 +80,6 @@ export function getFileExtension( file: string ): string | null { return file.includes( '.' ) ? file.split( '.' ).pop() || null : null; } -/** - * Checks whether a file name has one of the given extensions. - * - * Case-insensitive, since filesystems and cameras don't agree on casing - * (e.g. "IMG_1234.HEIC"). - * - * @param name File name. - * @param extensions Extensions to match against, without the leading dot. - * @return Whether the file name ends in one of the given extensions. - */ -export function hasFileExtension( - name: string, - extensions: readonly string[] -): boolean { - const extension = getFileExtension( name )?.toLowerCase(); - return !! extension && extensions.includes( extension ); -} - /** * Returns file basename without extension. * @@ -186,3 +168,88 @@ export function isAnimatedGif( buffer: ArrayBuffer ): boolean { return false; } + +/** + * Brands that identify a HEIC/HEIF image, as registered with the MP4RA. + * + * `mif1` and `msf1` are the generic HEIF brands, which AVIF files carry too, + * so the AVIF brands are ruled out before these are consulted. + */ +const HEIC_BRANDS = [ + 'heic', + 'heix', + 'heim', + 'heis', + 'hevc', + 'hevx', + 'hevm', + 'hevs', + 'mif1', + 'msf1', +]; +const AVIF_BRANDS = [ 'avif', 'avis' ]; + +/** + * Detects whether a file buffer contains a HEIC/HEIF image. + * + * Performs binary analysis of the ISOBMFF file structure: + * 1. Checks for the File Type Box marker ("ftyp" at offset 4) + * 2. Collects the brands it declares (major brand at offset 8, compatible + * brands from offset 16 on, each four ASCII characters) + * 3. Returns true if a HEIC/HEIF brand is present and no AVIF brand is + * + * Used when the browser can't report a MIME type at all (`file.type === ''`), + * which happens on platforms lacking the OS-level HEVC codec. More reliable + * than the file name, which is only a naming convention. + * + * Only the File Type Box is read, so a file can declare a HEIF brand and still + * be undecodable. That is non-destructive: it reaches the HEIC conversion path, + * where `parseHeic()` does the full parse and a failure surfaces as a regular + * decode error. + * + * Based on ISO/IEC 14496-12 (ISOBMFF) and ISO/IEC 23008-12 (HEIF): + * + * @see https://mp4ra.org/registered-types/brands + * @see https://nokiatech.github.io/heif/technical.html + * + * @param buffer File ArrayBuffer. The first 64 bytes cover the File Type Box. + * @return Whether the buffer contains a HEIC/HEIF image. + */ +export function isHeicBuffer( buffer: ArrayBuffer ): boolean { + const view = new Uint8Array( buffer ); + + // A File Type Box is at least: size (4) + "ftyp" (4) + major brand (4). + if ( view.length < 12 ) { + return false; + } + + // Check the File Type Box marker: "ftyp" (0x66 0x74 0x79 0x70) at offset 4. + if ( + view[ 4 ] !== 0x66 || + view[ 5 ] !== 0x74 || + view[ 6 ] !== 0x79 || + view[ 7 ] !== 0x70 + ) { + return false; + } + + // Collect the brands: the major one at offset 8, then the compatible ones + // every 4 bytes from 16 on, skipping the minor version at 12. The box size + // bounds the scan, as anything past it belongs to the next box. + const boxSize = new DataView( + buffer, + view.byteOffset, + view.byteLength + ).getUint32( 0 ); + const end = Math.min( boxSize || view.length, view.length ); + const brands = [ String.fromCharCode( ...view.subarray( 8, 12 ) ) ]; + for ( let i = 16; i + 4 <= end; i += 4 ) { + brands.push( String.fromCharCode( ...view.subarray( i, i + 4 ) ) ); + } + + if ( brands.some( ( brand ) => AVIF_BRANDS.includes( brand ) ) ) { + return false; + } + + return brands.some( ( brand ) => HEIC_BRANDS.includes( brand ) ); +} From 5f177a2ca080f6156aa9924e828bd39fe69161d1 Mon Sep 17 00:00:00 2001 From: Aki Hamano Date: Mon, 10 Aug 2026 16:51:31 +0900 Subject: [PATCH 5/6] fix: Skip the ImageDecoder strategy for files with no MIME type Co-Authored-By: Claude --- packages/upload-media/src/canvas-utils.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/upload-media/src/canvas-utils.ts b/packages/upload-media/src/canvas-utils.ts index 532d1d600aa6c5..a016f397d407e8 100644 --- a/packages/upload-media/src/canvas-utils.ts +++ b/packages/upload-media/src/canvas-utils.ts @@ -68,7 +68,7 @@ export async function canvasConvertToJpeg( // Strategy 2: WebCodecs ImageDecoder API. // Uses platform codecs (e.g., macOS HEIC support) that may not be // exposed through createImageBitmap or elements. - if ( typeof ImageDecoder !== 'undefined' ) { + if ( file.type && typeof ImageDecoder !== 'undefined' ) { const supported = await ImageDecoder.isTypeSupported( file.type ); if ( supported ) { const decoder = new ImageDecoder( { From 3230dc50996535fc1741c7aef4ab747cb3d73af2 Mon Sep 17 00:00:00 2001 From: Aki Hamano Date: Mon, 10 Aug 2026 16:55:46 +0900 Subject: [PATCH 6/6] docs: Add an upload-media changelog entry for the HEIC upload fix Co-Authored-By: Claude --- packages/upload-media/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/upload-media/CHANGELOG.md b/packages/upload-media/CHANGELOG.md index 8d8c35734ef7ac..2fb9ecd3565dd9 100644 --- a/packages/upload-media/CHANGELOG.md +++ b/packages/upload-media/CHANGELOG.md @@ -8,6 +8,7 @@ ### Bug Fixes +- HEIC uploads no longer hang indefinitely on platforms lacking the OS-level HEVC codec, where `ImageDecoder.decode()` never settles. The decode is now bounded by a timeout, and HEIC files the OS can't identify (empty `file.type`) are detected from the file header ([#81043](https://github.com/WordPress/gutenberg/issues/81043)). - A failed `/finalize` request is no longer reported as a successful upload. Finalize is the server's commit point for the attachment metadata (responsive sub-sizes and the final `-scaled` file reference); when it fails, the item is now cancelled and the error surfaced instead of showing "upload complete" and keeping an attachment that is missing its registered sizes ([#80673](https://github.com/WordPress/gutenberg/issues/80673)). ## 0.37.0 (2026-07-29)