prometeu-runtime/discussion/workflow/plans/PLN-0070-rgba8888-asset-palettes-tooling-and-fixtures.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0070	rgba8888-framebuffer-and-pixel-format-direction	RGBA8888 Asset Palettes Tooling and Fixtures	done	2026-05-23	DEC-0029	gfx framebuffer rgb565 rgba8888 renderer assets host backend

Briefing

Migrate asset palette serialization, decode, generators, and fixtures to RGBA8888. This plan intentionally breaks RGB565 palette compatibility rather than preserving it through runtime fallback.

Source Decisions

• DEC-0029 - RGBA8888 Runtime Pixel Format Contract.

Dependencies

• PLN-0067 for asset spec wording.
• PLN-0068 for RGBA8888 Color.
• PLN-0069 may run before or alongside this plan, but renderer normal paths must not require RGB565 palette compatibility.

Target

assets.pa glyph-bank palette payloads, runtime decode, generators, and tests must use RGBA8888 palette entries with RGBA channel order.

Scope

Included:

• crates/console/prometeu-hal/src/glyph_bank.rs.
• crates/console/prometeu-hal/src/asset.rs.
• crates/console/prometeu-hal/src/cartridge_loader.rs.
• crates/console/prometeu-drivers/src/asset.rs.
• crates/tools/pbxgen-stress/src/lib.rs and related generator code.
• Runtime and system tests that compute glyph-bank payload sizes.
• Test fixtures and generated assets.pa payload builders in the repository.

Out of Scope

• Supporting legacy RGB565 assets at runtime.
• Adding a general asset package v2 negotiation layer unless the existing format requires an explicit version bump to avoid ambiguous decode.
• Changing tile/sprite index packing beyond what RGBA8888 palettes require.
• Changing palette count or colors-per-palette limits.

Execution Plan

1. Change palette byte accounting.

   • Replace palette entry size from size_of::<u16>() / 2 bytes to 4 bytes.
   • Update decoded-size calculations in asset decode, cartridge loader tests, VM runtime tests, and pbxgen-stress.

2. Decode palettes as RGBA8888.

   • Read each palette entry as four bytes in RGBA order.
   • Construct Color through RGBA8888 APIs, not Color(raw_u16).
   • Reject payloads whose palette byte size matches old RGB565 layout when the format can identify the mismatch.

3. Update glyph-bank semantics.

   • Keep pixel_indices: Vec<u8> and 4bpp authored payloads where currently specified.
   • Keep palette count and colors-per-palette constants unless the spec says otherwise.
   • Remove comments that say runtime palettes are RGB565.
   • Ensure palette index 0 is not treated as transparent by decode or data model.

4. Update generators and fixtures.

   • Make pbxgen-stress emit RGBA8888 palette bytes.
   • Regenerate inline fixture builders to append four-byte RGBA palette entries.
   • Do not keep RGB565 fixture decode as runtime compatibility.

5. Update asset tests.

   • Assert RGBA channel order.
   • Include at least one non-opaque alpha value in a palette entry.
   • Assert payload size failures for old two-byte palette layout where practical.

Acceptance Criteria

• Glyph-bank palette payloads are RGBA8888 and use four bytes per entry.
• Asset decode constructs RGBA8888 Color values in RGBA order.
• Existing RGB565 palette payloads are not accepted as compatible runtime input.
• pbxgen-stress emits RGBA8888 palettes.
• Tests include meaningful alpha in palette entries.
• Palette index 0 has no special transparency semantics in asset decode.

Tests / Validation

• Run asset decode tests in prometeu-drivers.
• Run cartridge loader tests in prometeu-hal.
• Run VM runtime asset tests in prometeu-system.
• Run cargo test -p pbxgen-stress if available.
• Run scans for GLYPH_BANK_PALETTE.*u16, * 2, size_of::<u16>(), and RGB565 in asset/glyph-bank/tooling files.
• Run discussion validate.

Risks

• Payload-size constants are duplicated in tests. Update all derived size helpers in the same PR to avoid misleading failures.
• If the existing asset package has no version marker for palette encoding, the plan must choose an explicit metadata/version discriminator before accepting ambiguous payloads.