prometeu-studio/discussion/workflow/plans/PLN-0087-variable-glyph-palette-spec-propagation.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0087	variable-tile-bank-palette-serialization	Variable Glyph Palette Spec Propagation	open	2026-07-14		DEC-0038	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:

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.