feat: add MediaUploader, for a host that owns the whole upload

[jkmassel]

Stacked on #627. Fifth of ten PRs splitting #621, and the heart of it. Purely additive — nothing existing changes shape.

What?

A MediaUploader protocol that takes over performing a media upload on the host's own stack, and owns its whole lifecycle: retries, recovery, and cleanup.

Why?

Performing a media upload — and retrying it — should be a single, all-or-nothing responsibility: either GutenbergKit performs the upload and owns its retries, or the host does. Both go to the same configured site; the only difference is who executes the requests.

MediaUploadDelegate.uploadFile doesn't offer that. A host performs the POST /wp/v2/media and returns the raw response it received — then the editor, reading that response, drives the post-process retries and the orphan cleanup behind it, through the WebView rather than the host's stack. A host that took over uploads to run them through its own networking still didn't own the retries. It also receives no form fields, so an attachment it uploads lands unattached to its post.

Neither is fixable while the hook returns a raw response, which is what the replacement changes.

How?

MediaUploader

upload(_:) returns the finished attachment or throws. There is no raw response left for the editor to retry behind it, so the host drives its own post-process recovery and force-deletes its own orphan on terminal failure.

MediaUpload

Carries the file, its metadata, the editor's non-file form fields (post, additionalData) and the request query (?_embed) — everything needed to reproduce a native request.

MediaUploadField

Fields are an ordered list rather than a dictionary, so repeated names (a field[] array) survive verbatim and in order. A named type rather than a tuple: tuples are not nominal, so a tuple-typed property would permanently block Equatable/Hashable/Codable synthesis on MediaUpload, and that is not fixable later without a source break for every host.

Precedence

uploadFile still works and is marked deprecated, pointing hosts at the replacement; an uploader takes precedence when both are set. #629 removes the old hook, so hosts get a migration window rather than a flag day.

This deliberately leaves one deprecation warning in GutenbergKit's own build, at the call site that supports the old hook. The marker exists to tell hosts to migrate, and supporting the hook until it is removed means calling it. It goes away with #629.

The admission gate

With an uploader set, the delegate's metadata gate can no longer decline a file. The gate exists to skip a temp copy for a file the delegate won't touch, but an uploader takes over delivery for every file, so passing through would silently bypass it.

Testing Instructions

Five new tests on iOS, three on Android: delivery, form fields and query, precedence over uploadFile, the declined-file case, and a terminal throw surfacing without GutenbergKit re-delivering.

• swift test — host suite green
• Android :Gutenberg:testDebugUnitTest green
• iOS Simulator xcodebuild
• SwiftLint + Detekt clean

MediaUploadServerTest crosses Detekt's LargeClass threshold; baselined rather than split, which is its own change.

[wpmobilebot]

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/628")

_{Built from fadbd45}