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