Re-enable TJPGD on CircuitPython by sharing CP's lib/tjpgd — lv_tjpgd.c must honour JD_FORMAT; and is_jpg() rejects UVC MJPEG

[bdbarnett]

Two related findings from the jpegio plan (displayif issue linked in pydevices/docs/jpegio-vision.md).

1. The CircuitPython disable was a config mismatch, not a symbol clash. lv_conf.h:732 sets LV_USE_TJPGD 0 under LV_CIRCUITPYTHON_BUILD and lvgl-circuitpython/circuitpython.mk:31 filters LVGL's tjpgd.c out because CP already compiles lib/tjpgd/src/tjpgd.c (py/circuitpy_defns.mk:964) with "incompatible tjpgdcnf". Both are TJpgDec R0.03; the incompatibility is tjpgdcnf.h: CP builds JD_FORMAT 1 (RGB565) + JD_USE_SCALE 1, LVGL's vendored copy JD_FORMAT 0 (RGB888) + no scaling — and lv_tjpgd.c:207 hardcodes LV_COLOR_FORMAT_RGB888 regardless. Linking LVGL's decoder against CP's copy today would label RGB565 pixels RGB888.

Fix: (a) on CP builds set LV_USE_TJPGD 1, point lv_tjpgd.c's #include "tjpgd.h" at CP's lib/tjpgd/src (include path), keep LVGL's tjpgd.c excluded — one copy, CP's config; (b) make lv_tjpgd.c honour JD_FORMAT (RGB565 header + copy when built for it) — ~10 lines, upstreamable. Then remove the lv_tjpgd_init/lv_tjpgd_deinit target exceptions for CircuitPython in binding/api_policy.json, runtime_exports.py, docs/generator-architecture.md:69 and the smoke-test assertion at tools/test_lvgl_smoke.py:504. The org-wide TJpgDec config becomes CP's (RGB565 + scale); the MicroPython jpegio module links against LVGL's copy when lvgl is in the build.

2. is_jpg() at lv_tjpgd.c:302 requires FF D8 FF E0 00 10 "JFIF" in bytes 0..9. Measured UVC MJPEG frames (Logitech C920e) open SOI → DQT → SOF0 → DHT… with the APP0/JFIF segment after the Huffman tables, so LVGL's image decoder rejects every webcam frame before TJpgDec sees it. SOI alone is the correct sniff; jd_prepare judges the rest. Upstream LVGL bug; worth reporting there with the marker sequence (this org's emissary charter is CircuitPython-only, so that report is a human's).

[bdbarnett]

Scouting for this change is written up at pydevices/docs/jpegio-phase2-scouting.md (2026-09-03). Two facts change the shape of the fix: (1) LVGL's src/libs/tjpgd/tjpgd.c is not ChaN's R0.03 — it removed the scale 1–3 descale paths, the DC-only branch and grayscale, exports jd_restart/jd_mcu_load/jd_mcu_output, inserts rst/rsc/pool_original into JDEC and writes B,G,R — so a single shared copy must be ChaN's R0.03(+patch1) with LVGL's additions re-applied, and jpegio must never link LVGL's copy unmodified (scale>0 would silently emit garbage). (2) There is no sanctioned way to patch LVGL sources here (upstream submodule at v9.5.0, pin checks reject any submodule diff, no fork in the org), and upstream closed separating TJPGD as not planned (lvgl#10082) while master still hardcodes RGB888 — so the fix is a PyDevices fork branch or an override directory, re-applied at each pin bump with a tripwire test. Upstream has since fixed is_jpg to a 3-byte SOI sniff (99df9b9) and the 4 KB stack buffer (a04a3cd); both are worth backporting. Decisions before any commit are Brad's: fork vs override, CircuitPython's documented RGB565_SWAPPED jpegio output (a JD_SWAP_RGB565 knob keeps it), whether CPython links TJPGD too, and where the one-copy switch lives (displayif self-detect recommended).

[bdbarnett]

Phase 2 of jpegio landed on the bindings side (2026-09-03), without a fork of LVGL:

• lv_conf.h sets LV_USE_TJPGD 0 on MicroPython and CircuitPython (aa6c6bc); CPython keeps LVGL's built-in decoder (tjpgd_init/tjpgd_deinit are CPython-only in the API policy, with the reason recorded). The generator's single preprocess pass is the MicroPython flavour, so the conditional also keeps the declarations visible under PYCPARSER (documented in docs/generator-architecture.md).
• Consumers synced by SHA: lvgl-micropython d7ea193, lvgl-python 7883313 (compiles tjpgd.c again), lvgl-circuitpython 39de2c7 (its tjpgd.c filter is gone; a shim registers CircuitPython's own lib/tjpgd with lv_image_decoder_create, output labelled RGB565_SWAPPED). linux-integration.yml pins moved to those commits (151c13f).
• displayif registers jpegio's TJpgDec (JD_FORMAT 1, RGB565 native, SOI-only sniff, so UVC frames without a JFIF header decode) as LVGL's JPEG decoder when the lvgl-micropython sibling is present; its push follows the esp32 CMake build check.

Gate evidence on the aggregator: one object defines jd_prepare in both unix builds (displayif's tjpgd.o on MicroPython, CP's lib/tjpgd on CircuitPython); the corpus decodes through lv.image at jpegio's golden digests on both; lv.tjpgd_init absent on both, present on CPython; the smoke test asserts exactly that.

The is_jpg upstream bug in this issue's title no longer reaches us on MicroPython/CircuitPython (LVGL's decoder is off there); it still applies to CPython, where LVGL's own decoder stays on.

[bdbarnett]

Audit 2026-09-04: part 1 is superseded and should be rewritten or struck; part 2 is fully live.

Part 1 asked for LV_USE_TJPGD 1 on CircuitPython and for lv_tjpgd.c to honour JD_FORMAT. The org has since committed the other way: lv_conf.h:738 sets it to 1 only under LV_CPYTHON_BUILD || PYCPARSER, and :743 sets 0 otherwise — so it is deliberately off on CircuitPython and MicroPython, with jpegio registering its own decoder through LVGL's public API instead. lv_tjpgd.c:207 still writes LV_COLOR_FORMAT_RGB888, so the ~10 upstreamable lines were never written and no longer need to be. Leaving part 1 standing asks for the opposite of what shipped, and there are now tests enforcing the current arrangement.

Part 2 is real and untouched. On CPython LV_USE_TJPGD is 1, and lv_tjpgd.c:302-306 still demands the 10-byte FF D8 FF E0 00 10 'JFIF' prefix, so CPython's lv.image rejects every UVC MJPEG frame. The submodule is at 85aa60d (v9.5.0) and upstream's SOI-sniff fix (99df9b9) plus the 4 KB stack-buffer fix are genuinely absent from it.

Suggested trim: strike part 1 as superseded, retitle around the is_jpg upstream report, and note that filing it is a human's to do — the emissary charter covers CircuitPython only.