dev/studio-packer-rgba8888-asset-pipeline #11
@ -1,4 +1,5 @@
|
||||
{"type":"meta","next_id":{"DSC":38,"AGD":41,"DEC":37,"PLN":81,"LSN":53,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":39,"AGD":42,"DEC":38,"PLN":87,"LSN":53,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0038","status":"open","ticket":"studio-packer-rgba8888-asset-pipeline","title":"Studio and Packer RGBA8888 Asset Pipeline Alignment","created_at":"2026-05-23","updated_at":"2026-05-23","tags":["studio","packer","assets","glyph-bank","palette","rgba8888","runtime-alignment"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-studio-packer-rgba8888-asset-pipeline.md","status":"accepted","created_at":"2026-05-23","updated_at":"2026-05-23"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-studio-packer-rgba8888-asset-pipeline.md","status":"accepted","created_at":"2026-05-23","updated_at":"2026-05-23","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0081","file":"PLN-0081-rgba8888-packer-and-studio-spec-propagation.md","status":"review","created_at":"2026-05-23","updated_at":"2026-05-23","ref_decisions":["DEC-0037"]},{"id":"PLN-0082","file":"PLN-0082-rgba8888-palette-model-and-argb-conversion.md","status":"review","created_at":"2026-05-23","updated_at":"2026-05-23","ref_decisions":["DEC-0037"]},{"id":"PLN-0083","file":"PLN-0083-rgba8888-glyph-payload-emission-and-sizes.md","status":"review","created_at":"2026-05-23","updated_at":"2026-05-23","ref_decisions":["DEC-0037"]},{"id":"PLN-0084","file":"PLN-0084-rgba8888-packer-projections-and-workspace-apis.md","status":"review","created_at":"2026-05-23","updated_at":"2026-05-23","ref_decisions":["DEC-0037"]},{"id":"PLN-0085","file":"PLN-0085-rgba8888-tests-fixtures-and-conformance.md","status":"review","created_at":"2026-05-23","updated_at":"2026-05-23","ref_decisions":["DEC-0037"]},{"id":"PLN-0086","file":"PLN-0086-rgba8888-final-integration-and-residue-removal.md","status":"review","created_at":"2026-05-23","updated_at":"2026-05-23","ref_decisions":["DEC-0037"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-14","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]}
|
||||
{"type":"discussion","id":"DSC-0036","status":"open","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
|
||||
|
||||
@ -0,0 +1,273 @@
|
||||
---
|
||||
id: AGD-0041
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: Agenda - Studio and Packer RGBA8888 Asset Pipeline Alignment
|
||||
status: accepted
|
||||
created: 2026-05-23
|
||||
resolved: 2026-05-23
|
||||
decision: DEC-0037
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- assets
|
||||
- glyph-bank
|
||||
- palette
|
||||
- rgba8888
|
||||
- runtime-alignment
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio`, with direct subdomain ownership in `packer` and
|
||||
cross-domain dependency on `runtime`.
|
||||
|
||||
The runtime RGBA8888 migration changes the color contract underneath the Studio
|
||||
asset pipeline. Runtime `DEC-0029` says RGBA8888 is the single canonical logical
|
||||
color and physical framebuffer format, and that asset packages must encode
|
||||
palettes as RGBA8888 without preserving RGB565 compatibility.
|
||||
|
||||
Studio still carries RGB565 in the packer-facing asset pipeline:
|
||||
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
defines `GLYPH/indexed_v1` palette payloads as `64 * 16 * 2` bytes of
|
||||
little-endian `RGB565` values.
|
||||
- `PackerPaletteV1` stores both `originalArgb8888` and `convertedRgb565`.
|
||||
- `PackerGlyphBankWalker` drops partial alpha, treats alpha 0 and magenta as
|
||||
transparent index `0`, stores only RGB identity for palette lookup, and
|
||||
converts palette colors to RGB565.
|
||||
- `PackerAssetDetailsService`, `PackerReadMessageMapper`, test fixtures, and
|
||||
project `asset.json` files expose `convertedRgb565` as normal pipeline data.
|
||||
|
||||
The problem is not only changing one serializer. The Studio/packer side must
|
||||
decide how authoring metadata, palette UI/data, emitted `assets.pa`, tests, and
|
||||
existing project fixtures align with runtime RGBA channel order and meaningful
|
||||
alpha.
|
||||
|
||||
## Context
|
||||
|
||||
Runtime discussion context:
|
||||
|
||||
- `../runtime/discussion/workflow/agendas/AGD-0037-rgba8888-framebuffer-and-pixel-format-direction.md`
|
||||
was consulted as the originating discussion.
|
||||
- `../runtime/discussion/workflow/decisions/DEC-0029-rgba8888-runtime-pixel-format-contract.md`
|
||||
is accepted and normative for runtime.
|
||||
- Runtime plans already split execution across specs, HAL/ABI, renderer,
|
||||
asset palettes/tooling, host presentation, and validation.
|
||||
|
||||
Relevant runtime invariants for this Studio discussion:
|
||||
|
||||
- raw color values use RGBA channel order;
|
||||
- asset package palettes must be RGBA8888;
|
||||
- old RGB565 palette assets are not compatible runtime input;
|
||||
- indexed tile/sprite payloads may remain indexed/paletized;
|
||||
- transparency is represented by alpha in the resolved palette entry, not by
|
||||
reserving palette index `0` as a special transparent index;
|
||||
- RGB565 helpers may exist only as temporary migration utilities, not the
|
||||
normal runtime path.
|
||||
|
||||
Relevant Studio/packer state:
|
||||
|
||||
- `assets.pa` is the authoritative runtime-facing artifact owned by the packer.
|
||||
- `output.pipeline` is tooling-only by default, but current glyph palette data
|
||||
lives there and is used by packer details/read flows.
|
||||
- `GLYPH/indexed_v1` currently emits a fixed 256x256 packed `u4` pixel plane
|
||||
plus a fixed 64-palette RGB565 block.
|
||||
- `DSC-0005` is still open around variable tile-bank palette serialization.
|
||||
That discussion optimizes fixed-vs-variable palette count. RGBA8888 changes
|
||||
the color encoding and transparency semantics first, so it should supersede
|
||||
or reframe any RGB565 assumptions before variable palette work continues.
|
||||
- Studio scene publication currently carries `palette_id` in scene pack
|
||||
requests. Scene payload shape is mostly unaffected by color format, but scene
|
||||
previews, palette defaults, validation, and any editor-visible palette data
|
||||
must remain consistent with the glyph-bank contract.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] Should Studio keep the runtime-facing format name `GLYPH/indexed_v1` and
|
||||
make it an incompatible v1 contract update, or should packer emit a new
|
||||
explicit format/version such as `GLYPH/indexed_rgba8888_v1`?
|
||||
- Keep `GLYPH/indexed_v1`. The structural change is in palette encoding; the
|
||||
remaining glyph payload model stays stable.
|
||||
- [x] What is the canonical authoring-side palette field name: keep
|
||||
`originalArgb8888`, rename to `rgba8888`, or store structured channel data?
|
||||
- Use `rgba8888` unless the decision stage finds a concrete tooling reason to
|
||||
choose a more explicit variant.
|
||||
- [x] How should Java `BufferedImage` ARGB input be converted to runtime RGBA
|
||||
raw values without confusing storage order, JSON numeric representation, or
|
||||
signed `int` display in tooling?
|
||||
- Convert ARGB input to RGBA output directly at the packer boundary.
|
||||
- [x] Does palette index `0` remain an ordinary palette slot immediately, as
|
||||
runtime `DEC-0029` requires, or does Studio need a temporary migration step to
|
||||
rewrite existing transparent-index assets into alpha-bearing palette entries?
|
||||
- Palette index `0` becomes an ordinary palette slot. Glyph palettes therefore
|
||||
have 16 usable colors, not 15 plus a reserved transparent index.
|
||||
- [x] Should magenta color-key support disappear from Studio authoring now, or
|
||||
survive only as an explicit import/conversion helper outside the normal pack
|
||||
path?
|
||||
- Magenta color-key support should disappear completely.
|
||||
- [x] Should partial alpha in PNG tiles become first-class palette data, or
|
||||
should the packer still reject/diagnose partial alpha until renderer behavior
|
||||
is fully proven?
|
||||
- Partial alpha becomes valid palette data now. Existing validations and
|
||||
warnings that flatten or reject partial alpha should be removed.
|
||||
- [x] Which existing fixtures and sample projects should be regenerated versus
|
||||
deleted because they encode RGB565-specific expectations?
|
||||
- `main` and `fragments` will be regenerated manually later; they should not
|
||||
block the Studio/packer decision.
|
||||
- [x] How should this agenda relate to `DSC-0005`: close it as superseded,
|
||||
revise it after RGBA8888, or keep it open as a later palette-count
|
||||
optimization?
|
||||
- `DSC-0005` remains a later step. RGBA8888 should not absorb variable
|
||||
palette-count serialization.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Minimal serializer swap inside current names
|
||||
|
||||
- **Approach:** Keep current public names and `GLYPH/indexed_v1`, replace the
|
||||
palette block with fixed `64 * 16 * 4` RGBA8888 entries, remove
|
||||
`convertedRgb565`, and update tests/specs in place.
|
||||
- **Pro:** Smallest naming churn and likely the fastest path to unblock runtime
|
||||
asset decode.
|
||||
- **Con:** The `v1` label would silently change binary meaning, which is risky
|
||||
for fixtures, docs, and any stale build output.
|
||||
- **Maintainability:** Medium. Fast, but it relies on the repository accepting a
|
||||
coordinated breaking change with no compatibility ambiguity.
|
||||
|
||||
### Option B - Explicit RGBA8888 glyph payload format
|
||||
|
||||
- **Approach:** Add an explicit runtime-facing glyph format/version for the
|
||||
RGBA8888 palette payload, retire RGB565 output from the normal pack path, and
|
||||
update asset declarations, specs, materialization, tests, fixtures, and sample
|
||||
projects to the new format.
|
||||
- **Pro:** Makes the breaking contract visible in file format names, tests, and
|
||||
diagnostics while still obeying the runtime decision not to support RGB565 as
|
||||
compatible input.
|
||||
- **Con:** More code and fixture churn; requires clear migration handling for
|
||||
stale project declarations and generated build artifacts.
|
||||
- **Maintainability:** Strong. The format boundary becomes explicit and easier
|
||||
to audit.
|
||||
|
||||
### Option C - Broaden the wave into full palette model redesign
|
||||
|
||||
- **Approach:** Use the RGBA8888 migration to redesign palette count, sparse vs
|
||||
dense indices, material palettes, import/export, alpha authoring UI, and scene
|
||||
palette defaults in one decision.
|
||||
- **Pro:** Could produce a cleaner long-term asset model and resolve `DSC-0005`
|
||||
at the same time.
|
||||
- **Con:** Mixes a mandatory runtime alignment with optional model improvements,
|
||||
increasing risk and delaying the renderer/asset migration.
|
||||
- **Maintainability:** Weak for this wave. Better reserved for follow-up after
|
||||
the RGBA8888 contract is stable.
|
||||
|
||||
## Discussion
|
||||
|
||||
The discussion converged toward an in-place `GLYPH/indexed_v1` structural
|
||||
update rather than a new format name. This keeps the glyph-bank identity stable:
|
||||
indexed pixels, fixed emitted sheet shape, scene `palette_id` references, and
|
||||
the broad runtime glyph-bank model remain the same. The incompatible change is
|
||||
the palette block and palette metadata moving from RGB565-derived values to raw
|
||||
RGBA8888.
|
||||
|
||||
The authoring/read projection should expose `rgba8888` as the canonical palette
|
||||
field. Java image inputs may still arrive as ARGB through `BufferedImage`, but
|
||||
that is an input representation only. The packer boundary converts ARGB to
|
||||
runtime RGBA and the rest of the pipeline should speak RGBA8888.
|
||||
|
||||
Palette index `0` is no longer special. It becomes a normal usable palette
|
||||
entry, which gives glyph palettes 16 usable colors. Transparency comes from the
|
||||
alpha byte in the RGBA8888 palette value. As a consequence, the old magenta
|
||||
color-key behavior should be removed completely, not retained as a normal
|
||||
authoring shortcut or hidden compatibility rule.
|
||||
|
||||
Partial alpha is valid data in this model. The packer should preserve it in the
|
||||
palette instead of warning, flattening, or rejecting it. Existing validations
|
||||
around partial alpha and the 15-color limit are therefore stale and should be
|
||||
rewritten around the new 16-entry RGBA palette contract.
|
||||
|
||||
Existing sample projects and fixtures that still carry RGB565 assumptions are
|
||||
not part of the discussion blocker. `main` and `fragments` will be regenerated
|
||||
later. `DSC-0005` remains a separate future discussion for palette-count
|
||||
serialization and should not be folded into this RGBA8888 wave.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Compatibility vs explicit break
|
||||
|
||||
Runtime `DEC-0029` already rejects RGB565 compatibility for this migration.
|
||||
Studio therefore should not preserve RGB565 input as a normal path. The open
|
||||
tradeoff is whether the packer should make the break visible through a new
|
||||
format/version or simply mutate the existing v1 meaning.
|
||||
|
||||
### Authoring convenience vs runtime truth
|
||||
|
||||
Java image tooling naturally reads pixels as ARGB ints. Runtime wants raw RGBA
|
||||
channel order. Studio can keep ARGB only as an import-side implementation detail,
|
||||
but packer output, public metadata, and tests need one unambiguous RGBA8888
|
||||
representation.
|
||||
|
||||
### Indexed art identity vs alpha semantics
|
||||
|
||||
The indexed/palette model can remain. What changes is that every palette entry,
|
||||
including index `0`, should be a real RGBA color. Transparent pixels should be
|
||||
encoded by alpha, not by a hardwired index rule or magenta color key.
|
||||
|
||||
### Scope control vs complete cleanup
|
||||
|
||||
It is tempting to combine RGBA8888 with variable palette serialization from
|
||||
`DSC-0005`. That should be resisted unless the decision explicitly expands
|
||||
scope. RGBA8888 changes bytes per palette entry and transparency semantics;
|
||||
palette count optimization is a separate axis.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt a refined Option A.
|
||||
|
||||
The Studio/packer decision should keep `GLYPH/indexed_v1` as the runtime-facing
|
||||
format name, but redefine its palette block and palette metadata around
|
||||
RGBA8888. This is an intentional structural break in the palette contract, not
|
||||
a new glyph-bank format.
|
||||
|
||||
The recommended shape for the decision is:
|
||||
|
||||
1. emit palette entries as raw RGBA8888 values in runtime RGBA channel order;
|
||||
2. replace `convertedRgb565` with canonical `rgba8888` data in authoring and
|
||||
read/detail projections;
|
||||
3. treat Java/PNG ARGB as an input decoding detail and convert deliberately at
|
||||
the packer boundary;
|
||||
4. make palette index `0` ordinary, yielding 16 usable palette entries;
|
||||
5. represent transparency and partial transparency only through RGBA alpha;
|
||||
6. remove magenta color-key behavior completely;
|
||||
7. remove partial-alpha flattening/rejection and preserve partial alpha as
|
||||
valid palette data;
|
||||
8. preserve fixed 64-palette serialization for this wave unless a decision
|
||||
explicitly revises `DSC-0005`;
|
||||
9. regenerate or rewrite RGB565 fixtures instead of supporting stale RGB565
|
||||
assets at runtime.
|
||||
|
||||
## Next Step
|
||||
|
||||
The agenda is ready to move to decision if the refined recommendation is
|
||||
accepted.
|
||||
|
||||
The next artifact should be a Studio/packer decision that references runtime
|
||||
`DEC-0029`, leaves `DSC-0005` for a later palette-count step, and defines
|
||||
propagation targets for:
|
||||
|
||||
- `docs/specs/packer`;
|
||||
- `docs/specs/studio`;
|
||||
- `prometeu-packer` models, walkers, serializers, services, fixtures, and
|
||||
tests;
|
||||
- sample project assets;
|
||||
- any Studio asset workspace UI/read projections that expose palette data.
|
||||
|
||||
## Resolution
|
||||
|
||||
Accepted on 2026-05-23.
|
||||
|
||||
The discussion is closed in favor of decision `DEC-0037`. The accepted
|
||||
direction keeps `GLYPH/indexed_v1`, moves its palette contract to RGBA8888,
|
||||
uses `rgba8888` as the canonical palette field, makes palette index `0`
|
||||
ordinary, removes magenta color-key behavior completely, accepts partial alpha
|
||||
as valid palette data, and leaves `DSC-0005` for a later palette-count
|
||||
serialization step.
|
||||
@ -0,0 +1,228 @@
|
||||
---
|
||||
id: DEC-0037
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: Studio and Packer RGBA8888 Asset Pipeline Contract
|
||||
status: accepted
|
||||
created: 2026-05-23
|
||||
accepted: 2026-05-23
|
||||
ref_agenda: AGD-0041
|
||||
plans:
|
||||
- PLN-0081
|
||||
- PLN-0082
|
||||
- PLN-0083
|
||||
- PLN-0084
|
||||
- PLN-0085
|
||||
- PLN-0086
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- assets
|
||||
- glyph-bank
|
||||
- palette
|
||||
- rgba8888
|
||||
- runtime-alignment
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Accepted. Drafted from accepted agenda `AGD-0041` and accepted on
|
||||
2026-05-23.
|
||||
|
||||
## Context
|
||||
|
||||
Runtime `DEC-0029` makes RGBA8888 the canonical logical color representation
|
||||
and physical framebuffer format for Prometeu. It also requires asset package
|
||||
palettes to use RGBA8888, rejects RGB565 compatibility as normal runtime input,
|
||||
and defines transparency through alpha rather than a reserved palette index.
|
||||
|
||||
Studio embeds the packer and owns the asset authoring and publication pipeline
|
||||
that emits `assets.pa`. Before this decision, the Studio/packer glyph-bank path
|
||||
still carried RGB565 assumptions:
|
||||
|
||||
- `GLYPH/indexed_v1` palette payloads were specified as fixed
|
||||
`64 * 16 * 2` RGB565 `u16` values.
|
||||
- `PackerPaletteV1` exposed `originalArgb8888` and `convertedRgb565`.
|
||||
- `PackerGlyphBankWalker` flattened partial alpha, treated alpha zero and
|
||||
magenta as transparent index `0`, limited authored colors to 15 usable
|
||||
entries, and converted colors to RGB565.
|
||||
- Studio/packer read projections, details APIs, fixtures, and sample assets
|
||||
exposed `convertedRgb565` as ordinary pipeline data.
|
||||
|
||||
The runtime decision is already normative for the color contract. This decision
|
||||
locks how Studio and packer align their glyph-bank asset pipeline with it.
|
||||
|
||||
## Decision
|
||||
|
||||
Studio and packer SHALL keep the runtime-facing glyph payload format name
|
||||
`GLYPH/indexed_v1`.
|
||||
|
||||
The `GLYPH/indexed_v1` glyph-bank model SHALL remain indexed/paletized. Indexed
|
||||
pixel payloads, fixed emitted sheet shape, scene `palette_id` references, and
|
||||
the broad glyph-bank identity remain stable.
|
||||
|
||||
The structural change is the palette contract. `GLYPH/indexed_v1` palette data
|
||||
MUST move from RGB565-derived values to RGBA8888 values in runtime RGBA channel
|
||||
order.
|
||||
|
||||
Packer output, packer metadata, Studio read/detail projections, tests, and
|
||||
fixtures MUST stop treating RGB565 as the normal palette representation.
|
||||
`convertedRgb565` MUST be removed from the normal authored and projected
|
||||
palette contract.
|
||||
|
||||
The canonical authored/projected palette field for this wave SHALL be
|
||||
`rgba8888`.
|
||||
|
||||
Java `BufferedImage` and PNG inputs MAY be read as ARGB by host APIs, but ARGB
|
||||
is only an input representation. The packer boundary MUST convert ARGB input to
|
||||
runtime RGBA8888 output deliberately before emitting or projecting canonical
|
||||
palette data.
|
||||
|
||||
Palette index `0` MUST be an ordinary palette index. Glyph palettes SHALL have
|
||||
16 usable entries, not 15 usable entries plus a reserved transparent index.
|
||||
|
||||
Transparency and partial transparency MUST be represented only by the alpha
|
||||
channel in the RGBA8888 palette value.
|
||||
|
||||
Magenta color-key behavior MUST be removed completely from the normal Studio
|
||||
and packer asset pipeline. Magenta MUST NOT remain a hidden compatibility rule,
|
||||
normal authoring shortcut, or runtime-facing transparency encoding.
|
||||
|
||||
Partial alpha in PNG/glyph inputs SHALL be valid palette data. Packer behavior
|
||||
that warns about, flattens, rejects, or otherwise strips partial alpha MUST be
|
||||
removed or rewritten around the RGBA8888 palette contract.
|
||||
|
||||
The fixed 64-palette serialization model remains in scope for this wave unless
|
||||
another accepted decision explicitly revises it. `DSC-0005` remains a later
|
||||
palette-count serialization discussion and MUST NOT be folded into this
|
||||
RGBA8888 migration by implication.
|
||||
|
||||
Existing `main` and `fragments` sample project assets may be regenerated
|
||||
manually later. Their regeneration is not a blocker for this decision and MUST
|
||||
NOT justify preserving RGB565 compatibility in the packer.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping `GLYPH/indexed_v1` avoids renaming a format whose core identity remains
|
||||
the same: indexed glyph pixels resolved through palettes. The incompatible part
|
||||
is specifically the palette encoding and transparency semantics.
|
||||
|
||||
Making RGBA8888 the normal packer-side representation aligns Studio with
|
||||
runtime `DEC-0029` without introducing a parallel RGB565 compatibility path.
|
||||
This keeps the asset pipeline direct: authoring input is normalized once at the
|
||||
packer boundary, and emitted runtime artifacts carry the runtime color contract.
|
||||
|
||||
Treating index `0` as ordinary is required because transparency now belongs to
|
||||
the alpha channel. This also gives each glyph palette the full 16 authored
|
||||
entries available from the indexed payload.
|
||||
|
||||
Removing magenta color-key behavior avoids a second transparency mechanism that
|
||||
would conflict with meaningful alpha. Allowing partial alpha preserves source
|
||||
image information and supports the broader RGBA8888 renderer direction.
|
||||
|
||||
Keeping fixed 64-palette serialization separates mandatory color-format
|
||||
migration from later payload-size optimization. Palette count and sparse/dense
|
||||
serialization remain independent questions.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### Runtime-Facing Glyph Payload
|
||||
|
||||
- The format name remains `GLYPH/indexed_v1`.
|
||||
- The indexed pixel plane remains packed `u4`.
|
||||
- The emitted glyph-bank sheet shape remains unchanged for this wave.
|
||||
- The palette block changes from 2-byte RGB565 entries to 4-byte RGBA8888
|
||||
entries.
|
||||
- The fixed palette block remains `64 * 16` entries for this wave.
|
||||
- The byte-size formula for the palette block MUST be updated from
|
||||
`64 * 16 * 2` to `64 * 16 * 4`.
|
||||
- Size and decoded-size formulas for glyph-bank payloads MUST be updated
|
||||
accordingly.
|
||||
- Palette bytes MUST be interpreted as runtime RGBA channel order.
|
||||
|
||||
### Authored and Projected Palette Data
|
||||
|
||||
- Canonical palette data exposed by Studio/packer SHALL use `rgba8888`.
|
||||
- `convertedRgb565` SHALL be removed from normal authored pipeline metadata,
|
||||
details projections, read projections, fixtures, and tests.
|
||||
- `originalArgb8888` SHALL NOT be the canonical field for runtime-facing or
|
||||
packer-projected palette data in this wave.
|
||||
- ARGB values read from Java image APIs MUST be converted to RGBA8888 before
|
||||
entering canonical packer metadata or emitted payloads.
|
||||
|
||||
### Transparency and Alpha
|
||||
|
||||
- Palette index `0` is ordinary.
|
||||
- A glyph palette has 16 usable entries.
|
||||
- Alpha `0`, alpha between `1` and `254`, and alpha `255` are all valid
|
||||
palette-entry states.
|
||||
- Partial alpha MUST be preserved as data.
|
||||
- Packer warnings or validations that describe partial alpha as flattened,
|
||||
ignored, or unsupported MUST be removed.
|
||||
- Color limit validation MUST be rewritten for 16 usable palette entries.
|
||||
|
||||
### Removed Behaviors
|
||||
|
||||
- RGB565 palette emission is not a normal packer output.
|
||||
- RGB565 palette projection is not a normal Studio/packer read or details
|
||||
contract.
|
||||
- Magenta color-key transparency is not supported in the normal path.
|
||||
- Palette index `0` is not reserved for transparency.
|
||||
- Runtime asset compatibility with stale RGB565 palette payloads is not a
|
||||
Studio/packer requirement for this wave.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
### Specs
|
||||
|
||||
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`, if Studio-facing
|
||||
palette read/projection behavior is documented there.
|
||||
|
||||
### Code
|
||||
|
||||
- `prometeu-packer` palette model types.
|
||||
- `PackerGlyphBankWalker`.
|
||||
- `PackerAssetWalker` glyph-bank size and metadata calculations.
|
||||
- `PackerAssetDetailsService`.
|
||||
- `PackerReadMessageMapper`.
|
||||
- Any packer serializer/materializer that emits `assets.pa` glyph payloads.
|
||||
- Studio asset workspace read/detail surfaces that display or depend on
|
||||
palette metadata.
|
||||
|
||||
### Tests and Fixtures
|
||||
|
||||
- Packer glyph-bank walker tests.
|
||||
- Asset declaration parser tests that mention `convertedRgb565`.
|
||||
- Runtime asset materializer tests.
|
||||
- File-system workspace service tests.
|
||||
- Fixture `asset.json` files that still declare RGB565-derived palette data.
|
||||
- Test expectations for alpha, 16 usable colors, and removed magenta color-key
|
||||
behavior.
|
||||
|
||||
`main` and `fragments` project assets are expected to be regenerated manually
|
||||
later and are not blockers for this decision.
|
||||
|
||||
## Constraints
|
||||
|
||||
- This decision MUST NOT introduce an RGB565 compatibility mode.
|
||||
- This decision MUST NOT rename the runtime-facing format away from
|
||||
`GLYPH/indexed_v1`.
|
||||
- This decision MUST NOT change scene `palette_id` semantics except as needed
|
||||
to ensure referenced glyph palettes now resolve RGBA8888 entries.
|
||||
- This decision MUST NOT decide variable palette-count serialization.
|
||||
- This decision MUST NOT close or revise `DSC-0005`; that discussion remains a
|
||||
later palette-count optimization track.
|
||||
- Any implementation plan derived from this decision MUST preserve all
|
||||
normative requirements above unless the user explicitly requests a decision
|
||||
revision.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: `AGD-0041`
|
||||
- Runtime decision: `../runtime/discussion/workflow/decisions/DEC-0029-rgba8888-runtime-pixel-format-contract.md`
|
||||
- Related future discussion: `DSC-0005`
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-23: Initial accepted decision from `AGD-0041`.
|
||||
@ -0,0 +1,136 @@
|
||||
---
|
||||
id: PLN-0081
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Packer and Studio Spec Propagation
|
||||
status: review
|
||||
created: 2026-05-23
|
||||
completed:
|
||||
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
|
||||
|
||||
- [ ] Packer specs define `rgba8888` as the canonical palette field.
|
||||
- [ ] `GLYPH/indexed_v1` remains named exactly that.
|
||||
- [ ] Palette block formulas use `64 * 16 * 4 = 4096`.
|
||||
- [ ] Specs state palette index `0` is ordinary and all 16 entries are usable.
|
||||
- [ ] Specs state partial alpha is valid and magenta color-key is removed.
|
||||
- [ ] 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.
|
||||
@ -0,0 +1,144 @@
|
||||
---
|
||||
id: PLN-0082
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Palette Model and ARGB Conversion
|
||||
status: review
|
||||
created: 2026-05-23
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- packer
|
||||
- palette
|
||||
- rgba8888
|
||||
- conversion
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Replace the packer palette model with canonical RGBA8888 data and introduce a
|
||||
single deliberate ARGB-to-RGBA conversion boundary for image inputs.
|
||||
|
||||
## Background
|
||||
|
||||
`PackerPaletteV1` currently stores `originalArgb8888` and `convertedRgb565`.
|
||||
`PackerGlyphBankWalker` reads Java ARGB pixels, drops alpha semantics, reserves
|
||||
index `0`, applies magenta color-key, and converts colors to RGB565.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Replace `PackerPaletteV1` fields with canonical `rgba8888`.
|
||||
- Add or localize ARGB-to-RGBA conversion helpers.
|
||||
- Preserve partial alpha.
|
||||
- Remove RGB565 conversion from the normal palette model.
|
||||
- Expand glyph palette extraction from 15 to 16 usable colors.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Binary `assets.pa` emission changes.
|
||||
- Read/detail API projection changes outside direct model compile fixes.
|
||||
- Spec edits.
|
||||
- Fixture regeneration for `main` and `fragments`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Replace the palette record
|
||||
|
||||
**What:** Change the packer palette model to carry canonical RGBA8888 values.
|
||||
|
||||
**How:** Replace `int[] originalArgb8888, short[] convertedRgb565` with
|
||||
`int[] rgba8888`. Keep the record name only if it remains semantically useful;
|
||||
otherwise rename only if all callers are updated in the same change.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/PackerPaletteV1.java`
|
||||
|
||||
### Step 2 - Convert ARGB image pixels to RGBA
|
||||
|
||||
**What:** Introduce one conversion path from Java `BufferedImage` ARGB to raw
|
||||
runtime RGBA.
|
||||
|
||||
**How:** Convert `0xAARRGGBB` to `0xRRGGBBAA` when building palette entries.
|
||||
Do not store ARGB in canonical packer metadata.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
||||
|
||||
### Step 3 - Remove magenta color-key and reserved index behavior
|
||||
|
||||
**What:** Stop treating alpha zero or magenta as special palette-index behavior.
|
||||
|
||||
**How:** Remove `COLOR_KEY_RGB`. Build palette identity from full RGBA8888
|
||||
values, including alpha. Assign indices from `0` through `15`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
||||
|
||||
### Step 4 - Preserve partial alpha
|
||||
|
||||
**What:** Remove partial-alpha warnings and flattening.
|
||||
|
||||
**How:** Delete the `partialAlphaFound` warning path. Ensure pixels with alpha
|
||||
from `0` through `255` participate in palette extraction by full RGBA value.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
||||
|
||||
### Step 5 - Update color-limit validation
|
||||
|
||||
**What:** Change validation from 15 usable colors to 16 usable colors.
|
||||
|
||||
**How:** Replace `MAX_COLORS_PER_PALETTE = 15` with a 16-entry limit and update
|
||||
diagnostic wording to remove `indices 1..15`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Update `PackerGlyphBankWalkerTest` to assert:
|
||||
- 16 unique RGBA colors are valid.
|
||||
- a 17th unique RGBA color is blocking.
|
||||
- alpha `0`, partial alpha, and alpha `255` are preserved.
|
||||
- magenta is treated as an ordinary color.
|
||||
- palette index `0` can hold an ordinary color.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- None for this plan; binary emission is covered by a later plan.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search packer model and glyph walker sources for `convertedRgb565`,
|
||||
`originalArgb8888`, `COLOR_KEY_RGB`, `convertToRgb565`, and partial-alpha
|
||||
warning text.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `PackerPaletteV1` exposes `rgba8888` and no RGB565 field.
|
||||
- [ ] `PackerGlyphBankWalker` stores canonical RGBA values.
|
||||
- [ ] Magenta is not special.
|
||||
- [ ] Alpha zero and partial alpha are valid palette data.
|
||||
- [ ] All 16 palette indices are usable.
|
||||
- [ ] Unit tests cover conversion and palette indexing semantics.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0081` for spec wording.
|
||||
- Must complete before payload emission and projection plans.
|
||||
|
||||
## Risks
|
||||
|
||||
- Confusing Java ARGB input with runtime RGBA output will create hard-to-debug
|
||||
byte-order failures.
|
||||
- Cache reuse may keep stale palette metadata if reusable metadata checks are
|
||||
not updated with the model change.
|
||||
@ -0,0 +1,145 @@
|
||||
---
|
||||
id: PLN-0083
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Glyph Payload Emission and Size Accounting
|
||||
status: review
|
||||
created: 2026-05-23
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- packer
|
||||
- assets-pa
|
||||
- glyph-bank
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Change packer glyph-bank runtime payload emission from RGB565 palette bytes to
|
||||
RGBA8888 palette bytes while keeping `GLYPH/indexed_v1` and the fixed
|
||||
64-palette model.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` requires `GLYPH/indexed_v1` to retain its format name and indexed
|
||||
model but emit RGBA8888 palette entries. Current payload emission in
|
||||
`FileSystemPackerWorkspaceService` writes RGB565 bytes, reserves index `0`, and
|
||||
uses color-key bytes.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update glyph-bank payload palette byte emission.
|
||||
- Update measured payload size and decoded-size accounting.
|
||||
- Remove RGB565 palette constants and palette color-key bytes from emission.
|
||||
- Keep scene `palette_id` payload semantics unchanged.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Palette model extraction changes covered by `PLN-0082`.
|
||||
- Read/detail projection changes covered by `PLN-0084`.
|
||||
- Variable palette count.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update glyph payload constants and formulas
|
||||
|
||||
**What:** Change palette entry width from 2 bytes to 4 bytes.
|
||||
|
||||
**How:** Introduce clear constants for palette count, colors per palette, and
|
||||
RGBA bytes per color. Use `64 * 16 * 4` for palette block size.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
|
||||
### Step 2 - Emit RGBA8888 palette bytes
|
||||
|
||||
**What:** Write each palette color as runtime RGBA channel bytes.
|
||||
|
||||
**How:** Replace RGB565 little-endian writes with four byte writes in `R`, `G`,
|
||||
`B`, `A` order derived from the canonical `rgba8888` integer value.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 3 - Remove reserved color-key emission
|
||||
|
||||
**What:** Stop writing a synthetic color-key value at palette index `0`.
|
||||
|
||||
**How:** Remove `GLYPH_BANK_COLOR_KEY_RGB565` and any emission path that fills
|
||||
index `0` with magenta. Emit declared RGBA values for index `0` like every
|
||||
other index.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 4 - Update declared palette lookup
|
||||
|
||||
**What:** Read `rgba8888` from declared pipeline metadata.
|
||||
|
||||
**How:** Replace `originalArgb8888`/`convertedRgb565` lookup paths with
|
||||
`rgba8888`. Ensure empty or malformed `rgba8888` is structural failure where
|
||||
emission requires a palette.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
|
||||
### Step 5 - Keep scene payload stable
|
||||
|
||||
**What:** Preserve scene `palette_id` layout.
|
||||
|
||||
**How:** Do not change `writeSceneBankPayload` except compile fixes caused by
|
||||
shared helper changes. Scene tile records continue carrying `palette_id` as an
|
||||
index into the referenced glyph palette.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Add or update tests asserting glyph payload size includes a 4096-byte palette
|
||||
block.
|
||||
- Assert emitted palette bytes for a known RGBA value, including alpha.
|
||||
- Assert index `0` emits declared RGBA data, not magenta.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Update workspace build tests that read `build/assets.pa` and assert glyph-bank
|
||||
offsets/sizes.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search production packer code for `GLYPH_BANK_COLOR_KEY_RGB565`,
|
||||
`convertedRgb565`, RGB565 palette byte writes, and hard-coded `2048`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Glyph payloads keep `GLYPH/indexed_v1`.
|
||||
- [ ] Glyph palette blocks are 4096 bytes.
|
||||
- [ ] Palette entries are emitted as RGBA bytes in runtime channel order.
|
||||
- [ ] No synthetic magenta/color-key value is emitted.
|
||||
- [ ] Size and decoded-size metadata match the new payload length.
|
||||
- [ ] Scene `palette_id` payload shape is unchanged.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0082`.
|
||||
- Should run before tests/fixture conformance in `PLN-0085`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Updating size formulas without updating emitted bytes, or vice versa, will
|
||||
corrupt payload slicing in `assets.pa`.
|
||||
- Accidental scene payload edits could widen the change beyond `DEC-0037`.
|
||||
@ -0,0 +1,141 @@
|
||||
---
|
||||
id: PLN-0084
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Packer Projections and Workspace APIs
|
||||
status: review
|
||||
created: 2026-05-23
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- packer
|
||||
- studio
|
||||
- api
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Update packer and Studio-facing read/detail/write projections so palette data
|
||||
is exposed and accepted as `rgba8888`, with no normal `convertedRgb565` or
|
||||
canonical `originalArgb8888` surface.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` requires packer metadata, Studio read/detail projections, tests, and
|
||||
fixtures to stop treating RGB565 as normal palette data. Several services still
|
||||
parse or project `originalArgb8888` and `convertedRgb565`.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update parser and declaration normalization for palette metadata.
|
||||
- Update read/detail mappers.
|
||||
- Update palette-overhauling and bank-composition support to emit `rgba8888`.
|
||||
- Preserve existing DTO shapes except for palette payload field names.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Binary payload byte emission.
|
||||
- Renderer/runtime changes.
|
||||
- Manual regeneration of `main` and `fragments`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update asset declaration parsing
|
||||
|
||||
**What:** Parse canonical `rgba8888` arrays from `asset.json`.
|
||||
|
||||
**How:** Replace palette validation that requires `originalArgb8888` and
|
||||
`convertedRgb565` with validation for `rgba8888`. Keep numeric validation.
|
||||
Reject malformed or missing `rgba8888` where a palette payload is required.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`
|
||||
|
||||
### Step 2 - Update details projection
|
||||
|
||||
**What:** Return `rgba8888` from asset details.
|
||||
|
||||
**How:** Change `palettePayloadFromNode` to project `{ index, rgba8888 }`.
|
||||
Remove `convertedRgb565` and canonical `originalArgb8888` from details output.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
|
||||
|
||||
### Step 3 - Update read message mapping
|
||||
|
||||
**What:** Map `PackerPaletteV1` and cached palette metadata to `rgba8888`.
|
||||
|
||||
**How:** Replace `originalArgb8888` and `convertedRgb565` mapping with a single
|
||||
`rgba8888` array.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java`
|
||||
|
||||
### Step 4 - Update workspace write operations
|
||||
|
||||
**What:** Ensure packer write APIs that apply palette changes persist `rgba8888`.
|
||||
|
||||
**How:** Replace palette-overhauling and related write-lane logic that requires
|
||||
both `originalArgb8888` and `convertedRgb565` with a `rgba8888` contract.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 5 - Update cache reuse and walk projection checks
|
||||
|
||||
**What:** Make cache reuse validate new palette metadata.
|
||||
|
||||
**How:** Replace reusable metadata checks for `originalArgb8888` with
|
||||
`rgba8888`. Stale cached RGB565-derived metadata must not be considered
|
||||
reusable.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Update parser tests to accept `rgba8888` and reject missing/malformed
|
||||
`rgba8888`.
|
||||
- Update details service tests to assert `rgba8888`.
|
||||
- Update read mapper coverage for `PackerPaletteV1`.
|
||||
- Update write operation tests for palette overhauling.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Exercise a workspace read/build flow from `asset.json` using `rgba8888`.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search `prometeu-packer` for `originalArgb8888` and `convertedRgb565` after
|
||||
this plan. Remaining matches must be migration-only or removed in later
|
||||
fixture plan.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `asset.json` palette metadata uses `rgba8888`.
|
||||
- [ ] Details/read projections expose `rgba8888`.
|
||||
- [ ] Workspace write operations persist `rgba8888`.
|
||||
- [ ] Stale RGB565-derived cache metadata is not reused as canonical.
|
||||
- [ ] No normal API requires `convertedRgb565`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0082`.
|
||||
- Can run partly in parallel with `PLN-0083` after the palette model is stable.
|
||||
|
||||
## Risks
|
||||
|
||||
- DTO consumers may assume old map keys. Tests must cover the Studio-facing
|
||||
projection boundary.
|
||||
- Cache reuse can hide stale behavior if not invalidated by metadata shape.
|
||||
@ -0,0 +1,141 @@
|
||||
---
|
||||
id: PLN-0085
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Tests, Fixtures, and Conformance Updates
|
||||
status: review
|
||||
created: 2026-05-23
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- tests
|
||||
- fixtures
|
||||
- conformance
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Update packer tests and fixtures so RGBA8888 is the asserted source of truth and
|
||||
RGB565-specific expectations are removed.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` requires tests and fixtures to stop proving RGB565 behavior. The code
|
||||
base has parser, walker, details, materializer, and workspace service tests that
|
||||
mention `convertedRgb565`, `originalArgb8888`, 15-color limits, magenta
|
||||
color-key behavior, and RGB565 payload sizes.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Update packer unit tests and integration-style workspace tests.
|
||||
- Update fixture `asset.json` files under packer test resources.
|
||||
- Add conformance-oriented assertions for RGBA channel order, alpha, index `0`,
|
||||
16 usable colors, and removed color-key behavior.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Manual regeneration of `test-projects/main` and `fragments`.
|
||||
- Production code changes except minor compile-fix test helpers.
|
||||
- Runtime repository tests.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update parser and details tests
|
||||
|
||||
**What:** Replace palette payload fixtures with `rgba8888`.
|
||||
|
||||
**How:** Rewrite test JSON snippets and assertions that mention
|
||||
`originalArgb8888` or `convertedRgb565`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDeclarationParserTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDetailsServiceTest.java`
|
||||
|
||||
### Step 2 - Update glyph walker tests
|
||||
|
||||
**What:** Assert new palette extraction semantics.
|
||||
|
||||
**How:** Add image fixtures in tests that cover:
|
||||
16 colors, 17-color failure, alpha 0, partial alpha, magenta as ordinary color,
|
||||
and index `0` as ordinary.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`
|
||||
|
||||
### Step 3 - Update materializer and workspace service tests
|
||||
|
||||
**What:** Assert RGBA8888 runtime payload and metadata behavior.
|
||||
|
||||
**How:** Update tests that read `assets.pa`, measured bank size, payload offsets,
|
||||
and palette byte expectations. Replace RGB565 byte checks with RGBA byte checks.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimePatchServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimeRegistryTest.java`
|
||||
|
||||
### Step 4 - Update packer fixture assets
|
||||
|
||||
**What:** Replace fixture `asset.json` palette fields with `rgba8888`.
|
||||
|
||||
**How:** Edit packer test fixtures under `src/test/resources/fixtures` so
|
||||
canonical palette declarations do not contain `convertedRgb565`.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/**/asset.json`
|
||||
|
||||
### Step 5 - Add stale-contract guards
|
||||
|
||||
**What:** Add tests or quality checks that catch old RGB565 palette contract
|
||||
residue.
|
||||
|
||||
**How:** Add assertions in existing tests or a focused repository quality test
|
||||
that normal packer specs/tests/fixtures do not contain `convertedRgb565` or
|
||||
RGB565 glyph palette payload expectations.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Existing packer test suites under `prometeu-packer/prometeu-packer-v1/src/test/java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Parser, details, mapper, glyph walker, and workspace service unit tests must
|
||||
all pass.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Run the relevant Gradle test task for `prometeu-packer-v1`.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Search for `convertedRgb565`, `originalArgb8888`, `RGB565`, `rgb565`, `2048`,
|
||||
and magenta color-key references in packer tests and fixtures.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Tests use `rgba8888` as canonical palette data.
|
||||
- [ ] Tests assert RGBA channel order and alpha preservation.
|
||||
- [ ] Tests assert 16 usable palette entries.
|
||||
- [ ] Tests assert magenta is ordinary or no longer special.
|
||||
- [ ] Tests assert 4096-byte palette blocks where payload size is checked.
|
||||
- [ ] Packer test fixtures no longer rely on `convertedRgb565`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0082`, `PLN-0083`, and `PLN-0084`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Some stale generated fixture data may be easier to regenerate than hand-edit.
|
||||
- Overbroad residue checks could flag historical discussion artifacts; scope
|
||||
checks to normal specs, code, tests, and fixtures.
|
||||
@ -0,0 +1,148 @@
|
||||
---
|
||||
id: PLN-0086
|
||||
ticket: studio-packer-rgba8888-asset-pipeline
|
||||
title: RGBA8888 Final Integration and Residue Removal
|
||||
status: review
|
||||
created: 2026-05-23
|
||||
completed:
|
||||
ref_decisions:
|
||||
- DEC-0037
|
||||
tags:
|
||||
- integration
|
||||
- validation
|
||||
- residue-removal
|
||||
- rgba8888
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Run final integration checks and remove normal-path RGB565 residue after the
|
||||
spec, model, emission, projection, and test plans are implemented.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0037` prohibits RGB565 compatibility mode, normal `convertedRgb565`
|
||||
projection, magenta color-key behavior, reserved palette index `0`, and partial
|
||||
alpha flattening. Final validation must prove that the repository implements
|
||||
those constraints coherently.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
- Repository-wide residue audit.
|
||||
- Full relevant Gradle test execution.
|
||||
- Discussion workflow validation.
|
||||
- Final implementation notes for follow-up plan or lesson creation.
|
||||
|
||||
### Excluded
|
||||
|
||||
- New feature design.
|
||||
- Runtime repository changes.
|
||||
- Variable palette-count work in `DSC-0005`.
|
||||
- Manual regeneration of `main` and `fragments`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Run focused residue searches
|
||||
|
||||
**What:** Find stale RGB565 palette-contract residue.
|
||||
|
||||
**How:** Search production specs/code/tests/fixtures for:
|
||||
`convertedRgb565`, `originalArgb8888`, `RGB565`, `rgb565`, `COLOR_KEY`,
|
||||
`magenta`, `2048`, `indices 1..15`, and partial-alpha flattening text.
|
||||
Classify each match as removed, historical discussion-only, or out-of-scope.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `docs/specs/packer/**`
|
||||
- `docs/specs/studio/**`
|
||||
- `prometeu-packer/**`
|
||||
|
||||
### Step 2 - Run packer tests
|
||||
|
||||
**What:** Execute the packer test suite.
|
||||
|
||||
**How:** Run the Gradle test task that covers `prometeu-packer-v1` and related
|
||||
API modules.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Gradle modules under `prometeu-packer`
|
||||
|
||||
### Step 3 - Run broader build validation
|
||||
|
||||
**What:** Verify Studio build integration still compiles.
|
||||
|
||||
**How:** Run the repository's standard build or the narrowest existing Gradle
|
||||
task that compiles Studio plus packer consumers.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Root Gradle project
|
||||
- `prometeu-app`
|
||||
- `prometeu-packer`
|
||||
|
||||
### Step 4 - Validate discussion workflow
|
||||
|
||||
**What:** Ensure discussion artifacts remain consistent.
|
||||
|
||||
**How:** Run `discussion validate` after implementation and before any
|
||||
housekeeping.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- `discussion/index.ndjson`
|
||||
- `discussion/workflow/**`
|
||||
|
||||
### Step 5 - Record remaining intentional residue
|
||||
|
||||
**What:** Document any allowed remaining RGB565 references.
|
||||
|
||||
**How:** If matches remain only in historical discussions, runtime references,
|
||||
or explicit future migration notes, list them in the implementation summary so
|
||||
housekeeping and lesson work can distinguish intentional context from missed
|
||||
normal-path behavior.
|
||||
|
||||
**File(s):**
|
||||
|
||||
- Implementation summary or future lesson, after code work is complete.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Packer unit tests must pass.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Packer workspace build/materialization tests must pass.
|
||||
- Studio compile/build validation must pass.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Residue search results must contain no normal-path `convertedRgb565`,
|
||||
RGB565 glyph palette payload, magenta color-key, reserved index `0`, or
|
||||
partial-alpha flattening behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `discussion validate` passes.
|
||||
- [ ] Packer tests pass.
|
||||
- [ ] Studio/packer build validation passes.
|
||||
- [ ] Normal specs/code/tests/fixtures contain no stale RGB565 glyph-palette
|
||||
contract residue.
|
||||
- [ ] Remaining stale-looking matches, if any, are documented as historical or
|
||||
explicitly out of scope.
|
||||
- [ ] `DSC-0005` remains untouched except by explicit future work.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0081` through `PLN-0085`.
|
||||
|
||||
## Risks
|
||||
|
||||
- A broad residue search may include historical discussions and cause false
|
||||
positives.
|
||||
- Generated project cache files may change during tests; those changes must be
|
||||
reviewed separately from source edits.
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user