prometeu-studio/discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md

id	ticket	title	created	tags
LSN-0042	palette-management-in-studio	Schema-Driven Palette Authoring and Local Metadata Events	2026-04-23	studio glyph-bank palette-management color-schema local-events

Context

The glyph-bank palette workflow originally treated palette candidates as extracted tile artifacts. That made grouping, recoloring, and final bank palette selection compete in the same surface.

The completed palette-management work split the workflow into two authored layers:

1. Color Schema Groups, where selected tiles are grouped into a shared index structure.
2. Palette Overhauling, where palettes are authored and selected against already-ready schemas.

The durable implementation lesson is that schema edits, palette edits, and build selection are all local glyph-material metadata operations first. They should update local metadata projections directly instead of forcing a full asset-details reload.

Key Decisions

Schema Owns Index Semantics

What: A schema is the authored index structure for a group of selected glyph-bank tiles. It owns material_indices, artifact bindings, fingerprint snapshots, version, and status.

Why: The source PNG stays unchanged, while Studio records how tile colors map into stable bank-local indices. This keeps tile grouping separate from recoloring.

Trade-offs: Schema invalidation must be explicit. When selected tile fingerprints drift, the schema can become inconsistent and dependent palettes become invalid or stale.

Palettes Are Schema-Scoped

What: A palette always belongs to exactly one schema. It stores concrete #RRGGBB colors for that schema's visible indices and carries the schema version it was authored against.

Why: Multiple recolors can safely exist for one index structure without duplicating tile grouping metadata.

Trade-offs: Duplicate detection must use the tuple schemaId + colors + order, not display name or source tile identity.

Original Palettes Are Synthetic and Read-Only

What: The original palette is the synthetic schema-<schemaId>-original projection derived from the current schema colors. It is not a persisted user palette.

Why: Updating the schema should update the original palette automatically. The original represents the schema's source color meaning, not a user-authored recolor.

Trade-offs: Users cannot edit or delete the original palette directly. If they want a changed palette, they create or edit a separate persisted palette for the same schema.

Local Metadata Events Beat Global Reloads

What: Schema and palette metadata mutations should publish StudioGlyphMaterialMetadataChangedEvent and let interested sections rebind local state.

Why: Global asset refresh and selection events can close edit mode, reset form state, and make small metadata edits feel destructive.

Trade-offs: Controls must keep their local coordinators robust: stale button handlers should read the current view model at click time, and metadata replacement must preserve edit-mode drafts where possible.

Patterns and Algorithms

glyph-material.json

glyph-material.json is the Studio-owned support file for glyph-bank material authoring. It persists schemas and user-authored palettes, while derived original palettes remain a view projection.

Schema records store:

• stable schema_id
• status
• version
• dense visible material_indices
• artifact bindings with fingerprint snapshots

Palette records store:

• stable palette_id
• persisted name
• parent schema_id
• schema version
• concrete colors

Palette Names

Palette names are persisted even when the user leaves the name field blank. The blank-name path resolves to a deterministic, simple generated name such as snow white, fog twist, or ember bloom.

The generated name is a convenience label only. Palette identity remains palette_id, and duplicate detection remains schema plus ordered colors.

Original Palette Projection

Every ready schema projects a synthetic original palette from the schema's current material_indices.

This projection must always exist in the palette view, even if a user-authored palette has the same colors. A saved palette with the same schema and colors is still user-authored and can be deleted.

Pitfalls

• Do not treat same colors as proof that a palette is original. Original means "synthetic schema projection", not "matches current schema colors".
• Do not publish global asset refresh events for local schema or palette metadata changes. Use local metadata events unless pack/runtime state truly changed.
• Do not let button handlers capture stale preview objects. Fetch the current coordinator view model at click time for destructive actions.
• Do not let blank palette names remain blank on disk. Resolve the generated name before persisting.
• Do not open the palette wizard for synthetic original palettes. They are read-only projections.

Takeaways

• Schema formation and palette authoring are separate lifecycle stages.
• Original palettes are derived views, not persisted editable records.
• User-created palettes remain editable and removable even when they share a schema or colors with an original.
• Local metadata events preserve form continuity better than full asset refreshes.