---
id: PLN-0084
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Packer Projections and Workspace APIs
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
  - DEC-0037
tags:
  - packer
  - studio
  - api
  - rgba8888
---

## Objective

Update packer and Studio-facing read/detail/write projections so palette data
is exposed and accepted as `rgba8888`, with no normal `convertedRgb565` or
canonical `originalArgb8888` surface.

## Background

`DEC-0037` requires packer metadata, Studio read/detail projections, tests, and
fixtures to stop treating RGB565 as normal palette data. Several services still
parse or project `originalArgb8888` and `convertedRgb565`.

## Scope

### Included

- Update parser and declaration normalization for palette metadata.
- Update read/detail mappers.
- Update palette-overhauling and bank-composition support to emit `rgba8888`.
- Preserve existing DTO shapes except for palette payload field names.

### Excluded

- Binary payload byte emission.
- Renderer/runtime changes.
- Manual regeneration of `main` and `fragments`.

## Execution Steps

### Step 1 - Update asset declaration parsing

**What:** Parse canonical `rgba8888` arrays from `asset.json`.

**How:** Replace palette validation that requires `originalArgb8888` and
`convertedRgb565` with validation for `rgba8888`. Keep numeric validation.
Reject malformed or missing `rgba8888` where a palette payload is required.

**File(s):**

- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`

### Step 2 - Update details projection

**What:** Return `rgba8888` from asset details.

**How:** Change `palettePayloadFromNode` to project `{ index, rgba8888 }`.
Remove `convertedRgb565` and canonical `originalArgb8888` from details output.

**File(s):**

- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`

### Step 3 - Update read message mapping

**What:** Map `PackerPaletteV1` and cached palette metadata to `rgba8888`.

**How:** Replace `originalArgb8888` and `convertedRgb565` mapping with a single
`rgba8888` array.

**File(s):**

- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java`

### Step 4 - Update workspace write operations

**What:** Ensure packer write APIs that apply palette changes persist `rgba8888`.

**How:** Replace palette-overhauling and related write-lane logic that requires
both `originalArgb8888` and `convertedRgb565` with a `rgba8888` contract.

**File(s):**

- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`

### Step 5 - Update cache reuse and walk projection checks

**What:** Make cache reuse validate new palette metadata.

**How:** Replace reusable metadata checks for `originalArgb8888` with
`rgba8888`. Stale cached RGB565-derived metadata must not be considered
reusable.

**File(s):**

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

## Test Requirements

### Unit Tests

- Update parser tests to accept `rgba8888` and reject missing/malformed
  `rgba8888`.
- Update details service tests to assert `rgba8888`.
- Update read mapper coverage for `PackerPaletteV1`.
- Update write operation tests for palette overhauling.

### Integration Tests

- Exercise a workspace read/build flow from `asset.json` using `rgba8888`.

### Manual Verification

- Search `prometeu-packer` for `originalArgb8888` and `convertedRgb565` after
  this plan. Remaining matches must be migration-only or removed in later
  fixture plan.

## Acceptance Criteria

- [x] `asset.json` palette metadata uses `rgba8888`.
- [x] Details/read projections expose `rgba8888`.
- [x] Workspace write operations persist `rgba8888`.
- [x] Stale RGB565-derived cache metadata is not reused as canonical.
- [x] No normal API requires `convertedRgb565`.

## Dependencies

- Depends on `PLN-0082`.
- Can run partly in parallel with `PLN-0083` after the palette model is stable.

## Risks

- DTO consumers may assume old map keys. Tests must cover the Studio-facing
  projection boundary.
- Cache reuse can hide stale behavior if not invalidated by metadata shape.