142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
---
|
|
id: PLN-0084
|
|
ticket: studio-packer-rgba8888-asset-pipeline
|
|
title: RGBA8888 Packer Projections and Workspace APIs
|
|
status: review
|
|
created: 2026-05-23
|
|
completed:
|
|
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
|
|
|
|
- [ ] `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.
|