135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
---
|
|
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.
|