src/case_zero/api/hints.py

"""Spoiler-safe contextual hints (Det. Hale). Server-side and case-aware, but they never
name the killer, motive, or key-evidence chain - only the screen and the player's visible
progress shape the guidance.
"""

from __future__ import annotations

_BASE = {
    "briefing": "Read the file before you read people. Note the time of death - everything "
    "turns on who could be where, and when.",
    "story": "Don't look for the killer yet. The story tells you who was in the building and "
    "why; the lies come when you start asking questions.",
    "board": "Pick a suspect on the right and interrogate. Drag the exhibits as you think, "
    "and examine anything that doesn't sit right.",
    "evidence": "Examine each exhibit, then pin the ones that contradict a statement.",
    "timeline": "Find the two events that fight each other. Where a statement collides with a "
    "fact, an alibi falls apart.",
    "flashback": "Where an account and the evidence diverge in oxblood is where the lie lives.",
    "notes": "Line up motive against opportunity. Who could be where the evidence says, when "
    "it says - and who had the most to lose?",
    "accuse": "Don't guess. Means, then motive, then attach the evidence chain that proves it.",
}


def hint_for(screen: str, suspicion: dict[str, int]) -> str:
    if screen == "interro":
        hot = any(v >= 65 for v in suspicion.values())
        if hot:
            return (
                "Their composure is cracking - press the contradiction now and don't let them "
                "retreat to their alibi."
            )
        return (
            "Get their story on record with the soft questions, then present the exhibit that "
            "contradicts it and watch their composure move."
        )
    return _BASE.get(screen, "Take the case, detective. Start with the file, then the people.")