Leverage server-side HEIC conversion when available

[Copilot]

Leverage server-side HEIC conversion

This PR implements server-side HEIC conversion support as described in issue #483.

Summary

When a WordPress server supports HEIC image format (e.g., via Imagick with libheif), this feature allows uploading HEIC files directly to the server for conversion, rather than converting them client-side. This reduces client-side processing load while maintaining full control over thumbnail generation.

Changes Made

1. Server Capability Detection (PHP)

• Added wp_image_editor_supports(['mime_type' => 'image/heic']) check in inc/functions.php
• Exposed supports_heic flag through REST API index endpoint (filter_rest_index)

2. TypeScript Type Definitions

• Added supports_heic: boolean to RestBaseRecord type (packages/editor/src/types.ts)
• Added supportsHeic?: boolean to Settings interface (packages/upload-media/src/store/types.ts)
• Updated siteDataFields array to fetch supports_heic from REST API (packages/editor/src/init/index.ts)
• Pass supportsHeic to upload store settings

3. Upload Configuration (packages/upload-media/src/store/private-actions.ts)

• Added isHeicFile() utility function to check if a file is HEIC/HEIF
• In addItem(): Detect HEIC files and disable server-side thumbnail generation when server supports HEIC
  • Sets generate_sub_sizes: false for HEIC files when supportsHeic is true
  • Ensures thumbnails are generated client-side for optimal control

4. Operation Flow Restructuring (packages/upload-media/src/store/private-actions.ts)

• In prepareItem(): When server will convert HEIC, only add Upload operation

  • Remaining operations added dynamically after upload completes

• In uploadItem(): After uploading HEIC to supporting server

  • Dynamically adds operations in correct order: FetchRemoteFile → GenerateMetadata → GenerateCaptions → ThumbnailGeneration
  • Ensures converted JPEG is fetched before metadata/thumbnail generation
  • Updates item.file to the converted file so thumbnail generation works correctly

5. E2E Tests (tests/e2e/specs/images/heic-server-side.spec.ts)

• Test for server-side HEIC conversion when supported
  • Verifies HEIC uploads directly to server
  • Confirms server converts to JPEG
  • Validates metadata generation (blurhash, dominant color)
  • Ensures client-side thumbnails are generated
• Test for graceful fallback to client-side conversion
  • Verifies client-side conversion when server doesn't support HEIC
  • Confirms upload completes successfully

Operation Flow Comparison

Before (client-side conversion):

TranscodeHeif → ResizeCrop → TranscodeImage → GenerateMetadata → GenerateCaptions → Upload → ThumbnailGeneration

After (server-side when supported):

Upload (HEIC, generate_sub_sizes=false) → FetchRemoteFile (converted JPEG) → GenerateMetadata → GenerateCaptions → ThumbnailGeneration

Fallback (server doesn't support HEIC):

TranscodeHeif → ResizeCrop → TranscodeImage → GenerateMetadata → GenerateCaptions → Upload → ThumbnailGeneration

Benefits

✅ Offloads HEIC conversion to server when available (reduces client-side processing)
✅ Maintains full control over client-side thumbnail generation
✅ Graceful fallback to client-side conversion when server doesn't support HEIC
✅ Works seamlessly with existing WordPress image editor infrastructure
✅ No user-facing changes required - works automatically based on server capabilities
✅ Proper operation sequencing ensures converted file is available for all subsequent operations

Testing Requirements

This feature requires testing with:

1. WordPress installation with HEIC support (e.g., Imagick extension with libheif)
2. Related PR: wordpress-develop#7034 (adds HEIC MIME type support)

E2E test checklist:

• Test server-side HEIC conversion when supported
• Test fallback to client-side conversion when not supported
• Verify metadata generation works correctly
• Verify client-side thumbnail generation works
• Verify no upload errors occur

Related Issues

• Closes Evaluate libheif alternative #483
• Depends on wordpress-develop#7034 for full server-side HEIC support

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Leverage server-side HEIC conversion</issue_title>
<issue_description>Related:

• Evaluate libheif alternative #483

If WordPress/wordpress-develop#7034 lands and no client-side HEIC conversion is possible, it could be at least done on the server. The thumbnails could still be generated client-side though.

It would make things a bit more complicated:

1. Check whether server supports HEIC
2. Upload HEIC image to the server as a regular attachment

• Let WP do the conversion server-side, but do not create any thumbnails

3. Get back the converted JPEG on the client
4. Create all thumbnails on the client and sideload them

Might just be a matter of changing order of operations.

Before:

OperationType.TranscodeHeif
OperationType.ResizeCrop // Big image size threshold
OperationType.TranscodeImage // Compress
OperationType.GenerateMetadata
OperationType.GenerateCaptions
OperationType.Upload
OperationType.ThumbnailGeneration

After:

OperationType.Upload
OperationType.GenerateMetadata
OperationType.GenerateCaptions
OperationType.ThumbnailGeneration

</issue_description>

Comments on the Issue (you are @copilot in this section)

@swissspidy `wp_image_editor_supports( array( 'mime_type' => 'image/heic' ) )`

• Fixes Leverage server-side HEIC conversion #578

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[swissspidy]

@copilot can we add an e2e test for this perhaps?

[Copilot]

@copilot can we add an e2e test for this perhaps?

Added e2e test in commit a1e910f. The test covers both scenarios:

1. Server supports HEIC: Verifies HEIC uploads directly, server converts to JPEG, and client-side thumbnails are generated
2. Server doesn't support HEIC: Verifies graceful fallback to client-side conversion

The test checks server capability via the supports_heic flag from the REST API index and skips the appropriate scenario based on server configuration.

[github-actions]

Size Change: +275 B (0%)

Total Size: 16.6 MB

Filename	Size	Change
build/media-experiments.js	82.2 kB	+134 B (+0.16%)
build/view-upload-request.js	19.4 kB	+141 B (+0.73%)

ℹ️ View Unchanged

Filename	Size
build/100.js	117 kB
build/699.js	2.35 MB
build/ai.worker.js	7.79 MB
build/blurhash.worker.js	3.23 kB
build/canvas.worker.js	2.79 kB
build/chunk-ffmpeg.js	5.91 kB
build/chunk-selfie-segmentation.js	16.3 kB
build/dominant-color.worker.js	4.49 kB
build/ffmpeg.js	1.09 kB
build/heif.worker.js	518 kB
build/media-experiments-blocks-rtl.css	318 B
build/media-experiments-blocks.css	318 B
build/media-experiments-rtl.css	1.03 kB
build/media-experiments.css	1.03 kB
build/pdf.js	584 B
build/subtitles.js	850 B
build/view-upload-request-view-rtl.css	697 B
build/view-upload-request-view.css	699 B
build/vips.worker.js	5.65 MB

_{compressed-size-action}

[Copilot]

Pull Request Overview

This PR introduces server-side HEIC conversion support when WordPress has HEIC capabilities (e.g., Imagick with libheif). The implementation detects server capabilities via REST API and intelligently chooses between server-side and client-side conversion paths while maintaining client-side thumbnail generation.

Key changes:

• Added server capability detection using wp_image_editor_supports(['mime_type' => 'image/heic']) and exposed via REST API
• Modified operation flow to upload HEIC files directly when server supports them, then fetch converted JPEG for client-side thumbnail generation
• Implemented graceful fallback to existing client-side conversion when server doesn't support HEIC

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
inc/functions.php	Adds server-side HEIC capability detection and exposes it through REST API index
packages/editor/src/types.ts	Adds supports_heic field to REST base record type definition
packages/editor/src/init/index.ts	Propagates supports_heic from REST API to upload store settings
packages/upload-media/src/store/types.ts	Adds optional supportsHeic field to Settings interface
packages/upload-media/src/store/private-actions.ts	Implements conditional logic for server-side HEIC conversion with dynamic operation insertion
tests/e2e/specs/images/heic-server-side.spec.ts	Adds comprehensive E2E tests for both server-supported and fallback scenarios

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.