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