prometeu-studio/discussion/workflow/plans/PLN-0084-rgba8888-packer-projections-and-workspace-apis.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0084	studio-packer-rgba8888-asset-pipeline	RGBA8888 Packer Projections and Workspace APIs	done	2026-05-23	2026-05-23	DEC-0037	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

• asset.json palette metadata uses rgba8888.
• Details/read projections expose rgba8888.
• Workspace write operations persist rgba8888.
• Stale RGB565-derived cache metadata is not reused as canonical.
• 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.