backend/easter_eggs/registry.py

# backend/easter_eggs/registry.py
# PURPOSE: Every Iron Man / Tony Stark Easter Egg in JARVIS OS.
# CAUSAL CHAIN REQUIREMENT: Every Easter Egg here must have:
#   1. A real trigger (input phrase, key sequence, or UI action)
#   2. A real backend handler that returns a real response
#   3. A real frontend component that renders the response
# An Easter Egg that returns a stub is Crime 10.

from dataclasses import dataclass
from typing import Callable, Optional

@dataclass
class EasterEgg:
    id: str
    trigger_phrases: list[str]    # exact or fuzzy-matched user input phrases
    key_sequence: Optional[str]   # e.g. "up up down down left right left right b a"
    ui_trigger: Optional[str]     # e.g. "triple_click_arc_reactor"
    handler: Callable             # async function that returns the response
    response_type: str            # "voice_and_text" | "ui_takeover" | "voice_only" | "text_only"
    personality: str              # "jarvis" | "friday" | "both"
    discoverable: bool            # if True, shown in Secret Lab Easter Egg log after triggered

EASTER_EGG_REGISTRY: list[EasterEgg] = []  # populated by decorators below