---
id: PLN-0082
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Palette Model and ARGB Conversion
status: review
created: 2026-05-23
completed:
ref_decisions:
  - DEC-0037
tags:
  - 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.