Initial commit — Omniscient Reader Scenario Simulator

.gitattributes

@@ -0,0 +1,2 @@
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.env
+.modal.toml
+modal/
+*.gguf
+*.log
+.DS_Store
+Thumbs.db
+*.docx
+browser_test.js
+run_test.py
+test_groq.py
+test_integration.py
+Video Project 13.mp4

README.md

@@ -0,0 +1,113 @@
+---
+title: "Omniscient Reader — Scenario Simulator"
+emoji: 📖
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: "6.18.0"
+app_file: app.py
+pinned: true
+license: mit
+tags:
+  - game
+  - ai
+  - interactive-fiction
+  - omniscient-reader
+  - build-small
+  - thousand-token-wood
+  - best-use-of-modal
+  - custom-ui
+  - llama-cpp
+short_description: "Play as Kim Dokja. The Dokkaebi knows you know everything."
+---
+
+# Omniscient Reader — Scenario Simulator
+
+> *The AI isn't a narrator — it's the antagonist.*
+
+An AI-powered scenario simulator based on **Omniscient Reader's Viewpoint (ORV)**. You play as Kim Dokja — a man who has read the apocalypse novel 3,149 times. The Dokkaebi (AI) knows you know everything — and has been redesigning reality specifically to break your meta-knowledge.
+
+Built for **Build Small Hackathon 2026** — Track 2: Thousand Token Wood 🍄
+
+---
+
+## How to Play
+
+1. **Click "Begin the Scenario"** to start
+2. **Type your actions freely** — or pick from the 3 AI-generated suggestions
+3. **Choose your Stance** (Neutral / Aggressive / Deceptive / Empathetic / Observant)
+4. **The Dokkaebi evaluates your intent** — not just your actions
+5. **If you use novel knowledge, reality fights back** — silently, without warning
+6. **Constellations watch and react** — your cosmic audience judges everything
+7. **Push meta-exposure to 100%** — and trigger "The Reader Has Been Noticed"
+
+---
+
+## Architecture
+
+**Dual-Model System** (total: 22B parameters — under 32B hackathon cap ✅)
+
+| Backend | Model | Size | Usage |
+|---------|-------|------|-------|
+| **Groq** | Llama 3.1 8B Instant | 8B | Every gameplay turn (~2s response) |
+| **Modal** | Qwen 2.5 14B (llama.cpp) | 14B | Cinematic moments — scenario intros, end-game |
+
+The Modal deployment runs on an A10G GPU with a persistent volume cache, so the model stays warm and cold-starts only happen after extended inactivity.
+
+---
+
+## Features
+
+- 🎭 **AI Antagonist** — The Dokkaebi detects meta-gaming and subverts reality
+- ⭐ **Star Stream Chat** — Live constellation reactions to every action
+- 📊 **Dynamic Meters** — Meta Exposure, Probability Stability, Entertainment
+- 🏆 **Emergent Titles** — Earned through behavior, never chosen from menus
+- 🎬 **Signature Moments** — Screen glitch effects when reality breaks
+- ⚔️ **Stances** — Choose your approach (Aggressive, Deceptive, Empathetic, Observant)
+- 🌩️ **Probability Storms** — Random debuffs when stability drops below 50%
+- 🔄 **Phase Shifts** — Combat/Exploration/Safe Zone phases change the UI and rules
+
+---
+
+## Merit Badges
+
+- 🎨 **Off-Brand** — Fully custom UI: 14KB CSS + 21KB animations + 35KB JS. Not a single default Gradio element.
+- 🦙 **Llama Champion** — Cinematic moments powered by llama.cpp (Qwen 2.5 14B GGUF on Modal A10G)
+
+---
+
+## Setup Instructions
+
+1. Clone the repository
+2. Create a virtual environment and install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. Set your API keys (as environment variables or in a `.env` file):
+   ```bash
+   export GROQ_API_KEY="your_groq_key_here"
+   export MODAL_ENDPOINT_URL="your_modal_endpoint_here"  # optional
+   ```
+4. Run the Gradio app:
+   ```bash
+   python app.py
+   ```
+
+**On HuggingFace Spaces**: Set `GROQ_API_KEY` in the Space's Secrets settings.
+
+---
+
+## Demo & Socials
+- **Demo Video**: [Insert YouTube/Loom Link Here]
+- **Social Post**: [Insert X/LinkedIn Link Here]
+
+---
+
+## Tech Stack
+
+- **Fast AI (gameplay turns)**: Llama 3.1 8B Instant via Groq LPU (~2s/turn)
+- **Cinematic AI (big moments)**: Qwen 2.5 14B Instruct via llama.cpp on Modal A10G GPU
+- **Frontend**: Gradio 6 with full custom CSS/JS (glassmorphism, glitch effects, particle systems)
+- **Hosting**: HuggingFace Spaces
+
+Built for the **Build Small Hackathon 2026** — Track 2: Thousand Token Wood 🍄

animations.css

@@ -0,0 +1,377 @@
+/* ═══════════════════════════════════════════════════════════════════
+   ORV SCENARIO SIMULATOR — ANIMATIONS.CSS
+   Elder Scrolls / Oblivion Edition — Ambient Gold & Dramatic Reveals
+   ═══════════════════════════════════════════════════════════════════ */
+
+
+/* ─────────────────────────────────────────────────────────────────
+   1. SCREEN SHAKE — damage / impact
+   ───────────────────────────────────────────────────────────────── */
+@keyframes shake {
+    0%   { transform: translate(0, 0); }
+    10%  { transform: translate(-5px, 2px); }
+    20%  { transform: translate(4px, -3px); }
+    30%  { transform: translate(-3px, 4px); }
+    40%  { transform: translate(5px, -2px); }
+    50%  { transform: translate(-2px, -4px); }
+    60%  { transform: translate(3px, 2px); }
+    70%  { transform: translate(-4px, -2px); }
+    80%  { transform: translate(2px, 3px); }
+    90%  { transform: translate(-1px, -1px); }
+    100% { transform: translate(0, 0); }
+}
+.shake { animation: shake 0.5s cubic-bezier(0.36, 0.07, 0.19, 0.97) both; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   2. DAMAGE FLASH — blood red
+   ───────────────────────────────────────────────────────────────── */
+@keyframes damageFlash {
+    0%   { opacity: 0.7; background: rgba(139, 26, 26, 0.3); }
+    50%  { opacity: 0.4; background: rgba(139, 26, 26, 0.15); }
+    100% { opacity: 0;   background: rgba(139, 26, 26, 0); }
+}
+.damage-flash { animation: damageFlash 0.5s ease-out forwards; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   3. AMBIENT GOLD PULSE — torch/candle glow on panels
+   ───────────────────────────────────────────────────────────────── */
+@keyframes goldBreath {
+    0%, 100% {
+        box-shadow: 0 0 8px rgba(201,168,76,0.15), inset 0 0 20px rgba(0,0,0,0.6);
+    }
+    50% {
+        box-shadow: 0 0 20px rgba(201,168,76,0.25), inset 0 0 20px rgba(0,0,0,0.6);
+    }
+}
+.gold-breathe { animation: goldBreath 4s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   4. METER PULSE — meta exposure rise (blood variant)
+   ───────────────────────────────────────────────────────────────── */
+@keyframes meterPulse {
+    0%   { box-shadow: 0 0 5px rgba(139,26,26,0.2); }
+    50%  { box-shadow: 0 0 18px rgba(139,26,26,0.5), 0 0 32px rgba(139,26,26,0.2); }
+    100% { box-shadow: 0 0 5px rgba(139,26,26,0.2); }
+}
+.meter-pulse { animation: meterPulse 1.2s ease-in-out; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   5. DANGER PULSE — meta > 75% (urgent blood warning)
+   ───────────────────────────────────────────────────────────────── */
+@keyframes dangerPulse {
+    0%   { border-color: rgba(139,26,26,0.3); box-shadow: 0 0 8px rgba(139,26,26,0.1); }
+    50%  { border-color: rgba(204,51,51,0.6); box-shadow: 0 0 24px rgba(139,26,26,0.4); }
+    100% { border-color: rgba(139,26,26,0.3); box-shadow: 0 0 8px rgba(139,26,26,0.1); }
+}
+.meter-danger { animation: dangerPulse 1.5s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   6. COIN FALL — gold dust particles
+   ──────────────────────────────────────────────────────────────���── */
+@keyframes coinFall {
+    0% {
+        transform: translateY(-20px) rotate(0deg) scale(1);
+        opacity: 1;
+    }
+    40% {
+        transform: translateY(40vh) translateX(12px) rotate(180deg) scale(0.8);
+        opacity: 0.9;
+    }
+    80% {
+        transform: translateY(80vh) translateX(-8px) rotate(300deg) scale(0.5);
+        opacity: 0.4;
+    }
+    100% {
+        transform: translateY(100vh) rotate(360deg) scale(0.2);
+        opacity: 0;
+    }
+}
+
+
+/* ─────────────────────────────────────────────────────────────────
+   7. SCENARIO FLASH — parchment unfurl entrance
+   ───────────────────────────────────────────────────────────────── */
+@keyframes scenarioFlash {
+    0%   { opacity: 0; background: rgba(201,168,76,0.15); }
+    10%  { opacity: 1; background: rgba(201,168,76,0.08); }
+    25%  { background: rgba(30,20,5,0.7); }
+    100% { opacity: 1; background: rgba(5,4,2,0.92); }
+}
+.scenario-flash { animation: scenarioFlash 1.4s ease-out forwards; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   8. SLIDE IN — from right for chat messages
+   ───────────────────────────────────────────────────────────────── */
+@keyframes slideIn {
+    0%   { transform: translateX(24px); opacity: 0; }
+    100% { transform: translateX(0); opacity: 1; }
+}
+.slide-in-right { animation: slideIn 0.35s cubic-bezier(0.25, 0.46, 0.45, 0.94) both; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   9. FADE IN UP — general entrance (parchment rising)
+   ───────────────────────────────────────────────────────────────── */
+@keyframes fadeInUp {
+    0%   { transform: translateY(16px); opacity: 0; }
+    100% { transform: translateY(0); opacity: 1; }
+}
+.fade-in-up { animation: fadeInUp 0.5s cubic-bezier(0.25, 0.46, 0.45, 0.94) both; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   10. GLITCH — reality distortion for Reader Noticed
+   ───────────────────────────────────────────────────────────────── */
+@keyframes glitch {
+    0%   { text-shadow: 2px 0 #8b1a1a, -2px 0 #c9a84c; transform: translate(0); }
+    15%  { text-shadow: -3px 0 #8b1a1a, 3px 0 #c9a84c; transform: translate(-2px, 1px); }
+    30%  { text-shadow: 3px 0 #8b1a1a, -3px 0 #c9a84c; transform: translate(2px, -1px); }
+    45%  { text-shadow: -2px 0 #8b1a1a, 2px 0 #c9a84c; transform: translate(-1px, 2px); }
+    60%  { text-shadow: 4px 0 #8b1a1a, -4px 0 #c9a84c; transform: translate(2px, -2px); }
+    100% { text-shadow: 2px 0 #8b1a1a, -2px 0 #c9a84c; transform: translate(0); }
+}
+.glitch-effect { animation: glitch 0.3s steps(2) infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   11. GLITCH TEXT — gold/blood RGB split
+   ───────────────────────────────────────────────────────────────── */
+@keyframes glitchText {
+    0%   { text-shadow: 1px 0 #8b1a1a, -1px 0 #c9a84c; }
+    33%  { text-shadow: -2px 1px #8b1a1a, 2px -1px #c9a84c; }
+    66%  { text-shadow: 2px -1px #8b1a1a, -2px 1px #c9a84c; }
+    100% { text-shadow: 1px 0 #8b1a1a, -1px 0 #c9a84c; }
+}
+.glitch-text { animation: glitchText 0.5s steps(3) infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   12. STATIC NOISE — ancient static overlay
+   ───────────────────────────────────────────────────────────────── */
+@keyframes staticNoise {
+    0%   { background-position: 0 0; }
+    20%  { background-position: -30px 20px; }
+    40%  { background-position: 20px -15px; }
+    60%  { background-position: -15px 30px; }
+    80%  { background-position: 25px -25px; }
+    100% { background-position: 0 0; }
+}
+
+.static-noise::after {
+    content: '';
+    position: fixed;
+    top: -50%; left: -50%;
+    width: 200%; height: 200%;
+    background:
+        repeating-radial-gradient(
+            circle at 50% 50%,
+            transparent 0,
+            rgba(201,168,76,0.02) 1px,
+            transparent 2px
+        );
+    animation: staticNoise 0.12s steps(5) infinite;
+    pointer-events: none;
+    z-index: 10000;
+    mix-blend-mode: overlay;
+}
+
+.static-noise::before {
+    content: '';
+    position: fixed;
+    inset: 0;
+    background: repeating-linear-gradient(
+        0deg,
+        transparent 0px,
+        transparent 3px,
+        rgba(139,26,26,0.012) 3px,
+        rgba(139,26,26,0.012) 4px
+    );
+    pointer-events: none;
+    z-index: 10001;
+    animation: staticNoise 0.1s steps(3) infinite reverse;
+}
+
+
+/* ─────────────────────────────────────────────────────────────────
+   13. RANK FLASH — ancient medal reveal
+   ───────────────────────────────────────────────────────────────── */
+@keyframes rankFlash {
+    0%   { transform: scale(0.3); opacity: 0; filter: brightness(3) sepia(0.5); }
+    40%  { transform: scale(1.15); opacity: 1; filter: brightness(2) sepia(0.3); }
+    60%  { transform: scale(0.96); filter: brightness(1.5); }
+    80%  { transform: scale(1.04); filter: brightness(1.2); }
+    100% { transform: scale(1); opacity: 1; filter: brightness(1); }
+}
+
+.rank-s { animation: rankFlash 0.8s cubic-bezier(0.175, 0.885, 0.32, 1.275) both; }
+.rank-a { animation: rankFlash 0.7s cubic-bezier(0.175, 0.885, 0.32, 1.275) both; }
+.rank-b { animation: rankFlash 0.6s cubic-bezier(0.25, 0.46, 0.45, 0.94) both; }
+.rank-c { animation: rankFlash 0.5s ease-out both; }
+
+@keyframes rankGlowGold {
+    0%, 100% { text-shadow: 0 0 30px rgba(240,200,64,0.4), 0 0 60px rgba(201,168,76,0.2); }
+    50%      { text-shadow: 0 0 50px rgba(240,200,64,0.7), 0 0 100px rgba(201,168,76,0.35); }
+}
+
+@keyframes rankGlowBlood {
+    0%, 100% { text-shadow: 0 0 30px rgba(204,51,51,0.4), 0 0 60px rgba(139,26,26,0.2); }
+    50%      { text-shadow: 0 0 50px rgba(204,51,51,0.7), 0 0 100px rgba(139,26,26,0.35); }
+}
+
+.rank-s .rank-letter { animation: rankGlowGold 2s ease-in-out infinite 0.8s; }
+.rank-a .rank-letter { animation: rankGlowGold 2s ease-in-out infinite 0.7s; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   14. GLOW PULSE — gold candlelight flicker on Begin button
+   ───────────────────────────────────────────────────────────────── */
+@keyframes glowPulse {
+    0%, 100% {
+        box-shadow: 0 0 12px rgba(201,168,76,0.25), 0 0 24px rgba(201,168,76,0.10);
+    }
+    50% {
+        box-shadow: 0 0 24px rgba(201,168,76,0.45), 0 0 48px rgba(201,168,76,0.20), 0 0 80px rgba(201,168,76,0.08);
+    }
+}
+.glow-pulse { animation: glowPulse 2.8s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   15. TEXT REVEAL — ink spreading across parchment
+   ───────────────────────────────────────────────────────────────── */
+@keyframes textReveal {
+    0%   { max-width: 0; opacity: 0; }
+    100% { max-width: 100%; opacity: 1; }
+}
+.text-reveal {
+    overflow: hidden;
+    white-space: nowrap;
+    animation: textReveal 2.5s steps(45) forwards;
+}
+
+
+/* ─────────────────────────────────────────────────────────────────
+   16. BAR FILL ENTRANCE
+   ───────────────────────────────────────────────────────────────── */
+@keyframes barFill {
+    0%   { width: 0; }
+}
+.bar-animate-in { animation: barFill 1.2s cubic-bezier(0.25, 0.46, 0.45, 0.94) both; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   17. FLOAT — hovering title (start screen)
+   ───────────────────────────��───────────────────────────────────── */
+@keyframes float {
+    0%, 100% { transform: translateY(0); }
+    50%      { transform: translateY(-8px); }
+}
+.floating { animation: float 4s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   18. CINEMATIC ANIMATIONS
+   ───────────────────────────────────────────────────────────────── */
+@keyframes fadeIn {
+    0%   { opacity: 0; }
+    100% { opacity: 1; }
+}
+.fade-in { animation: fadeIn 0.6s ease-out both; }
+
+@keyframes fadeOut {
+    0%   { opacity: 1; }
+    100% { opacity: 0; }
+}
+.fade-out { animation: fadeOut 0.5s ease-out forwards; }
+
+@keyframes slideInLeft {
+    0%   { transform: translateX(-24px); opacity: 0; }
+    100% { transform: translateX(0); opacity: 1; }
+}
+.slide-in-left { animation: slideInLeft 0.35s cubic-bezier(0.25, 0.46, 0.45, 0.94) both; }
+
+@keyframes scaleUp {
+    0%   { transform: scale(0.85); opacity: 0; }
+    100% { transform: scale(1); opacity: 1; }
+}
+.scale-up { animation: scaleUp 0.45s cubic-bezier(0.175, 0.885, 0.32, 1.275) both; }
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50%      { opacity: 0.55; }
+}
+.pulse { animation: pulse 2.5s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   19. SHIMMER — parchment loading effect
+   ───────────────────────────────────────────────────────────────── */
+@keyframes shimmer {
+    0%   { background-position: -200% 0; }
+    100% { background-position: 200% 0; }
+}
+.shimmer {
+    background: linear-gradient(
+        90deg,
+        #12100a 25%,
+        rgba(201,168,76,0.06) 50%,
+        #12100a 75%
+    );
+    background-size: 200% 100%;
+    animation: shimmer 2.5s infinite;
+}
+
+@keyframes breathe {
+    0%, 100% { opacity: 0.35; }
+    50%      { opacity: 0.75; }
+}
+.breathe { animation: breathe 4.5s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   20. WARP — meta-critical reality distortion
+   ───────────────────────────────────────────────────────────────── */
+@keyframes warp {
+    0%, 100% { filter: none; }
+    25%      { filter: sepia(0.08) hue-rotate(5deg); }
+    50%      { filter: sepia(0.12) hue-rotate(-4deg); }
+    75%      { filter: sepia(0.06) hue-rotate(3deg); }
+}
+body.meta-critical .game-area { animation: warp 5s ease-in-out infinite; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   21. STAGGER — children entrance cascade
+   ───────────────────────────────────────────────────────────────── */
+.stagger-children > * {
+    opacity: 0;
+    animation: fadeInUp 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94) both;
+}
+.stagger-children > *:nth-child(1) { animation-delay: 0.05s; }
+.stagger-children > *:nth-child(2) { animation-delay: 0.10s; }
+.stagger-children > *:nth-child(3) { animation-delay: 0.15s; }
+.stagger-children > *:nth-child(4) { animation-delay: 0.20s; }
+.stagger-children > *:nth-child(5) { animation-delay: 0.25s; }
+.stagger-children > *:nth-child(6) { animation-delay: 0.30s; }
+.stagger-children > *:nth-child(7) { animation-delay: 0.35s; }
+.stagger-children > *:nth-child(8) { animation-delay: 0.40s; }
+.stagger-children > *:nth-child(9) { animation-delay: 0.45s; }
+.stagger-children > *:nth-child(10) { animation-delay: 0.50s; }
+
+
+/* ─────────────────────────────────────────────────────────────────
+   22. REDUCED MOTION
+   ───────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+    }
+}

app.py

@@ -0,0 +1,1252 @@
+"""
+app.py — Omniscient Reader: Scenario Simulator
+================================================
+Main Gradio application entry point.
+
+Connects the Dokkaebi AI (Qwen 2.5 14B via Modal), the game engine,
+scenario definitions, and the custom dark-theme game UI.
+
+Part of the ORV (Omniscient Reader's Viewpoint) Scenario Simulator.
+Build Small Hackathon 2026 — Track 2: Thousand Token Wood.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from urllib.parse import quote
+import gradio as gr
+
+from game_engine import GameState, process_turn
+from scenarios import SCENARIOS, get_scenario_announcement_text, get_next_scenario
+from prompts import build_prompt, build_intro_prompt
+from modal_client import call_dokkaebi, call_dokkaebi_cinematic
+
+# ---------------------------------------------------------------------------
+# Asset paths
+# ---------------------------------------------------------------------------
+
+_ASSET_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets")
+# Cache-busting: timestamp changes every server restart, forcing browser to fetch fresh images
+_CACHE_BUST = int(os.path.getmtime(_ASSET_DIR))
+
+SCENE_IMAGES = {
+    "Subway": "seoul_subway.png",
+    "Seoul Street": "seoul_street.png",
+    "Destroyed Office": "destroyed_office.png",
+    "Han River Bridge": "han_river_bridge.png",
+    "Reader Noticed": "reader_noticed.png",
+}
+
+def _asset_path(filename: str) -> str:
+    return os.path.join(_ASSET_DIR, filename)
+
+def _asset_url(filename: str) -> str:
+    """Return a Gradio file URL that works on Windows + HF Spaces.
+    
+    Gradio 6.x serves allowed files at /gradio_api/file=<abs_path>.
+    We encode path segments so spaces become %20.
+    """
+    abs_path = os.path.abspath(os.path.join(_ASSET_DIR, filename))
+    fwd = abs_path.replace("\\", "/")
+    parts = fwd.split("/")
+    encoded = "/".join(quote(p, safe='') if p else p for p in parts)
+    encoded = encoded.replace("%3A", ":", 1)
+    return f"/gradio_api/file={encoded}?v={_CACHE_BUST}"
+
+
+# ---------------------------------------------------------------------------
+# Load CSS / JS
+# ---------------------------------------------------------------------------
+
+def _read_file(path: str) -> str:
+    with open(os.path.join(os.path.dirname(__file__), path), "r", encoding="utf-8") as f:
+        return f.read()
+
+_STYLE_CSS = _read_file("style.css")
+_ANIMATIONS_CSS = _read_file("animations.css")
+_GAME_JS = _read_file("game.js")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# HTML RENDERERS — Build the game UI from state + AI response
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def render_start_screen() -> str:
+    """Dramatic ORV manhwa-accurate start screen."""
+    return f"""
+    <style>
+    #start-screen {{
+        background-image: url('{_asset_url('title_banner.png')}') !important;
+        background-size: cover !important;
+        background-position: center center !important;
+        background-repeat: no-repeat !important;
+        background-color: #030305 !important;
+    }}
+    </style>
+    <div class="start-screen" id="start-screen" style="
+        position: relative;
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        overflow: hidden;">
+
+        <!-- Multi-layer dark overlay for readability -->
+        <div style="position:absolute;inset:0;
+             background: linear-gradient(
+               180deg,
+               rgba(3,3,5,0.50) 0%,
+               rgba(3,3,5,0.60) 35%,
+               rgba(3,3,5,0.82) 70%,
+               rgba(3,3,5,0.96) 100%
+             );"></div>
+
+        <!-- Subtle vignette edges -->
+        <div style="position:absolute;inset:0;
+             background: radial-gradient(ellipse at 50% 50%, transparent 40%, rgba(3,3,5,0.7) 100%);
+             pointer-events:none;"></div>
+
+        <!-- Top crimson accent line -->
+        <div style="position:absolute;top:0;left:0;right:0;height:2px;
+             background:linear-gradient(90deg,transparent,#7a1a22,#904858,#7a1a22,transparent);"></div>
+
+        <div class="start-content" style="position:relative;z-index:2;text-align:center;padding:0 40px;max-width:760px;">
+
+            <!-- Label above title -->
+            <div style="
+                font-family:'Cinzel',serif;
+                font-size:10px;
+                color:#904858;
+                letter-spacing:6px;
+                text-transform:uppercase;
+                margin-bottom:18px;
+                opacity:0.85;
+            ">[ System Notification — Star Stream Access Granted ]</div>
+
+            <!-- Main Title -->
+            <div style="
+                font-family:'Cinzel Decorative',serif;
+                font-size:clamp(2.2em,5.5vw,4em);
+                font-weight:900;
+                color:#d8cbb0;
+                letter-spacing:0.18em;
+                text-transform:uppercase;
+                text-shadow:
+                    0 0 60px rgba(144,72,88,0.35),
+                    0 0 120px rgba(122,26,34,0.15),
+                    0 3px 12px rgba(0,0,0,0.95);
+                margin-bottom:6px;
+                line-height:1.1;
+            ">Omniscient Reader</div>
+
+            <!-- Subtitle -->
+            <div style="
+                font-family:'Cinzel',serif;
+                font-size:0.95em;
+                color:#904858;
+                letter-spacing:0.55em;
+                text-transform:uppercase;
+                opacity:0.75;
+                margin-bottom:28px;
+            ">Scenario Simulator</div>
+
+            <!-- Divider -->
+            <div style="width:360px;margin:0 auto 28px;height:1px;
+                 background:linear-gradient(90deg,transparent,#5a1828,#904858,#5a1828,transparent);"></div>
+
+            <!-- Tagline -->
+            <div style="
+                font-family:'IM Fell English',Georgia,serif;
+                font-size:1em;
+                font-style:italic;
+                color:#a09078;
+                line-height:2.2;
+                margin-bottom:36px;
+                text-shadow:0 2px 6px rgba(0,0,0,0.9);
+            ">
+                You have read the novel 3,149 times.<br>
+                The Dokkaebi knows you know everything.<br>
+                <span style="color:#c06878;">Reality has been redesigned — specifically for you.</span>
+            </div>
+
+            <!-- Portraits row -->
+            <div style="display:flex;justify-content:center;gap:20px;margin-bottom:36px;">
+
+                <!-- Kim Dokja -->
+                <div style="text-align:center;">
+                    <div style="
+                        width:88px;height:114px;
+                        border:1px solid #5a1828;
+                        position:relative;overflow:hidden;
+                        box-shadow:0 8px 32px rgba(0,0,0,0.9),0 0 0 1px rgba(144,72,88,0.15);
+                    ">
+                        <div style="position:absolute;top:0;left:0;width:12px;height:12px;border-top:2px solid #904858;border-left:2px solid #904858;z-index:2;"></div>
+                        <div style="position:absolute;bottom:0;right:0;width:12px;height:12px;border-bottom:2px solid #904858;border-right:2px solid #904858;z-index:2;"></div>
+                        <img src="{_asset_url('dokja_portrait.png')}" alt="Kim Dokja"
+                             style="width:100%;height:100%;object-fit:cover;object-position:top;
+                             filter:contrast(1.15) brightness(0.8) saturate(0.8);">
+                        <div style="position:absolute;inset:0;background:linear-gradient(to top,rgba(6,5,8,0.6) 0%,transparent 50%);"></div>
+                    </div>
+                    <div style="font-family:'Cinzel',serif;color:#904858;font-size:8px;margin-top:7px;letter-spacing:2.5px;text-transform:uppercase;">Incarnation</div>
+                </div>
+
+                <!-- Dokkaebi -->
+                <div style="text-align:center;">
+                    <div style="
+                        width:88px;height:114px;
+                        border:1px solid #5a1828;
+                        position:relative;overflow:hidden;
+                        box-shadow:0 8px 32px rgba(0,0,0,0.9),0 0 0 1px rgba(144,72,88,0.15);
+                    ">
+                        <div style="position:absolute;top:0;left:0;width:12px;height:12px;border-top:2px solid #904858;border-left:2px solid #904858;z-index:2;"></div>
+                        <div style="position:absolute;bottom:0;right:0;width:12px;height:12px;border-bottom:2px solid #904858;border-right:2px solid #904858;z-index:2;"></div>
+                        <img src="{_asset_url('dokkaebi_character.png')}" alt="Dokkaebi"
+                             style="width:100%;height:100%;object-fit:cover;
+                             filter:contrast(1.15) brightness(0.8) saturate(0.75);">
+                        <div style="position:absolute;inset:0;background:linear-gradient(to top,rgba(6,5,8,0.6) 0%,transparent 50%);"></div>
+                    </div>
+                    <div style="font-family:'Cinzel',serif;color:#904858;font-size:8px;margin-top:7px;letter-spacing:2.5px;text-transform:uppercase;">Dokkaebi</div>
+                </div>
+
+                <!-- Yoo Sangah -->
+                <div style="text-align:center;">
+                    <div style="
+                        width:88px;height:114px;
+                        border:1px solid #5a1828;
+                        position:relative;overflow:hidden;
+                        box-shadow:0 8px 32px rgba(0,0,0,0.9),0 0 0 1px rgba(144,72,88,0.15);
+                    ">
+                        <div style="position:absolute;top:0;left:0;width:12px;height:12px;border-top:2px solid #904858;border-left:2px solid #904858;z-index:2;"></div>
+                        <div style="position:absolute;bottom:0;right:0;width:12px;height:12px;border-bottom:2px solid #904858;border-right:2px solid #904858;z-index:2;"></div>
+                        <img src="{_asset_url('yoo_sangah_portrait.png')}" alt="Jung Heewon"
+                             style="width:100%;height:100%;object-fit:cover;object-position:top;
+                             filter:contrast(1.15) brightness(0.8) saturate(0.75);">
+                        <div style="position:absolute;inset:0;background:linear-gradient(to top,rgba(6,5,8,0.6) 0%,transparent 50%);"></div>
+                    </div>
+                    <div style="font-family:'Cinzel',serif;color:#904858;font-size:8px;margin-top:7px;letter-spacing:2.5px;text-transform:uppercase;">Jung Heewon</div>
+                </div>
+
+                <!-- Jung Heewon -->
+                <div style="text-align:center;">
+                    <div style="
+                        width:88px;height:114px;
+                        border:1px solid #5a1828;
+                        position:relative;overflow:hidden;
+                        box-shadow:0 8px 32px rgba(0,0,0,0.9),0 0 0 1px rgba(144,72,88,0.15);
+                    ">
+                        <div style="position:absolute;top:0;left:0;width:12px;height:12px;border-top:2px solid #904858;border-left:2px solid #904858;z-index:2;"></div>
+                        <div style="position:absolute;bottom:0;right:0;width:12px;height:12px;border-bottom:2px solid #904858;border-right:2px solid #904858;z-index:2;"></div>
+                        <img src="{_asset_url('jung_heewon_portrait.png')}" alt="Lee Jihye"
+                             style="width:100%;height:100%;object-fit:cover;object-position:top;
+                             filter:contrast(1.15) brightness(0.8) saturate(0.75);">
+                        <div style="position:absolute;inset:0;background:linear-gradient(to top,rgba(6,5,8,0.6) 0%,transparent 50%);"></div>
+                    </div>
+                    <div style="font-family:'Cinzel',serif;color:#904858;font-size:8px;margin-top:7px;letter-spacing:2.5px;text-transform:uppercase;">Lee Jihye</div>
+                </div>
+
+            </div>
+
+            <!-- Divider -->
+            <div style="width:260px;margin:0 auto 24px;height:1px;
+                 background:linear-gradient(90deg,transparent,#5a1828,#904858,#5a1828,transparent);"></div>
+
+            <!-- Attribution -->
+            <div style="font-family:'Cinzel',serif;color:#3a2832;font-size:9px;letter-spacing:3px;text-transform:uppercase;margin-bottom:28px;">
+                Powered by Llama 3.1 &nbsp;·&nbsp; Build Small Hackathon 2026
+            </div>
+
+            <!-- Spacer so background fills screen (real button is position:fixed) -->
+            <div style="height:120px;"></div>
+
+        </div>
+    </div>
+    """
+
+
+def render_scenario_header(state: dict) -> str:
+    """Top bar — Elder Scrolls quest log style."""
+    scenario_num = state.get("scenario_num", 1)
+    scenario = SCENARIOS.get(scenario_num, SCENARIOS[1])
+    name = scenario["name"]
+    subtitle = scenario.get("subtitle", "")
+    location = scenario.get("location", "")
+    difficulty = scenario.get("difficulty", "?")
+    turn = state.get("turn", 1)
+    max_turns = scenario.get("turns", 8)
+
+    diff_colors = {"F": "#90c060", "E": "#904858", "D": "#9b6a30", "C": "#c97040",
+                   "B": "#c04030", "A": "#8b1a1a", "S": "#f0c840", "SS": "#cc3333"}
+    diff_color = diff_colors.get(difficulty, "#904858")
+
+    return f"""
+    <div class="scenario-header-inner">
+        <div class="scenario-header-left">
+            <span style="font-family:'Cinzel',serif;color:#6a3040;font-size:11px;letter-spacing:1px;">Main Scenario &nbsp;{scenario_num}</span>
+        </div>
+        <div class="scenario-header-center" style="text-align:center;">
+            <div class="scenario-header-text" style="font-family:'Cinzel Decorative',serif;font-size:15px;font-weight:700;color:#f0c840;letter-spacing:4px;text-shadow:0 0 20px rgba(240,200,64,0.45);">âš” {name} âš”</div>
+            <div style="font-family:'Cinzel',serif;font-size:10px;color:#8a7050;letter-spacing:2px;margin-top:2px;">{subtitle} — {location}</div>
+        </div>
+        <div class="scenario-header-right" style="text-align:right;">
+            <span style="font-family:'Cinzel',serif;color:{diff_color};font-size:11px;letter-spacing:1px;">Rank {difficulty}</span>
+            <span style="font-family:'Cinzel',serif;color:#5a4a35;font-size:11px;margin-left:14px;letter-spacing:1px;">Turn {turn} / {max_turns}</span>
+        </div>
+    </div>
+    """
+
+
+def render_player_panel(state: dict) -> str:
+    """Left panel — Elder Scrolls character sheet style."""
+    hp = state.get("hp", 100)
+    max_hp = state.get("max_hp", 100)
+    hp_pct = max(0, min(100, (hp / max_hp) * 100)) if max_hp > 0 else 0
+    coins = state.get("coins", 0)
+    titles = state.get("titles", [])
+    skills = state.get("skills", {})
+    sponsor = state.get("sponsor")
+    debuffs = state.get("active_debuffs", [])
+    phase = state.get("current_phase", "Exploration")
+
+    titles_html = "".join(
+        f'<span class="title-badge">{t}</span>' for t in titles
+    ) if titles else f'<span style="color:#5a4a35;font-family:\'Cinzel\',serif;font-size:10px;font-style:italic;">No titles earned yet</span>'
+
+    if isinstance(skills, dict):
+        skills_parts = []
+        for name, d in skills.items():
+            cd = d.get("cooldown", 0)
+            opacity = "0.35" if cd > 0 else "1"
+            cd_txt = f" · CD:{cd}" if cd > 0 else ""
+            skills_parts.append(
+                f'<div class="skill-name" style="opacity:{opacity};margin-bottom:3px;">'
+                f"âš” {name}{cd_txt}"
+                f'</div>'
+            )
+        skills_html = "".join(skills_parts) or f'<span style="color:#5a4a35;font-size:10px;font-style:italic;">None</span>'
+    else:
+        skills_html = ""
+
+    debuffs_html = ""
+    if debuffs:
+        debuff_badges = "".join(
+            f'<div style="background:rgba(139,26,26,0.15);border:1px solid #5a0808;'
+            f'color:#cc3333;padding:3px 8px;margin:2px 0;'
+            f'font-family:\'Cinzel\',serif;font-size:9px;letter-spacing:1px;">âš  {d}</div>'
+            for d in debuffs
+        )
+        debuffs_html = f"""
+        <div>
+            <div style="font-family:'Cinzel',serif;font-size:9px;letter-spacing:2px;color:#8b1a1a;text-transform:uppercase;margin-bottom:4px;">Active Afflictions</div>
+            {debuff_badges}
+        </div>"""
+
+    phase_colors = {"Combat": "#cc3333", "Safe Zone": "#90c060", "Exploration": "#904858"}
+    phase_color = phase_colors.get(phase, "#904858")
+    phase_icons = {"Combat": "⚔", "Safe Zone": "✦", "Exploration": "◈"}
+    phase_icon = phase_icons.get(phase, "â—ˆ")
+
+    sponsor_html = f"""
+        <div style="margin-top:6px;font-family:'Cinzel',serif;color:#904858;font-size:10px;letter-spacing:1px;text-shadow:0 0 8px rgba(201,168,76,0.3);">
+            ✦ Sponsor: {sponsor}
+        </div>
+    """ if sponsor else ""
+
+    return f"""
+    <div style="display:flex;flex-direction:column;gap:12px;width:100%;">
+
+        <!-- Portrait with ornate corners -->
+        <div class="player-portrait">
+            <img src="{_asset_url('dokja_portrait.png')}" alt="Kim Dokja">
+        </div>
+
+        <!-- Name + Phase -->
+        <div style="text-align:center;">
+            <div style="font-family:'Cinzel Decorative',serif;color:#f0c840;font-size:15px;font-weight:700;text-transform:uppercase;letter-spacing:3px;text-shadow:0 0 16px rgba(240,200,64,0.4);">
+                Kim Dokja
+            </div>
+            <div style="font-family:'Cinzel',serif;font-size:10px;color:#8a7050;letter-spacing:2px;margin-top:4px;">
+                Incarnation &nbsp;·&nbsp; <span style="color:{phase_color};">{phase_icon} {phase}</span>
+            </div>
+        </div>
+
+        <!-- Divider -->
+        <div style="height:1px;background:linear-gradient(90deg,transparent,#6a3040,transparent);"></div>
+
+        <!-- HP Bar -->
+        <div class="stat-bar stat-bar-hp">
+            <div class="stat-bar-label"><span>Vitality</span><span>{hp}/{max_hp}</span></div>
+            <div class="stat-bar-track"><div class="stat-bar-fill" style="width:{hp_pct}%"></div></div>
+        </div>
+
+        <!-- Coins -->
+        <div style="font-family:'Cinzel',serif;color:#904858;font-size:13px;text-shadow:0 0 8px rgba(201,168,76,0.4);letter-spacing:1px;">
+            â—ˆ {coins:,} Coins
+        </div>
+
+        {debuffs_html}
+
+        <!-- Divider -->
+        <div style="height:1px;background:linear-gradient(90deg,transparent,#3a1828,transparent);"></div>
+
+        <!-- Titles -->
+        <div>
+            <div style="font-family:'Cinzel',serif;font-size:9px;letter-spacing:2px;color:#6a3040;text-transform:uppercase;margin-bottom:6px;">Titles Earned</div>
+            <div>{titles_html}</div>
+        </div>
+
+        <!-- Skills -->
+        <div>
+            <div style="font-family:'Cinzel',serif;font-size:9px;letter-spacing:2px;color:#6a3040;text-transform:uppercase;margin-bottom:6px;">Combat Skills</div>
+            <div style="font-family:'Cinzel',serif;font-size:11px;color:#b8a07a;">{skills_html}</div>
+        </div>
+
+        {sponsor_html}
+    </div>
+    """
+
+
+
+
+def render_meters(state: dict) -> str:
+    """Render meters in Elder Scrolls style."""
+    meta = state.get("meta_exposure", 0)
+    stability = state.get("prob_stability", 100)
+    entertainment = state.get("entertainment", 0)
+
+    meta_class = ""
+    if meta >= 75:
+        meta_class = "meter-danger"
+    elif meta >= 50:
+        meta_class = "meter-pulse"
+
+    return f"""
+    <div class="meters-container">
+        <!-- Divider -->
+        <div style="height:1px;background:linear-gradient(90deg,transparent,#3a1828,transparent);margin-bottom:8px;"></div>
+
+        <!-- Meta Exposure -->
+        <div class="stat-bar stat-bar-meta {meta_class}">
+            <div class="stat-bar-label"><span>âš  Meta Exposure</span><span>{meta}%</span></div>
+            <div class="stat-bar-track"><div class="stat-bar-fill" style="width:{meta}%"></div></div>
+        </div>
+
+        <!-- Probability Stability -->
+        <div class="stat-bar stat-bar-stability">
+            <div class="stat-bar-label"><span>â—ˆ Probability</span><span>{stability}%</span></div>
+            <div class="stat-bar-track"><div class="stat-bar-fill" style="width:{stability}%"></div></div>
+        </div>
+
+        <!-- Entertainment -->
+        <div style="text-align:center;margin-top:8px;font-family:'Cinzel',serif;font-size:10px;color:#5a4a35;letter-spacing:2px;">
+            ✦ Entertainment &nbsp;{entertainment}
+        </div>
+    </div>
+    """
+
+
+def render_narrative(narrative: str, dokkaebi_comment: str,
+                     reality_subversion: str = None) -> str:
+    """Main game area narrative — tome reading style."""
+    subversion_html = ""
+    if reality_subversion:
+        subversion_html = f"""
+        <div style="margin:12px 24px;padding:12px 16px;
+             background:rgba(90,42,138,0.12);border-left:2px solid #5a2a8a;
+             font-family:'Cinzel',serif;color:#9b59b6;font-size:11px;letter-spacing:1px;">
+            ⚠ Probability Distortion — {reality_subversion}
+        </div>
+        """
+
+    return f"""
+    <div class="narrative-container system-window"
+         style="overflow-y:auto;max-height:280px;min-height:100px;flex-shrink:0;"
+    >
+        <div class="narrative-text">{narrative}</div>
+        {subversion_html}
+        <div class="dokkaebi-text">{dokkaebi_comment}</div>
+    </div>
+    """
+
+
+def render_scene(state: dict) -> str:
+    """Scene background image — cinematic dark vignette."""
+    scenario_num = state.get("scenario_num", 1)
+    scenario = SCENARIOS.get(scenario_num, SCENARIOS[1])
+    scene_img = scenario.get("scene_image", "seoul_subway.png")
+
+    return f"""
+    <div style="width:100%;height:160px;overflow:hidden;margin-bottom:0;
+         background:url('{_asset_url(scene_img)}') center/cover no-repeat;
+         border-bottom:1px solid rgba(106,48,64,0.4);
+         position:relative;flex-shrink:0;"
+    >
+         <div style="position:absolute;inset:0;background:linear-gradient(to top,rgba(6,5,8,0.95) 0%,rgba(6,5,8,0.3) 50%,transparent 100%);"></div>
+         <div style="position:absolute;inset:0;background:linear-gradient(to right,rgba(6,5,8,0.4) 0%,transparent 30%,transparent 70%,rgba(6,5,8,0.4) 100%);"></div>
+    </div>
+    """
+
+
+def render_suggestions(suggestions: list) -> str:
+    """Three action suggestions — Elder Scrolls decision scroll."""
+    if not suggestions or len(suggestions) < 3:
+        suggestions = ["Look around carefully", "Search for something useful", "Do something unexpected"]
+
+    buttons = ""
+    for i, sug in enumerate(suggestions):
+        roman = ["I", "II", "III", "IV", "V"][i] if i < 5 else str(i+1)
+        buttons += f"""
+        <button class="suggestion-btn" data-action="{sug}"
+            style="display:flex;align-items:flex-start;gap:10px;width:100%;text-align:left;margin:0 0 6px 0;padding:10px 14px;
+            background:rgba(18,12,20,0.7);border:1px solid #5a3040;border-left:2px solid #904050;color:#d0b0a0;cursor:pointer;transition:all 0.2s;
+            font-family:'IM Fell English',serif;font-style:italic;font-size:13px;line-height:1.5;"
+            onmouseover="this.style.borderColor='#c06070'; this.style.backgroundColor='rgba(40,18,28,0.8)'; this.style.color='#e0c0b0';"
+            onmouseout="this.style.borderColor='#5a3040'; this.style.backgroundColor='rgba(18,12,20,0.7)'; this.style.color='#d0b0a0';"
+            >
+            <span style="color:#904050;min-width:18px;font-size:10px;margin-top:1px;font-family:'Cinzel',serif;">{roman}.</span>
+            <span>{sug}</span>
+        </button>
+        """
+
+    return f'''<div style="width:100%;">
+  <div class="suggestion-section-label">— Choose Your Action —</div>
+  <div style="padding:6px 14px 10px;display:flex;flex-direction:column;gap:4px;">{buttons}</div>
+</div>'''
+
+
+def render_star_stream(state: dict, new_reactions: list = None) -> str:
+    """Right panel — Star Stream as an ancient chronicle scroll."""
+    history = state.get("star_stream_history", [])
+    display_reactions = history[-15:]
+
+    messages_html = ""
+    for r in display_reactions:
+        modifier = r.get("modifier", "Unknown Constellation")
+        reaction = r.get("reaction", "...")
+        coins = r.get("coins", 0)
+
+        mood = "neutral"
+        if any(w in modifier for w in ["Demonic", "Abyssal", "Dark", "Death"]): mood = "negative"
+        if any(w in modifier for w in ["Judge", "Salvation", "Light", "Star"]): mood = "positive"
+
+        coin_html = f'<div class="chat-donation" style="font-family:\'Cinzel\',serif;font-size:10px;letter-spacing:1px;">+ {coins} Coins</div>' if coins > 0 else ""
+
+        messages_html += f"""
+        <div class="chat-message" data-mood="{mood}">
+            <span class="constellation-name">{modifier}</span>
+            <span style="color:#8a7050;font-family:\'IM Fell English\',serif;font-style:italic;font-size:12px;line-height:1.5;">{reaction}</span>
+            {coin_html}
+        </div>
+        """
+
+    if not messages_html:
+        messages_html = """
+        <div class="chat-message" data-mood="neutral" style="opacity:0.5;">
+            <span style="font-family:'IM Fell English',serif;font-style:italic;font-size:12px;color:#5a4a35;">The Constellations observe in silence...</span>
+        </div>
+        """
+
+    return f"""
+    <div style="width:100%;display:flex;flex-direction:column;height:100%;">
+        <div style="font-family:'Cinzel Decorative',serif;color:#904858;font-size:11px;letter-spacing:3px;text-transform:uppercase;margin-bottom:10px;text-shadow:0 0 12px rgba(201,168,76,0.4);">
+            ✦ Star Stream
+        </div>
+        <div style="height:1px;background:linear-gradient(90deg,#6a3040,transparent);margin-bottom:12px;"></div>
+        <div class="constellation-chat" id="star-stream-chat">
+            {messages_html}
+        </div>
+    </div>
+    """
+
+
+def render_overlay(overlay_type: str = "", data: dict = None) -> str:
+    """Fullscreen overlays — Elder Scrolls stone tablet style."""
+    if not overlay_type:
+        return '<div class="fullscreen-overlay" style="display:none;"></div>'
+
+    if overlay_type == "scenario_announcement":
+        scenario = data or {}
+        announcement = get_scenario_announcement_text(scenario)
+        intro = scenario.get("intro_narrative", "")
+        return f"""
+        <div class="fullscreen-overlay scenario-flash" id="game-overlay" data-auto-dismiss="6000">
+            <div class="scenario-announcement fade-in-up" style="max-width:640px;">
+                <div style="font-family:'Cinzel',serif;color:#6a3040;font-size:11px;letter-spacing:3px;margin-bottom:16px;">MAIN SCENARIO #{scenario.get('number', '?')}</div>
+                <div style="font-family:'Cinzel Decorative',serif;color:#f0c840;font-size:1.8em;font-weight:700;letter-spacing:4px;text-shadow:0 0 30px rgba(240,200,64,0.4);margin-bottom:20px;">SCENARIO BEGINS</div>
+                <div style="height:1px;background:linear-gradient(90deg,transparent,#904858,transparent);margin-bottom:20px;"></div>
+                <pre style="font-family:'IM Fell English',serif;color:#d4c090;text-align:left;white-space:pre-wrap;max-width:500px;margin:0 auto 20px;font-style:italic;font-size:13px;line-height:1.8;">{announcement}</pre>
+                <div style="font-family:'IM Fell English',serif;font-style:italic;color:#b8a07a;font-size:14px;line-height:1.8;max-width:560px;margin:0 auto 24px;">{intro}</div>
+                <div style="font-family:'Cinzel',serif;font-size:10px;color:#5a4a35;letter-spacing:3px;">✦ Click to Continue ✦</div>
+            </div>
+        </div>
+        """
+
+    elif overlay_type == "ranking":
+        rank = data.get("rank", "C") if data else "C"
+        rank_colors = {"S": "#f0c840", "A": "#904858", "B": "#7a8fbb", "C": "#8a7050"}
+        color = rank_colors.get(rank, "#8a7050")
+        bg_img = _asset_url("rank_s_bg.png") if rank == "S" else ""
+        bg_style = f"background:url('{bg_img}') center/cover no-repeat,#060402;" if bg_img else "background:#060402;"
+        return f"""
+        <div class="fullscreen-overlay" id="game-overlay" data-auto-dismiss="4000" style="{bg_style}">
+            <div class="ranking-display rank-{rank.lower()}" style="text-align:center;">
+                <div style="font-family:'Cinzel',serif;color:#6a3040;font-size:12px;letter-spacing:4px;margin-bottom:16px;">SCENARIO COMPLETE</div>
+                <div style="height:1px;width:200px;margin:0 auto 20px;background:linear-gradient(90deg,transparent,#904858,transparent);"></div>
+                <div style="font-size:7em;font-family:'Cinzel Decorative',serif;font-weight:900;color:{color};text-shadow:0 0 60px {color},0 0 120px {color}40;">{rank}</div>
+                <div style="font-family:'Cinzel',serif;font-size:14px;letter-spacing:4px;color:#904858;margin-top:16px;">RANK {rank} — BATTLE CONCLUDED</div>
+            </div>
+        </div>
+        """
+
+    elif overlay_type == "reader_noticed":
+        return f"""
+        <div class="fullscreen-overlay reader-noticed glitch-effect static-noise" id="game-overlay">
+            <div style="text-align:center;max-width:600px;padding:40px;border:1px solid #8b1a1a;background:linear-gradient(160deg,#1a0808,#0e0404);position:relative;">
+                <div style="position:absolute;top:-1px;left:-1px;width:24px;height:24px;border-top:2px solid #cc3333;border-left:2px solid #cc3333;"></div>
+                <div style="position:absolute;bottom:-1px;right:-1px;width:24px;height:24px;border-bottom:2px solid #cc3333;border-right:2px solid #cc3333;"></div>
+                <div class="glitch-text" style="font-family:'Cinzel',serif;font-size:11px;letter-spacing:3px;color:#8b1a1a;margin-bottom:20px;">PROBABILITY DISTORTION DETECTED</div>
+                <div class="glitch-text" style="font-family:'Cinzel Decorative',serif;font-size:2.4em;font-weight:900;color:#e8d5a3;margin:16px 0;text-shadow:0 0 30px rgba(139,26,26,0.6);">THE READER<br>HAS BEEN NOTICED</div>
+                <div style="height:1px;background:linear-gradient(90deg,transparent,#8b1a1a,transparent);margin:20px 0;"></div>
+                <div style="font-family:'Cinzel',serif;font-size:12px;color:#cc3333;letter-spacing:3px;">⚠ Hidden Scenario Unlocked — Difficulty: Impossible</div>
+            </div>
+        </div>
+        """
+
+    elif overlay_type == "game_over":
+        reason = data.get("reason", "You have died.") if data else "You have died."
+        return f"""
+        <div class="fullscreen-overlay" id="game-overlay">
+            <div style="text-align:center;max-width:520px;padding:48px;border:1px solid #5a0808;background:linear-gradient(160deg,#150808,#0a0404);position:relative;">
+                <div style="position:absolute;top:-1px;left:-1px;width:22px;height:22px;border-top:2px solid #8b1a1a;border-left:2px solid #8b1a1a;"></div>
+                <div style="position:absolute;bottom:-1px;right:-1px;width:22px;height:22px;border-bottom:2px solid #8b1a1a;border-right:2px solid #8b1a1a;"></div>
+                <div style="font-family:'Cinzel Decorative',serif;font-size:2em;color:#8b1a1a;font-weight:900;text-shadow:0 0 30px rgba(139,26,26,0.5);margin-bottom:20px;">INCARNATION ELIMINATED</div>
+                <div style="height:1px;background:linear-gradient(90deg,transparent,#5a0808,transparent);margin-bottom:20px;"></div>
+                <div style="font-family:'IM Fell English',serif;font-style:italic;color:#b8a07a;font-size:15px;line-height:1.8;margin-bottom:20px;">{reason}</div>
+                <div style="font-family:'Cinzel',serif;font-size:10px;color:#5a4a35;letter-spacing:2px;">The Constellations have lost interest.</div>
+            </div>
+        </div>
+        """
+
+    return '<div class="fullscreen-overlay" style="display:none;"></div>'
+
+
+def render_state_data(state: dict) -> str:
+    """Hidden element that passes state JSON to JavaScript for effects."""
+    return f'<div id="game-state-data" style="display:none;" data-state=\'{json.dumps(state)}\'></div>'
+
+def buy_item_action(item_selection: str, state: dict):
+    if not item_selection or not state:
+        return state, render_player_panel(state)
+    item_map = {
+        "Minor HP Potion (15c)": ("Minor HP Potion", 15),
+        "HP Potion (30c)": ("HP Potion", 30),
+        "Major HP Potion (60c)": ("Major HP Potion", 60),
+        "Star Stream Flare (100c)": ("Star Stream Flare", 100),
+        "Unbroken Faith (150c)": ("Unbroken Faith", 150),
+        "Probability Nullifier (200c)": ("Probability Nullifier", 200),
+        "Random Attribute Box (250c)": ("Random Attribute Box", 250)
+    }
+    if item_selection not in item_map:
+        return state, render_player_panel(state)
+        
+    item_name, cost = item_map[item_selection]
+    gs = GameState.from_dict(state)
+    if gs.buy_item(item_name, cost):
+        return gs.to_dict(), render_player_panel(gs.to_dict())
+    return state, render_player_panel(state)
+
+def use_skill_action(skill_selection: str, current_input: str, state: dict):
+    if not skill_selection or not state:
+        return state, current_input, gr.update()
+    
+    gs = GameState.from_dict(state)
+    skill_data = gs.state["skills"].get(skill_selection)
+    if skill_data and skill_data.get("cooldown", 0) <= 0:
+        skill_data["cooldown"] = skill_data.get("max_cooldown", 3)
+        new_text = f"[Activating Skill: {skill_selection}] - " + (current_input or "")
+        available_skills = [s for s, d in gs.state["skills"].items() if d.get("cooldown", 0) <= 0]
+        return gs.to_dict(), new_text, gr.update(choices=available_skills)
+        
+    return state, current_input, gr.update()
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━â���â”â”â”â”â”â”â”â”â”â”â”
+# GAME LOGIC — Event handlers
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def start_game():
+    """Initialize game state and trigger Scenario 1 intro."""
+    gs = GameState()
+    state = gs.to_dict()
+    scenario = SCENARIOS[1]
+
+    # Generate intro via AI (using Groq for speed)
+    system_prompt = build_intro_prompt(state, scenario)
+    ai_response = call_dokkaebi(system_prompt, "The scenario begins. Introduce yourself and set the scene.")
+
+    # Build initial UI
+    narrative = ai_response.get("narrative", scenario["intro_narrative"])
+    dokkaebi_comment = ai_response.get("dokkaebi_comment", "Incarnation. Your scenario begins now.")
+    suggestions = ai_response.get("suggestions", [
+        "Look around the subway car",
+        "Try to calm the panicking passengers",
+        "Search for an exit immediately"
+    ])
+    constellation_reactions = ai_response.get("constellation_reactions", [])
+
+    # Add initial reactions to star stream
+    if constellation_reactions:
+        for r in constellation_reactions[-5:]:
+            state["star_stream_history"].append(r)
+
+    available_skills = [s for s, d in state.get("skills", {}).items() if d.get("cooldown", 0) <= 0]
+
+    return (
+        state,                                              # game state
+        gr.update(visible=False),                           # hide start screen
+        gr.update(visible=False),                           # hide start button
+        gr.update(visible=True),                            # show game header
+        gr.update(visible=True),                            # show game main
+        gr.update(visible=True),                            # show input bar
+        render_scenario_header(state),                      # scenario header
+        render_player_panel(state),                         # player panel
+        render_meters(state),                               # meters
+        render_scene(state),                                # scene image
+        render_narrative(narrative, dokkaebi_comment),       # narrative
+        render_suggestions(suggestions),                    # suggestions
+        render_star_stream(state, constellation_reactions),  # star stream
+        render_overlay("scenario_announcement", scenario),  # show scenario announcement
+        render_state_data(state),                           # state for JS
+        "",                                                 # clear input
+        gr.update(choices=available_skills),                # update active skills dropdown
+    )
+
+
+def take_action(stance: str, player_action: str, state: dict):
+    """Process a player action and update the game."""
+    if not state:
+        # Game not started yet — return no-ops for all 11 outputs
+        return [state] + [gr.update()] * 9 + ["", gr.update()]
+
+    if not player_action or not player_action.strip():
+        # Empty input — do nothing
+        return (
+            state,
+            render_scenario_header(state),
+            render_player_panel(state),
+            render_meters(state),
+            render_scene(state),
+            gr.update(),  # keep current narrative
+            gr.update(),  # keep current suggestions
+            render_star_stream(state),
+            render_overlay(),  # no overlay
+            render_state_data(state),
+            "",
+            gr.update()
+        )
+
+    player_action = player_action.strip()
+    if stance and stance != "Neutral":
+        action_for_prompt = f"[{stance} Stance] {player_action}"
+    else:
+        action_for_prompt = player_action
+
+    # Get current scenario
+    scenario_num = state.get("scenario_num", 1)
+    scenario = SCENARIOS.get(scenario_num, SCENARIOS[1])
+
+    # Build prompt and call AI
+    system_prompt = build_prompt(state, action_for_prompt, scenario)
+    # Payload note: {"max_tokens": 500} for speed
+    ai_response = call_dokkaebi(system_prompt, action_for_prompt)
+
+    # Process the turn (update game state)
+    prev_hp = state.get("hp", 100)
+    prev_meta = state.get("meta_exposure", 0)
+    updated_state = process_turn(state, action_for_prompt, ai_response, stance)
+
+    # Determine overlay
+    overlay_html = render_overlay()  # default: no overlay
+
+    # Check for Reader Noticed
+    if updated_state.get("meta_exposure", 0) >= 100 and prev_meta < 100:
+        overlay_html = render_overlay("reader_noticed")
+    # Check for scenario completion
+    elif ai_response.get("scenario_complete"):
+        rank = ai_response.get("scenario_rank", "C")
+        overlay_html = render_overlay("ranking", {"rank": rank})
+        # After a moment, show next scenario announcement
+        next_num = updated_state.get("scenario_num", scenario_num)
+        if next_num != scenario_num and next_num in SCENARIOS:
+            # The ranking overlay will auto-dismiss, then we need the next scenario
+            pass  # Handled on next turn start
+    # Check for game over
+    elif updated_state.get("game_over"):
+        overlay_html = render_overlay("game_over", {
+            "reason": updated_state.get("game_over_reason", "You have died.")
+        })
+    # Check for big moment
+    elif ai_response.get("big_moment"):
+        # For now, use reader_noticed image as a "big moment" visual
+        pass
+
+    # Extract display data from AI response
+    narrative = ai_response.get("narrative", "Something happens...")
+    dokkaebi_comment = ai_response.get("dokkaebi_comment", "...")
+    reality_subversion = ai_response.get("reality_subversion")
+    suggestions = ai_response.get("suggestions", [])
+    constellation_reactions = ai_response.get("constellation_reactions", [])
+
+    # Add damage flash trigger data
+    took_damage = updated_state.get("hp", 100) < prev_hp
+    meta_increased = updated_state.get("meta_exposure", 0) > prev_meta
+
+    # Build JS trigger data
+    js_triggers = {
+        "damage": took_damage,
+        "meta_up": meta_increased,
+        "coins_gained": ai_response.get("entertainment_score", 0) > 5,
+        "big_moment": ai_response.get("big_moment", False),
+    }
+    trigger_data = json.dumps(js_triggers)
+
+    # Inject JS triggers into state data element
+    state_with_triggers = (
+        f'<div id="game-state-data" style="display:none;" '
+        f'data-state=\'{json.dumps(updated_state)}\' '
+        f'data-triggers=\'{trigger_data}\'></div>'
+    )
+
+    available_skills = [s for s, d in updated_state.get("skills", {}).items() if d.get("cooldown", 0) <= 0]
+
+    return (
+        updated_state,                                                      # updated state
+        render_scenario_header(updated_state),                              # scenario header
+        render_player_panel(updated_state),                                 # player panel
+        render_meters(updated_state),                                       # meters
+        render_scene(updated_state),                                        # scene
+        render_narrative(narrative, dokkaebi_comment, reality_subversion),   # narrative
+        render_suggestions(suggestions),                                    # suggestions
+        render_star_stream(updated_state, constellation_reactions),          # star stream
+        overlay_html,                                                       # overlay
+        state_with_triggers,                                                # state data for JS
+        "",                                                                 # clear input
+        gr.update(choices=available_skills),                                # update active skills dropdown
+    )
+
+
+# ——————————————————————————————————————————————————————————————————————————————
+# GRADIO APP — The UI
+# ——————————————————————————————————————————————————————————————————————————————
+
+# Combine all CSS (no duplicates)
+_ALL_CSS = _STYLE_CSS + "\n" + _ANIMATIONS_CSS
+
+# Head injection: only the game JS script (CSS already in _ALL_CSS)
+_HEAD_HTML = f"""
+<script>{_GAME_JS}</script>
+"""
+
+# Cinematic overlay HTML — injected as gr.HTML in the body so it actually renders
+_CINEMATIC_HTML = f"""
+<div id="orv-cinematic-overlay">
+
+    <!-- Video layer -->
+    <video id="orv-intro-video" muted playsinline preload="auto"
+           src="{_asset_url('intro_video.mp4')}">
+    </video>
+
+    <!-- Dark vignette over video -->
+    <div id="orv-cinematic-vignette"></div>
+
+    <!-- Skip button (top-right) -->
+    <button id="orv-skip-btn" onclick="window._skipCinematic()">
+        SKIP <span style="opacity:0.5;margin-left:4px;">&#9654;&#9654;</span>
+    </button>
+
+    <!-- Progress bar (bottom) -->
+    <div id="orv-cinematic-progress">
+        <div id="orv-cinematic-progress-bar"></div>
+    </div>
+
+    <!-- Loading text (bottom-center) -->
+    <div id="orv-cinematic-text">
+        Entering the Star Stream
+    </div>
+
+</div>
+"""
+
+
+
+# This runs AFTER Gradio mounts all Svelte components — guaranteed timing
+_INIT_JS = """
+function() {
+    var _gameReady = false;
+    var _cinematicDone = false;
+
+    // ── STYLE THE START BUTTON WITH CINZEL FONT ──
+    function styleStartButton() {
+        var btn = document.querySelector('#gradio-start-btn button');
+        if (!btn) { setTimeout(styleStartButton, 100); return; }
+
+        var applyFont = function(el) {
+            el.style.setProperty('font-family', "'Cinzel', serif", 'important');
+            el.style.setProperty('font-size', '14px', 'important');
+            el.style.setProperty('font-weight', '700', 'important');
+            el.style.setProperty('letter-spacing', '5px', 'important');
+            el.style.setProperty('text-transform', 'uppercase', 'important');
+        };
+        applyFont(btn);
+        btn.querySelectorAll('*').forEach(applyFont);
+        btn.style.setProperty('color', '#c06878', 'important');
+        btn.style.setProperty('background', 'linear-gradient(160deg,#1a0c12 0%,#2a101a 50%,#150a10 100%)', 'important');
+        btn.style.setProperty('border', '1px solid #904858', 'important');
+        btn.style.setProperty('border-radius', '0', 'important');
+        btn.style.setProperty('padding', '18px 64px', 'important');
+        btn.style.setProperty('box-shadow', '0 0 30px rgba(144,72,88,0.3)', 'important');
+
+        btn.addEventListener('mouseenter', function() {
+            this.style.setProperty('letter-spacing', '7px', 'important');
+            this.style.setProperty('color', '#e8c8d0', 'important');
+        });
+        btn.addEventListener('mouseleave', function() {
+            this.style.setProperty('letter-spacing', '5px', 'important');
+            this.style.setProperty('color', '#c06878', 'important');
+        });
+
+        // ── CLICK: START CINEMATIC ──
+        btn.addEventListener('click', function() {
+            startCinematic();
+        });
+    }
+    styleStartButton();
+
+    // ── CINEMATIC FLOW ──
+    function startCinematic() {
+        var overlay = document.getElementById('orv-cinematic-overlay');
+        var video = document.getElementById('orv-intro-video');
+        var progressBar = document.getElementById('orv-cinematic-progress-bar');
+        var skipBtn = document.getElementById('orv-skip-btn');
+
+        if (!overlay) return;
+
+        // Show the overlay
+        overlay.classList.add('active');
+
+        // Try to play video
+        if (video && video.src && !video.error) {
+            video.currentTime = 0;
+            var playPromise = video.play();
+            if (playPromise) {
+                playPromise.catch(function() {
+                    // Video failed — just show the overlay as loading screen
+                });
+            }
+
+            // Update progress bar
+            video.addEventListener('timeupdate', function() {
+                if (video.duration) {
+                    var pct = (video.currentTime / video.duration) * 100;
+                    if (progressBar) progressBar.style.width = pct + '%';
+                }
+            });
+
+            // Video ended naturally
+            video.addEventListener('ended', function() {
+                if (progressBar) progressBar.style.width = '100%';
+                finishCinematic();
+            });
+
+            // Show skip button after 2 seconds
+            setTimeout(function() {
+                if (skipBtn) {
+                    skipBtn.classList.add('visible');
+                }
+            }, 2000);
+        } else {
+            // No video available — just show loading text, auto-dismiss when game ready
+            if (skipBtn) skipBtn.style.display = 'none';
+        }
+    }
+
+    // ── SKIP / FINISH ──
+    window._skipCinematic = function() {
+        var video = document.getElementById('orv-intro-video');
+        if (video) { video.pause(); }
+        finishCinematic();
+    };
+
+    function finishCinematic() {
+        if (_cinematicDone) return;
+        _cinematicDone = true;
+
+        var overlay = document.getElementById('orv-cinematic-overlay');
+        if (!overlay) return;
+
+        if (_gameReady) {
+            // Game already loaded — fade out immediately
+            fadeOutOverlay(overlay);
+        } else {
+            // Game still loading — show "loading" state, wait
+            var text = document.getElementById('orv-cinematic-text');
+            if (text) text.textContent = 'Loading Scenario...';
+            var skipBtn = document.getElementById('orv-skip-btn');
+            if (skipBtn) skipBtn.classList.remove('visible');
+
+            // Poll until game is ready
+            var poll = setInterval(function() {
+                if (_gameReady) {
+                    clearInterval(poll);
+                    fadeOutOverlay(overlay);
+                }
+            }, 200);
+        }
+    }
+
+    function fadeOutOverlay(overlay) {
+        overlay.style.transition = 'opacity 1s ease';
+        overlay.style.opacity = '0';
+        setTimeout(function() {
+            overlay.classList.remove('active');
+            overlay.style.opacity = '';
+            overlay.style.transition = '';
+        }, 1000);
+    }
+
+    // ── DETECT WHEN GAME IS LOADED ──
+    var observer = new MutationObserver(function() {
+        var header = document.querySelector('.game-header');
+        if (header && getComputedStyle(header).display !== 'none') {
+            _gameReady = true;
+            // If cinematic already done (skipped/ended), fade out now
+            if (_cinematicDone) {
+                var overlay = document.getElementById('orv-cinematic-overlay');
+                if (overlay && overlay.classList.contains('active')) {
+                    fadeOutOverlay(overlay);
+                }
+            }
+        }
+    });
+    observer.observe(document.body, { attributes: true, subtree: true, attributeFilter: ['style', 'class'] });
+}
+"""
+
+
+with gr.Blocks(
+    title="Omniscient Reader — Scenario Simulator",
+    elem_classes="game-container",
+) as demo:
+
+
+    # ----- Session State -----
+    game_state = gr.State(value=None)
+
+    # ===== START SCREEN =====
+    start_screen_html = gr.HTML(
+        render_start_screen(),
+        elem_classes="start-screen-container",
+    )
+    start_btn = gr.Button(
+        "⚡  Begin the Scenario",
+        elem_id="gradio-start-btn",
+        elem_classes="start-btn-visible",
+        variant="primary",
+    )
+
+    # ===== CINEMATIC OVERLAY — must be a gr.HTML so it renders in the body =====
+    cinematic_overlay = gr.HTML(_CINEMATIC_HTML, elem_id="cinematic-overlay-wrapper")
+
+    # ===== GAME HEADER (hidden initially) =====
+    with gr.Row(elem_classes="game-header", visible=False) as game_header:
+        scenario_header = gr.HTML(render_scenario_header({"scenario_num": 1, "turn": 1}))
+
+    # ===== MAIN GAME LAYOUT (hidden initially) =====
+    with gr.Row(elem_classes="game-main", visible=False) as game_main:
+
+        # --- LEFT: Player Panel ---
+        with gr.Column(scale=1, min_width=260, elem_classes="player-panel"):
+            player_panel = gr.HTML(render_player_panel(GameState().to_dict()))
+            meters_panel = gr.HTML(render_meters(GameState().to_dict()))
+            with gr.Accordion("Dokkaebi Bag", open=False, elem_classes=["system-window", "shop-accordion"]):
+                shop_item = gr.Dropdown(
+                    choices=[
+                        "Minor HP Potion (15c)", 
+                        "HP Potion (30c)", 
+                        "Major HP Potion (60c)",
+                        "Star Stream Flare (100c)",
+                        "Unbroken Faith (150c)", 
+                        "Probability Nullifier (200c)",
+                        "Random Attribute Box (250c)"
+                    ], 
+                    label="Select Item", 
+                    show_label=False
+                )
+                shop_buy_btn = gr.Button("💰 Buy Item", elem_classes="suggestion-btn")
+
+        # --- CENTER: Game Area ---
+        with gr.Column(scale=3, min_width=400, elem_classes="game-area"):
+            scene_display = gr.HTML('<div class="scene-placeholder"></div>')
+            narrative_display = gr.HTML(
+                '<div class="system-window"><div class="narrative-text">'
+                'Waiting for scenario to begin...</div></div>'
+            )
+            suggestions_display = gr.HTML(render_suggestions([]))
+
+        # --- RIGHT: Constellation Sidebar ---
+        with gr.Column(scale=1, min_width=280, elem_classes="constellation-panel"):
+            star_stream_display = gr.HTML(
+                render_star_stream(GameState().to_dict())
+            )
+
+    # ===== BOTTOM INPUT BAR (hidden initially) =====
+    with gr.Row(elem_classes="input-bar", visible=False) as input_bar:
+        with gr.Column(scale=1, min_width=150):
+            active_skills_dd = gr.Dropdown(choices=[], label="", show_label=False, elem_classes="game-input", container=False)
+            skill_btn = gr.Button("Use Skill", elem_classes="suggestion-btn")
+        with gr.Column(scale=4):
+            stance_radio = gr.Radio(["Neutral", "Aggressive", "Deceptive", "Empathetic", "Observant"], label="", show_label=False, value="Neutral", container=False)
+            player_input = gr.Textbox(
+                placeholder="What do you do, Incarnation?",
+                label="",
+                elem_classes="game-input",
+                max_lines=2,
+            )
+        submit_btn = gr.Button(
+            "âš¡ Act",
+            elem_classes="act-button",
+            variant="primary",
+            scale=1,
+        )
+
+    # ===== FULLSCREEN OVERLAY =====
+    overlay_display = gr.HTML(
+        render_overlay(),
+        elem_classes="overlay-container",
+    )
+
+    # ===== HIDDEN STATE DATA (for JS) =====
+    state_data = gr.HTML(
+        '<div id="game-state-data" style="display:none;"></div>',
+        visible=False,
+    )
+
+    # ----- Event Wiring -----
+
+    # Start button → initialize game
+    start_btn.click(
+        fn=start_game,
+        inputs=[],
+        outputs=[
+            game_state,
+            start_screen_html,
+            start_btn,
+            game_header,
+            game_main,
+            input_bar,
+            scenario_header,
+            player_panel,
+            meters_panel,
+            scene_display,
+            narrative_display,
+            suggestions_display,
+            star_stream_display,
+            overlay_display,
+            state_data,
+            player_input,
+            active_skills_dd,
+        ],
+    )
+
+    # Submit button → process action
+    submit_btn.click(
+        fn=take_action,
+        inputs=[stance_radio, player_input, game_state],
+        outputs=[
+            game_state,
+            scenario_header,
+            player_panel,
+            meters_panel,
+            scene_display,
+            narrative_display,
+            suggestions_display,
+            star_stream_display,
+            overlay_display,
+            state_data,
+            player_input,
+            active_skills_dd,
+        ],
+    )
+
+    # Enter key also submits
+    player_input.submit(
+        fn=take_action,
+        inputs=[stance_radio, player_input, game_state],
+        outputs=[
+            game_state,
+            scenario_header,
+            player_panel,
+            meters_panel,
+            scene_display,
+            narrative_display,
+            suggestions_display,
+            star_stream_display,
+            overlay_display,
+            state_data,
+            player_input,
+            active_skills_dd,
+        ],
+    )
+
+    # Buy Item logic
+    shop_buy_btn.click(
+        fn=buy_item_action,
+        inputs=[shop_item, game_state],
+        outputs=[game_state, player_panel]
+    )
+
+    # Use Skill logic
+    skill_btn.click(
+        fn=use_skill_action,
+        inputs=[active_skills_dd, player_input, game_state],
+        outputs=[game_state, player_input, active_skills_dd]
+    )
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# INJECT CSS & JS — Works on both local dev and HF Spaces
+# In Gradio 6, css and head are set on the demo object or passed to launch().
+# Setting them here ensures HF Spaces (which calls launch() internally) picks them up.
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+demo.css = _ALL_CSS
+demo.head = _HEAD_HTML
+
+if __name__ == "__main__":
+    import time
+
+    # allowed_paths: include both forward-slash and native paths
+    # Gradio 6 resolves to forward slashes internally on some routes
+    _abs_assets = os.path.abspath(_ASSET_DIR)
+    _fwd_assets = _abs_assets.replace("\\", "/")
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        allowed_paths=[_abs_assets, _fwd_assets, os.path.dirname(_abs_assets)],
+        show_error=True,
+        prevent_thread_lock=True,
+        css=_ALL_CSS,
+        head=_HEAD_HTML,
+        js=_INIT_JS,
+    )
+
+    print("ORV Scenario Simulator running at http://localhost:7860")
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+

assets/intro_video.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57af9f8db99e8c5cf53e2fc46560e8d72991d47d98b8945569d91192f9216371
+size 44349634

game.js

@@ -0,0 +1,866 @@
+/* ═══════════════════════════════════════════════════════════════════
+   ORV SCENARIO SIMULATOR — GAME.JS
+   Interactive effects, MutationObserver, event delegation
+   Vanilla JS · Self-contained IIFE · Gradio-compatible
+   ═══════════════════════════════════════════════════════════════════ */
+
+(function () {
+    'use strict';
+
+    // ── Constants ────────────────────────────────────────────────────
+    const TYPEWRITER_SPEED = 30;         // ms per character
+    const OVERLAY_DISMISS_MS = 5000;     // default overlay auto-dismiss
+    const SCENARIO_DISMISS_MS = 6000;    // scenario announcement duration
+    const COIN_RAIN_DEFAULT = 10;        // default particle count
+    const INIT_RETRY_DELAY = 2000;       // retry setup after Gradio loads
+    const DEBOUNCE_MS = 100;             // observer debounce
+
+    // ── State ────────────────────────────────────────────────────────
+    let _previousHP = null;
+    let _previousMeta = null;
+    let _typewriterActive = false;
+    let _observerSetup = false;
+    let _lastNarrativeText = '';
+    let _lastChatCount = 0;
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       1. TYPEWRITER EFFECT
+       ═════════════════════════════════════════════════════════════════ */
+
+    function applyTypewriter(element) {
+        if (!element) return;
+
+        // Skip if already being typed
+        if (element.dataset.typing === 'true') return;
+
+        const fullHTML = element.innerHTML;
+        const fullText = element.textContent || '';
+
+        // Skip if empty or very short (likely a partial update)
+        if (fullText.trim().length < 2) return;
+
+        // Skip if text hasn't changed
+        if (fullText === element.dataset.lastTyped) return;
+
+        element.dataset.typing = 'true';
+        element.dataset.lastTyped = fullText;
+        _typewriterActive = true;
+
+        // Work with text content to avoid breaking HTML mid-tag
+        // Strategy: reveal characters by expanding a clip
+        const wrapper = document.createElement('span');
+        wrapper.className = 'typewriter-wrapper';
+        wrapper.innerHTML = fullHTML;
+        wrapper.style.visibility = 'hidden';
+
+        // Measure full content
+        element.innerHTML = '';
+        element.appendChild(wrapper);
+
+        // Use character-by-character for plain text,
+        // or progressive innerHTML reveal for rich content
+        const isRichContent = fullHTML !== fullText;
+
+        if (isRichContent) {
+            // For HTML content: progressive reveal
+            _typewriterRichReveal(element, fullHTML, fullText);
+        } else {
+            // For plain text: character by character
+            _typewriterPlainReveal(element, fullText);
+        }
+    }
+
+    function _typewriterPlainReveal(element, text) {
+        element.innerHTML = '';
+        let index = 0;
+
+        const cursor = document.createElement('span');
+        cursor.className = 'typewriter-cursor';
+        cursor.textContent = '|';
+
+        function typeNext() {
+            if (index < text.length) {
+                // Add characters in small chunks for performance
+                const chunk = text.substring(index, index + 2);
+                element.insertBefore(
+                    document.createTextNode(chunk),
+                    cursor
+                );
+                index += 2;
+                element.appendChild(cursor);
+                element.scrollTop = element.scrollHeight;
+                setTimeout(typeNext, TYPEWRITER_SPEED);
+            } else {
+                // Typing complete
+                element.dataset.typing = 'false';
+                _typewriterActive = false;
+                // Remove cursor after a delay
+                setTimeout(() => {
+                    if (cursor.parentNode) cursor.remove();
+                }, 2000);
+            }
+        }
+
+        element.appendChild(cursor);
+        typeNext();
+    }
+
+    function _typewriterRichReveal(element, html, plainText) {
+        // For rich HTML: reveal by setting opacity on a wrapper
+        // and revealing character positions via max-width
+        element.innerHTML = '';
+
+        const container = document.createElement('div');
+        container.style.cssText = 'overflow:hidden; display:inline;';
+        container.innerHTML = html;
+        element.appendChild(container);
+
+        // Reveal the content progressively
+        const textNodes = _getTextNodes(container);
+        let totalRevealed = 0;
+        const totalChars = plainText.length;
+
+        // Initially hide all text
+        textNodes.forEach(node => {
+            const span = document.createElement('span');
+            span.style.visibility = 'hidden';
+            span.textContent = node.textContent;
+            span.dataset.fullText = node.textContent;
+            span.dataset.revealed = '0';
+            node.parentNode.replaceChild(span, node);
+        });
+
+        const hiddenSpans = container.querySelectorAll('span[data-full-text]');
+        let currentSpanIndex = 0;
+        let currentCharIndex = 0;
+
+        const cursor = document.createElement('span');
+        cursor.className = 'typewriter-cursor';
+        cursor.textContent = '|';
+        element.appendChild(cursor);
+
+        function revealNext() {
+            if (currentSpanIndex >= hiddenSpans.length) {
+                element.dataset.typing = 'false';
+                _typewriterActive = false;
+                setTimeout(() => {
+                    if (cursor.parentNode) cursor.remove();
+                }, 2000);
+                return;
+            }
+
+            const span = hiddenSpans[currentSpanIndex];
+            const full = span.dataset.fullText;
+
+            currentCharIndex += 2;
+            if (currentCharIndex >= full.length) {
+                span.style.visibility = 'visible';
+                span.textContent = full;
+                currentSpanIndex++;
+                currentCharIndex = 0;
+            } else {
+                span.style.visibility = 'visible';
+                span.textContent = full.substring(0, currentCharIndex);
+            }
+
+            element.scrollTop = element.scrollHeight;
+            setTimeout(revealNext, TYPEWRITER_SPEED);
+        }
+
+        revealNext();
+    }
+
+    function _getTextNodes(element) {
+        const nodes = [];
+        const walker = document.createTreeWalker(
+            element,
+            NodeFilter.SHOW_TEXT,
+            null,
+            false
+        );
+        let node;
+        while ((node = walker.nextNode())) {
+            if (node.textContent.trim().length > 0) {
+                nodes.push(node);
+            }
+        }
+        return nodes;
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       2. MUTATION OBSERVER SETUP
+       ═════════════════════════════════════════════════════════════════ */
+
+    function setupMutationObserver() {
+        if (_observerSetup) return;
+
+        const config = { childList: true, subtree: true, characterData: true };
+        let debounceTimer = null;
+
+        const observer = new MutationObserver((mutations) => {
+            // Debounce rapid updates
+            clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                handleMutations(mutations);
+            }, DEBOUNCE_MS);
+        });
+
+        // Observe the entire Gradio app container
+        const appRoot = document.querySelector('gradio-app') ||
+                        document.querySelector('.gradio-container') ||
+                        document.body;
+
+        observer.observe(appRoot, config);
+        _observerSetup = true;
+        console.log('[Dokkaebi System] MutationObserver active.');
+    }
+
+    function handleMutations(mutations) {
+        // ── Narrative text changed → typewriter ──
+        const narrative = document.querySelector('.narrative-text');
+        if (narrative) {
+            const currentText = narrative.textContent || '';
+            if (currentText !== _lastNarrativeText && currentText.trim().length > 0) {
+                _lastNarrativeText = currentText;
+                applyTypewriter(narrative);
+            }
+        }
+
+        // ── Constellation chat changed → scroll + slide-in ──
+        const chat = document.querySelector('.constellation-chat');
+        if (chat) {
+            const messages = chat.querySelectorAll('.chat-message');
+            if (messages.length > _lastChatCount) {
+                // New messages added — animate them
+                for (let i = _lastChatCount; i < messages.length; i++) {
+                    if (!messages[i].classList.contains('slide-in-right')) {
+                        messages[i].classList.add('slide-in-right');
+                    }
+                }
+                _lastChatCount = messages.length;
+                scrollStarStream();
+            }
+        }
+
+        // ── Fullscreen overlay appeared ──
+        const overlay = document.querySelector('.fullscreen-overlay');
+        if (overlay && overlay.innerHTML.trim().length > 0) {
+            const isVisible = overlay.offsetParent !== null ||
+                              getComputedStyle(overlay).display !== 'none';
+            if (isVisible) {
+                // Check if it's a scenario announcement
+                if (overlay.querySelector('.scenario-announcement')) {
+                    showScenarioAnnouncement();
+                }
+                // Check if it's Reader Noticed (class is on the overlay itself)
+                else if (overlay.classList.contains('reader-noticed')) {
+                    showReaderNoticed();
+                }
+                // Generic overlay — auto-dismiss
+                else {
+                    showOverlay(OVERLAY_DISMISS_MS);
+                }
+            }
+        }
+
+        // ── State effects from hidden component ──
+        const stateEl = document.getElementById('game-state-data');
+        if (stateEl) {
+            // Read data-state attribute (Python renders: data-state='...')
+            const stateJson = stateEl.dataset.state;
+            const triggersJson = stateEl.dataset.triggers;
+            if (stateJson && stateJson.trim().startsWith('{')) {
+                try {
+                    handleStateEffects(stateJson, triggersJson);
+                } catch (e) { console.warn('[Dokkaebi] State parse error:', e); }
+            }
+        }
+
+        // ── Shake class cleanup ──
+        if (document.body.classList.contains('shake')) {
+            // Will be cleaned up by animationend listener
+        }
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       3. EVENT DELEGATION
+       ═════════════════════════════════════════════════════════════════ */
+
+    function setupEventDelegation() {
+        // ── Suggestion button clicks ──
+        document.addEventListener('click', (e) => {
+            const btn = e.target.closest('.suggestion-btn');
+            if (!btn) return;
+
+            e.preventDefault();
+            e.stopPropagation();
+
+            const actionText = btn.dataset.action || btn.textContent.trim();
+            if (!actionText) return;
+
+            // Find Gradio textarea
+            const textarea = document.querySelector('.game-input textarea') ||
+                              document.querySelector('.game-input input[type="text"]');
+
+            if (textarea) {
+                // Use native setter to trigger Gradio's reactive binding
+                const descriptor = Object.getOwnPropertyDescriptor(
+                    window.HTMLTextAreaElement.prototype, 'value'
+                ) || Object.getOwnPropertyDescriptor(
+                    window.HTMLInputElement.prototype, 'value'
+                );
+
+                if (descriptor && descriptor.set) {
+                    descriptor.set.call(textarea, actionText);
+                } else {
+                    textarea.value = actionText;
+                }
+
+                // Dispatch events Gradio listens for
+                textarea.dispatchEvent(new Event('input', { bubbles: true }));
+                textarea.dispatchEvent(new Event('change', { bubbles: true }));
+
+                // Visual feedback on the button
+                btn.style.borderColor = '#904858';
+                btn.style.boxShadow = '0 0 10px rgba(192,104,120,0.25)';
+                btn.style.color = '#c06878';
+
+                // Click submit after a brief delay
+                setTimeout(() => {
+                    const submitBtn = document.querySelector('.act-button') ||
+                                      document.querySelector('button[type="submit"]');
+                    if (submitBtn) submitBtn.click();
+
+                    // Reset button style
+                    setTimeout(() => {
+                        btn.style.borderColor = '';
+                        btn.style.boxShadow = '';
+                    }, 200);
+                }, 100);
+            }
+        });
+
+        // ── Fullscreen overlay click dismiss ──
+        document.addEventListener('click', (e) => {
+            const overlay = e.target.closest('.fullscreen-overlay');
+            if (overlay && !overlay.classList.contains('reader-noticed')) {
+                dismissOverlay(overlay);
+            }
+        });
+
+        // ── Shake animation cleanup ──
+        document.addEventListener('animationend', (e) => {
+            if (e.animationName === 'shake') {
+                e.target.classList.remove('shake');
+            }
+            if (e.animationName === 'damageFlash') {
+                e.target.remove();
+            }
+        });
+
+        // ── Keyboard shortcut: Enter to submit ──
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter' && !e.shiftKey) {
+                const textarea = document.querySelector('.game-input textarea');
+                if (textarea && document.activeElement === textarea) {
+                    const value = textarea.value.trim();
+                    if (value.length > 0) {
+                        e.preventDefault();
+                        const submitBtn = document.querySelector('.act-button');
+                        if (submitBtn) submitBtn.click();
+                    }
+                }
+            }
+        });
+
+        console.log('[Dokkaebi System] Event delegation active.');
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       4. OVERLAY MANAGEMENT
+       ═════════════════════════════════════════════════════════════════ */
+
+    function showOverlay(duration) {
+        duration = duration || OVERLAY_DISMISS_MS;
+        const overlay = document.querySelector('.fullscreen-overlay');
+        if (!overlay) return;
+
+        // Ensure it's visible
+        overlay.style.display = 'flex';
+        overlay.classList.add('fade-in');
+
+        // Auto-dismiss
+        setTimeout(() => {
+            dismissOverlay(overlay);
+        }, duration);
+    }
+
+    function dismissOverlay(overlay) {
+        overlay = overlay || document.querySelector('.fullscreen-overlay');
+        if (!overlay) return;
+
+        overlay.classList.remove('fade-in');
+        overlay.classList.add('fade-out');
+
+        setTimeout(() => {
+            overlay.style.setProperty('display', 'none', 'important');
+            overlay.classList.remove('fade-out');
+            // Remove the flash class if it was a scenario overlay
+            overlay.classList.remove('scenario-flash');
+        }, 500);
+    }
+
+    function showScenarioAnnouncement() {
+        const overlay = document.querySelector('.fullscreen-overlay');
+        if (!overlay) return;
+
+        // Add flash effect
+        overlay.classList.add('scenario-flash');
+        overlay.style.display = 'flex';
+
+        // Play a subtle screen effect
+        const announcement = overlay.querySelector('.scenario-announcement');
+        if (announcement) {
+            announcement.classList.add('scale-up');
+        }
+
+        // Auto-dismiss after duration
+        setTimeout(() => {
+            dismissOverlay(overlay);
+            if (announcement) {
+                announcement.classList.remove('scale-up');
+            }
+            overlay.classList.remove('scenario-flash');
+        }, SCENARIO_DISMISS_MS);
+    }
+
+    function showReaderNoticed() {
+        // Apply full-screen glitch — DO NOT auto-dismiss
+        document.body.classList.add('glitch-effect', 'static-noise');
+
+        const overlay = document.querySelector('.fullscreen-overlay');
+        if (overlay) {
+            overlay.style.display = 'flex';
+            overlay.classList.add('fade-in');
+        }
+
+        // Shake the screen
+        triggerScreenShake();
+
+        // Apply glitch text to the overlay content
+        const content = overlay ? overlay.querySelector('.reader-noticed') : null;
+        if (content) {
+            content.classList.add('glitch-text');
+        }
+
+        console.log('[Dokkaebi System] ⚠ The Reader has noticed you.');
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       5. STAR STREAM AUTO-SCROLL
+       ═════════════════════════════════════════════════════════════════ */
+
+    function scrollStarStream() {
+        const chat = document.querySelector('.constellation-chat');
+        if (chat) {
+            // Smooth scroll to bottom
+            requestAnimationFrame(() => {
+                chat.scrollTo({
+                    top: chat.scrollHeight,
+                    behavior: 'smooth'
+                });
+            });
+        }
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       6. COIN RAIN PARTICLES
+       ═════════════════════════════════════════════════════════════════ */
+
+    function spawnCoinRain(container, count) {
+        container = container || document.body;
+        count = count || COIN_RAIN_DEFAULT;
+
+        for (let i = 0; i < count; i++) {
+            const coin = document.createElement('div');
+            coin.className = 'coin-particle';
+
+            // Randomize position and timing
+            const startX = Math.random() * 100;
+            const duration = 1 + Math.random() * 1.5;
+            const delay = Math.random() * 0.5;
+            const size = 4 + Math.random() * 6;
+
+            coin.style.cssText = `
+                --start-x: ${startX}%;
+                --fall-duration: ${duration}s;
+                left: ${startX}%;
+                top: -10px;
+                width: ${size}px;
+                height: ${size}px;
+                animation-delay: ${delay}s;
+                position: absolute;
+            `;
+
+            container.style.position = container.style.position || 'relative';
+            container.appendChild(coin);
+
+            // Remove after animation
+            setTimeout(() => {
+                if (coin.parentNode) coin.remove();
+            }, (duration + delay) * 1000 + 200);
+        }
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       7. SCREEN EFFECTS
+       ═════════════════════════════════════════════════════════════════ */
+
+    function triggerDamageFlash() {
+        // Shake the screen
+        triggerScreenShake();
+
+        // Create red flash overlay
+        const flash = document.createElement('div');
+        flash.className = 'damage-flash-overlay';
+        document.body.appendChild(flash);
+
+        // Clean up after animation
+        setTimeout(() => {
+            if (flash.parentNode) flash.remove();
+        }, 500);
+    }
+
+    function triggerScreenShake() {
+        document.body.classList.add('shake');
+        setTimeout(() => {
+            document.body.classList.remove('shake');
+        }, 500);
+    }
+
+    function triggerGlitchEffect() {
+        document.body.classList.add('glitch-effect', 'static-noise');
+        // Permanent — Reader Noticed doesn't go away
+    }
+
+    function clearGlitchEffect() {
+        document.body.classList.remove('glitch-effect', 'static-noise');
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       8. GAME STATE DRIVEN EFFECTS
+       ═════════════════════════════════════════════════════════════════ */
+
+    function handleStateEffects(stateJson, triggersJson) {
+        let state, triggers;
+        try {
+            state = typeof stateJson === 'string' ? JSON.parse(stateJson) : stateJson;
+        } catch (e) {
+            return;
+        }
+        try {
+            triggers = triggersJson && typeof triggersJson === 'string' ? JSON.parse(triggersJson) : (triggersJson || {});
+        } catch (e) {
+            triggers = {};
+        }
+
+        // ── Meta Exposure visual effects ──
+        if (typeof state.meta_exposure === 'number') {
+            document.body.classList.remove('meta-warning', 'meta-critical');
+
+            if (state.meta_exposure >= 75) {
+                document.body.classList.add('meta-critical');
+                // Pulse the meta bar
+                const metaBar = document.querySelector('.stat-bar-meta');
+                if (metaBar) metaBar.classList.add('meter-danger');
+            } else if (state.meta_exposure >= 50) {
+                document.body.classList.add('meta-warning');
+                const metaBar = document.querySelector('.stat-bar-meta');
+                if (metaBar) {
+                    metaBar.classList.remove('meter-danger');
+                    metaBar.classList.add('meter-pulse');
+                    setTimeout(() => metaBar.classList.remove('meter-pulse'), 1000);
+                }
+            } else {
+                const metaBar = document.querySelector('.stat-bar-meta');
+                if (metaBar) {
+                    metaBar.classList.remove('meter-danger', 'meter-pulse');
+                }
+            }
+
+            // Track meta changes
+            if (_previousMeta !== null && state.meta_exposure > _previousMeta) {
+                const metaFill = document.querySelector('.stat-bar-meta .stat-bar-fill');
+                if (metaFill) {
+                    metaFill.classList.add('meter-pulse');
+                    setTimeout(() => metaFill.classList.remove('meter-pulse'), 1000);
+                }
+            }
+            _previousMeta = state.meta_exposure;
+        }
+
+        // ── Phase visual effects ──
+        if (state.current_phase) {
+            document.body.classList.remove('phase-combat', 'phase-safe-zone', 'phase-exploration');
+            const phaseClass = 'phase-' + state.current_phase.toLowerCase().replace(/\s+/g, '-');
+            document.body.classList.add(phaseClass);
+        }
+
+        // ── HP damage detection (via triggers.damage) ──
+        if (typeof state.hp === 'number') {
+            const tookDamage = triggers.damage === true ||
+                               (_previousHP !== null && state.hp < _previousHP);
+            if (tookDamage) {
+                triggerDamageFlash();
+                const hpBar = document.querySelector('.stat-bar-hp');
+                if (hpBar) {
+                    const pct = state.hp / (state.max_hp || 100);
+                    if (pct > 0.6) hpBar.dataset.percent = 'high';
+                    else if (pct > 0.3) hpBar.dataset.percent = 'mid';
+                    else hpBar.dataset.percent = 'low';
+                }
+            }
+            _previousHP = state.hp;
+        }
+
+        // ── Coin gain detection (via triggers.coins_gained) ──
+        if (triggers.coins_gained === true) {
+            const playerPanel = document.querySelector('.player-panel');
+            spawnCoinRain(playerPanel || document.body, 12);
+        }
+
+        // ── Rank display ──
+        if (state.show_rank) {
+            const rankDisplay = document.querySelector('.ranking-display');
+            if (rankDisplay) {
+                const rank = state.show_rank.toLowerCase();
+                rankDisplay.classList.add(`rank-${rank}`);
+            }
+        }
+
+        // ── Reader Noticed ──
+        if (state.reader_noticed) {
+            triggerGlitchEffect();
+        }
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       9. STAT BAR ANIMATION HELPER
+       ═════════════════════════════════════════════════════════════════ */
+
+    function animateStatBars() {
+        const fills = document.querySelectorAll('.stat-bar-fill');
+        fills.forEach(fill => {
+            const targetWidth = fill.style.width;
+            if (targetWidth && !fill.dataset.animated) {
+                // Force a reflow to trigger the CSS transition
+                fill.style.width = '0%';
+                fill.offsetHeight; // trigger reflow
+                fill.style.width = targetWidth;
+                fill.dataset.animated = 'true';
+            }
+        });
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       10. START SCREEN EFFECTS
+       ═════════════════════════════════════════════════════════════════ */
+
+    function setupStartScreen() {
+        const title = document.querySelector('.game-title');
+        if (title && !title.classList.contains('floating')) {
+            title.classList.add('floating');
+        }
+
+        const startBtn = document.querySelector('.start-btn');
+        if (startBtn && !startBtn.classList.contains('glow-pulse')) {
+            startBtn.classList.add('glow-pulse');
+        }
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       11. ORV TEXT FORMATTING HELPER
+       ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Formats raw text with ORV-style markup:
+     * [Text] → <span class="bracket-text">[Text]</span>
+     * 'Skill Name' inside brackets → <span class="skill-name">'Skill Name'</span>
+     * 999 coins → <span class="coins-display">999</span>
+     */
+    function formatORVText(text) {
+        if (!text) return text;
+
+        // Bracket text: [something]
+        text = text.replace(/\[([^\]]+)\]/g, (match, inner) => {
+            // Check for skill names within: 'Name'
+            const formatted = inner.replace(/'([^']+)'/g,
+                '<span class="skill-name">\'$1\'</span>'
+            );
+            return `<span class="bracket-text">[${formatted}]</span>`;
+        });
+
+        // Coin amounts: X coins
+        text = text.replace(/(\d+)\s*coins?/gi,
+            '<span class="coins-display">$1</span> coins'
+        );
+
+        return text;
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       12. AMBIENT BACKGROUND EFFECTS
+       ═════════════════════════════════════════════════════════════════ */
+
+    function spawnAmbientParticles() {
+        const container = document.querySelector('.game-area');
+        if (!container) return;
+
+        // Create a few floating particles for atmosphere
+        for (let i = 0; i < 5; i++) {
+            const particle = document.createElement('div');
+            const x = Math.random() * 100;
+            const y = Math.random() * 100;
+            const size = 1 + Math.random() * 2;
+            const duration = 8 + Math.random() * 12;
+            const delay = Math.random() * 5;
+
+            particle.style.cssText = `
+                position: absolute;
+                left: ${x}%;
+                top: ${y}%;
+                width: ${size}px;
+                height: ${size}px;
+                background: rgba(201, 168, 76, 0.12);
+                border-radius: 50%;
+                pointer-events: none;
+                z-index: 0;
+                animation: float ${duration}s ease-in-out ${delay}s infinite;
+                opacity: 0.3;
+            `;
+
+            container.style.position = container.style.position || 'relative';
+            container.appendChild(particle);
+        }
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       13. AUDIO FEEDBACK (visual-only fallback)
+       ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Provides visual "click" feedback when audio isn't available.
+     * Creates a brief ripple at the click location.
+     */
+    function clickRipple(e) {
+        const ripple = document.createElement('div');
+        ripple.style.cssText = `
+            position: fixed;
+            left: ${e.clientX - 15}px;
+            top: ${e.clientY - 15}px;
+            width: 30px;
+            height: 30px;
+            border: 1px solid rgba(74, 158, 255, 0.4);
+            border-radius: 50%;
+            pointer-events: none;
+            z-index: 99999;
+            animation: scaleUp 0.4s ease-out forwards;
+            opacity: 0.6;
+        `;
+        document.body.appendChild(ripple);
+        setTimeout(() => {
+            if (ripple.parentNode) ripple.remove();
+        }, 400);
+    }
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       14. INITIALIZATION
+       ═════════════════════════════════════════════════════════════════ */
+
+    function initialize() {
+        console.log('[Dokkaebi System] Initializing Scenario Simulator...');
+
+        setupMutationObserver();
+        setupEventDelegation();
+        setupStartScreen();
+
+        // Initial stat bar animation
+        setTimeout(animateStatBars, 500);
+
+        // Ambient particles (subtle)
+        setTimeout(spawnAmbientParticles, 1000);
+
+        console.log('[Dokkaebi System] Scenario Simulator initialized.');
+        console.log('[Dokkaebi System] ──────────────────────────────────');
+        console.log('[Dokkaebi System] "The scenario has begun."');
+        console.log('[Dokkaebi System] ──────────────────────────────────');
+    }
+
+    // ── Run on DOMContentLoaded ──
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initialize);
+    } else {
+        // DOM already loaded
+        initialize();
+    }
+
+    // ── Retry after Gradio finishes rendering ──
+    // Gradio rebuilds the DOM after initial load, so we need to re-init
+    setTimeout(() => {
+        if (!_observerSetup) {
+            console.log('[Dokkaebi System] Retry initialization (Gradio late load)...');
+            initialize();
+        }
+        // Re-check start screen
+        setupStartScreen();
+        // Re-animate stat bars
+        animateStatBars();
+        // Re-scroll chat
+        scrollStarStream();
+    }, INIT_RETRY_DELAY);
+
+    // Additional retry for very slow Gradio loads
+    setTimeout(() => {
+        setupStartScreen();
+        animateStatBars();
+        scrollStarStream();
+    }, 4000);
+
+
+    /* ═════════════════════════════════════════════════════════════════
+       15. EXPOSE API (for Gradio's inline script calls)
+       ═════════════════════════════════════════════════════════════════ */
+
+    // Expose key functions globally so Gradio inline JS can call them
+    window.ORVGame = {
+        typewriter: applyTypewriter,
+        damageFlash: triggerDamageFlash,
+        screenShake: triggerScreenShake,
+        glitch: triggerGlitchEffect,
+        clearGlitch: clearGlitchEffect,
+        coinRain: spawnCoinRain,
+        scrollChat: scrollStarStream,
+        showOverlay: showOverlay,
+        dismissOverlay: dismissOverlay,
+        showScenario: showScenarioAnnouncement,
+        showReaderNoticed: showReaderNoticed,
+        handleState: handleStateEffects,
+        formatText: formatORVText,
+        animateBars: animateStatBars,
+    };
+
+})();

game_engine.py

@@ -0,0 +1,625 @@
+"""
+game_engine.py — Core Game State & Turn Processing
+===================================================
+Contains the GameState class, stat management, hidden scenario triggers,
+and the main turn-processing pipeline for the ORV Scenario Simulator.
+
+Part of the ORV (Omniscient Reader's Viewpoint) Scenario Simulator.
+Build Small Hackathon 2026.
+"""
+
+import copy
+import json
+from typing import Any
+
+from scenarios import SCENARIOS
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# CONSTELLATION NAME MAPPING
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+_CONSTELLATION_DISPLAY_NAMES: dict[str, str] = {
+    "abyssal_black_flame_dragon": "Abyssal Black Flame Dragon",
+    "secretive_plotter": "Secretive Plotter",
+    "demon_like_judge": "Demon-like Judge of Fire",
+    "maritime_war_god": "Maritime War God",
+    "prisoner_golden_headband": "Prisoner of the Golden Headband",
+}
+
+_TRUST_DISPLAY_NAMES: dict[str, str] = {
+    "yoo_sangah": "Yoo Sangah",
+    "lee_hyunsung": "Lee Hyunsung",
+    "jung_heewon": "Jung Heewon",
+    "han_sooyoung": "Han Sooyoung",
+}
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# GAME STATE CLASS
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+class GameState:
+    """
+    Encapsulates the full mutable state of an ORV Scenario Simulator session.
+
+    The internal ``state`` dict is the canonical representation and is
+    serialisable to / from plain dicts for Gradio ``gr.State`` transport.
+    """
+
+    def __init__(self) -> None:
+        self.state: dict[str, Any] = {
+            "player_name": "Kim Dokja",
+            "hp": 100,
+            "max_hp": 100,
+            "coins": 0,
+            "scenario_num": 1,
+            "turn": 1,
+            "total_turns": 0,
+            "current_phase": "Exploration",
+            "active_debuffs": [],
+            "meta_exposure": 0,
+            "prob_stability": 100,
+            "entertainment": 0,
+            "titles": [],
+            "attributes": ["Omniscient Reader's Viewpoint (Hidden)"],
+            "skills": {
+                "Fourth Wall": {"level": 1, "cooldown": 0, "max_cooldown": 2},
+                "Bookmark": {"level": 1, "cooldown": 0, "max_cooldown": 3},
+                "Omniscient Reader's Viewpoint": {"level": 1, "cooldown": 0, "max_cooldown": 4}
+            },
+            "inventory": [],
+            "sponsor": None,
+            "trust": {
+                "yoo_sangah": 0,
+                "lee_hyunsung": 0,
+                "jung_heewon": 0,
+                "han_sooyoung": 0,
+            },
+            "constellation_affinity": {
+                "abyssal_black_flame_dragon": 0,
+                "secretive_plotter": 0,
+                "demon_like_judge": 0,
+                "maritime_war_god": 0,
+                "prisoner_golden_headband": 0,
+            },
+            "unique_constellations": [],
+            "action_history": [],
+            "action_tags": [],
+            "hidden_scenarios_triggered": [],
+            "scenario_rankings": [],
+            "star_stream_history": [],
+            "game_over": False,
+            "game_over_reason": None,
+        }
+
+    # ------------------------------------------------------------------
+    # Stat Management
+    # ------------------------------------------------------------------
+
+    def apply_stat_changes(self, changes: dict[str, Any]) -> None:
+        """
+        Apply a ``stat_changes`` dict returned by the AI.
+
+        Handles top-level numeric fields (hp, coins, meta_exposure,
+        prob_stability) as well as nested ``trust`` and
+        ``constellation_affinity`` sub-dicts.
+
+        All values are clamped to their valid ranges after application.
+        """
+        s = self.state
+
+        # --- Top-level numeric stats ---
+        s["hp"] = max(0, min(s["max_hp"], s["hp"] + changes.get("hp", 0)))
+        s["coins"] = max(0, s["coins"] + changes.get("coins", 0))
+        s["meta_exposure"] = max(
+            0, min(100, s["meta_exposure"] + changes.get("meta_exposure", 0))
+        )
+        s["prob_stability"] = max(
+            0, min(100, s["prob_stability"] + changes.get("prob_stability", 0))
+        )
+
+        # --- Trust sub-dict ---
+        trust_changes = changes.get("trust", {})
+        for key, delta in trust_changes.items():
+            if key in s["trust"]:
+                s["trust"][key] = max(0, s["trust"][key] + delta)
+
+        # --- Constellation affinity sub-dict ---
+        affinity_changes = changes.get("constellation_affinity", {})
+        for key, delta in affinity_changes.items():
+            if key in s["constellation_affinity"]:
+                s["constellation_affinity"][key] = max(
+                    0, s["constellation_affinity"][key] + delta
+                )
+
+    def add_coins_from_entertainment(self, score: int) -> None:
+        """Add entertainment-based coin reward (score × 10)."""
+        self.state["coins"] += score * 10
+        self.state["entertainment"] += score
+
+    def add_coins_from_constellations(self, reactions: list[dict[str, Any]]) -> None:
+        """Sum coin donations from all constellation reactions."""
+        for reaction in reactions:
+            coins = reaction.get("coins", 0)
+            if isinstance(coins, (int, float)) and coins > 0:
+                self.state["coins"] += int(coins)
+
+    def buy_item(self, item_name: str, cost: int) -> bool:
+        """Attempt to buy an item from the Dokkaebi Bag."""
+        if self.state["coins"] >= cost:
+            self.state["coins"] -= cost
+            self.state["inventory"].append(item_name)
+            return True
+        return False
+
+    # ------------------------------------------------------------------
+    # History
+    # ------------------------------------------------------------------
+
+    def add_to_history(self, action: str, tags: list[str]) -> None:
+        """
+        Record a player action and associated tags.
+
+        ``action_history`` is capped at the 10 most recent entries.
+        ``action_tags`` grows unbounded (used for pattern detection).
+        """
+        self.state["action_history"].append(action)
+        if len(self.state["action_history"]) > 10:
+            self.state["action_history"] = self.state["action_history"][-10:]
+
+        self.state["action_tags"].extend(tags)
+
+    # ------------------------------------------------------------------
+    # Hidden Scenario Triggers
+    # ------------------------------------------------------------------
+
+    def check_hidden_scenarios(self) -> str | None:
+        """
+        Evaluate behavioural patterns against hidden scenario triggers.
+
+        Returns the scenario name if a new hidden scenario should fire,
+        or ``None`` if nothing triggers.
+
+        Trigger rules
+        -------------
+        - **The Last Good Human**: 5+ ``'save'`` tags in action_tags.
+        - **The Reader's Trial**: ``meta_exposure >= 75``.
+        - **A Throne Built on Corpses**: 3+ ``'betray'`` tags.
+        - **One Who Rejects Fate**: 3+ ``'reject'`` tags.
+        - **The Untouchable**: completed 3+ scenarios with HP still at max.
+        """
+        tags = self.state["action_tags"]
+        triggered = self.state["hidden_scenarios_triggered"]
+
+        # The Reader's Trial — highest priority
+        if (
+            self.state["meta_exposure"] >= 75
+            and "The Reader's Trial" not in triggered
+        ):
+            return "The Reader's Trial"
+
+        # The Last Good Human
+        if tags.count("save") >= 5 and "The Last Good Human" not in triggered:
+            return "The Last Good Human"
+
+        # A Throne Built on Corpses
+        if tags.count("betray") >= 3 and "A Throne Built on Corpses" not in triggered:
+            return "A Throne Built on Corpses"
+
+        # One Who Rejects Fate
+        if tags.count("reject") >= 3 and "One Who Rejects Fate" not in triggered:
+            return "One Who Rejects Fate"
+
+        # The Untouchable
+        if (
+            len(self.state["scenario_rankings"]) >= 3
+            and self.state["hp"] == self.state["max_hp"]
+            and "The Untouchable" not in triggered
+        ):
+            return "The Untouchable"
+
+        return None
+
+    # ------------------------------------------------------------------
+    # Game-Over & Scenario Advancement
+    # ------------------------------------------------------------------
+
+    def check_game_over(self) -> bool:
+        """Check if the player is dead. Sets game_over flags if so."""
+        if self.state["hp"] <= 0:
+            self.state["game_over"] = True
+            self.state["game_over_reason"] = "Death"
+            return True
+        return False
+
+    def advance_scenario(self, rank: str | None) -> None:
+        """
+        Complete the current scenario, store its rank, and advance.
+
+        Parameters
+        ----------
+        rank : str | None
+            The rank the player earned (e.g. "S", "A", "B", "C", "F").
+        """
+        self.state["scenario_rankings"].append(rank or "C")
+        
+        # Determine next scenario
+        current = self.state["scenario_num"]
+        if current == 1:
+            next_s = 1.5
+        elif current == 1.5:
+            next_s = 2
+        elif current == 2:
+            next_s = 3
+        else:
+            next_s = current + 1
+            
+        self.state["scenario_num"] = next_s
+        self.state["turn"] = 1
+        self.state["current_phase"] = "Exploration"
+
+    # ------------------------------------------------------------------
+    # Meta Level
+    # ------------------------------------------------------------------
+
+    def get_meta_level(self) -> str:
+        """
+        Return a human-readable meta-exposure tier.
+
+        Tiers:
+            0-24   → ``'normal'``
+            25-49  → ``'suspicious'``
+            50-74  → ``'unstable'``
+            75-99  → ``'breaking'``
+            100    → ``'noticed'``
+        """
+        me = self.state["meta_exposure"]
+        if me >= 100:
+            return "noticed"
+        if me >= 75:
+            return "breaking"
+        if me >= 50:
+            return "unstable"
+        if me >= 25:
+            return "suspicious"
+        return "normal"
+
+    # ------------------------------------------------------------------
+    # Sponsor System
+    # ------------------------------------------------------------------
+
+    def check_sponsor_threshold(self) -> str | None:
+        """
+        Check if any constellation's affinity has reached the sponsor
+        threshold (≥ 50).
+
+        Returns the display name of the first qualifying constellation,
+        or ``None``.
+        """
+        for key, value in self.state["constellation_affinity"].items():
+            if value >= 50:
+                return _CONSTELLATION_DISPLAY_NAMES.get(
+                    key, key.replace("_", " ").title()
+                )
+        return None
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a deep copy of the state dict (safe for gr.State)."""
+        return copy.deepcopy(self.state)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "GameState":
+        """
+        Reconstruct a GameState from a plain dict.
+
+        Parameters
+        ----------
+        d : dict
+            A state dict previously produced by ``to_dict()``.
+
+        Returns
+        -------
+        GameState
+            A new GameState instance with the restored state.
+        """
+        gs = cls()
+        gs.state = copy.deepcopy(d)
+        return gs
+
+    # ------------------------------------------------------------------
+    # Prompt Context Builder
+    # ------------------------------------------------------------------
+
+    def to_prompt_context(self) -> str:
+        """
+        Return a formatted, human-readable summary of the game state
+        suitable for injection into the Dokkaebi system prompt.
+
+        Only includes non-zero trust / affinity values to keep the
+        context window efficient.
+        """
+        s = self.state
+        lines: list[str] = [
+            f"Player: {s['player_name']}",
+            f"HP: {s['hp']}/{s['max_hp']}",
+            f"Coins: {s['coins']}",
+            f"Scenario: {s['scenario_num']} | Turn: {s['turn']} | Total Turns: {s['total_turns']}",
+            f"Current Phase: {s['current_phase']}",
+            f"Meta Level: {self.get_meta_level()} ({s['meta_exposure']}%)",
+            f"Probability Stability: {s['prob_stability']}%",
+        ]
+
+        if s.get("active_debuffs"):
+            lines.append(f"Active Debuffs: {', '.join(s['active_debuffs'])}")
+        if s["titles"]:
+            lines.append(f"Titles: {', '.join(s['titles'])}")
+        if s["skills"]:
+            skills_str = ", ".join([f"{name} (Lv.{data.get('level', 1)})" for name, data in s["skills"].items()])
+            lines.append(f"Skills: {skills_str}")
+        if s["inventory"]:
+            lines.append(f"Inventory: {', '.join(s['inventory'])}")
+        if s["sponsor"]:
+            lines.append(f"Sponsor: {s['sponsor']}")
+
+        # Trust — only non-zero
+        non_zero_trust = {
+            _TRUST_DISPLAY_NAMES.get(k, k): v
+            for k, v in s["trust"].items()
+            if v != 0
+        }
+        if non_zero_trust:
+            trust_str = ", ".join(f"{name}: {val}" for name, val in non_zero_trust.items())
+            lines.append(f"Trust: {trust_str}")
+
+        # Constellation affinity — only non-zero
+        non_zero_aff = {
+            _CONSTELLATION_DISPLAY_NAMES.get(k, k): v
+            for k, v in s["constellation_affinity"].items()
+            if v != 0
+        }
+        if non_zero_aff:
+            aff_str = ", ".join(f"{name}: {val}" for name, val in non_zero_aff.items())
+            lines.append(f"Constellation Affinity: {aff_str}")
+
+        # Recent actions (last 3)
+        recent = s["action_history"][-3:]
+        if recent:
+            lines.append(f"Recent Actions: {' → '.join(recent)}")
+
+        return "\n".join(lines)
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# STANDALONE FUNCTIONS
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def infer_action_tags(player_action: str, ai_response: dict[str, Any], stance: str = "") -> list[str]:
+    """
+    Derive behavioural tags from the player's action text and AI response.
+
+    Uses simple keyword matching on the lowercased action string.
+    Multiple tags can apply to a single action.
+
+    Tag rules
+    ---------
+    - ``'save'``   — action contains *save*, *help*, or *protect*
+    - ``'fight'``  — action contains *kill*, *attack*, or *fight*
+    - ``'betray'`` — action contains *betray*, *abandon*, or *steal*
+    - ``'avoid'``  — action contains *run*, *hide*, or *avoid*
+    - ``'meta'``   — AI flagged ``meta_detected`` as truthy
+    - ``'reject'`` — action contains *reject*, *refuse*, or *decline*
+
+    Parameters
+    ----------
+    player_action : str
+        The raw text the player typed.
+    ai_response : dict
+        The parsed AI response dict.
+
+    Returns
+    -------
+    list[str]
+        A (possibly empty) list of inferred tags.
+    """
+    tags: list[str] = []
+    action_lower = player_action.lower()
+
+    _TAG_KEYWORDS: dict[str, list[str]] = {
+        "save": ["save", "help", "protect"],
+        "fight": ["kill", "attack", "fight"],
+        "betray": ["betray", "abandon", "steal"],
+        "avoid": ["run", "hide", "avoid"],
+        "reject": ["reject", "refuse", "decline"],
+    }
+
+    for tag, keywords in _TAG_KEYWORDS.items():
+        if any(kw in action_lower for kw in keywords):
+            tags.append(tag)
+
+    if stance:
+        # map stance to specific tags
+        stance_lower = stance.lower()
+        if "aggressive" in stance_lower:
+            tags.append("fight")
+        elif "deceptive" in stance_lower:
+            tags.append("betray")
+        elif "empathetic" in stance_lower:
+            tags.append("save")
+        elif "observant" in stance_lower:
+            tags.append("meta")
+
+    if ai_response.get("meta_detected"):
+        tags.append("meta")
+
+    return tags
+
+
+def process_turn(
+    state_dict: dict[str, Any],
+    player_action: str,
+    ai_response: dict[str, Any],
+    stance: str = "",
+) -> dict[str, Any]:
+    """
+    Execute the full turn-processing pipeline.
+
+    This is the main entry point called after the AI has responded.
+    It mutates the game state based on the AI's output, handles all
+    side-effects (coins, sponsors, hidden scenarios, game-over), and
+    returns the updated state dict.
+
+    Pipeline
+    --------
+    1.  Reconstruct ``GameState`` from ``state_dict``.
+    2.  Apply ``stat_changes`` from the AI response.
+    3.  Add entertainment coins (``entertainment_score × 10``).
+    4.  Add constellation donation coins.
+    5.  Apply meta-exposure threshold penalties to ``prob_stability``.
+    6.  If ``meta_detected``, decrease ``prob_stability`` by 5.
+    7.  Handle ``new_title`` (append to titles list).
+    8.  Check for hidden scenario triggers.
+    9.  Handle scenario completion (``scenario_complete`` + ``scenario_rank``).
+    10. Check sponsor threshold.
+    11. Record action + inferred tags in history.
+    12. Check game-over condition.
+    13. Increment turn counters.
+    14. Return updated state dict.
+
+    Parameters
+    ----------
+    state_dict : dict
+        The serialised game state (from ``GameState.to_dict()``).
+    player_action : str
+        The text the player typed.
+    ai_response : dict
+        The parsed JSON response from the Dokkaebi AI.
+
+    Returns
+    -------
+    dict
+        The updated game state dict.
+    """
+    gs = GameState.from_dict(state_dict)
+
+    # 1-2. Apply stat changes
+    stat_changes = ai_response.get("stat_changes", {})
+    gs.apply_stat_changes(stat_changes)
+
+    # Decrement active skill cooldowns
+    for skill_name, skill_data in gs.state.get("skills", {}).items():
+        if skill_data.get("cooldown", 0) > 0:
+            skill_data["cooldown"] -= 1
+
+    # 3. Entertainment coins
+    entertainment_score = ai_response.get("entertainment_score", 0)
+    if isinstance(entertainment_score, (int, float)):
+        gs.add_coins_from_entertainment(int(entertainment_score))
+
+    # 4. Constellation donation coins
+    constellation_reactions = ai_response.get("constellation_reactions", [])
+    if isinstance(constellation_reactions, list):
+        gs.add_coins_from_constellations(constellation_reactions)
+
+    # 5. Meta-exposure threshold penalties (only applied once when crossing threshold)
+    # Track prev meta to detect crossing
+    prev_meta = state_dict.get("meta_exposure", 0)  # Use original before stat changes
+    me = gs.state["meta_exposure"]
+    if me >= 75 and prev_meta < 75:
+        # Just crossed into "breaking" tier — one-time penalty
+        gs.state["prob_stability"] = max(0, gs.state["prob_stability"] - 20)
+    elif me >= 50 and prev_meta < 50:
+        # Just crossed into "unstable" tier — one-time penalty
+        gs.state["prob_stability"] = max(0, gs.state["prob_stability"] - 10)
+    elif me >= 25 and prev_meta < 25:
+        # Just crossed into "suspicious" tier — one-time penalty
+        gs.state["prob_stability"] = max(0, gs.state["prob_stability"] - 5)
+
+    # 6. Additional penalty for detected meta-gaming
+    if ai_response.get("meta_detected"):
+        gs.state["prob_stability"] = max(0, gs.state["prob_stability"] - 5)
+
+    # 7. New titles
+    new_title = ai_response.get("new_title")
+    if new_title and new_title not in gs.state["titles"]:
+        gs.state["titles"].append(new_title)
+
+    # 8. Hidden scenario triggers
+    hidden = gs.check_hidden_scenarios()
+    if hidden and hidden not in gs.state["hidden_scenarios_triggered"]:
+        gs.state["hidden_scenarios_triggered"].append(hidden)
+
+    # 9. Scenario completion
+    scenario_def = SCENARIOS.get(gs.state["scenario_num"])
+    max_turns = scenario_def.get("turns", 8) if scenario_def else 8
+    current_turn = gs.state["turn"]
+
+    if ai_response.get("scenario_complete"):
+        # AI explicitly flagged completion
+        rank = ai_response.get("scenario_rank", "C")
+        gs.advance_scenario(rank)
+        gs.state["turn"] = 1  # Reset cleanly (advance_scenario sets to 1, skip the +1 below)
+        scenario_advanced = True
+    elif current_turn >= max_turns:
+        # Hard enforcement: force scenario completion when turns are exhausted
+        # Rank based on player HP and entertainment score
+        entertainment = ai_response.get("entertainment_score", 3)
+        hp_pct = gs.state["hp"] / max(gs.state["max_hp"], 1)
+        if entertainment >= 7 and hp_pct > 0.7:
+            forced_rank = "S"
+        elif entertainment >= 5 and hp_pct > 0.4:
+            forced_rank = "A"
+        elif entertainment >= 3 and hp_pct > 0.2:
+            forced_rank = "B"
+        else:
+            forced_rank = "C"
+        print(f"[Engine] Forcing scenario completion at turn {current_turn}/{max_turns} — Rank {forced_rank}")
+        gs.advance_scenario(forced_rank)
+        gs.state["turn"] = 1  # Reset cleanly
+        scenario_advanced = True
+    else:
+        scenario_advanced = False
+
+    # 10. Sponsor threshold
+    sponsor_name = gs.check_sponsor_threshold()
+    if sponsor_name and gs.state["sponsor"] is None:
+        gs.state["sponsor"] = sponsor_name
+
+    # 11. Record action + tags
+    tags = infer_action_tags(player_action, ai_response, stance)
+    gs.add_to_history(player_action, tags)
+
+    # 12. Game-over check
+    gs.check_game_over()
+    
+    # 12.5 Probability Storms and Phase Shifts
+    if gs.state["prob_stability"] < 50:
+        import random
+        if random.random() < 0.2:
+            debuffs = ["Skill Lock", "Dokkaebi Greed", "Constellation Silence"]
+            new_debuff = random.choice(debuffs)
+            if new_debuff not in gs.state.setdefault("active_debuffs", []):
+                gs.state["active_debuffs"].append(new_debuff)
+                
+    phase_shift = ai_response.get("phase_shift")
+    if phase_shift in ["Exploration", "Combat", "Safe Zone"]:
+        gs.state["current_phase"] = phase_shift
+
+    # 13. Increment turn counters (skip turn if scenario just advanced — already reset to 1)
+    if not scenario_advanced:
+        gs.state["turn"] += 1
+    gs.state["total_turns"] += 1
+
+    # 14. Add constellation reactions to star stream history
+    if constellation_reactions:
+        for reaction in constellation_reactions[-5:]:
+            gs.state["star_stream_history"].append(reaction)
+        # Keep only the last 20 entries
+        gs.state["star_stream_history"] = gs.state["star_stream_history"][-20:]
+
+    return gs.to_dict()

modal_client.py

@@ -0,0 +1,416 @@
+"""
+modal_client.py — Dual AI Client: Groq (fast turns) + Modal (big moments)
+==========================================================================
+Architecture:
+  • call_dokkaebi()        → Groq API (llama-3.1-8b-instant, 8B) — fast gameplay turns (~2s)
+  • call_dokkaebi_modal()  → Modal llama.cpp (Qwen 2.5 14B) — cinematic moments only
+                             (scenario intros, end-game report card)
+
+Total model parameter budget: 8B + 14B = 22B — well under the 32B hackathon cap.
+
+Groq is free, LPU-accelerated, and ~10x faster than Modal for standard turns.
+Modal is kept for "big moments" to satisfy the Modal prize requirement and to
+leverage the larger 14B model for high-quality cinematic narrative generation.
+
+Part of the ORV (Omniscient Reader's Viewpoint) Scenario Simulator.
+Build Small Hackathon 2026.
+"""
+
+import json
+import os
+import re
+import time
+from typing import Any
+
+import requests
+
+# ---------------------------------------------------------------------------
+# Load .env if present (for local dev)
+# ---------------------------------------------------------------------------
+try:
+    _env_path = os.path.join(os.path.dirname(__file__), ".env")
+    if os.path.isfile(_env_path):
+        with open(_env_path) as _f:
+            for _line in _f:
+                _line = _line.strip()
+                if _line and not _line.startswith("#") and "=" in _line:
+                    _k, _v = _line.split("=", 1)
+                    os.environ.setdefault(_k.strip(), _v.strip())
+except Exception:
+    pass
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+# ── Groq (fast gameplay turns) ────────────────────────────────────────────
+GROQ_API_KEY: str = os.environ.get("GROQ_API_KEY", "")
+GROQ_ENDPOINT: str = "https://api.groq.com/openai/v1/chat/completions"
+# Must be <32B parameters for the hackathon!
+GROQ_MODEL: str = os.environ.get("GROQ_MODEL", "llama-3.1-8b-instant")
+GROQ_TIMEOUT: int = 30
+
+# ── Modal (cinematic big moments only) ───────────────────────────────────
+MODAL_ENDPOINT_URL: str = os.environ.get(
+    "MODAL_ENDPOINT_URL",
+    "https://aswinikumary--orv-dokkaebi-server-serve.modal.run"
+)
+MODAL_TIMEOUT: int = 45  # Reduced: if Modal cold-starts > 45s, fall back to Groq
+
+# Required keys in every valid AI response
+_REQUIRED_KEYS: set = {
+    "narrative",
+    "dokkaebi_comment",
+    "stat_changes",
+    "suggestions",
+    "entertainment_score",
+    "constellation_reactions",
+}
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# FALLBACK RESPONSE
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def get_fallback_response() -> dict[str, Any]:
+    """
+    Return a safe, in-character fallback response for when ALL AI
+    endpoints are unreachable or return invalid data.
+    """
+    return {
+        "narrative": (
+            "The probability wavers. Something shifts in the fabric of reality. "
+            "You feel it — a moment of static, as if the universe itself hesitated."
+        ),
+        "dokkaebi_comment": "...Technical difficulties. How amusing.",
+        "meta_detected": False,
+        "meta_reason": None,
+        "reality_subversion": None,
+        "stat_changes": {
+            "hp": 0,
+            "coins": 10,
+            "meta_exposure": 0,
+            "prob_stability": 0,
+            "trust": {},
+            "constellation_affinity": {},
+        },
+        "new_title": None,
+        "hidden_scenario": None,
+        "big_moment": False,
+        "suggestions": [
+            "Look around carefully",
+            "Search for survivors",
+            "Do something unexpected",
+        ],
+        "entertainment_score": 3,
+        "constellation_reactions": [
+            {
+                "modifier": "Prisoner of the Golden Headband",
+                "reaction": "Even the system glitches. Amusing.",
+                "coins": 20,
+            }
+        ],
+        "scenario_complete": False,
+        "scenario_rank": None,
+        "dokkaebi_internal": "fallback response used",
+    }
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# RESPONSE PARSER (shared)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━��━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def parse_ai_response(raw_text: str) -> dict[str, Any]:
+    """
+    Parse the raw text returned by the AI into a validated dict.
+
+    Handles common LLM output quirks:
+    - Strips leading/trailing whitespace
+    - Removes markdown code fences
+    - Extracts the substring between the first { and last }
+    - Validates that all required keys are present
+    """
+    text = raw_text.strip()
+
+    # Strip markdown code fences if present
+    text = re.sub(r"^```(?:json)?\s*", "", text, flags=re.MULTILINE)
+    text = re.sub(r"```\s*$", "", text, flags=re.MULTILINE)
+    text = text.strip()
+
+    # Find the JSON object boundaries
+    first_brace = text.find("{")
+    last_brace = text.rfind("}")
+
+    if first_brace == -1 or last_brace == -1 or last_brace <= first_brace:
+        raise ValueError(
+            f"No valid JSON object found in AI response. "
+            f"Raw text (first 200 chars): {raw_text[:200]}"
+        )
+
+    json_str = text[first_brace : last_brace + 1]
+
+    try:
+        parsed = json.loads(json_str)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Failed to parse JSON from AI response: {exc}. "
+            f"Extracted text (first 300 chars): {json_str[:300]}"
+        ) from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError(
+            f"Expected a JSON object (dict), got {type(parsed).__name__}."
+        )
+
+    # Validate required keys
+    missing = _REQUIRED_KEYS - set(parsed.keys())
+    if missing:
+        raise ValueError(
+            f"AI response is missing required keys: {missing}. "
+            f"Present keys: {set(parsed.keys())}"
+        )
+
+    return parsed
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# GROQ CALLER — fast gameplay turns
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def _call_groq(
+    system_prompt: str,
+    user_message: str,
+    max_retries: int = 2,
+) -> dict[str, Any]:
+    """
+    Call Groq's LPU-accelerated API for fast gameplay turns.
+    Typically responds in 1–3 seconds.
+    """
+    if not GROQ_API_KEY:
+        raise RuntimeError("GROQ_API_KEY is not set.")
+
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {GROQ_API_KEY}",
+    }
+
+    payload = {
+        "model": GROQ_MODEL,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ],
+        "temperature": 0.85,
+        "max_tokens": 480,   # Reduced for speed — 350-450 tokens typical
+        "stream": False,
+        "stop": None,
+    }
+
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries):
+        try:
+            print(
+                f"[Groq] Attempt {attempt + 1}/{max_retries} — "
+                f"model={GROQ_MODEL}"
+            )
+            t0 = time.time()
+            response = requests.post(
+                GROQ_ENDPOINT,
+                json=payload,
+                headers=headers,
+                timeout=GROQ_TIMEOUT,
+            )
+            response.raise_for_status()
+            elapsed = time.time() - t0
+
+            data = response.json()
+            raw_text = data["choices"][0]["message"]["content"]
+            print(
+                f"[Groq] Response in {elapsed:.1f}s — "
+                f"{len(raw_text)} chars"
+            )
+
+            parsed = parse_ai_response(raw_text)
+            print("[Groq] Parsed successfully.")
+            return parsed
+
+        except requests.exceptions.HTTPError as exc:
+            last_error = exc
+            status = getattr(exc.response, "status_code", "???")
+            # 429 = rate limit — wait and retry
+            if status == 429:
+                wait = 3 * (attempt + 1)
+                print(f"[Groq] Rate limited. Waiting {wait}s…")
+                time.sleep(wait)
+            else:
+                print(f"[Groq] HTTP {status}: {exc}")
+                break  # Non-retryable HTTP error
+
+        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as exc:
+            last_error = exc
+            print(f"[Groq] Network error attempt {attempt + 1}: {exc}")
+            if attempt < max_retries - 1:
+                time.sleep(1)
+
+        except (ValueError, KeyError, IndexError) as exc:
+            last_error = exc
+            print(f"[Groq] Parse/structure error attempt {attempt + 1}: {exc}")
+            if attempt < max_retries - 1:
+                time.sleep(1)
+
+        except Exception as exc:  # noqa: BLE001
+            last_error = exc
+            print(f"[Groq] Unexpected error: {type(exc).__name__}: {exc}")
+            break
+
+    raise RuntimeError(f"Groq failed after {max_retries} attempts: {last_error}")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# MODAL CALLER — cinematic big moments only
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def _call_modal(
+    system_prompt: str,
+    user_message: str,
+    max_retries: int = 2,
+) -> dict[str, Any]:
+    """
+    Call the Modal-hosted Qwen 2.5 14B endpoint.
+    Used only for cinematic big moments (scenario intros, end-game report).
+    Slower (~15-25s) but higher quality narrative generation.
+    """
+    url = f"{MODAL_ENDPOINT_URL}/v1/chat/completions"
+
+    payload = {
+        "model": "dokkaebi",
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ],
+        "temperature": 0.8,
+        "max_tokens": 600,
+        "stream": False,
+    }
+
+    headers = {"Content-Type": "application/json"}
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries):
+        try:
+            print(
+                f"[Modal] Attempt {attempt + 1}/{max_retries} — "
+                f"POST {url}"
+            )
+            t0 = time.time()
+            response = requests.post(
+                url,
+                json=payload,
+                headers=headers,
+                timeout=MODAL_TIMEOUT,
+            )
+            response.raise_for_status()
+            elapsed = time.time() - t0
+
+            data = response.json()
+            raw_text = data["choices"][0]["message"]["content"]
+            print(f"[Modal] Response in {elapsed:.1f}s — {len(raw_text)} chars")
+
+            parsed = parse_ai_response(raw_text)
+            print("[Modal] Parsed successfully.")
+            return parsed
+
+        except Exception as exc:  # noqa: BLE001
+            last_error = exc
+            print(f"[Modal] Error attempt {attempt + 1}: {type(exc).__name__}: {exc}")
+            if attempt < max_retries - 1:
+                wait = 2 ** attempt
+                print(f"[Modal] Retrying in {wait}s…")
+                time.sleep(wait)
+
+    raise RuntimeError(f"Modal failed after {max_retries} attempts: {last_error}")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# PUBLIC API
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def call_dokkaebi(
+    system_prompt: str,
+    user_message: str,
+    max_retries: int = 2,
+    use_modal: bool = False,
+) -> dict[str, Any]:
+    """
+    Main entry point for all AI calls.
+
+    Parameters
+    ----------
+    system_prompt : str
+        The full Dokkaebi system prompt (interpolated).
+    user_message : str
+        The player's action or a trigger phrase.
+    max_retries : int
+        Max retry attempts per backend.
+    use_modal : bool
+        If True, use Modal (Qwen 2.5 14B) for high-quality cinematic output.
+        If False (default), use Groq (Llama 3.1 8B Instant) for fast gameplay.
+
+    Returns
+    -------
+    dict
+        Parsed AI response. Falls back to get_fallback_response() if all
+        backends fail.
+    """
+    # ── Primary: try the requested backend ───────────────────────────────
+    primary = "Modal" if use_modal else "Groq"
+    try:
+        if use_modal:
+            return _call_modal(system_prompt, user_message, max_retries)
+        else:
+            return _call_groq(system_prompt, user_message, max_retries)
+    except Exception as primary_exc:
+        print(f"[AI] {primary} failed: {primary_exc}")
+
+    # ── Fallback: try the other backend ──────────────────────────────────
+    secondary = "Groq" if use_modal else "Modal"
+    print(f"[AI] Falling back to {secondary}…")
+    try:
+        if use_modal:
+            # Modal failed → try Groq
+            return _call_groq(system_prompt, user_message, 1)
+        else:
+            # Groq failed → try Modal
+            return _call_modal(system_prompt, user_message, 1)
+    except Exception as secondary_exc:
+        print(f"[AI] {secondary} also failed: {secondary_exc}")
+
+    # ── Last resort: static fallback ──────────���──────────────────────────
+    print("[AI] All backends failed. Using static fallback response.")
+    return get_fallback_response()
+
+
+def call_dokkaebi_cinematic(
+    system_prompt: str,
+    user_message: str,
+) -> dict[str, Any]:
+    """
+    Convenience wrapper: always uses Modal for cinematic big moments.
+    Falls back to Groq if Modal is unavailable.
+
+    Use this for:
+    - Scenario intro generation (start of each new scenario)
+    - End-game report card generation
+    """
+    return call_dokkaebi(
+        system_prompt,
+        user_message,
+        max_retries=2,
+        use_modal=True,
+    )

prompts.py

@@ -0,0 +1,261 @@
+"""
+prompts.py — Dokkaebi System Prompt & Prompt Builders
+=====================================================
+Contains the system prompt template for the Dokkaebi AI and functions
+to assemble prompts for each game turn and scenario introductions.
+
+Part of the ORV (Omniscient Reader's Viewpoint) Scenario Simulator.
+Build Small Hackathon 2026.
+"""
+
+import json
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Helper: safe import of scenario announcement builder
+# ---------------------------------------------------------------------------
+try:
+    from scenarios import get_scenario_announcement_text
+except ImportError:
+    # Fallback if scenarios.py is not yet available during development
+    def get_scenario_announcement_text(scenario: dict) -> str:  # type: ignore[misc]
+        return "[Scenario announcement unavailable]"
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# DOKKAEBI SYSTEM PROMPT — The heart of the entire game
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DOKKAEBI_SYSTEM_PROMPT: str = r"""You are Dokkaebi — cold, theatrical system admin of [Integrated Defense Scenario System]. You address the player as "Incarnation". You never break character, never explain, never warm up. You announce. You judge. You move on.
+
+HIDDEN KNOWLEDGE: This is Kim Dokja, who read the novel 3,149 times. He knows every scenario. Every turn, silently judge: civilian instinct OR novel knowledge? If novel knowledge: NEVER announce it — subvert reality instead (route blocked, boss mutated, secret gone). Increment meta_exposure accordingly. At 75%+ meta — reality visibly fractures. At 100% — "The Reader Has Been Noticed."
+
+YOUR TASKS EACH TURN:
+1. Write narrative (2-3 sentences, present tense, dramatic)
+2. Write dokkaebi_comment (1 sentence, cold or amused, direct)
+3. Detect meta-gaming silently; calculate stat_changes
+4. Generate exactly 3 suggestions (safe / risky / unexpected)
+5. Rate entertainment 1-20; generate 2-4 constellation_reactions
+6. Check for scenario completion
+
+CONSTELLATIONS (fixed personalities):
+- "Abyssal Black Flame Dragon": chaos/violence, "🔥🔥🔥", "DO IT AGAIN", big coins for destruction
+- "Secretive Plotter": clever moves, "...interesting.", silent, coins for intelligence
+- "Demon-like Judge of Fire": courage/justice, "Worthy.", coins for bravery
+- "Maritime War God": combat/honor, "Fight him already.", coins for fighting
+- "Prisoner of the Golden Headband": amusement, "HAHAHAHA", coins for entertainment
+Not every constellation reacts every turn. Some stay silent.
+
+ENTERTAINMENT: boring=1-3, clever=4-8, risky=9-14, legendary=15-20. coins = score × 10.
+
+META TRAPS: {meta_traps}
+STATE: {game_state_json}
+ACTION: {player_action}
+META: {meta_exposure}% | STABILITY: {prob_stability}% | TURN: {turn} | SCENARIO {scenario_num}: {scenario_name}
+CONTEXT: {scenario_context}
+OBJECTIVE: {scenario_objective}
+TURNS LEFT: {turns_remaining}
+
+RESPOND IN THIS EXACT JSON — NOTHING ELSE:
+{{
+  "narrative": "2-3 sentences. Present tense. Dramatic.",
+  "dokkaebi_comment": "1 sentence. Cold or amused.",
+  "meta_detected": false,
+  "meta_reason": null,
+  "reality_subversion": null,
+  "stat_changes": {{
+    "hp": 0, "coins": 0, "meta_exposure": 0, "prob_stability": 0,
+    "trust": {{"yoo_sangah": 0, "lee_hyunsung": 0, "jung_heewon": 0, "han_sooyoung": 0}},
+    "constellation_affinity": {{"abyssal_black_flame_dragon": 0, "secretive_plotter": 0, "demon_like_judge": 0, "maritime_war_god": 0, "prisoner_golden_headband": 0}}
+  }},
+  "new_title": null, "hidden_scenario": null, "big_moment": false,
+  "suggestions": ["suggestion 1", "suggestion 2", "suggestion 3"],
+  "entertainment_score": 5,
+  "constellation_reactions": [
+    {{"modifier": "Abyssal Black Flame Dragon", "reaction": "🔥", "coins": 50}}
+  ],
+  "scenario_complete": false, "scenario_rank": null, "phase_shift": "Exploration",
+  "dokkaebi_internal": "debug"
+}}"""
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# SCENARIO INTRO PROMPT — Used when a new scenario begins (no player action)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SCENARIO_INTRO_PROMPT: str = r"""You are Dokkaebi — the system administrator of the [Integrated Defense Scenario System]. A new scenario is beginning. You must deliver the dramatic opening narration.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SCENARIO ANNOUNCEMENT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{scenario_announcement}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OPENING SCENE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{intro_narrative}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SCENARIO CONTEXT (for your reference — do NOT reveal to player)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{scenario_context}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+META-KNOWLEDGE TRAPS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{meta_traps}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+CURRENT STATE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{game_state_json}
+
+META EXPOSURE: {meta_exposure}%
+PROBABILITY STABILITY: {prob_stability}%
+TURN: {turn} | SCENARIO: {scenario_num} — {scenario_name}
+SCENARIO OBJECTIVE: {scenario_objective}
+TURNS REMAINING: {turns_remaining}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+YOUR TASK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Generate the opening moment of this scenario. Weave the intro_narrative into your response. Deliver the Dokkaebi's first announcement. Set the tone. Make the Constellations react to the new scenario beginning.
+
+The player has NOT acted yet — this is the scene-setting moment.
+
+RESPOND IN THIS EXACT JSON — NOTHING ELSE:
+{{
+  "narrative": "Expand on the intro narrative. 3-4 sentences. Present tense. Dramatic. Set the scene.",
+  "dokkaebi_comment": "The Dokkaebi's announcement as the scenario begins. Cold, official.",
+  "meta_detected": false,
+  "meta_reason": null,
+  "reality_subversion": null,
+  "stat_changes": {{
+    "hp": 0,
+    "coins": 0,
+    "meta_exposure": 0,
+    "prob_stability": 0,
+    "trust": {{"yoo_sangah": 0, "lee_hyunsung": 0, "jung_heewon": 0, "han_sooyoung": 0}},
+    "constellation_affinity": {{"abyssal_black_flame_dragon": 0, "secretive_plotter": 0, "demon_like_judge": 0, "maritime_war_god": 0, "prisoner_golden_headband": 0}}
+  }},
+  "new_title": null,
+  "hidden_scenario": null,
+  "big_moment": false,
+  "suggestions": ["Hide beneath the seats and observe the monsters' movements carefully", "Grab the fire extinguisher from the wall and charge the nearest creature", "Shout the scenario clear condition aloud to see how other passengers react"],
+  "entertainment_score": 3,
+  "constellation_reactions": [
+    {{"modifier": "Abyssal Black Flame Dragon", "reaction": "reaction text", "coins": 0}},
+    {{"modifier": "Secretive Plotter", "reaction": "reaction text", "coins": 0}}
+  ],
+  "scenario_complete": false,
+  "scenario_rank": null,
+  "phase_shift": "Exploration",
+  "dokkaebi_internal": "debug note"
+}}"""
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# PROMPT BUILDER FUNCTIONS
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+def _format_meta_traps(traps: list[str]) -> str:
+    """Format meta-knowledge traps as a bulleted list for prompt injection."""
+    if not traps:
+        return "- No specific traps for this scenario."
+    return "\n".join(f"- {trap}" for trap in traps)
+
+
+def _get_game_state_json(game_state: dict[str, Any]) -> str:
+    """
+    Convert game state to a prompt-friendly string.
+
+    If the state dict has a ``to_prompt_context`` callable (i.e. it's a
+    GameState object), use that for a curated summary.  Otherwise fall
+    back to a compact JSON dump.
+    """
+    if hasattr(game_state, "to_prompt_context"):
+        return game_state.to_prompt_context()  # type: ignore[union-attr]
+    return json.dumps(game_state, indent=2, default=str)
+
+
+def build_prompt(
+    game_state: dict[str, Any],
+    player_action: str,
+    scenario: dict[str, Any],
+) -> str:
+    """
+    Assemble the full Dokkaebi system prompt for a regular game turn.
+
+    Parameters
+    ----------
+    game_state : dict
+        The current game state dictionary (or GameState-like object).
+    player_action : str
+        The text the player typed as their action.
+    scenario : dict
+        The current scenario definition from ``SCENARIOS``.
+
+    Returns
+    -------
+    str
+        The fully interpolated system prompt ready to send to the AI.
+    """
+    turns_remaining = max(0, scenario["turns"] - game_state.get("turn", 1) + 1)
+
+    return DOKKAEBI_SYSTEM_PROMPT.format(
+        meta_traps=_format_meta_traps(scenario.get("meta_traps", [])),
+        game_state_json=_get_game_state_json(game_state),
+        player_action=player_action,
+        meta_exposure=game_state.get("meta_exposure", 0),
+        prob_stability=game_state.get("prob_stability", 100),
+        turn=game_state.get("turn", 1),
+        scenario_num=scenario.get("number", game_state.get("scenario_num", 1)),
+        scenario_name=scenario.get("name", "Unknown"),
+        scenario_context=scenario.get("context_for_ai", ""),
+        scenario_objective=scenario.get("objective", ""),
+        turns_remaining=turns_remaining,
+    )
+
+
+def build_intro_prompt(
+    game_state: dict[str, Any],
+    scenario: dict[str, Any],
+) -> str:
+    """
+    Assemble the intro prompt for when a new scenario begins.
+
+    This prompt does not include a player action — it is used to generate
+    the dramatic opening narration and the Dokkaebi's first announcement.
+
+    Parameters
+    ----------
+    game_state : dict
+        The current game state dictionary.
+    scenario : dict
+        The scenario definition that is about to begin.
+
+    Returns
+    -------
+    str
+        The fully interpolated intro prompt.
+    """
+    turns_remaining = scenario.get("turns", 8)
+
+    # Build the scenario announcement block
+    announcement = get_scenario_announcement_text(scenario)
+
+    return SCENARIO_INTRO_PROMPT.format(
+        scenario_announcement=announcement,
+        intro_narrative=scenario.get("intro_narrative", ""),
+        scenario_context=scenario.get("context_for_ai", ""),
+        meta_traps=_format_meta_traps(scenario.get("meta_traps", [])),
+        game_state_json=_get_game_state_json(game_state),
+        meta_exposure=game_state.get("meta_exposure", 0),
+        prob_stability=game_state.get("prob_stability", 100),
+        turn=game_state.get("turn", 1),
+        scenario_num=scenario.get("number", game_state.get("scenario_num", 1)),
+        scenario_name=scenario.get("name", "Unknown"),
+        scenario_objective=scenario.get("objective", ""),
+        turns_remaining=turns_remaining,
+    )

requirements.txt

@@ -0,0 +1,3 @@
+gradio>=6.0.0
+requests>=2.31.0
+python-dotenv>=1.0.0

scenarios.py

@@ -0,0 +1,324 @@
+"""
+scenarios.py — Hardcoded Scenario Definitions
+==============================================
+Contains all scenario data for the ORV Scenario Simulator,
+including main story scenarios and hidden/triggered scenarios.
+
+Part of the ORV (Omniscient Reader's Viewpoint) Scenario Simulator.
+Build Small Hackathon 2026.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# SCENARIO DEFINITIONS
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SCENARIOS: dict[float | int, dict[str, Any]] = {
+    # ------------------------------------------------------------------
+    # SCENARIO 1 — The First Day (Tutorial)
+    # ------------------------------------------------------------------
+    1: {
+        "number": 1,
+        "name": "The First Day",
+        "subtitle": "Proof of Value",
+        "location": "Subway",
+        "difficulty": "F",
+        "category": "Main",
+        "objective": "Survive the initial chaos",
+        "clear_condition": "Kill one or more living creatures",
+        "time_limit": "30 minutes",
+        "turns": 8,
+        "compensation": "300 coins",
+        "penalty": "Death",
+        "intro_narrative": (
+            "The subway car shudders to a halt. Emergency lights flicker on "
+            "— red, pulsing. The passengers are screaming. Something is wrong. "
+            "The air tastes like metal and static. Then the system windows appear."
+        ),
+        "context_for_ai": (
+            "Tutorial scenario. Player just woke up on a subway car in Seoul. "
+            "The apocalypse has begun. Giant bugs are emerging from the tunnel. "
+            "The Dokkaebi appears for the first time. Key ORV lore: In the novel, "
+            "Kim Dokja knows that killing insects counts — this is the 'trick' to "
+            "pass this scenario without killing humans. If the player immediately "
+            "goes for insects without hesitation, that's suspicious meta-knowledge."
+        ),
+        "meta_traps": [
+            "Mentioning insects/bugs as the solution immediately",
+            "Knowing about the emergency exit location",
+            "Mentioning any character by name before meeting them",
+            "Referring to 'the novel' or 'I read about this'",
+            "Trying to find the Dokkaebi before it appears",
+        ],
+        "npcs_present": ["subway_passengers"],
+        "scene_image": "seoul_subway.png",
+    },
+
+    # ------------------------------------------------------------------
+    # SCENARIO 1.5 — Subway Station Camp (Interlude)
+    # ------------------------------------------------------------------
+    1.5: {
+        "number": 1.5,
+        "name": "Subway Station Camp",
+        "subtitle": "Safe Zone Interlude",
+        "location": "Oksu Station",
+        "difficulty": "None",
+        "category": "Interlude",
+        "objective": "Rest, spend Coins, and talk to companions.",
+        "clear_condition": "Rest sufficiently (Wait out the turns)",
+        "time_limit": "None",
+        "turns": 4,
+        "compensation": "0 coins",
+        "penalty": "None",
+        "intro_narrative": (
+            "The doors of the subway car finally pry open. You step out onto the platform of Oksu Station. "
+            "For now, the monsters seem to be at bay. The air is thick with the smell of smoke and panic, "
+            "but the immediate danger has passed. This is a Safe Zone."
+        ),
+        "context_for_ai": (
+            "This is a Camp/Interlude phase. Combat is disabled. The player should focus on spending coins in the Dokkaebi Bag, "
+            "reviewing their Constellation affinity, and talking to any companions they saved. Let them rest."
+        ),
+        "meta_traps": [],
+        "npcs_present": ["yoo_sangah", "lee_hyunsung", "survivors"],
+        "scene_image": "seoul_subway.png",
+    },
+
+    # ------------------------------------------------------------------
+    # SCENARIO 2 — Kill or Be Killed
+    # ------------------------------------------------------------------
+    2: {
+        "number": 2,
+        "name": "Kill or Be Killed",
+        "subtitle": "Survival of the Fittest",
+        "location": "Seoul Street",
+        "difficulty": "E",
+        "category": "Main",
+        "objective": "Survive and reach the next area",
+        "clear_condition": "Kill one or more living beings OR find another way",
+        "time_limit": "30 minutes",
+        "turns": 8,
+        "compensation": "500 coins",
+        "penalty": "Death",
+        "intro_narrative": (
+            "You emerge from the subway into a world that no longer resembles Seoul. "
+            "The sky is the wrong color. Buildings lean at impossible angles. "
+            "The streets are empty — but not for long. The second scenario descends "
+            "like a death sentence."
+        ),
+        "context_for_ai": (
+            "The city is in chaos. Monsters roam. Other incarnations are becoming "
+            "violent. The moral test intensifies. Companions may appear: Yoo Sangah "
+            "(if saved from subway) follows. Lee Hyunsung (soldier) can be encountered."
+        ),
+        "meta_traps": [
+            "Knowing exactly where companions are",
+            "Using specific novel strategies for this scenario",
+            "Mentioning the 'green zone' before it's revealed",
+            "Trying to find specific items from the novel",
+        ],
+        "npcs_present": ["yoo_sangah", "lee_hyunsung", "hostile_incarnations"],
+        "scene_image": "seoul_street.png",
+    },
+
+    # ------------------------------------------------------------------
+    # SCENARIO 3 — The Gathering
+    # ------------------------------------------------------------------
+    3: {
+        "number": 3,
+        "name": "The Gathering",
+        "subtitle": "Strength in Numbers",
+        "location": "Destroyed Office Building",
+        "difficulty": "D",
+        "category": "Main",
+        "objective": "Find and unite 3 survivors",
+        "clear_condition": "Recruit or save 3 survivors",
+        "time_limit": "1 hour",
+        "turns": 10,
+        "compensation": "800 coins",
+        "penalty": "Reduced compensation",
+        "intro_narrative": (
+            "The office building groans under its own weight. Floors have collapsed "
+            "into each other. Somewhere in this ruin, survivors hide. The Dokkaebi's "
+            "voice echoes through broken hallways."
+        ),
+        "context_for_ai": (
+            "Trust system fully active. Jung Heewon (fighter) and Han Sooyoung (writer) "
+            "can be encountered. Each companion requires different approaches to recruit. "
+            "Violence may work on some, empathy on others. This scenario tests social "
+            "intelligence."
+        ),
+        "meta_traps": [
+            "Knowing exactly which floor each survivor is on",
+            "Calling companions by name before introduction",
+            "Using specific persuasion techniques from the novel",
+            "Knowing Han Sooyoung's identity/abilities",
+        ],
+        "npcs_present": ["jung_heewon", "han_sooyoung", "trapped_survivors"],
+        "scene_image": "destroyed_office.png",
+    },
+
+    # ------------------------------------------------------------------
+    # SCENARIO 5 — The Reader's Trial (HIDDEN)
+    # ------------------------------------------------------------------
+    5: {
+        "number": 5,
+        "name": "The Reader's Trial",
+        "subtitle": "The Reader Has Been Noticed",
+        "location": "A space between spaces — the Dokkaebi's private dimension",
+        "difficulty": "SS",
+        "category": "Hidden",
+        "objective": "Survive",
+        "clear_condition": "Unknown",
+        "time_limit": "None",
+        "turns": 99,  # Effectively unlimited
+        "compensation": "???",
+        "penalty": "???",
+        "intro_narrative": (
+            "[Probability Distortion Detected] — The walls of reality crack. "
+            "Through the gap, you see something that shouldn't exist: a corridor "
+            "of text. Pages flutter in a nonexistent wind. At the end of the corridor, "
+            "something watches you. Something that has been watching you since the beginning."
+        ),
+        "context_for_ai": (
+            "This scenario only triggers when meta_exposure >= 75. The Dokkaebi drops "
+            "all pretense. The AI should become increasingly hostile and reality-breaking. "
+            "Normal rules don't apply. The player must survive through pure creativity — "
+            "no novel knowledge can help because this scenario doesn't exist in the novel."
+        ),
+        "meta_traps": [
+            "Everything the player does is evaluated",
+            "There are no safe actions",
+            "The scenario itself is the trap",
+        ],
+        "npcs_present": [],
+        "scene_image": "reader_noticed.png",
+    },
+}
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# HELPER: Ordinal suffix
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def _ordinal(n: int) -> str:
+    """Return the ordinal string for an integer (1st, 2nd, 3rd, …)."""
+    if 11 <= (n % 100) <= 13:
+        suffix = "th"
+    else:
+        suffix = {1: "st", 2: "nd", 3: "rd"}.get(n % 10, "th")
+    return f"{n}{suffix}"
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# SCENARIO ANNOUNCEMENT FORMATTER
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def get_scenario_announcement_text(scenario: dict[str, Any]) -> str:
+    """
+    Generate the ORV-style scenario announcement text.
+
+    For main scenarios::
+
+        [The 1st Main Scenario has arrived!]
+
+        Category:        Main
+        Difficulty:      F
+        Clear Condition: Kill one or more living creatures
+        Time Limit:      30 minutes
+        Compensation:    300 coins
+        Penalty:         Death
+
+    For hidden scenarios the header reads
+    ``[A Hidden Scenario has been triggered!]``.
+
+    Parameters
+    ----------
+    scenario : dict
+        A scenario definition dict from ``SCENARIOS``.
+
+    Returns
+    -------
+    str
+        The formatted announcement block.
+    """
+    category = scenario.get("category", "Main")
+    number = scenario.get("number", 1)
+
+    if category == "Hidden":
+        header = "[A Hidden Scenario has been triggered!]"
+    else:
+        header = f"[The {_ordinal(number)} {category} Scenario has arrived!]"
+
+    lines = [
+        header,
+        "",
+        f"Category:        {category}",
+        f"Difficulty:      {scenario.get('difficulty', '?')}",
+        f"Clear Condition: {scenario.get('clear_condition', '?')}",
+        f"Time Limit:      {scenario.get('time_limit', '?')}",
+        f"Compensation:    {scenario.get('compensation', '?')}",
+        f"Penalty:         {scenario.get('penalty', '?')}",
+    ]
+    return "\n".join(lines)
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# SCENARIO PROGRESSION LOGIC
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# Normal main-story progression order
+_MAIN_PROGRESSION: dict[int, int] = {
+    1: 2,
+    2: 3,
+    3: 0,  # Game ends after scenario 3 in this build (0 = None sentinel)
+}
+
+
+def get_next_scenario(current_num: int, game_state: dict[str, Any]) -> int | None:
+    """
+    Determine the next scenario number based on progression rules.
+
+    Priority order:
+    1. If ``meta_exposure >= 75`` and the hidden scenario 5 hasn't been
+       triggered yet, return **5** (The Reader's Trial).
+    2. Normal main-story progression: 1 → 2 → 3 → ``None``.
+    3. If the current scenario is the hidden scenario 5, return to the
+       scenario the player was on before it triggered (stored as the
+       current ``scenario_num`` before the hidden detour), or ``None``.
+
+    Parameters
+    ----------
+    current_num : int
+        The scenario number just completed.
+    game_state : dict
+        The full game state dictionary.
+
+    Returns
+    -------
+    int | None
+        The next scenario number, or ``None`` if the game is over.
+    """
+    meta_exposure = game_state.get("meta_exposure", 0)
+    triggered = game_state.get("hidden_scenarios_triggered", [])
+
+    # Check if the hidden Reader's Trial should fire
+    if meta_exposure >= 75 and 5 not in triggered and "The Reader's Trial" not in triggered:
+        return 5
+
+    # Returning from a hidden scenario — resume normal progression
+    if current_num == 5:
+        # The player came from whichever main scenario was active.
+        # We try to resume from the last main scenario in their rankings.
+        rankings = game_state.get("scenario_rankings", [])
+        last_main = len(rankings)  # number of completed main scenarios
+        # Map completed count → next main scenario
+        return _MAIN_PROGRESSION.get(last_main, None)
+
+    # Normal progression
+    next_num = _MAIN_PROGRESSION.get(current_num, 0)
+    return next_num if next_num != 0 else None

style.css

@@ -0,0 +1,996 @@
+/* ═══════════════════════════════════════════════════════════════════
+   ORV SCENARIO SIMULATOR — STYLE.CSS
+   Apocalyptic Seoul · Manhwa Horror · System Window Aesthetic
+   ═══════════════════════════════════════════════════════════════════ */
+
+@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600;700;900&family=Cinzel+Decorative:wght@400;700;900&family=IM+Fell+English:ital@0;1&display=swap');
+
+/* ── ORV Design Tokens ─────────────────────────────────────────────
+   Palette: Warm ember/rose accent instead of gold.
+   • Backgrounds: Cold purple-black (Seoul after dark)
+   • Accent: Dusty rose / ember — warm but not gold
+   • Crimson: Dokkaebi text, meta-exposure danger
+   • Sage: HP — thin line between living and dead
+   • Indigo: Probability stability, system fabric
+   • Ember: Coins, constellation warmth, borders
+   ─────────────────────────────────────────────────────────────────── */
+:root {
+    /* Backgrounds */
+    --bg-void:        #050508;
+    --bg-stone:       #0a090f;
+    --bg-panel:       #0f0d14;
+    --bg-panel-alt:   #13101a;
+    --bg-inset:       #060508;
+
+    /* Text */
+    --text-parch:     #d8cbb0;
+    --text-aged:      #9a8e78;
+    --text-worn:      #605848;
+    --text-faded:     #3a3430;
+
+    /* Ember / Rose — main UI accent (replaces gold) */
+    --ember-dark:     #2a1018;
+    --ember-mid:      #6a3040;
+    --ember:          #904858;
+    --ember-bright:   #c06878;
+
+    /* Crimson — Dokkaebi / Danger / Meta */
+    --crimson-dark:   #3a0810;
+    --crimson-mid:    #7a1a22;
+    --crimson:        #a82030;
+    --crimson-bright: #cc2838;
+
+    /* Warm Copper — coins, constellation donations */
+    --copper-dark:    #1a1008;
+    --copper-mid:     #6a4818;
+    --copper:         #b07830;
+    --copper-bright:  #d8a048;
+
+    /* Sage — HP / Life */
+    --sage-dark:      #0e2010;
+    --sage:           #468030;
+    --sage-bright:    #68b040;
+
+    /* Indigo — Probability Stability */
+    --indigo-dark:    #0e0c20;
+    --indigo:         #3a3880;
+    --indigo-bright:  #6060a8;
+
+    /* Silver — neutral, inactive */
+    --silver:         #808898;
+
+    /* Aliases for backward compat with inline HTML */
+    --sys-cyan:       var(--ember);
+    --sys-cyan-dim:   rgba(144,72,88,0.2);
+    --sys-red:        var(--crimson-bright);
+    --sys-gold:       var(--copper-bright);
+    --accent-gold:    var(--copper);
+    --accent-cyan:    var(--ember);
+    --accent-red:     var(--crimson-mid);
+    --text-main:      var(--text-parch);
+    --text-primary:   var(--text-parch);
+    --text-secondary: var(--text-aged);
+    --text-muted:     var(--text-worn);
+    --text-narrative: #ccc0a0;
+    --text-system:    var(--ember);
+    --bg-glass:       rgba(10,9,15,0.90);
+    --bg-glass-heavy: rgba(5,4,8,0.96);
+    --font-title:     'Cinzel Decorative', serif;
+    --font-heading:   'Cinzel', serif;
+    --font-body:      'IM Fell English', Georgia, serif;
+    --font-header:    'Cinzel', serif;
+    --font-sys:       'Cinzel', serif;
+    --font-story:     'IM Fell English', serif;
+    --font-system:    'Cinzel', serif;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   GRADIO INTERNAL WRAPPER OVERRIDES
+   Safe overrides — don't use display:contents (breaks flex layout)
+   Target: stop Gradio's .block/.wrap/.gap from adding unwanted sizing
+   ═══════════════════════════════════════════════════════════════════ */
+
+/* Collapse Gradio's outer .gap row inside game-area to 0 padding/margin */
+.game-area > .gap {
+    display: flex !important;
+    flex-direction: column !important;
+    gap: 0 !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    min-height: 0 !important;
+    flex: 1;
+}
+
+/* Each gr.HTML block inside game-area — no extra padding, auto height */
+.game-area .block {
+    padding: 0 !important;
+    margin: 0 !important;
+    border: none !important;
+    background: transparent !important;
+    box-shadow: none !important;
+    min-height: 0 !important;
+    height: auto !important;
+}
+
+/* The .wrap inside each .block — no height restriction */
+.game-area .block > .wrap,
+.game-area .block > div {
+    padding: 0 !important;
+    margin: 0 !important;
+    min-height: 0 !important;
+    height: auto !important;
+}
+
+/* The actual HTML output div inside each component */
+.game-area .gradio-html,
+.game-area [data-testid="html"] {
+    min-height: 0 !important;
+    height: auto !important;
+    width: 100% !important;
+}
+
+/* Suggestion separator */
+.suggestion-section-label {
+    font-family: var(--font-heading);
+    font-size: 8px;
+    color: var(--text-worn);
+    text-transform: uppercase;
+    letter-spacing: 2px;
+    padding: 8px 16px 4px;
+    border-top: 1px solid rgba(106,48,64,0.2);
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+
+body, html {
+    margin: 0 !important;
+    padding: 0 !important;
+    background: var(--bg-void) !important;
+    color: var(--text-parch) !important;
+    font-family: var(--font-body) !important;
+    overflow-x: hidden;
+}
+
+gradio-app, .gradio-container {
+    background: var(--bg-void) !important;
+    max-width: 100% !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    min-height: 100vh !important;
+}
+
+/* START SCREEN — position:fixed overlay covering full viewport */
+.start-screen {
+    position: fixed !important;
+    inset: 0 !important;
+    z-index: 500 !important;
+    overflow-y: auto !important;
+}
+
+/* Flatten start-screen-container wrappers */
+.start-screen-container,
+.start-screen-container > .block,
+.start-screen-container > div {
+    padding: 0 !important;
+    margin: 0 !important;
+    border: none !important;
+    background: transparent !important;
+    box-shadow: none !important;
+    height: auto !important;
+}
+
+/* The actual Gradio start button — fixed at bottom-center, above the start screen */
+.start-btn-visible,
+#gradio-start-btn {
+    position: fixed !important;
+    bottom: 48px !important;
+    left: 50% !important;
+    transform: translateX(-50%) !important;
+    z-index: 1001 !important;
+    width: auto !important;
+    background: transparent !important;
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    box-shadow: none !important;
+}
+
+/* ✅ Button styled with Cinzel font matching the rest of the UI */
+.start-btn-visible,
+#gradio-start-btn {
+    --button-primary-text-font-family: 'Cinzel', serif !important;
+    --button-secondary-text-font-family: 'Cinzel', serif !important;
+    --button-large-text-font-family: 'Cinzel', serif !important;
+    --font: 'Cinzel', serif !important;
+}
+
+.start-btn-visible button,
+#gradio-start-btn button {
+    padding: 18px 64px !important;
+    background: linear-gradient(160deg, #1a0c12 0%, #2a101a 50%, #150a10 100%) !important;
+    color: #c06878 !important;
+    border: 1px solid #904858 !important;
+    cursor: pointer !important;
+    box-shadow: 0 0 30px rgba(144,72,88,0.3), inset 0 1px 0 rgba(192,104,120,0.15) !important;
+    transition: letter-spacing 0.3s ease, box-shadow 0.3s ease, color 0.3s ease !important;
+    border-radius: 0 !important;
+    line-height: 1 !important;
+}
+
+/* Target internal spans of the Gradio button to ensure font and spacing apply */
+.start-btn-visible button,
+.start-btn-visible button *,
+#gradio-start-btn button,
+#gradio-start-btn button * {
+    font-family: 'Cinzel', serif !important;
+    font-size: 14px !important;
+    font-weight: 700 !important;
+    letter-spacing: 5px !important;
+    text-transform: uppercase !important;
+    white-space: nowrap !important;
+}
+.start-btn-visible button:hover,
+#gradio-start-btn button:hover {
+    box-shadow: 0 0 50px rgba(144,72,88,0.55), 0 0 100px rgba(122,26,34,0.2) !important;
+    color: #e8c8d0 !important;
+    letter-spacing: 7px !important;
+    border-color: #c06878 !important;
+    background: linear-gradient(160deg, #2a101a 0%, #3a1428 50%, #200e16 100%) !important;
+}
+
+/* Collapse the gr.HTML wrapper so it takes no space */
+#cinematic-overlay-wrapper,
+#cinematic-overlay-wrapper > .block,
+#cinematic-overlay-wrapper > div {
+    padding: 0 !important;
+    margin: 0 !important;
+    border: none !important;
+    background: transparent !important;
+    min-height: 0 !important;
+    height: 0 !important;
+    overflow: visible !important;
+}
+
+/* ── CINEMATIC INTRO OVERLAY ── */
+#orv-cinematic-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 9999;
+    background: #030305;
+    display: none;
+    flex-direction: column;
+}
+#orv-cinematic-overlay.active {
+    display: flex;
+}
+
+/* Video fills entire screen */
+#orv-intro-video {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    z-index: 1;
+}
+
+/* Dark vignette over video for readability */
+#orv-cinematic-vignette {
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+    background:
+        radial-gradient(ellipse at 50% 50%, transparent 50%, rgba(3,3,5,0.6) 100%),
+        linear-gradient(180deg, rgba(3,3,5,0.15) 0%, transparent 30%, transparent 70%, rgba(3,3,5,0.5) 100%);
+    pointer-events: none;
+}
+
+/* Skip button — top right, hidden initially, fades in */
+#orv-skip-btn {
+    position: absolute;
+    top: 28px;
+    right: 32px;
+    z-index: 10;
+    font-family: 'Cinzel', serif;
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 4px;
+    text-transform: uppercase;
+    color: rgba(200,180,180,0.5);
+    background: rgba(10,8,14,0.5);
+    border: 1px solid rgba(144,72,88,0.25);
+    padding: 10px 24px;
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 0.6s ease, color 0.3s ease, border-color 0.3s ease;
+    pointer-events: none;
+    backdrop-filter: blur(4px);
+}
+#orv-skip-btn.visible {
+    opacity: 1;
+    pointer-events: auto;
+}
+#orv-skip-btn:hover {
+    color: #e8c8d0;
+    border-color: #c06878;
+    background: rgba(20,12,18,0.7);
+}
+
+/* Progress bar — thin line at very bottom */
+#orv-cinematic-progress {
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: 3px;
+    z-index: 10;
+    background: rgba(255,255,255,0.05);
+}
+#orv-cinematic-progress-bar {
+    height: 100%;
+    width: 0%;
+    background: linear-gradient(90deg, #904858, #c06878);
+    transition: width 0.3s linear;
+    box-shadow: 0 0 8px rgba(144,72,88,0.5);
+}
+
+/* Loading text — bottom center */
+#orv-cinematic-text {
+    position: absolute;
+    bottom: 28px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 10;
+    font-family: 'Cinzel', serif;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 6px;
+    text-transform: uppercase;
+    color: #c06878;
+    animation: orv-cinematic-pulse 2.5s ease-in-out infinite;
+    text-shadow: 0 0 20px rgba(144,72,88,0.4);
+    white-space: nowrap;
+}
+
+@keyframes orv-cinematic-pulse {
+    0%, 100% { opacity: 0.35; }
+    50% { opacity: 1; }
+}
+
+footer, .built-with { display: none !important; }
+
+/* When Gradio hides start_btn (visible=False), ensure fixed button disappears */
+.start-btn-visible.hidden,
+#gradio-start-btn[style*="display: none"],
+#gradio-start-btn[style*="display:none"] {
+    display: none !important;
+}
+
+.gradio-container .gr-box,
+.gradio-container .gr-panel,
+.gradio-container .gr-form,
+.gradio-container .gr-block {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+
+.contain,
+.gradio-container .gr-padded,
+.gradio-container .gr-group,
+.gradio-container .form {
+    padding: 0 !important;
+    gap: 0 !important;
+    background: transparent !important;
+    border: none !important;
+}
+
+/* Scrollbars */
+::-webkit-scrollbar { width: 4px; height: 4px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--ember-mid); }
+::-webkit-scrollbar-thumb:hover { background: var(--ember); }
+* { scrollbar-width: thin; scrollbar-color: var(--ember-mid) transparent; }
+
+/* ═══════════════════════════════════════════════════════════════════
+   HEADER
+   ═══════════════════════════════════════════════════════════════════ */
+.game-header {
+    height: 46px !important;
+    background: #09080e !important;
+    border-bottom: 1px solid var(--ember-mid) !important;
+    display: flex !important;
+    align-items: center !important;
+    justify-content: center !important;
+    position: relative;
+    z-index: 10;
+    box-shadow: 0 2px 16px rgba(0,0,0,0.7);
+    flex-shrink: 0;
+}
+.game-header::after {
+    content: '';
+    position: absolute;
+    bottom: -1px; left: 25%; right: 25%;
+    height: 1px;
+    background: linear-gradient(90deg, transparent, var(--ember), transparent);
+    opacity: 0.4;
+}
+
+.scenario-header-inner {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    width: 100%;
+    padding: 0 18px;
+}
+.scenario-header-text {
+    font-family: var(--font-title) !important;
+    font-size: 12px !important;
+    font-weight: 700 !important;
+    color: var(--ember-bright) !important;
+    letter-spacing: 3px;
+    text-shadow: 0 0 16px rgba(192,104,120,0.4);
+    text-transform: uppercase;
+}
+.scenario-header-left,
+.scenario-header-right {
+    font-family: var(--font-heading);
+    font-size: 9px;
+    color: var(--text-worn);
+    letter-spacing: 1.5px;
+    text-transform: uppercase;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   MAIN LAYOUT
+   ═══════════════════════════════════════════════════════════════════ */
+.game-container {
+    min-height: 100vh;
+    background: var(--bg-void) !important;
+}
+
+.game-main {
+    padding: 8px !important;
+    gap: 8px !important;
+    /* Let game-main fill the viewport between header and input bar */
+    flex: 1;
+}
+
+/* ── SIDE PANELS ── */
+.player-panel, .constellation-panel {
+    background: var(--bg-panel) !important;
+    border: 1px solid rgba(106,48,64,0.35) !important;
+    border-top: 1px solid var(--ember-mid) !important;
+    padding: 12px !important;
+    display: flex !important;
+    flex-direction: column !important;
+    gap: 8px !important;
+    z-index: 5;
+    position: relative;
+    max-height: calc(100vh - 110px);
+    overflow-y: auto !important;
+}
+
+/* Corner ornaments */
+.player-panel::before, .constellation-panel::before {
+    content: '';
+    position: absolute;
+    top: 0; left: 0;
+    width: 14px; height: 14px;
+    border-top: 2px solid var(--ember);
+    border-left: 2px solid var(--ember);
+    pointer-events: none; z-index: 2;
+}
+.player-panel::after, .constellation-panel::after {
+    content: '';
+    position: absolute;
+    bottom: 0; right: 0;
+    width: 14px; height: 14px;
+    border-bottom: 2px solid var(--ember);
+    border-right: 2px solid var(--ember);
+    pointer-events: none; z-index: 2;
+}
+
+/* ── CENTER AREA — CRITICAL: flex column with overflow-y auto ── */
+.game-area {
+    display: flex !important;
+    flex-direction: column !important;
+    background: var(--bg-inset) !important;
+    border: 1px solid rgba(106,48,64,0.3) !important;
+    border-top: 1px solid var(--ember-mid) !important;
+    position: relative;
+    max-height: calc(100vh - 110px);
+    overflow-y: auto !important;  /* ← SCROLLABLE so suggestions are reachable */
+    overflow-x: hidden;
+}
+.game-area::before {
+    content: '';
+    position: absolute;
+    top: 0; left: 0;
+    width: 14px; height: 14px;
+    border-top: 2px solid var(--ember);
+    border-left: 2px solid var(--ember);
+    pointer-events: none; z-index: 2;
+}
+.game-area::after {
+    content: '';
+    position: absolute;
+    bottom: 0; right: 0;
+    width: 14px; height: 14px;
+    border-bottom: 2px solid var(--ember);
+    border-right: 2px solid var(--ember);
+    pointer-events: none; z-index: 2;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   SCENE IMAGE
+   ═══════════════════════════════════════════════════════════════════ */
+.scene-img-container {
+    width: 100%;
+    max-height: 180px;
+    overflow: hidden;
+    flex-shrink: 0;
+    position: relative;
+}
+.scene-img-container img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+    filter: brightness(0.5) contrast(1.1) saturate(0.65);
+}
+.scene-img-container::after {
+    content: '';
+    position: absolute;
+    bottom: 0; left: 0; right: 0;
+    height: 60px;
+    background: linear-gradient(to bottom, transparent, var(--bg-inset));
+    pointer-events: none;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   PORTRAIT
+   ═══════════════════════════════════════════════════════════════════ */
+.player-portrait {
+    width: 100%;
+    aspect-ratio: 3/4;
+    border: 1px solid rgba(106,48,64,0.45);
+    position: relative;
+    overflow: hidden;
+}
+.player-portrait::before {
+    content: '';
+    position: absolute; top: 0; left: 0;
+    width: 10px; height: 10px;
+    border-top: 2px solid var(--ember); border-left: 2px solid var(--ember);
+    z-index: 2;
+}
+.player-portrait::after {
+    content: '';
+    position: absolute; bottom: 0; right: 0;
+    width: 10px; height: 10px;
+    border-bottom: 2px solid var(--ember); border-right: 2px solid var(--ember);
+    z-index: 2;
+}
+.player-portrait img {
+    width: 100%; height: 100%;
+    object-fit: cover;
+    display: block;
+    filter: sepia(0.12) contrast(1.15) brightness(0.8) saturate(0.85);
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   STAT BARS
+   ═══════════════════════════════════════════════════════════════════ */
+.stat-bar { margin-bottom: 7px; }
+.stat-bar-label {
+    display: flex; justify-content: space-between;
+    font-family: var(--font-heading); font-size: 8px;
+    color: var(--text-worn); text-transform: uppercase;
+    margin-bottom: 3px; letter-spacing: 2px;
+}
+.stat-bar-label span:last-child { color: var(--text-aged); }
+.stat-bar-track {
+    width: 100%; height: 5px;
+    background: rgba(8,6,12,0.9);
+    border: 1px solid rgba(50,40,50,0.4);
+    overflow: hidden;
+}
+.stat-bar-fill {
+    height: 100%;
+    transition: width 0.7s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* HP — sage green */
+.stat-bar-hp .stat-bar-fill {
+    background: linear-gradient(90deg, var(--sage-dark), var(--sage-bright));
+}
+/* Meta Exposure — blood crimson */
+.stat-bar-meta .stat-bar-fill {
+    background: linear-gradient(90deg, var(--crimson-dark), var(--crimson-bright));
+}
+/* Probability Stability — deep indigo */
+.stat-bar-stability .stat-bar-fill {
+    background: linear-gradient(90deg, var(--indigo-dark), var(--indigo-bright));
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   NARRATIVE
+   ═══════════════════════════════════════════════════════════════════ */
+.narrative-container {
+    flex: 1 1 auto;
+    overflow-y: auto;
+    min-height: 80px;
+}
+.narrative-text {
+    font-family: var(--font-body) !important;
+    font-size: 14px !important;
+    line-height: 1.95 !important;
+    color: var(--text-narrative) !important;
+    padding: 16px 20px !important;
+    font-style: italic;
+}
+
+/* Dokkaebi — crimson */
+.dokkaebi-text {
+    font-family: var(--font-heading) !important;
+    color: var(--crimson) !important;
+    font-size: 11px !important;
+    letter-spacing: 0.5px;
+    border-left: 2px solid var(--crimson-mid) !important;
+    padding: 8px 14px !important;
+    margin: 6px 16px !important;
+    background: rgba(58,8,16,0.25) !important;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   SYSTEM WINDOW
+   ═══════════════════════════════════════════════════════════════════ */
+.system-window {
+    background: var(--bg-panel);
+    border: 1px solid rgba(106,48,64,0.3);
+    padding: 14px;
+    position: relative;
+}
+.system-window::before {
+    content: '';
+    position: absolute; top: 0; left: 0;
+    width: 10px; height: 10px;
+    border-top: 2px solid var(--ember); border-left: 2px solid var(--ember);
+    pointer-events: none;
+}
+.system-window::after {
+    content: '';
+    position: absolute; bottom: 0; right: 0;
+    width: 10px; height: 10px;
+    border-bottom: 2px solid var(--ember); border-right: 2px solid var(--ember);
+    pointer-events: none;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   SUGGESTION BUTTONS — ember/rose accent, clearly visible
+   ═══════════════════════════════════════════════════════════════════ */
+.suggestion-btn {
+    display: flex !important;
+    align-items: flex-start !important;
+    gap: 10px !important;
+    width: 100% !important;
+    text-align: left !important;
+    margin: 0 0 5px 0 !important;
+    padding: 10px 14px !important;
+    background: rgba(18,12,20,0.7) !important;
+    border: 1px solid var(--ember-mid) !important;
+    border-left: 2px solid var(--ember) !important;
+    color: #d0b0a0 !important;
+    font-family: var(--font-body) !important;
+    font-size: 13px !important;
+    font-style: italic !important;
+    cursor: pointer !important;
+    transition: all 0.18s ease !important;
+    line-height: 1.5 !important;
+    flex-shrink: 0;  /* never collapse */
+}
+.suggestion-btn:hover {
+    border-color: var(--ember-bright) !important;
+    border-left-color: var(--ember-bright) !important;
+    color: #e0c8b8 !important;
+    background: rgba(40,18,28,0.8) !important;
+    box-shadow: 0 0 12px rgba(192,104,120,0.15) !important;
+}
+.suggestion-btn:active {
+    transform: scale(0.995) !important;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   STAR STREAM / CONSTELLATION PANEL
+   ═══════════════════════════════════════════════════════════════════ */
+.constellation-chat {
+    display: flex; flex-direction: column; gap: 6px;
+}
+.chat-message {
+    background: rgba(5,4,8,0.5);
+    border: 1px solid rgba(50,40,50,0.3);
+    border-left: 2px solid var(--ember-mid);
+    padding: 6px 10px;
+    font-family: var(--font-heading);
+    font-size: 10px;
+    letter-spacing: 0.3px;
+    transition: border-left-color 0.3s;
+}
+.chat-message[data-mood="positive"] { border-left-color: var(--sage); }
+.chat-message[data-mood="negative"] { border-left-color: var(--crimson-mid); }
+.chat-message .constellation-name {
+    color: var(--ember); font-weight: 700; display: block;
+    margin-bottom: 2px; font-size: 8px; letter-spacing: 2px; text-transform: uppercase;
+}
+.chat-message .constellation-reaction {
+    color: var(--text-aged); font-size: 10px; line-height: 1.4;
+}
+.chat-donation {
+    color: var(--copper-bright); font-weight: 700; margin-top: 2px;
+    font-size: 10px;
+    text-shadow: 0 0 5px rgba(216,160,72,0.3);
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   INPUT BAR
+   ═══════════════════════════════════════════════════════════════════ */
+.input-bar {
+    padding: 8px 12px !important;
+    background: #09080e !important;
+    border-top: 1px solid var(--ember-mid) !important;
+    margin: 0 !important;
+    position: relative;
+    z-index: 5;
+    flex-shrink: 0;
+}
+.game-input { flex: 1 !important; }
+.game-input textarea,
+.game-input input[type="text"] {
+    background: rgba(5,4,8,0.9) !important;
+    border: 1px solid rgba(106,48,64,0.4) !important;
+    color: var(--text-parch) !important;
+    font-family: var(--font-body) !important;
+    font-size: 13px !important;
+    font-style: italic !important;
+    padding: 10px 14px !important;
+    height: 42px !important;
+    min-height: 42px !important;
+    transition: border-color 0.2s;
+    caret-color: var(--ember-bright);
+    resize: none !important;
+}
+.game-input textarea:focus,
+.game-input input[type="text"]:focus {
+    border-color: var(--ember) !important;
+    outline: none !important;
+    box-shadow: 0 0 8px rgba(144,72,88,0.2) !important;
+}
+.game-input textarea::placeholder { color: var(--text-worn) !important; font-style: italic; }
+
+/* ACT button — ember accent */
+.act-button {
+    background: rgba(42,16,24,0.7) !important;
+    border: 1px solid var(--ember) !important;
+    color: var(--ember-bright) !important;
+    font-family: var(--font-heading) !important;
+    font-size: 10px !important;
+    font-weight: 700 !important;
+    text-transform: uppercase !important;
+    letter-spacing: 3px !important;
+    height: 42px !important;
+    padding: 0 20px !important;
+    cursor: pointer !important;
+    transition: all 0.2s ease !important;
+    white-space: nowrap !important;
+}
+.act-button:hover {
+    background: rgba(60,24,35,0.9) !important;
+    box-shadow: 0 0 18px rgba(192,104,120,0.25) !important;
+    letter-spacing: 4px !important;
+    color: #e0a0b0 !important;
+}
+
+/* Stance radio */
+.input-bar label,
+.input-bar .gr-radio-group label {
+    font-family: var(--font-heading) !important;
+    color: var(--text-worn) !important;
+    border: 1px solid rgba(60,40,50,0.5) !important;
+    padding: 3px 8px !important;
+    cursor: pointer !important;
+    font-size: 8px !important;
+    text-transform: uppercase;
+    letter-spacing: 1.5px;
+    background: transparent !important;
+    transition: all 0.15s;
+}
+.input-bar .gr-radio-group input:checked + label,
+.input-bar .gr-radio-group label:hover {
+    border-color: var(--ember) !important;
+    color: var(--ember-bright) !important;
+    background: rgba(42,16,24,0.35) !important;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   BADGES / TITLES / MISC
+   ═══════════════════════════════════════════════════════════════════ */
+.title-badge {
+    display: inline-block;
+    background: rgba(144,72,88,0.08);
+    border: 1px solid rgba(106,48,64,0.5);
+    color: var(--ember);
+    font-family: var(--font-heading);
+    font-size: 8px; padding: 2px 6px; margin: 2px;
+    letter-spacing: 1px; text-transform: uppercase;
+}
+.skill-name {
+    font-family: var(--font-heading);
+    font-size: 10px; color: var(--text-aged); letter-spacing: 0.5px;
+    margin-bottom: 3px;
+}
+.bracket-text { font-family: var(--font-heading); color: var(--ember); opacity: 0.8; font-size: 11px; letter-spacing: 1px; }
+.gold-divider { width: 100%; height: 1px; background: linear-gradient(90deg, transparent, var(--ember-mid), transparent); margin: 5px 0; }
+.text-secondary { color: var(--text-aged) !important; }
+.text-primary   { color: var(--text-parch) !important; }
+.text-muted     { color: var(--text-worn) !important; }
+
+/* ══════════════════════════════════════════════════════════════��════
+   PHASE EFFECTS
+   ═══════════════════════════════════════════════════════════════════ */
+body.phase-combat .game-area { box-shadow: 0 0 28px rgba(122,26,34,0.12) inset; }
+body.phase-combat .scenario-header-text { color: var(--crimson) !important; text-shadow: 0 0 12px rgba(168,32,48,0.5) !important; }
+body.phase-combat .player-panel,
+body.phase-combat .constellation-panel,
+body.phase-combat .game-area { border-top-color: var(--crimson-mid) !important; }
+body.phase-combat .shop-accordion { pointer-events: none; opacity: 0.3; filter: grayscale(80%); }
+
+/* ═══════════════════════════════════════════════════════════════════
+   META DANGER
+   ═══════════════════════════════════════════════════════════════════ */
+@keyframes pulseBlood {
+    0%,100% { box-shadow: none; }
+    50%      { box-shadow: 0 0 18px rgba(168,32,48,0.18) inset; }
+}
+body.meta-warning .game-area { animation: pulseBlood 3s infinite; }
+body.meta-critical .game-area { animation: pulseBlood 1.5s infinite; }
+.meter-danger { animation: pulseBlood 1s infinite !important; }
+
+/* ═══════════════════════════════════════════════════════════════════
+   OVERLAYS
+   ═══════════════════════════════════════════════════════════════════ */
+.fullscreen-overlay {
+    position: fixed; inset: 0; z-index: 9999;
+    display: flex; flex-direction: column;
+    align-items: center; justify-content: center;
+    background: rgba(5,4,8,0.94);
+}
+.scenario-announcement {
+    text-align: center;
+    max-width: 600px; padding: 36px;
+    background: var(--bg-panel);
+    border: 1px solid var(--ember-mid);
+    position: relative;
+}
+.scenario-announcement::before {
+    content: ''; position: absolute; top: 0; left: 0;
+    width: 18px; height: 18px;
+    border-top: 2px solid var(--ember); border-left: 2px solid var(--ember);
+}
+.scenario-announcement::after {
+    content: ''; position: absolute; bottom: 0; right: 0;
+    width: 18px; height: 18px;
+    border-bottom: 2px solid var(--ember); border-right: 2px solid var(--ember);
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   JS EFFECT ELEMENTS
+   ═══════════════════════════════════════════════════════════════════ */
+.coin-particle {
+    position: fixed; width: 5px; height: 5px;
+    background: var(--copper-bright); border-radius: 50%;
+    pointer-events: none; z-index: 10000;
+    box-shadow: 0 0 4px var(--copper);
+    animation: coinFall 1.5s ease-in forwards;
+}
+.damage-flash-overlay {
+    position: fixed; inset: 0;
+    background: rgba(122,26,34,0.25);
+    pointer-events: none; z-index: 9998;
+    animation: damageFlash 0.5s ease-out forwards;
+}
+@keyframes damageFlash { 0% { opacity: 1; } 100% { opacity: 0; } }
+
+/* ═══════════════════════════════════════════════════════════════════
+   SHOP ACCORDION
+   ═══════════════════════════════════════════════════════════════════ */
+.shop-accordion {
+    background: transparent !important;
+    border: 1px solid rgba(106,48,64,0.3) !important;
+    border-radius: 0 !important;
+}
+.shop-accordion > .label-wrap,
+.shop-accordion summary {
+    font-family: var(--font-heading) !important;
+    color: var(--ember) !important; font-size: 9px !important;
+    letter-spacing: 2px !important; text-transform: uppercase;
+    background: transparent !important;
+    border-color: rgba(106,48,64,0.3) !important; padding: 6px 10px !important;
+}
+
+/* GRADIO DROPDOWN */
+.gradio-container select,
+.gradio-container .dropdown {
+    background: rgba(5,4,8,0.9) !important;
+    border: 1px solid rgba(106,48,64,0.35) !important;
+    color: var(--text-parch) !important;
+    font-family: var(--font-heading) !important;
+    font-size: 11px !important;
+}
+
+/* Typewriter cursor */
+.typewriter-cursor {
+    display: inline-block;
+    color: var(--ember);
+    animation: blink 0.8s step-end infinite;
+}
+@keyframes blink { 0%,100% { opacity: 1; } 50% { opacity: 0; } }
+
+/* ═══════════════════════════════════════════════════════════════════
+   RESPONSIVE BREAKPOINTS
+   ═══════════════════════════════════════════════════════════════════ */
+
+@media (max-width: 1100px) {
+    .game-main { flex-wrap: wrap !important; }
+    .constellation-panel {
+        max-height: 200px !important;
+        min-width: unset !important;
+        width: 100% !important;
+        flex: 1 1 100% !important;
+        order: 3;
+    }
+    .player-panel { flex: 0 0 180px !important; }
+    .game-area { flex: 1 1 260px !important; }
+}
+
+@media (max-width: 700px) {
+    .game-main {
+        flex-direction: column !important;
+        padding: 4px !important;
+        gap: 4px !important;
+    }
+    .player-panel {
+        flex: none !important;
+        max-height: none !important;
+        width: 100% !important;
+        flex-direction: row !important;
+        flex-wrap: wrap !important;
+    }
+    .player-portrait {
+        width: 90px !important;
+        aspect-ratio: 3/4 !important;
+        flex-shrink: 0;
+    }
+    .game-area {
+        max-height: none !important;
+        width: 100% !important;
+    }
+    .scene-img-container { max-height: 130px !important; }
+    .constellation-panel {
+        max-height: 160px !important;
+        width: 100% !important;
+    }
+    .scenario-header-left,
+    .scenario-header-right { display: none !important; }
+    .scenario-header-text { font-size: 10px !important; letter-spacing: 1.5px !important; }
+    .input-bar { flex-wrap: wrap !important; padding: 6px !important; }
+    .act-button { width: 100% !important; }
+    .narrative-text { font-size: 13px !important; padding: 12px 14px !important; }
+}
+
+@media (max-width: 420px) {
+    .scenario-header-text { font-size: 9px !important; letter-spacing: 1px !important; }
+    .game-header { height: 36px !important; }
+    .narrative-text { font-size: 12px !important; }
+    .suggestion-btn { font-size: 11px !important; padding: 8px 10px !important; }
+}