prometeu-studio/discussion/workflow/plans/PLN-0082-rgba8888-palette-model-and-argb-conversion.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0082	studio-packer-rgba8888-asset-pipeline	RGBA8888 Palette Model and ARGB Conversion	review	2026-05-23		DEC-0037	packer palette rgba8888 conversion

Objective

Replace the packer palette model with canonical RGBA8888 data and introduce a single deliberate ARGB-to-RGBA conversion boundary for image inputs.

Background

PackerPaletteV1 currently stores originalArgb8888 and convertedRgb565. PackerGlyphBankWalker reads Java ARGB pixels, drops alpha semantics, reserves index 0, applies magenta color-key, and converts colors to RGB565.

Scope

Included

• Replace PackerPaletteV1 fields with canonical rgba8888.
• Add or localize ARGB-to-RGBA conversion helpers.
• Preserve partial alpha.
• Remove RGB565 conversion from the normal palette model.
• Expand glyph palette extraction from 15 to 16 usable colors.

Excluded

• Binary assets.pa emission changes.
• Read/detail API projection changes outside direct model compile fixes.
• Spec edits.
• Fixture regeneration for main and fragments.

Execution Steps

Step 1 - Replace the palette record

What: Change the packer palette model to carry canonical RGBA8888 values.

How: Replace int[] originalArgb8888, short[] convertedRgb565 with int[] rgba8888. Keep the record name only if it remains semantically useful; otherwise rename only if all callers are updated in the same change.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/PackerPaletteV1.java

Step 2 - Convert ARGB image pixels to RGBA

What: Introduce one conversion path from Java BufferedImage ARGB to raw runtime RGBA.

How: Convert 0xAARRGGBB to 0xRRGGBBAA when building palette entries. Do not store ARGB in canonical packer metadata.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java

Step 3 - Remove magenta color-key and reserved index behavior

What: Stop treating alpha zero or magenta as special palette-index behavior.

How: Remove COLOR_KEY_RGB. Build palette identity from full RGBA8888 values, including alpha. Assign indices from 0 through 15.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java

Step 4 - Preserve partial alpha

What: Remove partial-alpha warnings and flattening.

How: Delete the partialAlphaFound warning path. Ensure pixels with alpha from 0 through 255 participate in palette extraction by full RGBA value.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java

Step 5 - Update color-limit validation

What: Change validation from 15 usable colors to 16 usable colors.

How: Replace MAX_COLORS_PER_PALETTE = 15 with a 16-entry limit and update diagnostic wording to remove indices 1..15.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java

Test Requirements

Unit Tests

• Update PackerGlyphBankWalkerTest to assert:
  • 16 unique RGBA colors are valid.
  • a 17th unique RGBA color is blocking.
  • alpha 0, partial alpha, and alpha 255 are preserved.
  • magenta is treated as an ordinary color.
  • palette index 0 can hold an ordinary color.

Integration Tests

• None for this plan; binary emission is covered by a later plan.

Manual Verification

• Search packer model and glyph walker sources for convertedRgb565, originalArgb8888, COLOR_KEY_RGB, convertToRgb565, and partial-alpha warning text.

Acceptance Criteria

• PackerPaletteV1 exposes rgba8888 and no RGB565 field.
• PackerGlyphBankWalker stores canonical RGBA values.
• Magenta is not special.
• Alpha zero and partial alpha are valid palette data.
• All 16 palette indices are usable.
• Unit tests cover conversion and palette indexing semantics.

Dependencies

• Depends on PLN-0081 for spec wording.
• Must complete before payload emission and projection plans.

Risks

• Confusing Java ARGB input with runtime RGBA output will create hard-to-debug byte-order failures.
• Cache reuse may keep stale palette metadata if reusable metadata checks are not updated with the model change.