theme

type Card struct {
	// Mode is "overlay" (full-bleed illustration + scrim + text) or "block"
	// (one line over a solid palette background).
	Mode string `json:"mode" mapstructure:"mode" yaml:"mode"`
	// Scrim is the overlay gradient (overlay mode only).
	Scrim *Scrim `json:"scrim,omitempty" mapstructure:"scrim" yaml:"scrim,omitempty"`
	// Lead / Tail are the silence a card holds before and after its narration,
	// in seconds (spec 0050 D4). Zero means the parity defaults, 0.5 and 0.7.
	// Pacing is part of a look, which is why it lives with one.
	Lead float64 `json:"lead,omitempty" mapstructure:"lead" yaml:"lead,omitempty"`
	Tail float64 `json:"tail,omitempty" mapstructure:"tail" yaml:"tail,omitempty"`
	// FontBold / FontMono are the card fonts (bold for body lines, mono for the
	// URL closer).
	FontBold string `json:"font_bold,omitempty" mapstructure:"font_bold" yaml:"font_bold,omitempty"`
	FontMono string `json:"font_mono,omitempty" mapstructure:"font_mono" yaml:"font_mono,omitempty"`
	// Style is the illustration-generation prompt prefix for per-card scenes,
	// rendered in this theme's visual style at 9:16 (spec 0001 §3.1).
	Style string `json:"style,omitempty" mapstructure:"style" yaml:"style,omitempty"`
	// Sequence marks this theme's cards as ONE evolving scene rather than
	// independent illustrations (spec 0045 D2). Card 1 becomes the style anchor
	// and every later card is generated against it, so the look holds across the
	// board. Off by default: a kinetic-typography theme wants independent cards.
	Sequence bool `json:"sequence,omitempty" mapstructure:"sequence" yaml:"sequence,omitempty"`
	// Shots are per-beat framing directives cycled across a sequence — wides that
	// breathe, an intimate close, an extreme close-up. Anchoring alone holds the
	// look but CLONES the compositions (0045 §2 stage 2); varying the shot scale
	// and negative space per beat is the other half of the fix (D6). Ignored
	// unless Sequence is set; empty falls back to a built-in rotation.
	Shots []string `json:"shots,omitempty" mapstructure:"shots" yaml:"shots,omitempty"`
}

type Catalog struct {
	// Default is `themes.default` — the keyword used when a generation names
	// none. One default, not one per target: a per-target default would have
	// relocated the type dimension rather than removed it (0047 D1).
	Default string
	// Themes maps keyword → theme (`themes.<keyword>`).
	Themes map[string]Theme
}

type FlatSummary struct {
	// Keywords is every distinct theme, sorted.
	Keywords []string `json:"keywords"`
	// Merged maps a keyword to the types it was flattened from, for the
	// collisions. Reported so a merge is visible rather than silent.
	Merged map[string][]string `json:"merged,omitempty"`
	// Default is the single default keyword the flat catalog will carry.
	Default string `json:"default"`
	// Framing maps a keyword to the format-ish phrases still in its style — the
	// instructions the target now supplies. Reported for MANUAL editing: the tool
	// does not rewrite prose a human wrote (D2).
	//
	// The PHRASES matter, not just the keyword. Nearly every style mentions
	// something, so a bare list of names flags everything and tells you nothing;
	// "editorial: 16:9, banner" tells you what to delete.
	Framing map[string][]string `json:"framing,omitempty"`
	// Renames lists keywords that need a human to choose a new name — see
	// [needsRename].
	Renames []string `json:"renames,omitempty"`
	// Divergent lists keywords whose `prompt` and `style` hold DIFFERENT prose.
	// Both are left in place: only one can survive and the choice is the author's,
	// so this reports rather than resolves (the same line D2 draws around framing).
	Divergent []string `json:"divergent,omitempty"`
}

type Format struct {
	// Aspect is the frame shape, e.g. "16:9".
	Aspect string `json:"aspect,omitempty" mapstructure:"aspect" yaml:"aspect,omitempty"`
	// Composition directs framing and negative space. Appended to the theme's
	// style, never replacing it.
	Composition string `json:"composition,omitempty" mapstructure:"composition" yaml:"composition,omitempty"`
}

type LegacyCatalog struct {
	// contains filtered or unexported fields
}

type Music struct {
	// Prompt is the tone-matched generation prompt for the bed (bespoke per
	// reel in practice; this is the seeded default tone).
	Prompt string `json:"prompt,omitempty" mapstructure:"prompt" yaml:"prompt,omitempty"`
	// Gain is the bed's mix level under the VO (≈0.16).
	Gain float64 `json:"gain" mapstructure:"gain" yaml:"gain"`
}

type Palette map[string]string

type Scrim struct {
	// From is where the gradient STARTS — fully transparent — as a fraction of
	// card height measured from the top (0=top, 1=bottom). It ramps to full
	// opacity at the frame edge Direction points to; 0.52 ≈ the lower half.
	From float64 `json:"from" mapstructure:"from" yaml:"from"`
	// Color is the palette role the scrim fades to (usually "charcoal").
	Color string `json:"color" mapstructure:"color" yaml:"color"`
	// Opacity is the gradient's maximum alpha, 0–1. Zero means the default.
	Opacity float64 `json:"opacity,omitempty" mapstructure:"opacity" yaml:"opacity,omitempty"`
	// Direction is which edge the gradient ramps to full opacity at: "up"
	// (the default — transparent at From, solid at the bottom) or "down"
	// (solid at the top). Empty means "up".
	Direction string `json:"direction,omitempty" mapstructure:"direction" yaml:"direction,omitempty"`
}

type Target string

type Theme struct {
	Keyword string `json:"keyword" mapstructure:"-" yaml:"-"`

	Palette Palette `json:"palette,omitempty" mapstructure:"palette" yaml:"palette,omitempty"`

	// Style is the aesthetic: medium, treatment, mood. NOT framing or aspect —
	// those come from the target's format profile (spec 0047, see format.go), so
	// one style serves a cover, a card and an avatar alike.
	Style string `json:"style,omitempty" mapstructure:"style" yaml:"style,omitempty"`

	// Formats optionally overrides a target's built-in composition profile,
	// keyed by target ("cover", "card", "portrait"). The escape hatch for a
	// style whose whole point is an unusual crop.
	Formats map[string]Format `json:"formats,omitempty" mapstructure:"formats" yaml:"formats,omitempty"`

	// Prompt and Aspect are the PRE-0047 FIELD names, still read because
	// flattening the catalog's SHAPE (0047 §6) did not rewrite the prose inside
	// it — the reference install is flat and still writes `prompt:`. Prompt falls
	// back into Style; Aspect is folded into Formats["cover"] at load, so a
	// non-default frame is honoured rather than silently lost. `theme migrate`
	// writes the modern names; nothing else does.
	Prompt string `json:"prompt,omitempty" mapstructure:"prompt" yaml:"prompt,omitempty"`
	Aspect string `json:"aspect,omitempty" mapstructure:"aspect" yaml:"aspect,omitempty"`

	// MergedFrom records the pre-0047 types this keyword was flattened from, so
	// `theme migrate` can report what it merged rather than silently conflating
	// two entries. Set only on the legacy read path; never persisted.
	MergedFrom []string `json:"merged_from,omitempty" mapstructure:"-" yaml:"-"`

	// Card / Music / Voice are consulted when generating a reel. A theme without
	// them is still usable for one — it simply has no music bed, which is a valid
	// choice (0047 D4). Avatars (the actor capability) are a separate top-level
	// registry (internal/avatar), not a field here.
	Card  *Card  `json:"card,omitempty" mapstructure:"card" yaml:"card,omitempty"`
	Music *Music `json:"music,omitempty" mapstructure:"music" yaml:"music,omitempty"`
	Voice *Voice `json:"voice,omitempty" mapstructure:"voice" yaml:"voice,omitempty"`
}

type Voice struct {
	// ID is the provider voice identifier (e.g. an ElevenLabs voice id).
	ID string `json:"id,omitempty" mapstructure:"id" yaml:"id,omitempty"`
	// Stability / Similarity are the clone settings (higher similarity favours
	// fidelity to the reference voice).
	Stability  float64 `json:"stability" mapstructure:"stability" yaml:"stability"`
	Similarity float64 `json:"similarity" mapstructure:"similarity" yaml:"similarity"`
	// Style is expression/exaggeration (0 = most faithful; higher is more
	// expressive but can drift the accent). Speed is the speech rate (0.7 slow …
	// 1.2 fast; 0 falls back to the provider default 1.0). SpeakerBoost toggles
	// speaker enhancement; nil falls back to the provider default (on).
	Style        float64 `json:"style,omitempty" mapstructure:"style" yaml:"style,omitempty"`
	Speed        float64 `json:"speed,omitempty" mapstructure:"speed" yaml:"speed,omitempty"`
	SpeakerBoost *bool   `json:"speaker_boost,omitempty" mapstructure:"speaker_boost" yaml:"speaker_boost,omitempty"`
	// Model selects the TTS model for this theme's voice (empty ⇒ provider default,
	// eleven_multilingual_v2). Pronunciation references a provider pronunciation
	// dictionary id whose rules apply to every line (spec 0022 B, A).
	Model         string `json:"model,omitempty" mapstructure:"model" yaml:"model,omitempty"`
	Pronunciation string `json:"pronunciation,omitempty" mapstructure:"pronunciation" yaml:"pronunciation,omitempty"`
}