Fix/remove grayscale parameter

[rbouteiller]

No description provided.

[ghcpuman902]

Coordination note: planning to land this first, then rebase #80 (bitmap fonts + dithering) on top. See #80 for context and the rendering alignment proposal.

[ghcpuman902]

Palette / quantization — current model + way forward

Cross-ref: scope split and #80 follow-up in #80.

Problem 1 — "how many gray levels" has three independent definitions

A device's gray-level count (BW=2, gray-4=4, gray-16=16) is the same fact whether we're encoding a BMP, building an error image, or quantizing a device PNG. Today it's defined in three places that can drift independently:

• the BMP / error-image path reads a hardcoded id → levels map (getBmpGrayLevelsForPalette(palette.id) in palette-gray-levels.ts);
• the device-PNG path reads palette.grays inline (device-image.ts), but only on the branch where resolvePaletteColors returns null;
• palettes.json already carries the authoritative grays per palette — the same numbers the map restates.

Adding a new grayscale palette today requires updating the map, the inline branch, and JSON independently. There is no shared getPaletteGrayLevels(palette), so palettes.json is not the single source of truth in practice.

Fix: one resolver — getPaletteGrayLevels(palette) in palette-colors.ts, reading palettes.json.grays. BMP path calls it (falling back to 2 for color palettes); device path calls it. The map and the inline read both disappear.

Problem 2 — the grayscale posterize path never runs

For bw / gray-4 / gray-16, resolvePaletteColors returns a discrete gray RGB list, so paletteGrays is always null and every grayscale device falls through to quantizeToPalette — never quantizeToGrayLevels. The posterize branch described in the comment block is unreachable for standard grayscale palettes.

The consequence is Problem 3.

Problem 3 — Floyd–Steinberg runs on the entire frame, not just images

quantizeToPalette unconditionally applies Floyd–Steinberg (FS) error diffusion: each pixel is snapped to the nearest palette entry and its quantization error is pushed into the not-yet-processed neighbors. Two properties matter here:

• It's non-local. The value written for a pixel depends on every pixel before it in scan order, so the whole frame is one serial dependency chain — the most CPU-heavy option, paid on every device render at request time.
• It's applied to everything. Text, SVG-style icons, flat color fills, and Tailwind dither-* blocks all go through it, not just <img> content.

For UI, that's actively wrong, not just slow. Concrete cases on current recipes:

• responsive-example — solid blue/red/green/purple panels become speckled gray instead of four uniform tones. The output looks broken, not dithered.
• Any text-forward recipe (simple-text, weather, bitcoin-price) — glyph and icon edges pick up error-diffusion noise from neighboring pixels, so type that is crisp in the Takumi PNG arrives soft on device.

Already correct in #78

Dropping the independent Device.grayscale knob, TRMNL X PNG palette encoding for the size budget, and the device-preview / log / registry refactor are all good foundation and unaffected by the above.

Way forward (for #78)

1. One resolver — getPaletteGrayLevels(palette) in palette-colors.ts; remove the hardcoded map and the inline read (Problem 1).
2. Route grayscale to a level-snap path — bw/gray-4/gray-16 hard-quantize to their palette level count; reserve quantizeToPalette for discrete color palettes (Problem 2).
3. Default = hard quantize, no FS — the Takumi PNG stays full-color and browser-faithful; the device step nearest-snaps each pixel to the palette independently. Levels still follow palette bit depth, the same contract as Framework image-dither, but without diffusing error across the frame (Problem 3).
4. Scope Fix/remove grayscale parameter #78 to foundation — palette model, routing fix, hard-quantize default, device profiles, preview/log. No global FS.

Why hard quantize is the right default now: BYOS targets many models, palettes, and bit depths (1-bit BW through 16-level gray and color). The shared payload across all of them is text, layout, and icons — not photos. Those must stay sharp and read identically in intent on every screen. A per-pixel nearest-level snap is local, content-independent in cost, and preserves crisp type and uniform fills. If a richer dither is ever wanted for UI, Bayer (fixed threshold-matrix lookup) and threshold quantize (per-pixel: luminance ≥ 50% → high level, < 50% → low level) are both local and cheap — same cost regardless of frame content, predictable across devices — and are the right tools, not FS.

Images are the author's call, not the renderer's. Photographic / continuous-tone content is the only place dither helps, and the author knows their content. So for images specifically, give them two routes (both in #80): render the image themselves and pre-quantize per device (conditional classes / per-device assets), or opt into a server helper (prepareForDevice, Bayer / white-noise / threshold) that dithers on their behalf. Either way it's scoped to the image, not a blanket FS pass on every recipe.

[rbouteiller]

Working on it right now, good point on the FS applied everywhere

[rbouteiller]

responsive-example — solid blue/red/green/purple panels become speckled gray instead of four uniform tones. The output looks broken, not dithered.

This screen doesn't work anymore in 1bit no dithering

[ghcpuman902]

responsive-example — solid blue/red/green/purple panels become speckled gray instead of four uniform tones. The output looks broken, not dithered.

This screen doesn't work anymore in 1bit no dithering

Working as intended, I think.

On 1-bit, semantic bg-* fills were never going to stay hue-distinct without simulated tone, quantization / snap-only collapses them to perceptual luminance. For the layout recipe that's expected; the fix is on the recipe side (add dither-* or screen-conditional classes), not a global dither pass.

Two things worth mentioning:

• Gray reduction should use Lab L*, not RGB channel average. We already match color palettes in Lab but reduce gray on raw channels. Blue-on-yellow reads fine in color yet can land on the same gray step — L* is what tells us whether text and background actually separate.
• Low-bit authoring rule: text and background on opposite sides of the threshold (light-on-dark, with a white border halo if the block is busy). Contrast is the recipe's responsibility on 1-bit, and the bitmap preview should make a failing pair obvious before deploy.

Authors keep full control either way: dither-* for simulated gray on 1-bit, or solid color that degrades to its L* on grayscale screens. Soft-enforce via docs + preview, not by re-adding frame-wide FS.