flatland_protocol/

types.rs

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};
use uuid::Uuid;

pub type EntityId = u64;
pub type Tick = u64;
pub type Seq = u32;
pub type SessionId = u64;

/// World position `(x, y, z, w, t)` — `t` reserved at 0.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct WorldCoord {
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub w: u32,
    pub t: u32,
}

/// Ground / free-aim cast point (map X/Y, optional elevation).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct AimPoint {
    pub x: f32,
    pub y: f32,
    #[serde(default)]
    pub z: f32,
}

impl AimPoint {
    pub fn xy(x: f32, y: f32) -> Self {
        Self { x, y, z: 0.0 }
    }
}

impl WorldCoord {
    pub fn surface(x: f32, y: f32) -> Self {
        Self {
            x,
            y,
            z: 0.0,
            w: 0,
            t: 0,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Velocity2D {
    pub vx: f32,
    pub vy: f32,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Transform {
    pub position: WorldCoord,
    pub yaw: f32,
    pub velocity: Velocity2D,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LifeState {
    Alive,
    Dead,
}

impl Default for LifeState {
    fn default() -> Self {
        Self::Alive
    }
}

/// Named slice of the in-game day (drives future weather / spawn tables).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TimeOfDayPhase {
    Night,
    Dawn,
    Morning,
    Midday,
    Afternoon,
    Evening,
}

impl TimeOfDayPhase {
    pub fn label(self) -> &'static str {
        match self {
            Self::Night => "Night",
            Self::Dawn => "Dawn",
            Self::Morning => "Morning",
            Self::Midday => "Midday",
            Self::Afternoon => "Afternoon",
            Self::Evening => "Evening",
        }
    }

    pub fn from_name(name: &str) -> Self {
        match name.to_ascii_lowercase().as_str() {
            "dawn" => Self::Dawn,
            "morning" => Self::Morning,
            "midday" | "mid_day" | "noon" => Self::Midday,
            "afternoon" => Self::Afternoon,
            "evening" | "dusk" => Self::Evening,
            _ => Self::Night,
        }
    }
}

/// Authoritative region clock (one in-game day = configurable real duration).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct WorldClock {
    /// Days elapsed since region start (0-based).
    pub day: u64,
    pub hour: u8,
    pub minute: u8,
    pub phase: TimeOfDayPhase,
}

impl Default for WorldClock {
    fn default() -> Self {
        Self {
            day: 0,
            hour: 8,
            minute: 0,
            phase: TimeOfDayPhase::Morning,
        }
    }
}

impl WorldClock {
    pub fn display_time(self) -> String {
        format!("{:02}:{:02}", self.hour, self.minute)
    }
}

/// Core primary stats — internal scale 1–1000; UI displays `value / 10` (1–100).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct PrimaryAttributes {
    pub strength: u16,
    pub dexterity: u16,
    pub intelligence: u16,
    pub stamina: u16,
    pub vitality: u16,
    pub wisdom: u16,
    pub charisma: u16,
}

impl Default for PrimaryAttributes {
    fn default() -> Self {
        Self {
            strength: 150,
            dexterity: 150,
            intelligence: 150,
            stamina: 150,
            vitality: 150,
            wisdom: 150,
            charisma: 150,
        }
    }
}

impl PrimaryAttributes {
    /// Map internal 1–1000 to player-facing 1–100.
    pub fn display(value: u16) -> u16 {
        (value / 10).clamp(1, 100)
    }

    /// Client-facing derived stat preview (mirrors sim tuning).
    pub fn derived_preview(&self) -> DerivedPreview {
        let str_d = Self::display(self.strength) as f32;
        let dex_d = Self::display(self.dexterity) as f32;
        let int_d = Self::display(self.intelligence) as f32;
        let wis_d = Self::display(self.wisdom) as f32;
        DerivedPreview {
            attack_power: str_d * 1.2 + dex_d * 0.3,
            spell_power: int_d * 1.1 + wis_d * 0.4,
            evasion: dex_d * 0.8 + wis_d * 0.2,
            carry_mass_max: str_d * 2.5,
            sight_range_m: 12.0 + wis_d * 0.15 + dex_d * 0.05,
            fov_deg: 120.0 + wis_d * 0.2,
            hearing_range_m: 6.0
                + wis_d * 0.08
                + (PrimaryAttributes::display(self.stamina) as f32) * 0.04,
        }
    }
}

/// Derived combat/survival preview for character sheet UI.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct DerivedPreview {
    pub attack_power: f32,
    pub spell_power: f32,
    pub evasion: f32,
    pub carry_mass_max: f32,
    pub sight_range_m: f32,
    pub fov_deg: f32,
    pub hearing_range_m: f32,
}

/// Trained skill — internal 0–1000; UI uses tiers / display level.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct SkillProgress {
    pub level: u16,
    #[serde(default)]
    pub last_trained_tick: u64,
}

impl Default for SkillProgress {
    fn default() -> Self {
        Self {
            level: 0,
            last_trained_tick: 0,
        }
    }
}

impl SkillProgress {
    /// Mastery tier 0–10 (`plans/11` §10). Tier 0 = untrained; tier 1 begins at internal 100.
    pub fn display_tier(&self) -> u16 {
        (self.level / 100).min(10)
    }
}

/// Fractional XP pools — source of truth for progression curve (`plans/27`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct ProgressionXp {
    pub strength: f64,
    pub dexterity: f64,
    pub intelligence: f64,
    pub stamina: f64,
    pub vitality: f64,
    pub wisdom: f64,
    pub charisma: f64,
    pub logging: f64,
    pub mining: f64,
    pub evocation: f64,
    pub restoration: f64,
    pub swords: f64,
    pub archery: f64,
    pub crafting: f64,
    pub alchemy: f64,
    pub cartography: f64,
    /// Per-ability mastery XP (`ability_id` → fractional XP). Empty = all abilities tier 0.
    #[serde(default)]
    pub ability: std::collections::BTreeMap<String, f64>,
}

impl ProgressionXp {
    /// Bootstrap pools for a new character at display baseline 15.
    pub fn bootstrap_new(baseline_display: u16, xp_base: f64, xp_growth: f64) -> Self {
        let bootstrap = |display: f64| {
            if display <= 1.0 {
                0.0
            } else {
                xp_base * xp_growth.powf(display - 1.0)
            }
        };
        let b = baseline_display as f64;
        let primary = bootstrap(b);
        Self {
            strength: primary,
            dexterity: primary,
            intelligence: primary,
            stamina: primary,
            vitality: primary,
            wisdom: primary,
            charisma: primary,
            ..Self::default()
        }
    }

    pub fn is_empty(&self) -> bool {
        self.strength == 0.0
            && self.dexterity == 0.0
            && self.intelligence == 0.0
            && self.stamina == 0.0
            && self.vitality == 0.0
            && self.wisdom == 0.0
            && self.charisma == 0.0
            && self.logging == 0.0
            && self.mining == 0.0
            && self.evocation == 0.0
            && self.restoration == 0.0
            && self.swords == 0.0
            && self.archery == 0.0
            && self.crafting == 0.0
            && self.alchemy == 0.0
            && self.cartography == 0.0
            && self.ability.is_empty()
    }
}

/// Per-ability mastery row for combat HUD / character sheet.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AbilityMasteryHud {
    pub ability_id: String,
    /// Mastery tier 0–10 (`SkillProgress::display_tier`).
    pub tier: u16,
    /// Internal level 0–1000.
    pub level: u16,
    /// Fractional XP in the ability pool.
    pub xp: f64,
    /// XP required to reach the next display step on the progression curve.
    pub xp_to_next: f64,
}

/// Core trained skills shipped at launch (`plans/11` §10).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct PlayerSkills {
    pub logging: SkillProgress,
    pub mining: SkillProgress,
    pub evocation: SkillProgress,
    #[serde(default)]
    pub restoration: SkillProgress,
    pub swords: SkillProgress,
    #[serde(default)]
    pub archery: SkillProgress,
    pub crafting: SkillProgress,
    #[serde(default)]
    pub alchemy: SkillProgress,
    pub cartography: SkillProgress,
}

impl Default for PlayerSkills {
    fn default() -> Self {
        Self {
            logging: SkillProgress::default(),
            mining: SkillProgress::default(),
            evocation: SkillProgress::default(),
            restoration: SkillProgress::default(),
            swords: SkillProgress::default(),
            archery: SkillProgress::default(),
            crafting: SkillProgress::default(),
            alchemy: SkillProgress::default(),
            cartography: SkillProgress::default(),
        }
    }
}

/// Player health / resources (players only; omitted on other entities).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct PlayerVitals {
    pub health: f32,
    pub health_max: f32,
    pub mana: f32,
    pub mana_max: f32,
    pub stamina: f32,
    pub stamina_max: f32,
    #[serde(default = "default_survival_pool_max")]
    pub hunger: f32,
    #[serde(default = "default_survival_pool_max")]
    pub hunger_max: f32,
    #[serde(default = "default_survival_pool_max")]
    pub thirst: f32,
    #[serde(default = "default_survival_pool_max")]
    pub thirst_max: f32,
    #[serde(default)]
    pub coins: u32,
    #[serde(default)]
    pub deaths: u32,
    #[serde(default)]
    pub life_state: LifeState,
    /// Hysteresis lock: entered at empty stamina, cleared at `vitals.exhaustion.recover_ratio`.
    #[serde(default)]
    pub winded: bool,
}

fn default_survival_pool_max() -> f32 {
    100.0
}

impl Default for PlayerVitals {
    fn default() -> Self {
        Self::from_attributes(PrimaryAttributes::default())
    }
}

impl PlayerVitals {
    /// Build pool maximums from primary attributes (current pools filled to max).
    ///
    /// Uses **display** stats (internal ÷ 10) so pools scale intuitively with
    /// progression, gear, and future enchant modifiers on attributes.
    ///
    /// Default attrs (all 150 → display 15): ~80 HP, ~51 stamina, ~61 mana.
    pub fn from_attributes(attrs: PrimaryAttributes) -> Self {
        let vit_d = PrimaryAttributes::display(attrs.vitality) as f32;
        let int_d = PrimaryAttributes::display(attrs.intelligence) as f32;
        let wis_d = PrimaryAttributes::display(attrs.wisdom) as f32;
        let sta_d = PrimaryAttributes::display(attrs.stamina) as f32;

        let health_max = 50.0 + vit_d * 2.0;
        let stamina_max = 30.0 + sta_d * 1.4;
        let mana_max = 25.0 + int_d * 1.1 + wis_d * 1.3;
        let hunger_max = 100.0;
        let thirst_max = 100.0;
        Self {
            health: health_max,
            health_max,
            mana: mana_max,
            mana_max,
            stamina: stamina_max,
            stamina_max,
            hunger: hunger_max,
            hunger_max,
            thirst: thirst_max,
            thirst_max,
            coins: 0,
            deaths: 0,
            life_state: LifeState::Alive,
            winded: false,
        }
    }

    /// Legacy pool maxima (pre-2026-07 pool rebalance) for migration scaling.
    pub fn legacy_maxima(attrs: PrimaryAttributes) -> (f32, f32, f32) {
        (
            attrs.vitality as f32 / 5.0,
            attrs.stamina as f32 / 5.0,
            (attrs.intelligence as f32 + attrs.wisdom as f32) / 20.0,
        )
    }
}

/// Durable pool snapshot for Postgres (max values recomputed from attributes on load).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct StoredVitalsState {
    pub health: f32,
    pub mana: f32,
    pub stamina: f32,
    pub hunger: f32,
    pub thirst: f32,
    pub coins: u32,
    pub deaths: u32,
    pub life_state: LifeState,
    #[serde(default)]
    pub winded: bool,
}

impl StoredVitalsState {
    pub fn from_live(v: &PlayerVitals) -> Self {
        Self {
            health: v.health,
            mana: v.mana,
            stamina: v.stamina,
            hunger: v.hunger,
            thirst: v.thirst,
            coins: v.coins,
            deaths: v.deaths,
            life_state: v.life_state,
            winded: v.winded,
        }
    }

    /// Empty `{}` JSON from a new character row — not a real gameplay snapshot.
    pub fn is_pristine(&self) -> bool {
        self.health == 0.0
            && self.mana == 0.0
            && self.stamina == 0.0
            && self.hunger == 0.0
            && self.thirst == 0.0
            && self.coins == 0
            && self.deaths == 0
            && self.life_state == LifeState::Alive
    }

    pub fn apply_to(self, attrs: PrimaryAttributes) -> PlayerVitals {
        if self.is_pristine() {
            return PlayerVitals::from_attributes(attrs);
        }
        let fresh = PlayerVitals::from_attributes(attrs);
        let (legacy_hp, legacy_sta, legacy_mana) = PlayerVitals::legacy_maxima(attrs);

        let scale = |current: f32, legacy_max: f32, new_max: f32| {
            if legacy_max > 0.0 && new_max > legacy_max * 1.05 && current >= legacy_max * 0.95 {
                let ratio = (current / legacy_max).clamp(0.0, 1.0);
                (new_max * ratio).min(new_max)
            } else {
                current.min(new_max)
            }
        };

        let mut v = fresh;
        v.health = scale(self.health, legacy_hp, fresh.health_max);
        v.mana = scale(self.mana, legacy_mana, fresh.mana_max);
        v.stamina = scale(self.stamina, legacy_sta, fresh.stamina_max);
        v.hunger = self.hunger.min(v.hunger_max);
        v.thirst = self.thirst.min(v.thirst_max);
        v.coins = self.coins;
        v.deaths = self.deaths;
        v.life_state = self.life_state;
        v.winded = self.winded;
        v
    }
}

impl Default for StoredVitalsState {
    fn default() -> Self {
        Self::from_live(&PlayerVitals::default())
    }
}

/// Fallback display text for snake_case ids when no authored label exists.
///
/// Example: `heal_touch` → `Heal Touch`. Prefer catalog/`label` fields when present.
pub fn humanize_snake_id(id: &str) -> String {
    id.split('_')
        .filter(|part| !part.is_empty())
        .map(|part| {
            let mut chars = part.chars();
            match chars.next() {
                None => String::new(),
                Some(first) => first.to_uppercase().chain(chars).collect(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Character-owned combat ability (skill book / temporary grant).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct KnownAbility {
    pub ability_id: String,
    /// When false, `expires_at_tick` must be set.
    #[serde(default = "default_known_permanent")]
    pub permanent: bool,
    /// Sim tick when a temporary grant ends (`None` = permanent).
    #[serde(default)]
    pub expires_at_tick: Option<u64>,
}

fn default_known_permanent() -> bool {
    true
}

impl KnownAbility {
    pub fn permanent(ability_id: impl Into<String>) -> Self {
        Self {
            ability_id: ability_id.into(),
            permanent: true,
            expires_at_tick: None,
        }
    }

    pub fn is_active(&self, tick: u64) -> bool {
        if self.permanent {
            return true;
        }
        match self.expires_at_tick {
            Some(exp) => tick < exp,
            None => false,
        }
    }
}

/// Saved ability rotation preset (`plans/26` §C3).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RotationPreset {
    pub id: String,
    pub label: String,
    #[serde(default)]
    pub abilities: Vec<String>,
}

impl RotationPreset {
    pub fn melee_default(ability_id: impl Into<String>) -> Self {
        let id = ability_id.into();
        Self {
            id: "melee".into(),
            // Built-in weapon auto preset — ability tracks equipped mainhand.
            label: "Weapon".into(),
            abilities: vec![id],
        }
    }

    pub fn is_weapon_preset(&self) -> bool {
        self.id == "melee"
    }
}

/// Durable combat state (`plans/12` §4.1) — target by wildlife instance id, not entity id.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct StoredTargetSlot {
    pub instance_id: Option<String>,
    #[serde(default)]
    pub preset_id: Option<String>,
    #[serde(default)]
    pub rotation_index: u32,
    #[serde(default)]
    pub auto_enabled: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct StoredCombatProfile {
    /// Wildlife `instance_id` (e.g. `meadow-rabbits-0`), stable across worker restarts.
    pub combat_target_instance_id: Option<String>,
    pub in_combat: bool,
    pub last_combat_tick: u64,
    pub last_attack_tick: u64,
    pub cooldowns_until_tick: BTreeMap<String, u64>,
    #[serde(default = "default_auto_attack")]
    pub auto_attack_enabled: bool,
    /// Equipped mainhand weapon template id (`plans/26` §C2b).
    #[serde(default)]
    pub mainhand_template_id: Option<String>,
    /// Specific mainhand instance (bindings / unique gear).
    #[serde(default)]
    pub mainhand_instance_id: Option<Uuid>,
    /// Equipped offhand (shield / dual-wield). Cleared when mainhand is two-handed.
    #[serde(default)]
    pub offhand_template_id: Option<String>,
    /// Specific offhand instance.
    #[serde(default)]
    pub offhand_instance_id: Option<Uuid>,
    /// Equipped body-slot items (backpack, belt, armor, jewelry), nested contents included
    /// (e.g. pouches clipped onto a worn belt). At most one entry per `BodySlot`.
    #[serde(default)]
    pub worn: Vec<(BodySlot, ItemStack)>,
    /// Player-authored rotation library (`plans/26` §C3).
    #[serde(default)]
    pub rotation_presets: Vec<RotationPreset>,
    /// Per-target slot state (T1/T2).
    #[serde(default)]
    pub target_slots: Vec<StoredTargetSlot>,
    /// Discovered craft recipe ids (`plans/09` §C2 hybrid discovery).
    #[serde(default)]
    pub known_blueprint_ids: Vec<String>,
    /// Keys stowed on the keychain (not counted toward carry mass).
    #[serde(default)]
    pub keychain: Vec<ItemStack>,
    /// Paired whisper stones ("phones") — zero carry mass; persists with combat profile.
    #[serde(default)]
    pub whisper_pouch: Vec<ItemStack>,
    /// Learned combat abilities (skill books / temporary grants). Empty on load → default unarmed.
    #[serde(default)]
    pub known_abilities: Vec<KnownAbility>,
    /// Hotbar slots 1–9 (`None` / missing = unbound). Empty on load → slot 1 = unarmed.
    #[serde(default)]
    pub hotbar: Vec<Option<String>>,
    /// Bump when combat ability progression model changes. `0` = pre–skill-book open kit.
    #[serde(default)]
    pub abilities_schema_version: u32,
    /// Secure bank ledger balance in copper (`plans/08` §8). Persists with combat profile.
    #[serde(default)]
    pub bank_balance_copper: u64,
}

fn default_auto_attack() -> bool {
    true
}

impl Default for StoredCombatProfile {
    fn default() -> Self {
        Self {
            combat_target_instance_id: None,
            in_combat: false,
            last_combat_tick: 0,
            last_attack_tick: 0,
            cooldowns_until_tick: BTreeMap::new(),
            auto_attack_enabled: true,
            mainhand_template_id: None,
            mainhand_instance_id: None,
            offhand_template_id: None,
            offhand_instance_id: None,
            worn: Vec::new(),
            rotation_presets: Vec::new(),
            target_slots: Vec::new(),
            known_blueprint_ids: Vec::new(),
            keychain: Vec::new(),
            whisper_pouch: Vec::new(),
            known_abilities: Vec::new(),
            hotbar: Vec::new(),
            abilities_schema_version: 0,
            bank_balance_copper: 0,
        }
    }
}

/// Short-lived combat overlay on an entity (dodge/block i-frames, attack wind-up).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CombatCueKind {
    Dodge,
    Block,
    AttackTelegraph,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CombatCueView {
    pub kind: CombatCueKind,
    /// Sim tick after which clients should hide this cue.
    pub until_tick: Tick,
    /// Sim tick when the cue began (for progress rings). `0` = client estimates from kind.
    #[serde(default)]
    pub start_tick: Tick,
    /// Ability id when `kind` is [`CombatCueKind::AttackTelegraph`].
    #[serde(default)]
    pub ability_id: Option<String>,
    /// When set, clients draw a spatial impact preview (red zone) at this origin.
    #[serde(default)]
    pub telegraph_kind: Option<CombatFxKind>,
    #[serde(default)]
    pub origin_x: Option<f32>,
    #[serde(default)]
    pub origin_y: Option<f32>,
    #[serde(default)]
    pub origin_z: Option<f32>,
    #[serde(default)]
    pub end_x: Option<f32>,
    #[serde(default)]
    pub end_y: Option<f32>,
    #[serde(default)]
    pub end_z: Option<f32>,
    #[serde(default)]
    pub yaw: Option<f32>,
    #[serde(default)]
    pub reach_m: Option<f32>,
    #[serde(default)]
    pub arc_deg: Option<f32>,
    #[serde(default)]
    pub radius_m: Option<f32>,
}

impl CombatCueView {
    /// Timing-only cue (dodge / block / entity wind-up without impact preview).
    pub fn timing(kind: CombatCueKind, until_tick: Tick, start_tick: Tick) -> Self {
        Self {
            kind,
            until_tick,
            start_tick,
            ability_id: None,
            telegraph_kind: None,
            origin_x: None,
            origin_y: None,
            origin_z: None,
            end_x: None,
            end_y: None,
            end_z: None,
            yaw: None,
            reach_m: None,
            arc_deg: None,
            radius_m: None,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EntityState {
    pub id: EntityId,
    pub transform: Transform,
    /// Character / display name (first letter used as map glyph for other players).
    #[serde(default)]
    pub label: String,
    #[serde(default)]
    pub vitals: Option<PlayerVitals>,
    /// Primary attributes (local player / inspect).
    #[serde(default)]
    pub attributes: Option<PrimaryAttributes>,
    #[serde(default)]
    pub skills: Option<PlayerSkills>,
    /// When inside a building interior (players only).
    #[serde(default)]
    pub inside_building: Option<String>,
    /// Gfx sprite sheet id for non-character entities. Player/NPC avatars use `paperdoll_ref` only.
    #[serde(default)]
    pub tile_id: Option<String>,
    /// Paperdoll skin id (`assets/paperdoll/skins/`). Client prefers this over `tile_id` when baked.
    #[serde(default)]
    pub paperdoll_ref: Option<String>,
    /// World draw size in map cells (from paperdoll skin `draw_scale`; 1.0 = one cell).
    #[serde(default = "default_draw_scale")]
    pub draw_scale: f32,
    /// Canonical gfx presentation key (`walking`, `combat`, `harvesting`, …).
    #[serde(default)]
    pub presentation_state: Option<String>,
    /// Resolved gfx sprite mode for `tile_id` (server-computed).
    #[serde(default)]
    pub sprite_mode: Option<String>,
    /// XP pools for local player progression display (omitted on NPCs / other players).
    #[serde(default)]
    pub progression_xp: Option<ProgressionXp>,
    /// Active dodge/block windows and attack telegraphs for map FX.
    #[serde(default)]
    pub combat_cues: Vec<CombatCueView>,
    /// Active status effects for world indicators (AOI entities / other players).
    #[serde(default)]
    pub statuses: Vec<StatusEffectHud>,
}

/// In-world speech / stone contact channels.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ChatChannel {
    /// Untargeted voice — everyone in acoustic range may hear.
    Nearby,
    /// Directed speak at a nearby player (eavesdroppers may overhear).
    Direct,
    /// Directed private whisper (range 0 for eavesdroppers).
    Whisper,
    /// Long-range contact via paired whisper stones ("phones").
    WhisperStone,
}

/// How clearly this recipient heard the line (server-authored text already matches).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum ChatClarity {
    #[default]
    Clear,
    Partial,
    Heavy,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChatMessage {
    pub channel: ChatChannel,
    pub from_entity: EntityId,
    pub from_name: String,
    /// Text as this recipient should see it (already garbled when unclear).
    pub text: String,
    pub tick: Tick,
    /// Directed / stone peer (omitted for untargeted Nearby).
    #[serde(default)]
    pub to_entity: Option<EntityId>,
    #[serde(default)]
    pub clarity: ChatClarity,
}

/// Client → server gameplay input (reliable, sequenced per entity).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Intent {
    Move {
        entity_id: EntityId,
        forward: f32,
        strafe: f32,
        /// Climb (+) or descend (−) on z axis (m/s intent).
        #[serde(default)]
        vertical: f32,
        /// Sprint multiplier when stamina allows.
        #[serde(default)]
        sprint: bool,
        /// Quiet slow movement (overrides sprint when both set).
        #[serde(default)]
        sneak: bool,
        seq: Seq,
    },
    Stop {
        entity_id: EntityId,
        seq: Seq,
    },
    Harvest {
        entity_id: EntityId,
        node_id: String,
        seq: Seq,
    },
    Use {
        entity_id: EntityId,
        template_id: String,
        seq: Seq,
    },
    /// Apply a grant consumable onto a specific item instance (unique gear status bindings).
    UseGrant {
        entity_id: EntityId,
        grant_instance_id: Uuid,
        target_instance_id: Uuid,
        seq: Seq,
    },
    Say {
        entity_id: EntityId,
        channel: ChatChannel,
        text: String,
        /// Required for Direct / Whisper / WhisperStone (peer entity).
        #[serde(default)]
        to_entity: Option<EntityId>,
        seq: Seq,
    },
    /// Start a blueprint craft (timed, like harvest).
    Craft {
        entity_id: EntityId,
        blueprint_id: String,
        /// Batches to run back-to-back; `None` crafts as many as materials/stamina allow.
        #[serde(default)]
        count: Option<u32>,
        seq: Seq,
    },
    /// Door, NPC, enter/exit building.
    Interact {
        entity_id: EntityId,
        target_id: String,
        seq: Seq,
    },
    /// Buy from an NPC shop offer (`ShopOpened` catalog).
    ShopBuy {
        entity_id: EntityId,
        npc_id: String,
        offer_id: String,
        #[serde(default = "default_one")]
        quantity: u32,
        seq: Seq,
    },
    /// Sell inventory to an NPC (`ShopOpened` buy list).
    ShopSell {
        entity_id: EntityId,
        npc_id: String,
        template_id: String,
        #[serde(default = "default_one")]
        quantity: u32,
        seq: Seq,
    },
    /// Close an open NPC shop UI (releases the NPC movement pin).
    ShopClose {
        entity_id: EntityId,
        npc_id: String,
        seq: Seq,
    },
    /// Dev / test: apply damage to self (co-op testing).
    TestDamage {
        entity_id: EntityId,
        amount: f32,
        seq: Seq,
    },
    /// Slot-1 combat target (`plans/12` alias).
    SetTarget {
        entity_id: EntityId,
        target_id: EntityId,
        seq: Seq,
    },
    /// Target slot assignment (`plans/12` §5.3). Slot 1 aliases `SetTarget`.
    SetTargetSlot {
        entity_id: EntityId,
        slot_index: u8,
        target_id: EntityId,
        seq: Seq,
    },
    ClearTarget {
        entity_id: EntityId,
        seq: Seq,
    },
    ClearTargetSlot {
        entity_id: EntityId,
        slot_index: u8,
        seq: Seq,
    },
    /// Toggle per-slot auto-attack (`plans/12` §4.2).
    SetAutoAttack {
        entity_id: EntityId,
        slot_index: u8,
        enabled: bool,
        seq: Seq,
    },
    /// Melee attack — uses `target_id` or the player's current target.
    Attack {
        entity_id: EntityId,
        #[serde(default)]
        target_id: Option<EntityId>,
        #[serde(default)]
        weapon_slot: Option<u32>,
        seq: Seq,
    },
    /// Pick up a ground loot pile (nearest in range when `drop_id` omitted).
    Pickup {
        entity_id: EntityId,
        #[serde(default)]
        drop_id: Option<String>,
        seq: Seq,
    },
    /// Cast a spell or use a non-weapon ability template (`plans/24` §4.3b).
    /// Optional [`target_point`] aims AoE / ground spells at a map location (Shift+click).
    Cast {
        entity_id: EntityId,
        ability_id: String,
        target_id: EntityId,
        #[serde(default)]
        target_point: Option<AimPoint>,
        seq: Seq,
    },
    /// Bind an ability to a target slot action bar (`plans/12` §4.2).
    BindActionSlot {
        entity_id: EntityId,
        slot_index: u8,
        ability_id: String,
        #[serde(default = "default_auto_attack")]
        auto_enabled: bool,
        seq: Seq,
    },
    /// Fire a bound consumable or ability from a slot (`plans/24` §4.3c).
    UseActionSlot {
        entity_id: EntityId,
        slot_index: u8,
        seq: Seq,
    },
    /// Dodge — brief i-frames, stamina cost; re-press during window refreshes (`plans/24` §4.3c).
    /// When `forward`/`strafe` are non-zero (WASD held), burst that way if walkable;
    /// otherwise the sim picks a smart auto destination (telegraph exit / rear).
    Dodge {
        entity_id: EntityId,
        /// Movement forward axis when dodging with WASD (−1..1). `0` = auto aim.
        #[serde(default)]
        forward: f32,
        /// Movement strafe axis when dodging with WASD (−1..1). `0` = auto aim.
        #[serde(default)]
        strafe: f32,
        seq: Seq,
    },
    /// Lunge — burst forward in movement/facing direction, higher stamina cost.
    Lunge {
        entity_id: EntityId,
        /// Last movement forward axis when idle (−1..1).
        #[serde(default)]
        forward: f32,
        /// Last movement strafe axis when idle (−1..1).
        #[serde(default)]
        strafe: f32,
        seq: Seq,
    },
    /// Directional jump — leap one cell uphill over a medium cliff (`plans/04` §4.5b).
    DirectionalJump {
        entity_id: EntityId,
        /// Jump direction forward axis (−1..1).
        #[serde(default)]
        forward: f32,
        /// Jump direction strafe axis (−1..1).
        #[serde(default)]
        strafe: f32,
        seq: Seq,
    },
    /// Block — frontal mitigation while held (`plans/24` §4.3c).
    Block {
        entity_id: EntityId,
        #[serde(default = "default_block_enabled")]
        enabled: bool,
        seq: Seq,
    },
    /// Equip or clear mainhand weapon (`plans/26` §C2b). `None` unequips.
    /// Two-handed weapons (`hand_slots: 2`) clear offhand on equip.
    /// Prefer `instance_id` so unique bindings travel with that weapon instance.
    EquipMainhand {
        entity_id: EntityId,
        #[serde(default)]
        template_id: Option<String>,
        #[serde(default)]
        instance_id: Option<Uuid>,
        seq: Seq,
    },
    /// Equip or clear offhand (shield / dual-wield). Rejected while mainhand is two-handed.
    EquipOffhand {
        entity_id: EntityId,
        #[serde(default)]
        template_id: Option<String>,
        #[serde(default)]
        instance_id: Option<Uuid>,
        seq: Seq,
    },
    /// Equip a wearable (container, belt, armor, jewelry) to a body slot, or clear the
    /// slot when `instance_id` is None.
    EquipWorn {
        entity_id: EntityId,
        slot: BodySlot,
        #[serde(default)]
        instance_id: Option<Uuid>,
        seq: Seq,
    },
    /// Move an item instance between root / worn / placed container inventories.
    MoveItem {
        entity_id: EntityId,
        item_instance_id: Uuid,
        from: InventoryLocation,
        to: InventoryLocation,
        /// When moving into a container location, nest under this parent instance (None = container root).
        #[serde(default)]
        to_parent_instance_id: Option<Uuid>,
        /// Units to move; `None` moves the whole stack. Server clamps to volume/carry limits.
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Place a placeable container from inventory onto the ground at the player's feet.
    PlaceContainer {
        entity_id: EntityId,
        item_instance_id: Uuid,
        seq: Seq,
    },
    /// Pick up a placed container (with contents) into inventory.
    PickupContainer {
        entity_id: EntityId,
        container_id: String,
        seq: Seq,
    },
    /// Relocate a placed container on the map without picking it up (keeps id / lodging).
    MovePlacedContainer {
        entity_id: EntityId,
        container_id: String,
        x: f32,
        y: f32,
        seq: Seq,
    },
    /// Lock or unlock a worn or placed container (requires matching key when locking/unlocking).
    SetContainerLocked {
        entity_id: EntityId,
        /// Worn slot or placed container id encoded as location.
        location: InventoryLocation,
        locked: bool,
        seq: Seq,
    },
    /// Drop a non-container item on the ground at the player's feet.
    DropItem {
        entity_id: EntityId,
        item_instance_id: Uuid,
        from: InventoryLocation,
        seq: Seq,
    },
    /// Permanently destroy an item stack (not recoverable; no ground drop).
    DestroyItem {
        entity_id: EntityId,
        item_instance_id: Uuid,
        from: InventoryLocation,
        /// Units to destroy; `None` destroys the whole stack.
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Set a custom display name on a container instance (chest, pouch, backpack).
    RenameContainer {
        entity_id: EntityId,
        item_instance_id: Uuid,
        location: InventoryLocation,
        name: String,
        seq: Seq,
    },
    /// Create or update a rotation preset in the player's library.
    UpsertRotationPreset {
        entity_id: EntityId,
        preset: RotationPreset,
        seq: Seq,
    },
    /// Remove a rotation preset from the library.
    DeleteRotationPreset {
        entity_id: EntityId,
        preset_id: String,
        seq: Seq,
    },
    /// Assign a library preset to target slot T1/T2.
    AssignSlotPreset {
        entity_id: EntityId,
        slot_index: u8,
        preset_id: String,
        seq: Seq,
    },
    /// Bind or clear a hotbar slot (`1`–`9`) to a learned / weapon ability
    /// or an inventory consumable (`item:<template_id>` — see [`hotbar_consumable_binding`]).
    SetHotbarSlot {
        entity_id: EntityId,
        /// 1–9
        slot: u8,
        /// `None` clears the slot. Ability id, or `item:<template_id>` for consumables.
        #[serde(default)]
        ability_id: Option<String>,
        seq: Seq,
    },
    /// Fire the next ready ability in a slot's rotation (manual step).
    AdvanceRotation {
        entity_id: EntityId,
        slot_index: u8,
        seq: Seq,
    },
    /// Open a turn-based conversation with an NPC.
    NpcTalkOpen {
        entity_id: EntityId,
        npc_id: String,
        /// When set, deliver that quest's offer or `talk_npc` line. Casual Talk omits this.
        #[serde(default)]
        quest_id: Option<String>,
        seq: Seq,
    },
    /// Send a player message in an open NPC conversation.
    NpcTalkSay {
        entity_id: EntityId,
        npc_id: String,
        message: String,
        seq: Seq,
    },
    /// Close an NPC conversation.
    NpcTalkClose {
        entity_id: EntityId,
        npc_id: String,
        seq: Seq,
    },
    /// Accept a discovered quest (adds to active list).
    AcceptQuest {
        entity_id: EntityId,
        quest_id: String,
        seq: Seq,
    },
    /// Withdraw from an active quest (resets progress; can re-accept).
    WithdrawQuest {
        entity_id: EntityId,
        quest_id: String,
        seq: Seq,
    },
    /// Highlight an active quest in the HUD.
    TrackQuest {
        entity_id: EntityId,
        quest_id: String,
        seq: Seq,
    },
    /// Turn in items for an active give_item objective while near an NPC.
    QuestGiveItem {
        entity_id: EntityId,
        npc_id: String,
        template_id: String,
        #[serde(default = "default_one")]
        quantity: u32,
        seq: Seq,
    },
    /// Hire an NPC worker (fee + recurring wage).
    HireWorker {
        entity_id: EntityId,
        def_id: String,
        wage_copper_per_interval: u32,
        #[serde(default)]
        lodging_container_id: Option<String>,
        #[serde(default)]
        job_yaml: Option<String>,
        seq: Seq,
    },
    /// Release a hired worker instance.
    DismissWorker {
        entity_id: EntityId,
        worker_instance_id: String,
        seq: Seq,
    },
    /// Replace or assign a worker job YAML loop.
    SetWorkerJob {
        entity_id: EntityId,
        worker_instance_id: String,
        job_yaml: String,
        seq: Seq,
    },
    /// Point a worker at a camp bed / lodging container.
    AssignWorkerLodging {
        entity_id: EntityId,
        worker_instance_id: String,
        lodging_container_id: String,
        seq: Seq,
    },
    /// Switch companion vs job-loop automation mode.
    SetWorkerMode {
        entity_id: EntityId,
        worker_instance_id: String,
        mode: String,
        seq: Seq,
    },
    /// Equip one item from the employer's inventory on a hired worker.
    ///
    /// `slot` accepts `mainhand`, `offhand`, or a `BodySlot` name such as
    /// `chest` / `head`. The item remains owned by the worker while equipped
    /// and is included in worker snapshots.
    EquipWorkerItem {
        entity_id: EntityId,
        worker_instance_id: String,
        item_instance_id: uuid::Uuid,
        slot: String,
        seq: Seq,
    },
    /// Hand an item from the player's inventory to a hired worker (e.g. a tool the
    /// worker must carry but not consume, like a handsaw for `oak_to_lumber`).
    GiveWorkerItem {
        entity_id: EntityId,
        worker_instance_id: String,
        item_instance_id: uuid::Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Take an item from a hired worker's inventory back into the employer's root.
    TakeWorkerItem {
        entity_id: EntityId,
        worker_instance_id: String,
        item_instance_id: uuid::Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Set a custom display name for a hired worker (shown in menus / route editor).
    RenameHiredWorker {
        entity_id: EntityId,
        worker_instance_id: String,
        name: String,
        seq: Seq,
    },
    /// Rename an owned property plot label (deed title and Location HUD follow).
    RenamePropertyPlot {
        entity_id: EntityId,
        plot_id: Uuid,
        label: String,
        seq: Seq,
    },
    /// Teach a known blueprint to a hired worker (costs `worker_train_copper`).
    TeachWorkerBlueprint {
        entity_id: EntityId,
        worker_instance_id: String,
        blueprint_id: String,
        seq: Seq,
    },
    /// Employer opened/closed the worker manage UI (`f` next to them) — pause job steps.
    AttendHiredWorker {
        entity_id: EntityId,
        worker_instance_id: String,
        attending: bool,
        seq: Seq,
    },
    /// Buy a fractional plot inside a crown property zone (plan 40). Mints a deed.
    BuyPlot {
        entity_id: EntityId,
        zone_id: String,
        x0: f32,
        y0: f32,
        x1: f32,
        y1: f32,
        seq: Seq,
    },
    /// Claim the largest free AABB in a property zone (plan 40).
    BuyPlotAllFree {
        entity_id: EntityId,
        zone_id: String,
        seq: Seq,
    },
    /// Sell a plot back to the crown (requires holding the deed).
    SellPlotToCrown {
        entity_id: EntityId,
        plot_id: Uuid,
        seq: Seq,
    },
    /// Cultivate one cell under/near the player into tilled soil (plan 40 P1).
    Cultivate {
        entity_id: EntityId,
        /// World cell to till (floor coords). Must be on an owned plot.
        x: f32,
        y: f32,
        seq: Seq,
    },
    /// Plant seeds onto free tilled cells on owned plots near the player (plan 40 P2).
    PlantSeeds {
        entity_id: EntityId,
        seed_template_id: String,
        quantity: u32,
        seq: Seq,
    },
    /// Toggle public farm access + public tax discount on an owned plot.
    SetPlotFarmPublic {
        entity_id: EntityId,
        plot_id: Uuid,
        public: bool,
        #[serde(default)]
        public_tax_discount_bps: u32,
        seq: Seq,
    },
    /// Add or update a named tenant farm grant (negotiated tax discount).
    PlotFarmAllowUpsert {
        entity_id: EntityId,
        plot_id: Uuid,
        /// Preferred when known.
        #[serde(default)]
        character_id: Option<Uuid>,
        /// Fallback: match online player display name (case-insensitive).
        #[serde(default)]
        character_name: String,
        #[serde(default)]
        tax_discount_bps: u32,
        seq: Seq,
    },
    /// Remove a named tenant from a plot's farm allow-list.
    PlotFarmAllowRemove {
        entity_id: EntityId,
        plot_id: Uuid,
        character_id: Uuid,
        seq: Seq,
    },
    /// Start timed craft to build a shell on the plot's solid tilled rectangle (plan 20 §18).
    /// Materials are taken from town storage (plot in boundary) or a nearby chest (outside).
    StartPlotBuild {
        entity_id: EntityId,
        plot_id: Uuid,
        wall_material_id: String,
        roof_material_id: String,
        seq: Seq,
    },
    CancelPlotBuild {
        entity_id: EntityId,
        seq: Seq,
    },
    /// Lock/unlock a player building exterior door (requires matching key).
    /// Door must be closed to lock.
    SetDoorLocked {
        entity_id: EntityId,
        door_id: String,
        locked: bool,
        seq: Seq,
    },
    /// Walk in through an already-open player-building exterior door.
    /// Latch open/close stays on [`Intent::Interact`] (`f`); map buildings still use open→enter.
    EnterBuildingDoor {
        entity_id: EntityId,
        door_id: String,
        seq: Seq,
    },
    /// Leave through an exterior portal from inside a player building.
    /// Always allowed even if the door is closed or locked (anti-trap).
    ExitBuildingDoor {
        entity_id: EntityId,
        door_id: String,
        seq: Seq,
    },
    /// Apply interior room layout; copper charged once on confirm.
    ConfirmInteriorEdit {
        entity_id: EntityId,
        building_id: String,
        rooms: Vec<InteriorRoomEdit>,
        room_doors: Vec<InteriorRoomDoorEdit>,
        seq: Seq,
    },
    CancelInteriorEdit {
        entity_id: EntityId,
        building_id: String,
        seq: Seq,
    },
    /// Deposit physical coins into the bank ledger at a teller (`plans/08` §8).
    BankDeposit {
        entity_id: EntityId,
        npc_id: String,
        /// Copper to deposit; `0` means deposit all on-person copper.
        #[serde(default)]
        amount_copper: u64,
        seq: Seq,
    },
    /// Withdraw copper from the bank ledger as physical coins at a teller.
    BankWithdraw {
        entity_id: EntityId,
        npc_id: String,
        /// Copper to withdraw; `0` means withdraw all bank balance.
        #[serde(default)]
        amount_copper: u64,
        seq: Seq,
    },
    /// Close the bank teller UI.
    BankClose {
        entity_id: EntityId,
        npc_id: String,
        seq: Seq,
    },
    /// Magical clearinghouse transfer to another character's bank ledger (`plans/08` §8.3).
    BankTransfer {
        entity_id: EntityId,
        npc_id: String,
        /// Recipient character id (preferred when known).
        #[serde(default)]
        to_character_id: Option<Uuid>,
        /// Fallback: match an online player's display name (case-insensitive).
        #[serde(default)]
        to_name: String,
        /// Copper to send (fee is extra, taken from sender bank balance).
        amount_copper: u64,
        seq: Seq,
    },
    /// Store an on-person item into the town storage vault at a storage manager.
    StorageStore {
        entity_id: EntityId,
        npc_id: String,
        item_instance_id: Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Take an item from the town storage vault onto person.
    StorageTake {
        entity_id: EntityId,
        npc_id: String,
        item_instance_id: Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Ship vault items to another storage building (distance fee + travel time).
    StorageShip {
        entity_id: EntityId,
        npc_id: String,
        dest_building_id: String,
        item_instance_id: Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Close the storage manager UI.
    StorageClose {
        entity_id: EntityId,
        npc_id: String,
        seq: Seq,
    },
    /// List goods from person or town storage into a market hall's escrow
    /// (`plans/10-economy-and-markets.md` §4.3).
    MarketList {
        entity_id: EntityId,
        npc_id: String,
        source: GoodsLocation,
        item_instance_id: Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        unit_price_copper: u64,
        /// When true, `unit_price_copper` is ignored — dump-queue mode (`plans/53`).
        #[serde(default)]
        npc_price: bool,
        seq: Seq,
    },
    /// Change the unit price of one of the caller's own listings.
    MarketReprice {
        entity_id: EntityId,
        npc_id: String,
        listing_id: Uuid,
        unit_price_copper: u64,
        seq: Seq,
    },
    /// Pull one of the caller's own listings back out of escrow.
    MarketDelist {
        entity_id: EntityId,
        npc_id: String,
        listing_id: Uuid,
        dest: GoodsLocation,
        seq: Seq,
    },
    /// Buy some or all of a listing's remaining quantity (§4.4).
    MarketBuy {
        entity_id: EntityId,
        npc_id: String,
        listing_id: Uuid,
        #[serde(default = "default_one")]
        quantity: u32,
        dest: GoodsLocation,
        seq: Seq,
    },
    /// Close the market clerk UI.
    MarketClose {
        entity_id: EntityId,
        npc_id: String,
        seq: Seq,
    },
    /// Request a player-to-player trade with a nearby peer.
    TradeRequest {
        entity_id: EntityId,
        peer_entity_id: EntityId,
        seq: Seq,
    },
    /// Accept or decline a pending trade request.
    TradeRespond {
        entity_id: EntityId,
        peer_entity_id: EntityId,
        accept: bool,
        seq: Seq,
    },
    /// Move an inventory item into the trade escrow (presented bucket).
    TradePresent {
        entity_id: EntityId,
        item_instance_id: Uuid,
        #[serde(default)]
        quantity: Option<u32>,
        seq: Seq,
    },
    /// Return a presented item from escrow to inventory.
    TradeUnpresent {
        entity_id: EntityId,
        item_instance_id: Uuid,
        seq: Seq,
    },
    /// Toggle ready / handshake on the open trade.
    TradeSetReady {
        entity_id: EntityId,
        ready: bool,
        seq: Seq,
    },
    /// Cancel the open trade (or withdraw a pending request).
    TradeCancel {
        entity_id: EntityId,
        seq: Seq,
    },
    /// Destroy a paired whisper stone from the whisper pouch (cut contact).
    DestroyWhisperStone {
        entity_id: EntityId,
        item_instance_id: Uuid,
        seq: Seq,
    },
    /// Stow a blank or paired whisper stone from inventory into the pouch.
    StowWhisperStone {
        entity_id: EntityId,
        item_instance_id: Uuid,
        seq: Seq,
    },
    /// Send a companion worker on a one-shot run to deposit all carried items
    /// into the nearest employer-owned storage in the worker's jurisdiction.
    DeliverWorkerToNearestStorage {
        entity_id: EntityId,
        worker_instance_id: String,
        seq: Seq,
    },
    /// Cancel an active companion delivery and leave the worker where they are.
    CancelWorkerDelivery {
        entity_id: EntityId,
        worker_instance_id: String,
        seq: Seq,
    },
}

fn default_block_enabled() -> bool {
    true
}

/// One active status effect for HUD (buff/debuff icon strip).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct StatusEffectHud {
    pub effect_id: String,
    pub label: String,
    #[serde(default)]
    pub polarity: String,
    #[serde(default)]
    pub icon_tile_id: Option<String>,
    /// Designer-authored dot color (`#RRGGBB`); gfx falls back to polarity tint when absent.
    #[serde(default)]
    pub dot_color: Option<String>,
    /// Remaining duration in seconds (`None` when permanent while-equipped).
    #[serde(default)]
    pub remaining_sec: Option<f32>,
    /// Concurrent stacks of this effect (1 when not stacking).
    #[serde(default = "default_stack_count")]
    pub stack_count: u8,
}

fn default_stack_count() -> u8 {
    1
}

/// Observer combat HUD (local player only).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct CombatTargetHud {
    pub entity_id: EntityId,
    #[serde(default)]
    pub label: String,
    #[serde(default)]
    pub level: u32,
    pub health: f32,
    pub health_max: f32,
    #[serde(default)]
    pub life_state: LifeState,
    #[serde(default)]
    pub distance_m: f32,
    #[serde(default)]
    pub statuses: Vec<StatusEffectHud>,
}

/// Kind of in-world timed channel (farming, crafting stubs, …).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum TimedChannelKind {
    #[default]
    Cultivate,
    Plant,
    Harvest,
    /// Timed player-building craft on a plot tilled pad.
    Build,
    /// Inventory craft channel (n-menu recipes).
    Craft,
}

/// Local-player timed action (till, plant, …) — same progress shape as [`CastProgressHud`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct TimedChannelHud {
    #[serde(default)]
    pub label: String,
    #[serde(default)]
    pub channel: TimedChannelKind,
    #[serde(default)]
    pub cell_x: i32,
    #[serde(default)]
    pub cell_y: i32,
    /// Optional world AABB for multi-cell channels (plot build pad). Zero = unused.
    #[serde(default)]
    pub x0: f32,
    #[serde(default)]
    pub y0: f32,
    #[serde(default)]
    pub x1: f32,
    #[serde(default)]
    pub y1: f32,
    #[serde(default)]
    pub ticks_remaining: u64,
    #[serde(default)]
    pub ticks_total: u64,
}

impl TimedChannelHud {
    /// True when this channel carries a drawable footprint AABB.
    pub fn has_footprint(&self) -> bool {
        self.x1 > self.x0 && self.y1 > self.y0
    }
}

/// Where plot-build materials are drawn from (plan 20 §18).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum PlotBuildMaterialSource {
    #[default]
    None,
    TownStorage,
    NearbyContainer,
}

/// One catalog pack selectable as walls and/or roof.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct BuildingMaterialView {
    pub id: String,
    pub display_name: String,
    #[serde(default)]
    pub can_wall: bool,
    #[serde(default)]
    pub can_roof: bool,
    #[serde(default)]
    pub wall_set: String,
    #[serde(default)]
    pub roof_set: String,
    #[serde(default = "default_material_tick_mult")]
    pub tick_mult: f32,
    #[serde(default)]
    pub wall_bom: Vec<BuildingBomLineView>,
    #[serde(default)]
    pub roof_bom: Vec<BuildingBomLineView>,
}

fn default_material_tick_mult() -> f32 {
    1.0
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct BuildingBomLineView {
    pub template_id: String,
    #[serde(default)]
    pub display_name: String,
    pub per_m2: f32,
}

/// Available qty of one template in the eligible build material pool.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct PlotBuildStockView {
    pub template_id: String,
    #[serde(default)]
    pub display_name: String,
    pub quantity: u32,
}

/// Pad + storage pool for the B build menu (owned plot underfoot, no building yet).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct PlotBuildOfferHud {
    pub plot_id: Uuid,
    #[serde(default)]
    pub pad_width_m: f32,
    #[serde(default)]
    pub pad_depth_m: f32,
    #[serde(default)]
    pub pad_ok: bool,
    #[serde(default)]
    pub pad_error: String,
    #[serde(default)]
    pub source: PlotBuildMaterialSource,
    #[serde(default)]
    pub source_label: String,
    #[serde(default)]
    pub available: Vec<PlotBuildStockView>,
    #[serde(default)]
    pub base_ticks: u32,
    #[serde(default)]
    pub tick_per_m2: u32,
}

/// Active spell cast channel progress.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct CastProgressHud {
    #[serde(default)]
    pub ability_id: String,
    #[serde(default)]
    pub ability_label: String,
    #[serde(default)]
    pub ticks_remaining: u64,
    #[serde(default)]
    pub ticks_total: u64,
}

/// Cooldown state for a combat ability shown on the action bar.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct AbilityCooldownHud {
    #[serde(default)]
    pub ability_id: String,
    #[serde(default)]
    pub label: String,
    #[serde(default)]
    pub cd_ticks: u64,
    #[serde(default)]
    pub cd_total_ticks: u64,
}

/// One combat target slot in the observer HUD.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct CombatSlotHud {
    pub slot_index: u8,
    #[serde(default)]
    pub target_entity_id: Option<EntityId>,
    #[serde(default)]
    pub target_label: Option<String>,
    #[serde(default)]
    pub target: Option<CombatTargetHud>,
    #[serde(default)]
    pub preset_id: Option<String>,
    #[serde(default)]
    pub preset_label: Option<String>,
    #[serde(default)]
    pub rotation: Vec<String>,
    #[serde(default)]
    pub rotation_index: u32,
    #[serde(default)]
    pub next_ability_id: Option<String>,
    #[serde(default)]
    pub auto_enabled: bool,
}

/// One worn piece contribution in the defense breakdown.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DefensePieceHud {
    pub slot: BodySlot,
    pub label: String,
    pub template_id: String,
    #[serde(default)]
    pub armor_physical: f32,
    #[serde(default)]
    pub resists: Vec<(String, f32)>,
}

impl Default for DefensePieceHud {
    fn default() -> Self {
        Self {
            slot: BodySlot::Head,
            label: String::new(),
            template_id: String::new(),
            armor_physical: 0.0,
            resists: Vec::new(),
        }
    }
}

/// Aggregated mitigation / resist summary for the local player Equip UI.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct DefenseHud {
    pub armor_physical: f32,
    pub vitality_contribution: f32,
    pub total_mitigation_rating: f32,
    /// `rating / (rating + K)` physical damage reduction fraction.
    pub estimated_physical_dr: f32,
    #[serde(default)]
    pub resists: Vec<(String, f32)>,
    #[serde(default)]
    pub pieces: Vec<DefensePieceHud>,
}

/// Observer combat HUD (local player only).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct CombatHud {
    pub in_combat: bool,
    /// T1 auto rotation (legacy field mirrors slot 1).
    pub auto_attack: bool,
    pub has_los: bool,
    pub attack_cd_ticks: u64,
    #[serde(default)]
    pub ability_id: String,
    #[serde(default)]
    pub target_entity_id: Option<EntityId>,
    #[serde(default)]
    pub target_label: Option<String>,
    #[serde(default)]
    pub max_target_slots: u8,
    #[serde(default)]
    pub slots: Vec<CombatSlotHud>,
    #[serde(default)]
    pub rotation_presets: Vec<RotationPreset>,
    #[serde(default)]
    pub gcd_ticks: u64,
    #[serde(default)]
    pub mainhand_template_id: Option<String>,
    #[serde(default)]
    pub mainhand_label: Option<String>,
    /// Specific mainhand instance when known (bindings / unique gear).
    #[serde(default)]
    pub mainhand_instance_id: Option<Uuid>,
    #[serde(default)]
    pub offhand_template_id: Option<String>,
    #[serde(default)]
    pub offhand_label: Option<String>,
    /// Specific offhand instance when known.
    #[serde(default)]
    pub offhand_instance_id: Option<Uuid>,
    /// Mainhand occupies this many hand sockets (`1` or `2`).
    #[serde(default)]
    pub mainhand_hand_slots: u8,
    /// Equipped body-slot items (backpack, belt, armor, jewelry).
    #[serde(default)]
    pub worn: Vec<(BodySlot, ItemStack)>,
    /// Live mitigation / resist summary for the Equip paperdoll.
    #[serde(default)]
    pub defense: Option<DefenseHud>,
    #[serde(default)]
    pub carry_mass: f32,
    #[serde(default)]
    pub carry_mass_max: f32,
    #[serde(default)]
    pub encumbrance: EncumbranceState,
    /// Keys on the virtual keychain (stowed, zero carry mass).
    #[serde(default)]
    pub keychain: Vec<ItemStack>,
    /// Paired whisper stones on the virtual pouch (stowed, zero carry mass).
    #[serde(default)]
    pub whisper_pouch: Vec<ItemStack>,
    #[serde(default)]
    pub target: Option<CombatTargetHud>,
    #[serde(default)]
    pub cast: Option<CastProgressHud>,
    /// Non-combat timed channel on the local player (till, plant, …).
    #[serde(default)]
    pub timed_channel: Option<TimedChannelHud>,
    /// When standing on an owned plot with no building: pad + material pool for the B menu.
    #[serde(default)]
    pub plot_build: Option<PlotBuildOfferHud>,
    #[serde(default)]
    pub ability_cooldowns: Vec<AbilityCooldownHud>,
    #[serde(default)]
    pub blocking_active: bool,
    /// Live XP pools for the local player (updated every tick with combat HUD).
    #[serde(default)]
    pub progression_xp: Option<ProgressionXp>,
    #[serde(default)]
    pub progression_baseline: u16,
    #[serde(default)]
    pub progression_xp_base: f64,
    #[serde(default)]
    pub progression_xp_growth: f64,
    #[serde(default)]
    pub attributes: Option<PrimaryAttributes>,
    #[serde(default)]
    pub skills: Option<PlayerSkills>,
    /// Active status effects on the local player.
    #[serde(default)]
    pub statuses: Vec<StatusEffectHud>,
    /// Learned abilities currently usable (permanent + unexpired temporary).
    #[serde(default)]
    pub known_abilities: Vec<String>,
    /// Aim / blast metadata for known abilities (ground cast UX).
    #[serde(default)]
    pub ability_meta: Vec<AbilityMetaHud>,
    /// Per-ability mastery for known abilities (tier / XP).
    #[serde(default)]
    pub ability_mastery: Vec<AbilityMasteryHud>,
    /// Hotbar bindings for keys 1–9 (index 0 = key 1).
    /// Ability ids, or `item:<template_id>` for consumables ([`hotbar_consumable_binding`]).
    #[serde(default)]
    pub hotbar: Vec<Option<String>>,
    /// Max abilities allowed in one rotation (INT+WIS mind score).
    #[serde(default)]
    pub max_abilities_per_rotation: u8,
    /// Effective walk speed after encumbrance, DEX, and status (m/s). Not sneak/sprint.
    #[serde(default)]
    pub move_speed_mps: f32,
    /// Load/status multiplier on base walk (`1.0` = unencumbered). `0` = unknown.
    #[serde(default)]
    pub move_speed_mult: f32,
}

/// Client-facing ability aiming hints (synced on combat HUD).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AbilityMetaHud {
    pub id: String,
    /// `entity` | `ground` | `either`
    #[serde(default = "default_aim_mode_entity")]
    pub aim_mode: String,
    #[serde(default)]
    pub blast_radius_m: f32,
    #[serde(default)]
    pub allows_self: bool,
    #[serde(default)]
    pub is_heal: bool,
    /// When false, rotation editor / presets should not include this ability
    /// (hotbar / direct cast still allowed). Default true for older snapshots.
    #[serde(default = "default_auto_rotation_eligible")]
    pub auto_rotation_eligible: bool,
}

fn default_auto_rotation_eligible() -> bool {
    true
}

fn default_aim_mode_entity() -> String {
    "entity".into()
}

/// Prefix for hotbar slots bound to inventory consumables (`item:health_potion`).
pub const HOTBAR_ITEM_PREFIX: &str = "item:";

/// Encode a consumable template id for [`Intent::SetHotbarSlot`] / combat HUD hotbar.
pub fn hotbar_consumable_binding(template_id: &str) -> String {
    format!("{HOTBAR_ITEM_PREFIX}{}", template_id.trim())
}

/// If `binding` is an `item:` consumable slot, return the template id.
pub fn hotbar_consumable_template(binding: &str) -> Option<&str> {
    binding
        .strip_prefix(HOTBAR_ITEM_PREFIX)
        .map(str::trim)
        .filter(|id| !id.is_empty())
}

/// True when a hotbar binding string refers to a consumable (not an ability).
pub fn hotbar_binding_is_consumable(binding: &str) -> bool {
    hotbar_consumable_template(binding).is_some()
}

/// Spatial combat cue for map overlays (`plans/39`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CombatFxKind {
    MeleeArc,
    Cone,
    Sphere,
    Beam,
    HitMarker,
}

/// Outcome attached to a hit marker / struck entity.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum CombatFxHitOutcome {
    #[default]
    Hit,
    Blocked,
    Miss,
    Glance,
}

/// One entity struck (or targeted) by a combat FX resolve.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CombatFxHit {
    pub entity_id: EntityId,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    #[serde(default)]
    pub outcome: CombatFxHitOutcome,
}

/// Authoritative attack footprint / hit cue for clients to draw on the map.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CombatFx {
    pub id: u64,
    pub kind: CombatFxKind,
    pub ability_id: String,
    pub caster_id: EntityId,
    pub origin_x: f32,
    pub origin_y: f32,
    pub origin_z: f32,
    #[serde(default)]
    pub end_x: Option<f32>,
    #[serde(default)]
    pub end_y: Option<f32>,
    #[serde(default)]
    pub end_z: Option<f32>,
    #[serde(default)]
    pub yaw: Option<f32>,
    #[serde(default)]
    pub reach_m: Option<f32>,
    #[serde(default)]
    pub arc_deg: Option<f32>,
    #[serde(default)]
    pub radius_m: Option<f32>,
    #[serde(default)]
    pub hits: Vec<CombatFxHit>,
    /// Sim tick after which clients should drop this cue.
    pub until_tick: u64,
    #[serde(default)]
    pub damage_type: String,
}

/// Lingering ground hazard (boss `leave_hazard` puddle) visible until `expires_at_tick`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GroundHazardView {
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub radius_m: f32,
    pub expires_at_tick: u64,
    #[serde(default)]
    pub damage_type: String,
}

/// Hired worker automation mode on the wire.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerModeView {
    Companion,
    Defender,
    JobLoop,
    /// Deliberately parked — no route, no follow. The worker stands down
    /// (still draws wages) until the employer assigns a mode/route again.
    Idle,
}

/// Hired worker FSM state on the wire.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerStateView {
    Idle,
    Traveling,
    Working,
    Resting,
    Waiting,
    Strike,
    Dismissed,
}

/// Compact vitals for hired worker HUD rows and proximity overlay.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
pub struct WorkerVitalsSummary {
    pub health_pct: f32,
    pub stamina_pct: f32,
    #[serde(default)]
    pub mana_pct: f32,
    #[serde(default)]
    pub hunger_pct: f32,
    #[serde(default)]
    pub thirst_pct: f32,
}

/// High-level route shape — `harvest_loop` (legacy flat lists) or `ordered` (typed stop list).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum WorkerRouteKindView {
    #[default]
    HarvestLoop,
    Ordered,
}

/// Saved worker route for UI / route editor reload.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct WorkerRouteView {
    #[serde(default)]
    pub kind: WorkerRouteKindView,
    #[serde(default)]
    pub lodging_container_id: Option<String>,
    /// Legacy `harvest_loop` waypoint list.
    #[serde(default)]
    pub outbound_waypoints: Vec<WorkerRouteWaypointView>,
    /// Legacy `harvest_loop` node id list.
    #[serde(default)]
    pub harvest_nodes: Vec<String>,
    #[serde(default = "default_route_carry_ratio")]
    pub carry_return_ratio: f32,
    /// Ordered-route typed stops (`kind: ordered`).
    #[serde(default)]
    pub stops: Vec<WorkerRouteStopView>,
}

fn default_route_carry_ratio() -> f32 {
    0.90
}

fn default_true_view() -> bool {
    true
}

/// One withdraw line for a `WithdrawFrom` route stop view.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WorkerWithdrawItemView {
    pub template: String,
    /// Hold-up-to count (top-up each loop). Ignored when `all` is set.
    #[serde(default)]
    pub qty: u32,
    /// Take every stack of this template (carry-capped). Wins over `qty`.
    #[serde(default)]
    pub all: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct WorkerRouteWaypointView {
    pub x: f32,
    pub y: f32,
    pub z: f32,
}

/// One typed stop in an ordered worker route.
///
/// NOTE: this is the wire (postcard) view. Postcard does **not** support
/// internally-tagged enums (`#[serde(tag = ...)]` — it returns `WontImplement`
/// from `deserialize_any`), so this enum uses serde's default **external tagging**.
/// The sim-side `WorkerRouteStop` (`crates/sim/src/worker_job.rs`) is the YAML-facing
/// twin and keeps its `tag = "stop"` for human-authored job YAML; the two never share
/// a wire format.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerRouteStopView {
    Waypoint {
        x: f32,
        y: f32,
        #[serde(default)]
        z: f32,
    },
    HarvestNode {
        node_id: String,
    },
    DepositAt {
        container_id: String,
        #[serde(default)]
        filter: Option<Vec<String>>,
    },
    TradeWith {
        #[serde(default)]
        npc_id: Option<String>,
        template: String,
        #[serde(default = "default_true_view")]
        sell_all: bool,
    },
    /// List held stacks on a market hall at NPC price (dump queue).
    ListOnMarket {
        template: String,
        #[serde(default = "default_true_view")]
        list_all: bool,
        #[serde(default)]
        hall_id: Option<String>,
    },
    WithdrawFrom {
        container_id: String,
        items: Vec<WorkerWithdrawItemView>,
    },
    CraftAt {
        device: String,
        blueprint: String,
        #[serde(default)]
        qty: Option<u32>,
    },
    CultivatePlot {
        plot_id: uuid::Uuid,
    },
    PlantPlot {
        plot_id: uuid::Uuid,
        seed_template: String,
    },
    HarvestPlot {
        plot_id: uuid::Uuid,
    },
    RestIfNeeded,
    Wait {
        #[serde(default)]
        wait_ticks: u64,
    },
}

/// Copper ledger category (expense negative / income positive on the wire entry).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LedgerCategory {
    Workers,
    Hire,
    Train,
    ShopBuy,
    Taxes,
    WorkerSales,
    TraderSales,
    BankDeposit,
    BankWithdraw,
    BankTransferOut,
    BankTransferIn,
    BankTransferFee,
    StorageShipFee,
    /// Crown or private purchase of a property deed.
    PropertyBuy,
    /// Crown buyback or private sale of a property deed.
    PropertySell,
    /// Landlord share of harvest tax paid on an owned plot.
    TaxShare,
    /// Bank debit for a market-hall purchase (`plans/10-economy-and-markets.md`).
    MarketBuy,
    /// Bank credit for a market-hall sale (net of crown sales tax).
    MarketSell,
    Other,
}

impl LedgerCategory {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Workers => "workers",
            Self::Hire => "hire",
            Self::Train => "train",
            Self::ShopBuy => "shop_buy",
            Self::Taxes => "taxes",
            Self::WorkerSales => "worker_sales",
            Self::TraderSales => "trader_sales",
            Self::BankDeposit => "bank_deposit",
            Self::BankWithdraw => "bank_withdraw",
            Self::BankTransferOut => "bank_transfer_out",
            Self::BankTransferIn => "bank_transfer_in",
            Self::BankTransferFee => "bank_transfer_fee",
            Self::StorageShipFee => "storage_ship_fee",
            Self::PropertyBuy => "property_buy",
            Self::PropertySell => "property_sell",
            Self::TaxShare => "tax_share",
            Self::MarketBuy => "market_buy",
            Self::MarketSell => "market_sell",
            Self::Other => "other",
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LedgerEntryView {
    pub id: uuid::Uuid,
    pub game_day: u64,
    pub signed_copper: i64,
    pub category: LedgerCategory,
    #[serde(default)]
    pub label: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct LedgerPeriodTotals {
    /// Absolute copper spent by category key.
    #[serde(default)]
    pub expenses: std::collections::HashMap<String, u64>,
    /// Absolute copper earned by category key.
    #[serde(default)]
    pub income: std::collections::HashMap<String, u64>,
    pub expense_copper: u64,
    pub income_copper: u64,
    /// income − expenses (may be negative).
    pub cash_flow_copper: i64,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct PlayerLedgerView {
    pub current_game_day: u64,
    #[serde(default)]
    pub period_day: LedgerPeriodTotals,
    #[serde(default)]
    pub period_week: LedgerPeriodTotals,
    #[serde(default)]
    pub period_month: LedgerPeriodTotals,
    #[serde(default)]
    pub period_lifetime: LedgerPeriodTotals,
    #[serde(default)]
    pub recent: Vec<LedgerEntryView>,
    /// Copper on the character (inventory + worn bags).
    #[serde(default)]
    pub wealth_on_person_copper: u64,
    /// Copper in owned placed storage (chests, lodging — not bank ledger).
    #[serde(default)]
    pub wealth_in_storage_copper: u64,
    /// Copper in the secure bank ledger (`plans/08` §8).
    #[serde(default)]
    pub wealth_in_bank_copper: u64,
    /// `wealth_on_person_copper + wealth_in_storage_copper + wealth_in_bank_copper`.
    #[serde(default)]
    pub wealth_total_copper: u64,
    /// Sum of purchase-basis copper for deeds this character currently holds (asset book value).
    #[serde(default)]
    pub wealth_in_property_copper: u64,
    /// Liquid copper + property book value.
    #[serde(default)]
    pub wealth_net_worth_copper: u64,
    /// Deeds held (inventory, worn bags, town vault, owned chests) with book values.
    #[serde(default)]
    pub property_assets: Vec<PropertyAssetView>,
    /// Recent property sales near plots you hold (comps for a local market).
    #[serde(default)]
    pub property_market_nearby: Vec<PropertyMarketCompView>,
    /// Live payroll burn (cp per wage interval) for hired workers.
    #[serde(default)]
    pub live_expense_per_interval_copper: u64,
    /// Estimated copper from one full worker job loop (broker sell steps).
    #[serde(default)]
    pub live_income_route_est_per_loop_copper: u64,
    /// Recent average income (worker/trader sales) per wage interval.
    #[serde(default)]
    pub live_income_avg_per_interval_copper: u64,
    /// Number of wage intervals in the rolling average window.
    #[serde(default)]
    pub live_income_avg_window_intervals: u32,
    /// `live_income_avg_per_interval_copper − live_expense_per_interval_copper`.
    #[serde(default)]
    pub live_net_avg_per_interval_copper: i64,
}

/// One deed currently held by the character (ledger asset line).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertyAssetView {
    pub plot_id: Uuid,
    /// Friendly deed label (`{Owner}'s {Zone} deed @ (x, y) (N m²)`).
    pub label: String,
    pub zone_id: String,
    #[serde(default)]
    pub zone_label: Option<String>,
    pub area_m2: f32,
    /// Book value (what you paid / last private sale price).
    pub purchase_basis_copper: u64,
    pub upkeep_copper_per_day: u64,
}

/// A recorded property sale near the observer's holdings.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertyMarketCompView {
    pub day: u64,
    pub zone_id: String,
    #[serde(default)]
    pub zone_label: Option<String>,
    pub area_m2: f32,
    pub price_copper: u64,
    /// `price_copper / area_m2` (0 when area is tiny).
    pub price_per_m2_copper: u64,
    /// `crown_purchase` | `crown_buyback` | `player_trade`.
    pub kind: String,
    /// Distance from the nearest plot you hold (meters).
    pub distance_m: f32,
}

/// Gameplay analytics metric keys (extensible string on the wire via rename).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AnalyticsMetric {
    NpcKill,
    WildlifeKill,
    Harvest,
    QuestComplete,
    QuestAccept,
    QuestAbandon,
    PlayerDeath,
    Craft,
    WorkerHire,
    WorkerDismiss,
    WorkerTeach,
    NpcTalk,
    ShopBuy,
    ShopSell,
    PlaceContainer,
    PickupContainer,
    PickupDrop,
    ConsumableUse,
    AbilityUse,
    DistanceWalkedM,
    DoorUse,
    BuildingEnter,
}

impl AnalyticsMetric {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::NpcKill => "npc_kill",
            Self::WildlifeKill => "wildlife_kill",
            Self::Harvest => "harvest",
            Self::QuestComplete => "quest_complete",
            Self::QuestAccept => "quest_accept",
            Self::QuestAbandon => "quest_abandon",
            Self::PlayerDeath => "player_death",
            Self::Craft => "craft",
            Self::WorkerHire => "worker_hire",
            Self::WorkerDismiss => "worker_dismiss",
            Self::WorkerTeach => "worker_teach",
            Self::NpcTalk => "npc_talk",
            Self::ShopBuy => "shop_buy",
            Self::ShopSell => "shop_sell",
            Self::PlaceContainer => "place_container",
            Self::PickupContainer => "pickup_container",
            Self::PickupDrop => "pickup_drop",
            Self::ConsumableUse => "consumable_use",
            Self::AbilityUse => "ability_use",
            Self::DistanceWalkedM => "distance_walked_m",
            Self::DoorUse => "door_use",
            Self::BuildingEnter => "building_enter",
        }
    }

    pub fn from_str_key(s: &str) -> Option<Self> {
        Some(match s {
            "npc_kill" => Self::NpcKill,
            "wildlife_kill" => Self::WildlifeKill,
            "harvest" => Self::Harvest,
            "quest_complete" => Self::QuestComplete,
            "quest_accept" => Self::QuestAccept,
            "quest_abandon" => Self::QuestAbandon,
            "player_death" => Self::PlayerDeath,
            "craft" => Self::Craft,
            "worker_hire" => Self::WorkerHire,
            "worker_dismiss" => Self::WorkerDismiss,
            "worker_teach" => Self::WorkerTeach,
            "npc_talk" => Self::NpcTalk,
            "shop_buy" => Self::ShopBuy,
            "shop_sell" => Self::ShopSell,
            "place_container" => Self::PlaceContainer,
            "pickup_container" => Self::PickupContainer,
            "pickup_drop" => Self::PickupDrop,
            "consumable_use" => Self::ConsumableUse,
            "ability_use" => Self::AbilityUse,
            "distance_walked_m" => Self::DistanceWalkedM,
            "door_use" => Self::DoorUse,
            "building_enter" => Self::BuildingEnter,
            _ => return None,
        })
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CareerMetricRow {
    pub subject_id: String,
    pub amount: u64,
}

/// Personal analytics summary for the Character `i` Career tab.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct PlayerCareerView {
    pub current_game_day: u64,
    #[serde(default)]
    pub kills: Vec<CareerMetricRow>,
    #[serde(default)]
    pub harvests: Vec<CareerMetricRow>,
    pub quests_completed: u64,
    #[serde(default)]
    pub crafts: Vec<CareerMetricRow>,
    pub deaths: u64,
    pub npc_talks: u64,
    pub shop_buys: u64,
    pub shop_sells: u64,
    pub distance_m: u64,
    #[serde(default)]
    pub other: Vec<CareerMetricRow>,
}

/// Equipment currently worn by a player-hired worker.
///
/// Equipped items are separate from `HiredWorkerView::inventory`; the latter
/// contains only the worker's loose/root pack contents.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct WorkerEquipmentView {
    #[serde(default)]
    pub mainhand: Option<ItemStack>,
    #[serde(default)]
    pub offhand: Option<ItemStack>,
    #[serde(default)]
    pub worn: Vec<(BodySlot, ItemStack)>,
}

/// One player-hired worker visible in snapshot / tick deltas.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HiredWorkerView {
    pub instance_id: String,
    pub entity_id: EntityId,
    pub def_id: String,
    /// Display label (custom name when set, otherwise the NPC def label).
    pub label: String,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub mode: WorkerModeView,
    pub state: WorkerStateView,
    #[serde(default)]
    pub step_label: String,
    pub vitals: WorkerVitalsSummary,
    #[serde(default)]
    pub carry_pct: f32,
    #[serde(default)]
    pub last_error: Option<String>,
    pub wage_copper_per_interval: u32,
    /// Estimated wage this interval (base + loop effort, travel meters excluded).
    #[serde(default)]
    pub effective_wage_copper: u32,
    /// Meters walked toward the next wage debit.
    #[serde(default)]
    pub wage_meters_walked: f32,
    /// Placed camp bed / lodging container this worker uses for deposit and rest.
    #[serde(default)]
    pub lodging_container_id: Option<String>,
    /// High-level harvest route (when job_loop route is configured).
    #[serde(default)]
    pub route: Option<WorkerRouteView>,
    /// Index into `route.stops` for the worker's current job step (ordered routes).
    /// Maps expanded job steps (travel+deposit, etc.) back to the designer stop.
    #[serde(default)]
    pub route_stop_index: Option<u32>,
    /// Recipes this worker already knows (from hire `teaches` + employer teach).
    #[serde(default)]
    pub known_blueprint_ids: Vec<String>,
    /// Overall worker level (1+).
    #[serde(default = "default_worker_view_level")]
    pub level: u32,
    /// Cumulative worker XP.
    #[serde(default)]
    pub worker_xp: f64,
    /// Items the worker currently carries (employer-visible for give/take).
    #[serde(default)]
    pub inventory: Vec<ItemStack>,
    /// Items currently equipped by the worker, separate from `inventory`.
    #[serde(default)]
    pub equipment: WorkerEquipmentView,
    /// Short "what you should do" line when `last_error` is a player-actionable
    /// plan or logistics issue (missing chest, empty lodging, etc.).
    #[serde(default)]
    pub issue_hint: Option<String>,
}

fn default_worker_view_level() -> u32 {
    1
}

/// Server → client AOI-filtered entity updates for one sim tick.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TickDelta {
    pub tick: Tick,
    pub entities: Vec<EntityState>,
    #[serde(default)]
    pub resource_nodes: Vec<ResourceNodeView>,
    #[serde(default)]
    pub buildings: Vec<BuildingView>,
    #[serde(default)]
    pub doors: Vec<DoorView>,
    #[serde(default)]
    pub npcs: Vec<NpcView>,
    /// Observer inventory stacks (template → qty).
    #[serde(default)]
    pub inventory: Vec<ItemStack>,
    #[serde(default)]
    pub blueprints: Vec<BlueprintView>,
    /// Wall/roof material packs for the B plot-build menu.
    #[serde(default)]
    pub building_materials: Vec<BuildingMaterialView>,
    #[serde(default)]
    pub world_clock: WorldClock,
    #[serde(default)]
    pub ground_drops: Vec<GroundDropView>,
    #[serde(default)]
    pub placed_containers: Vec<PlacedContainerView>,
    #[serde(default)]
    pub combat: Option<CombatHud>,
    #[serde(default)]
    pub interior_map: Option<InteriorMapView>,
    #[serde(default)]
    pub quest_log: Vec<QuestLogEntry>,
    #[serde(default)]
    pub hired_workers: Vec<HiredWorkerView>,
    #[serde(default)]
    pub interactables: Vec<InteractableView>,
    #[serde(default)]
    pub ledger: Option<PlayerLedgerView>,
    #[serde(default)]
    pub career: Option<PlayerCareerView>,
    /// Active combat footprints / hit markers in observer AOI (`plans/39`).
    #[serde(default)]
    pub combat_fx: Vec<CombatFx>,
    /// Persistent ground hazards (boss puddles) in observer AOI.
    #[serde(default)]
    pub ground_hazards: Vec<GroundHazardView>,
    /// Claimed property plots near the observer (plan 40).
    #[serde(default)]
    pub property_plots: Vec<PropertyPlotView>,
    /// Runtime terrain cell overlays (cultivate dirt → tilled). Replaces prior overlays.
    #[serde(default)]
    pub terrain_overlays: Vec<TerrainZoneView>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GroundDropView {
    pub id: String,
    pub template_id: String,
    pub quantity: u32,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    /// Optional gfx tile id from the item template.
    #[serde(default)]
    pub tile_id: Option<String>,
    /// Item display name (e.g. "Cloth Pants") for hover/chat labels.
    #[serde(default)]
    pub display_name: Option<String>,
    /// Facing yaw in radians (0 = north) for sprite draw on the ground.
    #[serde(default)]
    pub yaw: f32,
    /// Pitch in radians (0 = upright).
    #[serde(default)]
    pub pitch: f32,
    /// Roll in radians (0 = upright; tilts in the view plane).
    #[serde(default)]
    pub roll: f32,
    /// Draw scale relative to one map cell (1.0 = cell size).
    #[serde(default = "default_draw_scale")]
    pub draw_scale: f32,
    /// Preserved unique instance id when the pile carries full slot state (`plans/18`).
    #[serde(default)]
    pub item_instance_id: Option<Uuid>,
    /// Instance props (custom name, deed metadata, etc.).
    #[serde(default)]
    pub props: std::collections::BTreeMap<String, String>,
    /// Enchant / status bindings on the unique instance.
    #[serde(default)]
    pub status_bindings: Vec<ItemStatusBinding>,
}

fn default_draw_scale() -> f32 {
    1.0
}

/// Full state on region enter or reconnect.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Snapshot {
    pub tick: Tick,
    pub chunk_rev: u64,
    /// Bumped when blueprints, catalog, segment, or settings reload.
    #[serde(default)]
    pub content_rev: u64,
    /// Stable publish revision from `assets/.content-publish.json` (for client asset sync).
    #[serde(default)]
    pub publish_rev: u64,
    pub entities: Vec<EntityState>,
    #[serde(default)]
    pub resource_nodes: Vec<ResourceNodeView>,
    /// Outdoor play AABB origin (meters). With width/height, defines the composed world.
    #[serde(default)]
    pub world_x0: f32,
    #[serde(default)]
    pub world_y0: f32,
    /// Segment play area width in meters (for HUD / beyond-zone).
    #[serde(default)]
    pub world_width_m: f32,
    #[serde(default)]
    pub world_height_m: f32,
    #[serde(default)]
    pub buildings: Vec<BuildingView>,
    #[serde(default)]
    pub doors: Vec<DoorView>,
    #[serde(default)]
    pub npcs: Vec<NpcView>,
    #[serde(default)]
    pub inventory: Vec<ItemStack>,
    #[serde(default)]
    pub blueprints: Vec<BlueprintView>,
    /// Wall/roof material packs for the B plot-build menu.
    #[serde(default)]
    pub building_materials: Vec<BuildingMaterialView>,
    #[serde(default)]
    pub world_clock: WorldClock,
    #[serde(default)]
    pub terrain_zones: Vec<TerrainZoneView>,
    #[serde(default)]
    pub z_platforms: Vec<ZPlatformView>,
    #[serde(default)]
    pub z_transitions: Vec<ZTransitionView>,
    #[serde(default)]
    pub ground_drops: Vec<GroundDropView>,
    #[serde(default)]
    pub placed_containers: Vec<PlacedContainerView>,
    #[serde(default)]
    pub combat: Option<CombatHud>,
    #[serde(default)]
    pub interior_map: Option<InteriorMapView>,
    #[serde(default)]
    pub quest_log: Vec<QuestLogEntry>,
    #[serde(default)]
    pub hired_workers: Vec<HiredWorkerView>,
    #[serde(default)]
    pub interactables: Vec<InteractableView>,
    #[serde(default)]
    pub ledger: Option<PlayerLedgerView>,
    #[serde(default)]
    pub career: Option<PlayerCareerView>,
    /// Active combat footprints / hit markers (`plans/39`).
    #[serde(default)]
    pub combat_fx: Vec<CombatFx>,
    /// Persistent ground hazards (boss puddles) in observer AOI.
    #[serde(default)]
    pub ground_hazards: Vec<GroundHazardView>,
    /// Authored crown property zones (claimable land) — plan 40.
    #[serde(default)]
    pub property_zones: Vec<PropertyZoneView>,
    /// Tax overlays (for claim cost premium preview).
    #[serde(default)]
    pub tax_zones: Vec<TaxZoneView>,
    /// Town / security / PvP boundaries (plan 43).
    #[serde(default)]
    pub boundary_zones: Vec<BoundaryZoneView>,
    /// Random-encounter rectangles (plan 54).
    #[serde(default)]
    pub encounter_zones: Vec<EncounterZoneView>,
    /// Growth / fertility overlays (plan 37 / farming).
    #[serde(default)]
    pub growth_zones: Vec<GrowthZoneView>,
    /// Climate / biome overlays (plan 38).
    #[serde(default)]
    pub biome_zones: Vec<BiomeZoneView>,
    /// Terrain kind move speed / impassable table for client pathfinding (from terrain-kinds.yaml).
    #[serde(default)]
    pub terrain_kind_nav: Vec<TerrainKindNavView>,
    /// Claimed property plots in this segment.
    #[serde(default)]
    pub property_plots: Vec<PropertyPlotView>,
    /// Server knobs needed for client claim quote preview.
    #[serde(default)]
    pub property_plot_settings: Option<PropertyPlotSettingsView>,
    /// Compact item catalog (labels + category) so pickers can resolve UUID
    /// template ids without relying on inventory-only hints.
    #[serde(default)]
    pub item_catalog: Vec<ItemCatalogEntryView>,
}

/// Compact catalog row for client pickers (not a full item def).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ItemCatalogEntryView {
    pub template_id: String,
    #[serde(default)]
    pub display_name: String,
    #[serde(default)]
    pub category: String,
    /// When set, this template is a farm seed for the named crop.
    #[serde(default)]
    pub seed_for: Option<String>,
}

impl ItemCatalogEntryView {
    pub fn is_harvest_node(&self) -> bool {
        self.category == "harvest_node"
    }

    /// World harvest-node templates cannot exist as deposit/inventory stacks.
    pub fn is_depositable_stack(&self) -> bool {
        !self.is_harvest_node()
    }

    pub fn is_farm_seed(&self) -> bool {
        self.seed_for
            .as_deref()
            .is_some_and(|s| !s.trim().is_empty())
            || self.category == "seed"
    }
}

/// Harvestable node visible to clients.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ResourceNodeView {
    pub id: String,
    pub label: String,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub item_template: String,
    #[serde(default = "default_node_state")]
    pub state: ResourceNodeState,
    /// When true, players cannot walk through this node while available/harvesting.
    #[serde(default = "default_blocking_view")]
    pub blocking: bool,
    /// Collision radius for pathfinding (meters).
    #[serde(default = "default_blocking_radius_view")]
    pub blocking_radius_m: f32,
    /// Decorative map placement — not harvestable; `blocking` is forced false on the wire.
    #[serde(default)]
    pub harvest_off: bool,
    /// Optional gfx tile id (`resource.oak_log`, …).
    #[serde(default)]
    pub tile_id: Option<String>,
    /// Facing yaw in radians (0 = north). From map placement.
    #[serde(default)]
    pub yaw: f32,
    /// Pitch in radians (0 = upright). From map placement.
    #[serde(default)]
    pub pitch: f32,
    /// Roll in radians (0 = upright). From map placement.
    #[serde(default)]
    pub roll: f32,
    /// Draw scale relative to one map cell (1.0 = cell size).
    #[serde(default = "default_draw_scale")]
    pub draw_scale: f32,
    /// Resolved gfx sprite mode for `tile_id` (server-computed).
    #[serde(default)]
    pub sprite_mode: Option<String>,
    /// Canonical presentation key (`available`, `harvesting`, `depleted`).
    #[serde(default)]
    pub presentation_state: Option<String>,
    /// Farm crop growth 0.0–1.0 while immature; `None` for other nodes and mature crops.
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub growth_progress: Option<f32>,
    /// Active harvest channel (sim ticks), for progress rings on the node.
    #[serde(default)]
    pub channel_start_tick: Option<Tick>,
    #[serde(default)]
    pub channel_end_tick: Option<Tick>,
    /// Possible loot templates from this node's harvest loot table (route deposit filters).
    #[serde(default)]
    pub harvest_drop_templates: Vec<String>,
}

fn default_blocking_radius_view() -> f32 {
    0.8
}

fn default_blocking_view() -> bool {
    true
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ResourceNodeState {
    Available,
    Harvesting,
    Cooldown,
}
fn default_node_state() -> ResourceNodeState {
    ResourceNodeState::Available
}

/// Live state of a placed world item spawn (plan 45).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ItemSpawnStateView {
    Spawned,
    PickedUp { respawn_at_tick: u64 },
    Consumed,
}

/// Authoritative view of a placed findable item (plan 45) for admin/overseer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ItemSpawnView {
    pub id: String,
    pub label: String,
    pub item_template: String,
    pub quantity: u32,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub respawn_ticks: u32,
    #[serde(default)]
    pub building_id: Option<String>,
    pub state: ItemSpawnStateView,
    /// Each character may pick this spawn once; the pile stays for others.
    #[serde(default)]
    pub once_per_character: bool,
    /// How many characters have already collected a once-per-character spawn.
    #[serde(default)]
    pub collected_count: u32,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ItemStatusBindingMode {
    OnHit,
    WhileEquipped,
}

impl Default for ItemStatusBindingMode {
    fn default() -> Self {
        Self::OnHit
    }
}

/// Per-instance status effect binding (unique gear grants / enchantments).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ItemStatusBinding {
    pub effect_id: String,
    #[serde(default)]
    pub mode: ItemStatusBindingMode,
    /// Grant template id, `"loot"`, later `"altar"`, etc.
    #[serde(default)]
    pub source: String,
    #[serde(default)]
    pub applied_at_tick: u64,
    /// `None` = permanent until overwritten / dispelled.
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub expires_at_tick: Option<u64>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ItemStack {
    pub template_id: String,
    pub quantity: u32,
    /// Stable instance id — preserved across checkpoint/sync when set.
    #[serde(default)]
    pub item_instance_id: Option<Uuid>,
    /// Per-instance metadata (stat rolls, soul-bind, lock ids, etc.).
    #[serde(default)]
    pub props: BTreeMap<String, String>,
    /// Instance-only status effects (template effects live on the item def).
    #[serde(default)]
    pub status_bindings: Vec<ItemStatusBinding>,
    /// Nested contents when this stack is a container instance.
    #[serde(default)]
    pub contents: Vec<ItemStack>,
    /// From item catalog when sent on wire (display only).
    #[serde(default)]
    pub display_name: Option<String>,
    /// From item catalog when sent on wire (`weapon`, `consumable`, …).
    #[serde(default)]
    pub category: Option<String>,
    /// Per-unit mass in kg from catalog (display / move UX).
    #[serde(default)]
    pub base_mass: Option<f32>,
    /// Per-unit volume from catalog (display / move UX).
    #[serde(default)]
    pub base_volume: Option<f32>,
    /// Container capacity when this stack is a container template.
    #[serde(default)]
    pub capacity_volume: Option<f32>,
    /// Whether the template stacks in inventory (from catalog).
    #[serde(default)]
    pub stackable: Option<bool>,
    /// Can be placed on the ground from inventory (from catalog).
    #[serde(default)]
    pub world_placeable: Option<bool>,
    /// Hired-worker lodging capacity when this template is placed (from catalog).
    #[serde(default)]
    pub worker_lodging_capacity: Option<u32>,
    /// Body slot this template equips into (from catalog; display / Equip UI).
    #[serde(default)]
    pub equip_slot: Option<BodySlot>,
    /// Template baseline armor rating (from catalog).
    #[serde(default)]
    pub armor_physical: Option<f32>,
    /// Template resists damage_type → value (from catalog).
    #[serde(default)]
    pub resists: Vec<(String, f32)>,
    /// Weapon hand occupancy when category is weapon (`1` or `2`).
    #[serde(default)]
    pub hand_slots: Option<u8>,
    /// Market-hall list eligibility from catalog (display / client pickers).
    #[serde(default)]
    pub listable: Option<bool>,
    /// Catalog NPC trade base (`base_value_copper`) for dump-queue payout hints.
    #[serde(default)]
    pub base_value_copper: Option<u32>,
}

impl ItemStack {
    pub fn simple(template_id: impl Into<String>, quantity: u32) -> Self {
        Self {
            template_id: template_id.into(),
            quantity,
            ..Default::default()
        }
    }
}

impl Default for ItemStack {
    fn default() -> Self {
        Self {
            template_id: String::new(),
            quantity: 0,
            item_instance_id: None,
            props: BTreeMap::new(),
            status_bindings: Vec::new(),
            contents: Vec::new(),
            display_name: None,
            category: None,
            base_mass: None,
            base_volume: None,
            capacity_volume: None,
            stackable: None,
            world_placeable: None,
            worker_lodging_capacity: None,
            equip_slot: None,
            armor_physical: None,
            resists: Vec::new(),
            hand_slots: None,
            listable: None,
            base_value_copper: None,
        }
    }
}

/// Carry encumbrance band (`plans/57`). HUD maps Light/Heavy/Orange/Over → green/yellow/orange/red.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum EncumbranceState {
    #[default]
    Light,
    Heavy,
    Orange,
    Over,
}

impl EncumbranceState {
    /// Player-facing band name (not a raw id).
    pub fn label(self) -> &'static str {
        match self {
            Self::Light => "Light",
            Self::Heavy => "Heavy",
            Self::Orange => "Overloaded",
            Self::Over => "Over",
        }
    }

    /// Sprint is forbidden in the red (Over) band.
    pub fn allows_sprint(self) -> bool {
        !matches!(self, Self::Over)
    }
}

/// Body region a wearable item occupies — at most one item equipped per slot.
/// Armor, cloak, jewelry, and carriers (`Back` backpack, `Waist` belt). Hands
/// (mainhand / offhand) are separate combat sockets — not `BodySlot`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BodySlot {
    Head,
    /// Chest / torso armor. Serde alias `body` for older YAML / saves.
    #[serde(alias = "body")]
    Chest,
    /// Gauntlets / bracers / sleeves. Serde alias `arms` for older YAML / saves.
    #[serde(alias = "arms")]
    Forearms,
    Legs,
    Feet,
    Cloak,
    Back,
    Waist,
    Earrings,
    Necklace,
    Eyeglasses,
    /// Explicit rename: plain `snake_case` would be `ring_left1`.
    #[serde(rename = "ring_left_1", alias = "ring_left1")]
    RingLeft1,
    #[serde(rename = "ring_left_2", alias = "ring_left2")]
    RingLeft2,
    #[serde(rename = "ring_right_1", alias = "ring_right1")]
    RingRight1,
    #[serde(rename = "ring_right_2", alias = "ring_right2")]
    RingRight2,
}

impl BodySlot {
    /// All worn slots in paperdoll / catalog order.
    pub const ALL: [BodySlot; 15] = [
        BodySlot::Head,
        BodySlot::Chest,
        BodySlot::Forearms,
        BodySlot::Legs,
        BodySlot::Feet,
        BodySlot::Cloak,
        BodySlot::Back,
        BodySlot::Waist,
        BodySlot::Earrings,
        BodySlot::Necklace,
        BodySlot::Eyeglasses,
        BodySlot::RingLeft1,
        BodySlot::RingLeft2,
        BodySlot::RingRight1,
        BodySlot::RingRight2,
    ];

    pub fn as_str(self) -> &'static str {
        match self {
            BodySlot::Head => "head",
            BodySlot::Chest => "chest",
            BodySlot::Forearms => "forearms",
            BodySlot::Legs => "legs",
            BodySlot::Feet => "feet",
            BodySlot::Cloak => "cloak",
            BodySlot::Back => "back",
            BodySlot::Waist => "waist",
            BodySlot::Earrings => "earrings",
            BodySlot::Necklace => "necklace",
            BodySlot::Eyeglasses => "eyeglasses",
            BodySlot::RingLeft1 => "ring_left_1",
            BodySlot::RingLeft2 => "ring_left_2",
            BodySlot::RingRight1 => "ring_right_1",
            BodySlot::RingRight2 => "ring_right_2",
        }
    }
}

/// Where an item lives for `MoveItem` / open-container UX.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum InventoryLocation {
    /// Loose on-person inventory (not inside a worn/placed container).
    Root,
    /// Inside a worn item (backpack contents, or a pouch clipped onto a worn belt).
    Worn { slot: BodySlot },
    /// Inside a world-placed container.
    Placed { container_id: String },
    /// Virtual key ring — only `container_key` items; zero carry mass; persists with combat profile.
    Keychain,
    /// Virtual whisper pouch — only `whisper_stone` items; zero carry mass.
    WhisperPouch,
}

/// AOI view of a placeable chest on the map.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PlacedContainerView {
    pub id: String,
    pub template_id: String,
    pub display_name: String,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub locked: bool,
    /// Observer can open (unlocked, or holds matching key).
    #[serde(default)]
    pub accessible: bool,
    #[serde(default)]
    pub owner_character_id: Option<Uuid>,
    /// Nested contents when `accessible` (empty when locked without key).
    #[serde(default)]
    pub contents: Vec<ItemStack>,
    /// Lock id for matching `container_key` props (`opens_lock_id`).
    #[serde(default)]
    pub lock_id: Option<String>,
    /// Internal storage capacity (liters) from item catalog.
    #[serde(default)]
    pub capacity_volume: Option<f32>,
    /// Container instance id (for MoveItem parent targeting).
    #[serde(default)]
    pub item_instance_id: Option<Uuid>,
    /// Optional gfx tile id from the item template.
    #[serde(default)]
    pub tile_id: Option<String>,
    /// Hired-worker slots when this is placed lodging (`category: lodging`).
    #[serde(default)]
    pub worker_lodging_capacity: Option<u32>,
    /// From item template — blocks movement and autopath when placed.
    #[serde(default)]
    pub blocking: bool,
    /// Collision radius (m) for pathfinding when `blocking`.
    #[serde(default)]
    pub blocking_radius_m: f32,
    /// Interior space when placed indoors (`None` = outdoors). Postcard always
    /// serializes optionals so decode stays aligned — bump `PROTOCOL_VERSION`.
    #[serde(default)]
    pub building_id: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BlueprintIngredientView {
    pub template_id: String,
    pub quantity: u32,
    /// Always serialize — `true` is not bool::default() so postcard keeps it; explicit for clarity.
    pub consumed: bool,
    /// Catalog display name for UI (never show bare template_id when this is set).
    #[serde(default)]
    pub display_name: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ToolRequirementView {
    pub item: String,
    /// Always serialize — postcard omits `false` by default, which breaks roundtrip without explicit value.
    pub consumed: bool,
    /// Catalog display name for UI.
    #[serde(default)]
    pub display_name: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SkillRequirementView {
    pub skill: String,
    pub level: u32,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BlueprintView {
    pub id: String,
    pub label: String,
    pub output: String,
    pub output_qty: u32,
    pub craft_ticks: u32,
    pub inputs: Vec<BlueprintIngredientView>,
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub station: Option<String>,
    #[serde(default)]
    pub category: Option<String>,
    #[serde(default)]
    pub required_tools: Vec<ToolRequirementView>,
    #[serde(default)]
    pub skill: Option<SkillRequirementView>,
    #[serde(default)]
    pub failure_chance: f32,
    /// Copper cost for the employer to teach this recipe to a hired worker.
    #[serde(default)]
    pub worker_train_copper: u64,
    /// Catalog display name for `output` (UI must prefer this over the raw template id).
    #[serde(default)]
    pub output_display_name: String,
    /// Derived craft dependency depth (1 = only raw inputs). Tools do not deepen this.
    #[serde(default)]
    pub craft_tier: u32,
}

/// Per-kind pathfinding params replicated so clients share server content speeds.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TerrainKindNavView {
    pub kind: TerrainKindView,
    #[serde(default = "default_move_speed_mult_one")]
    pub move_speed_mult: f32,
    #[serde(default)]
    pub impassable: bool,
}

fn default_move_speed_mult_one() -> f32 {
    1.0
}

/// Terrain overlay from segment YAML (`terrain_zones`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum TerrainKindView {
    #[default]
    Grass,
    Dirt,
    Tilled,
    Desert,
    Hill,
    Bog,
    Beach,
    ShallowWater,
    DeepWater,
    Trail,
    Road,
    Rock,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TerrainZoneView {
    pub id: String,
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
    #[serde(default)]
    pub kind: TerrainKindView,
    /// Ground elevation at this zone (m).
    #[serde(default)]
    pub elevation: f32,
    /// Optional map glyph override (single character); falls back to terrain kind catalog.
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub glyph: Option<String>,
    /// Optional color (`#RRGGBB` or ratatui name); falls back to kind / elevation tint.
    #[serde(default)]
    pub color: Option<String>,
    /// Optional gfx tile id (`terrain.grass`, …) — presentation only.
    #[serde(default)]
    pub tile_id: Option<String>,
    /// Overlap priority — higher wins (`segment.terrain_zones`).
    #[serde(default)]
    pub z_order: i32,
    /// In-progress till/plant channel on this cell (sim ticks).
    #[serde(default)]
    pub channel_start_tick: Option<Tick>,
    #[serde(default)]
    pub channel_end_tick: Option<Tick>,
}

/// Axis-aligned rect used by property / tax zone views.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ZoneRectView {
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
}

/// Crown property zone (claimable land) — plan 40.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertyZoneView {
    pub id: String,
    /// Designer label when present; clients prefer this over id.
    #[serde(default)]
    pub label: Option<String>,
    pub rects: Vec<ZoneRectView>,
    #[serde(default)]
    pub z_order: i32,
    pub crown_price_copper: u64,
    pub upkeep_copper_per_day: u64,
    #[serde(default)]
    pub max_area_m2: Option<f32>,
    #[serde(default)]
    pub owner_tax_discount_bps: u32,
}

/// Tax overlay for claim premium preview.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TaxZoneView {
    pub id: String,
    #[serde(default)]
    pub label: Option<String>,
    pub rects: Vec<ZoneRectView>,
    #[serde(default)]
    pub z_order: i32,
    pub rate_bps: u32,
    #[serde(default)]
    pub flat_copper: u64,
    /// Market-hall sales tax in basis points of sale total.
    #[serde(default)]
    pub market_sales_tax_bps: u32,
    /// Optional flat copper per market-hall purchase.
    #[serde(default)]
    pub market_sales_flat_copper: u32,
}

/// Town / security / PvP boundary overlay (plan 43).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BoundaryZoneView {
    pub id: String,
    #[serde(default)]
    pub label: Option<String>,
    pub rects: Vec<ZoneRectView>,
    #[serde(default)]
    pub z_order: i32,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub jurisdiction_id: Option<String>,
    #[serde(default = "default_true")]
    pub worker_logistics: bool,
    #[serde(default)]
    pub security_tier: String,
    #[serde(default)]
    pub pvp_mode: String,
    #[serde(default = "default_true")]
    pub crime_enabled: bool,
    #[serde(default)]
    pub guard_response: bool,
    /// When true, placeable props do not block movement inside this zone.
    #[serde(default)]
    pub pass_through_props: bool,
    /// `fov_los` (default) or `full_aoi`.
    #[serde(default)]
    pub presence_mode: String,
}

/// Random encounter overlay (plan 54).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EncounterZoneView {
    pub id: String,
    #[serde(default)]
    pub label: Option<String>,
    pub rects: Vec<ZoneRectView>,
    #[serde(default)]
    pub z_order: i32,
}

fn default_true() -> bool {
    true
}

/// Growth / fertility overlay — faster respawn & farm tuning (plan 37 / 40).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GrowthZoneView {
    pub id: String,
    #[serde(default)]
    pub label: Option<String>,
    pub rects: Vec<ZoneRectView>,
    #[serde(default)]
    pub z_order: i32,
    #[serde(default = "default_one_f32")]
    pub fertility: f32,
}

fn default_one_f32() -> f32 {
    1.0
}

/// Climate / biome overlay (plan 38).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BiomeZoneView {
    pub id: String,
    #[serde(default)]
    pub label: Option<String>,
    pub rects: Vec<ZoneRectView>,
    #[serde(default)]
    pub z_order: i32,
    pub biome_id: String,
}

/// Named tenant on a property plot (farm access + tax discount).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FarmGrantView {
    pub character_id: Uuid,
    /// Display name when known (AOI / online); empty if offline-only id.
    #[serde(default)]
    pub character_label: String,
    pub tax_discount_bps: u32,
}

/// Claimed plot visible to clients (plan 40).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertyPlotView {
    pub plot_id: Uuid,
    pub property_zone_id: String,
    #[serde(default)]
    pub zone_label: Option<String>,
    pub deed_instance_id: Uuid,
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
    pub upkeep_copper_per_day: u64,
    pub arrears_days: u32,
    /// Observer currently holds this plot's deed.
    #[serde(default)]
    pub is_mine: bool,
    /// Observer may cultivate/plant/harvest on this plot (deed, owner, public, or grant).
    #[serde(default)]
    pub may_farm: bool,
    /// Book value when known (purchase / last private sale).
    #[serde(default)]
    pub purchase_basis_copper: u64,
    #[serde(default)]
    pub farm_public: bool,
    #[serde(default)]
    pub public_tax_discount_bps: u32,
    #[serde(default)]
    pub farm_allow: Vec<FarmGrantView>,
    /// Owner character when known.
    #[serde(default)]
    pub owner_character_id: Option<Uuid>,
    #[serde(default)]
    pub owner_label: Option<String>,
    /// Player building on this plot, if any.
    #[serde(default)]
    pub building_id: Option<String>,
    /// Immutable short code derived from `plot_id` (e.g. `xyz1234a`).
    #[serde(default)]
    pub plot_code: String,
    /// Owner-chosen label (defaults to `plot_code`).
    #[serde(default)]
    pub label: String,
}

/// Subset of server settings for client-side claim quotes.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PropertyPlotSettingsView {
    pub min_plot_area_m2: f32,
    pub tax_premium_weight: f32,
    pub sellback_bps: u32,
}

/// Walkable platform at a fixed z (`segment.z_platforms`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ZPlatformView {
    pub id: String,
    pub z: f32,
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
}

/// Stairs / ramp linking two z bands (`segment.z_transitions`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ZTransitionView {
    pub id: String,
    pub z_from: f32,
    pub z_to: f32,
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BuildingView {
    pub id: String,
    pub label: String,
    pub x: f32,
    pub y: f32,
    pub width_m: f32,
    pub depth_m: f32,
    #[serde(default)]
    pub interior_blueprint: Option<String>,
    #[serde(default)]
    pub tags: Vec<String>,
    /// Boundary zones this market hall participates in (`plans/10`).
    #[serde(default)]
    pub market_boundary_zone_ids: Vec<String>,
    /// Escrow capacity when tagged `market`. None → server default.
    #[serde(default)]
    pub market_max_volume: Option<f32>,
    /// Wall art set id (`schemas/gfx-sprites.schema.json` `wall_set`). `None` → `classic_stone`
    /// (legacy `building.wall_h`/`wall_v`/`wall_corner`/`door_open`/`door_closed` sprites).
    #[serde(default)]
    pub wall_set: Option<String>,
    /// Roof art set id (forge `roof_set` output_stem). `None` → `classic_stone`.
    #[serde(default)]
    pub roof_set: Option<String>,
}

/// Default wall/roof set id when a building doesn't specify one — keeps existing
/// content rendering pixel-identical (`plans/47` Workstream C).
pub const DEFAULT_BUILDING_ART_SET: &str = "classic_stone";

impl BuildingView {
    pub fn effective_wall_set(&self) -> &str {
        self.wall_set
            .as_deref()
            .filter(|s| !s.is_empty())
            .unwrap_or(DEFAULT_BUILDING_ART_SET)
    }

    pub fn effective_roof_set(&self) -> &str {
        self.roof_set
            .as_deref()
            .filter(|s| !s.is_empty())
            .unwrap_or(DEFAULT_BUILDING_ART_SET)
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DoorView {
    pub id: String,
    pub building_id: String,
    pub x: f32,
    pub y: f32,
    #[serde(default)]
    pub open: bool,
    #[serde(default)]
    pub portal: Option<String>,
    /// Exterior door locked: player-house key lock, or map-building door hours closed.
    /// Clients draw the padlock badge when `locked && !open`.
    #[serde(default)]
    pub locked: bool,
    /// Observer can open/close/enter. False when key-locked or outside door hours.
    #[serde(default = "default_door_accessible")]
    pub accessible: bool,
    #[serde(default)]
    pub lock_id: Option<Uuid>,
}

fn default_door_accessible() -> bool {
    true
}

/// Client → server interior room layout (confirm edit).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteriorRoomEdit {
    pub id: String,
    pub label: String,
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteriorRoomDoorEdit {
    pub id: String,
    pub room_a: String,
    pub room_b: String,
    pub x: f32,
    pub y: f32,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteriorRoomView {
    pub id: String,
    pub label: String,
    pub floor: i32,
    pub x0: f32,
    pub y0: f32,
    pub x1: f32,
    pub y1: f32,
    #[serde(default)]
    pub floor_color: Option<String>,
    #[serde(default)]
    pub floor_glyph: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteriorDoorView {
    pub id: String,
    pub room_a: String,
    pub room_b: String,
    pub x: f32,
    pub y: f32,
    pub kind: String,
    #[serde(default)]
    pub x_a: Option<f32>,
    #[serde(default)]
    pub y_a: Option<f32>,
    #[serde(default)]
    pub x_b: Option<f32>,
    #[serde(default)]
    pub y_b: Option<f32>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteriorMapView {
    pub building_id: String,
    pub blueprint_id: String,
    pub background_color: String,
    #[serde(default)]
    pub default_floor_color: Option<String>,
    #[serde(default = "default_floor_height_view")]
    pub floor_height_m: f32,
    /// Walkable platforms per floor (interior z-bands).
    #[serde(default)]
    pub z_platforms: Vec<ZPlatformView>,
    #[serde(default)]
    pub z_transitions: Vec<ZTransitionView>,
    pub rooms: Vec<InteriorRoomView>,
    #[serde(default)]
    pub room_doors: Vec<InteriorDoorView>,
}

fn default_floor_height_view() -> f32 {
    3.0
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NpcView {
    pub id: String,
    pub label: String,
    pub role: String,
    pub x: f32,
    pub y: f32,
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub building_id: Option<String>,
    /// Authoritative sim entity for wildlife / combat targets.
    #[serde(default)]
    pub entity_id: Option<EntityId>,
    #[serde(default)]
    pub life_state: Option<LifeState>,
    #[serde(default)]
    pub hp_pct: Option<f32>,
    /// True when this NPC has buy/sell/teach offers (`npc_has_market`).
    #[serde(default)]
    pub can_trade: bool,
    /// Exact item template IDs this NPC buys, for worker-route sell pickers.
    #[serde(default)]
    pub buy_templates: Vec<String>,
    /// Gfx sprite sheet id (`assets/gfx/sprites/`). Client falls back to `npc.{id}` / `npc.{role}`.
    #[serde(default)]
    pub tile_id: Option<String>,
    /// Wildlife FSM state (`idle`, `chase`, `combat`, …) when behavior-driven (debug).
    #[serde(default)]
    pub behavior_state: Option<String>,
    /// Canonical gfx presentation key (`combat`, `pursue`, `walking`, `talking`, …).
    #[serde(default)]
    pub presentation_state: Option<String>,
    /// Resolved gfx sprite mode for `tile_id` (server-computed).
    #[serde(default)]
    pub sprite_mode: Option<String>,
    /// Paperdoll skin id (`assets/paperdoll/skins/`). Client prefers this over `tile_id` when baked.
    #[serde(default)]
    pub paperdoll_ref: Option<String>,
    /// World draw size in map cells (from paperdoll skin `draw_scale`; 1.0 = one cell).
    #[serde(default = "default_draw_scale")]
    pub draw_scale: f32,
    /// Authoritative body yaw (radians) for wildlife LoS debug (F7).
    #[serde(default)]
    pub yaw: Option<f32>,
    /// Active visual acquire cone (degrees); 360 when engaged.
    #[serde(default)]
    pub perception_fov_deg: Option<f32>,
    /// Sight radius used for acquire/tracking (meters).
    #[serde(default)]
    pub perception_sight_m: Option<f32>,
    /// Hearing radius from behavior (meters); omitted when deaf.
    #[serde(default)]
    pub perception_hear_m: Option<f32>,
    /// Per-observer quest verbs for this NPC (offer / talk / give). Empty for wildlife.
    #[serde(default)]
    pub quest_verbs: Vec<NpcQuestVerb>,
}

/// Quest-tied NPC menu verb. `kind` is `offer`, `talk`, or `give`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct NpcQuestVerb {
    pub quest_id: String,
    /// Player-facing verb (quest title or authored `talk_verb`).
    pub label: String,
    pub kind: String,
}

impl NpcQuestVerb {
    pub const KIND_OFFER: &'static str = "offer";
    pub const KIND_TALK: &'static str = "talk";
    pub const KIND_GIVE: &'static str = "give";
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct UseResult {
    pub template_id: String,
    pub hunger_restored: f32,
    pub thirst_restored: f32,
    #[serde(default)]
    pub health_restored: f32,
    #[serde(default)]
    pub mana_restored: f32,
    #[serde(default)]
    pub cleared_dot_ids: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CraftResult {
    pub blueprint_id: String,
    pub outputs: Vec<ItemStack>,
    pub consumed: Vec<ItemStack>,
    /// 1-based index within the submitted batch (1 when not batching).
    #[serde(default = "default_one")]
    pub batch_index: u32,
    /// Total crafts requested in this batch (1 when not batching).
    #[serde(default = "default_one")]
    pub batch_total: u32,
}

fn default_one() -> u32 {
    1
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DeathNotice {
    pub entity_id: EntityId,
    pub respawn_x: f32,
    pub respawn_y: f32,
    pub message: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteractionNotice {
    pub target_id: String,
    pub message: String,
    #[serde(default)]
    pub coins_delta: i32,
    #[serde(default)]
    pub inventory_delta: Vec<ItemStack>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NpcTalkTrustFlag {
    Stranger,
    Acquainted,
    Trusted,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NpcTalkDepth {
    #[default]
    Full,
    Brief,
    Unavailable,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NpcTalkOpened {
    pub npc_id: String,
    pub npc_label: String,
    pub greeting: String,
    pub trust_flag: NpcTalkTrustFlag,
    #[serde(default)]
    pub talk_depth: NpcTalkDepth,
    #[serde(default = "default_true")]
    pub trade_allowed: bool,
    /// Keyword/topic hints for deterministic chat (e.g. "Trade", "Goblins").
    #[serde(default)]
    pub suggested_topics: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NpcTalkPending {
    pub npc_id: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NpcTalkReply {
    pub npc_id: String,
    pub line: String,
    pub trust_flag: NpcTalkTrustFlag,
    #[serde(default)]
    pub wind_down: bool,
    #[serde(default)]
    pub trade_disabled: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NpcTalkClosed {
    pub npc_id: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NpcTalkError {
    pub npc_id: String,
    pub reason: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum QuestStatusView {
    Available,
    Active,
    Completed,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestObjectiveProgress {
    pub label: String,
    pub current: u32,
    pub required: u32,
    pub done: bool,
    /// `talk_npc` / `kill_npc` / `harvest_item` / `give_item` / `interact` /
    /// `craft` / `buy_item` / `sell_item` / `enter_building` / `use_item` /
    /// `pickup_item` / `learn_blueprint`.
    #[serde(default)]
    pub kind: String,
    #[serde(default)]
    pub npc_ref: Option<String>,
    #[serde(default)]
    pub item_template: Option<String>,
    #[serde(default)]
    pub blueprint_id: Option<String>,
    #[serde(default)]
    pub building_id: Option<String>,
}

/// One item granted by a quest step or final completion reward.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct QuestRewardItemView {
    pub template_id: String,
    /// Friendly catalog name for HUD / TUI (never show raw template id alone).
    #[serde(default)]
    pub display_name: String,
    pub quantity: u32,
}

/// Coins + items granted when a step (or the quest) completes.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub struct QuestRewardView {
    #[serde(default)]
    pub coins: u32,
    #[serde(default)]
    pub items: Vec<QuestRewardItemView>,
}

impl QuestRewardView {
    pub fn is_empty(&self) -> bool {
        self.coins == 0 && self.items.is_empty()
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum QuestStepStatusView {
    #[default]
    Pending,
    Current,
    Done,
}

/// Authored step summary for quest log / journal UI.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestStepView {
    pub id: String,
    pub title: String,
    #[serde(default)]
    pub status: QuestStepStatusView,
    #[serde(default)]
    pub reward: QuestRewardView,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestLogEntry {
    pub quest_id: String,
    pub title: String,
    pub description: String,
    pub status: QuestStatusView,
    #[serde(default)]
    pub current_step_id: Option<String>,
    #[serde(default)]
    pub current_step_title: String,
    #[serde(default)]
    pub current_step_index: u32,
    #[serde(default)]
    pub objectives: Vec<QuestObjectiveProgress>,
    /// Reward granted when the current step completes (active quests).
    #[serde(default)]
    pub current_step_reward: QuestRewardView,
    /// Reward on the final step (quest completion prize).
    #[serde(default)]
    pub completion_reward: QuestRewardView,
    /// Full step list with per-step rewards for the journal.
    #[serde(default)]
    pub steps: Vec<QuestStepView>,
    #[serde(default)]
    pub is_tracked: bool,
    #[serde(default)]
    pub can_withdraw: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InteractableView {
    pub id: String,
    pub kind: String,
    pub label: String,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    #[serde(default)]
    pub board_id: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestOffer {
    pub quest_id: String,
    pub title: String,
    pub description: String,
    #[serde(default)]
    pub step_count: u32,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestCatalogEntry {
    pub quest_id: String,
    pub title: String,
    pub description: String,
    pub step_count: u32,
    #[serde(default)]
    pub board_ids: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestCatalogUpdated {
    pub revision: u64,
    pub game_day: String,
    #[serde(default)]
    pub accepted: Vec<QuestCatalogEntry>,
    #[serde(default)]
    pub retired: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuestNotice {
    pub quest_id: String,
    pub title: String,
    pub message: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ShopOfferKind {
    Item,
    Blueprint,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ShopOffer {
    pub offer_id: String,
    pub kind: ShopOfferKind,
    pub label: String,
    #[serde(default)]
    pub template_id: Option<String>,
    #[serde(default)]
    pub blueprint_id: Option<String>,
    pub price_copper: u32,
    #[serde(default)]
    pub affordable: bool,
    #[serde(default)]
    pub already_owned: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ShopBuyLine {
    pub template_id: String,
    pub label: String,
    pub quantity: u32,
    pub price_copper: u32,
}

/// Bank teller interaction panel (`plans/08` §8).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BankPanel {
    pub npc_id: String,
    pub npc_label: String,
    pub bank_balance_copper: u64,
    pub on_person_copper: u64,
    /// Copper still clearing to other accounts (debited, not yet credited).
    #[serde(default)]
    pub pending_outgoing_copper: u64,
    #[serde(default)]
    pub transfer_fee_bps: u32,
    #[serde(default)]
    pub transfer_clear_ticks: u64,
}

/// Town storage manager panel (`plans/08` §7).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StoragePanel {
    pub npc_id: String,
    pub npc_label: String,
    pub building_id: String,
    pub building_label: String,
    pub used_volume: f32,
    pub max_volume: f32,
    #[serde(default)]
    pub contents: Vec<ItemStack>,
    /// Other storage buildings that can receive a ship (id, label, distance_m, fee_copper, travel_ticks).
    #[serde(default)]
    pub ship_destinations: Vec<StorageShipDest>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StorageShipDest {
    pub building_id: String,
    pub label: String,
    pub distance_m: f32,
    pub fee_copper: u64,
    pub travel_ticks: u64,
}

/// Source or destination for market-hall goods movement
/// (`plans/10-economy-and-markets.md` §4.3/§4.4).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum GoodsLocation {
    /// On-person inventory (root, non-nested).
    Person,
    /// A town storage vault at a building whose jurisdiction intersects the
    /// listing hall's `market_boundary_zone_ids`.
    TownStorage { building_id: String },
}

/// One escrowed market-hall listing, as seen from a browsing hall
/// (`plans/10-economy-and-markets.md` §4.2).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MarketListingView {
    pub listing_id: Uuid,
    pub seller_character_id: Uuid,
    /// Seller display name (`prefer-labels-over-ids`).
    pub seller_label: String,
    pub hall_building_id: String,
    pub hall_label: String,
    pub template_id: String,
    pub display_name: String,
    /// Item catalog category (`resource`, `weapon`, …) for client filters.
    #[serde(default)]
    pub category: String,
    pub quantity: u32,
    pub unit_price_copper: u64,
    /// Total for the full remaining quantity (`quantity * unit_price_copper`).
    pub line_total_copper: u64,
    /// Dump-queue listing — players cannot buy (`plans/53`).
    #[serde(default)]
    pub npc_price: bool,
    /// Estimated net copper per unit for NPC-price rows (default buyer rates).
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub npc_dump_unit_copper: Option<u32>,
    /// True when the viewer is the seller — reprice/delist allowed.
    pub mine: bool,
}

/// Town storage vault eligible as a list/buy/delist goods source for a market hall.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MarketListVault {
    pub building_id: String,
    /// Designer label (`prefer-labels-over-ids`).
    pub building_label: String,
    #[serde(default)]
    pub contents: Vec<ItemStack>,
}

/// Market hall clerk panel — browse (zone-linked halls), list / reprice / delist,
/// buy confirm (`plans/10-economy-and-markets.md` §4, §10).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MarketPanel {
    pub npc_id: String,
    pub npc_label: String,
    pub building_id: String,
    pub building_label: String,
    /// Escrow volume used at *this* hall only (cap is per-hall, `market_max_volume`).
    pub used_volume: f32,
    pub max_volume: f32,
    /// Listings at this hall plus any zone-linked halls (`market_boundary_zone_ids`
    /// intersection) — the shared browse book (§4.2).
    #[serde(default)]
    pub listings: Vec<MarketListingView>,
    /// Crown sales tax at the tax zone covering this hall (§6).
    #[serde(default)]
    pub tax_bps: u32,
    #[serde(default)]
    pub tax_flat_copper: u32,
    /// Zone-eligible town storage vaults the caller can list from (§4.3).
    #[serde(default)]
    pub list_vaults: Vec<MarketListVault>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ShopCatalog {
    pub npc_id: String,
    pub npc_label: String,
    #[serde(default)]
    pub sells: Vec<ShopOffer>,
    #[serde(default)]
    pub buys: Vec<ShopBuyLine>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HarvestResult {
    pub node_id: String,
    /// Stack quantity granted (not one-node-one-instance).
    pub quantity: u32,
    pub item_template: String,
    /// Optional DB row id when persisted to control plane.
    /// Postcard always serializes optional fields (no `skip_serializing_if`) so decode stays aligned.
    #[serde(default)]
    pub item_instance_id: Option<Uuid>,
}

/// Every on-wire payload is wrapped for versioning and codec uniformity.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Envelope<T> {
    pub protocol_version: u16,
    pub payload: T,
}

impl<T> Envelope<T> {
    pub fn new(payload: T) -> Self {
        Self {
            protocol_version: crate::PROTOCOL_VERSION,
            payload,
        }
    }
}

/// Session handshake after transport connect.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Hello {
    pub client_name: String,
    pub protocol_version: u16,
    #[serde(default)]
    pub auth: AuthCredential,
    /// Required for session auth; embedded in `ApiToken` variant otherwise.
    #[serde(default)]
    pub character_id: Option<Uuid>,
}

/// How the client authenticates to the game gateway.
/// Uses default serde enum encoding (postcard-compatible; not internally tagged).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AuthCredential {
    DevLocal,
    Session { token: String },
    ApiToken { token: String, character_id: Uuid },
}

impl Default for AuthCredential {
    fn default() -> Self {
        Self::DevLocal
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Welcome {
    pub session_id: SessionId,
    pub entity_id: EntityId,
    pub snapshot: Snapshot,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ServerMessage {
    Welcome(Welcome),
    /// Static world layers refreshed (blueprints, catalog, map, terrain) — no client restart.
    ContentUpdated(Snapshot),
    Tick(TickDelta),
    IntentAck {
        entity_id: EntityId,
        seq: Seq,
        tick: Tick,
    },
    Chat(ChatMessage),
    HarvestResult(HarvestResult),
    UseResult(UseResult),
    CraftResult(CraftResult),
    Death(DeathNotice),
    Interaction(InteractionNotice),
    ShopOpened(ShopCatalog),
    NpcTalkOpened(NpcTalkOpened),
    NpcTalkPending(NpcTalkPending),
    NpcTalkReply(NpcTalkReply),
    NpcTalkClosed(NpcTalkClosed),
    NpcTalkError(NpcTalkError),
    QuestOffer(QuestOffer),
    QuestAccepted(QuestNotice),
    QuestWithdrawn(QuestNotice),
    QuestStepCompleted(QuestNotice),
    QuestCompleted(QuestNotice),
    QuestCatalogUpdated(QuestCatalogUpdated),
    /// Bank teller panel opened (`plans/08` §8).
    BankOpened(BankPanel),
    /// Town storage manager panel opened (`plans/08` §7).
    StorageOpened(StoragePanel),
    /// Market hall clerk panel opened or refreshed (`plans/10-economy-and-markets.md`).
    MarketOpened(MarketPanel),
    /// Player-to-player trade window opened or refreshed.
    TradeOpened(TradePanel),
    /// Trade ended (cancel, complete, or peer left range).
    TradeClosed {
        reason: String,
    },
    /// Hello accepted but play refused (character already online, etc.).
    /// Sent instead of Welcome; TCP closes afterward.
    ConnectRejected {
        reason: String,
    },
}

/// Live player-to-player trade escrow view (both sides see the same presented buckets).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TradePanel {
    pub peer_entity_id: EntityId,
    pub peer_name: String,
    pub my_presented: Vec<ItemStack>,
    pub their_presented: Vec<ItemStack>,
    pub i_ready: bool,
    pub they_ready: bool,
    /// Predicted carry mass after accepting their presented items (and losing mine).
    pub my_mass_after: f32,
    pub my_mass_max: f32,
    pub my_encumbrance_after: EncumbranceState,
    /// True when completing would put the local player Over.
    pub overburden_warning: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ClientMessage {
    Hello(Hello),
    Intent(Intent),
    Disconnect,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn pristine_vitals_state_yields_full_pools() {
        let attrs = PrimaryAttributes::default();
        let vitals = StoredVitalsState::default().apply_to(attrs);
        assert!(vitals.health > 0.0);
        assert_eq!(vitals.health, vitals.health_max);
        assert!((vitals.mana_max - 61.0).abs() < 0.01);
    }

    #[test]
    fn humanize_snake_id_title_cases_parts() {
        assert_eq!(humanize_snake_id("heal_touch"), "Heal Touch");
        assert_eq!(humanize_snake_id("fireball"), "Fireball");
        assert_eq!(humanize_snake_id("cone_frost"), "Cone Frost");
    }

    #[test]
    fn saved_vitals_scale_when_pool_max_increases() {
        let mut attrs = PrimaryAttributes::default();
        attrs.intelligence = 140;
        attrs.wisdom = 140;
        let saved = StoredVitalsState {
            health: 100.0,
            mana: 14.0,
            stamina: 100.0,
            ..StoredVitalsState::default()
        };
        let vitals = saved.apply_to(attrs);
        assert!(vitals.mana_max > 55.0);
        assert!(
            (vitals.mana - vitals.mana_max).abs() < 0.01,
            "full legacy mana bar migrates to full new bar"
        );
    }

    #[test]
    fn empty_vitals_state_is_pristine() {
        let pristine = StoredVitalsState {
            health: 0.0,
            mana: 0.0,
            stamina: 0.0,
            hunger: 0.0,
            thirst: 0.0,
            coins: 0,
            deaths: 0,
            life_state: LifeState::Alive,
            winded: false,
        };
        assert!(pristine.is_pristine());
        let vitals = pristine.apply_to(PrimaryAttributes::default());
        assert!(vitals.health > 0.0);
    }

    #[test]
    fn stored_vitals_roundtrip_preserves_partial_pools() {
        let attrs = PrimaryAttributes::default();
        let mut live = PlayerVitals::from_attributes(attrs);
        live.health = 25.0;
        live.hunger = 77.0;
        live.deaths = 2;
        live.winded = true;
        let stored = StoredVitalsState::from_live(&live);
        let restored = stored.apply_to(attrs);
        assert!(
            (restored.health - 25.0).abs() < 0.01,
            "partial HP below cap stays absolute"
        );
        assert_eq!(restored.hunger, 77.0);
        assert_eq!(restored.deaths, 2);
        assert!(restored.winded);
    }

    #[test]
    fn skill_tiers_start_at_zero() {
        let skill = SkillProgress::default();
        assert_eq!(skill.level, 0);
        assert_eq!(skill.display_tier(), 0);
        let trained = SkillProgress {
            level: 250,
            last_trained_tick: 1,
        };
        assert_eq!(trained.display_tier(), 2);
    }

    #[test]
    fn quest_server_messages_roundtrip_json() {
        use crate::codec::{Codec, PostcardCodec};

        let offer = ServerMessage::QuestOffer(QuestOffer {
            quest_id: "ada_goblin_hunt".into(),
            title: "Goblin Trouble".into(),
            description: "Help Ada".into(),
            step_count: 3,
        });
        let notice = ServerMessage::QuestAccepted(QuestNotice {
            quest_id: "ada_goblin_hunt".into(),
            title: "Goblin Trouble".into(),
            message: "Quest accepted".into(),
        });
        for msg in [offer, notice] {
            let bytes = PostcardCodec.encode(&msg).unwrap();
            let decoded: ServerMessage = PostcardCodec.decode(&bytes).unwrap();
            assert_eq!(decoded, msg);
        }
    }

    #[test]
    fn hotbar_consumable_binding_roundtrips() {
        let binding = hotbar_consumable_binding("vegetable_soup");
        assert_eq!(binding, "item:vegetable_soup");
        assert!(hotbar_binding_is_consumable(&binding));
        assert_eq!(
            hotbar_consumable_template(&binding),
            Some("vegetable_soup")
        );
        assert!(!hotbar_binding_is_consumable("fireball"));
        assert_eq!(hotbar_consumable_template("fireball"), None);
    }
}