---
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.