Variable Glyph Bank Palette Serialization
This commit is contained in:
@@ -1,136 +0,0 @@
|
||||
---
|
||||
id: PLN-0081
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Packer and Studio Spec Propagation
|
||||
status: done
|
||||
created: 2026-05-23
|
||||
completed: 2026-05-23
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- specs
|
||||
- packer
|
||||
- studio
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Propagate `DEC-0037` into the normative Studio and packer specifications before
|
||||
code implementation starts.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` keeps `GLYPH/indexed_v1` but changes its palette contract from
|
||||
RGB565 to RGBA8888. Specs currently still describe RGB565 palette bytes,
|
||||
`convertedRgb565`, and a 2048-byte palette block.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update packer specs for `asset.json` palette metadata and `assets.pa`
|
||||
glyph-bank payload layout.
|
||||
- Update Studio asset workspace specs if they expose palette metadata or
|
||||
details/read projection behavior.
|
||||
- Preserve the fixed 64-palette model and explicitly leave `DSC-0005` for a
|
||||
later palette-count optimization.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Code changes.
|
||||
- Test changes.
|
||||
- Variable palette-count serialization.
|
||||
- Runtime spec changes, except references to runtime `DEC-0029`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update asset declaration palette fields
|
||||
|
||||
**What:** Replace `originalArgb8888`/`convertedRgb565` examples and rules with
|
||||
canonical `rgba8888`.
|
||||
|
||||
**How:** Edit the palette portions of the asset declaration spec so
|
||||
`output.pipeline.palettes[*].palette.rgba8888` is the canonical field. State
|
||||
that ARGB may be an input API detail but is not canonical authored/projected
|
||||
palette data.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
|
||||
### Step 2 - Update glyph-bank payload layout
|
||||
|
||||
**What:** Change `GLYPH/indexed_v1` palette layout from RGB565 to RGBA8888.
|
||||
|
||||
**How:** Keep the format name. Change the palette block from
|
||||
`64 * 16 * 2 = 2048` bytes to `64 * 16 * 4 = 4096` bytes. Update size and
|
||||
decoded-size formulas. State that palette entries use runtime RGBA channel
|
||||
order.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
|
||||
### Step 3 - Document alpha and index semantics
|
||||
|
||||
**What:** Document that palette index `0` is ordinary and all 16 palette entries
|
||||
are usable.
|
||||
|
||||
**How:** Add normative rules that transparency and partial transparency are
|
||||
encoded only by RGBA alpha, magenta color-key is removed, and partial alpha is
|
||||
valid palette data.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
|
||||
### Step 4 - Update Studio-facing projection rules
|
||||
|
||||
**What:** Ensure Studio-facing docs use `rgba8888` where palette metadata is
|
||||
visible.
|
||||
|
||||
**How:** Update asset workspace language only where it describes palette read,
|
||||
details, scene preview, or palette default behavior. Keep scene `palette_id`
|
||||
semantics unchanged.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Not applicable for this spec-only plan.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Not applicable for this spec-only plan.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search specs for stale `RGB565`, `convertedRgb565`, 2048-byte palette block,
|
||||
reserved index `0`, and magenta color-key language.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Packer specs define `rgba8888` as the canonical palette field.
|
||||
- [x] `GLYPH/indexed_v1` remains named exactly that.
|
||||
- [x] Palette block formulas use `64 * 16 * 4 = 4096`.
|
||||
- [x] Specs state palette index `0` is ordinary and all 16 entries are usable.
|
||||
- [x] Specs state partial alpha is valid and magenta color-key is removed.
|
||||
- [x] Specs leave `DSC-0005` variable palette-count work out of scope.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on accepted `DEC-0037`.
|
||||
- Should complete before code plans are implemented.
|
||||
|
||||
## Risks
|
||||
|
||||
- Leaving stale RGB565 examples in specs will make implementation review
|
||||
ambiguous.
|
||||
- Over-editing scene specs could accidentally imply a scene payload change that
|
||||
`DEC-0037` does not authorize.
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
id: PLN-0082
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Palette Model and ARGB Conversion
|
||||
status: done
|
||||
created: 2026-05-23
|
||||
completed: 2026-05-23
|
||||
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
|
||||
|
||||
- [x] `PackerPaletteV1` exposes `rgba8888` and no RGB565 field.
|
||||
- [x] `PackerGlyphBankWalker` stores canonical RGBA values.
|
||||
- [x] Magenta is not special.
|
||||
- [x] Alpha zero and partial alpha are valid palette data.
|
||||
- [x] All 16 palette indices are usable.
|
||||
- [x] 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.
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
id: PLN-0083
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Glyph Payload Emission and Size Accounting
|
||||
status: done
|
||||
created: 2026-05-23
|
||||
completed: 2026-05-23
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- packer
|
||||
- assets-pa
|
||||
- glyph-bank
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Change packer glyph-bank runtime payload emission from RGB565 palette bytes to
|
||||
RGBA8888 palette bytes while keeping `GLYPH/indexed_v1` and the fixed
|
||||
64-palette model.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` requires `GLYPH/indexed_v1` to retain its format name and indexed
|
||||
model but emit RGBA8888 palette entries. Current payload emission in
|
||||
`FileSystemPackerWorkspaceService` writes RGB565 bytes, reserves index `0`, and
|
||||
uses color-key bytes.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update glyph-bank payload palette byte emission.
|
||||
- Update measured payload size and decoded-size accounting.
|
||||
- Remove RGB565 palette constants and palette color-key bytes from emission.
|
||||
- Keep scene `palette_id` payload semantics unchanged.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Palette model extraction changes covered by `PLN-0082`.
|
||||
- Read/detail projection changes covered by `PLN-0084`.
|
||||
- Variable palette count.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update glyph payload constants and formulas
|
||||
|
||||
**What:** Change palette entry width from 2 bytes to 4 bytes.
|
||||
|
||||
**How:** Introduce clear constants for palette count, colors per palette, and
|
||||
RGBA bytes per color. Use `64 * 16 * 4` for palette block size.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
|
||||
### Step 2 - Emit RGBA8888 palette bytes
|
||||
|
||||
**What:** Write each palette color as runtime RGBA channel bytes.
|
||||
|
||||
**How:** Replace RGB565 little-endian writes with four byte writes in `R`, `G`,
|
||||
`B`, `A` order derived from the canonical `rgba8888` integer value.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 3 - Remove reserved color-key emission
|
||||
|
||||
**What:** Stop writing a synthetic color-key value at palette index `0`.
|
||||
|
||||
**How:** Remove `GLYPH_BANK_COLOR_KEY_RGB565` and any emission path that fills
|
||||
index `0` with magenta. Emit declared RGBA values for index `0` like every
|
||||
other index.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 4 - Update declared palette lookup
|
||||
|
||||
**What:** Read `rgba8888` from declared pipeline metadata.
|
||||
|
||||
**How:** Replace `originalArgb8888`/`convertedRgb565` lookup paths with
|
||||
`rgba8888`. Ensure empty or malformed `rgba8888` is structural failure where
|
||||
emission requires a palette.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
|
||||
### Step 5 - Keep scene payload stable
|
||||
|
||||
**What:** Preserve scene `palette_id` layout.
|
||||
|
||||
**How:** Do not change `writeSceneBankPayload` except compile fixes caused by
|
||||
shared helper changes. Scene tile records continue carrying `palette_id` as an
|
||||
index into the referenced glyph palette.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Add or update tests asserting glyph payload size includes a 4096-byte palette
|
||||
block.
|
||||
- Assert emitted palette bytes for a known RGBA value, including alpha.
|
||||
- Assert index `0` emits declared RGBA data, not magenta.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Update workspace build tests that read `build/assets.pa` and assert glyph-bank
|
||||
offsets/sizes.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search production packer code for `GLYPH_BANK_COLOR_KEY_RGB565`,
|
||||
`convertedRgb565`, RGB565 palette byte writes, and hard-coded `2048`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Glyph payloads keep `GLYPH/indexed_v1`.
|
||||
- [x] Glyph palette blocks are 4096 bytes.
|
||||
- [x] Palette entries are emitted as RGBA bytes in runtime channel order.
|
||||
- [x] No synthetic magenta/color-key value is emitted.
|
||||
- [x] Size and decoded-size metadata match the new payload length.
|
||||
- [x] Scene `palette_id` payload shape is unchanged.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0082`.
|
||||
- Should run before tests/fixture conformance in `PLN-0085`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Updating size formulas without updating emitted bytes, or vice versa, will
|
||||
corrupt payload slicing in `assets.pa`.
|
||||
- Accidental scene payload edits could widen the change beyond `DEC-0037`.
|
||||
@@ -1,141 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,141 +0,0 @@
|
||||
---
|
||||
id: PLN-0085
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Tests, Fixtures, and Conformance Updates
|
||||
status: done
|
||||
created: 2026-05-23
|
||||
completed: 2026-05-23
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- tests
|
||||
- fixtures
|
||||
- conformance
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Update packer tests and fixtures so RGBA8888 is the asserted source of truth and
|
||||
RGB565-specific expectations are removed.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` requires tests and fixtures to stop proving RGB565 behavior. The code
|
||||
base has parser, walker, details, materializer, and workspace service tests that
|
||||
mention `convertedRgb565`, `originalArgb8888`, 15-color limits, magenta
|
||||
color-key behavior, and RGB565 payload sizes.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update packer unit tests and integration-style workspace tests.
|
||||
- Update fixture `asset.json` files under packer test resources.
|
||||
- Add conformance-oriented assertions for RGBA channel order, alpha, index `0`,
|
||||
16 usable colors, and removed color-key behavior.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Manual regeneration of `test-projects/main` and `fragments`.
|
||||
- Production code changes except minor compile-fix test helpers.
|
||||
- Runtime repository tests.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update parser and details tests
|
||||
|
||||
**What:** Replace palette payload fixtures with `rgba8888`.
|
||||
|
||||
**How:** Rewrite test JSON snippets and assertions that mention
|
||||
`originalArgb8888` or `convertedRgb565`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDeclarationParserTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDetailsServiceTest.java`
|
||||
|
||||
### Step 2 - Update glyph walker tests
|
||||
|
||||
**What:** Assert new palette extraction semantics.
|
||||
|
||||
**How:** Add image fixtures in tests that cover:
|
||||
16 colors, 17-color failure, alpha 0, partial alpha, magenta as ordinary color,
|
||||
and index `0` as ordinary.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`
|
||||
|
||||
### Step 3 - Update materializer and workspace service tests
|
||||
|
||||
**What:** Assert RGBA8888 runtime payload and metadata behavior.
|
||||
|
||||
**How:** Update tests that read `assets.pa`, measured bank size, payload offsets,
|
||||
and palette byte expectations. Replace RGB565 byte checks with RGBA byte checks.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimePatchServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimeRegistryTest.java`
|
||||
|
||||
### Step 4 - Update packer fixture assets
|
||||
|
||||
**What:** Replace fixture `asset.json` palette fields with `rgba8888`.
|
||||
|
||||
**How:** Edit packer test fixtures under `src/test/resources/fixtures` so
|
||||
canonical palette declarations do not contain `convertedRgb565`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/**/asset.json`
|
||||
|
||||
### Step 5 - Add stale-contract guards
|
||||
|
||||
**What:** Add tests or quality checks that catch old RGB565 palette contract
|
||||
residue.
|
||||
|
||||
**How:** Add assertions in existing tests or a focused repository quality test
|
||||
that normal packer specs/tests/fixtures do not contain `convertedRgb565` or
|
||||
RGB565 glyph palette payload expectations.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Existing packer test suites under `prometeu-packer/prometeu-packer-v1/src/test/java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Parser, details, mapper, glyph walker, and workspace service unit tests must
|
||||
all pass.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Run the relevant Gradle test task for `prometeu-packer-v1`.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search for `convertedRgb565`, `originalArgb8888`, `RGB565`, `rgb565`, `2048`,
|
||||
and magenta color-key references in packer tests and fixtures.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Tests use `rgba8888` as canonical palette data.
|
||||
- [x] Tests assert RGBA channel order and alpha preservation.
|
||||
- [x] Tests assert 16 usable palette entries.
|
||||
- [x] Tests assert magenta is ordinary or no longer special.
|
||||
- [x] Tests assert 4096-byte palette blocks where payload size is checked.
|
||||
- [x] Packer test fixtures no longer rely on `convertedRgb565`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0082`, `PLN-0083`, and `PLN-0084`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Some stale generated fixture data may be easier to regenerate than hand-edit.
|
||||
- Overbroad residue checks could flag historical discussion artifacts; scope
|
||||
checks to normal specs, code, tests, and fixtures.
|
||||
@@ -1,159 +0,0 @@
|
||||
---
|
||||
id: PLN-0086
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Final Integration and Residue Removal
|
||||
status: done
|
||||
created: 2026-05-23
|
||||
completed: 2026-05-23
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- integration
|
||||
- validation
|
||||
- residue-removal
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Run final integration checks and remove normal-path RGB565 residue after the
|
||||
spec, model, emission, projection, and test plans are implemented.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` prohibits RGB565 compatibility mode, normal `convertedRgb565`
|
||||
projection, magenta color-key behavior, reserved palette index `0`, and partial
|
||||
alpha flattening. Final validation must prove that the repository implements
|
||||
those constraints coherently.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Repository-wide residue audit.
|
||||
- Full relevant Gradle test execution.
|
||||
- Discussion workflow validation.
|
||||
- Final implementation notes for follow-up plan or lesson creation.
|
||||
|
||||
### Excluded
|
||||
|
||||
- New feature design.
|
||||
- Runtime repository changes.
|
||||
- Variable palette-count work in `DSC-0005`.
|
||||
- Manual regeneration of `main` and `fragments`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Run focused residue searches
|
||||
|
||||
**What:** Find stale RGB565 palette-contract residue.
|
||||
|
||||
**How:** Search production specs/code/tests/fixtures for:
|
||||
`convertedRgb565`, `originalArgb8888`, `RGB565`, `rgb565`, `COLOR_KEY`,
|
||||
`magenta`, `2048`, `indices 1..15`, and partial-alpha flattening text.
|
||||
Classify each match as removed, historical discussion-only, or out-of-scope.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/**`
|
||||
- `docs/specs/studio/**`
|
||||
- `prometeu-packer/**`
|
||||
|
||||
### Step 2 - Run packer tests
|
||||
|
||||
**What:** Execute the packer test suite.
|
||||
|
||||
**How:** Run the Gradle test task that covers `prometeu-packer-v1` and related
|
||||
API modules.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Gradle modules under `prometeu-packer`
|
||||
|
||||
### Step 3 - Run broader build validation
|
||||
|
||||
**What:** Verify Studio build integration still compiles.
|
||||
|
||||
**How:** Run the repository's standard build or the narrowest existing Gradle
|
||||
task that compiles Studio plus packer consumers.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Root Gradle project
|
||||
- `prometeu-app`
|
||||
- `prometeu-packer`
|
||||
|
||||
### Step 4 - Validate discussion workflow
|
||||
|
||||
**What:** Ensure discussion artifacts remain consistent.
|
||||
|
||||
**How:** Run `discussion validate` after implementation and before any
|
||||
housekeeping.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `discussion/index.ndjson`
|
||||
- `discussion/workflow/**`
|
||||
|
||||
### Step 5 - Record remaining intentional residue
|
||||
|
||||
**What:** Document any allowed remaining RGB565 references.
|
||||
|
||||
**How:** If matches remain only in historical discussions, runtime references,
|
||||
or explicit future migration notes, list them in the implementation summary so
|
||||
housekeeping and lesson work can distinguish intentional context from missed
|
||||
normal-path behavior.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Implementation summary or future lesson, after code work is complete.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Packer unit tests must pass.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Packer workspace build/materialization tests must pass.
|
||||
- Studio compile/build validation must pass.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Residue search results must contain no normal-path `convertedRgb565`,
|
||||
RGB565 glyph palette payload, magenta color-key, reserved index `0`, or
|
||||
partial-alpha flattening behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] `discussion validate` passes.
|
||||
- [x] Packer tests pass.
|
||||
- [x] Studio/packer build validation passes.
|
||||
- [x] Normal specs/code/tests/fixtures contain no stale RGB565 glyph-palette
|
||||
contract residue.
|
||||
- [x] Remaining stale-looking matches, if any, are documented as historical or
|
||||
explicitly out of scope.
|
||||
- [x] `DSC-0005` remains untouched except by explicit future work.
|
||||
|
||||
## Execution Notes
|
||||
|
||||
- `discussion validate` passed.
|
||||
- `./gradlew build` passed.
|
||||
- Residue search found only:
|
||||
- normative spec statements explicitly saying `convertedRgb565` and magenta
|
||||
color-key behavior are not normal contract;
|
||||
- `test-projects/main` asset manifests, which are intentionally out of scope
|
||||
for this implementation because they will be regenerated manually later.
|
||||
- `DSC-0005` was not modified.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0081` through `PLN-0085`.
|
||||
|
||||
## Risks
|
||||
|
||||
- A broad residue search may include historical discussions and cause false
|
||||
positives.
|
||||
- Generated project cache files may change during tests; those changes must be
|
||||
reviewed separately from source edits.
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
id: PLN-0087
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Variable Glyph Palette Spec Propagation
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0038
|
||||
tags:
|
||||
- specs
|
||||
- packer
|
||||
- studio
|
||||
- glyph-bank
|
||||
- palette-serialization
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Propagate `DEC-0038` into the canonical Studio and packer specifications before
|
||||
code changes start.
|
||||
|
||||
## Background
|
||||
|
||||
Runtime `DEC-0041` makes `palette_count` the serialized and resident palette
|
||||
count for `GLYPH/indexed_v1`. Studio/packer `DEC-0038` adopts that runtime
|
||||
contract downstream. Current packer specs still describe a fixed
|
||||
`64 * 16 * 4 = 4096` palette block and `palette_count = 64`.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update packer specs for glyph-bank metadata, payload layout, and size formulas.
|
||||
- Update Studio specs only where Studio-facing palette count projection or asset
|
||||
details are documented.
|
||||
- Preserve RGBA8888 channel order, packed `u4` pixels, and `GLYPH/indexed_v1`.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Code changes.
|
||||
- Fixture regeneration.
|
||||
- Runtime spec changes.
|
||||
- Any `GLYPH/indexed_v2` design.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update asset declaration metadata rules
|
||||
|
||||
**What:** Define `palette_count` as the effective runtime metadata field.
|
||||
|
||||
**How:** Update glyph-bank declaration language so `palette_count` means the
|
||||
number of serialized and resident RGBA8888 palettes, constrained to `1..=64`.
|
||||
State that `palette_authored`, if present, is informative and not runtime
|
||||
effective.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
|
||||
### Step 2 - Update glyph payload layout
|
||||
|
||||
**What:** Replace fixed 4096-byte palette block text.
|
||||
|
||||
**How:** Change the layout to `palette_count * 16 * 4` palette bytes and update
|
||||
formulas to:
|
||||
|
||||
```text
|
||||
size = ceil(width * height / 2) + palette_count * 16 * 4
|
||||
decoded_size = width * height + palette_count * 16 * 4
|
||||
```
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
|
||||
### Step 3 - Preserve v1 boundaries
|
||||
|
||||
**What:** Explicitly prohibit v2, compatibility padding, and remapping.
|
||||
|
||||
**How:** Add rules that this remains `GLYPH/indexed_v1`, old fixed-padding is
|
||||
not a compatibility mode, and v1 has no sparse-to-dense palette remapping.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
|
||||
### Step 4 - Update Studio-facing spec text
|
||||
|
||||
**What:** Align Studio projections if they mention palette count or fixed bank
|
||||
shape.
|
||||
|
||||
**How:** Search the Studio asset workspace spec for palette projection, details,
|
||||
or pack wizard language and update only stale fixed-count wording.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Not applicable for this spec-only plan.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Not applicable for this spec-only plan.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search specs for stale normal-path `palette_count = 64`, `4096`, fixed
|
||||
64-palette block, `GLYPH/indexed_v2`, and remapping language.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Packer specs define `palette_count` as runtime-effective `1..=64`.
|
||||
- [ ] Packer specs use variable palette byte and size formulas.
|
||||
- [ ] Specs keep `GLYPH/indexed_v1` and reject v2 for this change.
|
||||
- [ ] Specs reject fixed-padding compatibility and sparse-to-dense remapping.
|
||||
- [ ] Studio specs contain no stale fixed 64-palette projection wording.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on accepted `DEC-0038`.
|
||||
- Should complete before code plans.
|
||||
|
||||
## Risks
|
||||
|
||||
- Leaving stale fixed 4096-byte examples will make implementation review
|
||||
ambiguous.
|
||||
- Over-editing Studio specs could imply UI behavior not required by `DEC-0038`.
|
||||
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
id: PLN-0088
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Variable Glyph Palette Metadata and Count Model
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0038
|
||||
tags:
|
||||
- packer
|
||||
- metadata
|
||||
- glyph-bank
|
||||
- palette-count
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Make packer metadata compute and expose runtime-effective glyph-bank
|
||||
`palette_count` from declared palette data instead of hard-coding `64`.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0038` requires `palette_count` to describe the number of serialized and
|
||||
resident palettes expected by runtime. Current packer code emits
|
||||
`palette_count = 64` and uses `palette_authored` for the actual authored count.
|
||||
That makes the informative count and effective runtime count diverge.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Compute effective glyph palette count from declared `output.pipeline.palettes`.
|
||||
- Validate `palette_count` in `1..=64`.
|
||||
- Keep palette identity direct; do not remap sparse authored indices.
|
||||
- Stop using `palette_authored` as a runtime-effective field.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Binary payload byte emission.
|
||||
- Size formula changes.
|
||||
- Studio UI changes except compile-safe DTO/projection adjustments.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Add a runtime-effective palette count helper
|
||||
|
||||
**What:** Centralize effective glyph palette count calculation.
|
||||
|
||||
**How:** Add or update helper logic so packer derives `palette_count` from
|
||||
declared palette indices. Because v1 has no remapping, the effective count must
|
||||
cover the highest direct palette id: `max(index) + 1`. Reject no palettes,
|
||||
negative indices, duplicate indices, and any effective count above `64`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`
|
||||
|
||||
### Step 2 - Replace fixed runtime metadata
|
||||
|
||||
**What:** Stop writing `palette_count = 64` unconditionally.
|
||||
|
||||
**How:** Replace runtime metadata emission so glyph-bank entries publish the
|
||||
computed runtime-effective `palette_count`. Keep `palette_authored` only if it
|
||||
is useful as pipeline/tooling information and never as runtime-effective root
|
||||
metadata.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
|
||||
### Step 3 - Validate direct palette identity
|
||||
|
||||
**What:** Preserve runtime direct `palette_id` semantics.
|
||||
|
||||
**How:** Ensure packer does not compact or renumber palette indices. If palette
|
||||
indices are sparse, emitted palette slots up to `palette_count - 1` must keep
|
||||
their direct identity, with missing slots represented by deterministic default
|
||||
RGBA8888 palette data only when required to preserve direct ids.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
||||
|
||||
### Step 4 - Update projections that expose metadata
|
||||
|
||||
**What:** Align details/read projections with the effective count.
|
||||
|
||||
**How:** Ensure packer read/details APIs expose `palette_count` consistently
|
||||
where runtime metadata is projected, and do not present `palette_authored` as
|
||||
the field that runtime consumes.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Parser/metadata tests for `palette_count = 1`, intermediate count, and `64`.
|
||||
- Rejection tests for zero effective palettes, duplicate indices, negative
|
||||
indices, and count above `64`.
|
||||
- Sparse direct identity tests where palette index `3` implies
|
||||
`palette_count = 4`, without remapping palette `3` to `0`.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Workspace read/build test proving asset table metadata reports variable
|
||||
`palette_count`.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search packer code for `palette_count = 64` and `GLYPH_BANK_PALETTE_COUNT`
|
||||
assumptions after the change.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Packer computes runtime-effective `palette_count` from declared palettes.
|
||||
- [ ] `palette_count` is validated as `1..=64`.
|
||||
- [ ] Sparse palette ids are not remapped.
|
||||
- [ ] `palette_authored` is not treated as runtime-effective metadata.
|
||||
- [ ] Read/details projections do not expose stale fixed-count assumptions.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0087`.
|
||||
- Must complete before payload emission changes in `PLN-0089`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Sparse palette handling can accidentally become remapping if implemented by
|
||||
sorting and compacting declarations.
|
||||
- Keeping `palette_authored` in tooling may confuse readers unless tests prove
|
||||
runtime-effective metadata uses `palette_count`.
|
||||
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
id: PLN-0089
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Variable Glyph Palette Payload Emission and Size Accounting
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0038
|
||||
tags:
|
||||
- packer
|
||||
- assets-pa
|
||||
- glyph-bank
|
||||
- payload
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Change packer `GLYPH/indexed_v1` payload emission from a fixed 64-palette block
|
||||
to exactly `palette_count * 16 * 4` RGBA8888 bytes, with matching size and
|
||||
decoded-size accounting.
|
||||
|
||||
## Background
|
||||
|
||||
`FileSystemPackerWorkspaceService` currently defines fixed palette constants
|
||||
and emits a fixed `GLYPH_BANK_PALETTE_BYTES` block. `DEC-0038` requires packer
|
||||
to emit only the runtime-effective palette count and compute asset table sizes
|
||||
from that count.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Replace fixed palette byte constants with count-dependent formulas.
|
||||
- Emit exactly `palette_count` palettes in RGBA byte order.
|
||||
- Update asset table `size` and `decoded_size`.
|
||||
- Reject metadata/payload mismatches.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Palette model extraction changes covered by `PLN-0088`.
|
||||
- Studio UI changes.
|
||||
- Runtime code changes.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Replace fixed palette byte constants
|
||||
|
||||
**What:** Remove normal-path fixed `64 * 16 * 4` size assumptions.
|
||||
|
||||
**How:** Keep maximum constants such as `MAX_PALETTE_COUNT = 64`, but compute
|
||||
payload palette bytes as `palette_count * 16 * 4` at each glyph-bank packing
|
||||
boundary.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
|
||||
### Step 2 - Emit variable palette bytes
|
||||
|
||||
**What:** Write only runtime-effective palettes.
|
||||
|
||||
**How:** Update palette byte generation to allocate
|
||||
`palette_count * 16 * 4` bytes and fill direct palette ids from `0` through
|
||||
`palette_count - 1`. Each color remains RGBA8888 in `R`, `G`, `B`, `A` order.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 3 - Update size and decoded-size formulas
|
||||
|
||||
**What:** Align asset table sizes with runtime `DEC-0041`.
|
||||
|
||||
**How:** Compute:
|
||||
|
||||
```text
|
||||
size = ceil(width * height / 2) + palette_count * 16 * 4
|
||||
decoded_size = width * height + palette_count * 16 * 4
|
||||
```
|
||||
|
||||
Use these formulas for asset table entries, materializer expectations, and
|
||||
workspace build outputs.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
|
||||
### Step 4 - Reject metadata/payload mismatches
|
||||
|
||||
**What:** Prevent stale fixed-padding artifacts.
|
||||
|
||||
**How:** Add validation that emitted palette byte length, root metadata
|
||||
`palette_count`, `size`, and `decoded_size` agree. Do not allow a fixed
|
||||
64-palette block when `palette_count < 64`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Assert emitted palette bytes for `palette_count = 1`, an intermediate count,
|
||||
and `64`.
|
||||
- Assert `size` and `decoded_size` formulas for variable counts.
|
||||
- Assert RGBA byte order is unchanged.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Build a workspace and inspect `assets.pa` asset table and payload length for
|
||||
variable palette counts.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search for fixed normal-path `4096`, `64 * 16 * 4`, and
|
||||
`GLYPH_BANK_PALETTE_BYTES` residue.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Glyph payloads emit exactly `palette_count * 16 * 4` palette bytes.
|
||||
- [ ] Asset table `size` and `decoded_size` use variable formulas.
|
||||
- [ ] RGBA byte order is unchanged.
|
||||
- [ ] Fixed 64-palette padding is emitted only when `palette_count = 64`.
|
||||
- [ ] Metadata/payload mismatch is rejected or impossible by construction.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0088`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Updating metadata without payload length will corrupt runtime slicing.
|
||||
- Updating payload length without decoded-size metadata will fail runtime asset
|
||||
validation.
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: PLN-0090
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Studio and Packer Projections for Variable Glyph Palettes
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0038
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- api
|
||||
- projections
|
||||
- glyph-bank
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Align Studio-facing and packer-facing projections so variable glyph
|
||||
`palette_count` is visible and not confused with `palette_authored`.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0038` says packer metadata projection and Studio-facing read/detail APIs
|
||||
must expose the runtime-effective `palette_count` correctly. Studio code must
|
||||
not treat `palette_authored` as the runtime-effective count.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update packer read/detail DTO projections where runtime metadata is surfaced.
|
||||
- Update Studio asset details, palette overhauling, schema, or pack wizard code
|
||||
if it reads fixed counts or authored counts as runtime-effective.
|
||||
- Keep `rgba8888` color projection unchanged.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Binary payload emission.
|
||||
- General palette UI redesign.
|
||||
- `originalArgb8888` UI fallback cleanup unrelated to variable `palette_count`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Audit projection boundaries
|
||||
|
||||
**What:** Find all Studio/packer paths that expose glyph palette metadata.
|
||||
|
||||
**How:** Search for `palette_count`, `palette_authored`,
|
||||
`GLYPH_BANK_PALETTE_COUNT`, fixed `64`, and related asset details projections.
|
||||
Classify each match as runtime-effective metadata, tooling-only metadata, UI
|
||||
fallback, or unrelated.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**`
|
||||
|
||||
### Step 2 - Update packer details/read surfaces
|
||||
|
||||
**What:** Expose runtime-effective `palette_count`.
|
||||
|
||||
**How:** Ensure details/read projections show the `palette_count` that will be
|
||||
written to the runtime asset table. Preserve `palette_authored` only as
|
||||
explicitly tooling-only information if it remains useful.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java`
|
||||
|
||||
### Step 3 - Update Studio consumers
|
||||
|
||||
**What:** Prevent Studio from using authored count as runtime count.
|
||||
|
||||
**How:** Adjust Studio asset details and pack wizard code so any displayed or
|
||||
validated runtime count comes from effective `palette_count`. Keep palette
|
||||
color rendering based on `rgba8888`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/**`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/**`
|
||||
|
||||
### Step 4 - Preserve scene palette id shape
|
||||
|
||||
**What:** Avoid accidental scene payload changes.
|
||||
|
||||
**How:** Confirm scene projections still carry `palette_id` unchanged and only
|
||||
runtime/packer validation changes count semantics.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Packer details/read tests for variable `palette_count`.
|
||||
- Studio asset details tests proving runtime count and authored/tooling count
|
||||
are not conflated.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Workspace read/build flow where a glyph bank with an intermediate
|
||||
`palette_count` is projected through packer/Studio surfaces.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search Studio and packer projection code for stale assumptions that
|
||||
`palette_authored` is runtime-effective.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Packer read/details projections expose effective `palette_count`.
|
||||
- [ ] Studio consumers do not use `palette_authored` as runtime-effective count.
|
||||
- [ ] `rgba8888` color projection remains unchanged.
|
||||
- [ ] Scene `palette_id` payload shape is unchanged.
|
||||
- [ ] Tests cover variable count projection.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0088`.
|
||||
- Can run in parallel with `PLN-0089` after metadata semantics are stable.
|
||||
|
||||
## Risks
|
||||
|
||||
- UI code may still need ARGB helper fields for presentation. This plan must not
|
||||
turn that into a runtime metadata decision.
|
||||
- Overbroad projection edits could accidentally change scene contracts.
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
---
|
||||
id: PLN-0091
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Variable Glyph Palette Tests, Fixtures, and Final Validation
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0038
|
||||
tags:
|
||||
- tests
|
||||
- fixtures
|
||||
- validation
|
||||
- glyph-bank
|
||||
- palette-serialization
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Update tests and fixtures to prove Studio/packer emit runtime-conforming
|
||||
variable glyph palette payloads and contain no stale fixed-padding assumptions.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0038` requires downstream fixture coverage for `palette_count = 1`, an
|
||||
intermediate count, and `palette_count = 64`, plus producer validation for
|
||||
metadata/payload mismatch. Earlier tests still assert `palette_count = 64`,
|
||||
4096-byte palette blocks, and fixed glyph payload sizes.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update packer unit tests and integration-style workspace tests.
|
||||
- Update packer fixture `asset.json` files and expected runtime payload checks.
|
||||
- Update Studio tests only where Studio projections or UI logic expose
|
||||
effective palette count.
|
||||
- Run focused and broad validation.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Runtime repository tests.
|
||||
- New feature design.
|
||||
- Palette remapping behavior.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update packer parser and metadata tests
|
||||
|
||||
**What:** Prove effective `palette_count` validation.
|
||||
|
||||
**How:** Add tests for `palette_count = 1`, intermediate counts, `64`,
|
||||
duplicate/sparse direct identity behavior, and rejection above `64`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDeclarationParserTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`
|
||||
|
||||
### Step 2 - Update payload and asset table tests
|
||||
|
||||
**What:** Prove variable payload lengths and size formulas.
|
||||
|
||||
**How:** Replace fixed 4096-byte expectations with
|
||||
`palette_count * 16 * 4`. Assert `size`, `decoded_size`, payload offsets, and
|
||||
RGBA bytes for several counts.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimePatchServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimeRegistryTest.java`
|
||||
|
||||
### Step 3 - Update fixtures
|
||||
|
||||
**What:** Replace stale fixed-padding fixtures.
|
||||
|
||||
**How:** Regenerate or edit packer test fixtures so at least one glyph bank uses
|
||||
`palette_count = 1`, one uses an intermediate count, and one uses `64`.
|
||||
Fixtures with fixed 64 padding are valid only when metadata says
|
||||
`palette_count = 64`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/**/asset.json`
|
||||
- Related binary or generated expected payload fixtures under packer test
|
||||
resources.
|
||||
|
||||
### Step 4 - Update Studio tests
|
||||
|
||||
**What:** Cover Studio-facing projection changes.
|
||||
|
||||
**How:** Adjust tests only where Studio surfaces effective palette counts or
|
||||
metadata. Keep color rendering assertions focused on `rgba8888`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/**`
|
||||
|
||||
### Step 5 - Run validation and residue scans
|
||||
|
||||
**What:** Prove no normal-path fixed-padding residue remains.
|
||||
|
||||
**How:** Run relevant Gradle tests and search normal specs/code/tests/fixtures
|
||||
for stale `palette_count = 64`, `4096`, fixed `64 * 16 * 4`, `GLYPH/indexed_v2`,
|
||||
and sparse remapping language. Classify any remaining match as historical,
|
||||
max-bound, or a bug.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/**`
|
||||
- `docs/specs/studio/**`
|
||||
- `prometeu-packer/**`
|
||||
- `prometeu-studio/**`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Packer parser, walker, materializer, details/read, and workspace service tests
|
||||
pass.
|
||||
- Studio asset details tests pass where touched.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Packer workspace build/materialization tests pass.
|
||||
- Repository build or narrow Studio/packer build validation passes.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Residue scan finds no normal-path fixed-padding contract text or code.
|
||||
- `discussion validate` passes.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Tests cover `palette_count = 1`, an intermediate count, and `64`.
|
||||
- [ ] Tests cover variable `size` and `decoded_size`.
|
||||
- [ ] Tests cover emitted palette byte length and RGBA order.
|
||||
- [ ] Tests cover metadata/payload mismatch rejection or producer validation.
|
||||
- [ ] Fixtures no longer rely on fixed 64-palette padding unless count is `64`.
|
||||
- [ ] Validation commands pass.
|
||||
- [ ] Residue scan results are clean or explicitly classified.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0087`, `PLN-0088`, `PLN-0089`, and `PLN-0090`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Generated project fixtures may require regeneration rather than manual edits.
|
||||
- Broad residue scans may include historical discussions; scope final checks to
|
||||
active specs, code, tests, and fixtures.
|
||||
Reference in New Issue
Block a user