fix(producer): convert HEIC images to JPEG at compile time - #6455

What

HEIC and HEIF images now work in every render path. The compile step converts each one to a JPEG before the page loads and rewrites the <img src>, so the CLI, Studio preview, Lambda and cloud renders all get it from one place.

No visible change

Compositions without HEIC images compile exactly as before. A HEIC image that used to fail the render now shows as a normal picture.

Why

Chrome cannot decode HEIC, and a tiled iPhone photo also reads as several video streams. The media-type check then rejects the <img> and the render fails at the plan step. On main, with a real tiled HEIC:

THROW ASSET_MEDIA_TYPE_MISMATCH 1 composition asset(s) do not match their authored media element type (expected: image) [{"expected":"image","detected":"video"}]

The media probe reports the file as visualKind: "moving". A real CLI render on main fails with the same message (exit 1).

Related work

Follows the same shape as the animated-GIF preparation (animatedGifPrep.ts), which is the existing owner of "turn an unsupported <img> into something Chrome can show".

How

• New heifImagePrep.ts sits next to the GIF prep and is wired in the same two places: htmlCompiler.ts (renders) and Studio's preview transform.
• A source counts as HEIC by its content (ftyp brands heic, heix, hevc, hevx, heim, heis, mif1, msf1; AVIF is excluded), not its extension. Covered: a .heic file, a mislabeled .jpg, a data:image/heic;base64 source, and a remote source already downloaded by the existing localisation pass.
• ffmpeg alone does not do it: through ffmpeg 8.0 a tiled HEIC decodes as separate tile streams and the file's rotation is not applied (one tile of 512x512 comes out). So the grid is stacked with xstack from the tile layout ffprobe -show_stream_groups reports, cropped to the declared size, and rotated by the primary item's irot box (heifRotation.ts). The result must equal the declared size (swapped for a quarter turn) or the conversion fails, so a lone tile can never pass.
• Each unique source converts once (content hash, with the same cache directory the GIF prep uses), through the shared media-probe slots. A composition with no <img> never reaches the parse; one with only non-HEIC images costs a 4 KB header read per local image.
• A file that cannot be converted fails with a typed error that names the file and says to re-export it; it is not retried (HEIF_IMAGE_CONVERSION_FAILED).
• runFfprobe is now exported from the engine and the source resolver in animatedGifPrep.ts is shared, so there is one resolver.

Design calls: (1) a sibling of the GIF prep, not a new stage: it is the existing owner of this kind of rewrite and its two callers; (2) JPEG output only, since there is no alpha HEIC fixture to prove a PNG path; (3) tiles joined by us, because ffmpeg does not do it.

Test plan

• Unit tests added: 25 new tests pass 3 runs in a row with real ffmpeg (tiled + rotated fixture with pixel checks derived from decoding each tile separately, data URL, mislabeled .jpg, remote-style source, dedupe, corrupt file names the file, no-HEIC spawns nothing, compile no longer fails the media-type check); breaking rotation or the tile join fails 3 tests each
• Manual testing performed: a 1100x700 composition showing the fixture rendered with the CLI (exit 0); the extracted frame is portrait, upright, whole, continuous across tile seams
• Documentation updated (not applicable)
• Comments follow CONTRIBUTING.md

Not covered: HEIC with an alpha plane (always JPEG), a single non-tiled HEIC that carries a rotation (relies on ffmpeg's own handling), a mirror (imir) property, CSS url() and srcset. The tile join needs ffprobe 7.0 or newer for -show_stream_groups; the arm64 Lambda image builds ffmpeg 7.0.2 and the GCP and CLI Docker images ship a BtbN 8.0.1 build, all with the hevc decoder, while the x86 Lambda zip uses the npm ffmpeg-static binary and is worth checking.