Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/plans/PLN-0090-studio-and-packer-projections-for-variable-glyph-palettes.md

4.2 KiB
Raw Blame History

id ticket title status created completed ref_decisions tags
PLN-0090 variable-tile-bank-palette-serialization Studio and Packer Projections for Variable Glyph Palettes open 2026-07-14
DEC-0038
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.