palette-types

PURPOSE

Defines the shared 7-slot color model that unifies terrain and backdrop rendering under a single cohesive palette. A Palette is one color mood: terrain samples from 4 slots, backdrop samples from 5, with shadow and midtone shared across both. Swapping the active palette re-skins the whole scene in one step and keeps all surfaces internally consistent.

Authorship is hybrid — a PalettePreset declares parameters (temperature, brightness, saturation, optional hue_bias) and a generator produces the 7 hex slots. Presets may override individual slots by name when the algorithm produces something flat.

OWNS

• The PaletteSlot string-union type enumerating the seven slot names: shadow, midtone, bg_deep, bg_haze, bg_star, terrain_base, terrain_edge.
• The PaletteParams interface — the procedural-generation inputs (temperature, brightness, saturation, optional hue_bias).
• The Palette interface — a fully resolved palette with an id plus the seven concrete hex strings, extending PaletteParams.
• The PalettePreset interface — PaletteParams plus id, displayName, and an optional overrides Partial<Pick<Palette, ...slots>> for hand-tuned slot overrides.

READS FROM

Nothing. This file is pure type declarations with no imports.

PUSHES TO

Nothing at runtime. Consumed structurally by:

• The palette generator that turns PalettePreset parameters into a resolved Palette.
• Terrain renderers (consume shadow, midtone, terrain_base, terrain_edge).
• Backdrop renderers (consume shadow, midtone, bg_deep, bg_haze, bg_star).
• Preset tables that declare concrete PalettePreset values.

DOES NOT

• Generate colors. The procedural mapping from PaletteParams to hex slots lives in the generator, not here.
• Validate hex strings, parameter ranges, or override completeness.
• Register, store, or look up palettes by id.
• Apply overrides on top of generator output — that merge happens downstream.
• Define backdrop or terrain geometry, layering order, or blend modes.
• Export runtime values, defaults, or constants — types only.

Signals

None. This module declares no events, no observers, and no mutable state.

Entry points

• PaletteSlot — slot-name string union, used wherever code needs to refer to a specific slot.
• PaletteParams — input shape for procedural generation.
• Palette — output shape consumed by renderers; extends PaletteParams and adds id plus the seven hex slots.
• PalettePreset — authored shape combining PaletteParams, id, displayName, and optional overrides.

Pattern notes

• Shared-slot design: shadow and midtone are intentionally referenced by both terrain and backdrop so the two layers visually tie together; the other slots are scoped to one surface.
• Parameter axes are signed and normalized: temperature and brightness run roughly -1..+1, saturation 0..1, and hue_bias (when set) is in degrees 0..360. When hue_bias is provided it pins the base hue and temperature is downgraded to a warm/cool accent bias around that hue.
• Palette extends PaletteParams keeps the source parameters on the resolved object so downstream code can re-derive or audit how a palette was generated.
• overrides uses Partial<Pick<Palette, ...slot names>> rather than Partial<Palette> to ensure only the seven slot fields can be overridden, never id or the parameter axes.
• Snake_case slot names (bg_deep, terrain_base, hue_bias) are used deliberately for slot identifiers and parameter knobs, distinct from camelCase fields like displayName.