[libphf]

Summary

Brings the monograph's compression by pixel (the NHF3 palette mode, already in the engine) into the PHF container, lets callers choose between speed and size, and makes decoding faster and lighter. The file format is unchanged except that writers may now emit the palette mode, which this PR documents in SPEC.md.

Encoder options

phf_encode_memory() / phf_write_file() now take const phf_encode_options_t * (NULL or {0} = AUTO, BEST):

	PHF_EFFORT_BEST (files)	PHF_EFFORT_FAST (streaming)
PHF_MODE_MED	both plane variants (plain / run-length), smaller kept	one encode per plane
PHF_MODE_PALETTE	same, palette stream	one encode
PHF_MODE_AUTO	tries MED and palette up to 4096 colours, smaller kept	palette only up to 256 colours, else MED; no trials

Streaming applications are expected to fix the mode up front (webcam/video → MED, screen content → palette). CLI: --mode=auto|med|palette, --fast; info reports the coding mode.

Decoder (no format change)

• Bug: palette mode left alpha at 0 when decoding RGB into a 4-byte stride, so palette images would be transparent in the browser. Fixed; covered by tests.
• Huffman decoders are allocated only for the tables a plane carries (was always 259 × ~2.4 KB = 618 KB per plane; measured need 47–157 KB). Matters for small-memory targets and caches.
• Inverse MED runs the three colour planes in one interleaved pass when OpenMP does not split them: ~2.1× for that stage, bit-identical.

Measurements

Single thread, Apple M3 Pro, main → this branch:

Image	MED+FAST encode / decode	AUTO+BEST size
photo 1080p	38.8 → 15.4 ms / 30.9 → 27.2 ms	=
camera 720p	15.9 → 10.1 ms / 13.7 → 11.3 ms	=
video frame 1080p	35.3 → 22.7 ms / 33.0 → 25.8 ms	=
graphics (monograph GIFs)	similar	−71 % to −76 %, decode 2–3× faster

MED+FAST sizes stay within ±2 % of main. BEST encodes more variants, so it is slower than before (still well below PNG level 9).

Spec

SPEC.md section 4 describes the palette stream byte by byte; flags 0x08/0x09 mark palette files. An independent decoder written only from the text reproduced 12 encoder outputs bit-exactly (RGB/RGBA, 1–300 colours, with and without runs, both efforts).

Breaking changes

• New options parameter on phf_encode_memory() and phf_write_file(); nhf3_encode() / nhf3_plane_encode() gain an effort argument.
• apps/web/phf.wasm must be rebuilt for the alpha fix before palette files are served to the web viewer.
• phf-stream-webcam / phf-stream-video call the old signature; they keep working with their bundled library and will be updated to { MED, FAST } in follow-up PRs.

Test plan

• 2686/2686 checks (was 470): round-trips in all 6 mode/effort combinations, stride 3/4 with alpha, mode selection, invalid options, palette fuzz, legacy sample.phf.
• Same suite under ASan + UBSan and in a no-OpenMP Release build (exercises the interleaved inverse MED at every size).
• CLI: auto picks palette for a graphic and MED for a camera frame; decode bit-exact.
• CI (Linux OpenMP + sanitizers, macOS, Windows MSVC).
• WASM rebuild and browser check of a palette file.

🤖 Generated with Claude Code