feat: route media uploads through native host for processing

[dcalhoun]

What?

Adds a native media upload pipeline that routes file uploads through a local HTTP server on iOS and Android, enabling the host app to process files (e.g., resize images, transcode video) before they are uploaded to WordPress.

Why?

Ref CMM-1249.

Gutenberg's built-in upload path sends files directly from the WebView to the WordPress REST API with no opportunity for native processing. Host apps need to resize images, enforce upload size limits, or apply other transformations before upload. This pipeline gives the native layer full control over media processing while keeping the existing Gutenberg upload UX (blob previews, save locking, entity caching) unchanged.

How?

Architecture: A localhost HTTP server runs on each platform (NWListener on iOS, raw ServerSocket on Android), bound to 127.0.0.1 on a random port with per-session Bearer token auth.

JS layer:

• nativeMediaUploadMiddleware in api-fetch.js intercepts POST /wp/v2/media requests when nativeUploadPort is configured in window.GBKit, forwarding files to the local server and transforming responses to WordPress REST API attachment shape (source_url, caption.raw/rendered, title.raw/rendered, media_details, etc.) so the existing Gutenberg upload pipeline works unchanged
• Uses exact endpoint matching (/wp/v2/media but not /wp/v2/media/123 or /wp/v2/media-categories) to avoid intercepting non-upload requests

Native layer:

• MediaUploadDelegate protocol/interface with processFile (resize/transcode) and optional uploadFile (custom upload)
• DefaultMediaUploader as fallback, uploading to /wp/v2/media via the host's HTTP client
• Upload server only starts when a delegate is provided — no resources wasted otherwise
• Filename sanitization prevents path traversal from malicious Content-Disposition values
• 250 MB upload size limit with early rejection (HTTP 413) before buffering the body into memory
• User-friendly error messages surfaced to the editor (e.g., "file too large" for 413) with structured error codes (upload_file_too_large, upload_failed)

Demo apps:

• Both iOS and Android demo apps include a delegate that resizes images to 2000px max
• "Enable Native Media Upload" toggle (defaults to true) controls whether the delegate is set

Key design decisions

• Localhost HTTP server over platform-specific bridges: Provides a uniform interception point for all upload paths (file picker, paste, drag-and-drop, programmatic) without requiring per-path bridge wiring
• Delegate is opt-in: The server doesn't start and no configuration is injected unless the host provides a MediaUploadDelegate, keeping the default behavior unchanged
• api-fetch middleware over mediaUpload editor setting: Ideally, media uploads would be handled via the mediaUpload editor setting (see the Gutenberg Framework guides), but GutenbergKit uses Gutenberg's EditorProvider which overwrites that setting internally. Until GutenbergKit is refactored to use BlockEditorProvider, the api-fetch middleware approach is necessary.

Alternatives considered

1. JS Canvas resize + native inserter resize — Two separate implementations: createImageBitmap() + OffscreenCanvas in JS for web uploads, CGImageSourceCreateThumbnailAtIndex in MediaFileManager.import() for the native inserter. Ships fastest and lowest complexity, but Canvas resize quality is lower than native, two codepaths to maintain, and a dead-end for video (client-side transcoding in a WebView is impractical).

2. Native upload pipeline via local HTTP server (this PR) — A single api-fetch middleware intercepts all POST /wp/v2/media requests and routes files through a localhost server for native processing. Covers every upload path (file picker, drag-and-drop, paste, programmatic, plugin blocks) with native-quality processing. Scales to video transcoding. More upfront work than option 1.

3. Replace MediaPlaceholder via withFilters hook — Use editor.MediaPlaceholder and editor.MediaReplaceFlow filters with handleUpload={false} to deliver raw File objects to onSelect, then route to native. Incomplete coverage: misses block drag-and-drop re-uploads (handleBlocksDrop calls mediaUpload directly), direct mediaUpload calls from plugins, and loses blob previews when handleUpload is false. instanceof FileList checks are fragile in WebView contexts.

4. Redirect to native UI on large files — Keep the web upload button, but show a native dialog when files exceed limits. Awkward UX (user already picked a file, now asked to pick again differently). On iOS, the already-selected JS File can't be handed to native for optimization. Two parallel upload paths add complexity.

5. JS resize for images + hide web upload for video blocks — JS Canvas resize for images, hide the "Upload" button on video-accepting blocks via editor.MediaPlaceholder filter (forcing users to Media Library for video). Users can't drag-and-drop videos, blocks accepting both image and video (Cover) get complicated, and it's a dead-end architecture.

6. Client-side processing via @wordpress/upload-media (WASM libvips) — Gutenberg's experimental @wordpress/upload-media package includes a WASM build of libvips for high-quality client-side image resizing, rotation, format transcoding, and thumbnail generation. Quality is comparable to server-side ImageMagick. However, it requires SharedArrayBuffer for WASM threading, which is only available in cross-origin isolated contexts — WKWebView loads GutenbergKit's HTML locally with no HTTP headers, so SharedArrayBuffer is unavailable. WebKit also lacks credentialless iframe support, meaning cross-origin isolation would break third-party embeds (YouTube, Twitter, etc.). Single-threaded WASM fallback is unvalidated, and the package's memory footprint (50-100MB+ per image) is a concern under iOS jetsam pressure. Not viable today, but worth revisiting if the package decouples its store/queue management from WASM processing (tracked upstream).

A key constraint is platform asymmetry: Android can intercept web <input type="file"> via onShowFileChooser(), but iOS cannot — WKWebView handles file selection internally. This rules out purely native interception strategies for web-originated uploads and motivated the localhost server approach, which works identically on both platforms.

Testing Instructions

1. Open the iOS or Android demo app connected to a WordPress site (e.g., wp-env)
2. Verify the "Enable Native Media Upload" toggle is present and defaults to on
3. Insert an Image block and upload a large image (>2000px)
4. Verify the upload succeeds and the image displays in the editor
5. Check logs for "Resized image from WxH to fit 2000px" confirming native processing
6. Toggle "Enable Native Media Upload" off, restart the editor, and upload again — verify the upload still works (via standard Gutenberg path, no resize log)

Accessibility Testing Instructions

The toggle follows the same pattern as the existing "Enable Native Inserter" toggle — no new UI beyond that.

Screenshots or screencast

N/A — backend/infrastructure change with no visible UI changes beyond the demo app toggle.

[jkmassel]

We should probably print whatever the server sends back – it should be WP_Error-shaped, but some hosts might have messaging like "The max is ${SOME_NUMBER}" or "You've reached your quota".

WDYT?

[dcalhoun]

Yes, that makes sense.

This was strictly implemented to handle the 250 MB maximum upload restriction of the local server, but I agree it should be made more robust. If we do not add specific handling for 413, the default user-facing message is something like "Unable to get a valid response from the server."