File Formats

OpenGPEX v2's unified file I/O: a single decision authority for import, a single GPU pipeline for export, and full wide-gamut / high-bit-depth fidelity.

Import Pipeline

Every file passes a two-stage ingest driven by one pure function:

extractMetadata(file)            // header sniff: format, size, colorSpace, bitDepth, hasAlpha, isMultiFrame
  → resolveIngestDecision(md)    // the only decision authority in the codebase
  → handler.decode(...)          // pure pixel extraction for the assigned channel
  → AssetService.storeBundle()   // light record + optional dec:/raw: keys

Decode Channels

Key invariants: high-depth channel failures must throw (no silent 8-bit fallback), AVIF is pre-clamped to 8-bit, and retainSourceBlob holds iff the channel is not image-bitmap (Revert re-decodes the retained original and reproduces the same content hash).

Export Pipeline

Export reuses the same WebGPU RenderGraph as the screen (One Pipeline): an offscreen scene locked at dpr: 1 renders through the identical shaders, then f32 premultiplied linear pixels are read back and encoded by one shared function (unpremultiplyEncodeGamut).

Egest Channels

Container capability is the single gate: unsupported intent collapses to the working gamut, then sRGB; Rec.2020 harmlessly degrades to Display-P3 (the working gamut); HEIC/RAW have no encode channel and throw. Default bit depth follows the source document (a 16-bit source defaults to 16-bit export; wide gamut is never forced to 16-bit anymore). ICC embedding is decided per container (PNG/JPEG/WebP/TIFF yes; AVIF/BMP/GIF/SVG/EPS no — the AVIF encoder has no ICC-embed API at all).

Pass-Through Fast Path

Unedited, unclipped, unscaled, format-matched documents whose requested gamut equals the source gamut skip the GPU entirely — the retained source bytes download verbatim.

Metadata Preservation

Native .gpex Format

The project save format is a self-contained binary container: a 20-byte header (magic GPEX, version, section sizes) followed by three sections:

• Thumbnail — WebP preview image for cloud listings
• Manifest — outer JSON metadata read by the server without touching the ZIP: frameLocalId (the cloud upsert key), frame name, canvas size, layer/asset counts, editor version
• Payload — ZIP archive with the dehydrated document state plus all content-addressed assets:

state.json               dehydrated Frame
assets-manifest.json     per-asset geometry, colour identity, provenance
assets/{id}.png|webp     8-bit display bitmap, one per assetId
raw/{fileHash}           original encoded source file, deduplicated by content hash
dec/{id}.bin             decoded high-depth naked pixels (f16/f32), per dataFormat

Legacy containers written before assets-manifest.json existed carry no per-asset metadata; unpack degrades them to plain 8-bit registration (probing dimensions via createImageBitmap when the manifest geometry is missing), which matches their historical 8-bit ceiling rather than introducing loss.

Multi-Frame Semantics

All multi-frame containers decode into a unified pages: DecodedImage[] sequence; business logic then splits by meaning:

• Animated GIF → a time-sequence model inside a single frame (per-layer frame timing via delay), reassembled on export
• Multi-page TIFF → Trunk + Branch independent artboards, one page per artboard, physically sharing one raw: source file

WASM Modules

Heavy format work runs in dedicated workers, never blocking the UI:

wasm-vips is codec-only by contract — all compositing lives in the GPU RenderGraph.

Last updated: 2026-10-12